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Editor’s  Preface 


If  there's  any  lingering  impression  of  the  past  year  —  and  that  is  reflected  in  this 
collection  of  DDJ  articles  —  it  is  that  in  1989  object-oriented  programming  stormed 
to  the  forefront  in  the  world  of  programming.  This  isn't  to  say  that  1989  ended  with 
hundreds,  or  even  dozens  for  that  matter,  of  new  applications  built  around  and  upon 
the  object-oriented  paradigm.  Instead,  this  year  saw  the  emergence  of  object-oriented 
development  tools  that  will  lay  the  foundation  of  software  for  years  to  come.  And 
as  you  turn  the  pages  of  this  volume,  you'll  see  that  DDJ  established  itself  as  the 
leader  in  providing  information  about  this  emerging  technology  with  in-depth  arti¬ 
cles  on  every  major  object-oriented  environment  —  from  C++  and  Object  Pascal,  to 
Smalltalk  and  Eiffel. 

This  isn't  to  say  that  the  object-oriented  approach  is  the  be-all  and  end-all  of  pro¬ 
gramming  in  the  future.  Scott  Guthery  doesn't  think  so  as  you’ll  see  in  his  highly 
controversial  December  article  entitled  "Are  the  Emperor's  New  Clothes  Object 
Oriented?"  Nor  were  object-oriented  systems  the  only  approaches  gaining  momentum 
this  year,  as  Ronald  Fischer's  article  on  functional  programming  (also  in  December) 
makes  evident.  Programming  is  an  evolutionary  process  and  approaches  to  it  come 
and  go  as  new  tools  and  new  algorithms  find  their  way  into  the  hands  of  software 
developers. 

But  no  matter  how  much  we  speculate  on  what  the  future  of  programming  will  look 
like,  programmers  still  have  to  be  concerned  with  the  here-and-now  and  that  most 
often  involves  producing  the  tightest,  fastest  code  possible.  Practical  programming 
techniques  to  achieve  this  for  the  now-familiar  procedural  and  structured  languages 
remains  the  bread-and-butter  of  the  DDJ  articles  in  this  volume  and  the  reason  pro¬ 
grammers  worldwide  have  been  turning  to  DDJ  for  years. 

Among  this  year's  highlights.  I'd  like  to  direct  you  to  the  Rhealstone  real-time 
benchmarking  proposal  in  February,  the  techniques  for  memory  swapping  in  the 
March  issue,  and  image  mathematics  in  July.  I'd  also  encourage  you  to  examine  the 
C  mixed-language  programming  articles  in  August,  our  simulated  annealing  in 
September,  November's  parallel  optimization  article,  and  the  entire  contents  of  our 
two  special  issues.  Dr.  Dobb's  Macintosh  Journal  and  Dr.  Dobb's  C  Sourcebook  for  the 
1990s.  A1  Stevens'  interviews  with  Dennis  Ritchie  and  Bjarne  Stroustrup  provides  a 
fascinating  perspective  of  C  and  C++  during  a  period  of  transition,  and  we've  dis- 
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covered  that  Al's  article  entitled  a  "C  Programmer's  Guide  to  C++'"  is  being  used  in 
college-level  C  programming  courses. 

The  past  year  hasn't  been  without  its  ups  and  downs,  however.  On  the  upside,  per¬ 
sonnel-wise  anyway,  it  was  the  year  that  Jeff  Duntemann  joined  us  as  a  regular 
columnist,  Ray  Valdes  as  a  staff  technical  editor,  and  Andrew  Schulman  as  a  con¬ 
tributing  editor.  On  the  downside,  1989  was  the  year  that  Kent  Porter  passed  away, 
leaving  a  very  big  void  in  the  lives  of  those  who  read  his  columns  and  articles  and 
those  of  us  who  worked  with  him  daily. 

Overall,  I  think  you'll  agree  that  this  year  was  very  good  for  the  Doctor  and  that 
this  volume  will  be  a  programmer's  tool  for  years  to  come. 

Jonathan  Erickson 
Editor-in-Chief 
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Depending  on  who  you  talk  to,  the 
first  IEEE  international  neural  net¬ 
work  conference  (which  took  place 
nearly  two  years  ago)  was  either  a  sur¬ 
prising  success  or  a  woeful  failure.  The 
naysayers  point  to  a  relatively  small 
number  of  people  who  showed  up  to 
hear  a  smattering  of  papers,  share  some 
theories,  and  see  a  dozen  or  so  exhib¬ 
its.  The  yeasayers,  however,  insist  that 
the  conference  was  successful  simply 
because  people  showed  up  at  all,  es¬ 
pecially  considering  that  as  recently  as 
a  couple  of  years  ago  few  people  knew 
what  neural  nets  were,  let  alone  how 
they  could  be  used. 

(As  an  aside,  neural  nets,  as  defined 
by  Doug  Palmer  of  Hecht-Nielsen  Neu¬ 
rocomputers,  are  highly  parallel  dynami¬ 
cal  systems  that  process  information 
by  means  of  response  to  continuous 
input.  The  structure  of  a  neural  net 
consists  of  a  large  number  of  process¬ 
ing  elements,  each  with  multiple  in¬ 
puts,  but  with  a  single  output.  In  addi¬ 
tion  to  the  processing  element,  a  neu¬ 
ral  net  is  made  up  of  an  interconnec¬ 
tion  scheme  [topology],  a  learning 
model,  and  knowledge  of  the  state  of 
the  system.  Together,  these  elements 
are  called  the  network  paradigm;  cur¬ 
rently,  about  20  distinct  paradigms  have 
been  identified.) 

There’s  little  question,  however,  that 
the  second  international  neural  network 
conference,  which  took  place  in  July 
of  1988,  was  a  success.  Nearly  two 
thousand  attendees  — including  mem¬ 
bers  of  the  DDJ  staff  (see  Michael 
Swaine’s  “Programming  Paradigms”  col¬ 
umn  of  October,  1988)  — converged  on 
San  Diego  to  find  out  what  had  hap¬ 
pened  in  the  world  of  neural  nets  over 
the  space  of  a  year.  What  did  they  talk 
about?  Among  the  dozens  of  papers 
presented  were  those  on  topics  such 
as  “Neural  Computation  for  Control¬ 
ling  the  Configuration  of  2-Dimensional 
Truss  Structure,”  “Neural  Network  Simu¬ 
lation  at  Warp  Speed:  How  We  Got  17 
Million  Connections  per  Second,”  “Abili¬ 
ties  and  Limitations  of  a  Neural  Net¬ 
work  Model  for  Spoken  Word  Recog¬ 
nition,”  “Neural  Network  Models  and 
Their  Application  to  Handwritten  Digit 
Recognition,”  and  “A  Multilayer  Per¬ 
ception  Network  for  the  Diagnosis  of 
Low  Back  Pain.” 

More  significantly,  the  emphasis  at 
the  second  conference,  as  well  as  more 
recent  technical  conferences  like  the 


Fall  ACM  or  the  Pattern  Recognition 
and  Advanced  Missile  System  confer¬ 
ences,  was  on  the  practical,  rather  than 
theoretical,  side  of  neural  networking. 
It’s  becoming  apparent  that  neural  nets 
are  rapidly  moving  out  of  research  labs 
and  into  commercial  development  en¬ 
vironments  because  neural  technology 
has  the  capability  of  providing  effec¬ 
tive  solutions  to  many  kinds  of  com¬ 
plex  computing  tasks.  A  good  example 
of  this  is  the  kind  of  applications  under 
development  at  companies  like  Accu¬ 
rate  Automation  (a  company  located 
in  Tennessee,  a  state  that  surprisingly 
has  become  a  hotbed  of  neural  net 
development).  AA  is  building  commer¬ 
cial  neural  net  systems  for  tasks  like 
monitoring  the  behavior  of  aircraft  en¬ 
gines,  for  real-time  and  process  con¬ 
trol,  and  even  for  monitoring  of  local 
area  networks  and  database  activities 
using  a  form  of  neural  nets  called  the 
“nearest  neighbor  classifier”  that  looks 
for  emergency  patterns  and  reacts  ac¬ 
cordingly.  The  basic  questions  being 
asked  by  programmers  who  are  be¬ 
coming  neural  net  aware  concern  which 
neural  net  paradigms  should  be  ap¬ 
plied  in  specific  situations,  not  whether 
or  not  neural  nets  are  right  at  all. 

With  this  backdrop,  this  month’s  ex¬ 
amination  of  neural  networks  looks  at 
the  technology  from  the  practical  side. 
Todd  King’s  lead  article  will  give  you 
a  feel  for  what  nets  are  about,  and 
provide  you  with  a  new  tool  for  solv¬ 
ing  old  programming  problems.  Casey 
Klimasauskas’  article,  and  Steven  Me- 
linkoffs  sidebar,  give  you  a  chance  to 
see  how  commercial  neural  net  pack¬ 
ages  differ  from  the  roll-your-own  ap¬ 
proach  taken  by  Todd.  Together,  our 
pair  of  neural  net  articles  also  lets  you 
examine  the  main  types  of  problems  — 
primarily  pattern  recognition  and  noise 
filtering  — neural  networks  are  currently 
being  used  to  solve. 

In  short,  neural  nets  have  come  a 
long  way  since  DDJ  last  looked  at  them 
over  a  year-and-a-half  ago,  and  you 
can  be  assured  that,  over  the  next  18 
months,  you’ll  see  new  uses  and  even 
more  startling  developments  in  this 
emerging  technology. 


Jonathan  Erickson 
editor-in-chief 
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Find  that  Function  (Again ) 

Dear  DDJ, 

The  article  “Find  that  Function”  caught 
my  attention.  I  imagine  every  program¬ 
mer,  at  some  time,  wants  a  list  of  func¬ 
tions  or  other  declarations,  particularly 
for  a  sizable  program  distributed  over 
many  source  files. 

I  was  surprised  by  the  complexity 
of  the  code  used  to  build  the  function 
list  in  Hymowech  s  Listing  One  (pages 
70  -  74),  perhaps  400  lines  of  code  and 
comments.  Surely  there  should  a  sim¬ 
pler  way  of  doing  this.  The  problem  is 
how  to  extract  all  instances  of  a  par¬ 
ticular  grammar  element,  the  identifier 
of  a  function  definition,  from  a  source 
file  presented  as  a  character  stream. 
This  is  made  difficult  by  the  start  of  the 
definition  (function  type,  name,  parame¬ 
ter  declarations,  and  beginning  of  the 
function  body)  being  commonly  on 
more  than  one  line,  having  a  varied 
arrangement  of  white  space  and  punc¬ 
tuation,  comprising  many  different  to¬ 
kens,  and  possibly  including  comment 
lines. 

Lex,  a  generator  of  automatons  for 
lexical  analysis,  is  admirably  suited  for 
this  particular  kind  of  pattern-matching 
problem.  My  example  code  gives  Lex 
sources  for  two  filters  and  a  wrapping 
shell  script.  The  definitions  (FUNCSTRT, 
etc.)  were  written  in  the  hope  that  they 
make  self-explanatory  the  few  pattern- 
action  rules  given  at  the  end  of  each 
source,  following  the  %%  symbol. 
Mk_funclist.one  and  its  dependents 
serve  to  build  a  table  of  functions  from 
a  list  of  C  source  files. 

The  seven  rules  in  the  two  Lex 
sources  duplicate,  I  believe,  the  essen¬ 
tial  actions  of  Listing  One  of  “Find  that 
Function.”  The  design  of  Listing  One 
assumes  that  preprocessor  directives 
within  the  function  body  do  not  alter 
the  curly  brace  balance.  If  this  is  not 
true,  my  second  example  shows  that 
the  preprocessor  itself  can  be  used  to 
sort  things  out.  A  few  changes  in  List¬ 
ing  One  serve  to  change  it  into  a  gen¬ 
erator  of  a  list  of  all  declarations,  each 


on  one  line,  with  parameter  declara¬ 
tions  and  return  value  given  on  the  line 
for  each  function  (a  lint  library). 

There  are  tremendously  powerful 
tools  for  pattern  matching  and  extrac¬ 
tion  of  elements  from  text  files.  Public 
domain  versions  of  Lex  that  run  on 
non-Unix  systems  have  been  available 
for  some  time,  awk  is  sold  for  non- 
Unix  systems  (should  I  say  MS-DOS?). 


They  ran  on  simple  hardware;  the  Lex 
sources  of  Examples  1  and  2  were 
worked  out  on  a  PC  AT.  The  problem 
is  choosing  the  best  tool.  For  problems 
like  the  one  addressed  here,  Lex  is 
arguably  the  most  appropriate.  Lex  proc¬ 
esses  character  streams  simply,  with 
new  lines  having  no  special  meaning, 
and  so  it  differs  from  line-oriented  tools, 
like  sed  and  awk.  Lex  also  tests  left  and 


Example  1 


#  MK_FUNCLI ST . ONE 
echo  " 
for  i;  do 

echo  "\n/* 'basename  S { i >  '*/" 
cat  ${i) I  uncomment | funcfilt3 

done 


FUNCTION  LIST*’ 


%f 

/‘UNCOMMENT-  based  on  Usenet  posting  by:  */ 

/*  Chris  Thewait;  thewalt@ritz.cive.cmu.edu  */ 

%l 

\" { [A"\n] | \\\") *\" 

"/*" ( [ A*\n] | "*"+ [A*/\n] )*"*"*"*/" 


STRING 

COMMENT 

*% 

{COMMENT) 

(STRING) 

- 1  \n 


ECHO; 

ECHO; 


%{ 

/‘-FUNCFILT3:  print  function  names,  indented  1  tab;  */ 

/*DECL  &  FUNCPTR  may  require  change  for  ANSI  compatibility  */ 
%} 

int  curly; 

WLF 
NAME 
ARRAY 
DECL 
FUNCPTR 
DECLST 
FUNCSTRT 
STRING 

SKIPALLQUOTED 
%START  CURLY  NORM 
%< 

main()  { 

/*  if  no  shell  wrapper,  loop  over  files  here  */ 

/*  and  run  other  filters  using  tmp  files  */ 

BEGIN  NORM; 


([  \t\n\f\r) *) 

( [*)*[_a-zA-Z] (_a-zA-Z0-9] *) 

(\ [ (0-9+-/*) *\] ) 

([;,)  I {WLF) | {NAME) | (ARRAY)) 

( \ ( { DECL } * \ ) \ ( { DECL }  *\ ) ) 
({DECL) I (FUNCPTR))* 

([  \t] *\ ( (DECLST )\) (DECLST) \ { ) 
\"<[A"\n] |\\\")*\" 

((STRING)  IV  .V  |\\.) 


yylexO  ; 

) 

%) 

%% 

<CURLY>\ {  curly++; 

<CURLY>\ )  (if  (—curly  ■ 

(SKIPALLQUOTED) | . |\n 
<N0RM> ( NAME ) / { FUNCSTRT  >  {printf("\t%s\n' 

curly»0;BEGIN  0; BEGIN  CURLY;) 


0)  (BEGIN  0; BEGIN  NORM;)) 


Example  2 


‘FUNCTION  LIST* 


#  MK_FUNC  L I S  T . T WO 
echo  " 
for  i;  do 

echo  "\n/» 'basename  ${i}’*/" 
cat  ${i) | funcfiltl | /lib/cpp  -P  -Cl 

funcf ilt2 | uncomment | funcf ilt3 

done 

%( 

/‘-FUNCFILT1 :  prepare  for  cpp  execution  of  fifdefs,  etc.;  */ 
/*i.e.,  setup  to  restore  lincludes  &  remove  code  added  by  cpp  */ 
%} 

%% 

,'\#[  \tj ‘include .  *$  (prir.tf  ("/*%s*/\n",  yytext); 

printf ( "/‘DINGDONGDELL*/^") ; 
printf ("%s\n",  yytext); 
printf (n/*DELLDONGDING*/\n: ) ; ) 

.  |  \n  ECHO; 


%( 

/‘-FUNCFILT2 :  remove  cpp-included  code,  restore  #include's  */ 
%) 

%START  DING 
%% 

A " / * D INGDONGDELL * / " $  BEGIN  DING; 

''"/*DELLDONGDING*/"$  BEGIN  0; 

<DING>,'n/*#"[A*]  *"*/"$ 

<DING>. I \n 

,A"/*#" (A‘] *"*/"$  (yytext (yyleng-2]  =  0; 

printf ("%s",  syytext [2] ) ; } 

A[  \t]*\n 

. | \n  ECHO; 
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(continued  from  page  8) 


Ten  Years  Ago  in  DDJ 

“I  have  always  enjoyed  reading  New  Year 
predictions;  this  year  I  decided  to  make  a 
few  myself.  Over  the  next  two  years:  the 
Intel  8086  and  its  support  chips  will  be  the 
most  prevalent  16-bit  micro  system.  .  .  .  only 
applications  requiring  large  amounts  of 
memory  will  decide  against  the  8086.  Over 
the  next  five  to  seven  years:  C  and  similarly 
designed  translators  will  be  the  prevalent 
systems  languages.  Physical  micro/mini/maxi 
distinctions  will  become  more  vague  until 
completely  lost;  processors  will  only  be 
differentiated  by  their  architectures,  speed, 
and  addressing  ranges.  Over  the  next  fifteen 
to  twenty  years:  Paper  mail  and  newspapers 
will  be  obsolete  as  a  result  of  improvements 
in  electronic  media,  particularly  graphics.”  — 
Mike  Gabrielson,  “Letters,  "  DDJ,  January, 
1979. 


You  Could  Say  that  You  Can’t  See 
the  Forth  for  the  Trees  . . . 

“With  the  68000,  it  often  seems  as  if  one 
is  let  loose  upon  a  tropical  island,  full  of 
flowers  of  dazzling  beauty  but  so  much 
underbrush  that  it  seems  impossible  to  scale 
its  central  mountain  peak  and  survey  the 
totality  of  the  landscape.”  — W.  D.  Maurer, 
“Simplified  68000  Mnemonics, "  DDJ, 
October,  1982. 


“In  the  long  run,  making  programs  free  is  a 
step  toward  the  post-scarcity  world,  where 
nobody  will  have  to  work  very  hard  just  to 
make  a  living.  People  will  be  free  to  devote 
themselves  to  activites  that  are  fun,  such  as 
programming,  after  spending  the  necessary 
ten  hours  a  week  on  required  tasks  such 
as  legislation,  family  counseling,  robot 
repair,  and  asteroid  prospecting.  " — Richard 
Stallman,  “The  GNU  Manifesto,  'DDJ,  March, 
1985. 
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right  context  simply.  Consider  the  last 
rule  of  Listing  One.  It  prints  the  NAME 
when  the  right  context  matches 
FUNCSTRT  and  when  the  left-context 
flag  NORM  ensures  that  NAME  is  not 
inside  a  function  body.  The  same  pars¬ 
ing  likely  could  be  accomplished  also 
by  use  of  awk  or  sed,  but  the  code  for 
these  tools  would  be  more  complicated. 
My  intent  is  not  to  push  Lex  as  an 
all-purpose  solution  for  text  manipula¬ 
tion.  The  filters  of  Listing  Two,  unlike 
those  of  Listing  One,  could  just  as  eas¬ 
ily  have  been  written  for  awk  or  sed. 

With  Lex,  awk,  and  other  such  arma¬ 
ment  in  hand,  there  would  seem  to  be 
little  justification  for  coding  the  solu¬ 
tion  to  a  text  manipulation  problem 
from  scratch.  Programmers  should  be 
encouraged  to  use  the  excellent  tools 
available  and  should  have  the  knowl¬ 
edge  to  choose  the  one  right  for  the 
job.  I  hesitate  to  suggest  that  Dr.  Dobb’s 
should  take  its  readers  through  discus¬ 
sions  of  the  internals  or  give  tutorials 
on  the  use  of  “mature”  tools  like  Lex, 
yacc,  and  awk.  You  could,  however, 
take  care  to  give  readers  programming 
examples  that,  rather  than  showing  the 
long  and  wrong  way  to  solve  a  prob¬ 
lem,  show  them  the  appropriate  use 
of  tools. 

John  Rupley 

University  of  Arizona 

Tucson,  Arizona 


Ada  Aid 

Dear  DDJ, 

I’ve  read  with  interest  the  Ada  articles 
in  the  September  1988  issue  and  hope 
to  see  more  such  features  in  the  future. 

In  “Object-Oriented  Dimensional 
Units,”  John  Grosberg  presents  a  use¬ 
ful  example  of  how  a  dimensioned  unit 
with  a  float-type  value  might  be  imple¬ 
mented  as  a  reusable  component  in 
Ada.  However,  I  think  one  of  his  main 
points  is  misleading. 

In  discussing  the  operations  that  the 
dimensional  unit  type  Float_  Unit.  Class 
inherits  from  the  predefined  type  Float, 
Mr.  Grosberg  notes  that  some  opera¬ 
tions  are  invalid.  For  example,  5  feet  x 
4  feet  =  20  square  feet,  not  20  feet.  He 
then  states  the  "Ada  provides  no  way 
to  detect  it  (an  invalid  operation)  at 
compile  time”  and  presents  a  way  to 
detect  the  error  at  run  time. 

One  way  to  detect  such  an  invalid 
operation  at  compile  time  is  to  imple¬ 
ment  the  type  “Class”  as  a  private  type. 
Objects  of  a  private  type  may  be  ma¬ 
nipulated  only  by  the  operations  pro¬ 
vided  in  the  visible  part  of  the  spec.  If 


invalid  operations  are  not  explicitly  pro¬ 
vided,  then  they  are  not  available  to  a 
client.  The  integrity  of  the  abstraction 
is  thereby  preserved,  and  invalid  op¬ 
eration  attempts  are  discovered  at  com¬ 
pile  time. 

Use  of  private  (and  limited  private) 
types  is  even  more  important  when  a 
class  is  implemented  as  an  array  or 
record,  which  is  often  the  case.  Typi¬ 
cally,  individual  components  of  a  com¬ 
posite  type  need  to  be  protected  from 
manipulation  by  the  clients.  This  is  ac¬ 
complished  by  use  of  private  types 
which  provide  a  more  accurate  abstrac¬ 
tion,  a  cleaner  interface  for  the  client, 
more  precise  control  of  operations  on 
the  class,  and  minimization  of  side  ef¬ 
fects  of  any  changes  to  the  internal 
representation  of  the  type. 

The  code  on  page  12  shows  the  revi¬ 
sions  to  Mr.  Grosberg’s  Float_Unit spec 
required  to  make  type  “Class”  a  private 
type.  “Class”  is  declared  as  type  private 
instead  of  type  Float.  The  private  part 
is  inserted  at  the  end  of  the  spec,  and 
“Class”  declaration  is  completed  in  the 
private  part.  The  invalid  function  dec¬ 
larations  are  then  removed  from  the 
spec.  The  Units_Error  exception  decla¬ 
ration  is  also  removed. 

In  the  Float_Unit  body,  only  the  re¬ 
moval  of  the  invalid  function  bodies  is 
required.  Package  Float_Unit  is  shown 
in  Listing  One. 

Glenn  A.  Edwards 

St.  Petersburg,  Fla. 

John  responds:  My  statement  that  “Ada 
provides  no  way  .  .  .  "sounds  more  ab¬ 
solute  than  I  intended.  I  would  have 
been  more  correct  had  1  said  “having 
chosen  to  make  float_unit.class  public, 
Ada  provides  no  way  ....  "Any  method 
of  doing  something  has  advantages  and 
disadvantages  relative  to  the  applica¬ 
tion.  One  must  choose  the  method  that 
best  Jits  the  circumstances.  Mr.  Edwards’ 
method  for  making  float_unit.class  into 
a  private  type  is  the  way  I  started  the 
design  of  the  float_unit  package.  For 
my  application,  however,  I  eventually 
chose  to  make  the  type  public  for  two 
main  reasons:  First,  I  wanted  to  be  able 
to  use  floating  point  literals  with  vari¬ 
ables  of  the  various  units  types.  For 
example,  I  wanted  to  be  able  to  say: 

supply_voltage  :  volt.class  :=  5.2; 
or  supply_voltage  :=  10.0; 

Second,  I  wanted  to  be  able  to  use  the 
range  declaration  and  checking  fea¬ 
tures  that  are  available for floating  point 
types  in  Ada.  So,  for  example,  I  could 
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LETTERS 

(continued  from  page  10) 


do  something  like  this: 

supply_voltage  :  volt.class  range  0.0 

..  10.5; 

I  think  it  is  safe  to  say  neither  of  these 
capabilities  is  available  if  the  type  is 
private.  One  could  (if  the  type  were 


private)  obtain  the  effect  of  my  first 
example  by  adding  a  function  to  the 
package  to  convert  floating  point  to 
float_unit.class: 

function  to_class(  f :  float )  return 

class; 


and  use  it  as  an  inherited  function  like 
this: 

supply_voltage  :  volt.class  := 

volt.to_class(5.2); 

But  that  seems  less  natural,  and,  be¬ 
sides,  the  range  feature  that  I  wanted 
still  wouldn ’t  be  available.  In  addition, 
there  is  little  reason  to  hide  the  fact 
that  a  dimensional  unit  is  based  on 
float,  since  that  is  the  way  we  think 
about  them  anyway.  It  is  only  neces¬ 
sary  to  “hide"  or  restrict  the  ways  they 
can  be  combined  with  each  other.  What 
I  traded  for  the  features  I  wanted  was 
to  postpone  the  checking  of  some  inva¬ 
lid  operations  to  run-time.  By  the  way, 
if  Mr.  Edwards  or  any  other  readers 
are  interested  in  an  altogether  differ¬ 
ent  method  of  handling  units  in  Ada, 
I  recommend  they  check  out  the  article 
“Dimensional  Analysis  in  Ada"  by  Pat 
Rogers,  published  in  the  ACM  Ada  Let¬ 
ters,  vol.  8,  no.  5,  Sept/Oct.  1988. 


Leftie  Light  Bulbs 

Dear  DDJ 

I  enjoyed  reading  Steve  Upstill’s  article 
on  RenderMan  Shading  Language  (“Pho¬ 
torealism  in  Computer  Graphics,”  No¬ 
vember  1988,  but  Figures  1  and  3  pro¬ 
vided  compelling  examples  of  why  soft¬ 
ware  people  have  to  be  watched  so 
closely  out  in  the  real  world.  The  threads 
on  the  light  bulbs  are  left-handed.  And 
another  thing:  Threads  are  helixes,  not 
spirals. 

Fred  Klingener 
McLean,  Virginia 

Editor’s  note:  Unfortunately,  the  slide  was 
flopped  during  the  printing  process.  The 
error  was  not  the  programmer’s. 

Algorithmic  Answer for  Alan 

Dear  DDJ, 

Software  Manual for  Elementary  Func¬ 
tions  (by  William  J.  Cody  Jr.  and  Wil¬ 
liam  Waite,  Prentice-Flail)  should  help 
Alan  Clark,  who  needs  a  resource  that 
lists  fundamental  algorithms  for  high- 
level  functions  that  do  not  exist  in  ma¬ 
chine  code.  (See  “Letters,”  August  1988.) 
The  book  gives  detailed  implementa¬ 
tion  of  sqrt,  alog,  aloglO,  exp,  power, 
sin,  cos,  tan,  cot,  asin,  acos,  atan,  atan2, 
sinh,  cosh,  tanh,  and  provides  a  test 
suite  to  boot. 

Edmund  Ramm 
Kaltenkirchen,  W.  Germany 

DDJ 


Listing  One 

—  This  code  shows  changes  to  Float_Unit  spec 

—  (Listing  One,  page  94,  September  '88) 

—  which  will  allow  the  invalid  operations  to  be 

—  discovered  at  compile  time  instead  of  run  time. 

—  The  type  "Class"  is  simply  made  a  private  type. 

—  The  changes  in  the  Float_Unit  body  involve  removing  the 

—  bodies  of  the  unwanted  operations. 

type  Class  is  private  ; 

—  Type  "Class"  is  declared  to  be  a  private  type 

—  instead  of  a  Float  type. 

--  The  "Class"  type  objects  may  now  be  manipulated  only 

—  by  the  operations  defined  in  the  visible  part  of  this  spec. 

—  Float  operations  are  not  implicitly  inherited. 

—  The  =  and  /=  comparisons  as  well  as  the  :=  assignment 

—  are  still  available  for  type  "Class"  objects. 

— Units_Error  :  exception  ; 

—  This  exception  is  no  longer  needed. 

— Function  (  Left  :  Class  ; 

Right  :  Class  ) 
return  Class  ; 

—  This  unwanted  function  is  removed  from  the  spec. 

—  Any  call  to  this  function  will  now,  obviously, 

—  be  caught  at  compile  time  because  this  function 

—  does  not  exist  for  the  private  type  "Class." 

—  The  other  subprogram  declarations  remain  the  same 

—  after  removing  the  "**"  function  and  the 

—  "/"  function  that  returns  type  Class... 

Function  (  Left  :  Float  ; 

Right  :  Class  ) 

return  Class  ; 

Function  "*"  (  Left  :  Class  ; 

Right  :  Float  ) 

return  Class  ; 

Function  "*"  (  Left  :  Integer  ; 

Right  :  Class  ) 

return  Class  ; 

Function  "*"  (  Left  :  Class  ; 

Right  :  Integer  ) 

return  Class  ; 

— Function  "/"  (  Left  :  Class  ; 

Right  :  Class  ) 
return  Class  ; 

—  This  unwanted  function  is  removed  from  the  spec. 

—  Same  rationale  as  the  function  above. 

Function  "/"  (  Left  :  Class  ; 

Right  :  Class  ) 

return  Float  ; 

Function  "/"  (  Left  :  Class  ; 

Right  :  Float  ) 

return  Class  ; 

Function  "/"  (  Left  :  Class  ; 

Right  :  Integer  ) 

return  Class  ; 

—  Function  "**"  (  Left  :  Class  ; 

Right  :  Integer  ) 
return  Class  ; 

—  This  unwanted  function  is  removed  from  the  spec. 

—  Same  rationale  as  the  "*"  function  above. 

Function  Image  (  The_Object  :  Class  ) 
return  String  ; 

—  A  side  note: 

—  The  "in"  mode  indicator  was  not  needed,  therefore  removed,  because 

—  parameters  of  Ada  functions  are  exclusively  of  mode  "in." 

(Parameters  in  Ada  procedures  may  be  of  mode  "in,"  "in  out,"  or 
"out . ") 

Function  Value  (  The_String  :  String  ) 
return  Class  ? 

private 

—  A  private  part  is  added  to  the  specification. 

type  Class  is  new  Float  ; 

—  Complete  the  declaration  for  type  "Class." 

end  Float_Unit  ;  End  Listing 
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_ Using _ 

Neural  Networks 

for  Pattern  Recognition 

Recognizing  and  learning  patterns  is  one  thing 
neural  nets  do  best 


by  Todd  King 


By  their  very  definition,  neural  networks  are  able  to 
tolerate  ambiguities  in  much  the  same  way  as  the 
human  brain  can.  Consequently,  the  types  of  prob¬ 
lems  that  neural  networks  are  best  suited  for  unraveling  are 
those  in  which  decisions  need  to  be  made  based  on  close 
approximations  to  — not  exact  correspondence  with  — the 
original  input.  One  such  class  of  problem  is  pattern  recogni¬ 
tion,  where  the  neural  network  can  memorize  a  pattern, 
then  recognize  it  with  100  percent  certainty  when  it  sees  the 
pattern  again.  And  when  an  entirely  new  pattern  is  pre¬ 
sented  to  the  network,  the  network  can  determine  which 
of  the  previously  memorized  patterns  the  new  one  matches 
the  most  closely. 

One  issue  faced  by  programmers  who  are  interested  in 
using  neural  nets  to  solve  pattern  recognition  problems  is 
that  there  is  more  than  one  way  to  skin  a  pattern  recognition 
problem.  In  fact,  research  into  the  physiological  and  cog¬ 
nitive  processes  of  the  mind  has  shown  that  there  are  several 
paradigms  of  pattern  recognition,  each  with  its  own  use¬ 
fulness,  purpose,  and  inherent  goal.  In  this  article  I’ll  con¬ 
centrate  on  the  pattern  associator  and  a  called  variation  of 
the  classification  paradigm. 

Broadly  speaking,  the  goal  of  a  pattern  associator  is  to 
handle  pairs  of  patterns  — one  member  of  the  pair  being  the 
input  pattern  and  the  other  member  the  output  pattern.  The 
network  is  configured  (either  explicitly  or  by  teaching)  to 
associate  the  output  pattern  with  the  input  pattern.  Once 
this  has  been  done,  every  time  the  input  pattern  is  presented 
to  the  network  the  response  will  be  the  desired  output 
pattern. 


Todd  King  is  a  programmer/analyst  with  the  Institute  of 
Geophysics  and  Planetary  Physics  at  UCLA.  He  is  also  asso¬ 
ciated  with  the  NASA/JPL  Planetary  Data  Systems  project. 
Todd  can  be  reached  at  1104  N.  Orchard,  Burbank,  CA 
91506. 


The  classification  paradigm  is  similar  to  the  pattern  asso¬ 
ciator  in  that  it,  too,  makes  associations  between  input 
patterns  and  output  patterns.  Where  it  differs  is  that  the 
input  patterns  are  placed  into  a  fixed  set  of  categories.  A 
benefit  of  this  categorizing  is  that  distorted  or  incomplete 
versions  of  the  input  pattern  can  be  presented  to  the  net¬ 
work  and  the  response  will  be  the  correct  output  pattern. 

Network  Topologies 

You  can  choose  from  a  wide  range  of  neural  network 
topologies  when  attempting  to  solve  a  particular  problem. 
Choosing  the  right  topology  can  mean  a  very  simple  solu¬ 
tion;  choosing  the  wrong  one  can  result  in  an  overly  com¬ 
plicated  solution  or  no  solution  at  all. 

After  studying  the  problems  that  I  discuss  in  this  article  - 
an  executive  board  simulator,  logic  gates,  and  an  optical 
character  recognition  (OCR)  system — I  decided  that  all 
these  examples  could  be  implemented  with  the  following 
attributes:  a  three-layer  network  consisting  of  an  input  layer, 
a  hidden  layer  and  an  output  layer.  The  number  of  neurons 
within  each  layer  can  be  set  at  run  time.  All  neurons  within 
each  layer  are  fully  connected  with  all  neurons  in  the  next 
layer;  that  is,  each  neuron  in  one  layer  connects  to  every 
neuron  in  the  next  layer  (see  Figure  1,  page  16).  The 
activation  function  is  the  same  for  every  neuron  in  every 
layer  and  is  set  to  either  a  linear  or  linear-threshold  function. 
The  propagation  function  is  always  a  weighted  sum,  and  all 
connections  activate  in  the  direction  of  the  output  layer 
(feed-forward  network).  Starting  with  this  foundation,  you 
can  build  a  variety  of  useful  networks. 

The  Support  Code 

Let’s  first  look  at  the  support  code  that  allows  you  to  build 
neural  networks.  A  simple,  general-purpose  library,  it  con¬ 
sists  of  seven  functions  and  five  pseudofunctions  (defines) 
that  allow  you  to  build  three-layer  networks  with  any  num- 


14 


Dr.  Dobb’s  Journal,  January  1989 

21 


each  members  vote  and  prints  out  whether  the  vote  w,v 
for,  against,  or  a  tie.  The  number  of  stockholders  each 
member  votes  for  is  set  to  the  board  member's  number  (tot 

example,  three  for  board  member  3). 


ter  of  neurons  in  each  layer  (up  to  a  maximum).  It  also 
allows  you  to  set  the  activation,  user  input,  and  result  output 
functions  as  well  as  the  weights  between  connections.  List¬ 
ing  One,  page  90,  contains  the  source  for  the  support 
library.  The  pseudofunctions  are  in  the  include  file  in  Listing 
Two,  page  90.  The  functions  are  simple  with  few  or  no 
arguments.  Rather  then  detail  each  function  with  words,  I 
hope  the  names  of  the  functions,  the  comments  in  the 
listings,  and  the  following  examples  will  demonstrate  how 
to  use  the  support  code. 

Building  an  Executive  'Board 

A  linear  network  is  one  of  the  simplest  types  of  network.  It 
operates  by  passing  the  result  from  the  propagation  func¬ 
tion  directly  to  its  output;  that  is,  the  activation  function 

performs  no  action  on  the  input.  To  demonstrate  this  type 
of  network,  let’s  consider  an  executive  board  that  has  five 

voting  members.  Each  member  represents  some  number  of 
Stockholders  who  are  voting  by  proxy.  There  is  one  vote 
taker  u>  whom  all  beard  members  give  their  votes.  The  vote 
taker  then  determines  the  net.  vote  (now  many  for  or  against) 
by  considering  how  each  board  member  votes  and  how 
many  stockholders  he  or  she  represents.  The  vote  taker  then 
reports  the  results  to  the  board  president,  who  announces 
the  outcome  of  the  vote. 

This  problem  can  be  represented  as  a  neural  network 
with  the  board  members  as  an  input  layer  consisting  of  five 
neurons  The  vote  taker  is  a  one-neuron  hidden  layer  and 
the  boaid  president  Is  a  one-neuron  output  layer.  The 
weight  between,  the  input  layer  and  the  vote  taker  Is  the 
number  of  stockholders  a  board  member  represents.  The 
vote  taker  is  considered  to  be  honest,  so  the  board  president 
takes  the  results  at  lace  value  (a  weight  of  1,0).  Figure  2, 
page  16,  is  a  diagram  of  the  network,  and  Listing  Three, 
page  95,  is  the  source  to  implement  the  executive  board 
neural  network.  When  rim,  the  program  prompt'  vot.  h* 


The  Logic  Gate 

A  slightly  more  complicated  network  is  the  linear-threshold : 
based  network.  With  this  type  of  network,  the  output  value 

is  set  to  a  specific  value  if  the  net  input  to  the  neuron 
exceeds  some  threshold  (specific  value)  and.  to  'something 
different  if  the  value  is  below  the  threshold.  A  good  example 
of  such  a  network  is  one  that  emulates  logic  gates.  With  a 
logic  gate,  the  gate,  is  either  on  or  off,  so  you  have  what  is 
called  a  binary  linear  threshold.  For  a  two-input  OR  and  a 
two-input  AND  gate,  you  can  use  an  input  layer  of  two 
neurons,  a  hidden  layer  of  one  neuron,  anti  an  output  layei: 
of  one  neuron.  A  two-gate  XOR  requires  a  two-neuron 
hidden  layer.  The  difference  is  because  the  XOR  logic  gats 
needs  to  compare  both  inputs  from  two  persjxs  trees  so  it 
can  perform  the  exclusive  operation. 

Now  let’s  look  at  how  you  can  "teach"  a  network  to 
recognize  the  two-bit  inpui  patterns  and  produce  the  de¬ 
sired  one-bit  output  pattern.  Even  though,  with  more  code 
and  execution  time,  the  network  could  teach  itself,  let’s 
calculate  the  weights  for  the  connections  tetween  .til  neu¬ 
rons  by  deriving  them  mathematic  ally  The  first  thing  n >  note 
is  that  with  linear  networks,  when  you  have -a  neuron  wit 
only  one  input  connection,  that  neuron  is  not  needed.  The 
input  connection  can  bypass  the  one  tonne,  non  neuron 
and  go  directly  to  all  neurons  that  the  one  connection 
neuron  connects  to,  without  altering  the  .solution.  This  meaty 
that  for  the  AND  and  OR  logic  gates,  you  really  only  neec 
two  layers  Using  three  layers  here  means  that  the  model-  to 
a  more  complicated  solution  than  is  needed,  hut  I’ll  accept 
the  three-layer  model  so  that  all  examples  can  me  the  saint 
support  library.  You  can  infer  from  this  that  rhe  w  eigh! 
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(continued  from  page  15) 


between  the  hidden  layer  and  output  layer  is  to  be  1.0  (face 
value). 

Starting  with  the  OR  gate,  you  can  detail  the  mappings 
between  the  input  pattern  and  the  desired  output  pattern, 
as  shown  in  Table  1,  page  24. 

From  this  you  can  derive  the  following  simultaneous 
equations,  which  once  solved  will  tell  you  what  weights  the 
connections  between  the  input  and  hidden  layer  are  to 
have.  Let’s  use  a  threshold  of  1.0  to  differentiate  between 
an  on  state  and  an  off  state.  The  general  equation  is: 

wpi  +  w2i2  >=0 

where  w2  is  the  weight  for  input  neuron  1  and  u>2  is  the 
weight  for  neuron  2,  it  and  i2  are  the  input  patterns,  and  o 
is  the  output  pattern.  The  >=  is  because  you’re  using  a 
threshold  network.  Because  you  have  four  patterns,  the 
equations  after  substitution  of  the  values  are: 

w,  >=  1.0 

w2  >=  1.0 

Wj  +  w,  >=  1.0 

This  not  only  gives  you  the  answer  immediately  but  also 
provides  a  check  for  the  answer.  Let’s  choose  1.0  for  both 
connections.  You  can  derive  the  weights  for  the  AND  gate. 
The  values  of  wt  =  0.5  and  w2  =  0.5  should  be  one  of  the 
solutions. 

The  solution  for  the  XOR  gate  is  more  complicated  to 
derive  and  requires  more  math,  so  I’ll  discuss  the  logic 


Figure  1:  An  example  of  a  fully  connected  three-layer 
network 


Figure  2:  Topology  of  the  executive  board  network 


NEURAL  NETWORKS 

(continued  from  page  16) 


behind  its  solution.  The  weights  between  the  input  and 
hidden  layers  must  be  adjusted  so  that  when  both  inputs  are 
on  the  hidden-layer  neurons  are  turned  off.  This  is  easy  to 
do  if,  at  any  hidden-layer  neuron,  the  weights  given  to  the 
input  neurons  are  equal  in  value  but  have  opposite  signs. 
Then,  whenever  both  neurons  are  on,  they  cancel.  This 
makes  the  input-hidden  layer  pair  a  filter  that  ensures  that 
both  hidden-layer  neurons  can  never  be  on.  The  hidden- 
output-layer  pair  is  then  a  simple  OR  gate. 


The  most  difficult  aspect  of 
dealing  with  neural  networks  is 
the  proper  management  of 
the  neurons 


Figure  3,  page  24,  shows  what  all  the  logic  gates  look  like 
as  neural,  networks  and  Listing  Four,  page  91,  shows  how 
to  build  the  logic  gate  networks.  When  you  run  the  code,  it 
prompts  you  for  the  values  for  the  input  pins  for  each  type 
of  gate,  and  the  result  is  printed  to  the  screen. 

The  OCR  System 

Now  let’s  try  something  that  is  really  suited  for  neural 
networks  — an  optical  character  recognition  (OCR)  system. 


which  translates  an  optical  pattern  composed  of  on  and  off 
bits  to  an  ASCII  code.  The  system  will  also  tell  you  just  how 
certain  it  is  that  the  input  pattern  is  the  character  it  says  it  is. 
To  do  this  I  need  to  introduce  one  other  concept  — namely, 
of  clustering.  A  cluster  is  a  collection  of  neurons,  all  in  the 
same  layer,  which  are  in  competition  with  one  another  to 
be  the  only  one  on.  It’s  winner  takes  all  in  a  cluster,  so  the 
rule  that  is  applied  is  that  the  neuron  that  is  closest  to  being 
on  is  forced  on  whereas  all  other  neurons  are  forced  off. 
The  closeness  to  being  on  is  a  measure  of  the  certainty  to 
which  the  input  pattern  can  be  determined.  In  the  cases  in 
which  two  or  more  neurons  have  the  same  value  and  are 
closest,  the  first  neuron  encountered  is  turned  on.  Doing 
this  doesn’t  affect  the  accuracy  of  the  recognition  because 
all  neurons  with  equal  values  have  the  same  certainty. 

For  the  OCR  system,  the  input-hidden-layer  pair  is  de¬ 
fined  to  be  a  binary  linear-threshold-based  network  in  which 
neurons  are  either  on  or  off.  The  other  layer  pair,  composed 
of  the  hidden  layer  and  the  output  layer,  is  defined  to  be  a 
linear  network.  This  approach  allows  you  to  associate  any 
value  you  like  with  the  bit-image  input  pattern.  Only  the 
neurons  in  the  hidden  layer  are  clustered,  and  all  neurons 
in  the  hidden  layer  are  placed  in  the  same  cluster.  A  further 
restriction  that  is  placed  on  the  OCR  network  is  that  the  sum 
of  all  weights  for  all  input  connections  to  a  neuron  in  the 
hidden  layer  will  be  1.0  or  less.  Collectively,  the  input-hidden- 
layer  pair,  with  all  its  features  and  restrictions,  is  a  variety 
of  what  is  commonly  called  a  perceptron  (Rosenblatt,  1957). 
One  aspect  of  a  perceptron  is  that  it  can  classify  its  input 
patterns  in  as  many  groups  as  there  are  neurons  in  the 
hidden  layer.  Thus,  to  uniquely  classify  the  26  characters  in 
the  alphabet  the  hidden  layer  must  have  26  neurons. 

In  order  for  the  OCR  network  to  recognize  a  pattern,  it 
must  be  taught  which  patterns  produce  which  outputs.  You 
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can  simplify  the  learning  process  by  understanding  just 
what  the  network  learns  and  then  build  in  shortcuts  that 
will  speed  things  up.  For  this  example,  let’s  limit  each  group 
so  that  it  recognizes  only  one  character.  By  doing  this  the 
learning  process  is  almost  instantaneous. 

Each  letter  to  learn  is  read  and  presented  to  the  network. 
The  next  unaltered  hidden  neuron  is  selected,  and  the 
weights  from  that  neuron  to  all  input  neurons  are  set.  The 
weight  for  each  input  connection  that  is  on  is  set  to  1.0 
divided  by  the  total  number  of  input  connections  that  are 
on.  The  weight  for  any  input  connection  that  is  off  is  set  to 
0.0.  The  weight  of  the  connections  from  the  hidden-layer 
neurons  to  the  output  neuron  is  set  to  the  numeric  (ASCII, 


Input 

Output 

00 

0 

1  0 

1 

0  1 

1 

1  1 

1 

Table  1:  Mappings  between  input  pattern  and  desired  out¬ 
put  pattern  for  an  OR  gate 


OR  /  AND  GATE 


Output  pin 


Logic  gate 


Input  pins 


XOR  GATE 

Output  pin 


Logic  gate 


Input  pins 


Figure  3:  Topology  of  the  logic  examples 
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for  example)  value  with  which  the  input  pattern  is  associ¬ 
ated.  The  function  learn_ocr( )  in  Listing  Five,  page  94, 
does  all  this.  Once  a  network  has  learned  a  set  of  characters, 
you  can  present  it  with  any  character  pattern  and  it  will  tell 
you  which  one  of  the  known  patterns  the  presented  pattern 
matches  most  closely. 

Listing  Five  contains  the  code  for  the  OCR  system,  and 
Figure  4,  below,  shows  the  topology  of  the  neural  network. 


Figure  4:  Topology  of  the  OCR  network 


When  you  run  this  program,  you  specify  the  characters  it  is 
to  learn  and  test  on  the  command  line  as  file  names.  Only 
one  character  is  allowed  in  each  file.  The  patterns  to  learn 
are  given  first,  then  the  word  -test,  and  then  the  file  names 
of  the  patterns  to  test.  The  content  of  a  file  is  the  optical 
pattern  for  a  character  as  a  5x7-bit  pattern,  with  the  bits 
represented  as  Is  and  Os.  If  the  OCR  system  is  to  learn  a 
pattern,  the  next  value  after  the  character  pattern  is  the 
numeric  value  that  pattern  is  to  be  known  by.  A  pattern  that 
is  only  to  be  tested  does  not  need  a  numeric  value  because, 
when  the  OCR  system  is  testing  a  pattern,  it  reads  only  the 
pattern.  The  format  of  the  file  allows  the  same  file  to  be  used 
for  both  learning  and  testing.  Table  2,  page  28,  contains 
values  for  the  letters  A,  B,  C,  E,  and  O.  A  good  invocation 
would  be: 

ocr  letter.a  letter.b  letter.c  -test  letter.a  letter.e  letter.o 

The  OCR  system  should  respond  with  A  is  an  A,  E  is  a  B, 
and  O  is  C,  which  is  an  intelligent  deduction  given  that  all 
the  OCR  network  knows  about  are  the  letters  A,  B,  and  C. 

Benchmarks 

On  an  XT-compatible  rated  at  CL  1.8  and  DI:  1.1  with 
Norton’s  SI  program,  1  found  that  the  OCR  neural  network, 
when  compiled  with  Turbo  C,  could  learn  a  new  pattern  in 
0.2  seconds.  With  four  pattern  groups  it  could  determine  a 
pattern  in  0.7  seconds.  There  was  an  overall  start-up  over¬ 
head  of  0.2  seconds.  The  program  and  library  were  com¬ 
piled  so  that  they  were  optimized  for  speed,  register  use, 
and  jumps,  and  floating-point  emulation  was  in  effect.  List¬ 
ing  Six,  page  95,  contains  the  project  files  to  build  the 
examples  using  Turbo  C.  The  source  will  also  compile  and 
run  under  Quick  C. 
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00100 

B: 

11110 

C: 

00110 

01010 

10001 

01001 

10001 

10001 

10000 

11111 

11110 

10000 

10001 

10001 

10000 

10001 

10001 

01001 

10001 

11110 

00110 

65.0 

66.0 

67.0 

E: 

11111 

O: 

00100 

10000 

01010 

10000 

10001 

11100 

10001 

10000 

10001 

10000 

01010 

11111 

00100 

69.0 

79.0 

Table  2:  Values  for  letters  A,  B,  C,  E,  and  O.  The  values  for 
each  letter  must  be  in  separate  files  when  used  with  the  OCR 
example.  The  bit  image  is  shaded  to  emphasize  how  it  was 
derived. 


Conclusion 

I  encourage  you  to  experiment  with  neural  networks.  The 
support  library  contained  in  this  article  is  a  toolbox  you  can 
use  to  do  this.  The  most  difficult  aspect  of  dealing  with 
neural  networks  is  the  proper  management  of  the  neurons. 
One  way  to  do  this  is  revealed  in  Listing  Two,  which  is  the 
include  file  that  is  shared  between  the  examples  and  the 
support  library. 

Even  though  neural  networks  have  been  a  concept  for 
almost  as  long  as  computers  have  existed,  there’s  still  room 
for  new  ideas  and  innovations.  This  article  touches  on  only 
a  small  part  of  the  topologies  and  functionality  of  neural 
networks.  If  you’d  like  to  learn  more  about  neural  networks, 
see  the  bibliography  for  reading  material. 

I’m  giving  this  neural  network  toolbox  away  freely.  If  you 
do  use  it  to  build  applications,  please  do  not  charge  for  the 
toolbox  portion. 

Please  direct  any  questions  about  this  article  to  the  author 
at  the  address  given  at  the  beginning  of  the  article.  If  you  need 
a  response,  include  a  self-addressed,  stamped  envelope. 
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ARTICLES 


Neural  Nets  and 
Noise  Filtering 

Back-propagation  is  a  powerful  adaptive  method  for 
filtering  out  noise  or  identifying  underlying  signals 


by  Casey  Klimasauskas 


Neural  networks  are  an  informa¬ 
tion-processing  technology  in¬ 
spired  by  studies  of  the  brain 
and  nervous  system.  Despite  (or,  per¬ 
haps,  because  of)  their  origins,  certain 
types  of  neural  networks  have  a  strong 
founding  in  mathematics.  One  network 
type  in  particular,  back-propagation , 
is  a  powerful  adaptive  technique  for 
approximating  relationships  between 
several  continuous  valued  inputs  and 
one  (or  more)  continuous  valued  out¬ 
put.  This  article  discusses  applications 
of  back-propagation  to  filtering  out 
noise,  or,  conversely,  identifying  fun¬ 
damental  underlying  signals.  An  exam¬ 
ple,  discussed  later,  is  in  isolating  EKG 
signals  taken  from  a  noisy  environment. 

This  article  addresses  the  problem 
of  developing  a  limited  number  of  “fea¬ 
ture  detectors”  that  can  account  for  the 
maximum  amount  of  a  signal  (in  a  least- 
mean-square  sense).  In  doing  this,  the 
noise  is  assumed  to  be  random  and  of 
a  higher  frequency  than  the  underlying 
signal.  The  approach  taken  here  is  to 
find  a  way  of  encoding  or  compressing 
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the  input  data  and  then  reexpanding  it. 
The  compression  process  eliminates  por¬ 
tions  of  the  input  data,  which  represent 
small  or  nonrecurring  features.  By  se¬ 
lecting  the  number  of  “encoders,”  you 
can  vary  the  amount  of  detail  retained 
in  the  transformation.  Figure  1,  page 
31,  illustrates  this  process.  Key  to  solv¬ 
ing  this  problem  is  the  selection  of  a 
good  set  of  feature  detectors  for  the 
particular  signal  to  be  to  filtered. 

Notice  that  in  Figure  1  the  1 1  inputs 
have  been  reduced  at  the  output  of  the 
encoder  stage  to  3  outputs.  If  you  were 
to  represent  each  input  as  well  as  the 
output  of  each  encoder  as  a  32-bit  float¬ 
ing-point  number,  it  would  take  352 
bits  (1 1  x  32)  to  represent  the  input  to 
the  system.  It  would  take  96  bits  (3  x 
32)  to  represent  the  output  of  the  sys¬ 
tem.  From  this  perspective,  you  have 
compressed  the  input  data  by  a  factor 
of  96/352.  This  form  of  data  compres¬ 
sion  is  also  known  as  dimensionality 
reduction.  You  have  reduced  the  num¬ 
ber  of  dimensions  from  1 1  to  3.  For  this 
system  to  work  well,  you  must  be  sure 
that  the  following  two  interrelated  cri¬ 
teria  are  met:  1.  There  must  be  some 
relationship  between  input  variables; 
and  2.  You  must  use  an  encoding  sys¬ 
tem  that  can  represent  the  relationship. 

It  may  not  be  apparent  at  first  that 


these  two  criteria  are  related,  but  con¬ 
sider  the  situation  in  which  the  input 
samples  are  from  a  constant-amplitude 
sine  wave.  In  this  case,  you  could  en¬ 
code  the  data  exactly  with  a  single 
“sine-wave”  detector  in  which  the  out¬ 
put  is  related  to  the  position  in  the 
cycle.  On  the  other  hand,  trying  to  use 
another  type  of  detector  function  may 
require  several  detectors  to  develop  a 
“piece  wise”  approximation  of  the  func¬ 
tion.  If  there  is  no  relationship  between 
the  input  variables,  dimensionality  re¬ 
duction  often  results  in  a  series  of  fixed 
outputs  representing  the  “average”  value 
of  a  combination  of  inputs.  In  the  case 
of  noise  filtering  (where  the  inputs  are 
a  series  of  time-sequential  samples), 
there  is  usually  a  high  degree  of  corre¬ 
lation  (or  relationship)  between  adja¬ 
cent  time  samples.  Dimensionality 
reduction  works  very  well  in  this 
situation. 

With  a  little  thought,  it  becomes  ap¬ 
parent  that  if  the  signal  you  are  work¬ 
ing  with  has  a  noise  component  added 
to  it,  the  contribution  of  the  noise  to 
the  signal  will  tend  to  be  random  or 
nonstationary  with  respect  to  other 
larger  features.  As  such,  the  noise  will 
most  likely  be  one  of  the  features  elimi¬ 
nated  in  the  encoding  process.  If  the 
noise  component  is  of  a  relatively  low 
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frequency  and  accounts  for  a  majority 
of  the  energy  in  the  output  signal  (for 
example,  60-cycle  hum),  this  process 
will  detect  the  noise.  Subtracting  the 
output  of  the  detector  from  the  input 
signal  removes  the  noise  from  the 
signal. 

To  approach  the  problem  of  feature 
detection,  first  consider  a  simpler  prob¬ 
lem  of  mapping  from  a  single  continu¬ 
ous  input  to  a  single  continuous  out¬ 
put.  Assume  that  the  input  and  output 
are  related  by  some  continuous  differ¬ 
entiable  function.  Figure  2,  this  page, 
shows  a  plot  of  input  values  “X”  and 
output  values  “Y.” 

A  first  attempt  to  approximate  the 
relationship  uses  a  linear  relationship. 
This,  too,  is  shown  in  Figure  2.  The 
slope  of  this  line  can  be  determined 
using  statistical  techniques  (linear  re¬ 
gression)  or  by  using  adaptive  signal¬ 
processing  techniques  (Bernard  Wid- 
row).  Rather  than  using  a  straight  line, 
you  could  have  used  a  quadratic  poly¬ 
nomial.  Figure  3,  this  page,  shows  how 
a  quadratic  polynomial  might  fit  the 
data  shown.  Both  of  these  techniques 
can  be  generalized  to  two,  three,  or 
more  inputs.  Notice  that  regardless  of 
the  number  of  inputs,  each  feature  de¬ 
tector  has  exactly  one  output. 

For  both  of  the  cases  just  described, 
the  decoded  output  is  assumed  to  be 
identical  to  the  output  of  the  encoders. 
Consider  a  more  complex  situation  in 
which  you  use  a  “sigmoidal”  feature 
detector.  Figure  4,  page  34,  shows  an 
example  of  a  sigmoid  function.  You 
might  use  this  function  to  create  two 
encoders  as  shown  in  Figures  4b  and 
4c.  Now,  if  you  use  a  decoder  that 
takes  the  difference  of  the  output  of 
the  two  encoders,  you  have  the  func¬ 
tion  shown  in  Figure  4d.  Using  this 
method,  you  have  been  able  to  synthe¬ 
size  a  “bump.”  By  varying  the  aiO term, 
you  shift  the  transition  point.  Varying 
the  ail  parameter  changes  the  slope 
at  the  transition.  In  this  way,  you  could 
have  created  a  “bump”  of  any  size,  any 
location,  and  independently  vary  the 
slope  of  each  of  its  sides.  By  adding 
more  “bumps”  together,  you  can  cre¬ 
ate  arbitrarily  complex  functional  rela¬ 
tionships  between  one  or  more  inputs 
and  a  single  output. 

Though  bumps  can  be  used  to  cre¬ 
ate  arbitrarily  complex  functions,  this 
may  not  always  be  the  best  method. 
At  times,  it  may  be  better  to  use  sine 
or  other  types  of  functions  in  the  en¬ 
coders.  Using  “sine”  encoders  is  equiva¬ 
lent  to  Fourier  decomposition  of  the 
inputs.  Unlike  the  standard  Fourier  trans¬ 
form,  this  technique  accounts  for  both 
the  phase  and  amplitude  of  the  sam¬ 
pled  input. 

At  this  point,  you  might  observe  that 


Figure  1:  An  input  signal  is  sampled  at  several  points  (11  in  this  case)  with 
the  data  from  these  sample  points  encoded  by  three  encoders.  The  output  of 
the  encoders  is  used  to  reconstruct  the  full  1 1  inputs  through  the  decoders. 


Figure  2:  A  scatter  diagram  of  several  x-inputs  and  the  resulting  y-outputs. 
The  line  shown  was  selected  to  minimize  the  error  between  what  would  be 
predicted  by  the  line  and  the  actual  output. 


Figure  3:  The  effect  of  using  a  quadratic  function  to  approximate  the 
relationship  between  the  input  X  and  the  output  Y. 
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NOISE  FILTERING 

( continued  from  page  34) 


cal  to  a  single  linear  element.  The  novel 
characteristics  of  the  neural  network 
approach  is  that  the  output  of  the 
weighted  sum  (linear  combination  of 
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Artificial  neural  networks  (A 
great  promise  in  providing  so 
to  signal  processing  or  signal-nc 
duction  problems.  In  fact,  these  sol 
lions  might  be  seen  as  more  natural 
intuitive  when  compared  with  tra 
tional  techniques.  As  this  note  will  in¬ 
dicate,  however,  there  are  a  number 
of  issues  and  considerations  that  have 
to  be  faced  when  applying  theory  I 
real-world  situations.  A  few  more  wor 
on  how  a  neural  network  does  sigr— 
processing  might  help  to  clarify  this 
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the  inputs)  is  transformed  using  a  non¬ 
linear  function  such  as  a  sigmoid  or 
sine  function.  These  nonlinearities  make 
the  creation  of  multilevel  systems  pos¬ 
sible  and  are  responsible  for  several  of 
the  resulting  characteristics. 

Why  use  this  approach?  The  two  ba¬ 


sic  reasons  are  as  follows.  First,  it  is 
capable  of  retaining  a  level  of  detail 
greater  than  other  techniques.  Rather 
than  simply  ignoring  small  features,  it 
can  allow  them  to  pass  if  they  are  of  a 
stationary  recurring  nature.  Second,  the 
amount  of  detail  retained  by  the  filter¬ 


ing  process  can  be  varied  by  varying 
the  number  of  elements  in  the  hidden 
layer.  From  these  perspectives,  it  is  a 
technique  providing  additional  flexibil¬ 
ity  and  control  when  the  engineer  ana¬ 
lyzes  noisy  data. 

The  approach  described  thus  far  is 


(or  representation)  of  a  typical  signal. 
Following  this,  we  have  a  network  to 
process  the  noisy  data. 

To  illustrate  the  process  in  an  engi¬ 
neering  application,  Figure  la  shows 
the  training  or  target  signal  for  a  medi¬ 
cal  diagnostic  (hemoglobin  red  blood 
cell)  device  and  the  network  output 
after  different  numbers  of  training  cy¬ 
cles.  For  our  data  a  few  hundred  train¬ 
ing  epochs  resulted  in  better  than  a 
one  percent  difference  between  taiget 
and  output.  Figure  lb  shows  the  end 


result  of  applying  this  network  on  a 
noisy  set  of  data.  For  this  study  I  used 
either  two,  five,  or  ten  inputs  along 
with  ten  hidden  units;  the  presented 
results  are  for  the  case  of  five  inputs. 

Now  to  important  considerations 
when  putting  neural  network  theory 
into  practice.  First,  if  we  use  a  small 
input  window  (for  instance,  the  num¬ 
ber  of  inputs  is  one  or  two),  we  will 
have  a  fine  sampling  of  our  signal.  As 
such,  we  will  need  a  large  number  of 
hidden  units  to  correctly  encode  the 


500  1000  1500  2000  2500 


Figure  1:  a)  Network  generated  pulse  height  vs.  time,  Jive  inputs  ten  hidden 
units,  b)  Pulse  height  vs.  time  for  noisy  data,  five  inputs  ten  hidden  units;  c) 
Noisy  data  network  output  vs.  time. 


|  character  of  the  signal.  This  in  turn 
involves  more  data  processing,  which 
could  prohibit  real-time  response  with¬ 
out  the  use  of  parallel  processors.  Fur¬ 
thermore,  with  only  two  inputs,  if  one 
or  both  are  noisy,  the  success  of  the 
network  in  distinguishing  between  sig¬ 
nal  and  noise  is  diminished.  Therefore, 
we  might  want  to  increase  the  size  of 
the  input  window  in  order  to  maximize 
the  network’s  noise  handling  capabili¬ 
ties.  Remember,  however,  that  we’re 
also  trying  to  maintain  as  fine  a  sam¬ 
pling  as  possible  to  maximize  signal 
detail.  The  question  then  becomes:  Flow 
many  inputs  and  how  many  hidden  units? 

In  general,  the  task  is  to  find  a  bal¬ 
ance  between  a  number  of  variables 
(besides  the  number  of  units),  which 
at  the  present  are  more  or  less  deter¬ 
mined  empirically.  In  addition,  we  might 
decide  to  introduce  feedback  (networks 
of  this  type  are  sometimes  called  Jor¬ 
dan  networks)  from  either  input  or  out¬ 
put  to  further  enhance  the  network’s 
memory  of  the  signal’s  time  structure. 
As  mentioned  in  the  main  article,  many 
of  these  options  can  be  explored  more 
quickly  using  one  of  the  commercially 
available  network  simulation  packages. 
For  my  work,  I  used,  and  highly  rec¬ 
ommend,  The  Cognitron  by  Cognitive 
Software. 

Figure  lc  shows  a  final  plot  of  our  data 
representing  the  arithmetic  difference 
between  the  two  curves  of  Figure  lb. 
You  can  see  this  difference  is  relatively 
small,  except  for  a  number  of  spikes. 
Figure  lc  is  marked  with  two  horizon¬ 
tal  lines  to  indicate  these  large  variance 
points.  In  fact,  these  spikes  emerge  just 
where  we  have  a  random  noise  pulse 
interposed  as  part  of  the  data! 

To  conclude,  the  network  distin¬ 
guished  the  signal  from  the  noise  with¬ 
out  using  multiband  filters,  Fourier- 
Laplace  transforms,  and  the  like.  You 
might  even  go  further  to  conclude  that 
artificial  neural  networks  seem  to  have 
an  almost  human  capability  to  process 
difficult,  intrinsically  nonlinear  signal 
shapes. 


Steve  Melnikof  is  an  experimental  par¬ 
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hours  in  a  multitasking  fashion.  When 
he  isn’t  designing  experiments  or  con¬ 
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home  programming  a  Macintosh  II  to 
investigate  neural  network  architectures. 
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to  develop  a  limited  number  of  feature 
detectors  that  encode  a  series  of  sam¬ 
ples  of  an  input  signal.  The  output  of 
these  encoders  is  used  to  reconstruct 
all  or  a  portion  of  the  input  sample. 
The  use  of  a  limited  number  of  feature 
detectors  ensures  that  some  of  the  in¬ 
formation  (preferably  the  noise)  will 
be  removed  in  the  reconstruction. 

Putting  the  Theory  Into  Practice 

Until  now,  the  problem  of  how  to  com¬ 
pute  the  various  coefficients  used  by  a 
feature  detector  or  encoder  has  been 
ignored.  The  process  is  a  form  of  re¬ 
gression.  The  word  “regression”  comes 
from  a  study  done  in  the  early  1900s. 
In  this  study,  the  researchers  attempted 
to  find  relationships  between  the  height 
of  parents  and  that  of  their  children. 
They  developed  a  statistical  technique 
for  fitting  a  straight  line  through  the 
data  (linear  regression).  The  results  of 
the  study  showed  that  tall  parents  had 
shorter  children  and  that  short  parents 
had  relatively  taller  children  — their 
heights  were  regressively  correlated. 
The  term  regression  analysis  applies 
to  any  technique  for  fitting  a  curve  to 
data. 

The  technique  used  to  set  the  coeffi¬ 
cients  in  a  network  is  described  as  a 
set  of  differential  equations  that  modify 
the  coefficients  in  such  a  way  as  to 
reduce  the  mean-square-error  of  the 
output  for  the  training  set.  These  are 


derived  by  defining  the  error  for  a  sin¬ 
gle  pass  through  a  training  set  (several 
presentations  of  input  and  expected, 
or  desired,  output)  as  the  sum  of  the 
squares  of  the  difference  of  the  actual 
and  expected  outputs.  This  is  called 
the  square  error. 

The  derivative  of  each  weight  (or 
coefficient)  in  the  network  is  computed 
as  a  function  of  the  error.  For  most 
cases,  these  differential  equations  do 
not  have  a  closed-form  solution.  As 
such,  the  solution  (or  a  solution)  is 
derived  by  using  numerical  methods. 
The  numerical  techniques  compute  the 
direction  to  change  the  coefficients  (gra¬ 
dient)  and  then  change  them  slightly 
in  that  direction.  The  mathematics  be¬ 
hind  this  are  explained  in  detail  in  Chap¬ 
ter  8  of  Parallel  Distributed  Processing 
by  Rumelhart  and  McClelland  (MIT  Press 
1986). 

Listing  One,  page  96,  presents  a  back- 
propagation  network  program  that  can 
solve  the  “exclusive  OR”  problem  de¬ 
scribed  in  the  Rummelhart-McClelland 
book.  This  program  could  also  be  ex¬ 
tended  to  solve  the  noise  filtering  prob¬ 
lem.  If  you  want  to  extend  the  program 
in  Listing  One  to  solve  the  “noise  filter¬ 
ing”  problem,  you  must  do  three  things: 

1.  Increase  the  number  of  processing 
elements  in  the  input  and  output  layers 
to  19  each  and  the  number  of  process- 
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ing  elements  in  the  hidden  layer  to  5, 
7,  10,  or  19. 

2.  Delete  all  of  the  existing  connec¬ 
tions  and  fully  connect  the  input  layer 
to  the  hidden  layer  and  the  hidden 
layer  to  the  output  layer.  Likewise  fully 
connect  the  bias  to  both  the  hidden 
and  output  layers. 

3.  Write  a  module  to  load  a  series  of 
noise  data  into  memory  and  present 
them  to  the  network. 

For  the  purposes  of  studying  the  noise 
filtering  problem,  I  used  a  commercial 


One  of  the  particularly 
interesting 
characteristics  of 
neural  nets  is  the 
capability  to  develop  an 
adaptive  filtering 
technique  that  can  be 
tuned  to  preserve 
varying  degrees  of 
detail 


neural  network  development  environ¬ 
ment  (NeuralWorks  Professional  II  by 
NeuralWare)  for  all  of  the  examples 
that  follow  because  neural  network  de¬ 
velopment  systems  provide  the  infra¬ 
structure  needed  to  solve  the  problem. 
These  systems  provide  the  network  build¬ 
ing  tools  that  make  it  easy  to  change 
the  network  design,  interfaces  to  assist 
in  setting  up  the  problem,  tools  for 
investigating  what  is  happening  within 
the  network  itself,  and  a  host  of  other 
“bookkeeping”  functions.  A  good  de¬ 
velopment  environment  also  enables 
you  to  focus  on  the  problem.  Though 
most  neural  network  types  appear  rela¬ 
tively  straightforward  from  the  stand¬ 
point  of  mathematics,  many  program¬ 
mers  find  it  difficult  to  debug  this  kind 
of  numerical-oriented  code.  If  a  hand- 
coded  network  fails  to  converge,  the 
problem  may  lie  either  in  the  “code” 
or  the  network  parameters.  A  neural 
network  development  environment 
solves  the  first  of  these  problems  and 
makes  the  other  problems  easier  to 
test. 


Figure  5a :  Noise  filtering  with  five  hidden  units.  Though  not  shown,  all  of 
the  elements  in  the  "Input"  layer  are  connected  to  all  of  the  units  in  the 
" Hidden "  layer.  Likewise,  all  of  the  units  in  the  "Hidden"  layer  are  connected 
to  all  of  the  elements  in  the  "Out"  layer.  The  upper  plot  ("Filtered  Output 
Signal")  shows  the  output  value  of  the  middle  processing  element  in  the  output 
(top-most)  layer. 
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Figures  5a,  page  42,  and  5b,  5c,  and 
5d,  page  44,  show  screen  dumps  of 
four  tests  of  training  a  network  to  filter 
out  noise.  The  examples  use  5,  7,  10, 
and  19  elements  in  the  hidden  layer. 
As  you  would  expect  from  the  previ¬ 
ous  discussion,  the  more  processing 
elements  in  the  hidden  layer,  the  more 
detail  is  preserved  from  the  encoding 
process  to  decoding  process. 

The  data  displayed  in  the  lower  win¬ 
dow  of  each  of  the  examples  is  the  raw 
input  data.  This  is  actually  EKG  data 
taken  in  a  noisy  environment  (the  noise 
is  caused  primarily  by  fluorescent  lights). 


Figure  5b:  The  same  experiment  done  with  seven  hidden  units.  Notice  that 
additional  details  have  been  captured. 
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Figure  5c:  The  same  experiment  done  with  ten  hidden  units.  Notice  the 
increase  in  detail  over  five  units. 
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Figure  5d:  A  final  experiment  done  with  19  units.  Though  a  certain  amount 
of  additional  detail  was  retained  in  the  process,  it  is  not  appreciably  more 
than  in  Figure  5c. 


Neural  network 
techniques  are 
sometimes 
smarter  than 
you  might 
expect! 


The  filtered  output  data  is  displayed  in 
the  upper  window.  The  networks  used 
here  each  had  19  inputs  and  19  out¬ 
puts.  The  “filtered  output”  in  the  upper 
window  is  the  output  of  the  center 
processing  element  of  the  output  layer. 
Experimentally,  the  outputs  of  the  other 
processing  elements  in  the  output  layer 
do  a  similar  job  of  tracking  the  input. 

So  far,  we  have  looked  at  the  prob¬ 
lem  from  the  perspective  of  doing  di¬ 
mensionality  reduction  on  19  inputs 
to  produce  19  outputs.  The  way  we 
trained  the  network  was  to  randomly 
select  a  block  of  19  sequential  samples 
from  the  raw  data,  and  to  use  this  as 
both  the  input  and  desired  output  of 
the  network.  This  was  typically  repeated 
300,000  to  600,000  times  for  each  of  the 
networks  shown  (overnight  on  a  NEC 
Powermate  III).  Each  time  a  block  of 
inputs  was  applied  to  the  network,  the 
weights  were  slightly  adjusted  to  make 
the  actual  network  output  closer  to  the 
desired  output.  Only  the  middle  out¬ 
put  element  is  used  as  the  “filtered” 
output. 
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You  might  wonder  what  would  hap¬ 
pen  if  you  were  to  have  only  one  out¬ 
put  element  that  was  trained  to  re¬ 
produce  the  value  of  the  middle  input. 
Figure  6,  this  page,  shows  the  results 
of  such  a  network  with  five  elements 
in  the  hidden  layer. 

Closely  examining  the  weights  in  the 
network,  it  becomes  clear  that  the  out¬ 
put  is  affected  almost  exclusively  by 
the  center  input.  All  other  inputs  are 
ignored.  Neural  network  techniques  are 
sometimes  smarter  than  you  might  ex¬ 
pect!  The  use  of  additional  processing 
elements  in  the  output  layer  forces  the 
feature  detectors  to  come  up  with  a 
more  “general”  way  of  encoding  the 
inputs. 

During  the  recall  process,  the  raw 
data  is  shifted  through  a  19-element 
long  shift  register  and  the  output  com¬ 
puted  with  that  set  of  inputs.  The  data 
is  shifted  one  position  and  the  process 
repeated. 

The  training  process  is  reasonably 
repeatable  with  the  data  shown.  We 
have  tried  it  on  a  variety  of  other  sig¬ 
nals  (manually  constructed)  with  some 
interesting  results.  Depending  on  the 
type  of  signal  used,  the  processing  ele¬ 
ments  in  the  hidden  layer  should  use 
a  “sine”  function  rather  than  a  sigmoid. 
As  mentioned  previously,  this  causes 
the  network  to  do  a  form  of  Fourier 
decomposition  and  reconstruction. 


Conclusion 

As  a  general  technique,  neural  network- 
based  techniques  for  noise  filtering  of¬ 
fer  an  interesting  and  potentially  pow¬ 
erful  approach.  One  of  the  particularly 
interesting  characteristics  of  neural  nets 
is  the  capability  to  develop  an  adaptive 
filtering  technique  that  can  be  tuned 
to  preserve  varying  degrees  of  detail. 
Significant  experimentation  remains  to 
develop  these  techniques  to  the  point 
where  they  are  well  characterized  and 
understood. 
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Figure  6;  The  effects  of  training  the  network  with  only  a  single  output.  The 
input  signal  is  reproduced  as  output.  An  analysis  of  the  weights  shows  that  the 
only  input  affecting  the  output  is  the  middle  one. 
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UNIX  STREAMS 

If  modularity  and  portability  are  part  of  your  Unix 
problems,  Streams  may  be  part  of  the  solution 

by  Michael  W.  Garwood  and 
Andrew  E.  Schweig 


Not  long  ago,  in  an  effort  to  over¬ 
come  some  of  the  shortcomings 
associated  with  traditional  Unix 
mechanisms  for  dealing  with  character- 
based  I/O  systems,  a  new  framework 
called  Streams  was  introduced  and  imple¬ 
mented  for  Unix  System  V,  Release  3. 
This  Streams  framework  incorporates 
several  design  strengths  that  are  impor¬ 
tant  to  the  development  of  efficient, 
portable  network  protocols  for  the  Unix 
system. 

Streams  is  a  framework  that  provides 
for  a  full-duplex  data  connection  be¬ 
tween  a  user  process  and  a  device  or 
pseudodevice.  This  connection,  termed 
a  stream ,  is  composed  of  a  module 
stack  with  which  communication 
among  neighboring  modules  on  the 
stack  is  achieved  by  passing  messages 
through  a  well-defined,  intermodule 
interface.  (Throughout  this  article,  the 
terms  module  and  driver  are  used  in¬ 
terchangeably;  however,  device  driver 
refers  to  the  software  used  to  directly 
control  a  particular  hardware  device 
or  pseudodevice.)  Messages  are  passed 
“downstream”  on  the  write  half  of  the 
stream  toward  the  device  driver  and 
“upstream”  on  the  read  half  of  the  stream 
toward  the  stream  head  or  user  proc¬ 
ess.  A  module  passes  messages  to  a 
neighboring  module  by  calling  the  neigh¬ 
bor  module’s  put  procedure.  Once  a 
message  is  received  by  a  module,  it 
may  either  be  passed  to  a  neighboring 
stream  module  or  be  enqueued  for  subse¬ 
quent  processing  by  the  module’s  serv¬ 
ice  procedure. 

A  simple  put  and  service  strategy  is 
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shown  in  Example  1,  page  53.  The  put 
procedure  ( modput ): 

1 .  Processes  all  IOCTL  messages  imme¬ 
diately 

2.  Enqueues  all  messages  of  type 
M_DATA 

3.  Passes  all  other  messages  downstream 

The  service  procedure  (  modsrv)  proc¬ 
esses  as  much  locally  enqueued  data 
as  possible  until  the  downstream  queues 
fill  up.  At  that  point  the  dequeued  mes¬ 
sage  is  reenqueued  via  putbq  and  the 
service  procedure  returns.  The  flow- 
control  mechanisms  of  Streams  will  re¬ 
invoke  the  service  procedure  when  the 
downstream  blockage  has  subsided. 
Note  that  putq,  putnext,  getq,  canput , 
and  putbq  are  standard  Streams  utili¬ 
ties. 

Information  about  a  particular  mod¬ 
ule  is  included  in  a  pair  of  structures 
called  queues.  One  queue  describes 
the  write  half  of  the  module,  and  the 
other  describes  the  read  half  of  the 
module.  Information  kept  by  the  queue 
structures  contains,  among  other  things, 
pointers  to  module  entry  points,  state 
flags,  a  data  queue,  and  low  and  high 
watermarks  used  for  flow  control  on 
the  stream. 

Streams  Benefits 

The  Streams  design  provides  several 
advantages  over  the  traditional  Unix 
method  of  establishing  communication 
between  a  user  process  and  character- 
type  driver.  Most  notably,  it  enforces 
(or  at  least  strongly  encourages)  modu¬ 
larity  of  design.  It  is  certainly  possible 
to  write  a  module  that  does  not  con¬ 
form  to  the  standard  Streams  interface 
among  modules,  but  it  would  be  a  lot 
less  trouble  to  stay  within  the  Streams’ 
framework.  For  example,  we  developed 
a  raw  IP  driver  to  provide  a  TLI  inter¬ 
face  to  the  network-level  IP  driver  with¬ 


out  making  any  modifications  whatso¬ 
ever  to  the  network  driver.  In  this  way 
the  network  driver  can  multiplex  to 
other  drivers  (for  example,  TCP  and 
UDP)  without  the  overhead  imposed 
by  a  complex  user  interface. 

The  structure  imposed  by  this  frame¬ 
work  delivers  another  bonus:  portabil¬ 
ity.  Not  only  is  Streams  itself  reason¬ 
ably  portable  among  different  machine 
environments,  but  modules  that  coop¬ 
erate  with  the  communication  princi¬ 
ples  laid  down  by  the  Streams  frame¬ 
work  also  tend  to  be  fairly  portable. 

Streams  permits  logical  data  (mes¬ 
sages)  to  be  split  across  several  buffers. 
The  capability  to  efficiently  construct 
large  messages  from  several  smaller  com¬ 
ponents  proved  to  be  of  great  benefit 
in  the  design  of  the  data  reassembly 
portions  of  IP  and  TCP  drivers  we  de¬ 
veloped.  Data  can  also  be  efficiently 
duplicated  (shared)  without  being  cop¬ 
ied  in  the  Streams  environment.  This 
feature  allows  a  reliable  transmission 
protocol  (such  as  TCP)  to  send  data 
and  keep  a  “copy”  for  possible  retrans¬ 
mission  without  actually  copying  the 
data. 

Another  nicety  in  the  Streams  pack¬ 
age  is  the  clone  driver  feature.  This 
feature  makes  it  possible  to  open  a 
driver  in  “clone”  mode  and  have  the 
driver  itself  pick  an  available  minor 
device  number.  Gone  are  the  days  of 
a  user  process  sequencing  through  a 
long  line  of  major-minor  pairs  in  order 
to  locate  an  available  device.  The  bur¬ 
den  is  more  efficiently  handled  by  the 
kernel  driver  itself.  For  example,  we 
wrote  a  socket  interface  that  requires 
each  socket  endpoint  be  attached  to  a 
specific  protocol  device  major-minor 
pair.  Because  the  socket  creation  inter¬ 
face  does  not  require  an  argument  that 
would  specify  a  minor  device  number 
for  a  particular  protocol  driver,  it  would 
be  cumbersome  to  locate  an  available 
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minor  device  number  without  the 
Streams  clone  feature. 

The  use  of  this  clone  feature  is  dem¬ 
onstrated  by  the  Streams  driver  open 


routine  in  Example  2,  below.  If  the 
driver  open  flag  sflag  is  CLONEOPEN, 
denoting  a  clone  open,  the  driver  must 
allocate  and  return  an  unused  minor 
or  return  OPENFAIL.  A  “normal”  open 
should  check  to  see  if  the  minor  is 
already  in  use  and,  if  so,  should  make 
certain  that  the  queue  pointer  is  the 


/* 

*  module  put  procedure 
*7 

modput(q,  mp) 

queue_t  *q; 
mblk_t  *mp; 

switch (mp->b_datap->db_type)  { 

case  M_I0CTL : 

do_ioctl (mp) ; 
break; 

/*  process  IOCTLs  immediately  */ 

case  M_DATA: 

putq(q,  mp); 
break; 

/*  enqueue  for  service 

processing  */ 

default : 

putnext(q,  mp) ; 
break; 

} 

/*  pass  downstream  */ 

}  '  . 

/* 

*  module  service  procedure 

*7 

modsrv (q) 

queue_t  *q; 

mblk_t  *mp; 

while  (mp  “  getq ( ) ) 

if  (canput (q->q_next) ) 
transform (mp) ; 
putnext (q,  mp) ; 

f  else  { 

putbq(q,  mp) ; 
return; 

) 

) 

/*  dequeue  messages  */ 

{ 

/*  local  transformation 

of  data  */ 

Example  1:  A  Streams  module  put  and  service  procedure 


struct  queue_t  *drvqueue [MAXDEV] ; 

drvopen (q,  dev,  flag,  sflag) 
queue_t  *q; 
dev_t  dev; 

{ 

unsigned  int  mindev; 

char  error  =  0; 

if  (sflag  ==  CLONEOPEN)  { 

for  (mindev  =  0  ;  mindev  <  MAXDEV;  mindev++)  /*  allocate  dev  */ 
if  (drvqueue [mindev]  ==  NULL) 
break; 

if  (mindev  >=  MAXDEV) 

return (OPENFAIL) ; 

}  else  { 

mindev  =  minor (dev); 
if  (mindev  >=  MAXDEV) 
error  =  ENXIO; 

else 

if  (drvqueue [mindev]  && 

drvqueue [mindev]  !=  q)  /*  one  at  a  time  */ 

error  =  EBUSY;  /*  maybe  EAGAIN  */ 

) 

if  (error) 

u.u_error  =  error; 

else 

x  drvqueue (mindev]  =  q; 

return (mindev) ;  /*  return  minor  for  clone  driver  */ 

\ 


Example  2:  A  Streams  clone  device  driver  open  procedure 
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same  as  the  previous  open.  This  avoids 
a  small  window  in  the  current  Streams 
implementation. 

The  resource  allocation  scheme  used 
by  the  Streams  package  is  simple  and 
fast.  Because  the  resource  pools  (buff¬ 
ers,  queues,  message  headers,  and  so 
on)  are  statically  allocated,  freeing  or 
allocating  a  resource  is  as  simple  as 
linking  or  unlinking  a  pointer  from  a 
free  list.  This  simplicity,  however,  does 
have  its  drawbacks,  as  we  will  discuss 
later. 

Streams  Caveats 

Despite  the  aforementioned  advantages 
of  Streams,  there  are  still  a  few  areas 
in  which  the  System  V,  Release  3, 


Not  only  is  Streams 
itself  reasonably 
portable  among 
different  machine 
environments  but 
modules  that  cooperate 
with  the  communication 
principles  laid  down  by 
the  Streams  framework 
also  tend  to  be  fairly 
portable 


Streams  implementation  requires  atten¬ 
tion.  The  relative  severity  of  any  of 
these  items  depends,  for  the  most  part, 
on  the  particular  system  being  imple¬ 
mented.  The  amount  of  memory  allo¬ 
cated  to  a  particular  Streams  resource 
pool  (that  is,  streams,  queues,  buffers, 
and  so  forth)  is  determined  by  various 
configuration  parameters.  No  dynamic 
capability  is  currently  built  into  Streams 
resource  management.  Once  you’ve  hit 
a  resource  limit,  you’ve  hit  it. 

One  twist  with  respect  to  resource 
management  concerns  data  buffer  allo¬ 
cation.  The  buffer  allocation  scheme 
utilized  by  Streams  divides  data  buffers 
into  nine,  different,  statically  config¬ 
ured  size  classes  (4,  16,  32,  64,  128, 
256,  512,  1,024,  and  4,096  bytes).  Al¬ 
though  the  Streams  allocation  algorithm 
tries  a  couple  of  different  classes  in  an 
attempt  to  satisfy  a  buffer  request,  this 
request  may  fail  even  when  the  buffer 
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pool  on  the  whole  N  is  relatively  un¬ 
derutilized  (for  example,  a  request  for 
a  buffer  in  class  N  may  fail  when  there 
is  a  large  number  of  buffers  available 


1  STR 

Send  IOCTL  message  on  stream 

1  LINK 

Link  two  streams 

1  UNLINK 

Unlink  streams  linked  via  1  LINK 

LPUSH 

Push  module  onto  stream  below  stream 
head 

1  POP 

Pop  top  module  from  stream 

1  LOOK 

Return  name  of  first  module  on  stream 

1  FIND 

Look  for  particular  module  on  stream 

: 

LSETSIG 

Arrange  for  asynchronous  stream  event 

notification 

LGETSIG 

Return  registry  of  asynchronous  events 
for  which  process  is  to  be  signaled 

1  PEEK 

Nonconsumptive  read  of  stream 

1  NREAD 

Return  size  of  first  stream  message 

1  FLUSH 

Send  flush  message  on  stream 

LSRDOPT 

Set  read  characteristics  of  the  stream 
head  read  queue 

':7: 

LGRDOPT 

Get  read  characteristics  of  the  stream 
head  read  queue 

1  SENDFD 

Pass  file  descriptor  through  stream 

LRECVFD 

Retrieve  and  set  up  previously  sent 
(LSENDFD)  file  descriptor 

LFDINSERT 

Pass  characteristic  of  one  stream  to  an¬ 
other  stream  (for  stream  pipe  creation) 

Table  1 :  Streams’ IOCTLs 


in  classes  other  than  N  or  N+l).  These 
allocation  failures  may  occur  quite  fre¬ 
quently  on  a  heavily  loaded  or  improp¬ 
erly  configured  system;  therefore,  the 
driver  must  at  all  times  be  prepared  for 
such  a  failure,  allowing  for  graceful 
recovery  of  the  device  or  system.  It 
may  be  the  case  that  the  processing 
module  is  in  a  state  whereby  it  can 
wait  synchronously  for  an  available 
buffer;  most  of  the  time,  however,  this 
is  not  the  case  as  a  module  has  no 
process  context  after  open  and  before 
close.  (Normal  character-based  drivers 
have  this  restriction  for  interrupt-side 
processing  only.)  This  Streams  design 
choice  prevents  service  routines  from 
running  as  independent  processes 
(which  would  allow  them  to  sleep  when¬ 
ever  necessary),  makes  performance 
measurements  difficult,  and  makes  nec¬ 
essary  asynchronous  buffer  allocation 
recovery  measures. 

Streams  provides  a  mechanism  for 
asynchronous  recovery  from  buffer  al¬ 
location  failures.  The  driver  interface 
to  this  mechanism,  the  function  bufcall, 
schedules  an  event  to  notify  the  driver 
when  a  buffer  of  a  particular  size  be¬ 
comes  available.  At  least  three  prob¬ 
lems  can  occur  here.  First  of  all,  this 
notification  is  not  a  guarantee  that  the 
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awaited  buffer  will  be  obtainable  by 
the  driver;  thus,  the  driver  must  be 
prepared  for  another  allocation  failure. 
Second,  bufcall  may  fail  because  the 
event  structures  that  it  uses  are  also 
statically  allocated  and  can  be  depleted 
at  times  of  heavy  load.  Finally,  the  buffer 
may  become  available  and  the  event 
may  be  triggered  too  late,  forcing  the 
driver  to  take  (sometimes  complicated) 
actions  to  avoid  potential  problems. 

We  have  attempted  to  get  around 
some  of  the  buffer  allocation  short¬ 
comings  by  building  our  own  alloca¬ 
tion  routine  around  the  Streams  buffer 
allocator,  allocb.  This  new  allocator  tries 
a  little  harder  than  allocb  by  waiting  for 
buffers  requested  at  low  priority  and/ 
or  attempting  to  cut  and  paste  together 
buffers  from  different-size  classes  to 
fulfill  the  size  requested.  In  the  cases 
in  which  bufcall  is  required  after  an 
allocation  failure,  we  check  the  validity 
of  the  function  argument  supplied  by 
the  buffer  event.  In  the  event  that  bufcall 
should  fail,  we  use  timeout.  Example 
3,  this  page,  is  a  routine  that  tries  very 
hard  to  pass  a  buffer  to  its  neighbor. 
Note  that  the  buffer  may  or  may  not 
have  actually  been  sent  upon  return  to 
the  original  caller. 

Each  open  driver  has  an  associated 
pair  of  queues  (one  for  read,  one  for 
write)  that  contains,  among  other  things, 
low  and  high  watermarks  that  are  used 
to  control  the  flow  from  neighboring 
modules.  Although  these  may  be  use¬ 
ful  quantities  to  dynamically  configure, 
Streams  does  not  provide  an  adminis¬ 
trative  interface  that  would  support  this 
easily.  Although  Streams  does  define  a 
special  message  type  ( M_SETOPTS)  to 
allow  a  Streams  module  to  set 
streamhead  read  queue  parameters,  no 
method  is  provided  for  setting  parame¬ 
ters  of  other  queues.  We  got  around 
this  problem  to  a  certain  extent  by  pro¬ 
viding  each  one  of  our  drivers  with  an 
IOCTL  that  sets  the  low  and  high  wa¬ 


termarks  for  the  various  queues  associ¬ 
ated  with  the  driver. 

The  driver  queues  also  contain  infor¬ 
mation  about  the  module  entry  points 
and  data  service  routines.  As  such,  these 
queues  are  important  in  scheduling  the 
module  to  run.  These  queues,  how¬ 
ever,  are  deallocated  unconditionally 
when  the  module  is  closed.  Drivers 
such  as  TCP  that  still  have  processing 
to  do  after  the  close  returns  to  the  user 
process  can  no  longer  be  scheduled 
using  the  ordinary  queue-scheduling 
mechanism.  We  overcame  this  prob¬ 
lem  by  using  our  own  built-in,  queue- 
independent  scheduler  after  the  TCP 
queues  were  deallocated.  An  alterna¬ 
tive  may  have  been  to  allocate  a  new 
pair  of  queues  before  the  original  pair 
were  deallocated,  although  this  alloca¬ 
tion  may  fail  because  of  static  alloca¬ 
tion  problems  discussed  previously. 

The  Streams  message  architecture  that 
allows  data  to  be  shared  among  multi¬ 
ple  messages  also  gives  rise  to  a  minor 
inconvenience.  Given  a  reference  into 
the  data  portion  of  a  buffer,  it  is  diffi¬ 
cult  to  find  a  reference  back  to  the 
buffer  header  itself.  Our  fragment  reas¬ 
sembly  code,  for  instance,  uses  fields 
within  the  IP  header  itself  to  sequence 
incoming  packet  fragments  properly; 
however,  when  the  time  comes  for  the 
assembled  packet  to  be  passed  up¬ 
stream,  it  is  necessary  to  find  the  corre¬ 
sponding  buffer  header.  We  have  cir¬ 
cumvented  this  problem  by  temporar¬ 
ily  overlaying  the  header  pointer  onto 
the  IP  header  itself. 

Streams  Impact  on 
High-Level  Services 

For  the  most  part,  Streams  should  be 
relatively  transparent  to  a  typical  user 
program  or  high-level  application;  how¬ 
ever,  there  are  a  couple  of  new  features 
that  are  visible  at  the  user  level.  First 
of  all,  there  are  new  system  calls  ( getmsg 
and  putmsg)  that  can  be  used  in  addi¬ 
tion  to  read  and  write  to  read  and  write 
a  stream  endpoint.  These  new  system 
calls  enable  a  user  process  to  receive 
and  send  packetized  control  and  nor¬ 
mal  stream  data.  A  poll  system  call. 


similar  to  the  Berkeley  select  call,  per¬ 
mits  a  user  process  to  monitor  several 
stream  endpoints  for  various  events, 
including  data  arrival  and  departure. 
Streams  also  provides  several  useful 
IOCTLs,  which,  among  other  things  as¬ 
sist  in  stream  administration,  access  con¬ 
trol,  and  interprocess  communication. - 
A  summary  of  these  IOCTLs  is  given 
in  Table  1,  page  56. 

The  mechanics  for  sending  an  IOCTL 
are  slightly  different  for  a  Streams  de¬ 
vice  than  for  a  “normal,”  character- 
based  device  driver.  An  IOCTL  on  a 
non-Streams  device  is  fairly  simple: 

ioctl(fd,  IOCFOO,  &arg); 

For  a  Streams  device,  issuance  of  the 
IOCTL  requires  more  preparation: 

struct  strioctl  strioc; 

strioc.ic_cmd  =  IOCFOO; 
strioc. ic_timout  =  -1;  /*  seconds, 

-1  ==  forever  */ 
strioc.  icjen  =  sizeof(arg); 
strioc. io_dp  =  (char  *)  &arg; 
ioctl(fd,  I_STR,  &strioc); 


Conclusion 

Despite  any  limitations  that  may  exist 
in  its  current  implementation  under  Unix 
System  V,  Release  3,  Streams  has  clearly 
been  demonstrated  as  a  practical  frame¬ 
work  for  networking.  The  general  prem¬ 
ise  around  which  Streams  is  based  is  a 
sound  one;  the  problems  that  arise  in 
using  the  framework  are  more  related 
to  correctable  defects  in  implementation 
than  to  any  flaws  in  the  main  structure 
itself.  As  a  relatively  new  technology, 
Streams  will  certainly  be  improved 
through  new  advances  by  AT&T  and 
other  Streams  implementors. 
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Vote  for  your  favorite  feature/article. 

Circle  Reader  Service  No.  3. 


sendbuf (q) 

queue_t  *q; 

{ 

mblk_t  *bp; 


if  (!(bp  =  alloc (BUFSIZE,  BPRIJ4ED)))  { 

if  ( ! bufcall (B0FSIZE,  BPRI_MED,  sendbuf,  q) ) 

timeout (sendbuf ,  q,  HZ);  /*  if  all  else  fails  */ 

return (0) ; 

} 

putnextlq,  bp); 
return (1) ; 


Example  3:  Usage  of  bufcall 
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ARTICLES 


Comparing  Modula-2  and  C++ 

These  two  languages  have  a  lot  in  common  — but 
how  they’re  different  is  what  really  matters 


Two  of  the  hottest  languages  these 
days  are  Modula-2  and  C++.  They 
appeared  in  the  early  1980s,  and 
both  are  gaining  in  popularity.  Each 
was  designed  and  written  by  a  single 
person:  Niklaus  Wirth  created  Modula- 
2,  and  C++  was  developed  by  Bjarne 
Stroustrup.  An  additional  similarity  is 
that  both  languages  are  extended  ver¬ 
sions  of  earlier  languages.  This  article 
contrasts  Modula-2  and  C++;  it  assumes 
you  have  a  cursory  familiarity  with  both 
Pascal  and  C  (the  root  languages  of 
Modula-2  and  C++,  respectively). 

Modula-2  Background 

Pascal  was  designed  as  a  teaching  lan¬ 
guage,  to  show  students  how  to  struc¬ 
ture  programs  properly.  It  lacks  intrin¬ 
sic  support  for  character  strings,  file 
I/O,  and  separately  compiled  modules. 
Pascal  has  many  features  that  are  use¬ 
ful  in  software  development,  and  the 
language  gradually  gained  popularity 
outside  the  academic  community.  Un¬ 
fortunately,  the  vendors  that  imple¬ 
mented  Pascal  did  not  develop  a  stan¬ 
dard  for  extending  the  language  to  cover 
its  weak  points.  Thus,  every  Pascal  com¬ 
piler  is  unique,  and  porting  programs 
between  implementations  is  difficult. 

Wirth  intended  Modula-2  to  be  the 
successor  to  Pascal.  Modula-2’s  name 
implies  one  of  its  basic  concepts:  modu¬ 
lar  program  design.  Through  the  use 
of  modular  facilities,  Modula-2  supports 
data  abstraction  and  encapsulation.  All 
I/O  is  done  through  procedures  in  mod¬ 
ules  as  an  aid  to  portability.  As  long  as 
the  interface  to  the  I/O  procedures  does 
not  change,  the  implementation  of  those 
procedures  can  be  modified  for  differ¬ 
ent  environments  without  having  to 
make  alterations  in  the  programs  using 
them. 


Scott  Ladd  is  a  full-time  freelance  com¬ 
puter  journalist.  You  can  reach  him 
at  P.O.  Box  61425,  Denver,  CO  80206. 


by  Scott  Robert  Ladd 

Among  high-level  languages,  only 
Modula-2  and  Ada  support  multiproc¬ 
essing.  In  addition,  Modula-2  supports 
bit  manipulation,  generic  types,  and 
system-level  access.  Modula-2  (unlike 
Pascal)  is  well  suited  to  the  writing  of 
system  software  such  as  operating  sys¬ 
tems  and  device  drivers. 

C+  +  Background 

C  is  a  powerful  system-level  language; 
in  its  original  definition,  however,  it 
lacked  many  features  necessary  for 
large,  complex  projects.  Stroustrup  de¬ 
signed  C++  to  amend  problems  with 
the  C  language,  in  much  the  same  way 
as  Wirth  designed  Modula-2  to  correct 
the  deficiencies  of  Pascal.  C++  pro¬ 
vides  capabilities  for  strong  type  check¬ 
ing,  modular  programming,  and  data 
abstraction  while  maintaining  full  com¬ 
patibility  with  existing  C  programs. 

Stroustrup  borrowed  the  object-ori¬ 
ented  paradigm  from  Smalltalk;  classes 
and  methods  are  the  most  significant 
additions  he  added  to  C  in  creating 
C++.  In  an  object-oriented  language, 
objects  (data  items)  belong  to  classes 
(types),  which  have  associated  meth¬ 
ods  (functions).  “Messages”  are  sent 
to  objects  via  their  class  methods;  the 
messages  tell  the  objects  how  to  act. 
For  example,  an  object  of  class  int 
would  be  given  the  message  “add  1” 
by  the  ++  (increment)  method.  Although 
this  concept  can  take  some  getting  used 
to,  it  can  be  more  appropriate  than 
traditional  program  design  methods. 

C++  is  often  implemented  as  a  trans¬ 
lator.  The  C++  translator  works  much 
like  the  standard  C  preprocessor,  con¬ 
verting  C++  programs  into  C  programs. 
A  C  compiler  is  then  run  on  the  output 
of  the  translator,  producing  executable 
code.  By  its  nature,  this  process  is  cum¬ 
bersome  and  slow.  Recently,  manufac¬ 
turers  have  released  true  C++  com¬ 
pilers. 

In  addition  to  adding  object-oriented 


capabilities  to  C,  C++  offers  other  en¬ 
hancements,  including  in-line  functions, 
function  prototyping  (since  added  to 
the  ANSI  standard),  and  overloading. 
Because  it  retains  all  C’s  low-level  fa¬ 
cilities,  C++  can  be  used  for  a  wide 
variety  of  applications. 

General  Language  Features 

Modula-2  and  C++  have  the  following 
general  features: 

•  Source  code  format  — Source  code 
is  case  sensitive  in  C++  and  Modula-2. 
All  C++’s  keywords  must  be  in  lower¬ 
case;  Modula-2  requires  uppercase. 

•  Data  types  — Both  languages  are  rich 
in  data  types  and  allow  the  creation  of 
new  types.  They  offer  long  and  short, 
signed  and  unsigned,  integers  and  re¬ 
als.  Strings  in  both  languages  are  han¬ 
dled  as  arrays  of  characters  terminated 
by  a  zero  (NUL)  byte.  Both  languages 
have  pointer  types.  C++  provides  the 
capability  to  smoothly  integrate  new 
types  through  its  class  structure,  while 
Modula-2  provides  generic  types  and 
better  control  over  data  item  visibility. 
Modula-2  provides  SET  types  (includ¬ 
ing  BITSET,  which  allows  access  to  the 
individual  bits  of  an  item),  whereas 
C++  has  C’s  bit  structures. 

•  Functions  and  procedures  — Modu¬ 
la-2  has  procedures,  whereas  C++  has 
functions.  The  purpose  is  the  same  in 
both  languages:  to  provide  callable  rou¬ 
tines  with  parameters  and  local  vari¬ 
ables.  Modula-2  allows  the  nesting  of 
procedures  within  procedures,  using 
the  same  scoping  rules  as  it  does  for 
variables.  Modula-2  and  C++  parame¬ 
ters  can  be  passed  either  by  reference 
or  by  value. 

•  Control  structures  — Here,  too,  there 
are  no  important  differences.  Although 
the  syntax  may  vary,  the  capability  is 
the  same.  Both  languages  have  loops 
with  tests  at  both  the  top  and  the  bot¬ 
tom  of  the  loop.  The  for,  which  iterates 
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through  a  succession  of  values,  is  avail¬ 
able  in  both  languages.  There  is  (of 
course)  the  ubiquitous  if .  else  .  .endif 
conditional  construct.  Useful  multiple- 
condition  branches  ( switch  in  C++  and 
CASE  in  Modula-2)  are  available. 

•  Library  routines  — C++  uses  the  stan¬ 
dard  C  library,  which  is  extensive  and 
robust.  Wirth  defined  several  standard 
modules  in  his  definition  of  Modula-2, 
but  these  provided  only  minimal  capa¬ 
bilities.  Most  Modula-2  vendors  have 
created  expanded  libraries  for  their  im¬ 
plementations. 

Unique  Features  of  Modula-2 

Modula-2  is  not  a  superset  of  Pascal; 
rather,  it  is  an  evolution  of  the  earlier 
language.  For  example,  one  of  Modu¬ 
lar’s  most  welcome  enhancements  over 
Pascal  is  its  simplified  block  structure. 
A  Modula-2  program  is  not  filled  with 
BEGIN. .  .END pairs;  each  control  struc¬ 
ture  has  an  implicit  block  terminated 
by  an  END  statement.  Where  Pascal 
has  functions  and  procedures  (the  for¬ 
mer  returns  a  value  whereas  the  later 
does  not),  Modula-2  simply  has  proce¬ 
dures.  A  Modula-2  procedure  returns 
a  value  if  it  is  specified  as  doing  so. 

One  fascinating  feature  of  Modula-2 
is  its  support  for  coroutines,  which  are 
individual  processes  within  a  program 
that  run  concurrently.  This  allows  mul¬ 
tiple  tasks  (within  a  program)  to  be 
performed  simultaneously.  A  word  proc¬ 
essor,  for  example,  could  use  corouti¬ 
nes  to  allow  a  document  to  be  printed 
while  another  is  being  edited. 

The  strong  type  checking  in  Pascal 
prevents  spurious  errors  but  also  causes 
difficulties.  For  instance,  it  is  impossi¬ 
ble  to  create  a  general  function  in  stan¬ 
dard  Pascal  that  can  accept  arrays  (such 
as  character  strings)  of  different  sizes. 
Modula-2  introduces  the  concept  of  the 
open  array  parameter — for  example, 
a  parameter  to  a  procedure  can  be  de¬ 
clared  as  an  array  without  bounds  ( ar¬ 
ray  of  char).  Any  length  array  of  the 
specified  type  (in  this  case,  a  character 
array)  can  be  passed  to  that  function. 
The  procedure  can  then  find  out  the 
actual  length  of  the  array  with  the  built- 
in  HIGH  procedure. 

Modula-2  also  provides  the  generic 
type.  A  WORD  type  is  equal  in  size  to 
the  default  word  size  of  the  hardware 
it  is  running  on.  In  the  case  of  MS-DOS, 
a  WORD  type  is  16  bits  long.  Any  type 
of  the  same  size  (usually  the  INTEGER 
and  CARDINAL  types)  is  assignment 
compatible  with  WORD.  An  extension 
of  this  is  that  any  value  can  be  passed 
to  an  open  array  of  type  WORD  (that 
is,  a  procedure  parameter  of  type  AR¬ 
RAY  OF  WORD).  The  size  of  the  array 
is  the  number  of  WORD  types  required 
to  hold  the  value  being  passed. 
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The  concept  of  modules  allows 
Modula-2  programmers  to  control  ac¬ 
cess  to  individually  compiled  portions 
of  a  program.  The  following  object- 
oriented  example  illustrates  how  mod¬ 
ules  can  be  used. 


Unique  Features  of  C++ 

C++  refines  and  expands  C  while  in¬ 
cluding  all  C’s  strengths.  Several  fea¬ 
tures  of  the  emerging  ANSI  C  standard 
are  actually  borrowed  from  C++.  Ex¬ 
amples  of  this  are  function  prototypes, 
const ,  and  void.  Function  prototypes 
were  added  so  that  C++  could  do  type 
checking  or  arguments;  under  the  origi¬ 
nal  K&R  C,  values  of  incorrect  types 
could  be  passed  to  functions,  often 
causing  obscure  errors.  Const  provides 
named  constants.  Adding  fold  allowed 
the  creation  of  generic  pointers  and 
made  it  possible  to  declare  that  a  func¬ 
tion  does  not  return  a  value. 

Overloading  functions  lets  the  pro¬ 
grammers  create  several  functions  with 
the  same  name  but  differentiated  by 
their  parameters.  Instead  of  C’s  current 
crop  of  absolute  value  functions  ( abs , 
dabs,  f abs ,  and  labs),  a  C++  implemen¬ 
tation  could  have  the  following: 


overload 

int 

long 

float 

double 


abs; 

abs(int  i); 
absOong  1); 
abs(float  0; 
abs(double  d); 


At  compile  time,  the  C++  compiler  de¬ 
termines  which  version  of  abs  to  use 
based  on  the  parameters  it  is  being 
passed.  This  facility  can  make  programs 
easier  to  understand. 

It  is  possible  to  overload  operators 
in  C++.  You  can,  for  instance,  create  a 
new  class  that  can  use  the  same  opera¬ 
tors  as  existing  classes.  The  section  on 
object-oriented  programming  later  in 
this  article  contains  an  example  of  op¬ 
erator  overloading. 

The  object-oriented  features  of  C++ 
are  prominent.  Object-oriented  program¬ 
ming  requires  a  change  in  thinking  for 
many  programmers;  instead  of  think¬ 
ing  in  terms  of  the  nuts  and  bolts  of 
programming,  programmers  are  re¬ 
quired  to  visualize  a  program  as  a  se¬ 
ries  of  processes  applied  to  data  items. 
This  may  seem  to  be  a  subtle  distinc¬ 
tion,  but  it  must  be  mastered  to  truly 
appreciate  and  use  an  object-oriented 
language.  The  object-oriented  features 
of  C++  are  illustrated  in  the  section  on 


the  subject  in  this  article. 

C++  provides  dozens  of  other  exten¬ 
sions  to  C,  including  in-line  functions, 
anonymous  (unnamed)  unions,  and  de¬ 
fault  function  parameter  values.  There 


are  dangers  to  the  many  features  pro¬ 
vided  by  C++.  Whereas  C  has  always 
been  famous  for  providing  the  rope 
by  which  programmers  hang  their  pro¬ 
grams,  C++  adds  the  noose.  Care  must 


A  class  in  C++ 
looks  like  a 
structure;  in  fact, 
a  structure  is  a 
special 
form  of  class 


be  taken  to  avoid  “going  wild,”  espe¬ 
cially  with  the  overload  capabilities. 

An  Object-Oriented  Example 

An  object-oriented  language  is  extensi¬ 
ble,  which  means  the  programmer  can 
create  new  data  objects  that  are  inte¬ 
grated  into  a  program.  In  order  to  show 
how  each  language  is  used  to  create  a 
new  class  of  objects,  I  have  implemented 
complex  numbers  in  each  language. 
Complex  numbers  are  a  superset  of  the 
real  numbers,  having  both  a  real  and 
an  imaginary  part.  Complex  numbers 
are  used  in  a  number  of  scientific  cal¬ 
culations;  this  is  one  reason  why  For¬ 
tran  directly  supports  complex  num¬ 
bers. 

Both  implementations  are  identical 
in  function.  First,  you  need  to  define 
the  data  elements  of  a  complex  num¬ 
ber.  In  this  case,  the  complex  number 
has  two  floating-point  components  for 
its  real  and  imaginary  parts.  Then,  you 
determine  what  operations  can  be  per¬ 
formed  on  complex  numbers.  In  the 
example,  the  allowed  operations  are 
assignments,  addition,  subtraction,  mul¬ 
tiplication,  division,  and  output.  I  used 
Zortech  C++,  Version  1.06,  and  JPI 
TopSpeed  Modula-2,  Version  1.11,  to 
develop  the  examples. 

In  C++,  a  class  is  generally  devel¬ 
oped  using  two  files.  A  header  file  con¬ 
tains  the  class  description,  and  a  source 
file  holds  the  actual  implementation. 
The  example  in  Listings  One  -  Three, 
page  102,  follows  this  form. 

A  class  in  C++  looks  like  a  structure; 
in  fact,  a  structure  is  a  special  form  of 
class.  Those  items  listed  in  the  private 
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section  cannot  be  accessed  outside  the 
class  definition.  Public  data  and  func¬ 
tions  are  available  for  use  outside  the 
class  scope.  The  example  has  only  two 
private  items,  which  are  the  two  floating¬ 
point  components  of  a  complex  value. 
(See  Listings  Four  -  Six,  page  104.) 

A  “constructor”  in  C++  is  called  when¬ 
ever  an  object  of  the  class  is  created  to 
initialize  the  object.  The  counterpart 
of  a  constructor  is  a  “destructor,”  which 
can  be  used  to  deallocate  any  resources 
used  by  an  object  (once  that  object  is 
no  longer  needed).  The  example  does 
not  require  or  implement  a  destructor. 

Function  overloading  is  used  to  pro¬ 
vide  several  different  constructors.  Each 
constructor  allows  an  object  of  class 
complex  to  be  declared  with  different 
initialization  values.  The  type  and  num¬ 
ber  of  the  initializers  determines  which 
constmctor  is  used.  The  following  code 
fragment  shows  how  C++  determines 
which  constructor  to  use: 

complex  a;  /*  no  values;  uese  1st 
constmctor  */ 

complex  b(2. 0,5.0);  /*  two  real 

values;  uses  3rd  constmctor  V 

complex  c(b);  /*  complex  value;  uses 
2nd  constmctor  V 

Note  that  the  first  constmctor  is  de¬ 
fined  in  the  class  definition;  there  is 
no  external  function  for  it.  This  con¬ 
stmctor  is  compiled  into  in-line  code, 
avoiding  the  overhead  of  a  function 
call  when  declaring  complex  values 
without  initializers. 

Modula-2  does  not  support  a  spe¬ 
cific  class  structure,  but  the  same  effect 
can  be  created  through  the  use  of  mod¬ 
ules.  Modula-2  uses  two  files  to  create 
modules  called  the  definition  and  im¬ 
plementation  modules.  The  definition 
module  defines  the  interface  to  the  data 
elements  and  procedures  stored  in  the 
implementation.  Unless  it  is  defined  in 
the  definition  module,  an  item  is  pri¬ 
vate  to  the  implementation. 

In  order  to  prevent  programmers  from 
manipulating  the  component  values  of 
a  complex  item  directly,  an  “opaque 
type”  is  used.  The  definition  module 
lists  the  type  COMPLEX  (allowing  pro¬ 
grams  to  create  items  of  that  type)  but 


does  not  expose  the  type’s  internal  struc¬ 
ture.  Because  Modula-2’s  opaque  types 
must  be  pointers,  the  implementation 
module  defines  the  COMPLEX  type  as 
a  pointer  to  a  structure  containing  two 
real  values.  The  situation  requires  the 
functions  Create  and  Destroy  in  order 
to  allocate  and  deallocate  space  for  the 
complex  numbers.  These  are  similar 
to  C++  constructors  and  destructors, 
but  they  must  be  called  explicitly  by 
the  program. 

Modula-2  does  not  support  overload¬ 
ing,  so  there  is  no  way  to  assign  func¬ 
tions  to  infix  operators.  C++  allows  func¬ 
tions  to  be  assigned  to  operators,  so  in 
C++  it  is  possible  to  say: 

a  =  b  +  (c  *  d); 

Modula-2  requires  a  less  readable  con¬ 
struct: 

Multiply(templ,c,d); 

Add(a,b, tempi); 

The  process  is  identical;  both  languages 
use  functions  to  simulate  operators.  The 
primary  difference  is  that  C++’s  nota¬ 
tion  is  more  natural,  making  it  easier 
for  programmers  to  discern  what  is  hap¬ 
pening.  Although  the  results  are  the 
same,  most  programmers  would  prefer 
the  clarity  of  the  C++  version. 

Both  implementations  provide  a  func¬ 
tion  for  displaying  the  value  of  com¬ 
plex  number.  The  Modula-2  version 
uses  a  procedure  that  calls  upon  stan¬ 
dard  library  procedures.  In  the  C++ 
version,  a  function  is  declared  that  ac¬ 
cesses  the  stream  output  functions  of 
C++.  The  stream  class  is  provided  with 
C++.  The  «  (left  shift)  operator  has 
been  overloaded  in  C++  to  say  “send 
the  object  on  the  right  to  the  object  on 
the  left.”  Streams  can  be  easier  to  use 
for  simple  output  than  library  function 
calls.  Complex  numbers  are  displayed 
using  built-in  stream  output  functions 
for  characters,  strings,  and  floating¬ 
point  numbers. 

C++  offers  other  object-oriented  fea¬ 
tures  not  shown  in  the  example.  New 
classes  can  be  "derived”  from  other, 
pre-existing  classes,  and  characteristics 
can  then  be  “inherited”  from  the  origi¬ 
nal  class. 

Implementations 

C++  and  Modula-2  are  young  languages. 
Modula-2  has  been  more  widely  imple¬ 
mented;  on  the  other  hand,  it  has  had 
slightly  longer  to  get  into  the  main¬ 
stream.  C++  is  just  beginning  to  come 
into  its  own  outside  the  Unix/AT&T 
environment.  Currently,  half  a  dozen 
Modula-2  compilers  are  available  for 
the  PC,  whereas  three  C++  preproces¬ 
sors  and  one  C++  compiler  are  avail¬ 


able.  In  the  Macintosh  world,  Apple 
has  announced  that  it  will  extend  its  C 
compiler  to  be  a  C++,  and  there  are  at 
least  two  Macintosh  Modula-2  com¬ 
pilers. 

The  situation  is  similar  when  it  comes 
to  third-party  add-on  libraries.  I  know 
of  only  one  company  that  provides 
object  libraries  for  C++.  There  are  a  few 
companies  that  market  products  for 
Modula-2.  Recently,  several  vendors  of 
C  libraries  have  begun  to  market  Modu- 
la2  versions  of  their  products.  As  the 
popularity  of  these  products  grows,  so 
will  the  third-party  support. 

Conclusion 

Modula-2  and  C++  are  powerful  lan¬ 
guages;  both  have  bright  futures.  C++’s 
classes,  methods,  and  overloading  make 
it  a  powerful  tool,  but  it  has  few  re¬ 
straints  to  keep  programmers  from  be¬ 
ing  too  “creative.”  Modula-2  is  a  strongly 
organized  language  with  restraints  to 
keep  programmers  within  guidelines. 
It  is  not  as  extensible  as  C++,  but  it 
does  implement  its  own  unique  fea¬ 
tures,  such  as  SETs,  coroutines,  and 
open  arrays.  Which  of  these  languages 
is  more  appropriate  for  a  specific  pro¬ 
ject  will  depend  on  the  type  of  applica¬ 
tion  and  the  experience  of  the  pro¬ 
grammers  involved.  Both  languages  are 
powerful  and  interesting  to  work  with. 
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REVIEW 


MS-DOS 

Assemblers  Compared 

Today’s  feature-rich  assemblers  make  life  on  the 
assembly  line  a  lot  more  pleasant 


I’ll  admit  it.  I  am  biased  about  lan¬ 
guages;  I  write  almost  all  of  my 
code  in  assembly  language.  I  do 
this  for  several  reasons,  but  mostly  I 
do  it  because  the  resultant  code  is  both 
compact  and  fast.  In  this  article,  how¬ 
ever,  I  avoid  a  debate  over  the  merits 
of  assembly  language  versus  those  of 
the  various  high-level  languages.  Rather, 
I  explore  the  choices  you  have  after 
you’ve  already  made  the  decision  to 
program  in  assembly. 

Programmers  who  are  more  familiar 
with  high-level  languages  may  be  sur¬ 
prised  to  find  out  that  modern  assem¬ 
bly  languages  include  an  equally  rich 
set  of  features.  These  often  include  pow¬ 
erful  macros,  data  structures,  defined 
procedures,  dynamic  stack  variables, 
several  memory  models,  floating  point 
support,  and  a  host  of  conditional  as¬ 
sembly  directives. 

But  to  most  programmers  it  isn’t  a 
matter  of  whether  it  can  be  done,  but 
how  easy  it  is  to  accomplish  the  end 
result.  For  years  I  have  contended  that 
assembly  language  need  not  be  as  tedi¬ 
ous  and  difficult  to  learn  as  a  typical 
bit-banger  might  lead  you  to  believe. 
Today’s  crop  of  assemblers  have  lent 
much  support  to  this  contention.  New 
products  from  Borland  International  and 
SLR  Systems,  and  new  versions  from 
Microsoft,  have  gone  far  toward  mak¬ 
ing  assembly  language  programming 
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more  approachable,  and  the  time  spent 
doing  it  more  productive. 

This  article  compares  three  MS-DOS 
assemblers:  Microsoft’s  Macro  Assem¬ 
bler  51  (MASM),  Borland’s  Turbo  As¬ 
sembler  1.0  (TASM),  and  SLR  System’s 
OPTASM  1.5.  MASM  is  a  well-estab¬ 
lished  standard  that  others  must  be  meas¬ 
ured  against,  the  baseline  against  which 
others  should  be  compared.  In  recog¬ 
nition  of  this  fact,  it’s  important  to  note 
that  both  OPTASM  and  TASM  claim 
almost  100  percent  compatibility  with 
Microsoft’s  MASM. 

I  will  assume  some  familiarity  with 
MASM,  and  will  not  dwell  too  long  on 
assembly  language  itself.  Rather  I’ll  con¬ 
centrate  on  the  differences  between 
the  assemblers,  the  performance  of  the 
assembler,  and  the  enhancements  of¬ 
fered  in  OPTASM  and  TASM. 

Even  though  all  three  assemblers  can 
translate  the  same  source  files,  their 
internal  workings  are  radically  differ¬ 
ent.  MASM  is  a  conventional  two-pass 
assembler,  and  TASM  performs  only 
one  pass  and  then  fixes  forward  refer¬ 
ences.  OPTASM,  on  the  other  hand,  is 
an  n-pass  assembler,  performing  as 
many  passes  as  required  to  eliminate 
phase  errors  and  extraneous  NOPs. 

Let’s  look  at  each  separately. 

MASM 

Because  of  what  might  be  best  de¬ 
scribed  as  the  least-common-denomi¬ 
nator  effect,  most  magazine  articles  have 
standardized  on  MASM  4.0  for  example 
code.  With  no  serious  competition,  Mi¬ 
crosoft  has,  until  recently,  been  slow 
to  add  features  and  increased  power 


to  MASM.  But  now  that’s  changed.  With 
the  5.x  series  Microsoft  has  added  a 
number  of  nice  features.  For  example, 
it  added  a  simplified  system  for  declar¬ 
ing  segments  that  works  for  stand¬ 
alone  assembly  language  programs  and 
for  interfacing  to  high-level  languages. 
Other  enhancements  include  better 
performance,  automatic  allocation  for 
stack  variables,  local  and  global  labels, 
continuation  lines,  OS/2  support  and 
an  HLL-like  interface  for  Basic,  C,  For¬ 
tran,  and  Pascal. 

A  number  of  problems  arise  natu¬ 
rally  because  of  the  way  that  different 
languages  pass  arguments  on  the  stack. 
MASM  handles  all  of  this  automatically, 
but  there  is  no  easy  way  to  allow  for 
an  assembly  language  routine  to  do 
this,  unless  the  FILL  model  is  dupli¬ 
cated  exactly.  It  should  be  noted,  how¬ 
ever,  that  argument  passing  conven¬ 
tion  problems  are  not  unique  to  MASM, 
because  the  calling  conventions  are  de¬ 
fined  by  the  HLL. 

The  reason  for  this  is  that  some  in¬ 
structions  have  a  variable  number  of 
bytes,  such  as  the  JMP  instructions.  A 
JMP  can  have  a  displacement  of  1,  2, 
or  4  bytes  corresponding  to  destination 
labels  that  are  SHORT,  NEAR,  or  FAR. 
It’s  even  more  complicated  for  a  large 
segment  on  the  80386,  because  a  NEAR 
label  can  have  a  4-byte  offset  and  a 
FAR  label  can  have  a  6-byte  offset. 

This  design  was  apparently  modeled 
after  the  original  8086  assembler  (In¬ 
tel’s  ASM-86),  which  assumes  the  most 
likely  size  for  the  operand  (2  bytes).  If 
only  1  byte  is  needed,  then  a  NOP  is 
filled  into  the  other  byte.  If  more  than 
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2  bytes  are  needed,  then  an  error  is 
generated.  ASM-86  keeps  track  of  every 
assumption,  however,  and  generates 
an  error  message  corresponding  to  the 
exact  instruction  that  is  in  error.  The 
MASM  designers  took  a  shortcut  and 
the  assumptions  are  checked  only  indi¬ 
rectly  by  ensuring  that  labels  have  the 
same  offset  on  each  pass.  If  they  don’t, 
MASM  generates  the  message  “Phase 
error  between  passes.” 

This  message  has  ended  the  assem¬ 
bly  language  programming  careers  of 
many  programmers.  The  instruction 
with  the  bad  assumption  can  be  any¬ 
where  between  the  instruction  where 
the  message  was  generated  and  the 
previous  label.  This  could  be  one  in¬ 
struction  or  a  thousand.  (You  can  ex¬ 
amine  a  pass-one  listing  to  help  find 
the  problem,  but  if  you’re  experienced 
enough  to  know  about  pass-one  list¬ 
ings,  then  you  probably  don’t  need 
help  finding  the  problem.) 

The  manuals  that  come  with  MASM 
include,  among  others,  a  programmer’s 
guide,  a  guide  to  CodeView,  and  a  guide 
to  utilities.  But  the  one  that  I  use  most 
is  the  1 50-page  spiral-bound  reference 
guide.  This  guide  includes  a  list  of  every 
directive,  instruction,  and  math  co¬ 
processor  instruction;  it  also  includes 


syntax,  timings,  brief  explanations,  flags 
affected,  and  more.  The  programmer’s 
guide  is  quite  an  improvement  over  the 
version  4.0  manual  in  that  there  are 
examples  on  most  every  directive  and 
instruction.  There  are  also  a  numerical 
error  message  listing  and  an  excellent 
index. 

MASM  5.1  comes  with  a  number  of 
utilities,  including  the  Microsoft  Linker, 
Librarian,  Cross-Reference  utility,  and 
Make  utility.  New  with  5.1  is  the  Micro¬ 
soft  Editor,  a  programmer’s  editor  that 


allows  compiling  (or  assembling)  from 
the  editor.  One  major  feature  of  MASM 
is  a  BIND  utility,  which  allows  the  crea¬ 
tion  of  a  program  that  runs  under  DOS 
or  OS/2. 

TASM 

TASM  was  originally  designed  for  in¬ 
ternal  use  only,  providing  Borland  with 
a  competitive  advantage.  Many  of  the 
familiar  Borland  products  made  heavy 
use  of  TASM,  including  Turbo  Pascal 
and  Quattro.  Perhaps  because  of  its 
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roots,  the  Turbo  Assembler  is  a  depar¬ 
ture  from  Borland’s  standard  language 
product  strategy;  it  is  not  an  integrated 
environment  like  the  familiar  Turbo  Pas¬ 
cal  or  Turbo  C.  Rather  it  is  a  stand¬ 
alone,  command  line  program  like 
MASM  or  OPTASM. 

TASM  is  a  single-pass  assembler  with 
forward  reference  resolution  (which  ac¬ 
counts  for  much  of  its  speed  advantage 
over  MASM)  and  a  number  of  enhance¬ 
ments  that  exceed  the  capabilities  of 
MASM.  In  fact,  TASM  (and  OPTASM) 
both  claim  to  be  more  compatible  with 
MASM  than  MASM  is,  based  on  the  fact 
that  they  support  previous  versions  of 
MASM.  This  is  important  if  you  are 
supporting  older  code  or  frequently 
use  code  from  magazines,  bulletin 
boards,  or  the  like. 

TASM  handles  forward  references  in 
roughly  the  same  way  as  MASM,  but 
with  better  error  reporting  for  refer¬ 
ences  that  cannot  be  resolved.  The  man¬ 
ual,  however,  admits  that  “The  truth 
of  the  matter  is  that  all  sorts  of  forward 
references  can  cause  problems  for 
Turbo  Assembler,  so  you  should  avoid 
forward  references  — that  is,  references 


to  labels  farther  on  in  the  code  — when¬ 
ever  possible.”  (According  to  Borland, 
however,  forward  references  in  TASM 
only  cause  probems  when  the  program¬ 
mer  makes  explicit  use  of  the  two-pass 
nature  of  MASM.ed.) 


Unfortunately  there  are 
still  a  number  of 
problems  with  MASM 
due  to  the  quirky  way 
that  different  languages 
pass  arguments  on  the 
stack 


One  nuisance  that  a  programmer 
must  deal  with  when  writing  code  for 
the  Intel  processors  is  that  conditional 
jumps  have  only  a  1-byte  displacement 
(+127  or  -128  bytes).  (Note:  the  80386 
has  a  2-byte  displacement,  but  most 
code  is  still  written  for  DOS  [8086]  or 
OS/2  [80286].) 

This  means  that  MASM  programmers 
get  a  lot  of  “relative  jump  out  of  range” 
error  messages.  If  you  can’t  adjust  your 


design,  then  you  must  opt  for  the  inele¬ 
gant  5-byte  sequence  (see  Figure  1, 
page  71),  which  consists  of  two  jumps. 
Every  veteran  MASM  programmer  has 
done  this  hundreds  of  times.  TASM  has 
a  new  JUMPS  directive  that,  in  most  cases, 
automatically  handles  this  situation. 

One  of  the  most  notable  features  of 
TASM  is  that  it  has  two  modes:  MASM 
and  Ideal.  The  MASM  mode  can  also 
be  MASM51,  which  then  allows  some 
of  the  new  features  in  MASM  5.1.  Based 
on  the  names  you  can  guess  which 
mode  the  Borland  programmers  con¬ 
sider  to  be  the  better  one. 

Ideal  mode,  as  defined  by  Borland, 
makes  the  expression  parser  accept  only 
a  more  rigid,  type-checked  syntax.  Ad¬ 
vantages  and  disadvantages  of  this  mode 
are  listed  in  Table  1,  page  78.  One  key 
feature  is  the  fact  that  the  same  source 
file  may  switch  back  and  forth  between 
MASM  and  Ideal  modes.  Borland  claims 
a  30  percent  speedup  when  using  the 
Ideal  mode.  I  believe  that  this  is  due 
to  the  fact  that  the  parser  can  isolate 
assembly  directives  and  addressing 
modes  more  quickly  in  the  Ideal  mode. 
Also  I  think  that  the  assembler  was 
written  for  Ideal  mode  and  MASM  com¬ 
patibility  was  added  later;  thus  MASM 
compatibility  was  not  part  of  the  pri- 
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mary  design  goal.  All  tests  were  run 
using  the  default  MASM  mode. 

One  of  the  key  features  of  Ideal  mode 
is  a  consistent  syntax  for  the  use  of 
directives,  such  as  the  declaration  of  a 
procedure.  The  Ideal  syntax  is: 


ENDP  Fund  ;  optional 

repeating  of  Fund 


Although  SLR  calls 
OPTASM  an  optimizing 
assembler  it  really  does 
not  do  optimization  in 
the  sense  that,  for 
example,  a  C  compiler 
does  optimizations. 


This  allows  a  faster  assembler,  and  the 
syntax  makes  sense  because  the  first 
token  on  the  line  always  defines  direc¬ 
tive  type,  unlike  the  MASM  syntax.  But 
you  could  make  an  equally  sensible 
argument  for  the  MASM  syntax.  The 
PROC  directive  defines  a  program  la¬ 
bel,  just  as  a  label  followed  by  a  colon 
does,  or  a  label  followed  by  a  DW 
defines  a  data  word.  It  would  make 
no  sense  to  reverse  the  order  of  these. 
Then  again,  the  MASM  syntax  for  the 
ENDP  doesn’t  fit  into  any  of  these  rules. 

Perhaps  the  biggest  difference  be¬ 
tween  MASM  and  Ideal  is  that  Ideal 
uses  square  brackets  ([  ])  in  expres¬ 
sions  as  shown  in  Figure  2,  page  76. 
In  Ideal  mode  you  use  square  brackets 
to  reference  memory.  This  is  easy  to 
remember  and  makes  a  lot  of  sense. 
(Ideal  mode  doesn’t  require  square  brack¬ 
ets,  but  it  will  warn  you  if  you  don’t  use 
them.  However,  this  warning  can  be 
disabled  with  the  NOWARN  direc¬ 
tive. ed.)  For  example,  in  MASM  you 
would  use: 

item_l  DW  10 

item_2  equ  20 

array  1  DB  256  dup(0) 

mov  ax,  item_l 

mov  dx,  item_2 

mov  cx,  31bx] 

mov  al,  array l[bx] 
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(continued  from  page  75) 


title  MASM  mode  example  program 
.model  small 

stdin  =  0 
stdout  =  1 
buf  len  =  128 


Without  the  data  declaration  and  equate 
in  clear  view,  it  is  difficult  to  tell  the 
difference  between  the  first  two  MOVs. 
There  are  times  when  you  may  not 


comment  in  title 


dosint  MACRO  function 
mov  ah,  function 
int  21h 
ENDM 


ax,  @data 
ds,  ax 
es,  ax 

dx,  OFFSET  inbuf 
bx,  stdin 
cx,  buf_len 


macro  to  invoke  a  DOS  interrupt  21h  function 


;  load  data  segment 


dest  for  input 
source  of  input 
len  for  input 


dosint 

.  3fh 

;  read  file 

cmp 

ax,  2 

jle 

fin 

mov 

bx,  ax 

mov 

inbuf [bx-2],  0 

;  null  at  end  (rem< 

mov 

cx,  ax 

;  len  for  example 

sub 

cx,  2 

;  removes  CR  LF 

call 

lower  line 

mov 

dx,  OFFSET  outbuf 

;  source  of  output 

mov 

bx,  stdout 

;  dest  for  output 

dosint 

4  Oh 

;  write  file 

dosint 

4ch 

;  exit  to  DOS 

lower_line  PROC  near 
push  cx 

mov  si,  OFFSET  inbuf 

xor  di,  di 

cld 
loopl : 
lodsb 

or  al,  20h 

mov  outbuf[di],  al 

inc  di 

loop  loopl 

pop  cx 

ret 

lower  line  ENDP 


inbuf  DB  buf_len  DUP(?) 
outbuf  DB  buf_len  DUP(?) 

stk  SEGMENT  STACK 
db  100  dup(0) 
stk  ENDS 


;  for  example  no  STOS  for  DI 


read  a  char 
convert  to  lower  case 
store  in  outbuf 

loop  til  end  of  string 


;  reserve  space  for  stack 
;  using  old  segment  method 


specify  starting  address 


IDEAL 

%title  "TASM  IDEAL  mode  example  program"  ;  comment  not  in  title 
;  all  directives  affecting  listing 
;  file  begin  with  a  percent  sign  (%) 


stdin  =  0 
stdout  =  1 
buf_len  =  128 

MACRO  dosint  function 
mov  ah,  function 
int  21h 
ENDM 


mov  ax,  @data 

mov  ds ,  ax 

mov  es,  ax 

mov  dx,  OFFSET  inbuf 
mov  bx,  stdin 

mov  cx,  buf_len 

dosint  3fh 
cmp  ax,  2 

jle  fin 

mov  bx,  ax 

mov  [bx+inbuf-2] ,  0 
mov  cx,  ax 

sub  cx,  2 

call  lower_line 
mov  dx,  OFFSET  outbuf 

mov  bx,  stdout 

dosint  4 Oh 
fin: 

dosint  4ch 


;  no  periods  in  Ideal  directives 


;  label  and  MACRO  reversed 


segmentation  directive  renamed 
label  and  PROC  reversed 


memory  reference  must  be  in  [] 
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struct  that  is  legal  but  does  not  get  the 
intended  results.  MASM  veterans  may 
have  a  hard  time  accepting  the  Ideal 
mode.  Beginners  will  probably  learn 
assembly  language  quicker. 

There  are  about  25  differences  be¬ 
tween  the  Ideal  and  MASM  modes  (see 
Table  2,  page  80).  The  manual  gives  a 
description  and  an  example  of  each 
difference  covering  about  30  pages  in 
all. 

There  is  an  additional  submode  called 
Quirks  (see  Table  3,  page  83),  which, 
according  to  the  manual,  “allows  you 
to  assemble  a  source  file  that  makes 
use  of  one  of  the  true  MASM  bugs.” 
Although  this  statement  is  a  shot  at 
Microsoft,  more  important  is  the  fact 
that  it  refers  to  enabling  several  well- 
documented  features  that  Borland  was 
apparently  reluctant  to  include.  The 
Manual  lists  three  main  quirks: 

1.  Local  labels  are  defined  with  @@  and 
referred  to  with  @F  and  @B. 

2.  There  is  a  redefinition  of  variables 
inside  PROCs. 

3.  C  language  PROCs  are  all  PUBLIC 
with  leading  underscores. 


Description 

Directives  that  begin  with  a 
period  have  been  renamed 

Examples 

.model  small 
code 

;  MASM 

Comments 

model  small 
codeseg 

;  TASM  Ideal 

Directives  such  as  PROC, 

ENDP,  SEGMENT,  and 

ENDS  are  reversed 

funcl  PROC  near 
PROC  fund  near 

;  MASM 
;TASM  Ideal 

-  Causes  all  directives  to  be 
the  first  token  except  data 
declarations,  EQUs,  and  =s 

Square  brackets  [  ]  required 
for  memory  references 

mov  ax,  varl 
mov  cl,  array1[bx] 
mov  ax,  [varl] 
mov  cl,  [bx+arrayl] 

;  MASM 

;  TASM  Ideal 

-  In  some  instances  this 
removes  ambiguity,  but  also 
prevents  writing  code  that 
looks  like  an  HLL  array  index 

Structure  fields  are  not 
global 

mov  ax,  [bx].field_1 

;  MASM 

-  Allows  the  re-use  of 
structure  field  names 

;  TASM  Ideal 

mov  cx,  [(struc_a  PTR  BX)].field_1] 

-  Allows  UNIONS  (two 

STRUC’s  for  the  same  data 
items) 

-  Messy  notation  when  you  want 
to  overlay  a  structure  onto  data 
not  explicitly  declared,  (i.e.  data 
allocated  from  DOS) 

EQUs  are  always  text  based 
(MASM  does  not  handle 

EQUs  and  =s  in  a 
consistent  manner) 

A  =  1 

B  =  2 

CEQUA  +  B 

B  =  3 
var  DW  C 

;  MASM  =  3 
;TASM  Ideal  =  4 

-  Fixes  an  inconsistency  in 

MASM 

SIZE  returns  actual  size  of 
first  item  in  a  list 

msgl  DB  message  1’,  0 
len  DB  SIZE  msgl  ;  MASM  =  1 

;TASM  Ideal  =  9 

-  Makes  the  SIZE  operator 
much  more  useful 

Floating  point  constants  must 
include  a  decimal  point  to 
prevent  ambiguous  values 

numl  DT  1E7  ;  in  MASM  could 

;  be  a  radix  16  value 
num2  DT  1 .0e7  ;  required  for 

;  TASM  Ideal 

-  Prevents  confusion  if  you 
useradix  1 6  in  programs 
using  floating  point 

Table  1:  Highlights  of  Turbo  Assembler’s  MASM  and  Ideal  Modes 
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I  agree  that  the  first  Quirk  is  a  quirk. 
In  my  opinion,  MASM’s  implementa¬ 
tion  of  local  labels  is  brain  damaged 
(both  TASM  and  OPTASM  have  differ¬ 
ent  implementations).  I  believe  that  the 
last  two  quirks  are  actually  a  benefit  for 
anyone  writing  HLL  utilities  in  assem¬ 
bly  language.  The  second  quirk  allows 
you  to  use  the  same  names  for  argu¬ 
ments  being  passed  from  an  HLL.  The 
third  quirk  is  that  all  PROCs  are  de¬ 
clared  public.  When  MASM51  is  turned 
on  and  the  C  language  is  specified  as 


part  of  the  .MODEL  statement,  leading 
underscores  are  appended.  This  serves 
a  quirk  of  the  C  language  itself  that 
requires  that  functions  have  a  hidden 
leading  underscore  in  the  public  name 
passed  to  the  linker.  (See  Figure  3, 
page  84.) 

The  Turbo  Assembler  documenta¬ 
tion  includes  a  580-page  user’s  guide 
and  a  300-page  reference  guide.  The 
user’s  guide  includes  a  200-page  tuto¬ 
rial  that  is  one  of  the  best  beginner’s 
guides  to  the  Intel  architecture  that  I 
have  read.  There  are  also  chapters  on 
the  specifics  of  interfacing  with  the  other 
Borland  languages:  Turbo  C,  Turbo  Ba¬ 


sic,  Turbo  Pascal,  and  Turbo  Prolog. 
Much  of  this  information  is  common 
with  other  languages. 

The  reference  guide  is  primarily  a 
description  of  all  the  directives  and 
operators.  Each  directive  and  operator 
is  marked  as  to  which  modes  (MASM 
or  Ideal)  it  is  .available  in  and  any  dif¬ 
ferences  in  syntax.  But  it  is  not  possible 
to  tell  what  MASM  mode  syntax  is  a 
super  set  of  Microsoft’s  MASM.  In  other 
words,  it  is  possible  to  write  code  in 
Turbo  Assembler’s  MASM  mode  that 
will  not  assemble  with  MASM,  and  the 
manual  does  not  readily  note  the  dif¬ 
ferences.  This  is  not  a  major  concern  if 
you  are  planning  on  using  TASM  ex¬ 
clusively,  but  would  be  a  problem  if 
you  are  sharing  code  with  other  pro¬ 
grammers  not  using  TASM. 

Turbo  Assembler  comes  with  a  num¬ 
ber  of  additional  programs.  One  pro¬ 
gram  is  the  Debugger.  Turbo  Debugger 
is  a  source-level  debugger  that  sup¬ 
ports  debugging  from  a  remote  system 
and  has  multiple  windows,  menus,  on¬ 
line  help,  and  virtual  8086  debugging 
on  an  80386  system.  It  is  a  significant 
product  in  its  own  right;  any  further 
discussion  is  beyond  the  scope  of  this 
article. 

Turbo  Assembler  also  provides  a  util¬ 
ity  that  allows  source  debugging  of 
files  linked  for  CodeView  debugging. 
Additional  utilities  include  Turbo  Linker, 
Turbo  Librarian,  TCREF  (a  cross-refer¬ 
ence  utility),  and  MAKE.  The  Turbo 
Linker  is  not  a  complete  replacement 
for  the  Microsoft  Linker.  The  manual 
states,  “TLINK  is  lean  and  mean; ...  it 
lacks  some  of  the  bells  and  whistles  of 
other  linkers.” 

OPTASM 

OPTASM,  by  SLR  Systems,  is  a  high- 
performance  optimizing  assembler  that 
is  nearly  100  percent  compatible  with 
MASM.  OPTASM  supports  incompa¬ 
tibilities  between  MASM,  Versions  3, 
4,  and  5.  OPTASM  is  the  clear  winner 
in  terms  of  performance  and  code  size, 
but,  as  is  always  the  case,  has  some 
limitations. 

These  limitations  are  either  minimal 
or  severe,  depending  upon  your  needs. 
For  example,  OPTASM  does  not  sup¬ 
port  80386  instructions,  nor  does  it  sup¬ 
port  some  of  the  MASM  features  gained 
in  the  jump  from  version  5.0  to  5.1.  An¬ 
other  downfall  is  that  no  linker  is  pro¬ 
vided.  Although  MASM  doesn’t  provide 
a  linker  either,  the  high  performance 
of  OPTASM  leads  you  to  expect  that  it 
will.  (Note:  OPTASM,  Version  1.6,  which 
will  be  released  this  month  includes  a 
linker  and  debugger.  No  changes  have 
been  made  to  the  assembler.)  But  then 
after  assembling  at  lightning  speed,  you 
must  wait  for  the  Microsoft  Linker.  This 


Features  comparison 


MASM  5.1 

OPTASM 

TASM 

MASM  3.x  compatible 

X 

MASM  4.x  compatible 

X 

X 

MASM  5.x  compatible 

X 

1 

X 

80286  code 

X 

X 

X 

80287  code 

X 

X 

X 

80386  code 

X 

X 

80387  code 

X 

X 

8087  emulation 

X 

X 

Expand  conditional  jumps  >  128  bytes 

X 

X 

away  by  adding  an  extra  jump 

Expand  LOOP'S  >  128  bytes  away  by 

X 

adding  two  additional  jumps 

Remove  extra  NOPs 

X 

Eliminates  phase  errors 

X 

Externals  can  include  size  info 

X 

Global  symbols  (combines  Public/Extrn) 

2 

X 

UNION  directive  (nested  STRUC's) 

X 

Additional  modes 

3 

4 

Length  of  data  item 

5 

6 

Generation  of  Group  offsets7 

X 

X 

Local  labels 

8 

9 

10 

Multiple  PUSH  and  POP  pseudo-op 

X 

Short  Extrn  directives  (i.e.  EXTB) 

X 

Wildcard  filenames  on  cmd  line 

X 

Built-in  make 

X 

predefined  symbols 

X 

X 

time 

date 

X 

X 

filename 

X 

version 

X 

Notes: 

1)  OPTASM  supports  up  to  MASM  5.0  and  some  of  MASM  5.1  features. 

2)  OPTASM  has  a  Soft  Extrn  directive  that  allows  an  internal  definition  to  override  the 
Extrn. 

3)  OPTASM  has  about  40  features  that  can  be  individually  enabled  or  disabled  to 
override  the  normal  MASM  features. 

4)  TASM  defaults  to  MASM  4.0  and  has  directives  for  MASM  5.0,  MASM  5.1 ,  Quirks, 
and  an  Ideal  mode  (see  text). 

5)  OPTASM  has  an  option  to  allow  the  LENGTH  operator  to  return  the  total  length  of 
all  items  defined  for  a  given  label. 

6)  In  Ideal  mode  the  SIZE  operator  returns  the  total  size  for  the  first  data  item  in  a  data 
list. 

7)  When  using  the  SEG  operator  and  the  OFFSET  operator,  MASM  can  generate 
incorrect  addresses  when  using  simplified  segmentation. 

8)  MASM  allows  local  labels  to  be  defined  as  which  can  then  be  referenced  as 
@F  (forward  to  next  @@:)  or  @B  (backwards  to  previous  @@:)-  In  additional,  when 
using  an  HLL  model  all  labels  are  local,  unless  defined  with  two  colons. 

9)  OPTASM  allows  local  labels  by  prefixing  any  label  with  a  #  sign  or  suffixing  it  with  a 
dollar  ($)  sign. 

10)  TASM  allows  local  labels  by  prefixing  with  two  @  signs  (@@). 


Table  2:  TASM  operating  modes  and  quirks 
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TASM  Operating  Modes 

a)  Normal  MASM 

Emulates  MASM  4.0,  5.0  without  minor  quirks. 

b)  QUIRKS 

Emulates  MASM  4.0,  5.0  with  minor  quirks  in  those  versions. 

c)  MASM51 

Emulates  those  features  of  MASM  5.1  that  conflict  with 

MASM  4.0  and  5.0  operation  but  do  not  conflict  with  the 
operation  of  Borland's  extensions  that  perform  the  similar 
functions. 

d)  MASM51  and  Quirks 

Emulates  MASM  5.1  fully. 

Quirks  as  explained  in  the  TASM  HELPMEI.DOC  disk  file 

Mode 

Operations 

Quirks 

Allows  FAR  jumps  to  be  generated  as  NEAR  or  SHORT  if 

CS  assumes  agree. 

Allows  all  instruction  sizes  to  be  determined  in  a  binary 
operation  solely  by  a  register,  if  present. 

Destroys  OFFSET,  segment  override,  etc.,  information  on 
v  or  numeric  'EQU'  assignments. 

Forces  EQU  assignments  to  expressions  with  "PTR”  or 
in  them  to  be  text. 

MASM51 

Instr,  Catstr,  Substr,  Sizestr,  and  T  line  continuation  are 
all  enabled. 

EQU's  to  keywords  are  made  TEXT  instead  of  ALIASes. 
Leading  whitespace  is  not  discarded  on  %textmacro  in 
macro  arguments. 

MASM51  and  Quirks 

Everything  listed  under  Quirks  above. 

Everything  listed  under  MASM51  above. 

@@,  <§>F,  and  @B  local  labels  are  enabled. 

Procedure  names  are  PUBLICed  automatically  in  extended 
MODELS. 

Near  labels  in  PROCs  are  redefinable  in  other  PROCs. 

operator  is  enabled  to  define  symbols  that  can  be 
reached  outside  of  current  proc. 

MASM51  and  Ideal 

Ideal  mode  syntax  and  the  MASM51  text  macro  directives 
are  supported,  i.e.,  Instr,  Catstr,  Substr,  and  Sizestr. 

Table  3:  Features  comparison 

is  like  using  a  20-MHz  80386  and  then 
shifting  to  a  4.77-MHz  PC. 

SLR  Systems  was  the  only  company 
willing  to  discuss  future  products  with 
me.  It  is  working  on  80386  support,  a 
linker,  and  full  compatible  MASM  5.1. 

As  mentioned  before,  OPTASM  is  an 
n-pass  assembler.  This  unique  design 
allows  OPTASM  to  perform  as  many 
passes  as  required  to  prevent  all  phase 
errors,  and  it  never  inserts  extra  NOPs 
into  your  code.  Although  SLR  calls  OP¬ 
TASM  an  optimizing  assembler,  it  re¬ 
ally  does  not  do  optimizations  in  the 
sense,  for  example,  that  a  C  compiler 
does  optimizations.  The  truth  is  that 
MASM  and  TASM  perform  wnoptimiza- 
tions  by  inserting  NOPs  where  the  pro¬ 
grammer  did  not  ask  for  them;  all  OP¬ 
TASM  does  in  the  way  of  optimizations 
is  not  to  make  this  mistake. 

OPTASM  also  contains  a  number  of 
extensions  to  the  basic  MASM  language. 
But  it’s  important  to  note  that  every 
feature  can  be  either  enabled  or  dis¬ 
abled. 

The  Make  capability  in  OPTASM  is 
not  really  a  Make  utility  in  the  tradi¬ 
tional  sense,  because  the  MAKE  rou¬ 
tines  are  built  into  the  assembler.  There 
are  both  advantages  and  disadvantages 


Old  method  (MASM  5.0  and  before) : 

Public 

sample  func 

sample  func  proc  near 

push 

bp 

mov 

bp,  sp 

push 

bx 

push 

cx 

push 

dx 

mov 

bx,  [bp+4]  ;  get 

ptr 

to  varl 

pop 

dx 

pop 

cx 

pop 

bx 

pop 

bp 

ret 

sample_func  endp 

New  method: 

.model 

small,  C 

.code 

sample 

func  proc  near  USES  BX 

CX 

DX,  varl: PTR 

mov 

bx,  varl  ;  get 

ptr 

to  varl 

ret 

sample 

_func  endp 

Figure  3'  New  MASM  to  C 
calling  interface 


to  this  approach.  You  can  still  use  your 
old  Make  in  the  same  way,  or  you  can 
use  your  old  Make  along  with  the  OP¬ 
TASM  Make. 

In  its  simplest  form  the  OPTASM 
Make  will  just  process  a  file  that  has  a 
list  of  filenames.  Actually  you  are  re¬ 
quired  to  enter  the  command  tail,  just 
as  it  would  appear  in  a  DOS  batch  file, 
minus  the  OPTASM  program  name.  The 
advantage  here  is  that  OPTASM  does 
not  need  to  be  reloaded  by  DOS  be¬ 
tween  each  file.  OPTASM  is  also  smart 
enough  to  keep  include  files  in  mem¬ 
ory,  if  possible.  Just  as  with  a  regular 
Make,  you  can  add  dependencies,  so 
that  files  are  assembled  only  if  they  are 
out  of  date. 

Version  1.0  of  OPTASM  came  with 
no  other  utilities,  but  version  1 .5  is  now 
shipped  with  a  unique  utility:  OPTHELP. 
This  is  a  memory-resident  utility  that 
provides  help  on  the  instruction  set 
and  OPTASM.  The  help  is  fairly  de¬ 
tailed,  including  bit  encodings  for  the 
various  instructions.  For  example,  the 
MOV  instruction  has  15  pages  of  help. 

OPTASM  does  not  come  with  a  li¬ 
brarian,  but  OPTLIB  is  available  sepa¬ 
rately.  OPTLIB  is  ten  times  faster  than 
the  Microsoft  Librarian. 

OPTASM  comes  with  one  320-page 
spiral-bound  manual.  The  manual  does 
not  include  a  tutorial,  but  is  a  complete 
description  of  the  language,  with  all 
features  unique  to  OPTASM  appearing 
in  boxes  marked  as  OPTASM  features. 
When  reading  about  any  feature,  there 
is  no  doubt  as  to  whether  the  exact 
syntax  is  also  available  in  MASM. 

Local  Labels 

Each  of  the  three  assemblers  imple¬ 
ments  local  labels  in  a  different  man¬ 
ner.  (See  Figure  4,  below.)  They  are  all 
incompatible  with  each  other.  In  other 
words,  if  you  write  a  program  that  uses 
any  of  the  methods  for  local  labels, 
then  the  other  assemblers  will  not  al¬ 
low  it.  The  only  exception  is  that  TASM 
will  accept  the  MASM  methods  if  you 
use  both  the  MASM  and  Quirks  direc¬ 
tives. 

Local  labels  are  a  new  feature  in 
MASM  5.1.  The  idea  is  simple:  you  de¬ 
fine  a  local  label  with  two  at  signs 
(@@)  followed  by  a  colon.  To  refer¬ 
ence  the  nearest  preceding  local  label, 
use  @B  (back);  to  reference  the  next 
local  label,  use  @F  (forward).  When 
writing  assembly  language  routines  for 
use  in  HLL  programs,  a  much  more 
structured  feature  is  enabled.  The  man¬ 
ual  describes  it  as  a  local  variable  scope 
when  you  use  the  extended  form  of  the 
.MODEL  directive.  Labels  ending  with 
a  single  colon  (and  procedure  argu¬ 
ments  passed  on  the  stack  and  local 
stack  variables)  are  considered  local 
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to  the  procedure  where  they  are  de¬ 
fined.  To  make  a  label  available  from 
another  procedure,  it  must  be  defined 
with  two  colons. 

This  is  an  excellent  feature  of  MASM, 
it  promotes  well-structured  code  and 
highlights  any  labels  that  are  used  ex¬ 
ternal  to  a  procedure.  The  bad  news  is 
that  you  must  be  using  the  extended 
form  of  the  .MODEL  directive,  which 
is  not  always  appropriate.  With  TASM, 
on  the  other  hand,  local  symbols  are 
available  whether  you  are  using  the 
extended  form  of  the  .MODEL  state¬ 
ment  or  not. 

As  stated  earlier,  TASM  can  emulate 
the  MASM  local  labels.  But  in  addition 
you  can  define  a  local  label  by  preced¬ 
ing  a  label  with  two  at  (@@)  signs.  The 
scope  of  these  local  labels  is  in  be¬ 
tween  any  two  regular  labels.  This  fea¬ 
ture  is  automatically  available  in  the 
Ideal  mode  and  can  be  enabled  in  the 
MASM  mode  with  the  Locals  directive. 
The  two  at  signs  can  be  replaced  with 
any  other  characters  that  can  start  a 
label  by  using  the  Locals  directive. 

OPTASM  1.5  does  not  support  the 
MASM  local  labels.  However,  OPTASM 
has  a  unique  feature  called  Procedure 
Local  Labels.  There  are  two  formats: 

#  n  label 

n  label  $ 

The  first  format  begins  with  a  #  sign 
and  is  followed  by  a  series  of  digits  (n) 
or  a  standard  label  (label).  The  second 
format  begins  with  a  series  of  digits 
(n),  is  optionally  followed  by  a  stan¬ 
dard  label  (label),  and  is  terminated 


;  MASM  example 

@0: 

inc 

ax 

cmp 

ax,  bx 

j® 

@f 

loop 

@b 

@0: 

ret 

;  TASM  example 

@@loop: 

inc 

ax 

cmp 

ax,  bx 

je 

@@exit 

loop 

@@loop 

@@exit : 

ret 

;  OPTASM 

example 

#1: 

inc 

ax 

cmp 

ax,  bx 

je 

#2 

loop 

#1 

#2: 

ret 

_ 

Figure  4:  Local  labels  examples 


by  a  dollar  sign  ($).  The  assembler 
ignores  the  #  and  $  characters  when 
evaluating  a  label,  and  thus  #10  and 
10$  are  considered  the  same.  All  these 
labels  are  automatically  local  only  to 
the  procedure  in  which  they  are  de¬ 
fined.  Therefore  the  same  labels  can 
be  reused  in  other  procedures. 

The  Results 

I  conducted  a  number  of  tests  on  all 
three  assemblers  on  several  machines, 
including  a  4.77-MHz  XT,  a  10-MHz 
AT,  and  a  16-MHz  80386.  The  results 
were  proportional  for  each  class  of  ma¬ 
chine,  and  so  were  based  only  on  the 
10-MHz  AT  clone  with  a  Seagate  ST- 
251  drive  (40  Mbyte,  38-ms  access  time). 

The  first  test  was  based  on  a  pro¬ 
gram  that  consisted  of  15  source  files, 
ranging  in  size  from  2K  to  100K,  to¬ 
taling  535K.  There  were  also  four  in¬ 
clude  files  totaling  16K.  Based  on  how 
many  times  the  include  files  were  read, 
the  assembler  had  to  read  more  than 
600K  of  source  to  build  the  object  files. 
All  times  were  in  seconds  and  did  not 
include  linking  or  generating  listing  files. 

The  second  set  of  tests  consisted  of 
assembling  six  100K  source  files.  The 
third  and  fourth  tests  used  the  unique 
features  of  TASM  and  OPTASM  to  ob¬ 
tain  more  speed.  These  tests  were  the 
same  as  the  first  two,  except  that  I  used 
TASM’s  wildcard  feature  and  OPTASM’s 
internal  make.  The  effect  was  that  both 
TASM  and  OPTASM  obtained  a  speed 
advantage,  because  reloading  the  as¬ 
sembler  between  files  was  not  required. 
See  Figure  3  for  the  test  results. 

Both  Borland’s  Turbo  Assembler  and 
SLR  System’s  OPTASM  provided  clear 
advantages  over  Microsoft’s  Macro  As¬ 
sembler.  The  TASM/Debugger  pack¬ 
age  seems  to  be  the  best  value,  but 
both  were  much  faster,  with  OPTASM 
clearly  the  fastest.  Plug  and  play,  OP¬ 
TASM  also  produced  the  most  compact 
code,  maybe  1  percent  smaller  than  the 
other.  While  this  is  significant,  view 


Figure  5:  Test  data 


these  results  in  context.  For  example, 
with  a  bit  of  additional  work,  compac¬ 
tion  could  have  been  improved  in  TASM 
through  the  use  of  overrides.  Likewise, 
using  a  different  linker,  like  Phoenix’s 
PLINK,  is  likely  to  shrink  code  size. 

Both  TASM  and  OPTASM  also  pro¬ 
vided  a  number  of  nice  extras,  such  as 
fixing  conditional  jumps  that  were  out 
of  range  by  putting  in  two  jumps.  OP¬ 
TASM  clearly  outperformed  TASM  based 
on  the  fact  that  it  never  inserted  extra 
NOPs  and  it  handled  all  combinations 
of  conditional  jumps  and  loops.  TASM, 
on  the  other  hand  (if  automatic  jump 
sizing  is  used  with  forward  references), 
automatically  assumed  that  the  jump 
is  going  to  be  far  and  reserved  5  bytes 
for  the  jump,  padding  the  code  with 
extra  NOPs. 

It  is  also  worth  nothing  that  both 
MASM  and  TASM  support  80386  code, 
as  will  OPTASM,  sometime  in  the  fu¬ 
ture,  and  for  the  present,  at  least,  MASM 
is  the  only  assembler  that  runs  in  OS/2 
protected  mode. 

Now  that  there  is  finally  some  com¬ 
petition  in  the  macro  assembler  mar¬ 
ket,  it’s  about  time  users  began  sending 
their  wish  lists  to  the  manufacturers. 
Keep  in  mind  that  a  job  is  only  as  easy 
as  the  tools  make  it. 

DDJ 


Vote  for  your  favorite  feature/article. 
Circle  Reader  Service  No.  8. 


Test  description 

MASM 

TASM 

OPTASM 

test 

1 

(15  files,  600K  total) 

85 

50 

35 

test 

2 

(6  files,  100K  each) 

80 

40 

26 

test 

3 

(test  1  with  wildcards/make) 

85 

34 

24 

test 

4 

(test  2  with  wildcards/make) 

80 

32 

22 

Notes : 

1)  Times  are  in  seconds 

2)  All  tests  on  10  MHz  AT  clone, 
zero  wait  states,  Seagate 
ST-251  hard  disk,  no  cache 

There  were  four  test  cases  run,  as  described  in  the  article. 
Each  test  consisted  of  just  three  data  points, 
one  for  each  of  the  assemblers. 
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NEURAL  NETWORKS 


Listing  One  (Text  begins  on  page  14.) 

♦include  <stdio.h> 

♦define  EXTERN  extern 
♦include  "neural. h" 

/*--  MAKE_MIND  - 

Constructs  a  mental  unit  with  the  given  number 
of  input,  hidden  and  output  neurons. 

- */ 

make_mind (in,  hid,  out) 
int  Tn; 
int  hid; 
int  out; 

{ 

if  (  in  >  MAX_NEURONS  | | 
hid  >  MAX_NEURONS  | j 
out  >  MAX_NEURONS  )  return (0); 
if  (in  <  1  ||  hid  <  1  ||  out  <  1  )  return(O); 
Mind.n_input  -  in; 

Mind.n_hidden  =  hid; 

Mind.n_output  =  out; 
set_cluster_fun (NULL,  NULL) ; 
set_all_weights (1.0); 
set_act_fun (pass) ; 
set_user_in_f un (prompted) ; 
set_result_fun (print_binary_state) ; 

strcpy (Prompt . string,  "Input  a  value  for  neuron  %d:  "); 
Prompt. count  =  1; 
return (1) ; 


/*—  ACTIVATE_MIND - 

Sets  a  mind  in  motion.  Sequentially  activating  each  neuron 

. - - - */ 

activate_mind() 

( 

int  i; 

float  net_input; 

/*  Activate  input  layer  */ 

Prompt. count  =  1; 

for  (i  =  0;  i  <  Mind.n_input;  i++) 

{ 

Mind. i_layer [i] .value  =  Mind.user_in_fun () ; 

} 

/*  Activate  hidden  layer  */ 

for  (i=  0;  i  <  Mind.n_hidden;  i++) 

{ 

net_input  =  weighted_sum(i,  HIDDEN); 

Mind.h_layer[i) .value  =  Mind. act_fun (net  input); 

) 

/*  Activate  feedback/certainty  function  (if  one  is  set)  */ 

if  (  Mind. certainty  !=  NULL)  Mind. cluster_fun (Mind. certainty) ; 

/*  Activate  output  layer  */ 

for  (i=0;  i  <  Mind.n_output;  i++) 

( 

net_input  =  weighted_sum (i,  OUTPUT); 

Mind.o_layer[i) .value  =  Mind.act_fun (net_input) ; 

Mind. result_fun (Mind.o_layer (ij .value) ; 

) 


/*—  SET_ALL_WEIGHTS - - - 

Sets  the  weight  of  all  connections  between  all  neurons 
in  all  layers  to  the  given  value 

- - - */ 

set_all_weights (value) 
float  value; 

( 

int  i,  j; 

/*  Weights  between  input  and  hidden  */ 

for(i  =0;  i  <  Mind.n_input;  i++) 

{ 

for(j  =0;  j  <  Mind.n_hidden;  j++) 

{ 

Input_to_hidden [i] [ j ] .weight  =  value; 

) 

1 

/*  Weights  between  hidden  and  output  */ 

for(i=0;  i<  Mind.n_hidden;  i++) 

( 

for(j  =0;  j  <  Mind.n_output;  j++) 

{ 

Hidden_to_output [ i ] [j] .weight  *  value; 

} 

) 


/* —  SET_WEIGHT  - 

Sets  the  weight  between  two  neurons  to  a  given  value. 

. - - - - —*/ 

set_weight (from,  to,  layer,  value) 

int  from; 

int  to; 

int  layer; 

float  value; 

{ 

switch  (layer) 

{ 

case  HIDDEN: 

if  (from  >  Mind.n_input)  return; 
if  (to  >  Mind.n_hidden)  return; 


Input_to_hidden [from] [to] .weight  =  value; 
break; 

case  OUTPUT: 

if  (from  >  Mind.n_hidden)  return; 
if  (to  >  Mind.n_output)  return; 

Hidden_to_output [from] [to] .weight  =  value; 
break; 
default : 
break; 

} 

return; 

} 

/*—  WEIGHT_SUM - 

Calculates  the  weighted  sum  for  a  given  neuron  in  a  given 
layer 

- */ 

float  weighted_sum(this_neuron,  this_layer) 
int  this_neuron; 
int  this_layer; 

{ 

int  i; 

float  sum  =  0.0; 

switch  (this_layer) 

{ 

case  HIDDEN: 

for  (i  =  0;  i  <  Mind. n_input;  i++) 

{ 

sum  +=  (Mind. i_layer [i] .value  *  Input_to_hidden [i] [this_neuron] . 

weight) ; 

) 

break; 

case  OUTPUT: 

for  (i  =0;  i  <  Mind.n_hidden;  i++) 

< 

sum  +=  (Mind.h_layer [i] .value  *  Hidden_to_output [i] [this_neuron] . 

weight) ; 

) 

break; 

default: 

break; 

} 

return  (sum); 

} 

/*—  PASS - 

Returns  the  input  value.  A  dummy  activation  function. 

- - - */ 

float  pass (value) 
float  value; 

( 

return  (value) ; 

) 

/*—  PROMPTED - 

Prompts  the  user  for  an  input  value  and  returns  the 
value.  A  user  input  function. 

- - - */ 

float  prompted () 

( 

float  value; 

printf (Prompt .string.  Prompt .count++) ; 
scanf("%f",  ivalue); 
return (value) ; 

) 

/*—  PRINT_BINARY_STATE - 

Prints  the  output  state  of  a  neuron.  If  greater  than 
0.0  the  value  printed  is  "on",  otherwise  "off". 

- */ 

float  print_binary_state (value) 
float  value; 

{ 

printf ("The  output  gate  is:  "); 

if  (value  >  0.0)  printf ("ON. ") ; 
else  printf ("OFF. ") ; 

printf ("\n") ; 

) 

End  Listing  One 

Listing  Two 

♦ifndef  _NEURAL_ 

♦define  _NERUAL_ 

♦define  MAX_NEURONS  35 

♦define  HIDDEN  1 
♦define  OUTPUT  2 

/*  Type  definition  for  neurons  and  neural  networks  */ 

typedef  struct  { 
float  value; 

}  NEURON; 

typedef  struct  { 
int  n_input; 
int  n_hidden; 
int  n_output; 
float  "certainty; 
float  (*cluster_fun) () ; 
float  (*act_fun) () ; 
float  (*user_in_fun) () ; 
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float  (‘result  fun)(); 

strcpy (Prompt . string,  "Logic  state  of  gate  %d:  "); 

NEURON  i  layer [MAX  NEURONS]; 

printf ("Logic  values:  1,  on;  0,  off\n\n"); 

NEURON  h  layer [MAX  NEURONS]; 

NEURON  o  layer [MAX  NEURONS]; 

printf ("OR  logic  gate.Xn"); 

}  MIND; 

printf  (" - \n\n") ; 

make  mind (2,  1,  1)  ; 

typedef  struct  { 

activate_mind ( ) ; 

float  weight; 

/*  AND  gates  must  have  weights  <1.0  (  and  >0.0)  */ 

)  WEIGHTS; 

typedef  struct 
{ 

printf ("\n") ; 

printf ("AND  logic  gate.Xn"); 

char  string [80]; 

printf  (" - \n\n") ; 

int  count; 

)  PROMPT; 

for(i  =0;  i  <  2;  i++) 

/*  Global  Variables  */ 

set_weight (i,  0,  HIDDEN,  0.5); 

EXTERN  MIND  Mind; 

activate  mind(); 

EXTERN  WEIGHTS  Input  to  hidden[MAX  NEURONS] [MAX  NEURONS); 

/*  XOR  gates  are  the  most  complicated  */ 

EXTERN  WEIGHTS  Hidden  to  output [MAX  NEURONS] [MAX  NEURONS]; 

EXTERN  PROMPT  Prompt; 

printf ("\n") ; 

/*  Functions  */ 

printf ("XOR  logic  gate.Xn"); 
printf  (" - \n\n") ; 

float  weighted  sum(); 

make  mind (2,  2,  1) ; 

float  pass(); 

set  weight (0,  0,  HIDDEN,  1.0); 

float  prompted (); 

set  weight (1,  0,  HIDDEN,  -1.0); 

float  print  binary  state(); 

set  weight (0,  1,  HIDDEN,  -1.0); 

float  certainty  fun(); 

set  weight (1,  1,  HIDDEN,  1.0); 

int  activate  mind(); 

set  weight (0,  0,  OUTPUT,  1.0); 

set  weight (1,  0,  OUTPUT,  1.0); 

/*  Pseudo-functions  */ 

set_act_fun (linear_threshold) ; 
activate  mind(); 

♦define  set  act  fun(f)  Mind. act  fun  =  f 

} 

♦define  set  user  in  fun(f)  Mind. user  in  fun  =  f 

♦define  set  back_prop  fun(f)  Mind.back_prop  fun  =  f 

/*—  LINEAR  THRESHOLD - 

♦define  set  result  fun(f)  Mind. result  fun  =  f 

If  the  input  value  is  greater  than  zero  then  it  returns 

♦define  set  cluster  fun(f,  x)  Mind. cluster  fun  =  f;  Mind. certainty 

1.0,  otherwise  it  returns  0.0.  A  linear  threshold 

=  X 

activation  function. 

- - - - - */ 

float  linear  threshold (value) 

♦endif 

End  Listing  Two 

float  value; 

{ 

if  (value  >  0.0)  return(l.O); 

Listing  Three 

else  return (0.0); 

1  End  Listing  Four 

/*  Linear  network  */ 

♦define  EXTERN 

Listing  Five 

♦include  "neural. h" 

♦define  MEMBERS  5 

Optical  Character  Recognition  (OCR)  neural  network 

This  is  a  hybrid  between  a  linear  threshold,  fully 

float  print  vote  state (); 

interconnected  network,  and  a  linear  network.  The 

♦define  plural (x)  (x  ==  1  ?  ""  ;  "s") 

transition  being  at  the  hidden  layer.  A  feedback  neuron 
guarantees  a  pattern  match  in  the  threshold  layer. 

main  () 

*/ 

{ 

♦include  <stdio.h> 

int  i; 

♦define  EXTERN 
♦include  "neural. h" 

make  mind (5, 1,1); 

set  result  fun (print  vote  state); 

float  per cep (); 

strcpy (Prompt. string,  "Ballot  for  member  %d:  "); 

float  print  ocr(); 

for  (i-0;  KMEMBERS;  i++) 

float  certainty_cluster () ; 

set  weight (i,  0,  HIDDEN,  (float)  (i+1)  ); 

float  Certainty; 

} 

FILE  *Ocr  fptr ; 

printf ("Ballot  values:  1  =  for,  0  =  obstain,  -1  =  against\n\n") ; 

activate  mind(); 

main(argc,  argv) 

) 

int  argc; 
char  *argv[]; 

float  print  vote  state (value) 

( 

float  value; 

int  i; 

int  votes; 

if (argc  <  2) 

printf ("The  vote  is:  "); 

( 

printf ("proper  usage:  ocr  [<train  file>  ...]  (-test  <test  file>  ...] 

votes  =  (int) value; 

\n") ; 

if  (votes  >  0) 

exit (-1) ; 

printf ("FOR,  by  %d  vote%s",  votes,  plural (votes)  ); 

) 

else  if  (votes  <  0) 

printf ("AGAINST,  by  %d  vote%s",  -votes,  plural (-votes)  ); 

make  mind(35,  3,  1); 

else 

set  user  in  fun(percep); 

printf ("A  TIE"); 

set_result  fun (print  ocr); 

set  cluster  fun (certainty  cluster,  SCertainty) ; 

printf (" .\n") ; 

set_all_weights (0.0) ; 

End  listing  Three 

/*  Teach  the  network  about  the  patterns  */ 
i  =  1; 

while (strcmp (argv [ i] ,  "-test")  !=  0) 

Listing  Four 

i 

printf ("Learning:  %s\n",  argv[i]); 
if(  i  >  Mind.n  hidden) 

/*  Simple  linear  threshold  network. 

{ 

Demonstrates  logic  gates  */ 

printf ("Too  many  pattern  groups  for  the  given  topology,  aborting. 

\n") ; 

♦define  EXTERN 

♦include  "neural. h" 

) 

ocr  learn (argv [i] ,  i  -  1); 

float  linear  threshold (); 

i++; 

if (i  >=  argc) 

main() 

{ 

( 

int  i; 

printf ("Nothing  to  test  -  exitingXn") ; 

exit (-1) ; 

/*  OR  gates  work  using  the  default  weights  (1.0)  */ 

) 
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/*  Classify  each  pattern  based  on  what  the  network  knows  */ 
i++;  /*  Skip  over  "-test"  deliniator  */ 

while  (i  <  argc) 

{ 

printf ("Testing  %s\n",  argv[i]); 

if  ( (Ocr_fptr  =  fopen (argv [i] ,  "r"))  ==  NULL) 

{ 

perror (argv[i] ) ; 

printf ("Unable  to  open  file,  skipping  pattern. \n") ; 
i++; 

continue; 

) 

activate_mind () ; 
f close (Ocr_fptr)  ; 
i++; 

} 

} 

/*--  PERCEP - 

Returns  the  value  of  the  next  pixel  every  time  its  called. 
The  pixel  state  is  determined  from  the  contents  of  the 
pre-opened  file  pointed  to  by  '  Ocr  fptr' . 

- */ 

float  percep( ) 

{ 

extern  FILE  *Ocr_fptr; 
int  pixel_value; 

fscanf (Ocr_fptr,  "%ld",  fipixel_value) ; 
return  (  ( float ) pixel_value) ; 


/*—  PRINT_OCR - 

Prints  the  character  which  the  network  determines 
it  to  be.  Also  prints  the  certainty  of  the  match. 

- - - */ 

float  print_ocr (value) 
float  value; 

{ 

extern  float  Certainty; 

printf ("The  character  is  '%c'  (%d).\n",  (int) value,  (int) value) ; 
printf ("with  a  certainty  of  %3.2f%.\n".  Certainty); 


/*--  OCRJLEARN  - 

Teach  the  network  how  to  classify 
a  pattern. 

. . - . . . */ 

ocr_learn (filename,  group_id) 
char  filename []; 
int  group_id; 

{ 

int  i; 

FILE  ‘fptr; 
int  pixel_cnt  =  0; 
int  pixel_value; 
float  dist_weight; 
float  output_value; 

if  ((fptr  =  fopen (filename,  "r") )  ==  NULL) 

{ 

perror (filename) ; 

printf ("Skipping  pattern. \n") ; 

return (0)  ; 

) 

/*  Determine  the  number  of  "on"  pixels,  hence  fractional  weight  */ 
for(i=0;  i  <  Mind.n_input;  i++) 

( 

fscanf (fptr,  "%ld",  &pixel_value) ; 
if (pixel_value  ==  1)  pixel_cnt++; 

) 

dist_weight  =  1 . 0/pixel_cnt; 
rewind (fptr) ; 

/*  Set  fractional  weight  for  each  "on"  connection  */ 
for(i=0;  i  <  Mind.n_input;  i++) 

{ 

fscanf (fptr,  "%ld",  &pixel_value) ; 

if (pixel_value  ==  1)  set_weight (i,  group_id,  HIDDEN,  dist_weight) ; 

) 

/*  Now  set  weight  for  output  value  for  this  character  */ 
fscanf (fptr,  "%f",  &output_value) ; 
set_weight (group_id,  0,  OUTPUT,  output_value) ; 


for(i=0;  i<Mind.n_hidden;  i++) 

( 

if (Mind.h_layer(i) .value  >  highest) 

{ 

closest  =  i; 

highest  =  Mind. h_layer [i] .value; 

} 

} 

if (closest  ==  -1)  /»  All  are  equally  likely  -  choose  the  first  */ 

{ 

closest  =  0; 

} 

‘certainty  =  Mind. h_layer [closest] .value  *  100.0; 

/* 

Cause  just  enough  feedback  to  the  neuron  which  is  closest 
to  being  "on"  so  that  it  is  "on".  That  is  set  it  "on" 

All  others  are  given  negative  feedback  to  force  them  to 
zero,  (set  them  to  zero) . 

*/ 

for(  i  =  0;  i  <  Mind.nhidden;  i++) 

{ 

if  (i  ==  closest)  Mind.h_layer[i] .value  =  1.0; 
else  Mind.h_layer [i] .value  =  0.0; 

} 

) 

End  listing  Five 


Listing  Six 


Board: 

board. c  (neural. h) 
neurlib.c  (neural. h) 

Logic: 

logic. c  (neural. h) 
neurlib.c  (neural. h) 

OCR: 

ocr.c  (neural. h) 
neurlib.c  (neural. h) 


End  Listings 


fclose (fptr) ; 
return  (1) ; 


/*—  CERTAINTY_CLUSTER - 

Performs  a  cluster  function.  It  inhibits  (sets  to  0)  all 
neurons  in  the  cluster  except  the  one  which  is  closest  to 
the  value  1.0.  This  neuron  is  set  to  1.0.  The  passed 
variable  is  assigned  the  certainty  to  which  the  closest 
neuron  felt  it  matched  the  pattern 

- */ 

float  certainty_cluster (certainty) 
float  ‘certainty; 

{ 

int  i  ; 

float  highest  =  0.0; 

int  closest  =  -1; 
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NOISE  FILTERING 


Listing  One  (Text  begins  on  page  32.) 

backprop.c  Back-propagation  XOR  example  */ 


♦include  <stdio.h> 


double  r; 

extern  int  rand(); 


/*  return  result  */ 

/*  random  number  generator  */ 


r  =  (rand()  /  32767.)  *  (high  -  low)  +  low; 
return (  r  ) ; 


Back-propagation  Exclusive  OR  Program 


Written  by  Casimir  C.  Klimasauskas .  No  copyright  or  other  proprietary 
rights  reserved. 

This  program  was  compiled  and  tested  using  DataLight  "C"  version  3.14 
as  follows: 

DLC  -ms  backprop.c 

NOTE:  the  structure  "_conn"  uses  an  index  for  the  PE  source.  This  was 
done  (rather  than  a  pointer  to  the  processing  element  itself)  to  get 
around  certain  problems  with  handling  circular  references  in  structure 
definitions . 


♦define  MAXCONN  5 


typedef  struct  _conn  { 

int  PESource; 

float  ConnWt; 

float  LastDelta; 

)  CONN; 


/*  maximum  number  of  conn  */ 


/*  connection  to  a  PE  */ 
/*  index  of  PE  source  */ 
/*  connection  Wt  */ 

/*  last  weight  change  */ 


RandWtsO  -  randomize  all  of  the  weights  in  a  network 


void  RandWts (  low,  high,  LLp  ) 

double  low,  high;  /*  low  /  high  limits  for  random  */ 

PE  ***LLp;  /*  layer  list  pointer  */ 

{ 

PE  **PePP;  /*  PE  Pointer  */ 

PE  *PeP;  /*  PE  itself  */ 

CONN  *WtP;  /*  connection  Pointer  */ 

for (  ;  (PePP  =  *LLp)  !-  (PE  **)0;  LLp++  )  /*  layer  loop  */ 

for  (  ;  (PeP  =  *PePP)  !=  (PE  *)0;  PePP++  )  /*  PE  loop  */ 

for(  WtP  =  &PeP->Conns [0] ;  WtP->PESource  !=  0;  WtP++  ) 

{ 

WtP->ConnWt  =  RRand(  low,  high  ); 

WtP->LastDelta  =  0.0; 

} 


typedef  struct  _pe  {  /*  processing  element  */ 

float  Output;  /*  PE  output  */ 

float  Error;  /*  Accumulated  error  */ 

CONN  Conns [MAXCONN+1] ;  /*  connections  */ 

)  PE; 


Recall  ()  -  Recall  information  from  the  network 


Network  Topology 


The  following  diagram  shows  how  the  processing  elements  have  been 
connected  to  solve  the  exclusive  "OR"  problem.  This  is  taken  from 
Volume  1  of  "Parallel  Distributed  Processing"  by  Rummelhart  and 
McClelland. 


- PE5 

/  I  \ 

/  I  \ 

— / - PE4  \ 

I  /  \  I 

I  /  \  I 

1/  \l 

PE2  PE3 


static  PE  pel  =  (  1.0,  0  );  /*  bi 

static  PE  pe2  =  (  0  );  /*  in 

static  PE  pe3  =  {  0  }; 

static  PE  pe4  =  {  0,  0,  1,0,0,  2,0,0,  3,0,0  }; 
static  PE  pe5  =  {  0,  0,  1,0,0,  2,0,0,  3,0,0, 


/*  bias  */ 

/*  inputs  */ 


3,0,0,  4,0,0  } ; 


/*  hidden  */ 
/*  output  */ 


/*  -  Processing  Elements  (for  reference  by  number)  -  */ 

static  PE  *PEList [ ]  =  {  (PE  *)0,  &pel,  &pe2,  &pe3,  &pe4,  &pe5  }; 

/*  -  Layer  definitions  -  */ 

static  PE  *LayIn[]  =  {  &pe2,  &pe3,  (PE  *)0  );  /*  input  layer  list  */ 

static  PE  *LayMid( ]  =  (  &pe4,  (PE  *)0  };  /*  hidden  layer  list  */ 

static  PE  * LayOut [ ]  -  (  &pe5,  (PE  *)0  };  /*  output  layer  list  */ 

/* - Network  List - */ 

static  PE  **LayList [ ]  =  {  &LayIn(0],  &LayMid[0],  &LayOut(0],  (PE  **)0  }; 


Sigmoid ()  -  Compute  the  sigmoid  of  a  value 


void  Recall (  ov,  iv,  LLp,  ref  ) 

double  *ov;  /*  output  vector  */ 

double  *iv;  /*  input  vector  */ 

PE  ***LLp;  /*  layer  list  pointer  */ 

int  ref;  /*  "recall"  mode  flag  (0=learn)  */ 

{ 

PE  **PePP;  /*  PE  Pointer  */ 

PE  **LastPP;  /*  last  non-zero  PE  list  pointer  */ 

PE  *PeP;  /*  PE  itself  */ 

CONN  *WtP;  /*  connection  Pointer  */ 

double  sum;  /*  weighted  sum  */ 

/*  copy  the  input  vector  to  the  inputs  of  the  network  */ 
for (  PePP  =  *LLp++;  (PeP  =  *PePP)  !=  (PE  *)0;  PePP++  ) 

PeP->Output  =  *iv++; 

/*  compute  the  weighted  sum  and  transform  it  */ 

for (  ;  (PePP  =  *LLp)  !=  (PE  **)0;  LLp++  )  /*  layer  loop  */ 

( 

LastPP  =  PePP; 

for (  ;  (PeP  =  *PePP)  !=  (PE  *)0;  PePP++  )  /*  PE's  in  a  layer  */ 

{ 

/*  weighted  sum  of  the  inputs  */ 
sum  =  0; 

for (  WtP  =  &PeP->Conns [0] ;  WtP->PESource  !=  0;  WtP++  ) 
sum  +=  WtP->ConnWt  *  PEList [  WtP->PESource  ]->Output; 

/*  transform  it  using  a  sigmoidal  transfer  function  */ 
PeP->Output  =  sigmoid (  sum  ); 

/*  if  "learn"  mode,  set  the  error  to  zero  */ 

if  (  ref  ==  0  )  PeP->Error  =  0.0;  /*  (for  learning)  */ 

) 


/*  copy  the  results  to  the  output  array  */ 
if  (  ref  !=  0  )  /*  only  if  not  learning  */ 

{ 

for (  ;  (PeP  =  *LastPP)  !=  (PE  *)0;  LastPP++  ) 
*ov++  =  PeP->Output; 

} 


double  sigmoid (  x  ) 
double  x; 

{ 

double  r;  /*  result  */ 

extern  double  exp(); 

/*  check  special  limiting  cases  to  prevent  overflow  */ 

if  (  x  <  -10.  )  r  =  0.0; 

else  if  (  x  >  10.  )  r  =  1.0; 

else  r  =  1.0  /  (1.0+  exp (  -x  )); 

return (  r  ) ; 


RRandO  -  Compute  a  random  number  in  a  range 


double  RRand(  low,  high  ) 
double  low,  high; 


Learn ()  -  "learn"  an  association 


double  Learn (  ov,  iv,  LLp,  alpha,  eta  ) 


double 

*ov; 

/* 

output  vector  */ 

double 

*iv; 

/* 

input  vector  */ 

PE 

*  *  *  LLp ; 

/*  layer  list  pointer  */ 

double 

alpha; 

/* 

learning  rate  */ 

double 

eta; 

/* 

momentum  */ 

t 

double 

MAErr; 

/* 

Maximum  Absolute  error  */ 

double 

rv; 

/* 

work  value  */ 

double 

SigErr; 

/* 

back-propagated  error  */ 

***ALp;  /*  alternate  layer  pointer  */ 

*PePP;  /*  PE  Pointer  */ 

*LastPP;  /*  last  non-zero  PE  list  pointer  */ 

*PeP;  /*  PE  itself  */ 

*WtP;  /*  connection  Pointer  */ 


/*  low  /  high  limits  */ 
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Listing  One  (Listing  continued,  text  begins  on  page  32.) 

extern  double  fabsO;  /*  absolute  value  */ 

Recall  (  ov,  iv,  LLp,  0  );  /*  perforin  a  recall  */ 

/*  find  the  output  layer  */ 

for (  ALp  =  LLp;  ALp[l]  !=  (PE  **)0;  ALp++  ) 


/*  compute  the  square  error  in  the  output  */ 

for (  MAErr  =  0.0,  PePP  =  *ALp;  (PeP  -  *PePP)  !=  (PE  *)0;  PePP++  ) 

{ 

rv  =  *ov++  -  PeP->Output;  /*  output  Error  */ 

PeP->Error  =  rv; 

if  (  fabs(rv)  >  MAErr  )  MAErr  =  fabs(rv); 

) 

/*  back-propagate  the  error  &  update  the  weights  */ 
for{  ;  ALp  >  LLp;  ALp —  )  /*  layer  loop  */ 

( 

PePP  =  *ALp; 

fort  ;  (PeP  =  *PePP)  !=  (PE  *)0;  PePP++  )  /*  PE's  in  a  layer  */ 

( 

/*  compute  the  error  prior  to  the  sigmoid  function  */ 

SigErr  =  PeP->Output  *  (1.0  -  PeP->Output)  *  PeP->Error; 

/*  back-propagate  the  errors  &  adjust  weights  */ 
fort  WtP  =  &PeP->Conns  [0] ;  WtP->PESource  !=  0;  WtP++  ) 

( 

PEList [  WtP->PESource  ] ->Error  +■ 

WtP->ConnWt  *  SigErr; 

rv  =  alpha  *  PEList (  WtP->PESource  ]->0utput  *  SigErr  + 
eta  *  WtP->LastDelta; 

WtP->ConnWt  +=  rv; 

WtP->LastDelta  *  rv; 

} 

} 

} 


return (  MAErr  ); 
) 


*  Main()  -  main  driver  routine  to  train  the  network 


*/ 
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NOISE  FILTERING 

Listing  One  (Listing  continued,  text  begins  on  page  32.) 

static  double  ivl[]  -  (  0.0,  0.0  };  static  double  ovl[]  =  {  0.0  }; 
static  double  iv2[j  =  (  1.0,  0.0  };  static  double  ov2[j  =  (  1.0  }; 
static  double  iv3[j  =  (  0.0,  1.0  );  static  double  ov3[]  -  {  1.0  }; 
static  double  iv4[]  =  {  1.0,  1.0  };  static  double  ov4[]  =  (  0.0  ); 

static  double  *ivp[]  -  (  &ivl[0],  6iv2(0],  &iv3[0],  & i v4 [ 0 ]  ); 
static  double  *ovp(j  =  {  &ovl[0],  4ov2[0],  Sov3[0],  &ov4[0]  }; 

main  () 

int  wx;  /*  work  index  */ 

int  x;  /*  index  into  samples  array  */ 

double  r;  /*  work  value  */ 

double  MAErr;  /*  maximum  Absolute  error  */ 

double  wo [sizeof (ivp) /sizeof (*ivp) ] ; 

/*  randomize  the  weights  in  the  network  */ 

RandWts(  -1.0,  1.0,  &LayList[0]  ); 

MAErr  =  0.0; 

for(  wx  =  0;  ;  wx++  ) 

x  =  wx  %  (sizeof (ivp) /sizeof (*ivp) ) ; 
if  (  x  ==  0  &&  wx  ! =  0  ) 

if  (  (wx  %  100)  ==  0  ) 

printf(  "Presentation  %4d.  Maximum  Absolute  Error  =  %.5f\n", 
wx,  MAErr  ); 

if  (  MAErr  <  .1  )  break; 

MAErr  =  0.0; 

} 

r  =  Learn (  ovp[x],  ivp[x],  SLayList[0],  0.9,  0.5  ); 
if  (  r  >  MAErr  )  MAErr  =  r; 

} 

/*  test  the  network  */ 

f or (  wx  =  0;  wx  <  (sizeof (ivp) /sizeof (*ivp) ) ;  wx++  ) 

Recall (  wo,  ivp[wx),  SLayList [0] ,  1  );  /*  perform  a  recall  */ 

printf(  "Input:  %.2f  %.2f  ->  %.2f\n",  ivp[wx)[0],  ivp[wx][l],  wo[0]  ); 

} 

return; 

} 

End  Listing 
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Listing  One  ( Text  begins  on  page  62.) 


II 

Header: 

Complex 

n 

Version : 

1.00 

// 

Date: 

10-Sep-1988 

ii 

Language : 

C++ 

// 

Purpose : 

Provides  the  class  "complex"  for  C++  programs 

// 

Copyright 

1988  by  Scott  Robert  Ladd.  All  Rights  Reserved. 

II  real  part 
//  imaginary  part 


♦include  "stream. hpp" 

class  complex 

{ 

private: 

double  real;  / 
double  imag;  / 

public: 

//  constructors 
complex  (void) 

{ 

real  =  0.0; 
imag  =  0.0; 

} 


complex  (complex  &c) ; 
complex  (double  &r,  double  Si) ; 

//  value  extraction  methods 
double  get_real  (void); 
double  get_imag  (void); 

//  assignment  method 

void  assign  (double  Sr,  double  Si); 

//  calculation  methods 
complex  operator  =  (complex  Sc) ; 

complex  operator  +  (complex  sc) ; 

complex  operator  -  (complex  sc) ; 

complex  operator  *  (complex  Sc) ; 

complex  operator  /  (complex  Sc) ; 


//  output  method 

friend  ostreams  operator  <<  (ostream  ss,  complex  Sc); 


Listing  Two 

COMPLEX. CPP 


//  add  two  complex  numbers 

complex  complex: : operator  +  (complex  Sc) 


complex  res; 


End  Listing  One 


res. real  =  real  +  c.real; 
res. imag  =  imag  +  c.imag; 


//  subtract  two  complex  numbers 
complex  complex: : operator  -  (complex  sc) 
{ 

complex  res; 

res. real  =  real  -  c.real; 
res. imag  =  imag  -  c.imag; 


//  multiply  two  complex  numbers 
complex  complex: : operator  *  (complex  Sc) 

( 

complex  res; 

res. real  =  (real  *  c.real)  -  (imag  *  c.imag); 
res. imag  =  (imag  *  c.real)  +  (real  *  c.imag); 


//  divide  two  complex  numbers 

complex  complex: : operator  /  (complex  Sc) 

{ 

complex  res; 
double  r,  den; 

if  (fabs (c.real)  >=  fabs (c.imag) ) 

( 

r  =  c.imag  /  c.real; 
den  =  c.real  +  r  *  c.imag; 
res. real  =  (real  +  r  *  imag)  /  den; 
res. imag  =  (imag  -  r  *  real)  /  den; 
} 


r  =  c.real  /  c.imag; 

den  =  c.imag  +  r  *  c.real; 

res. real  =  (real  *  r  +  imag)  /  den; 

res. imag  =  (imag  *  r  -  real)  /  den; 


// 

Module : 

Complex 

II 

Version: 

1.00 

1/ 

Date : 

10-Sep-1988 

// 

Language: 

C++ 

II 

Purpose: 

Provides  the  class  "complex"  for  C++  programs 

II 

Copyright 

1988  by  Scott  Robert  Ladd.  All  Rights  Reserved. 

♦include  "complex. hpp" 
♦include  "stream. hpp" 


//  constructor:  copy  initializer 
complex: : complex  (complex  Sc) 


real  =  c.real; 
imag  =  c.imag; 


//  constructor:  real  and  imaginary  parts  specified 
complex: : complex  (double  Sr,  double  Si) 


real  =  r; 
imag  =  i; 


//  retrieve  real  portion 
double  complex: :get_real  (void) 


return  real; 


//  retrieve  imaginary  portion 
double  complex: :get_imag  (void) 
{ 

return  imag; 


//  stream  output  of  complex  number 
ostreams  operator  «  (ostream  ss,  complex  Sc) 


char  buf [80) ; 


sprintf (buf, "%lgl+lgi", c . real, c . imag) ; 
return  (s  <<  buf); 


Listing  Three 

COMPTEST . CPP 


End  Listing  Two 


// 

Program: 

CompTest 

// 

Version: 

1.00 

// 

Date : 

10-Sep-1988 

// 

Language : 

C++ 

// 

Purpose: 

Provides  the  class  "complex"  for  C++  programs 

II 

Copyright 

1988  by  Scott  Robert  Ladd.  All  Rights  Reserved. 

♦include  "complex. hpp" 
void  main () 


complex  a (1 . 0, 2 . 0) , 

b (-1 . 5, -5 . 5) , 


//  set  the  value  of  a  complex  object  to  a  pair  of  real  values 
void  complex: : assign  (double  Sr,  double  Si) 

{ 

real  =  r; 
imag  =  i; 

) 

//  set  the  value  of  a  complex  number 
complex  complex :  .‘operator  =  (complex  Sc) 

{ 

real  =  c.real; 
imag  =  c.imag; 


cout  <<  "a  =  "  «  a  «  "  b  =  "  «  b  «  "  c  =  "  «  c  «  "\n" 

c  =  a  +  b; 

cout  «  c  «  "\n"; 

c  =  c  -  b; 

cout  «  c  «  "\n"; 

c  =  b; 

cout  <<  c  «  "\n"; 

c  =  b  *  a; 

cout  <<  c  «  "\n"; 

c  =  c  /  a; 

cout  «  c  <<  "\n"; 

c  =  b  /  b; 

cout  «  c  «  "\n"; 


End  Listing  Three 

(continued  on  page  104) 
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MODULA-2  vs  C++ 

Listing  Four  (Listing  continued,  text  begins  on  page  62.) 

PROCEDURE  Mult (VAR  C  :  COMPLEX;  Cl,  C2  :  COMPLEX); 

BEGIN 

COMP LEX. DEF 

CA.Real  :=  (ClA.Real  *  C2A.Real)  -  (ClA.Imag  *  C2A.Imag); 

CA . Imag  :=  (ClA.Real  *  C2A.Imag)  -  (ClA.Imag  *  C2A.Real); 

s 

END  Mult; 

DEFINITION  MODULE  Complex; 

PROCEDURE  Div (VAR  C  :  COMPLEX;  Cl,  C2  :  COMPLEX); 

(* 

VAR 

Version:  1.00 

rl,  r2  :  LONGREAL; 

Date:  ll-Sep-1988 

BEGIN 

Language:  Modula-2 

IF  ABS (C2A.Real)  >=  ABS (C2 A . Imag)  THEN 

Purpose:  Provides  the  type  "complex"  for  Modula-2. 

rl  :=  C2 A . Imag  /  C2A.Real; 

Copyright  1988  by  Scott  Robert  Ladd.  All  Rights  Reserved. 

r2  :=  C2A .Real  +  rl  *  C2A.Imag; 

*) 

CA . Real  :=  (ClA.Real  +  rl  *  ClA.Imag)  /  r2; 

CA . Imag  :=  (ClA.Imag  -  rl  *  ClA.Real)  /  r2; 

TYPE 

ELSE 

COMPLEX; 

rl  :=  C2A .Real  /  C2A.Imag; 
r2  :=  C2A.Imag  +  rl  *  C2A.Real; 

PROCEDURE  Create (VAR  C  :  COMPLEX); 

CA.Real  :=  (ClA.Real  *  rl  +  ClA.Imag)  /  r2; 

CA.Imag  :=  (ClA.Imag  *  rl  -  ClA.Real)  /  r2; 

PROCEDURE  Destroy (VAR  C  :  COMPLEX); 

END;  (*  IF  *) 

PROCEDURE  Get Real (C  :  COMPLEX)  :  LONGREAL; 

END  DE¬ 
PROCEDURE  WriteComplex (C  :  COMPLEX); 

PROCEDURE  Getlmag (C  :  COMPLEX)  :  LONGREAL; 

VAR 

S  :  ARRAY  [0..10]  OF  CHAR; 

PROCEDURE  Assign (VAR  C  :  COMPLEX;  R,  I  :  LONGREAL); 

OK  :  BOOLEAN; 

PROCEDURE  Equate (VAR  Cl  :  COMPLEX;  C2  :  COMPLEX); 

FixRealToStr (CA. Real,  3,  S,  OK); 

WrStr (S) ; 

PROCEDURE  Add (VAR  C  :  COMPLEX;  Cl,  C2  :  COMPLEX); 

FixRealToStr (CA . Imag,  3,  S,  OK); 

IF  CA . Imag  >=0.0  THEN 

PROCEDURE  Sub (VAR  C  :  COMPLEX;  Cl,  C2  :  COMPLEX); 

WrChar ('+'); 

END;  {*  IF  *) 

WrStr (S) ; 

WrChar ('i'); 

PROCEDURE  Mult (VAR  C  :  COMPLEX;  Cl,  C2  :  COMPLEX); 

PROCEDURE  Div (VAR  C  :  COMPLEX;  Cl,  C2  :  COMPLEX); 

END  WriteComplex; 

PROCEDURE  WriteComplex (C  :  COMPLEX); 

ENDComplex.  End  Listing  Five 

ENDComplex  End  Listing  Four 

Listing  Six 

Listing  Five 

COMPTEST.MOD 

COMP LEX. MOD 

MODULE  CompTest; 

Version:  1.00 

IMPLEMENTATION  MODULE  Complex; 

Date:  ll-Sep-1988 

(* 

Language:  Modula-2 

Version:  1.00 

Purpose:  Tests  the  Complex  module 

Date:  ll-Sep-1988 

Copyright  1988  by  Scott  Robert  Ladd.  All  Rights  Reserved. 

Language:  Modula-2 

Purpose:  Provides  the  type  "complex"  for  Modula-2. 

*> 

Copyright  1988  by  Scott  Robert  Ladd.  All  Rights  Reserved. 

*) 

FROM  Complex  IMPORT  COMPLEX, 

Create,  Destroy,  Assign,  Equate, 

Add,  Sub,  Mult,  Div,  WriteComplex; 

FROM  Str  IMPORT  FixRealToStr; 

FROM  10  IMPORT  WrStr,  WrChar; 

FROM  Storage  IMPORT  ALLOCATE,  DEALLOCATE; 

FROM  IO  IMPORT  WrStr,  WrLn; 

VAR 

TYPE 

a,  b,  c  :  COMPLEX; 

COMPLEX  =  POINTER  TO  RECORD 

rl,  il  :  LONGREAL; 

Real  :  LONGREAL; 

Imag  :  LONGREAL; 

r2,  i2  :  LONGREAL; 

END; 

BEGIN 

rl  :=  1.0; 

PROCEDURE  Create (VAR  C  :  COMPLEX); 

il  :=  2.0; 

BEGIN 

r2  :=  -1.5; 

NEW (C)  ; 

CA . Real  :=  0.0; 

i2  :=  -5.5; 

CA.Imag  :=  0.0; 

Create (a) ; 

END  Create; 

Create (b) ; 

Create (c) ; 

PROCEDURE  Destroy (VAR  C  :  COMPLEX); 

BEGIN 

Assign (a, rl, il) ; 

DISPOSE (C) ; 

Assign (b, r2, i2) ; 

END  Destroy; 

Assign (c, rl, i2) ; 

PROCEDURE  GetReal (C  :  COMPLEX)  :  LONGREAL; 

WrStr ("a  =  "); 

BEGIN 

WriteComplex (a) ; 

RETURN  CA .Real; 

WrStr ("  b  =  ") ; 

END  GetReal; 

WriteComplex (b) ; 

WrStr {"  c  =  ") ; 

PROCEDURE  Getlmag (C  :  COMPLEX)  :  LONGREAL; 

WriteComplex (c) ; 

BEGIN 

WrLn; 

RETURN  CA . Imag; 

END  Getlmag; 

Add(c,a,b)  ; 

WriteComplex (c) ; 

PROCEDURE  Assign (VAR  C  :  COMPLEX;  R,  I  :  LONGREAL); 

WrLn; 

BEGIN 

CA.Real  :=  R; 

Sub (c, c, b) ; 

CA.Imag  :=  I; 

WriteComplex (c) ; 

END  Assign; 

WrLn; 

PROCEDURE  Equate (VAR  Cl  :  COMPLEX;  C2  :  COMPLEX); 

Mult (c,b, a) ; 

BEGIN 

WriteComplex (c) ; 

C1A .Real  :=  C2A.Real; 

ClA.Imag  :=  C2A.Imag; 

WrLn; 

END  Equate; 

Div (c, c, a) ; 

WriteComplex (c) ; 

PROCEDURE  Add (VAR  C  :  COMPLEX;  Cl,  C2  :  COMPLEX); 

WrLn; 

BEGIN 

CA .Real  :=  ClA.Real  +  C2A.Real; 

Div (c, b, b) ; 

CA.Imag  :=  Cl A. Imag  +  C2A.Imag; 

WriteComplex (c) ; 

END  Add; 

WrLn; 

PROCEDURE  Sub (VAR  C  :  COMPLEX;  Cl,  C2  :  COMPLEX); 

Destroy (a) ; 

BEGIN 

Destroy (b) ; 

CA . Real  :=  ClA.Real  -  C2A.Real; 

Destroy (c) ; 

CA . Imag  :=  ClA.Imag  -  C2A.Imag; 

End  Listings 

END  Sub; 

END  CompTest . 
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ARTICLES 


Using  Extended  Memory  on  the  PC  AT 


Here’s  a  program  that  lets  you  copy  memory  from 
real  mode  to  extended  memory  -  and  back  again 


by  Paul  Thomson 


The  PC  AT  BIOS  contains  a  ser¬ 
vice  — service  87h  of  interrupt 
15h  — forcopying  memory  in  pro¬ 
tected  mode,  thereby  allowing  you  to 
copy  memory  anywhere  in  the  16- 
Mbyte  address  range  of  the  80286.  This 
means  that  you  can  copy  memory  from 
real-mode  memory  to  extended  mem¬ 
ory  and  back  again.  Before  calling  this 
service  routine,  however,  you  must  set 
up  a  data  structure  for  protected-mode 
operation.  This  structure  is  called  a 
global  descriptor  table.  It  contains  six 
descriptors,  each  with  8  bytes.  Two  of 
these  are  segment  descriptors  that  de¬ 
scribe  the  source  and  target  buffers. 
The  rest  of  the  descriptors  are  simply 
dummy  descriptors  that  will  be  initial¬ 
ized  by  the  BIOS  routine.  The  8-byte 
segment  descriptors  are  shown  in  Ta¬ 
ble  1 ,  below. 

Before  calling  the  service  routine, 


Paul  Thomson  is  a  software  engineer 
at  Black  Dot.  He  can  be  reached  at  439 
N Lake  Shore  Dr.,  Palatine,  IL  60067. 


you  must  set  up  the  registers  as  shown 
in  Table  2.- 

There  is  also  another  interrupt  15h 
service  — service  88h  — which  is  use¬ 
ful  for  extended  memory.  Service  88h 
returns  the  number  of  Kbytes  of  ex¬ 
tended  memory  (which  starts  at 
0x100000)  in  AX.  Since  service  88h  will 
not  return  an  error  when  accessing  non¬ 
existent  memory,  service  88h  can  be 
used  to  determine  if  the  move  will  in¬ 
volve  valid  memory  locations. 

Listing  One,  page  108,  shows  a  Micro¬ 
soft  C  (compact  or  large  model)  ver¬ 
sion  of  the  move  routine  (movphy),  the 
top  of  memory  routine  (getext),  and  a 
test  routine  (main)  while  Listing  Two, 
page  1 19,  is  an  assembly  language  ver¬ 
sion.  movphy  will  copy  memory  in  64K- 
byte  chunks  given  the  source  and  desti¬ 
nation  addresses  in  24-bit  format,  getext, 
which  must  be  called  once  (before 
movphy  is  called  for  the  first  time)  sets 
up  a  static  variable  with  the  maximum 
physical  address  of  extended  memory. 
The  test  copies  a  string  between  ex¬ 


tended  and  real-mode  memory  to  show 
that  the  routine  is  working  correctly. 
An  error  can  be  discovered  by  check¬ 
ing  the  routine  return  code  (ax  in  C, 
ah  in  the  assembler  routine).  Before 
you  use  the  program,  check  that  your 
extended  memory  is  not  occupied  by 
vdisk;  the  program  can  wipe  out  your 
virtual  disk  files  and/or  render  vdisk 
unusable. 

Availability 

All  source  code  for  articles  in  this  issue 
is  available  on  a  single  disk.  To  order, 
send  $14.95  to  Dr.  Dobb's Journal,  501 
Galveston  Dr.,  Redwood  City,  CA  94063, 
or  call  415-366-3600,  ext.  221.  Please 
specify  issue  number  and  format  (MS- 
DOS,  Macintosh,  Kaypro). 

DDJ 

(Listings  begin  on  page  108.) 

Vote  for  your  favorite  feature/article. 

Circle  Reader  Service  No.  12. 


Descriptor 

Format 

16  bits 

Null:  Reserved  for  future  use 

8  bits 

Access  rights  byte:  Contains  attribute  flags  for  the  segment  (writable?,  data 
segment?,  etc.) 

24  bits 

Physical  address:  Any  real  mode  address  must  be  converted  to  a  24  bit 
physical  address  by  the  following  formula:  (segreg  *  16)  +  offset. 

16  bits 

Segment  length  in  bytes:  Words  to  transfer  *  2. 

Table  1:  Segment  descriptor formats 


AH 

=  87h 

ES:SI 

=  Real  mode  address  of 

global  descriptor  table 

CX 

=  Count  of  words  to  copy 

Table  2:  Setup  for  registers 
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EXTENDED  MEMORY 


Listing  One  (Text  begins  on  page  106.) 

/*** 

***  ROUTINE  FOR  COPYING  MEMORY  USING  PHYSICAL  ADDRESSES  ON  THE  PCAT. 
***  WRITTEN  BY  PAUL  THOMSON. 

***  COMPILE  USING  MICROSOFT  C  V4.0,  LARGE  OR  COMPACT  MODEL. 

***  DO  NOT  USE  THIS  ROUTINE  WITH  A  VIRTUAL  DISK  IN  EXTENDED  MEMORY. 
***/ 

#include  <stdio.h> 

♦include  <dos.h> 


♦define  PHYS(s)  ( ( (long) FP_SEG (s)  «  4)  +  FP_OFF(s)) 

♦define  BUFSZ  16 

♦define  PHY  ADDR  OxlOOOOOL 


/*  CALC  PHYS  ADDR  */ 

/*  BUF  SIZE  IN  BYTES*/ 
/*  BEG  OF  EXT  MEMORY  */ 


char  *buf="ORIGINAL  MESSAGE"; 


/*  TEST  MOVPHY  BY  COPYING  A  MESSAGE  TO  EXTENDED  MEMORY  AND  BACK  */ 
main  () 


extsizeO ; 
puts (buf ) ; 

movphy (PHY_ADDR,  PHYS(buf),  BUFSZ/2); 
sprintf (buf,  "XXXXXXXXXXXXXXXX") ; 
puts  (buf) ; 

movphy (PHYS (buf ) ,  PHY_ADDR,  BUFSZ/2); 
puts (buf) ; 


/*  MOVE  TO  EXTENDED  MEMORY  */ 

/*  OVERWRITE  BUFFER  */ 

/*  MOVE  BACK  FROM  EXTENDED  MEMORY*/ 


static  long  maxext;  /*  HOLDS  MAX  ADDRESS  OF  EXTENDED  MEMORY  */ 

extsizeO 

{ 

union  REGS  r; 


r.h.ah  -  0x88; 

int86 (0x15,  fir,  fir);  /*  RETURNS  SIZE  OF  EXTENDED  MEM  IN  KBYTES  */ 

maxext  =  (r.x.ax  +  1024L)*1024;  /*  FIND  TOP  OF  EXTENDED  MEMORY  */ 


/*  MOVE  MEMORY  USING  PHYSICAL  ADDRESSES  */ 


movphy (target,  source,  wcount) 
unsigned  long  target; 
unsigned  long  source; 
int  wcount; 

( 

int  bcount; 
char  gdt [48]; 
char  *g  =  gdt; 
union  REGS  r; 
struct  SREGS  s; 


/*  PHYSICAL  24  BIT  TARGET  ADDRESS  */ 

/*  PHYSICAL  24  BIT  SOURCE  ADDRESS  */ 

/*  16  BIT  COUNT  OF  WORDS  TO  MOVE  0  -  32767  */ 


/*  GLOBAL  DESCRIPTOR  TABLE  (6  DESCRIPTORS*8) * / 
/*  POINTER  TO  gdt  FOR  MACROS  FP_SEG  &  FP_OFF*/ 
/*  HOLDS  REGISTER  VALUES  FOR  int86x  CALL  */ 

/*  HOLDS  SEG  REGISTER  VALUES  FOR  int86x  CALL*/ 


if (wcount  <=  0) 

return (wcount) ; 
bcount  =  wcount *2; 


/*  CHECK  FOR  WORD  COUNT  TOO  BIG  OR  0  */ 
/*  SIZE  IN  BYTES  TO  MOVE  */ 


if (target +bcount  >=  maxext  ||  source+bcount  >=  maxext) 
return (4) ; 


/*  DESCRIPTORS  0  AND  1  ARE  DUMMIES  (NULL)  */ 

gdt [ 0 ] -gdt [ 1 ] -gdt [ 2 ] -gdt [ 3 ] -gdt [ 4 ) -gdt [ 5 ] -gdt [ 6 ] -gdt ( 7 ] =0 ; 

gdt  [  8  ]  -gdt  [  9  ]  -gdt  [10]  -gdt  [11]  -gdt  [12]  -gdt  [13]  -gdt  [  14  ]  -gdt  [15]  =0; 


/*  DESCRIPTOR  2:  SOURCE  */ 
gdt [16]  =  bcount; 

/* 

BYTE  COUNT  */ 

gdt  [17]  =  bcount»8; 
gdt [18]  =  source; 

/* 

PHYSICAL  ADDRESS  TO  COPY  FROM 

gdt  [19]  =  source»8; 
gdt  [20]  =  source»16; 
gdt [21]  =  0x93; 

/* 

ACCESS  RIGHTS  BYTE  */ 

gdt [22]  =  gdt [23]  =  0; 

/* 

UNUSED  ENTRIES  */ 

/*  DESCRIPTOR  3:  TARGET  */ 
gdt [24]  =  bcount; 

/* 

BYTE  COUNT  */ 

gdt  [25]  =  bcount»8; 
gdt [26]  =  target; 

/* 

PHYSICAL  ADDRESS  TO  COPY  TO  *, 

gdt  [27]  =  target»8; 
gdt  [28]  =  target»16; 
gdt [29]  =  0x93; 

/* 

ACCESS  RIGHTS  BYTE  */ 

gdt  [30]  =  gdt  [31]  =  0; 

/* 

UNUSED  ENTRIES  */ 

/*  DESCRIPTORS  4  AND  5  ARE  DUMMIES  (NULL)  */ 

gdt [ 32 ] -gdt [ 33 ] -gdt [ 34 ] -gdt [ 35 ] -gdt [36] -gdt [ 37 ] -gdt [ 38 ] -gdt [ 39 ] =0 ; 
gdt  [40] -gdt  [41] -gdt  [42 ] -gdt  [43] -gdt  [ 44  ] -gdt  [ 45] -gdt  [ 4 6] -gdt  [47  ]  =0; 


r.h.ah  =  0x87; 

r. x.cx  =  wcount; 

s. es  =  FP_SEG (g) ; 
r.x.si  =  FP_OFF(g); 


/*  AH  =  SERVICE  0x87  */ 

/*  CX  =  COUNT  OF  WORDS  TO  TRANSFER  */ 
/*  ES : SI  =  SEGMENT: OFFSET  OF  GDT  */ 


int86x (0x15,  fir,  fir,  &s);  /*  PERFORM  BIOS  INTERRUPT  0x15  */ 


return (r.h.ah) ; 


RETURN  STATUS: 

0:  SUCCESSFUL  MOVE 
1:  RAM  PARITY  ERROR 
2:  EXCEPTION  ERROR 
3:  ADDRESS  LINE  20  FAILED 
4:  MEMORY  OUT  OF  RANGE 
<0:  WORD  COUNT  >  32767  */ 


End  Listing  One 

(continued  on  page  119) 
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COLUMNS 


C  PROGRAMMING 


The  Surrogate  Library 


Several  readers  have  asked  why  I 
selected  Turbo  C  for  the  “C  Pro¬ 
gramming”  column  project.  Many  of 
you  use  other  compilers,  and  some  of 
you  feel  left  out.  One  such  reader  goes 
so  far  as  to  say  that  the  next  several 
issues  of  DDJ  will  be  useless  to  him, 
and  he  will  likely  allow  his  subscrip¬ 
tion  to  expire.  That  got  my  attention. 

All  this  distress  is  because  the  pro¬ 
grams  being  discussed  are  written  with 
the  specific  screen  management  func¬ 
tions  of  Turbo  C.  This  particular  reader 
felt  that  the  column  should  restrict  it¬ 
self  to  generic  ANSI  C  whenever  possi¬ 
ble  to  reach  the  widest  possible  audi¬ 
ence.  That  argument  has  merit,  and  I 
do  not  want  to  lose  readers,  particu¬ 
larly  those  who  care  enough  to  tell  me 
when  things  are  not  right.  I  must,  there¬ 
fore,  deal  with  this  concern. 

First,  let’s  consider  why  generic  C  is 
not  practical  for  this  project.  The  pro¬ 
gram  uses  our  own  home-grown  video 
windows  on  the  IBM  PC  and  compa¬ 
tibles.  Such  a  program  must,  if  per¬ 
formance  is  to  be  considered,  directly 
address  video  memory.  The  program 
will  also  use  the  PC’s  serial  port.  These 
requirements  bind  the  program  to  the 
PC  hardware  architecture.  Of  course, 
most  of  the  many  C  compilers  for  the 
PC  could  be  used  to  develop  such  a 
program,  and  each  such  program  would 
be  somewhat  different  from  the  others. 
The  methods  that  you  use  for  low-level 
hardware  access  are  different  enough 
with  each  compiler  that  different  pro¬ 
grams  will  result.  Perhaps  a  need  exists 


by  A I  Stevens 


for  a  standard  library  for  MS-DOS  PC 
programs,  but  no  such  standard  is  in 
acceptance.  Some  compilers  attempt 
to  be  compatible  with  others,  but  these 
attempts  fall  apart  when  the  compiler 


developers  are  working  on  similar  ex¬ 
tensions  at  the  same  time.  Witness  the 
different  approaches  to  graphics  librar¬ 
ies  in  Turbo  C  and  Microsoft  C. 

The  news,  however,  is  not  all  bad. 
A  relatively  small  amount  of  the  code 
in  our  project  is  specific  to  and  de¬ 
pendent  upon  Turbo  C.  All  such  code 
is  in  the  area  of  screen  management, 
and  is  represented  by  a  set  of  Turbo  C 
functions  and  a  few  internal  Turbo  C 
constructs.  Most  of  the  rest  of  the  code 
is  generic  at  least  at  the  PC  level.  Micro¬ 
soft  C  and  Turbo  C  do  a  lot  of  things 
the  same  way.  Remember,  however, 
that  the  underlying  theory  that  applies 
to  our  video  windows  is  based  on  the 
PC’s  video  architecture;  the  functions 
that  we  are  developing  are  for  the  PC 
with  MS-DOS.  They  are  not  CP/M,  Unix, 
or  VAX/VMS  programs,  for  example. 
This  fact  could  give  rise  to  a  new  up¬ 
roar,  and  I  reluctantly  wait  for  that  heat 
and  will  try  bravely  to  bear  up  under  it. 

Why  did  I  chose  Turbo  C?  The  an¬ 
swer  is  simple:  Turbo  C  is  the  compiler 
I  use  for  nearly  everything  else  in  MS- 
DOS.  That  is  not  so  much  an  endorse¬ 
ment  as  a  mere  fact.  I  use  Turbo  C 
because  it  has  excellent  support  for  the 
kind  of  programs  1  write:  TSRs  and 
programs  with  video  windows.  Micro¬ 
soft  C  has  some  support  for  those  ar¬ 
eas,  but  not  as  much  as  Turbo  C. 

I  might  have  selected  Microsoft  C  for 
the  project,  in  which  case  I  would  be 
addressing  this  same  discourse  to  the 
users  of  all  the  other  compilers.  I  like 
Microsoft  C.  Recently  my  work  has  ex¬ 
tended  into  the  OS/2  arena,  and  that 
venture  has  me  using  Microsoft  C  once 
again.  All  that  great  Turbo  C  support 
does  not  apply  to  OS/2.  First,  Turbo  C 
does  not  come  in  an  OS/2  flavor.  Sec¬ 


ond,  one  does  not  write  the  same  kind 
of  TSRs  for  OS/2  that  one  writes  for 
MS-DOS.  Third,  one  does  not  do  win¬ 
dows  in  OS/2;  that  will  be  the  domain 
of  screen  groups  and  the  Presentation 
Manager,  like  it  or  not. 

The  TC  to  MSC 
Surrogate  Library 

What  good  does  all  this  rationalization 
do  for  those  of  you  dear  readers  who 
do  not  use  Turbo  C  and  who  want  to 
use  the  code  in  the  “C  Programming” 
column?  None,  unfortunately,  and  that 
is  something  I  intend  to  partially  rectify 
in  this  column.  This  month  I  will  pro¬ 
vide  a  library  of  Microsoft  C  functions 
and  macros  that  turn  the  “C  Program¬ 
ming”  project  into  a  Microsoft  C-com- 
patible  program.  The  library  will  mirror 
those  Turbo  C-specific  functions  that  I 
have  used  so  that  you  can  compile  the 
project’s  functions  with  Microsoft  C. 
In  subsequent  months  I  will  add  to  this 
library  (if  need  be). 

How  about  the  other  compilers?  At 
last  count  there  were  countless  other 
MS-DOS  C  compilers.  Lattice,  Aztec, 
Watcom,  Zortech,  MIX,  High  C,  White¬ 
smith’s,  Mark  Williams,  De  Smet, 
QC88,  Small  C,  Eco-C,  are  all  names 
that  come  to  mind.  At  one  time  or 
another,  I  have  used  each  of  them.  I 
do  not,  however,  intend  to  provide  a 
compiler-independent  program  here.  I 
will  describe  the  Turbo  C  functions 
that  must  be  emulated  for  Microsoft  C, 
and  I  will  provide  the  source  code  for 
that  purpose.  Users  of  those  other  fine 
compilers  may  use  my  example  to  build 
their  own  libraries.  I  am  doing  it  for 
Microsoft  C  because  that  will  satisfy  the 
largest  base  of  readers,  and  that  wheel 
is  squeaking  rather  prominently  just 
now,  thus  getting  the  grease.  To  take 
this  same  side  trip  for  all  those  compil¬ 
ers  would  use  my  allotted  space  in  DDJ 
for  about  the  next  year,  and  we  wouldn’t 
get  anything  else  done. 
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This  library  development  is  not  a  big 
effort  as  you  will  see,  but  I  do  encour¬ 
age  anyone  who  builds  one  for  an¬ 
other  compiler  to  send  the  code  in; 
we’ll  post  it  on  CompuServe  in  the  DDJ 
Forum.  But  let  me  caution  you.  In  the 
past  I  wrote  and  marketed  a  library  of 
C  functions,  and  I  distributed  versions 
that  worked  with  most  of  those  com¬ 
pilers.  It  was  a  frustrating  experience. 
The  effort  required  to  keep  up  with  the 
latest  versions  of  the  compilers  was 
significant.  The  targets  would  never  hold 
still.  Eventually  I  surrendered  and  dis¬ 
tributed  only  source  code.  The  source 
code  was  a  melange  of  compile-time 
conditionals  that  managed  the  differ¬ 
ence  between  compilers  and,  in  doing 
so,  obscured  the  original  meaning  of 
the  code.  Such  a  mess  is  marginally 
acceptable  in  a  commercial  product, 
but  it  should  never  be  seen  in  a  pub¬ 
lished  work  where  the  purpose  is  as 
much  to  inform  as  to  perform. 

I  built  these  surrogate  functions  and 
tested  them  with  Microsoft  C,  Versions 
5.0  and  5-1.1  tried  to  get  them  running 
with  QuickC  as  well,  but  the  window.c 
file  causes  an  internal  QuickC  compiler 
error.  I  recompiled  just  that  module 
with  Microsoft  C,  linked  it  with  the  rest 
of  the  program  as  compiled  with 
QuickC,  and  everything  worked.  A  more 
recent  version  of  QuickC  might  not 
have  this  problem,  but  I  have  only  the 
first  version. 

The  library  consists  of  three  source 
files  and  a  make  file.  The  source  files 
are  microsft.h  (see  Listing  One,  page 
129),  microsft.c  (Listing  Two,  page  129), 
and  vpeek.asm  (Listing  Three,  page 
131).  The  make  file  is  twrp.mak  (List¬ 
ing  Four  on  page  132).  The  make  file 
uses  these  new  functions  to  build  last 
month’s  TWRP  tiny  word  processor  with 
Microsoft  C.  The  microsft.h  file  is  in¬ 
tended  to  be  appended  to  or  included 
in  the  window,  h  file  from  my  Septem¬ 
ber  column.  The  microsoft.c  file  pro¬ 
vides  the  surrogate  functions  that  emu¬ 
late  those  features  of  the  project  that 
depend  on  things  unique  to  Turbo  C. 

These  emulations  are  not  compre¬ 
hensive  — some  of  them  will  not  work 
as  Turbo  C  substitutes  for  everything 
you  might  do.  Rather,  they  provide  suf¬ 
ficient  support  for  the  ways  we  used 
those  functions  in  the  “C  Programming” 
project  so  far.  For  this  reason  I  call 
them  surrogates  rather  than  clones.  Natu¬ 
rally,  as  I  add  to  the  project,  I  will  verify 
that  all  the  new  code  works  with  both 
compilers,  and  I  will  update  this  library 
if  necessary.  If  you  want  a  comprehen¬ 
sive  cross-compiler  library,  you  might 
try  buying  the  Turbo  C  runtime  library 
source  code  and  compiling  the  perti¬ 
nent  functions  with  Microsoft  C.  Such 


an  ambitious  endeavor  is  beyond  the 
scope  of  this  column.  I  need  say  no 
more  than  that  it  would  be  a  significant 
effort,  fraught  with  peril. 

Following  is  a  discussion  of  each 
component  of  the  library. 

microsft.h — The  microsft.h  file  is 
meant  to  be  appended  to  or  included 
in  window,  h  from  September.  You  must 
make  one  change  to  window,  h  to  ac¬ 
commodate  differences  between  the 
two  compilers’  treatments  of  prototypes. 
In  window. h  on  about  line  9  you  will 
see  this  prototype: 

int  select_window( int,int,int,int 

(*func)(int,int)); 

You  must  change  it  to  the  following: 

int  select_window(int,int,int,nt 

(*)(int,int)); 

Microsoft  C  does  not  allow  you  to 
mix  named  and  unnamed  parameters 
in  a  prototype  while  Turbo  C  does  not 
seem  to  mind. 

The  microsft.h  file  begins  with  a  test 
of  the  COMPILER  compile-time  condi¬ 
tional  flag.  This  flag  is  defined  by  the 
compile  statement  in  the  make  file,  and 
it  tells  the  compiler  to  use  the  code 
inserted  from  microsft.h.  My  objective 
was  to  minimize  changes  to  code  al¬ 
ready  published. 

The  #define  statements  for  movmem 
and  setmem  substitute  the  names  of 
appropriate  MSC  functions. 

The  setmem  function  sets  all  the  bytes 
in  a  buffer  to  a  specified  character  value. 
The  first  parameter  is  a  character  pointer 
that  points  to  the  buffer.  The  second 
parameter  is  the  buffer’s  size  in  bytes. 
The  third  parameter  is  the  character 
value  to  be  filled  into  the  buffer.  The 
corresponding  Microsoft  C  function  is 
memset.  Its  parameters  are  in  a  differ¬ 
ent  sequence  than  those  of  Turbo  C’s 
setmem. 

The  movmem  function  takes  three 
parameters:  a  source  character  pointer, 
a  destination  character  pointer,  and  a 
byte  count.  The  function  moves  a  block 
of  memory  and  accounts  for  overlap¬ 
ping  source  and  destination  blocks,  mov¬ 
ing  from  the  correct  end  of  the  buffer 
to  prevent  byte  replication.  The  corre¬ 
sponding  Microsoft  C  function  is 
memmove.  Its  parameters  are  in  a  dif¬ 
ferent  sequence  than  those  of  movmem. 
Note  that  Microsoft  C  has  a  movmem 
function  that  resembles  Turbo  C’s 
movmem ,  but  it  does  not  correct  for 
overlapping  buffers  and  cannot  be  used 
here. 

The  #define  statements  for  cprintf 
cputs ,  getch,  and  putch  substitute  the 


names  of  functions  in  microsft.c  for 
these  names.  Both  Turbo  C  and  MSC 
have  functions  with  these  names,  but 
their  behaviors  are  different  enough 
that  we  must  make  substitutions. 

Next  come  the  prototypes  for  the 
functions  of  TC  that  MSC  does  not  have. 
After  that  are  ^define  statements  for  the 
screen  colors. 

microsft.c  — This  file  has  the  func¬ 
tions  that  emulate  the  Turbo  C  func¬ 
tions  — the  Turbo  surrogate.  It  starts 
with  some  #includes  and  prototypes. 
The  vpeek  and  vpoke  prototypes  are  for 
the  functions  in  vpeek.asm ,  which  read 
and  write  video  memory  compensat¬ 
ing  for  video  snow.  If  your  system  does 
not  use  the  color  graphics  adaptor 
(CGA),  you  do  not  need  the  assembly 
language  functions. 

The  compile-time  global  symbol, 
ADAPTOR,  specifies  the  video  adaptor 
your  program  uses,  and  the  VSEG  sym¬ 
bol  is  automatically  equated  to  the  seg¬ 
ment  address  of  display  refresh  mem¬ 
ory,  which  is  OxbOOO  for  the  mono¬ 
chrome  display  adaptor  and  0xb800 
for  the  others.  The  SNOW  symbol  is  set 
to  0  if  the  adaptor  does  not  generate 
video  snow  when  video  memory  is 
accessed.  Otherwise  it  is  set  to  1.  If  you 
use  an  adaptor  other  than  the  CGA, 
you  can  remove  the  references  to 
vpeek.asm  and  vpeek. obj  from  Listing 
Four,  twrp.mak. 

With  Turbo  C  the  tests  for  the  video 
segment  and  snow  are  made  at  run 
time  by  the  compiled  code  and  are  not 
visible  to  you.  For  this  subset  emula¬ 
tion,  however,  you  must  specify  the 
video  adaptor  when  you  compile  the 
program.  This  is  consistent  with  the 
philosophy  of  this  program  where  con¬ 
figuration  items  are  controlled  by  com¬ 
piled  #define  control  statements. 

The  video  structure  is  a  duplicate  of 
an  external  structure  that  is  internal  to 
Turbo  C  and  that  is  referenced  in  win¬ 
dow.c.  We  declare  it  here  because  Mi¬ 
crosoft  C  has  no  such  structure.  By 
maintaining  the  values  that  our  soft¬ 
ware  uses,  we  can  make  the  program 
react  just  as  it  does  when  the  Turbo  C 
run-time  library  (RTL)  is  running  things. 

The  window  function  is  used  to  es¬ 
tablish  a  rectangle  of  memory  as  the 
current  video  window.  Its  integer  pa¬ 
rameters  are  the  left,  top,  right,  and 
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bottom  screen  coordinates  where  the 
upper  left  screen  coordinate  is  row  1, 
column  1,  and  the  lower  right  coordi¬ 
nate  is  row  25,  column  80. 

The  _vptr  function  returns  a  far 
pointer  to  video  memory  based  on  the 
x  and  y  coordinates  passed  to  it.  This 
is  an  emulation  of  an  external  Turbo  C 
function  that  is  normally  only  called 
from  within  the  Turbo  C  run-time  li¬ 
brary  but  that  we  used  in  window. c. 
You’ll  recall  that  1  chastised  myself  for 
using  it.  Now  I  pay. 

The  _vram  function  writes  a  linear 
block  of  program  memory  to  video 
memory.  Its  parameters  are  a  far  pointer 
to  the  start  of  the  video  memory  loca¬ 
tion,  a  far  pointer  to  the  program  mem¬ 
ory  buffer,  and  the  number  of  2-byte 
integers  to  write.  Video  memory  con¬ 
sists  of  2  bytes  — a  video  attribute  and 
an  ASCII  character — for  each  screen 
character  position.  This  function  is  also 
an  emulation  of  one  that  is  normally 
only  called  from  the  TC  RTL.  We  used 
it  in  window. c  to  effect  a  smooth  write 
to  the  screen  without  the  annoyance 
of  a  cursor  flash  across  the  write  such 
as  you  see  when  you  use  cprintf  and 
cputs. 

The  _getvram  function  is  the  reverse 
of  _vram.  It  reads  rather  than  writes 
video  memory.  This  function  is  not  an 
emulation,  but  one  that  we  need  for 
the  gettext  function  described  below. 
In  Turbo  C,  the  _vram  function  man¬ 
ages  video  memory  moves  in  both  di¬ 
rections  by  using  the  segment  addresses 
to  determine  if  the  source  or  destina¬ 
tion  is  the  video  RAM.  Rather  than  go 
to  that  trouble,  I  coded  a  simple  _vram 
and  then  added  _getvram  as  a  recipro¬ 
cal  of  _vram. 

The  gettext  and  puttext  functions  are 
higher-level  read  and  write  video  mem¬ 
ory  functions.  They  deal  with  linear 
buffers  of  program  memory  and  rec¬ 
tangular  windows  of  video  memory. 
They  are  used  to  save  and  restore  the 
video  space  that  our  windows  occupy. 
The  coordinates  (left,  top,  right,  bot¬ 
tom)  are  relative  to  the  full  screen  and 
begin  with  1,1  at  the  top  left.  The 
movetext  function  moves  a  video  win¬ 
dow.  We  use  it  for  window  scrolling, 
so  this  emulated  function  works  with 
vertical  movements  only.  The  Turbo  C 
movetext  function  is  a  lot  smarter,  be¬ 
ing  able  to  move  a  window  from  and 
to  any  screen  positions.  The  arguments 
to  movetext  are  the  four  corner  coordi¬ 
nates  of  the  original  window  (relative 
to  the  full  screen)  and  the  upper  left 
coordinates  of  where  it  is  to  be  moved. 
If  you  are  using  the  CGA,  you  can 
eliminate  movetext  because  we  used 


BIOS  to  scroll  CGA  screens  for  per¬ 
formance  reasons.  To  avoid  changing 
the  scroll  function  in  window. c,  put  a 
null  function  named  movetext  in  mi- 
crosft.c  in  place  of  the  one  given  here. 

The  gotoxy  function  positions  the  cur¬ 
sor  at  a  location  in  the  current  window 
(the  one  most  recently  defined  by  the 
window  function)  as  specified  by  the 
x  and  y  parameters.  These  parameters 
are  relative  to  the  window,  with  1,1 
being  the  upper  left  corner  of  the  win¬ 
dow. 

The  wherex  and  wherey  functions 
return  the  current  cursor  x  and  y  posi¬ 
tions  relative  to  the  current  window. 


Portability  is  not  the 
objective  it  once  was.  In 
olden  times 

programmers  wrote for 
teletype-like  interfaces 
and  portable  programs 
were  possible 


The  textcolordnd  textbackgroundfunc- 
tions  set  the  colors  that  will  be  used  the 
next  time  a  text  display  is  written.  Their 
parameters  are  integer  values  as  de¬ 
fined  in  microsft.h. 

The  ivprintf  function  is  substituted 
for  cprintf.  Both  compilers  have  cprintf 
functions  that  are  similar,  but  they  are 
both  related  to  their  own  internal  text 
display  processes.  The  cprintf  macro 
in  microsft.h  replaces  calls  to  cprintf 
with  ones  to  wprintf.  This  new  func¬ 
tion  makes  a  simple  translation  using 
the  vsprintf  function  of  Microsoft  C. 
The  resulting  string  is  then  copied  to 
video  memory  based  on  the  current 
cursor  position.  Note  that  this  surro¬ 
gate  function  does  not  attempt  to  deal 
with  control  characters  such  as  \n  and 
\  r.  This  omission  is  because  we  never 
use  such  controls  in  our  calls  to  cprintf. 

I  hope  I  do  not  regret  this  shortcut 
later. 

We  have  substituted  wgetch  and 
uputch  for  getch  and  putch  because 
the  existing  Microsoft  C  functions  do 
not  work  in  the  context  in  which  we 
are  using  them. 

vpeek,  asm  — The  vpeek function  has 
two  unsigned  parameters.  The  first  is 


the  segment  address  of  video  memory 
(always  the  value  #defined  as  VSEG) 
and  the  second  is  the  video  offset  ad¬ 
dress.  The  function  returns  the  2-byte 
value  in  the  video  memory  address. 
Before  accessing  video  RAM,  vpeek  waits 
for  a  video  retrace  cycle  to  avoid  the 
snow-causing  memory  access  conflict 
between  the  CPU  and  the  video  con¬ 
troller. 

The  ipoke  function  inserts  a  2-byte 
value  into  a  video  memory  location 
with  the  same  snow-eliminating  rou¬ 
tine  as  vpeek.  It  has  the  same  two  video 
memory  address  parameters  as  i peek. 
Its  third  parameter  is  the  two-byte  word 
to  be  inserted  into  video  memory. 

Header  Files 

Turbo  C  and  Microsoft  C  define  their 
function  prototypes  in  header  files  in 
mostly  the  same  way.  The  same  header 
files  define  the  same  ANSI  standard 
functions.  There  are  two  minor  differ¬ 
ences,  however.  Turbo  C  defines  all 
the  memory  allocation  functions  in  al¬ 
loc. h  and  Microsoft  C  uses  malloc.h. 
Turbo  C  uses  mem.h  for  prototypes  of 
functions  similar  to  those  that  Micro¬ 
soft  C  puts  in  memory. h.  To  get  around 
this  problem,  you  can  put  surrogate 
alloc,  h  and  mem.h  files  in  with  your 
Microsoft  C  header  files.  The  alloc. h 
file  should  simply  * include  malloc.h. 
The  mem.h  will  #include  memory. h.  I 
have  not  included  listings  of  these  one- 
liners. 

A  C  Crotchet:  The  ANSI  Gotcha 

In  its  goal  to  specify  a  standard  C  lan¬ 
guage  that  is  all  things  to  all  computers, 
the  ANSI  X3J11  committee  has  faced 
some  thorny  problems.  Their  solutions 
do  not  always  provide  the  best  answer 
for  everyone.  Once  upon  a  time,  if  you 
coded  this  statement: 

char  cp  [  ]  =  "\00123"; 

you  got  a  character  array  of  four  char¬ 
acters  initialized  with  three  characters 
and  a  null  terminator.  The  first  charac¬ 
ter  was  the  binary  value  001  as  speci¬ 
fied  by  the  backslash  octal  sequence. 
The  next  two  characters  were  the  AS¬ 
CII  values  ’2’  and  ’3’. 

The  draft  ANSI  specification  says  that 
since  some  computers  have  character 
sizes  of  greater  than  eight  bits,  the  back¬ 
slash  sequence  must  allow  for  more 
than  three  digits.  Therefore,  the  state¬ 
ment  will  now  declare  a  two-character 
array  with  the  octal  value  123  (hex  53) 
followed  by  the  null  terminator.  The 
compiler’s  scan  of  digits  to  form  an 
integral  value  continues  as  long  as  the 
compiler  sees  octal  digits. 

Existing  code  can  get  broken  by  com¬ 
pilers  that  comply,  particularly  if  the 
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array  is  compiled  without  warning  mes¬ 
sages.  ANSI  makes  no  provision  for  the 
protection  of  existing  code  with  the 
changes  brought  about  by  this  new 
rule.  This  discussion  is,  therefore,  aimed 
at  those  who  might  be  changing  to  an 
ANSI-compliant  compiler.  Eventually 
that  will  include  all  of  us.  This  will  be 
part  of  the  future  ANSI  legacy,  but  let’s 
see  how  it  is  effecting  some  of  us  right 
now. 

Borland  decided  to  comply  with  this 
new  rule  of  the  standard  in  Turbo  C 
2.0.  This  decision,  I  am  told,  was  based 
on  Borland’s  commitment  to  full  com¬ 
pliance  with  the  ANSI  standard.  That 
position  is  hard  to  argue  with  even 
when  the  consequences  seem  dire.  Al¬ 
low  me  to  try. 

When  programmers  complained  that 
this  new  rule  was  breaking  existing 
code,  they  were  offered  a  workaround: 
Use  the  ANSI  string  concatenation  fea¬ 
ture,  which  works  like  this: 

char  *cp  =  "\001"  "23"; 

This,  of  course,  is  a  workaround  for 
developers  of  new  code  and  does  not 
address  the  problem  faced  by  those 
who  compile  large  systems  of  existing 
code.  ANSI  addressed  this  rule  to  solve 
portability  issues.  Some  machines  have 
6-bit  characters,  some  have  8,  some 
have  12.  Traditionally,  when  a  program¬ 
mer  ported  C  code  to  a  new  machine, 
this  was  one  of  the  portability  consid¬ 
erations.  Now,  however,  the  new  ANSI 
rule  —  or  more  specifically,  the  Borland 
compliance  with  it  —  gives  us  an  un¬ 
expected  portability  issue  and  an  un¬ 
wanted  surprise.  Programs  that  com¬ 
piled  correctly  one  way  for  years  — 
including  with  Turbo  C  1 .5  —  are  now 
not  portable  to  Turbo  C  2.0,  and  the 
compiler  issues  no  warning  and  pro¬ 
vides  no  way  to  turn  off  the  new  rule. 

The  only  error  message  associated 
with  the  original  format  occurs  when 
coincidental  octal  digits  following  the 
octal  constant  happen  to  form  an  inte¬ 
gral  value  greater  than  255.  So  if  the 
initializer  contains  “\ 00377”,  the  com¬ 
piler  says  your  code  is  correct  but  com¬ 
piles  something  other  than  what  ten 
years  of  tradition  have  conditioned  us 
to  expect.  If,  however,  the  string  is 
“\00400”  you  get  a  compile  error.  In 
the  latter  circumstance  you  can  do  some¬ 
thing  about  it.  In  the  former,  you  have 
no  clue  that  something  is  amiss  until 
the  program  stops  working. 

In  my  opinion,  a  compiler  should 
issue  a  warning  when  it  deviates  from 
tradition  in  the  name  of  ANSI.  The  warn¬ 
ing  could  be  turned  off  by  those  who 


do  not  need  or  want  to  see  it. 

Perhaps  compilers  for  computers  with 
8-bit  characters  should  ignore  the  new 
rule.  I  doubt  that  many  users  would 
complain.  That’s  right,  your  DDJ C  col¬ 
umnist  advocates  nonviolent  civil  dis¬ 
obedience  sometimes.  As  Paul  New¬ 
man  said  in  the  movie  Hud,  “I’ve  al¬ 
ways  believed  in  being  lenient  with  the 
law.  Sometimes  I  lean  one  way,  some¬ 
times  I  lean  the  other.” 

Most  PC  programs,  however,  are  writ¬ 
ten  to  execute  from  inside  a  user  inter¬ 
face  that  is  tightly  bound  to  the  archi¬ 
tecture  of  the  PC.  Our  “C  Program¬ 
ming”  column  project  is  an  example 
of  such  a  program.  The  vast  majority 
of  programs  written  in  Turbo  C  will 
never  be  ported  anywhere  other  than 
to  the  next  improved  edition  of  Turbo 
C.  I  would  guess  that  if  Borland  were 
to  offer  an  ANSI-only  version  of  the 
compiler,  there  would  be  few  takers. 

Borland’s  official  position  on  this  is¬ 
sue  is  that  the  compiler  exhibits  correct 
ANSI  behavior,  and  is,  therefore,  cor¬ 
rect.  On  the  other  hand,  Borland  is  a 
company  that  listens  to  its  users.  If 
enough  of  you  say  that  you  need  some¬ 
thing  changed,  they  will  change  it.  I 
say  we  need  a  warning  message. 

Since  version  1.0,  I  have  recom¬ 
mended  Turbo  C  without  hesitation. 
Until  this  problem  is  addressed,  how¬ 
ever,  I  suggest  caution  if  Turbo  C  2.0 
is  to  be  used  in  projects  that  involve 
large  helpings  of  existing  code.  Fortu¬ 
nately,  Turbo  C  1.5,  Microsoft  C  5.1, 
and  other  compilers  have  not  adopted 
this  rule,  so  you  have  reasonable  alter¬ 
natives  to  Turbo  C  2.0  if  this  new  rule 
will  be  a  problem. 

Other  Turbo  C  2.0  Offerings 

Turbo  C  2.0  has  a  bounty  of  new  fea¬ 
tures.  Most  notable  is  the  long-awaited 
integrated  debugger  in  the  environment. 
Borland  now  markets  a  standalone 
Turbo  Debugger  as  well,  and  Turbo  C 
programs  can  be  debugged  with  it,  too. 
If  you  get  the  Turbo  C  Professional 
package,  you  get  Turbo  C  2.0,  the  Turbo 
Debugger,  and  the  new  Turbo  Assem¬ 
bler.  Also  included  are  the  linker,  li¬ 
brarian,  make  utility,  grep,  and  a  host 
of  other  programmer’s  utility  programs. 
All  that  is  missing  is  a  multi-window, 
programmable  programmer’s  editor  in 
the  class  of  Brief  or  the  Microsoft 
Editor. 

One  new  feature  of  Turbo  C  2.0  is  a 
mixed  blessing.  Each  object  file  is  en¬ 
coded  with  the  paths  and  names  of  the 
*include  files  that  went  into  its  compi¬ 
lation.  The  Project  Make  facility  has  an 
option  called  “Auto  dependencies.” 
When  this  option  is  on,  the  make  proc¬ 
ess  checks  the  dates  of  the  files  that 
were  included  against  the  date  of  the 


object  file.  This  is  useful  in  projects 
where  the  project  make  files  might  not 
be  current.  With  this  feature  you  can 
get  pretty  sloppy  about  keeping  the 
project  make  file  up  to  date. 

Why  a  mixed  blessing?  The  embed¬ 
ded  file  names  can  increase  the  size  of 
the  object  file  significantly.  One  devel¬ 
oper  found  that  his  commercial  library 
now  required  additional  diskettes.  There 
is  an  undocumented  TUB  switch  (/0) 
for  eliminating  these  strings.  My  sources 
say  that  Borland  will  post  a  utility  to 
strip  the  path  names  from  object  files 
and  that  the  next  release  of  Turbo  C 
will  include  a  switch  to  suppress  them. 
Now  that  I  have  them,  though,  I  cannot 
do  without  them.  I  would  like  to  see 
them  used  by  the  command  line  MAKE 
utility  program. 

Bugs  in  the  version  1.5  cprintf  and 
cputs  functions  were  fixed  in  version 
2.0.  What’s  that,  you  didn’t  know  those 
functions  were  broken?  Then  you,  like 
I,  did  not  read  the  documentation,  which 
has  always  said  that  cprintf  and  cputs 
do  not  expand  the  newline  into  a  car¬ 
riage  return,  line  feed.  That’s  what  the 
documentation  said,  but  in  TC  1.5,  the 
new-line  was  expanded.  In  2.0  you 
need  to  code  \r\n  to  get  the  same 
effect  you  got  with  \n  before.  This 
keeps  the  compiler  in  synch  with  its 
documentation  and  also  with  Microsoft 
C.  TC  will  need  to  stay  close  to  MSC 
with  many  such  functions  if  they  in¬ 
tend  to  get  into  the  OS/2  game.  Many 
programmers  used  cprintf  the  way  it 
worked  rather  than  how  it  was  de¬ 
scribed  and  are  not  pleased  with  the 
change. 

Coming  up . . . 

Next  month  we  get  on  with  the  project. 
We’ll  discuss  the  weighty  subject  of 
asynchronous  communication  and  add 
serial  port  and  modem  functions  to  our 
library. 

Availability 

All  source  code  for  articles  in  this  issue 
is  available  on  a  single  disk.  To  order, 
send  $14.95  to  Dr.  Dobb’s Journal,  501 
Galveston  Dr.,  Redwood  City,  CA  94063, 
or  call  415-366-3600,  ext.  221.  Please 
specify  the  issue  number  and  format 
(MS-DOS,  Macintosh,  Kaypro). 


DDJ 


(Listings  begin  on  page  129.) 


Vote  for  your  favorite  feature/article. 
Circle  Reader  Service  No.  6. 
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EXTENDED  MEMORY 

listing  Two  (Text  begins  on  page  106.) 

mov 

shl 

ax,  cx 
ax,  1 

;  CALCULATE  MAXIMUM  TARGET  ADDRESS 

mov 

bl,  dh 

ROUTINE 

FOR  COPYING  MEMORY 

USING  PHYSICAL  ADDRESSES  ON  THE  PCAT. 

add 

ax,  di 

WRITTEN 

BY  PAUL  THOMSON. 

adc 

bl,  0 

DO  NOT  USE  THIS  ROUTINE  WITH  A  VIRTUAL  DISK  IN  EXTENDED  MEMORY. 

cmp 

bl,max  hi 

;  CHECK  IF  TARGET  ADDRESS  OUT  OF  RANGE 

jl 

Starget  ok 

jg 

Sbad  range 

.  286p 

ALLOW  286  INSTRUCTIONS 

cmp 

ax, max  lo 

code  segment 

jge 

$bad  range 

assume  cs 

code,  ds : code, es : code, ss : code 

Starget  ok 

mov 

ax,  cx 

;  CALCULATE  MAXIMUM  SOURCE  ADDRESS 

;  TEST  MOVPHY  BY  COPYING  A  MESSAGE  TO  EXTENDED  MEMORY  AND  BACK 

shl 

ax,  1 

test  proc 

near 

mov 

bl,  dl 

mov 

ax,  cs 

ALLOW  ACCESS  OF  DATA  IN  CODE  SEG 

add 

ax,  si 

mov 

ds,  ax 

adc 

bl,  0 

cmp 

bl,max  hi 

;  CHECK  IF  SOURCE  ADDRESS  OUT  OF  RANGE 

call 

extsize  ; 

FIND  TOP  OF  EXTENDED  MEMORY 

jl 

Ssource  ok 

jg 

$bad  range 

mov 

dx, offset  messl 

PRINT  MESSAGE 

cmp 

ax, max  lo 

mov 

ah,  9 

jl 

Ssource  ok 

int 

21h 

$bad  range 

mov 

ah,  4 

;  IF  ACCESSING  NON-EXISTENT  MEMORY,  RETURN 

mov 

dx,cs  ; 

CALCULATE  PHYS  ADDR  FROM  REAL  ADDR  OF  MESSAGE 
BUF 

jmp 

Sxend 

ERROR  4 

shr 

dx,  12 

SI  =  BITS  0-15,  DL  =  BITS  16-23 

Ssource  ok 

mov 

ax,  cs 

shl 

ax,  4 

cmp 

cx,  0 

;  CHECK  FOR  WORD  COUNT  TOO  BIG  OR  0 

mov 

si, offset  messl 

jg 

Swcount  ok 

add 

si,  ax 

mov 

ax,  cx 

;  RETURN  255  IF  WORD  COUNT  >  32767 

adc 

dl,  0 

jmp 

Sxend 

push 

si 

SAVE  PHYS  ADDRESS  FOR  LATER 

$wcount  ok 

push 

dx 

;  DESCRIPTORS  0, 1,4,5  ARE 

DUMMIES  (NULL) 

mov 

dh, lOh 

TOP  OF  EXTENDED  MEMORY  (lOOOOOh) 

sub 

ax,  ax 

mov 

di,  0 

DI  =  BITS  0-15,  DH  =  16-23 

mov 

gdt, ax 

;  DESCRIPTOR  0 

mov 

cx,  8 

SIZE  OF  MESSAGE  BUF  IN  WORDS 

mov 

gdt +2, ax 

call 

movphy 

MOVE  MESSAGE  TO  EXTENDED  MEMORY 

mov 

gdt+4, ax 

mov 

gdt+6, ax 

sub 

bx,  bx 

OVERWRITE  MESSAGE  BUFFER 

top: 

mov 

gdt+8, ax 

;  DESCRIPTOR  1 

mov 

al, mess2 [bx] 

mov 

gdt  +  10,  ax 

mov 

messl [bx] , al 

mov 

gdt+12, ax 

inc 

bx 

mov 

gdt+14,ax 

cmp 

bx,  16 

jl 

top 

mov 

gdt+32, ax 

;  DESCRIPTOR  4 

mov 

dx, offset  messl 

mov 

gdt+34 , ax 

mov 

gdt+36,  ax 

mov 

ah,  9 

PRINT  OVERWRITTEN  MESSAGE  BUFFER 

mov 

gdt+38, ax 

int 

21h 

mov 

gdt+40, ax 

;  DESCRIPTOR  5 

pop 

dx 

GET  PHYS  BUFFER  ADDRESS  FROM  BEFORE 

mov 

gdt+42, ax 

pop 

di 

DI  =  BITS  0-15,  DH  =  BITS  16-23 

mov 

gdt+44, ax 

mov 

dh,  dl 

mov 

gdt+46, ax 

mov 

dl, lOh 

TOP  OF  EXTENDED  MEMORY  (lOOOOOh) 

mov 

gdt+22, ax 

;  UNUSED  ENTRIES  IN  DESCRIPTOR  2 

mov 

si,  0 

DI  =  BITS  0-15,  DH  =  16-23 

mov 

gdt+30, ax 

;  UNUSED  ENTRIES  IN  DESCRIPTOR  3 

mov 

cx,  8 

SIZE  OF  MESSAGE  BUF  IN  WORDS 

mov 

ax,  cx 

;  CHANGE  WORD  COUNT  TO  BYTE  COUNT 

call 

movphy 

MOVE  MESSAGE  BACK  FROM  EXTENDED  MEMORY 

shl 

ax,  1 

mov 

gdt+16, ax 

;  BYTE  COUNT  DESCRIPTOR  2 

mov 

dx, offset  messl 

PRINT  RESTORED  MESSAGE 

mov 

gdt+24,  ax 

;  BYTE  COUNT  DESCRIPTOR  3 

mov 

ah,  9 

int 

21h 

mov 

gdt+18, si 

;  PHYSICAL  ADDRESS  TO  COPY  FROM 

mov 

al,  dl 

mov 

ah,4ch 

EXIT 

mov 

ah, 93h 

;  ACCESS  RIGHTS  BYTE 

int 

21h 

mov 

gdt +20, ax 

test  endp 

messl 

db  'ORIGINAL  MESSAGE' , Odh, Oah, ' 

mov 

gdt+26, di 

;  PHYSICAL  ADDRESS  TO  COPY  TO 

mess2 

db  'XXXXXXXXXXXXXXXX' 

mov 

al,  dh 

mov 

ah, 93h 

;  ACCESS  RIGHTS  BYTE 

;  ext  size 

-  GET  PHYSICAL  ADDRESS  OF  TOP  OF  EXTENDED  MEMORY 

mov 

gat+28, ax 

;  ADDRESS 

RETURNED  IN  max  hi, 

max  lo 

extsize  proc  near 

;  MAKE  DOS  CALL 

mov 

ah, 88h 

mov 

ah, 87h 

;  SELECT  SERVICE  87h 

int 

15h 

mov 

si, offset  gdt 

;  ES:SI=SEGMENT: OFFSET  OF  GLOBAL  DESCRIPTOR 

mov 

cx, 1024 

TABLE 

add 

ax,  cx 

int 

15h 

;  PERFORM  MEMORY  MOVE 

mul 

cx 

$xend : 

mov 

max  hi,dl 

pop 

ds 

mov 

max  lo,a;< 

ret 

ret 

extsize  endp 

gdt  dw 

2  4  dup(?) 

;  GLOBAL  DESCRIPTOR  TABLE 

max  hi 

db  ? 

max  lo 

dw  ? 

movphy  endp 

code  ends 

movphy  - 

MOVE  MEMORY  USING 

PHYSICAL  ADDRESSES 

end 

CALLED  WITH: 

dh :  di 

=  physical  24  bit  target  address. 

dl :  si 

=  physical  24  bit  source  address. 

cx  =  word  count 

STATUS  RETURNED  IN  ah: 

0:  successful  move 

1  :  RAM 

parity  error 

2:  exception  error 

3:  address  line  20  failed 

4 :  memory  out  of  range 
255:  word  count  >  32767 

End  listings 

public  movphy 
movphy  proc  near 

push 

ds 

mov 

ax,  cs 

ALLOW  ACCESS  OF  gdt  IN  CODE  SEGMENT 

mov 

ds,  ax 

mov 

es,  ax 

es  =  SEGMENT  OF  gdt  FOR  int  15h 
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STRUCTURED  PROGRAMMING 


Useful  Utilities  in  Marvelous  Modula 


Last  September  I  did  something  I’ve 
done  only  twice  before  in  dozens 
of  reviews:  gave  a  rave  to  JPI’s  TopSpeed 
Modula-2.  Now  it’s  time  to  put  it  to 
practical  use. 

With  the  spate  of  utilities  that  have 
appeared  in  this  column,  I’ve  given 
some  thought  to  taking  the  lead  from 
Peter  Norton  and  calling  them  Porter’s 
Utilities.  If  I  really  followed  Peter’s  ex¬ 
ample,  though,  I’d  have  to  abbreviate 
the  name  as  PU:  hardly  an  appealing 
prospect,  so  I  guess  they’ll  go  without 
a  name. 

At  any  rate,  this  month  we’ll  present 
three  utility  programs  that  are  genu¬ 
inely  useful  as  well  as  illustrating  some 
aspects  of  systems  programming  in 
Modula. 

Before  I  stray  too  far  from  the  Sep¬ 
tember  review,  though,  there  are  a  cou¬ 
ple  of  things  to  add.  First  is  a  correction 
to  Table  6  on  page  76.  I  reported  that 
Logitech’s  FP  run  time  with  a  coproces¬ 
sor  was  45.28  seconds.  Several  readers 
let  me  know  that  I  had  missed  an  ob¬ 
scure  passage  in  the  Logitech  docs  re¬ 
garding  linkage  with  the  proper  float¬ 
ing  point  library,  and  that  if  I  hadn’t 
overlooked  it,  the  results  would  have 
been  on  the  order  of  12  or  13  seconds. 
I  haven’t  rerun  the  benchmark,  but  one 
reader  got  results  similar  to  mine  with 
TopSpeed  and  12.5  or  thereabouts  with 
Logitech.  From  that  we  can  conclude 
that  Logitech’s  floating  point  perform¬ 
ance  with  a  coprocessor  isn’t  spectacu¬ 
lar,  but  it’s  a  whole  bunch  better  than 
I  reported  and  comparable  with  the 
others.  Sorry,  guys. 

The  Modula  review  ranked  twice  as 
high  as  the  second  runner  up  in  the 
reader  interest  survey,  and  I  got  more 
feedback  from  that  than  from  anything 
(maybe  everything)  else  I’ve  ever  writ¬ 
ten.  There’s  an  amazing  amount  of  in¬ 
terest  in  Modula-2  Out  There.  It  is  an 
up-and-coming  language  with  some 
strong  supporting  compilers,  and  it  is 
a  viable  alternative  to  C,  and  I  was 
gratified  to  find  that  a  lot  of  folks  agree 
with  me. 

Don’t  get  me  wrong,  I  like  C.  I  have 
two  advanced  C  programming  books 
coming  out  in  the  next  couple  of 


by  Kent  Porter 


months.  While  there’s  an  element  of 
shameless  commercialism  in  mention¬ 
ing  that,  there’s  also  an  implicit  en¬ 
dorsement  of  C  as  a  strong,  vibrant 
language  with  a  future.  But  frankly,  C 
makes  you  work  harder  than  you  have 


to  and  it’s  difficult  to  read  when  the 
code  gets  cold.  I  live  in  a  polyglot 
world  of  programming  languages  and 
believe  me,  life  is  easier  on  the  Pascal/ 
Modula  shores  than  it  is  on  the  C. 

All  of  which  is  a  roundabout  way  of 
getting  to  the  subject  of  this  month’s 
column. 

Utility  Number  1:  How  Much  Free 
Memory  Do  You  Have? 

Software  products  keep  getting  bigger, 
while  at  the  same  time  available  mem¬ 
ory  keeps  shrinking  as  we  find  more 
and  more  TSRs  that  we  can’t  live  with¬ 
out.  I  never  once  ran  out  of  memory 
on  my  64K  CP/M  machine  (remember 
those  days?),  but  it  happens  often 
enough  on  my  640K  AT  to  be  a  prob¬ 
lem.  Even  modern  compilers  with  their 
interactive  environments  and  dynamic 
linkers  and  integrated  debuggers  and 
such  often  require  upwards  of  400K, 
which  pushes  against  the  limits  of  a 
well-TSRed  machine. 

So  the  first  utility  in  this  group  re¬ 
ports  the  amount  of  free  memory.  It 
includes  the  space  it  occupies  in  the 
result;  that  is,  the  program  measures 
free  space  from  the  start  of  the  area  it 
occupies,  and  not  just  the  space  above 
itself. 

You  can  determine  the  beginning  of 
the  space  a  program  claims  by  getting 
the  segment  of  its  program  segment 
prefix  (PSP).  This  is  a  256-byte  data 
structure  that  DOS  builds  when  it  loads 
a  program  for  execution;  the  program 
itself  starts  immediately  above  the  PSP. 
When  the  program  terminates,  the  mem¬ 
ory  starting  with  the  PSP  becomes  free 
again. 

The  PSP  always  begins  on  a  para¬ 
graph  boundary,  a  paragraph  being  a 
1 6-byte  region  expressed  by  the  seg¬ 
ment  portion  of  the  address.  Therefore 
its  offset  is  always  zero,  and  we  know 
where  the  PSP  is  simply  by  finding  out 
its  segment. 

DOS  provides  two  ways  to  get  the 
PSP  segment.  One  is  the  undocumented 
function  51h,  and  the  other  is  function 
62h,  both  under  Int  21h.  Function  62h 
is  an  official  part  of  DOS  3  0  and  above; 


function  51h  was  the  only  way  to  get 
the  PSP  in  DOS  2.n.  The  latter  has  a 
bug  that  conflicts  with  Int  28h,  which 
is  where  DOS  hangs  out  when  it’s  look¬ 
ing  for  something  to  do.  Because  the 
MEMORY  utility  (Listing  One,  page  134) 
might  have  to  run  under  DOS  2.n,  it 
uses  function  51h.  No  danger,  since 
DOS  isn’t  idle  while  this  program  is 
running.  The  bug  is  only  a  problem 
with  TSR’s. 

The  PSPO  procedure  in  MEM¬ 
ORY.  MOD  shows  how  to  use  function 
51h  to  get  the  PSP  segment,  which  is 
returned  in  register  BX.  The  usage  for 
function  62h  is  identical,  but  of  course 
62h  doesn’t  work  under  DOS,  Version 
2.  The  PSPfj  function  returns  the  prod¬ 
uct  of  register  BX  times  16.  Why  the 
multiplication?  Because  BX  holds  the 
PSP  paragraph  segment,  so  we  multi¬ 
ply  by  1 6  to  get  the  byte  address  of  the 
PSP.  This  tells  us,  in  effect,  how  much 
memory  is  used  below  the  utility. 

The  other  critical  value  in  this  utility 
is  the  total  size  of  main  memory.  It 
happens  that  this  value  is  stored  in  the 
ROM  BIOS  data  area,  a  treasure  trove 
of  machine-specific  information  based 
at  paragraph  40h.  The  main  memory 
size,  expressed  in  K,  is  a  CARDINAL 
(unsigned  integer)  at  offset  13h.  Line 
10  in  Listing  One  shows  how  to  declare 
a  variable  at  an  absolute  location  using 
a  Modula-2  address  constructor.  The 
analogous  declaration  in  Turbo  Pascal 
would  be 

MemSize  :  WORD  ABSOLUTE 
$0040:$0013; 

The  first  statement  in  the  main  body 
of  MEMORY  casts  MemSize  to  a 
LONGCARD,  which  is  a  32-bit  unsigned 
integer,  and  multiplies  by  1024  to  con¬ 
vert  K  to  bytes.  The  rest  is  simple:  Sub¬ 
tract  the  bytes  below  the  PSP  and  re¬ 
port  the  difference,  which  is  the  free 
memory  in  the  machine. 

There  are  a  couple  of  things  to  note 
about  the  output  instructions.  First, 
Modula-2  doesn’t  have  a  catch-all,  high- 
overhead  statement  like  Pascal’s 
WriteLn,  into  which  you  can  pour  any 
number  of  parameters  of  varying  types. 
Instead,  it  has  one  output  instruction 
for  each  data  type.  This  makes  for  more 
keystrokes  to  write  a  program. 

That  leads  to  the  second  point,  which 
is  unique  to  TopSpeed  Modula-2. 
Niklaus  Wirth,  the  inventor  of  Modu¬ 
la-2,  suggests  some  module  and  proce¬ 
dure  names.  Most  Modula  implemen¬ 
tors  have  followed  Wirth’s  lead.  JPI  has 
been  criticized  for  deviating  from  these 
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recommendations,  but  their  approach 
cuts  down  on  the  number  of  keystrokes 
by  abreviating  the  Wirth  names.  For 
example,  Wirth  speaks  of  a  console 
input/output  module  called  InOut,  and 
a  routine  called  WriteString.  Under  his 
way  of  doing  things,  then,  the  state¬ 
ment  at  line  28  would  read 

InOut.WriteString  (’Available  .  . 

which  is  nine  more  keystrokes  than  in 
TopSpeed.  Multiply  this  by  all  the  con¬ 
sole  I/O  statements  in  a  typical  pro¬ 
gram  and  you  find  a  significant  differ¬ 
ence  in  the  sheer  amount  of  work  to 
write  the  source. 

Speaking  of  module  names,  notice 
the  IMPORT  list  at  line  7  in  Listing 
One.  A  Modula-2  module  has  to  ex¬ 
plicitly  import  any  libraries  it  uses.  Spe¬ 
cific  procedure  calls  are  then  bound 
to  their  supporting  library  using  dot 
notation.  This  clearly  identifies  which 
library  the  procedure  comes  from,  and 
allows  similarly-named  procedures  to 
co-exist.  For  example,  both  IO  and  FIO 
(the  file  I/O  library)  furnish  a  WrStr 
procedure.  You  specify  which  you  mean 
through  the  dot  notation.  There’s  also  a 
way  of  importing  specific  elements  from 
a  library  to  avoid  use  of  this  verbose 
dot  notation;  lines  9  and  52  -  53  in 
Listing  Three,  page  134,  illustrate  how. 

MEMORY  is  a  handy  utility  to  keep 
in  your  toolbox.  Run  it  any  time  you 
need  to  find  out  how  much  free  mem¬ 
ory  you  have.  Also,  you  can  run  it 
before  and  after  loading  a  TSR  to  learn 
how  much  memory  the  TSR  actually 
grabs. 

Utility  Number  2:  What  Are  The 
Subdirectories  ? 

The  DOS  DIR  command  and  the  SUB 
utility  I  published  in  this  column  a  few 
months  back  both  list  subdirectories, 
but  not  exclusively;  they’re  sprinkled 
randomly  among  other  files,  which 
makes  them  hard  to  spot.  Often  in  the 
past  I  used  to  start  up  something  like 
XTREE  simply  to  find  out  what  subdi¬ 
rectories  were  hanging  off  a  specific 
directory.  When  that  eventually  got  on 
my  nerves  enough,  I  wrote  SD.MOD, 
shown  in  Listing  Two,  page  134. 

Put  SD.EXE  somewhere  along  your 
PATH.  Then,  wherever  you  are,  you 
can  type  SD  and  the  program  will  list 
only  the  subdirectories  in  the  current 
directory.  Unlike  a  DOS  shell  or  the 
DOS  TREE  utility,  SD  doesn’t  list  the 
children  of  those  subdirectories.  It  con¬ 
cedes  that  capability  for  the  benefits 
of  being  fast  and  requiring  no  command¬ 
line  arguments. 

SD  relies  heavily  on  the  DOS  findfirst/ 
findnext  functions  (4Eh  and  4Fh  under 
Int  21h).  These  functions  are  Siamese 


twins.  Findfirst  locates  the  first  instance 
of  a  filename  pattern  with  a  given  file 
attribute  and  builds  a  data  structure. 
Findnext  uses  this  data  structure  to  step 
through  the  remainder  of  the  current 
directory,  on  each  call  pulling  out  the 
next  file  entry  that  satisfies  the  para¬ 
meters. 

In  TopSpeed  Modula-2,  these  DOS 
functions  are  sugar  coated  with  Modula 
syntax  as  ReadFirstEntry  and  ReadNext- 
Entry,  and  are  located  in  the  FIO  li¬ 
brary.  They  return  TRUE  if  the  call  is 
successful  and  FALSE  otherwise.  The 
involved  data  structure  is  of  type  Dir- 
Entry,  also  from  FIO.  Thus  lines  15  -  16 
in  Listing  Two  make  the  first  call,  and 
then  a  loop  begins  at  line  17.  This  loop 
will  not  execute  if  ReadFirstEntry  failed 
to  find  a  match.  In  fact,  for  reasons 
we’ll  discuss  shortly,  the  loop  will  al¬ 
most  always  execute  at  least  twice  de¬ 
spite  its  structure.  Within  the  loop’s 
scope  is  the  call  to  ReadNextEntry, 
which  also  returns  a  Boolean  to  the 
Found  variable  controlling  the  loop. 
Thus  the  loop  reiterates  until  Read¬ 
NextEntry  runs  out  of  directory  entries 
satisfying  the  criteria  in  the  DirEntry 
structure. 

Note  the  parameters  for  ReadFirstEn¬ 
try.  They  specify,  in  order,  the  pattern 
to  look  for,  the  file  attribute(s),  and  the 
name  of  a  DirEntry  object.  The  attrib¬ 
utes  are  a  set  of  type  FileAttr  defined 
in  FIO.  The  names  describe  the  possi¬ 
ble  file  attributes:  readonly,  hidden,  sys¬ 
tem,  volume,  directory,  and  archive. 
In  the  case  of  SD,  we  want  to  look  only 
for  entries  that  have  the  directory  at¬ 
tribute,  so  that’s  the  only  set  member 
we  pass  to  ReadFirstEntry  as  an  argu¬ 
ment. 

The  underlying  DOS  functions  have 
a  “feature,”  or  in  other  words  a  fairly 
well-known  bug  that  the  vendor  doesn’t 
intend  to  fix.  The  bug  is  that,  even 
when  you  specify  the  directory  attrib¬ 
ute  alone,  the  functions  return  not  only 
directory  entries,  but  also  all  normal 
(read/write)  file  entries.  For  that  rea¬ 
son,  it’s  necessary  to  check  the  result 
in  the  attr  field  of  the  DirEntry  structure 
to  make  sure  it  has  a  directory  attribute. 
That’s  the  purpose  of  line  18.  It  screens 
the  results,  allowing  only  legitimate  di¬ 
rectories  to  be  processed  further. 

Every  DOS  subdirectory  (that  is,  every 
directory  except  the  root)  has  the  two 
entries  '.’  and  referring  to  the  cur¬ 
rent  directory  and  its  parent,  respec¬ 
tively.  That  explains  why  the  loop  be¬ 
ginning  at  line  17  will  execute  at  least 
twice;  the  only  exception  is  when  SD 
is  looking  at  the  root  of  an  empty  disk. 
Because  the  existence  of  these  entries 
is  a  given,  there’s  no  reason  to  list 
them.  Consequently  the  IF  at  line  19 
filters  them  out. 


SD  is  one  of  those  little  utilities  that 
you  quickly  come  to  take  for  granted 
because  it’s  so  useful  and  such  a  natu¬ 
ral  extension  of  DOS.  Here  it  does  dou¬ 
ble  duty,  because  it  also  lays  the  ground¬ 
work  for  the  much  more  complex  di¬ 
rectory  search  utility  discussed  next. 

Utility  Number3:  Where  is ...  ? 

The  final  program  in  this  set  is 
WHERE. MOD  (Listing  Three).  This  util¬ 
ity  searches  the  entire  directory  struc¬ 
ture  of  a  disk,  reporting  the  location  of 
every  entry  that  satisfies  a  pattern. 

The  pattern  can  be  any  combination 
of  literal  and  wildcard  characters.  For 
example,  if  you  want  to  know  the  loca¬ 
tion  of  every  file  with  the  extension 
.  OLD ,  type 

WHERE,  OLD 
or 

WHERE  ‘.OLD 

Similarly,  to  find  all  files  whose  names 
have  AU  as  the  first  two  characters, 
type 

WHERE  AU* 
or 

WHERE  AU*.* 

Note  that,  unlike  Modula-2  itself,  the 
pattern  is  not  case  sensitive.  You  can 
list  specific  filenames  if  you  remember 
what  the  file  is  called  but  not  where  it 
is.  The  command  is  also  useful  for  chas¬ 
ing  down  unnecessary  instances  of  a 
file,  as  in 

WHERE  COMMAND.COM 

In  response  to  the  command,  WHERE 
lists  each  instance  of  a  matching  file, 
showing  the  drive,  directory  path,  and 
filename. 

WHERE  can  also  search  other  drives. 
If  you’re  running  off  drive  C  and  you 
want  to  find  all  the  dBase  files  on  drive 
D,  type 

WHERE  D:.DBF 
or 

WHERE  D:*.DBF 

The  utility  interprets  the  command 
line  argument  to  see  if  it  contains  a 
drive,  and  performs  the  necessary  drive 
change  when  it  does.  It  also  completes 
wildcards,  which  is  why  some  of  the 
example  commands  have  two  forms. 

And  if  you  don’t  furnish  a  command¬ 
line  argument,  WHERE  asks  you  for 
the  pattern  with  the  query  Filename? 

The  main  body  of  WHERE  begins 
by  finding  out  the  current  directory 
and  drive.  This  information  is  needed 
in  order  to  restore  the  user’s  environ¬ 
ment  when  the  program  quits.  The  next 
step  is  to  get  the  command-line  argu- 
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ment  or,  if  not  present,  ask  for  it. 

The  code  beginning  at  line  119  inter¬ 
prets  the  search  pattern.  When  the  sec¬ 
ond  character  is  a  colon,  the  program 
knows  that  the  first  character  is  a  drive 
designator,  so  it  converts  the  letter  into 
its  numeric  DOS  equivalent  (where 
0  =  A,  1  =  B,  etc.).  Having  done  that,  it 
selects  the  new  drive  and  shifts  the 
pattern  left  to  form  a  driveless  pattern. 
(Note  that  the  program  doesn’t  recog¬ 
nize  a  subdirectory  as  a  starting  point; 
all  searches  proceed  from  the  root,  so 
a  pattern  containing  a  directory  path 
won’t  produce  meaningful  results.) 

The  output  list  will  contain  the  drive 
prefix  d:\  where  d  is  a  drive  name. 
This  string  is  contructed  starting  at 
line  134. 

Lines  140-146  patch  in  wildcards  as 
needed.  For  example,  if  the  user  typed 

WHERE  .BAK 

this  routine  translates  the  pattern  into 
'.BAK  and,  if 

WHERE  SALES 

into  the  pattern  SALES. *.  There  is  a  dis¬ 
tinction,  by  the  way,  between  patterns 
such  as  SALES  and  SALES*.  If  you  type 
the  first,  the  program  reports  only  files 
with  SALES  as  the  base  name,  and  skips 
those  such  as  SALESREP.XYZ.  The  pat¬ 
tern  SALES*  finds  the  latter,  because  it 
gets  translated  into  SALES*.  * 

With  all  the  preliminaries  out  of  the 
way,  the  program  can  now  undertake 
the  search.  This  always  begins  at  the 
root  and  progresses  through  the  entire 
directory  structure,  checking  every  sin¬ 
gle  file  entry  on  the  disk.  Line  149 
initiates  the  search. 

The  SearchDir  procedure  is  recur¬ 
sive.  That  is,  it  calls  itself,  passing  the 
name  of  a  child  directory  to  search.  A 
level  of  recursion  thus  exists  for  each 
level  in  the  generations  of  subdirecto¬ 
ries.  When  a  child  directory  has  been 
completely  searched,  the  procedure  re¬ 
turns  to  the  parent  level.  When  all  di¬ 
rectories  have  been  visited,  the  root 
level  returns  to  the  main  program’s 
cleanup  routines  starting  at  line  151. 
Here’s  how  it  works  in  more  detail. 

SearchDir  begins  by  changing  to  the 
directory  it  was  passed  as  a  parameter, 
and  reconstructing  the  full  pathname 
including  drive  for  reporting  purposes. 
It  then  searches  the  current  directory 
for  any  entry  satisfying  the  pattern.  The 
names  of  matching  entries  are  listed 
on  the  display.  When  the  matching  en¬ 
try  is  a  subdirectory,  this  first  phase 
merely  reports  the  name  suffixed  with 
<DIR>;  it  doesn’t  actually  branch  to 
that  directory  yet. 


That’s  what  the  second  phase  start¬ 
ing  at  line  66  does.  When  all  entries  in 
the  directory  have  been  checked,  line 
67  starts  over  again,  scanning  specifi¬ 
cally  for  subdirectories  much  as  SD 
does.  However,  here  the  loop  issues  a 
recursive  call  to  SearchDir,  passing  the 
name  of  the  subdirectory.  This  call  sus¬ 
pends  the  parent  invocation  of  Search¬ 
Dir  and  restarts  the  procedure  with 
different  data  needed  to  search  the 
child  directory.  This  process  continues 
through  the  children  of  the  children. 
Eventually  all  lines  of  inquiry  along  the 
path  are  exhausted,  and  the  child  level 
returns  to  the  parent  level  at  line  71. 
The  child  invocations  changed  the  cur¬ 
rent  directory,  so  line  71  restores  the 
parent  directory  and  continues  the  loop 
seeking  other  child  paths  to  search. 
When  it  runs  out  of  directories,  it  re¬ 
turns  to  its  parent  level  of  recursion, 
and  so  on  until  eventually  control  re¬ 
turns  to  the  main  program  at  line  151, 
thus  ending  the  program  run. 

Note  how  the  screen  output  is  con¬ 
trolled.  Line  49  displays  the  full  name 
of  the  path  currently  being  searched. 
When  a  match  occurs,  lines  55-60  add 
the  filename  and  advance  to  the  next 
display  row,  where  line  6l  again  shows 
the  current  path.  Often  a  path  contains 
no  matches,  and  even  when  it  does, 
eventually  it  runs  out  of  them.  In  either 
case,  the  next  invocation  of  SearchDir 
calls  ClrSol  from  line  48.  This  routine 
erases  the  name  of  the  old  exhausted 
path  and  overlays  it  with  the  next. 

ClrSol  (for  clear  to  start  of  line)  does 
this  by  using  yet  another  field  in  the 
ROM  BIOS  data  area.  When  it  gets  con¬ 
trol,  the  cursor  is  winking  at  the  end 
of  the  current  path,  which  might  be  of 
any  length.  Offset  50  contains  the  cur¬ 
rent  cursor  column  in  video  page  0,  the 
default  video  buffer  for  WHERE.  The 
procedure  learns  where  the  cursor  is 
by  checking  this  absolute  variable.  It 
then  backs  up  the  cursor,  replacing 
each  position  with  a  space,  until  the 
cursor  is  in  column  0,  the  left  margin 
of  the  display  area.  Line  49  can  then 
write  a  fresh  string  indicating  the  new 
search  path  without  worrying  about 
excess  baggage  left  over  from  a  longer 
line  previously  occupying  the  same  row. 
Similarly,  the  code  beginning  at  line 
151  erases  the  last  fruitless  path  to  re¬ 
port  the  number  of  matches  found. 

TopSpeed  Modula-2  includes  a  com¬ 
prehensive  high-level  module  called  Win¬ 
dow,  providing  for  advanced  screen 
control.  The  TopSpeed  interactive  en¬ 
vironment  itself  was  written  using  the 
Window  module.  However,  Window 
takes  more  control  of  the  display  than 
I  deemed  desirable  for  this  program. 
For  example,  the  first  call  to  any  Win¬ 
dow  routine  clears  the  display  and  sets 


the  default  text  color  to  bright  white.  I 
preferred  that  WHERE  have  the  appear¬ 
ance  of  standard  DOS  utilities,  which 
is  why  I  devised  the  ClrSol  routine. 

So  there  you  have  three  useful  utili¬ 
ties  and  a  hands-on  demonstration  of 
Modula-2  in  action.  Like  C,  Modula  is 
a  language  inherently  capable  of  em¬ 
bracing  the  full  spectrum  of  program¬ 
ming  requirements,  from  low-level  sys¬ 
tems  utilities  to  advanced  applications. 

Handing  Over  the  Reins 

We  all  mourn  the  demise  of  Turbo  Tech- 
nix :,  Borland’s  excellent  programming 
magazine.  Yet,  even  bad  things  have 
positive  results.  One  of  them  is  that 
we  were  able  to  recruit  Mike  Floyd  to 
come  to  work  for  DDJ  as  technical  edi¬ 
tor.  Another  is  that  it  freed  Technix’ 
editor-in-chief,  Jeff  Duntemann,  to  take 
over  this  column. 

Jeff  needs  little  introduction  to  struc¬ 
tured  programming  devotees.  Through 
his  work  at  PC  Tech  Journal  and  Turbo 
Technix ,  as  well  as  several  authorita¬ 
tive  books,  Jeff  has  had  a  substantial 
impact  on  the  art  of  structured  pro¬ 
gramming.  Indeed,  one  might  fairly  de¬ 
scribe  him  as  Mr.  Pascal.  He’s  also  an 
accomplished  Modula  programmer,  and 
a  superlative  writer.  Consequently,  I 
leave  the  column  in  capable  hands. 

Doing  this  column  for  the  past  year 
has  been  a  lot  of  fun  and  earned  me 
many  new  friends.  Had  Technix  not 
shut  down  and  made  Jeff  available,  I 
would  gladly  have  continued  with  it. 
But  for  a  long  time  I’ve  had  a  fantasy 
about  doing  a  graphics  programming 
column.  Cosmic  forces  created  the  op¬ 
portunity,  and  we  decided  to  go  for  it. 

You  may  not  have  noticed,  but  DDJ 
has  been  putting  on  weight.  The  num¬ 
ber  of  articles  is  up,  and  by  changing 
the  typeface  we’re  able  to  get  more 
content  on  each  page.  These  factors 
have  created  the  space  to  run  another 
column  and  still  keep  the  article  count 
at  its  historic  high. 

So  starting  next  month,  you’ll  find 
Jeff  Duntemann  here  and  I’ll  be  launch¬ 
ing  an  expedition  into  the  magical  world 
of  graphics  programming.  See  you  there. 

Availability 

All  the  source  code  for  articles  in  this 
issue  is  available  on  a  single  disk.  To 
order,  send  $14.95  to  Dr.  Dobb’s  Jour¬ 
nal,  501  Galveston  Dr.,  Redwood  City, 
CA  94063,  or  call  415-366-3600,  ext. 
221.  Please  specify  issue  number  and 
format  (MS-DOS,  Macintosh  Kaypro). 

DDJ 

(Listings  begin  on  page  134.) 

Vote  for  your  favorite  feature/article. 

Circle  Reader  Service  No.  7. 
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Paradigms  Past  and  Future 


This  issue  marks  the  beginning  of 
the  14th  year  of  continuous  publi¬ 
cation  for  Dr.  Dobb’s  Journal.  That 
makes  this  the  13th  anniversary  issue, 
and  in  honor  of  the  occasion  I  offer 
this  Janus  view  of  the  paradigms  of 
programming,  past  and  future.  As  you 
know,  this  is  just  the  sort  of  schmaltzy 
occasion  on  which  writers  feel  free  to 
indulge  in  the  most  shameless  journal¬ 
istic  excesses:  homespun  anecdotes,  ro- 
manticizations  of  the  past,  prognostica¬ 
tions  on  the  future,  and  filling  space 
with  other  people’s  words. 

“The  more  often  a  problem  has  been 
solved  on  a  desk  machine,  the  more 
certain  it  is  that  the  methods  developed 
need  reexamining  before  translation  into 
a  computer  programme.”  — R.K.  Lives- 
ley,  An  Introduction  to  Automatic  Digi¬ 
tal  Computers ,  1957. 

R.K.  Livesley,  in  his  little  book  about 
programming  the  Manchester  computer 
in  the  1950s,  cautions  the  reader  that 
some  of  our  favorite  desk  calculator 
algorithms  may  be  ridiculously  inap¬ 
propriate  when  implemented  on  a  com¬ 
puter.  His  book  was  one  of  the  first  to 
discuss  programming  techniques.  I  some¬ 
how  overlooked  its  sound  advice,  and 
similar  advice  in  thousands  of  program¬ 
ming  books  over  the  succeeding  dec¬ 
ades,  and  had  to  leam  the  lesson  the 
hard  way. 

The  Runaway  Algorithm: 

A  True  Story 

In  the  mid-70s,  I  was  a  graduate  stu¬ 
dent  picking  up  some  extra  money  writ¬ 
ing  statistical  analysis  programs  in  For¬ 
tran  for  faculty  members  and  other  gradu¬ 
ate  students.  All  the  conventional  stud¬ 
ies  lent  themselves  to  analysis  with  the 
standard  statistical  packages  such  as 
SPSS,  so  the  jobs  I  was  picking  up  were 
all  a  little  unusual. 


by  Michael  Swaine 


One  day  a  graduate  student  brought 
me  a  magtape  full  of  data  and  a  book 
with  an  equation  circled  and  asked 
me  to  apply  the  latter  to  the  former.  I 
set  to  work  implementing  the  algo¬ 
rithm  that  the  equation  implied,  tested 


it  on  very  small  data  sets  against  hand 
calculation  from  the  book  equation, 
scrutinized  boundary  conditions,  pro¬ 
nounced  the  program  ready,  and  turned 
in  the  tape  to  be  loaded. 

Insufficient  memory.  I  banged  my 
head  against  “insufficient  memory”  mes¬ 
sages  far  too  long  — probably  because 
after  seven  years  on  campus  I  knew 
too  many  tricks  for  “finding”  more  core 
in  the  university’s  computer  system  — 
before  I  finally  did  some  calculations 
and  convinced  myself  that  the  data  set 
I  was  working  with  was  not  too  large 
for  my  core  allotment.  I  could  load  the 
entire  input  data  set  into  memory,  as 
well  as  all  the  output  matrices.  Be¬ 
tween  input  and  output,  something  was 
eating  memory  like  a  Core  Wars  cham¬ 
pion.  At  that  point  I  saw  what  should 
have  been  obvious  from  the  outset: 
that  the  book  equation  made  use  of 
huge  sparse  matrices,  ballooning  the 
data  out  before  collapsing  it  back  to 
manageable  size  at  output.  It  was  sim¬ 
ply  an  inappropriate  algorithm  for  com¬ 
puter  implementation. 

So,  having  learned  my  lesson,  I  re¬ 
worked  the  equation  and  everything 
was  fine  — at  least  until  the  student’s 
dissertation  committee  discovered  that 
her  analysis  was  based  on  my  unpub¬ 
lished  (therefore  suspect)  version  of 
the  equation.  There  was  a  lesson  in 
that,  too,  but  I’m  not  sure  I  ever  really 
learned  it. 

But  that’s  how  I  learned  the  lesson 
about  the  need  to  recast  the  algorithm 
closer  to  the  machine’s  desire.  When  I 
acquired  my  first  personal  computer  a 
couple  of  years  later  (a  TRS-80  Model 
with  Basic  in  ROM  and  4K  of  user 
RAM),  the  first  thing  I  wrote  for  it  was 
a  set  of  sparse-matrix  collapsing  rou¬ 
tines.  Just  in  case  I  had  to  do  some 
heavy  statistical  analysis. 


Beyond  Space  and  Time 

“The  Ural  II  was  exactly  like  a  personal 
computer  because  it  was  just  you  and 
the  machine.  .  .  .  With  4K  of  memory 
and  the  slow  speed,  it  was  very  similar 
to  the  Altair,  which  was  introduced  in 
1974.  The  excitement  I  experienced  with 
the  Ural  II  in  1964  was  the  same  kind 
of  excitement  that  Bill  Gates  experi¬ 
enced  with  the  Altair  in  1974.”  — Char¬ 
les  Simonyi,  in  Programmers  at  Work 
by  Susan  Lammers. 

My  TRS-80  experience  was  well  into 
the  personal  computer  era.  You  could 
do  a  lot  with  4K  of  memory  if  you  had 
Basic  in  ROM.  It  was  harder  earlier. 
Charles  Simonyi  gave  himself  headaches 
programming  in  octal  absolute  on  that 
Ural  II.  And  who,  besides  a  hacker  like 
Bill  Gates,  would  have  attempted  to 
write  a  Basic  interpreter  for  the  Altair 
back  in  1975?  A  bunch  of  hackers,  that’s 
who. 

Toward  the  close  of  1975,  when  the 
typical  personal  computer  programmer 
was  someone  who  had  a  friend  across 
town  with  an  Altair,  the  San  Francisco 
Bay  Area-based  People’s  Computer  Com¬ 
pany  had  a  runaway  project  on  its 
hands.  It  wasn’t  an  unusual  situation; 
the  group  was  filled  with  creative,  en¬ 
ergetic,  intelligent  people  who  were 
fired  up  by  the  possibilities  of  comput¬ 
ers  for  empowering  individuals,  and 
had  lots  of  projects  to  pursue.  The  group 
was,  after  all,  an  offshoot  of  the  same 
group  that  produced  the  Whole  Earth 
Catalog,  subtitled  Access  to  Tools. 

The  runaway  project  was  a  portable 
Basic  interpreter  that  would  run  in  the 
remarkably  small  memory  space  of  the 
Altair,  or  on  one  of  the  other  micro¬ 
computers  then  being  designed.  It  was 
the  famous  Tiny  BASIC,  brainchild  and 
bandwagon  of  Dennis  Allison  and  Bob 
Albrecht,  and  raison  detreof  this  maga¬ 
zine  in  its  early  days. 

Those  early  days  began  in  January 
1976,  and  the  magazine  was  originally 
titled  Dr.  Dobb’s  Journal  of  Tiny  BASIC 
Calisthenics  and  Orthodontia  (Running 
Light  without  Overbyte ).  The  title  said 
it  all  (a  title  that  long  had  better  say  it 
all):  memory  is  tight,  and  code  must 
be  equally  tight.  Dr.  Dobb’s  readers 
and  writers  (then,  as  now,  overlapping 
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sets)  were  spending  a  lot  of  time  re¬ 
casting  their  algorithms  closer  to  the 
machine’s  desire.  And  what  the  ma¬ 
chine  desired  was  tight  code,  memory- 
frugal  algorithms.  It  was  a  time  for  run¬ 
ning  light  without  overbyte. 

It’s  always  that  time.  Dr.  Dobb’s  sub¬ 
head  could  still  be  Running  Light  with¬ 
out  Overbyte.  It’s  a  paradoxical  fact  of 
programming  life  that  memory  space 
remains  precious,  efficiency  remains 
valuable,  no  matter  how  much  RAM 
you  have.  It’s  one  of  the  two  funda¬ 
mental  resources:  The  truism  among 
programmers  is  that  the  only  commodi¬ 
ties  are  time  and  space.  Cycles  and 
core.  Ticks  and  bits.  And  in  some  times 
and  in  some  places,  the  truism  is  the 
only  relevant  truth. 

Environmental  Action 

Elsewhen  and  -where,  though,  it  be¬ 
comes  appropriate  to  pay  more  atten¬ 
tion  to  the  human  commodity:  The  pro¬ 
grammer.  Rather  than  focusing  exclu¬ 
sively  on  the  program  and  efficiencies 
with  regard  to  its  operation,  to  look  at 
overall  effectiveness  of  the  program¬ 
ming  effort.  To  allocate  programming 
effort  economically.  It’s  not  a  new  idea, 
of  course. 

I’m  always  pitching  the  importance 
of  knowing  many  paradigms.  That’s 
the  subtext  (at  least)  of  this  column. 
I’m  not  alone  in  promoting  this.  One 
reason  often  put  forth  is  that  the  sepa¬ 
rate  streams  of  existing  paradigms  are 
currently  converging.  It’s  not  entirely 
clear  whether  the  streams  are  converg¬ 
ing,  though  some,  say,  C.  The  truth  is 
probably  not  so  simple.  In  fact,  it  may, 
to  muddy  the  metaphor,  be  more  co¬ 
agulation  than  convergence. 

In  any  case,  things  are  getting 
clumpier.  Nobody  wants  to  sell  you  a 
compiler  anymore.  What  you  need,  you 
are  told,  is  an  environment.  Well,  you 
probably  do;  who  am  I  to  scoff.  But 
“environments”  are  more  complicated 
than  compilers,  and  one  of  the  ways 
in  which  they  show  signs  of  getting 
further  complicated  is  in  terms  of  sup¬ 
port  for  different  paradigms,  and  that’s 
my  beat. 

The  future  in  C  programming  envi¬ 
ronments,  for  example,  seems  to  in¬ 
clude  a  C++  front  end.  C  programmers 
can  use  C++  to  work  in  an  object- 
oriented  paradigm  without  quite  leav¬ 
ing  C,  and  while  there  may  be  argu¬ 
ments  about  whether  C++  is  fully  object- 
oriented,  it  certainly  brings  in  non¬ 
procedural  programming  considera¬ 
tions:  Moving  from  C  to  C++  requires 
a  paradigm  shift. 

Two  products  that  have  come  across 


my  desk  recently,  neither  of  which  is  a 
programming  language,  but  both  of 
which  include  programming  languages, 
seem  particularly  catholic  in  their  em¬ 
bracing  of  alternative  paradigms.  These 
are  Mathematica  from  Wolfram  Research 
in  Champaign,  Ill.  and  HyperBase  from 
Cogent  Software  in  Framingham,  Mass. 

Mathematica  is  an  environment  for 
doing  mathematics.  It  is  designed  to 
run  on  many  machines,  notably  the 
Sun,  Macintosh,  and  NeXT  machines. 
It  handles  the  basically  arithmetic  cal¬ 
culations  that  spreadsheets  know  how 
to  do,  but  it  also  solves  algebraic  and 
calculus  problems.  You  can  integrate 
a  function  symbolically  or  numerically. 
It  supports  arbitrary  precision  math. 
And  it  embodies,  according  to  its  crea¬ 
tor,  Stephen  Wolfram,  several  different 
programming  paradigms. 

As  a  procedural  language,  Mathema¬ 
tica  supplies  the  syntactic  elements  if, 
while,  and  for  to  direct  flow  of  control, 
as  well  as  the  dreaded  goto.  But  the 
language  is  more  effectively  used  as  a 
functional  language  like  Lisp  or  APL. 
The  thought  processes  that  go  on  when 
building  a  functional  program  are  dif¬ 
ferent  from  those  behind  procedural 
development.  Functional  programming 
makes  little  use  of  control  structures 
or  named  variables.  In  fact,  Mathema¬ 
tica  encourages  eliminating  names  even 
for  functions.  Functional  programs  can 
look  extremely  concise: 

exprod[n_Integer]  :=  Expand!  Prod¬ 
ucts  +  i,  (i,  n}]  ]. 

Possibly  the  most  powerful  paradigm 
supported  by  Mathematica,  though,  is 
rule-based  programming.  This  paradigm 
allows  the  programmer  to  build  a  data¬ 
base  of  rules  like  these  mathematical 
rules  for  differentiation: 

diff(x^n,x)  =  nxA(n-l) 
diff(log(x),x)  =  1/x. 

This  technique  brings  with  it  a  dis¬ 
tinctly  nonprocedural  approach  to  pro¬ 
gramming.  It’s  easy,  using  this  approach, 
to  develop  a  program  by  a  process  of 
successive  approximations  to  the  ulti¬ 
mate  program.  You  simply  add  rules 
to  deal  with  additional  cases. 

An  even  more  disorienting  paradigm, 
from  the  procedural  point  of  view,  is 
the  approach  of  constraint  propaga¬ 
tion.  In  this  approach  (supported  by 
Mathematica)  you  specify  constraints 
that  variable  must  satisfy,  but  don’t  tell 
the  program  how  to  satisfy  them.  Con¬ 
straints  like 

va  =  =  vo  rl  /  (rl  +  r2) 
va  =  =  vi 
g  =  =  vo  /  vi 


make  no  assumptions  about  the  direc¬ 
tion  of  the  relationships  they  define. 
The  solve  function  does  its  best  to  pull 
a  solution  out  of  the  constraints.  This 
approach  has  similarities  with  using  a 
spreadsheet,  but  with  fewer,  constraints 
on  the  form  of  the  constraints.  Spread¬ 
sheets  in  effect  implement  linear  con¬ 
straints,  but  Mathematica  lets  you  de¬ 
fine  non-linear  dependencies  among 
variables. 

Both  the  rule-based  and  constraint 
propagation  approaches  sound  like 
logic  programming  a  la  Prolog,  and  in 
fact  Mathematica  supports  something 
like  the  logic  programming  paradigm. 
It  differs,  though,  in  being  more  di¬ 
rected,  more  explicit,  in  the  order  in 
which  it  tries  its  rules. 

Another  consequence  of  Mathema- 
tica’s  aggressive  ordering  of  its  rules 
shows  up  in  its  implementation  of  re¬ 
cursion.  A  recursive  solution  to  a  prob¬ 
lem  always  consists  of  at  least  one  re¬ 
cursive  (self-invoking)  condition  and 
at  least  one  non-recursive,  terminal  con¬ 
dition.  Mathematica  lets  you  drop  these 
conditions  in  as  independent  rules,  like 

factorial[n_Integer]  := 

n  factorials  -1] 

factorial!  1]  =  1, 

without  worrying  about  the  order  in 
which  the  mles  should  be  applied.  Mathe¬ 
matica  understands  enough  about  re¬ 
cursion  to  recognize,  usually,  the  ter¬ 
minal  condition  and  to  apply  it  first. 

HyperBase  is  a  system  for  creating, 
what  its  author  calls,  intelligent  docu¬ 
ments.  It  runs  on  MS-DOS  machines. 
Intelligent  documents  are  text  and  graph¬ 
ics  documents  with  attached  code.  The 
code  is  associated  with  elements  of  the 
text  or  areas  of  the  graphic  images,  and 
when  the  code  effects  jumps  to  other 
nodes  in  the  document,  the  system  can 
be  described  as  an  implementation  of 
HyperText.  But  the  code  can  be  pretty 
much  anything,  including  commands 
that  modify  the  text  and  graphics,  in 
which  case  the  system  can  be  described 
as  an  adaptive  document.  The  underly¬ 
ing  language  is  a  full  Prolog  system. 

The  result  is  a  system  that  feels  on 
the  surface  something  like  a  word  proc¬ 
essor,  and  something  like  HyperCard 
or  Owl  International’s  Guide,  while  dig¬ 
ging  deeper  into  the  product  takes  you 
squarely  into  logic  programming.  That’s 
got  to  be  a  paradigmatic  jolt. 


DDJ 


Vote  for  your  favorite  feature/article. 
Circle  Reader  Service  No.  9. 
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C  PROGRAMMING 


Listing  One  (Text  begins  on  page  111.) 

/* - microsft.h - */ 

/*  #include  this  file  at  the  end  of  window. h  */ 

#if  COMPILER  ==  MSOFT 

/*  this  line  replaces  the  select_window  prototype  in  window. h  */ 
int  select_window (int,  int,  int,  int  (*) (int, int) ) ; 

♦define  setmem(bf,sz,c)  memset (bf , c, sz) 

♦define  movmem(fr,to. In)  memmove (to, fr, In) 

♦define  cprintf  wprintf 
♦define  cputs(s)  wprintf (s) 

♦define  putch(c)  wputch(c) 

♦define  getchO  wgetch() 

void  window(int  If, int  tp,int  rt,int  bt); 

void  puttext(int  If, int  tp,int  rt,int  bt,char  *sv) ; 

void  gettext(int  If, int  tp,int  rt,int  bt,char  *sv) ; 

void  movetext(int  If,  int  tp,  int  rt,  int  bt,  int  lfl,  int  tpl); 

void  gotoxy(int  x,int  y) ; 

void  textcolor (int  cl); 

void  textbackground(int  cl); 

int  wherex (void) ; 

int  wherey (void) ; 

void  wprintf (char  *,  ...); 

void  wputch(int  c) ; 

int  wgetch (void) ; 


void  window (int  If, int  tp,int  rt,int  bt) 

{ 

wlf  =  If; 
wtp  =  tp; 
wrt  =  rt; 
wbt  =  bt; 

_video.snow  =  (char  )  SNOW; 

) 

/* - makes  a  video  offset  from  x,y  coordinates - */ 

♦define  vaddr(x,y)  ( ( (y) -1) *160+ ( (x) -1) *2) 

/*  —  makes  far  pointer  to  video  RAM  from  x,y  coordinates  —  */ 

void  far  *  pascal  _ vptr(int  x,  int  y) 

{ 

void  far  *vp; 

FP_SEG (vp)  =  VSEG; 

FP_OFF(vp)  =  vaddr(x,y); 
return  vp; 


/*  -  writes  a  block  of  memory  to  video  ram  -  */ 

void  pascal  _ vram(int  far  *vp,  int  far  *bf,  int  len) 


while  (len — )  { 

vpoke (VSEG,  FF_OFF(vp),  *bf++)  ; 
vp++; 

} 


BLACK  0 
BLUE  1 
GREEN  2 
CYAN  3 
RED  4 
MAGENTA  5 
BROWN  6 
LIGHTGRAY  7 
DARKGRAY  8 
LIGHTBLUE  9 
LIGHTGREEN  10 
LIGHTCYAN  11 
LIGHTRED  12 
LIGHTMAGENTA  13 
YELLOW  14 
WHITE  15 


/*  -  gets  a  block  of  memory  from  video  ram  -  */ 

void  pascal  _ getvram(int  far  *vp,  int  far  *bf,  int  len) 

{ 

while (len — )  { 

*bf++  =  vpeek (VSEG,  FP_OFF(vp)); 
vp++; 


/*  -  writes  a  memory  block  to  a  video  window  -  */ 

void  puttext(int  If, int  tp,int  rt,int  bt,char  *sv) 

( 

while  (tp  <  bt+1)  { 

_ vram( _ vptr(lf,  tp) ,  (int  far  *)  sv,  rt+l-lf ) ; 

tp++; 

sv  +=  (rt+l-lf) *2; 


Listing  Two 


End  Listing  One 


microsft.c - */ 


Surrogate  Turbo  C  functions 
for  Microsoft  C  users. 


/* - reads  a  memory  block  from  a  video  window - */ 

void  gettext(int  If, int  tp, int  rt,int  bt,char  *sv) 

{ 

while  (tp  <  bt+1)  { 

_ getvram( _ vptr(lf,  tp) ,  (int  far  *)  sv,  rt+l-lf); 

tp++; 

sv  +«  (rt+l-lf) *2; 

) 

} 


♦include  <dos.h> 
♦include  <string.h> 
♦include  <stdio.h> 
♦include  <stdarg.h> 
♦include  <ctype.h> 
♦include  <conio.h> 
♦include  <bios.h> 


♦define  MDA  1 
♦define  CGA  2 
♦define  EGA  3 
♦define  VGA  4 

♦define  ADAPTER  EGA 

♦if  ADAPTER==MDA 
♦define  VSEG  OxbOOO 
♦else 

♦define  VSEG  0xb800 
♦endif 


One  of  these  is  your  Display  Adapter 


/*  Monochrome  Display  Adapter  */ 
/*  Color  Graphics  Adapter  */ 
/*  Enhanced  Graphics  Adapter  */ 
/*  Video  Graphics  Array  */ 

/*  Specifies  the  Display  Adapter 


VSEG  is  the  video  memory  segment  */ 


♦if  ADAPTER==CGA 
♦define  SNOW  1 

/*  -  assembly  language  vpeek. asm:  manages  CGA  flicker  */ 

void  vpoke (unsigned  adr,  unsigned  off,  int  ch) ; 
int  vpeek (unsigned  adr,  unsigned  off); 

♦  else 

♦define  SNOW  0 

/*  -  macros  for  vpeek  and  vpoke  for  non-CGA  systems  -  */ 

♦define  MKFP(s,o)  ( ( (long)  s«16)  |o) 

♦define  vpoke(a,b,c)  (*((int  far*)MKFP (a,b) )=c) 

♦define  vpeek (a, b)  (*((int  far* ) MKFP (a,b) ) ) 

♦endif 

static  union  REGS  rg; 

/*  -  a  structure  defined  within  Turbo  C  and  used  by  us  -  */ 

struct  ( 

char  f illerl [4] ; 

char  attribute;  /*  saves  the  current  video  attribute  */ 
char  filler2 [5] ; 

char  snow;  /*  says  if  the  adapter  snows  */ 

}  _video; 

static  int  wlf , wtp, wrt, wbt;  /*  current  window  corners  */ 
static  int  wx,wy;  /*  current  window  cursor  */ 


/*  -  moves  a  video  window  (used  for  scrolling)  -  */ 

void  movetext(int  If,  int  tp,  int  rt,  int  bt,  int  lfl,  int  tpl) 
( 

int  nolines  =  bt  -  tp  +  1; 
int  incr  =  tp  -  tpl; 
int  len,  i; 
unsigned  src,  dst; 

if  (tp  >  tpl)  { 
src  =  tp; 
dst  =  tpl; 

) 

else  { 

src  =  bt; 

dst  =  tpl+nolines-1; 

} 

while  (nolines — )  { 

len  =  rt  -  If  +  1; 
for  (i  =  0;  i  <  len;  i++) 

vpoke (VSEG,  vaddr(lfl+i,  dst), 

vpeek (VSEG, vaddr (lf+i,  src))); 
src  +=  incr; 
dst  +=  incr; 

} 


position  the  window  cursor 


void  gotoxy(int  x,int  y) 

{ 

wx  =  x; 
wy  =  y; 
rg.h.ah  =  15; 
int86(16,  &rg,  Srg) ; 
rg.x.ax  =  0x0200; 
rg.h.dh  =  wtp  +  y  -  2; 
rg.h.dl  =  wlf  +  x  -  2; 
int86{16,  &rg,  &rg); 


/*  -  return  the  window  cursor  x  coordinate  -  */ 

int  wherex (void) 


/*  -  return  the  window  cursor  y  coordinate  -  */ 

int  wherey (void) 

{ 


define  a  video  window  -  */ 


(continued  on  page  13V 
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C  PROGRAMMING 


Listing  Two  ( Listing  continued,  text  begins  on  page  111.) 

return  wy; 


/*  -  sets  the  window  foreground  (text)  color 

void  textcolor (int  cl) 


_video. attribute  =  (_video. attribute  &  OxfO)  |  (cl&Oxf); 


/*  -  sets  the  window  background  color 

void  textbackground(int  cl) 


_video. attribute  =  (_video. attribute  &  0x8f)  |  ((cl£7)«4); 


void  writeline (int,  int,  char  *); 


/*  -  our  substitution  for  MSC  cprintf  — 

void  wprintf(char  *ln,  ...) 

{ 

char  dlin  [81],  *dl  =  dlin,  ch; 
int  cl  [81],  *cp  -  cl; 
va_list  ap; 

va_start (ap,  In) ; 
vsprintf (dlin.  In,  ap); 
va_end(ap) ; 

while  (*dl)  ( 

ch  =  (*dl++  &  255); 
if  ( ! isprint (ch) ) 
ch  =  '  ' ; 

*cp++  =  ch  |  (_video. attribute  «  8); 

} 

_ vram ( _ vptr (wx+wlf-1, wy+wtp-1) , 

(int  far  *)  cl,  strlen (dlin) ) ; 
wx  +=  strlen (dlin) ; 


/*  -  our  substitution  for  MSC  putch 

void  wputch(c) 

i 

if  ( lisprint (c) ) 
putch (c) ; 
wprintf ("%c",  c) ; 


/* - our  substitution  for  MSC  getch 

int  wgetch(void) 


static  unsigned  ch  =  Oxffff; 

if  ( (ch  &  Oxff)  ==  0)  { 

ch++; 

return  (ch  »  8)  &  0x7f; 

) 

ch  =  _bios_keybrd (_KEYBRD_READ ) ; 
return  ch  &  0x7 f; 


End  Listing  Two 


Listing  Three 


-  vpeek.asm  - 

dosseg 

. model  compact 
.code 

public  _vpoke 

-  insert  a  word  into  video  memory 

vpoke(vseg,  adr,  ch) ; 

unsigned  vseg;  /*  the  video  segment  address  */ 

unsigned  adr;  /*  the  video  offset  address  */ 

unsigned  ch;  /*  display  byte  &  attribute  byte  */ 


_vpoke 

proc 

push 

bp 

mov 

bp,  sp 

push 

di 

push 

es 

mov 

cx,  4 [bp] 

;  video  board  base  address 

mov 

es,  cx 

mov 

di, 6 [bp] 

;  offset  address  from  caller 

mov 

dx, 986 

;  video  status  port  address 

loopl ; 

in 

al,dx 

;  wait  for  retrace  to  quit 

test 

al,  1 

jnz 

loopl 

loop2 : 

in 

al,  dx 

;  wait  for  retrace  to  start 

test 

al,  1 

jz 

loop2 

mov 

ax,  8 [bp] 

;  word  to  insert 

stosw 

;  insert  it 

pop 

es 

pop 

di 

pop 

bp 

ret 

_vpoke 

endp 

public  _vpeek 

-  retrieve  a  word  from  video  memory 


;  vpeek (vseg,  adr) ; 

;  unsigned  vseg;  /* 

;  unsigned  adr;  /* 

the  video  segment  address  */ 
the  video  offset  address  */ 

_vpeek 

proc 

push 

bp 

mov 

bp,  sp 

push 

si 

push 

ds 

mov 

si,  6 [bp] 

;  offset  address 

mov 

cx,  4 [bp] 

;  video  board  base  address 

mov 

ds,  cx 

mov 

dx, 986 

;  video  status  port  address 

loop3 : 

in 

al,dx 

;  wait  for  retrace  to  stop 

test 

al,  1 

jnz 

loop3 

loop4 : 

in 

al,  dx 

;  wait  for  retrace  to  start 

test 

al,  1 

jz 

loop4 

lodsw 

;  get  the  word 

pop 

ds 

pop 

si 

pop 

bp 

ret 

_vpeek  endp 
end 

Listing  Four 


End  Listing  Three 


#  TWRP.MAK  —  make  file  for  TWRP.EXE  with  Microsoft  C/MASM 

* 

.c.obj: 

Cl  /DCOMPILER=MSOFT  -c  -W3  -Gs  -AC  $*.c 

twrp.obj  :  twrp.c  editor. h  help.h  window. h 

editshel.obj  :  editshel.c  editor. h  menu.h  entry. h  help.h  \ 
window. h  microsft.h 

editor. obj  :  editor. c  editor. h  window. h  microsft.h 

entry. obj  :  entry. c  entry. h  window. h  microsft.h 

menu. obj  :  menu.c  menu.h  window. h  microsft.h 

help. obj  :  help.c  help.h  window. h  microsft.h 

window. obj  :  window. c  window. h  microsft.h 

microsft.obj  :  microsft.c 

vpeek.obj  :  vpeek.asm 
masm  /MX  vpeek; 

twrp.exe  :  twrp.obj  editshel.obj  editor. obj  entry. obj  menu. obj  help. obj  \ 
window. obj  microsft.obj  vpeek.obj 
cl  twrp  editshel  editor  entry  menu  help  window  microsft  vpeek 


End  Listings 
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STRUCTURED 

PROGRAMMING 


Listing  One  (Text  begins  on  page  120.) 

1|  MODULE  Memory; 

21 

3 |  (*  Reports  amount  of  memory  available,  excluding  this  program 
4 j  (*  JPI  TopSpeed  Modula-2 
5 |  (*  K.  Porter,  DDJ,  January  '89 
61 

7 |  IMPORT  SYSTEM,  10,  Lib; 

8| 

9 |  VAR  MainMem,  MemUsable  :  LONGCARD; 

10 |  MemSize  [0040H  :  0013H]  :  CARDINAL; 

HI  (*  - 


PROCEDURE  PSPO  :  LONGCARD; 
VAR  Reg  :  SYSTEM. Registers; 


(*  Return  byte  address  of  PSP 


BEGIN 

Reg. AH  ;=  51H;  (*  Undocumented:  same  as  62H  but  works  in  DOS  2.n  *) 

Lib.Intr  (Reg,  21H) ; 

RETURN  (LONGCARD  (Reg.BX)  *  16); 

END  .PSP; 


BEGIN 

MainMem  :=  LONGCARD  (MemSize)  *  102 
MemUsable  :=  MainMem  -  PSP(); 
IO.WrStr  ('Available  memory  is  '); 
IO.WrLngCard  (MemUsable,  1); 
IO.WrStr  ('  bytes'); 

IO.WrLn; 

END  Memory. 


(*  Total  memory  in  bytes  *) 


End  Listing  One 


Listing  Two 


(*  Lists  all  subdirectories  in  the  current  directory  *) 
(*  JPI  TopSpeed  Modula-2  *) 

(*  K.  Porter,  DDJ,  January  '89  *) 

IMPORT  FIO,  10; 

VAR  F  :  FIO.DirEntry; 

Found  :  BOOLEAN; 

Count  :  CARDINAL; 

BEGIN 

Count  : =  0 ; 

Found  :=  FIO.ReadFirstEntry  ("*.*", 

FIO.FileAttr  (FIO. directory ) ,  F) ; 

WHILE  Found  DO 

IF  FIO. directory  IN  F.attr  THEN 
IF  F .Name [0]  #  ' .'  THEN 

IO.WrStr  (F .Name) ;  IO.WrLn; 

INC  (Count); 

END; 

END; 

Found  :=  FIO.ReadNextEntry  (F) ; 

END; 

IO.WrCard  (Count,  1); 

IO.WrStr  ('  directories  found'); 

IO.WrLn; 

END  sd. 


End  Listing  Two 


Listing  Three 

1|  MODULE  Where; 


(*  Searches  directory  structure  from  the  root,  listing  all  occur- 
(*  rences  of  a  filename  matching  the  search  argument 
(*  JPI  TopSpeed  Modula-2 
(*  K.  Porter,  DDJ,  January  '89 

IMPORT  FIO,  IO,  SYSTEM,  Lib,  Str; 

FROM  FIO  IMPORT  FileAttr,  readonly,  hidden,  system,  directory, 
archive; 

TYPE  string  =  ARRAY  [0..79]  OF  CHAR; 

CONST  DefaultDrive  =  0; 

Backspace  =  CHR(8); 

VAR  arg,  curdir,  xfer  :  string; 

DriveName  :  ARRAY  [0..3]  OF  CHAR; 

count,  p,  s,  d  :  CARDINAL; 
curdrive,  newdrive  :  SHORTCARD; 

cx  [40H: 50H]  :  SHORTCARD;  (*  ROM  BIOS  cursor  col 


PROCEDURE  ClrSol; 

BEGIN 

WHILE  cx  #  0  DO 

IO.WrChar  (Backspace); 
IO.WrChar  ('  '); 
IO.WrChar  (Backspace); 
END; 

END  ClrSol; 


(*  Clear  from  cursor  to  start  of  line 


PROCEDURE  SearchDir  (Path  :  ARRAY  OF  CHAR) ; 

(*  Recursive  directory  search  routine 

VAR  F  :  FIO.DirEntry; 

WholePath  :  string; 

Found  :  BOOLEAN; 


BEGIN 

FIO.ChDir  (Path);  (*  Set  directory 

FIO.GetDir  (DefaultDrive,  WholePath);  (*  Get  full  pathname 

Str.Concat  (WholePath,  DriveName,  WholePath);  (*  Add  drive 

ClrSol;  (*  Clear  to  start  of  line 

IO.WrStr  (WholePath);  (*  List  directory 

(*  Search  for  filename  matches  in  this  directory  *) 

Found  :=  FIO.ReadFirstEntry  (arg,  FileAttr  (readonly,  hidden, 
system,  directory,  archive),  F) ; 

WHILE  Found  DO 

IF  Str. Length  (WholePath)  >  3  THEN  IO.WrChar  ('\')  END; 

IO.WrStr  (F .Name) ; 

IF  directory  IN  F.attr  THEN 
IO.WrStr  ("  <DIR>") ; 

END; 

IO.WrLn;  (*  New  line 

IO.WrStr  (WholePath); 

INC  (count);  (*  Count  occurrence 

Found  :=  FIO.ReadNextEntry  (F) ;  (*  Get  next  match 

END; 


(*  Now  recursively  search  any  subs  under  this  directory  *) 

Found  :=  FIO.ReadFirstEntry  ("*.*",  FileAttr  (directory),  F) ; 

WHILE  Found  DO 

IF  (directory  IN  F.attr)  AND  (F.Name[0]  #  '.')  THEN 

SearchDir  (F.Name);  (*  Recursive  call  *) 

FIO.ChDir  (WholePath);  (*  Restore  dir  to  this  level  *) 

END; 

Found  :=  FIO.ReadNextEntry  (F) ;  (*  Do  next  sub  *) 

END; 

END  SearchDir; 

(* - - - - *> 

PROCEDURE  GetDriveO  :  SHORTCARD;  (*  Get  currently  active  drive  *) 

VAR  Reg  :  SYSTEM. Registers; 

BEGIN 

Reg. AH  :=  19H; 

Lib.Intr  (Reg,  21H)  ; 

RETURN  (Reg. AL) ; 

END  GetDrive; 

(* - - - *) 

PROCEDURE  SetDrive  (Drive  :  SHORTCARD);  (*  Set  default  drive  *) 

VAR  Reg  :  SYSTEM. Registers; 

BEGIN 

Reg. AH  :=  OEH; 

Reg.DL  :=  Drive; 

Lib.Intr  (Reg,  21H)  ; 

END  SetDrive; 

(* - - - - - *) 

BEGIN  (*  Main  body  of  WHERE  *) 


(*  Initialize  *) 

FIO.GetDir  (0,  curdir);  (*  Remember  where  we  are  *) 

curdrive  :=  GetDriveO;  (*  and  drive  *) 

count  :=  0; 

FOR  p  :=  0  TO  3  DO  DriveName [p]  :=  CHR(O)  END; 

(*  Get  the  name  to  search  for  *) 

IF  Lib . ParamCount ( )  >  0  THEN 
Lib.ParamStr  (arg,  1); 

ELSE 

IO.WrStr  ("Filename?  "); 

IO.RdStr  (arg) ; 

END; 

(*  Select  another  drive,  strip  out  designator  if  necessary  *) 

IF  arg[l]  =  ' THEN 

DriveName [0]  :=  CAP  (arg[0]); 

newdrive  :=  SHORTCARD  (ORD  (CAP  (arg(OJ))  -  ORD  ('A')); 

SetDrive  (newdrive);  (*  Set  new  drive  *) 

IF  arg [2]  =  'V  THEN  s  :=  3  ELSE  s  :=  2  END; 
d  :=  0; 

FOR  p  :=  s  TO  Str. Length  (arg)  DO  (*  Strip  out  drive  designator  *) 
xfer [d]  :=  arg [p] ; 

INC  (d)  ; 

xfer [d]  :=  CHR  (0); 

END; 

Str. Copy  (arg,  xfer);  (*  Copy  back  to  arg  *) 

END; 

(*  Build  name  of  target  drive  *) 

IF  DriveName [0]  =  CHR(0)  THEN 

DriveName [0]  :=  CHR  (curdrive  +  65) 

END; 

Str.Concat  (DriveName,  DriveName,  ":\"); 

(*  Add  wildcard  prefix/suffix  as  necessary  *) 

IF  arg [0]  =  ' .'  THEN 

Str.Concat  (arg,  "*",  arg);  {*  Stick  in  wildcard  prefix  *) 

END; 

IF  Str.Pos  (arg,  ".")  =  MAX  (CARDINAL)  THEN 

Str.Concat  (arg,  arg,  ".*");  (*  Append  wildcard  suffix  *) 

END; 

(*  Begin  search  at  root  *) 

SearchDir  ("\"); 

(*  Report  matches  found  *) 

ClrSol; 

IO.WrCard  (count,  1) ; 

IO.WrStr  ("  matches  found"); 

IO.WrLn; 

(*  Restore  user's  original  environment  *) 

SetDrive  (curdrive) ; 

FIO.ChDir  (curdir);  ,  _  , 

end  where.  End  Listings 


End  Listings 
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PROGRAMMER'S  SERVICES 


OF  INTEREST 


Software 

BrainMaker,  a  neural  network  simula¬ 
tion  program,  has  been  introduced  by 
California  Scientific  Software.  Brain- 
Maker  is  a  system  for  designing,  build¬ 
ing,  training,  testing,  and  running  neu¬ 
ral  networks. 

Using  BrainMaker,  users  can  build 
networks  that  do  optical  character  rec¬ 
ognition,  speech  synthesis,  and  control 
systems  applications.  Programmers  can 
also  use  BrainMaker  to  investigate  re¬ 
search  topics  such  as  speech  recogni¬ 
tion  and  artificial  vision. 

BrainMaker  runs  at  up  to  500,000 
neural  connections  per  second  and  has 
I/O  facilities  for  visual  or  symbolic  data 
manipulation.  Menu-driven  with  color 
and  mouse  support,  BrainMaker  comes 
with  sample  neural  networks  including 
optical  character  recognition,  speech 
synthesis,  image  recognition,  image  en¬ 
hancement,  and  Tic-Tac-Toe. 

This  product,  which  sells  for  $99.95, 
requires  an  IBM  PC  or  compatible  with 
256K  memory,  a  monochrome  or  color 
display,  and  PC-DOS  or  MS-DOS  3.0 
or  later.  Reader  Service  No.  20. 
California  Scientific  Software 
160  E  Montecito  Ave.,  #E 
Sierra  Madre,  CA  91024 
818-355-1094 

Cognitive  Software  has  released  two 
products:  Cognitron,  Version  1.1,  a  neu¬ 
ral  network  development  tool;  and  Cog- 
nitron  Prime  1.0  for  use  with  INMOS 
T800  transputers.  These  products  are 
development  environments  for  creat¬ 
ing  networks  of  processing  units  and 
connections.  According  to  Cognitive  Soft¬ 
ware,  neural  networks  developed  on 
the  Cognitron  can  solve  problems  such 
as  forms  of  diagnosis,  problems  in  eco¬ 
nomics,  project  planning,  best  choice, 
financial  analysis,  and  forecasting. 

Features  of  these  products  include 


simulated  parallel  processing,  graphi¬ 
cal  3-D  modeling  window  with  net¬ 
working  tools,  editing  window  for  pro¬ 
gramming  the  processing  units  and 
weights  between  units,  supporting  win¬ 
dows  and  dialogues,  Lisp  subset  for 
use  in  programming  units  and  weights, 
graphical  user  interface,  and  simula¬ 
tion  engine. 

The  Cognitron  1.1  is  designed  to  run 
on  the  Macintosh  Plus,  Macintosh  SE, 
and  Macintosh  II.  Cognitron  1.1  sells 
for  $600,  and  Cognitron  Prime  1.0  is 
priced  at  $1,800.  Educational  discounts 
and  group  pricing  are  available.  Reader 
Service  No.  21. 

Cognitive  Software  Inc. 

703  E  30th  St.,  Ste.  7 
Indianapolis,  IN  46205 
317-924-9988 

Software  Artistry  has  released  PC  Ex¬ 
pert,  a  system  development  environ¬ 
ment  for  Microsoft  C,  Turbo  C,  JPI 
Modula-2,  and  Logitech  Modula-2  com¬ 
pilers.  The  name  of  the  product  has 
been  changed  from  Turbo  Expert,  the 
original  version  that  supported  only 
Turbo  Pascal  4.0.  PC  Expert  consists 
of  a  library  module  containing  an  infer¬ 
ence  engine  that  can  be  embedded  in 
applications  developed  with  one  of  the 
supported  compilers. 

According  to  Software  Artistry,  the 
inference  engine  takes  up  less  than 
64K  of  code  space  yet  offers  features 
such  as  backward  chaining,  demons, 
agendas,  non-monotonic  reasoning,  trac¬ 
ing,  data  and  time  arithmetic,  and  com¬ 
munication  between  the  inference  en¬ 
gine  and  the  other  parts  of  the  program 
in  which  it  is  embedded.  Facilities  are 
included  to  interrupt  a  consultation 
when  a  value  is  needed,  return  control 
to  the  host  program  to  obtain  that  value, 
and  then  resume  the  consultation. 

Software  Artistry  also  offers  a  graph¬ 
ics  package  that  can  be  used  to  create 
a  graphical  front-end  for  expert  sys¬ 
tems  or  other  projects.  The  graphics 
package  includes  a  memory-resident 
program  that  can  be  used  to  capture 
images  created  with  commercial  paint 
programs  and  then  display  them  dur¬ 
ing  a  consultation.  The  package  also 
includes  routines  to  animate  images, 
display  graphical  gauges  and  dials,  and 
add  on  mouse  support. 

PC  Expert  and  the  add  on  graphics 
package  are  $99. 95  each.  Reader  Serv¬ 
ice  No.  22. 

Software  Artistry 
3500  DePauw  Blvd.,  Ste.  2021 
Indianapolis,  IN  46 268 
317-876-3042 


Utilities 

C-DOC,  a  collection  of  tools  that  ana¬ 
lyze  and  document  C  programs,  has 
been  introduced  by  Software  Black¬ 
smiths.  C-DOC  modifies  programs  to 
include  both  caller/ called  hierarchy  docu¬ 
mentation  and  global/local/parameter 
identifier  documentation  in  each  pro¬ 
cedure  header. 

The  product  also  displays  caller/ 
called  hierarchy  tree  diagrams  show¬ 
ing  interaction  of  procedures,  produces 
table  of  contents  files  versus  proce¬ 
dures,  documents  both  procedure  and 
system  usage  of  local/global  identifi¬ 
ers,  produces  both  summary  and  de¬ 
tailed  documentation,  modifies  pro¬ 
grams  (adjusts  indentation)  to  reflect 
their  logic/control  structure  (and  op¬ 
tionally  adjusts  comment  alignment), 
and  lists  programs  with  optional  graphic 
action  diagrams  of  logic  structure. 

C-DOC  requires  an  IBM  PC  or  com¬ 
patible;  PC/MS-DOS,  Version  2.x  or  3x, 
256K  memory  minimum  (640K  recom¬ 
mended);  and  independent  of  the  C 
compiler  used.  C-DOC,  which  includes 
four  programs,  sells  for  $99.  Reader 
Service  No.  23. 

Software  Blacksmiths  Inc. 

6064  St.  Ives  Way 

Mississauga,  Ont.  Canada  L5N  4M1 
416-858-4466 

Edward  K.  Ream  has  begun  shipping 
Sherlock,  a  productivity  tool  that  works 
to  trace,  debug,  and  profile  C  programs. 
Sherlock  consists  of  C  language  mac¬ 
ros  and  support  routines  called  by  these 
macros.  The  macros  are  inserted  with 
a  separate  tool  (included  with  Sher¬ 
lock),  and  the  macros  contain  tracing 
and  debugging  code  that  lies  dormant 
until  enabled  during  the  execution  of 
the  program. 

Sherlock  can  be  used  during  coding, 
testing,  and  maintenance  phases  of  pro¬ 
gramming  and  will  work  with  Micro¬ 
soft,  Turbo  C,  or  any  full  C  compiler. 
Programs  containing  Sherlock  macros 
may  also  be  debugged  using  traditional 
debuggers.  Sherlock  can  also  be  used 
with  C++  compilers  that  produce  C  lan¬ 
guage  output. 

Sherlock,  which  sells  for  $195,  counts 
how  many  times  each  macro  is  en¬ 
countered  and  measures  the  time  spent 
in  functions.  It  comes  with  three  utility 
programs:  The  SPP  program  inserts  mac¬ 
ros  into  a  file,  the  SDEL  program  re¬ 
moves  all  Sherlock  macros  from  a  file, 
and  the  SDIF  compares  a  file  contain¬ 
ing  Sherlock  macros  to  a  file  without 
them.  Reader  Service  No.  24. 

Edward  K.  Ream 
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1617  Monroe  St. 

Madison,  WI  53711 
800-922-4763 

SLR  Systems  has  added  a  linker  and 
debugger  to  the  OPT  group  of  devel¬ 
opment  tools.  OPTL1NK  is  a  program 
linker  that  works  with  modules  in  Intel 
OMF  format  (.OBJ  files),  including  those 
generated  by  the  standard  SLR  IBM  as 
well  as  Microsoft  assemblers  and  com¬ 
pilers.  OPTDEBUG  is  a  source  level 
debugger  that  provides  the  program¬ 
mer  with  eight  display  types.  These 
two  products  are  priced  at  $125  each. 

Another  new  product  is  OPTLIB/2, 
an  object  module  librarian  that  can  cre¬ 
ate  and  maintain  master  indexed  files 
or  libraries  in  the  OS/2  environment. 
OPTLINK/R  works  in  the  protected 
mode  of  OS/2  and  generates  real  mode 
.EXE  files. 

SLR  Systems  has  also  announced  an 
update  to  its  macro  assembler,  OPTASM. 
The  new  version,  1.6,  adds  two  new 
utilities:  OLINK  and  ODEBUG.  OP¬ 
TASM,  Version  1.6,  sells  for  $125.  Reader 
Service  No.  25. 

SLR  Systems 
1622  N  Main  St. 

Butler,  PA  16001 
412-282-0864 


Neural  Nets 

The  BRAIN  simulator,  announced  by 
Abbot,  Foster  &  Hauserman  for  IBM 

PCs,  simulates  a  neural  circuit  array  on 
MS-DOS.  By  emulating  a  small  section 
of  a  human  brain,  the  program  gives 
users  an  understanding  of  how  neuron 
circuitry  works. 

Included  with  the  program  are  sev¬ 
eral  examples  of  the  types  of  circuitry 
that  can  be  created  with  the  neural 
model,  including  simple  switching,  mem¬ 
ory,  and  pattern-recognition  circuitry. 
An  accompanying  booklet  explains  the 
operation  of  biological  neurons  and 
describes  how  they  are  emulated  by 
the  program. 

The  BRAIN  Simulator  implements  an 
array  of  1,200  neurons  using  a  digital 
model  of  the  human  brain  neuron  de¬ 
veloped  by  the  Neural  Network  Labo- 
Iratory.  A  network  of  neurons  is  repre¬ 
sented  on  the  CRT;  when  a  neuron 
fires,  its  CRT  location  flashes. 

Users  can  modify  the  sample  net¬ 
works  or  define  new  ones.  Using  a 
mouse  to  indicate  a  particular  neuron, 
users  can  display  the  existing  synaptic 
connections  and  add  or  delete  new 
ones.  Neurons  can  be  forced  to  fire  the 
established  initial  conditions  or  emu¬ 
late  the  input  of  a  visual  image.  This 


software  is  available  for  $99.  Reader 
Service  No.  26. 

Abbot,  Foster  &  Hauserman  Co. 

44  Montgomery  St.,  5th  Floor 
San  Francisco,  CA  94101 
415-955-2711 
800-562-0025 


Miscellaneous 

Turbo  Plus  5.5  for  Turbo  Pascal  5.0  is 
now  available  from  Nostradamus. 
Turbo  Plus  is  a  professional  develop¬ 
ment  package  for  Turbo  Pascal  pro¬ 
grammers.  One  of  its  new  features  is 
display  mapping,  which  allows  the  user 
to  create  entry  screens  with  multi¬ 
ple  fields  using  direct  memory-map¬ 
ping  techniques. 

The  display-mapping  procedures  in¬ 
clude  features  for  I/O  control;  edit 
masks,  field  highlighting  with  color  bars, 
and  insert/overwrite  modes;  delete  key; 
arrow  keys;  and  home  and  end  keys. 
I/O  mapping  supports  all  Turbo  Pascal 
data  types  including  extended  floating¬ 
point  numbers.  Numeric  I/O  fields  can 
be  handled  as  decimal,  hexadecimal, 
or  scientific  notation  format.  Version 
5.5  also  has  display  map  user  interven¬ 
tion  routines  that  gain  control  on  every 
key  pressed  for  user  control  of  exit 
keys,  cursor  positioning,  keyboard  re¬ 
direction,  and  keyboard  status. 

Screen  Genie,  the  screen  painter  in¬ 
cluded  with  Turbo  Plus,  has  been  up¬ 
graded  to  include  support  for  screen, 
window,  and  menu  libraries.  Library 
support  is  also  available  to  program¬ 
mers  as  part  of  the  programming  tools. 

Turbo  Genie  — the  included  source 
code  generator  for  compiling  screens, 
windows,  and  menus  into  the  .EXE 
file  — has  been  upgraded  to  support 
libraries.  In  addition,  painted  screens, 
windows,  and  menus  can  now  be  used 
in  bit  mapped  graphics  CGA,  EGA,  and 
VGA  modes,  as  well  as  text  modes. 

Over  70  new  routines  have  been 
added  to  the  Turbo  Plus  package,  in¬ 
cluding  new  graphics  routines  for  sav¬ 
ing  and  loading  .PCX  and  .PCC  files. 
Turbo  Plus  5.5  sells  for  $149.95;  current 
users  of  Turbo  Plus  5.0  can  upgrade 
for  $50.  Reader  Service  No.  27. 
Nostradamus  Inc. 

3191  S  Valley  St.,  Ste.  252 
Salt  Lake  City,  UT  84109 
801-487-9662 

Logical  Systems  has  released  the 
Transputer  Toolset,  which  provides  a 
C  and  assembly  language  development 
environment  for  the  INMOS  transputer 
family.  It  works  with  a  single  transputer 
or  a  transputer  network. 
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The  toolset  provides  optimization  fa¬ 
cilities  and  conformance  to  the  ANSI  C 
standard.  In  addition  to  supporting  fea¬ 
tures  specific  to  the  various  models  of 
transputers,  the  product  is  provided  in 
source  code  format. 

The  toolset  facilitates  C  code  genera¬ 
tion  for  programmers  developing  par¬ 
allel  and  embedded  system  applica¬ 
tions.  The  transputer,  a  32-bit  parallel 
processing  chip,  has  been  implemented 
in  products  such  as  image  systems,  com¬ 
puter  graphics,  industrial  control,  ro¬ 
botics,  workstation  and  PC  accelerator 
boards,  and  supercomputers. 

The  toolset  includes  a  C  compiler, 
assembler,  linker,  librarian,  and  both  a 
single  processor  and  network  loader. 
The  compiler  supports  in-line  assem¬ 
bly  language  and  optionally  generates 
in-line  code  for  the  C  functions  that 
map  into  the  transputer  instruction  set. 
The  compiler  can  generate  code  for 
the  64-bit/32-bit  ANSI  floating  point 
model  or  32-bit  only  floating-point  (or 
a  mixture). 

The  toolset  is  portable  across  MS- 
DOS,  Apple  Mac  II  (under  both  MPW 
and  LSC),  and  SYS5/BSD4.3  Unix  sys¬ 
tems,  including  Apollo,  Sun,  and  DEC. 
The  C  library  contains  both  transputer 
runtime  routines  and  host  interface  fa¬ 
cilities.  Host  I/O  is  provided  by  three 
standard  servers,  which  handle  file  and 
system  I/O. 

The  $995  price  includes  six  months 
of  support  and  updates.  Reader  Service 
No.  29. 

Logical  Systems 
P.O.  Box  1702 
Corvallis,  OR  97339 
503-753-9051 

Cobalt  Blue  has  announced  the  re¬ 
lease  of  a  Xenix  version  of  FOR_C,  a 
Fortran  to  C  translator  running  under 
MS-DOS.  FOR_C  converts  standard  For- 
tran-77  into  ANSI  C,  and  MILSPEC  ex¬ 
tensions  are  supported. 

FOR_C,  Version  2.1,  incorporates  im¬ 
provements  to  I/O  translations;  for  ex¬ 
ample,  list  directed  WRITES  are  trans¬ 
lated  to  /print/ s  and  unformatted  I/O 
is  translated  to  /prtun/  and  /scanun/ 
unformatted  equivalents  to  their  C  coun¬ 
terparts.  Do  loops  are  reduced,  and 
function  arguments  are  checked  for  con¬ 
sistent  usage  and  can  be  passed  either 
by  value  or  by  address. 

With  C  runtime  source,  FOR_C  is 
priced  at  $750;  with  binary  runtime  (for 
Turbo  C  or  Microsoft  C),  the  price  is 
$550.  The  new  Xenix  version,  with  run¬ 
time  source  for  both  ANSI  C  and  Unix 
System  V,  is  priced  at  $975.  Both  pack¬ 
ages  include  six  months  technical  sup¬ 


port  and  free  upgrades.  Reader  Service 
No.  30. 

Cobalt  Blue 
2940  Union  Ave.,  Ste.  C 
San  Jose,  CA  95124 
408-723-0474 

The  release  of  REM86,  a  remote  target 
debugger  for  the  Future86  language, 
has  been  announced  by  Development 
Associates.  The  REM86  extension  com¬ 
pletes  the  Future86  development  envi¬ 
ronment,  and  it  works  in  both  hosted 
or  targeted  environments  for  80x8x  CPU 
and  related  CPU  families. 

REM86  consists  of  a  target  monitor 
(written  in  Future86)  that  is  less  than 
2K  bytes.  The  remaining  part  of  REM86 
is  the  host  control  program  that  is  func¬ 
tionally  similar  (but  extended)  to  FDT86, 
the  Future86  host  debugger. 

This  product  supports  a  patching  as¬ 
sembler,  file  loading,  disassembler,  im¬ 
mediate  execution  assembler,  high- 
level  definition  creation/execution,  sin¬ 
gle  stepping,  breakpoints,  and  sym¬ 
bolic  debugging  and  control. 

REM86  is  supplied  with  sample  moni¬ 
tor  driver  source  code  for  both  the  NEC 
V25  DDK  and  the  Vesta  Technologies 
Micro  88  boards.  Also  included  is  sam¬ 
ple  application  source  code.  Selling  for 
$479,  REM86  requires  Future86.  Reader 
Service  No.  31. 

Development  Associates 
1520  S  Lyon  St. 

Santa  Ana,  CA  92705 
714-835-9512 

Apex  Software  has  released  the  Apex 
Database  Library  (ADL),  a  library  of 
functions  enabling  C  programmers  to 
create,  access,  and  update  dBase  files. 
ADL  features  include  the  ability  to  ac¬ 
cess  the  database  at  either  the  field 
or  record  level,  automatic  updating  of 
index  files,  and  a  tunable  caching 
algorithm. 

With  ADL,  programmers  can  retrieve 
one  field  from  the  database  record  or 
access  the  record  reformatted  into  a 
standard  C  structure.  ADL  includes  a 
dBase  expression  parser  for  index  file 
support,  which  allows  automatic  ac¬ 
cess  to  database  records  based  on  the 
key  expression  of  the  current  index  file 
(with  a  maximum  of  nine  index  files 
open  per  database).  If  database  records 
are  updates,  the  parser  evaluates  and 
updates  the  key  expression  for  all  open 
index  files. 

ADL’s  extension  parser  is  provided 
in  three  different  versions.  Support  is 
provided  for  Microsoft  C  compilers,  Ver¬ 
sion  4.0  and  later,  and  Turbo  C  compil¬ 


ers,  Version  1.5  and  later.  System  re¬ 
quirements  are  PC,  AT,  PS/2,  or  com¬ 
patible.  The  system  also  must  have  a 
minimum  of  128K  RAM  and  MS-DOS 
or  PC-DOS,  Version  2.0  or  later.  A  hard 
disk  is  recommended. 

ADL  is  priced  at  $395  without  source 
code  or  $795  with  source  code.  Prices 
include  support  and  updates  for  90 
days.  Reader  Service  No.  32. 

Apex  Software  Corp. 

4516  Henry  St.,  Ste.  308 
Pittsburgh,  PA  15213-3785 
412-681-4343 

SOFTGRAF,  Version  5.0,  has  been  re¬ 
leased  by  Sunrise-Littleton.  SOFT¬ 
GRAF  is  a  menu-driven  TSR  software 
driver  that  “fools”  a  monochrome  PC, 
allowing  it  to  run  CGA  color  graphics 
programs  and  games,  without  use  of  a 
color  card  or  monitor.  It  does  this  by 
setting  the  system’s  flags  for  a  CGA 
environment,  intercepting  graphics  sig¬ 
nals  sent  to  the  video  buffer,  and  trans¬ 
lating  video  formats  so  that  the  mono¬ 
chrome  pixel  coordinates  that  of  a  CGA 
color  system.  Colors  appear  as  tones 
of  amber  or  green. 

SOFTGRAF  operates  from  its  own 
startup  menu.  Other  software  features 
include  running  programs  in  large  40 
character  text  mode,  an  AFC  feature, 
and  the  ability  for  the  user  to  adjust  the 
screen  refresh  rate  interval  from  16  to 
1,024  times  per  second. 

The  upgraded  version  commits  about 
12K  of  RAM,  and  it  senses  to  determine 
if  color  graphics  commands  are  being 
sent  to  the  video  buffer.  If  a  color- 
oriented  program  is  detected, 
SOFTGRAF  switches  to  CGA  resolu¬ 
tion  and  then  reverts  back  to  the  higher 
Hercules  monochrome  resolution  as 
soon  as  the  application  requiring  color 
is  terminated. 

SOFTGRAF  supports  most  commer¬ 
cial  and  public  domain  software  and 
operates  in  Hercules  compatible  or  EGA 
environments.  Systems  such  as  a  Tandy 
1000  and  leading  edge  models  are  also 
supported. 

Not  copy  protected,  SOFTGRAF  sells 
for  $34.95.  Reader  Service  No.  33. 
Sunrise-Littleton  Technology  Corp. 
15200  Shady  Grove  Rd. 

Rockville,  MD  20850 
301-963-0341 
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SWAINE'S  FLAMES 


The  Return  of  Insane  Greatness 


I  went  to  the  NeXT  machine  introduc¬ 
tion.  Read/write  optical  drive.  Mega¬ 
pixel  display.  Mathematica.  The  com¬ 
pete  works  of  William  Shakespeare. 
I  want  that  machine.  It’s  so  insanely 
great. 

It’s  so  insanely  great  that  I  don’t  care 
that  there  seems  to  be  no  way  for  a 
software  developer  to  make  a  buck  on 
it.  It’s  so  insanely  great  that  I  don’t  care 
that  it’s  only  going  to  be  sold  to  higher 
education.  It’s  so  insanely  great  that  I 
don’t  care  that  there  seems  to  be  no 
way  for  a  writer  to  make  a  .  .  .  Well, 
maybe  it’s  not  so  great. 

The  Foot  Metaphor 

Steve  Jobs  insists  that  the  NeXT  ma¬ 
chine  will  be  sold,  read  his  lips,  Only 
to  Higher  Education.  Right.  No  new 
taxes. 

Hard  on  the  heels  of  NeXT’s  proof-of- 
concept  media  event  comes  a  packet 
of  press  releases  from  Microsoft  an¬ 
nouncing  its  support  for  higher  educa¬ 
tion.  Is  there  a  connection?  Who  knows, 
but  speaking  of  being  hard  on  the  well 
heeled,  Bill  Gates  has  been  galling  the 
Jobs  kibe  lately  by  bad-mouthing  the 
NeXT  machine.  Howcum? 

My  friend  Thom  Hogan  thinks  Bill’s 
just  annoyed  that  he  can’t  get  any  le¬ 
gitimate  press  out  of  the  NeXT  announce¬ 
ment.  Thom  has  been  immersed  in  Mac 
technology  since  March,  when  he 
launched  the  Macintosh  II  Report  (which 
I  help  him  with).  He  doesn’t  think  there’s 
anything  in  the  NeXT  machine  that  Ap¬ 
ple  shouldn’t  be  able  to  put  into  the 
Tower  in  a  year  or  so.  But  he  also 
admits,  after  doing  some  research  into 
the  matter,  that  he  doesn’t  see  how 
NeXT  can  make  a  decent  profit  selling 
the  machine  for  $6,500,  no  matter  how 
good  a  deal  it  made  on  memory.  Some¬ 
thing’s  funny  there. 

Jobs’  insistence  that  his  only  market 
is  higher  education  (“Fortune  500  com¬ 


panies  in  disguise”)  makes  one  curious 
about  the  language  of  his  arrangement 
with  Apple.  I  am  very  impressed  with 
the  machine.  But  I  wonder  about  the 
company.  What  else  does  it  have  to 
sell,  and  to  whom,  and  how?  What’s 
the  rest  of  the  NeXT  strategy?  Does 
Steve  Jobs  have  another  shoe  to  drop? 
And  if  so,  on  whom? 

Roget’s  Paradigm 

Proponents  of  the  object-oriented  pro¬ 
gramming  paradigm  defend  it  as  lucid 
and  realistic.  It’s  lucid,  they  claim,  in 
that  it  packages  information  neatly  and 
allows  for  suppression  of  detail.  Ob¬ 
jects  encapsulate  information  clearly. 
It’s  realistic,  they  claim,  in  that  it  repre¬ 
sents  the  real  world  better  than  other 
paradigms  do.  Developing  OOP  ob¬ 
jects  is  really  modeling  real-world  ob¬ 
jects  and  their  interactions.  Lucid  and 
realistic. 

Yes,  but .  .  .  The  sticky  point  comes 
when  you  consider  multiple  inheritance. 
No  one  since  Roget  has  believed  that 
real-world  objects  can  be  gathered  into 
a  single,  all-encompassing  hierarchy. 
The  real  world  is  saddled  with  real 
multiple  inheritance.  The  keyboard  I’m 
pounding  on  as  I  write  this  belongs  to 
the  class  of  tools  and  to  the  class  of 
possessions  of  mine,  and  neither  class 
encompasses  the  other.  And  doesn’t 
multiple  inheritance  blow  away  the 
vaunted  lucidity  of  object-oriented  pro¬ 
gramming?  Sure  seems  like  it. 

It  begins  to  look  like  object-oriented 


programming  can  be  lucid  or  realistic, 
but  not  both.  No  sex,  please,  we’re 
software  engineers. 

Nothing  is  lost  that  can  be  reinvented. 
Forty  years  ago,  engineers  knew  how 
to  decompose  a  large  problem  into 
small  tasks  to  be  handled  by  separate 
processors.  The  processors  weren’t 
transputer  chips,  to  be  sure.  Technol¬ 
ogy  advances. 

So  does  language.  Back  then,  a  com¬ 
puter  was  a  human  being.  Rows  of 
WACs,  or  in  Britain  WRENs,  each  punch¬ 
ing  keys  on  a  desk  calculator,  each 
computing  her  tiny  task  of  some  large 
computing  problem. 

It’s  strange  to  reflect  that  electronic 
digital  computers  were  invented  to  re¬ 
place  women.  Stranger  still  to  realize 
that,  for  some  (male)  programmers,  the 
replacement  seems  to  have  succeeded 
beyond  expectations.  If  this  paragraph 
has  nothing  to  do  with  you,  please  take 
no  offense.  But  if  you  recognize  your¬ 
self  in  this  picture,  take  a  break.  Log 
off.  Shut  down.  Talk  to  people. 

Personal  to  Two  Valley  Boys 

Stan  Kelly-Bootle:  OK,  so  I’m  overus¬ 
ing  the  P  word.  But  that’s  my  job,  Stan; 
it’s  in  my  contract.  It’s  clause  3b:  “The 
party  of  the  first  part  shall  use  the  word 
[P  word  deleted]  at  every  opportunity.” 

Jeff  Duntemann:  Rumor  is  you’re  go¬ 
ing  to  be  writing  for  the  premier  pro¬ 
grammer’s  magazine.  I  think  that’s  won¬ 
derful.  Don’t  let  them  put  any  funny 
stuff  in  your  contract. 


Michael  Swaine 
editor-at-large 
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EDITORIAL 


For  reasons  that  glimpse  back  to  the 
past,  while  still  looking  ahead  to 
the  future,  this  issue  of  Dr.  Dobb’s Jour¬ 
nal  is  especially  significant  for  us.  As 
you’ve  probably  already  noticed,  with 
this  issue  we’ve  launched  a  new  logo, 
one  that  emphasizes  the  name  Dr. 
Dobb’s  Journal  and  puts  the  descrip¬ 
tive  tagline  “Software  Tools  for  the  Pro¬ 
fessional  Programmer”  back  in  what  I 
consider  its  proper  (less  dominant)  per¬ 
spective.  Our  reason  for  doing  this  is 
quite  straightforward:  When  most  peo¬ 
ple,  including  those  of  us  who  put  the 
magazine  together  every  month,  think 
of  this  publication,  it’s  DDJ,  Dr.  Dobb’s , 
or  simply  the  Journal  that  comes  to 
mind. 

There’s  a  lot  of  recognition,  histori¬ 
cal  and  otherwise,  that  goes  with  the 
name  Dr.  Dobb’s  Journal  and,  to  bor¬ 
row  from  a  recent  article  in  American 
Heritage  magazine  that  acknowledged 
the  100th  anniversary  of  the  Wall  Street 
Journal ,  “I  am  pleased  to  report  that 
the  Journal’s  editors  .  .  .  awakened  to 
the  value  of  preserving  an  institutional 
memory.”  That’s  the  way  we  feel  about 
DDJ — themagazine  and  its  name. 

Part  of  the  history  of  DDJ  revolves 
around  some  pf  the  genuinely  signifi¬ 
cant  articles  we’ve  published  over  the 
years.  (Articles  like  “Tiny  Basic”  and 
“Fattening  Your  Mac,”  for  instance.) 
This  month,  we’re  continuing  that  tra¬ 
dition  with  what  I  think  will  be  one  of 
the  more  important  articles  we’ll  pub¬ 
lish  this  year.  Our  lead  feature,  cowrit¬ 
ten  by  DDJ  s  senior  technical  editor 
Kent  Porter  and  Intel  engineer  Robin 
Kar,  describes  a  specification  for  meas¬ 
uring  real-time  performance  that  we 
call  the  “Rhealstone.”  Over  the  past 
few  months,  Kent’s  been  working  with 
key  people  across  the  real-time  in¬ 
dustry  — silicon  vendors,  software  de¬ 
velopers,  and  system  designers  — to  gen¬ 
erate  the  Rhealstone.  As  part  of  this 
process,  Kent  chaired  a  panel  that  in¬ 
cluded  Robin  Kar,  Ray  Duncan  (from 
Laboratory  Microsystems  Inc.),  and  Dan 
Erickson  (of  Digital  Research  Inc.)  at 


the  Real-time  Programming  conference 
where  the  Rhealstone  was  initially  in¬ 
troduced.  As  Kent  mentions  in  the  arti¬ 
cle,  we’re  now  presenting  it  to  you  and 
asking  for  your  ideas,  questions,  and 
comments.  We’ll  then  publish  the  final 
proposal,  including  code  examples,  in 
this  year’s  June  issue. 

Kent  is  also  central  to  another  of  this 
month’s  developments.  For  the  past 
couple  of  years,  Kent  has  been  writing 
our  “Structured  Programming”  column, 
and  he’s  recently  become  known  in 
some  circles  as  a  Modula-2  evangelist. 
Beginning  this  month,  however,  Kent 
is  starting  a  new  column,  which  is  de¬ 
voted  to  high-performance  graphics  pro¬ 
gramming. 

Our  new  “Structured  Programming” 
columnist  is  Jeff  Duntemann,  no  doubt 
familiar  to  many  of  you  as  the  former 
editor  of  Turbo  Technix,  a  magazine 
that  until  recently  was  published  by 
Borland.  Turbo  Technix  was  a  first-rate 
magazine  and  Jeff  deserves  most  of  the 
credit  for  its  excellence.  Sad  to  say, 
Borland  discontinued  publication  of 
Turbo  Technix  a  few  months  ago,  which 
made  it  possible  for  Jeff  to  join  the  DDJ 
family  as  a  contributing  editor  and  col¬ 
umnist.  While  lamenting  the  demise  of 
Turbo  Technix,  I’m  equally  pleased  to 
welcome  Mike  Floyd,  a  new  technical 
editor  for  DDJ.  Mike,  too,  comes  from 
Turbo  Technix  and  he’s  already  proven 
to  be  a  valuable  addition  to  our  staff. 

The  long  and  short  of  all  this  is  that 
DDJ  is  continuing  its  commitment  to 
publish  the  kind  of  information  that, 
for  the  past  12  years,  has  made  it  the 
magazine  for  serious  programmers,  and 
it’s  our  intent  for  DDJ  to  remain  so  for 
many  years  to  come. 
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Ten  Years  ago  in  DDJ 

“The  creation  and  recognition  of  modular 
structure  in  programs  allows  many  variants 
of  an  operation,  each  fitting  the  particular 
needs  for  speed,  code-efficiency,  or 
complexity  in  the  unending  game  of  trade¬ 
offs.” — H.T.  Gordon,  “An  Unusual 
Pseudorandom  Number  Generator  Program,  " 
DDJ,  February  /  9 79. 


Maybe  That’s  Why  Software  is 
Always  Late. . . 

“The  greatest  value  of  Prolog  is  that,  in 
the  process  of  understanding  it,  a  programmer 
must  alter  and  reexamine  the  fundamental 
assumptions  of  his  or  her  craft.  Prolog 
demonstrates  that  the  distinction  between 
code  and  data  is  artificial  and  unnecessary, 
and  it  exposes  the  many  assumptions  we 
make  about  the  flow  of  time.”  — D.E.  Cortesi, 
" A  Tour  of  Prolog,  "DDJ,  March  1985. 


Yes,  But  Does  He  Have 
Market  Share? 

“We  are  dealing  with  an  infinitely  malleable 
tool.  People  who  choose  to  develop  and  use 
that  tool,  whether  for  work,  play,  or  both, 
have  the  choice  and  cannot  be  denied  it.  The 
computer  serves  not  only  as  a  workhorse, 
but  also  as  an  easel  for  exercising  one’s 
creative  abilities.  Therefore,  the  hacker  has 
expanded  his  intellectual  horizon  because 
now  he  has  the  infinite  tool.”  — G.  Gandalf 
"Essay  on  Hacking,  ”DDJ,  November  1981. 
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Pessimistic  Portrayal  in 
Programming  Paradigms 

Dear  DDJ, 

I  was  intrigued  by  your  [Mike  Swaine’s] 
worries  about  the  U.S.  software  indus¬ 
try  as  expressed  in  “Programming  Para¬ 
digms”  (August  1988).  I  believe  you 
are  unduly  pessimistic. 

About  10  years  ago,  I  learned  that 
the  British  arm  of  Burroughs,  as  it  was 
then,  delegated  a  substantial  part  of  its 
programming  to  India.  There  is  the  bene¬ 
fit  that  English  is  a  common  language, 
not  only  between  Indians  and  ourselves, 
but  also  within  India  where  there  are 
many  other  languages  besides  the  ma¬ 
jority  Hindi.  There  too  is  a  tradition  of 
scientific  and  technical  studies. 

The  point  is  this:  I  do  not  think  the 
U.S.  computer  industry’s  use  of  Indian 
labor  was  a  very  great  secret  — at  the 
time  I  was  not  working  for  an  espe¬ 
cially  favored  customer  — and  certainly 
would  not  be  now.  Yet,  there  is  no 
evidence  of  other  firms  following  the 
Burroughs  example;  I  don’t  even  know 
if  Unisys  continues  the  practice.  There 
are  great  shortages  of  expertise  across 
a  wide  range  of  ADP  applications.  Sala¬ 
ries  are  sky  high,  and  even  middle- 
aged  programmers  like  me  can  still 
make  a  living.  Closer  to  home  is  the 
Republic  of  Ireland,  dedicated  to  giv¬ 
ing  technical  skills  to  one  of  the  young¬ 
est  populations  in  Europe.  Some  re¬ 
cruitment  into  the  U.K.  has  occurred, 
but  the  great  off-shore  software  indus¬ 
try  just  has  not  appeared. 

I  think  that  employers  will  always 
want  people  carrying  out  critical  work 
to  be  on-site.  It  is  significant  that  Bur¬ 
roughs’  Indian  programmers  were  do¬ 
ing  largely  program  conversion  — work 
that  had  to  be  carried  out  to  a  high 
standard  of  accuracy  and  to  a  tight 
deadline,  but  routine  and  not  requiring 
a  high  degree  of  interaction. 

Just  as  people  in  business  do  not  like 


paying  for  anything  that  they  cannot 
drop  on  their  foot,  they  do  not  like 
employing  people  who  are  not  there 
to  kiss  the  same.  Cheap  joke,  but  you 
know  what  I  mean.  They  feel  uncom¬ 
fortable  without  physical  evidence  of 
payroll. 

An  interesting  manifestation  of  a  simi¬ 
lar  phenomenon  occurred  here  recently. 
You  must  know  that  we  had  a  postal 
strike.  I,  and  probably  many  other  tech¬ 
nically  aware  people,  expected  a  large 
increase  in  traffic  on  Telecom  Gold 
and  smaller  communications  networks. 
Not  at  all.  The  real  boom  was  in  facsim¬ 
ile  machines.  Even  now,  none  of  the 
large  computer  recruitment  agencies  I 
use  has  a  communications  link,  in  spite 
of  the  fact  that  the  capital  and  running 
costs  are  lower  than  fax.  They  all  have 
fax.  The  physical  appearance  of  a  docu¬ 
ment,  even  a  poor  copy,  is  more  im¬ 
portant  than  the  content. 

Many  of  us  are  trying  to  persuade 
employers  in  areas  where  recruitment 
is  difficult  to  employ  us  as  “telecom¬ 
muters.”  We  work  from  home,  don’t 
have  to  travel  long  distances  (in  U.K. 
terms),  and  need  not  be  distracted  by 
office  politics.  In  return,  the  employers 
pay  substantially  less  than  their  local 
going  rate  and  do  not  have  to  provide 
accommodation,  furniture,  or  equip¬ 
ment  apart  from  a  terminal  and  a  com¬ 
munications  link.  However,  the  con¬ 
cept  has  not  spread  beyond  a  core  of 
specialized  areas. 

You  may  ask  why  I  am  sending  you 
a  letter,  rather  than  using  electronic 
mail.  I  would  reply  that  I  have  had  to 
move  my  computers  to  another  part  of 
the  house,  it  is  too  much  trouble  to 
fiddle  around  with  cables  and  modems 
at  the  moment,  that  it  is  more  trouble 
to  look  up  your  BBS  identity  than  your 
business  address.  .  .but  I  don’t  convince 
even  myself.  Atavism  rules. 

Frank  Little 

Clydach,  Swansea 


Blind  to  His  Love’s  Faults ? 

Dear  DDJ, 

After  some  thought,  I  finally  decided 
to  write  about  a  key  issue  left  unspo¬ 
ken  in  most  discussion  of  “the  new 
Basics.”  Bruce  Tonkin’s  review  of  the 
Microsoft  and  Bork  nd  offerings  of 
Quick  and  Turbo  Basic  (“Inserting  Ele¬ 
ments  into  a  Basic  Integer  Array,”  No¬ 
vember  1988)  is  a  good  case  in  point. 
After  reading  pages  of  benchmarks  and 
comments  about  the  quality  of  editors 
and  so  on,  I  still  wondered  “how  large 
is  the  data  segment?”  In  a  program 


8 

76 


Dr.  Dobb’s  Journal,  February  1989 


LETTERS 

(continued  from  page  8) 


written  last  year  in  QuickBasic  3.0,  I 
ran  up  against  the  64K  data  limit  — a 
limit  of  the  medium  memory  model.  I 
wondered  if  this  had  been  changed  in 
QB4,  the  new  Basic  compiler  or  in 
Turbo  Basic.  A  re-reading  of  the  article 
provided  no  further  clues. 

A  call  to  Microsoft  straightened  me 
out.  QB4  and  BASCOM,  Version  6,  con¬ 
tinue  to  use  the  medium  memory  model 
under  DOS,  even  in  the  OS/2  world! 

Of  course,  there  are  workarounds 
for  the  new  Basics.  Microsoft  offers 
large  numeric  arrays,  which  are  a  help 
if  your  data  is  numeric  and  if  you  don’t 
mind  the  execution  speed  penalty  over 
using  the  heap  in  other  languages.  (Kent 
Porter  suggests  this  works  out  to  about 
a  500  percent  penalty.)  Although  ad¬ 
dressing  limitations  of  the  8088/80x86 
requires  workarounds  in  Pascal  and  C, 
they  exact  a  more  serious  penalty  on 
Basic.  For  many  applications,  this  limi¬ 
tation  essentially  prevents  a  new  Basic 
from  being  considered  the  platform.  It 
is  important  for  this  information  to  be 
given  and  put  in  context  in  a  review 
aimed  at  software  developers. 

I  always  read  Bruce  Tonkin’s  articles 
and  enjoy  his  often  eloquent  defense 
of  Basic’s  honor  in  an  apparently  hos¬ 
tile  professional  world.  I  am  beginning 
to  wonder,  though,  if  he  is  blind  to  his 
love’s  faults. 

Jay  van  Santen 

Topeka,  Kansas 

Bruce  replies: 

I  think  I’d  better  confess  that  I’m  con - 
fused  by  Mr.  van  Santen ’s  letter.  I  did 
know  that  Microsoft  used  the  medium 
memory  model  for  both  Basic  6.0  and 
QuickBasic  4.0.  Microsoft  could  have 
used  the  huge  memory  model,  but  that 
would  have  made  for  slower  data  ac¬ 
cess  and  a  larger  amount  of  generated 
code  in  most  programs. 

If  Jay  meant  “Microsoft  should  have 
allowed  a  choice  of  memory  model,  ”  I 
agree,  but  it  would  have  meant  a  more 
complex  compiler  and  perhaps  a  less- 
easy  and  less-general  interface  to  other 
languages. 

Large  arrays  are  not  limited  to  nu¬ 
meric  data;  both  QB4  and  Basic  6 
permit  arrays  of  static  strings  and  user- 
defined  types  of  any  size,  limited  by 
memory.  If  he’d  like  variable-length 
string  arrays  larger  than  a  single  seg¬ 
ment,  I  agree.  I’ve  been  asking  for  that 
for  years. 

I  don ’t  think  he  meant  code  size  is 
limited.  The  medium-memory  model 
allows  code  up  to  a  megabyte. 

There  is  a  bug  with  arrays  of  static 


strings  and  user-defined  types  for  QB 
4  and  Basic  6.0.  If  the  element  lengths 
are  not  a  power  of  two,  the  maximum 
memory  available  to  the  array  is  about 
128K. 

Though  data  on  the  heap  can  be 
accessed  faster,  I’ve  found  Basic ’s  string 
functions  faster,  more  flexible,  and  eas¬ 
ier  to  use  than  those  of  Pascal  or  C. 
Often,  that  more  than  makes  up  for 
any  theoretical  losses.  For  numeric  ar¬ 
rays,  please  note:  The  alternate  math 
package  in  Basic  6.0  is  the  same  one 
used  by  the  Microsoft  C  compiler. 

Don’t  overlook  the  fact  that  large 
arrays  are  easy  in  QB  or  Basic  6.0, 
and  not  always  so  in  C  or  Pascal.  If 
you  have  to  do  a  little  kludging,  it  seems 
to  me  that  you’d  lose  at  least  some 
performance  and  (more  important) 
code  clarity. 

I'd  never  concede  that  QB  or  Turbo 
Basic  is  a  poor  development  platform 
compared  to  Pascal.  There  are  a  few 
jobs  where  C  is  better  than  Basic,  and 
jobs  where  assembler  is  better  than 
either.  Where  Pascal  might  be  better, 
I’ve  always  found  that  C  is  better  still. 
If  time  permits,  assembler  is  always  the 
best  choice  in  those  same  cases. 

If  I  wrote  different  software,  maybe 
I’d  use  C.  I’ve  had  to  write  few  device 
drivers  or  systems  software.  Instead,  I’ve 
been  writing  database  management 
tools,  a  word  processor,  and  business 
programs.  For  those,  Basic  is  and  has 
been  a  perfect  choice.  The  medium  mem¬ 
ory  model  has  been  no  constraint  to 
me  or  anyone  I  know. 

I find  it  impossible  to  believe  any  of 
the  applications  mentioned  could  have 
been  more  quickly  written  or  debugged 
in  C  or  Pascal.  The  small  parts  where 
speed  proved  most  critical  were  identi¬ 
fied  and  then  coded  in  assembler,  any¬ 
way,  so  I  doubt  the  C  version  would 
show  any  better  performance. 


Mohr’s  Flames 

Dear  DDJ, 

I  have  been  a  subscriber  for  years,  and 
I  like  the  magazine.  I  am  a  little  put  off, 
though,  by  the  endless  PC  stuff.  I  was 
forced  to  use  one  at  work  and  found  it 
and  its  software  abysmal.  Aztec  C  had 
a  number  of  errors  in  it,  and  even  though 
I  was  supposed  tc  get  updates  of  bug 
fixes,  none  ever  came. 

Flame  One:  Why  is  the  programmer 
supposed  to  pick  the  large  or  small, 
code/data  model?  Is  this  not  a  job  suit¬ 
able  for  the  compiler  and  computer  to 
figure  out?  The  entire  Intel  line  beyond 
the  8080  seems  to  conglomerate  the 


problems  instead  of  solve  them.  Maybe 
I  am  just  stupid,  but  Motorola’s  68000 
series  is  much  better  designed. 

Flame  Two:  I  responded  to  an  adver¬ 
tisement  for  the  C  club  in  Kansas,  which 
had  lots  of  public  domain  (so  they  say) 
software.  Well,  that  is  a  fallacy;  it  is 
public  domain  as  long  as  you  own  the 
BDS  C  compiler  and  library.  Somehow 
I  do  not  think  that  is  what  public  do¬ 
main  means.  Am  I  naive  or  stupid  in 
this  matter? 

Flame  Three:  I  have  used  a  simple 
but  powerful  editor  on  a  DEC  11/20, 
which  is  a  64K  machine  called  TECO, 
Version  28.  It  would  (and  could)  do 
more  than  any  other  editor  I’ve  seen 
for  small  (64K)  or  even  ten  times  bigger 
(640K)  IBM  PCs.  EMACs,  however,  is 
an  exception.  Why  is  there  no  TECO 
for  CPM  machines?  We  seem  to  have 
turned  to  a  swamp  of  fancy  junk  edi¬ 
tors  rather  than  maintaining  a  simple 
powerful  editor  like  TECO. 

End  of  Flames:  I  close  with  the  wish 
that  IBM  and  its  clones  drown  in  the 
swamp  of  their  own  making,  quietly 
and  without  fuss.  Intel  has  pioneered 
the  lowest  common  denominator  of 
computing  hardware,  and  IBM,  by  farm¬ 
ing  it  out,  has  indeed  pioneered  the 
same  in  software  for  its  machines  — a 
software  environment  where  wild  cards 
sometimes  work,  sometimes  not.  Noth¬ 
ing  is  consistent  there.  I  have  spent  a 
lot  of  time  using  Unix  and  C,  and  the 
comparison  to  the  Intel/IBM  systems 
show  the  latter  to  be  sorely  lacking  in 
both  hardware  and  software.  I  would 
hope  that  Dr.  Dobb’s  would  lead  the 
way  instead  of  just  playing  in  the 
swamp.  I  eagerly  await  my  NeXT  com¬ 
puter,  as  it  seems  like  the  first  real  step 
up  from  CPM. 

Douglas  Mohr 

Boulder,  Colo. 


DDJ 


We  welcome  your  comments  (and 
suggestions).  Mail  your  letters  to 
DDJ,  501  Galveston  Dr.,  Redwood 
City,  CA  94063,  or  send  them 
electronically  to  CompuServe 
76704,50  or  MCI  Mail  c/o  DDJ. 
Please  include  your  name,  city, 
and  state.  We  reserve  the  right  to 
edit  letters. 
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An  independently  verifiable  metric  for 
complex  mult itc iskers 


in  time  to  influence  subsequent  events  \n  example  is  an 
aircraft  autopilot,  which  detects  and  corrects  deviations 
from  the  plane's  intended  flight  profile, 

A  complete  real-time  solution  consists  of  the  computet" 
system  plus  the  application  software  plus  external  devices. 
Rheal.xtones  won't  measure  how  good  the  complete  solu¬ 
tion  is.  and  thus  they  may  not  be  an  appropriate  measure 
for  end  users  of  real-time  systems,  instead,  Rhealstones  are 
an  engineering  measurement  targeted  specifically  toward 
true  multitasking  solutions 

A  multitasking  svstem  is  one  in  whic  h  more  than  two 
tasks  having  different  priority  levels  run  concurrently'  By 
this  definition,  then,  Rhealstones  do  not  apply  to  sy  nchro¬ 
nous  polling  solutions,  in  whic  h  all  tasks  have  equal  priority 
and  are  granted  equal  time  and  access  to  resources  it  active 
Rhealstones  apply  chiefly  to  complex  systems  running  five 
to  thirty  concurrent  prex'esses. 

The  derivation  of  the  name  "Rhealstone"  ts  obvious  and  — 
to  those  concerned  w  ith  performance  measurement  — so  is 
the  application  of  the  result.  The  similarities  to  Whetstone 
and  Dhrystone  end  there 

The  Whetstone  and  Dhrystone  benchmarks  are  synthetic 
programs  that  try  to  achieve  a  statistically  balanced  set  of 


Despite  the  grow  ing  importance  of  real-time  systems, 
the  industry  lacks  any  meaningful,  objective  w  ay  to 
measure  real-time  performance  We  use  Whetstones 
and  Dhrvstones  to  benchmark  the  ccxle  generated  bv  com¬ 
pilers  and  or  the  throughput  of  hardware  platforms,  but  to 
date  there  has  been  no  equivalent  ob|ective  measure  for 
real-time  systems  in  an  effort  to  plug  the  gap,  this  article 
proposes  a  standard  methodology  for  objec  tively  measuring 
real-time  performance  and  summarizing  the  components 
of  performance  in  a  figure  of  merit  called  Rhealstones 
The  Rhealstone  metric  chiefly  helps  developers  select 
real-time  computer  systems  appropriate  for  their  applica¬ 
tions.  A  real-time  computer  sy  stem  is  any  marriage  of 
hardware  and  systems  software  —operating  system,  kernel, 
exec  utive,  or  these  elements  of  systems  softw  are  in  combi¬ 
nation  — that  forms  a  platform  for  a  real-time  application 
A  "real-time  application”  is  a  limited-purpose  computerized 
system  that  responds  to  defined  circumstances  as  they  arise 
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operations  reflecting  an  "average"  workload:  Whetstone  for 
floating-point  applications  and  Dhrystone  for  systems  pro¬ 
grams  such  as  compilers  and  operating  system  utilities.  The 
benchmark  programs  loop  some  number  of  times,  and  this 
number  divided  by  the  elapsed  time  in  seconds  yields  the 
figure  of  merit  the  bigger,  the  better.  The  result  serves  as  a 
predictor  of  a  given  platform’s  performance  given  the  "aver¬ 
age”  job.  Though  useful,  the  Whetstone  and  Dhrystone 
metrics  reveal  nothing  about  the  relative  performances  of 
the  various  operations  that  contribute  to  the  single-figure 
result  — and  they  have  no  applicability  to  real-time  systems. 

The  Rhe.iKtone  measure,  on  the  other  hand,  proceeds 
from  the  observation  that  every'  real-time  application  is 
unique.  One  system  may  be  highly  interrupt-driven,  another 
rely  heavily  on  message-passing  among  tasks,  and  still  an¬ 
other  deal  with  contention  for  resources,  and  so  on  Real¬ 
time  systems  are  almost  always  multitasking,  with  one  task 
or  another  capturing  the  attention  of  the  processor  based 
upon  conditions  within  the  specific  application's  limited 
universe.  The  processor  relies  on  some  sort  of  real-time 
systems  software  to  help  it  do  its  job.  Moreover,  real-time 
systems  react  to  circumstances  and  by  definition  are  endless 
programs  that  stop  only  when  the  plug  is  pulled.  All  this 
makes  the  notion  of  statistical  balance  irrelevant. 

The  Rhealstone  figure  is  consequently  a  sum  obtained 
from  six  categories  of  activity  most  crucial  to  the  perform¬ 
ance  of  real-time  systems,  irrespective  of  the  actual  applica¬ 
tion  The  categories,  or  components,  of  the  Rhcalstone  sum 
are: 

*  Task  switching  time 

•  Preemption  time 

»  interrupt  latency  time 

»  Semaphore  shuttling  time 

*  Deadlock  breaking  time 

•  Datagram  throughput  time 

1  !smg  coefficients  we'li  discuss  later,  the  system  engineer 
can  assign  each  Rhcalstone  component  a  weight  that  re¬ 
flects  its  relative  importance  in  the  target  application  But 
first,  let’s  describe  the  components 

What  Makes  up  a  Rhealstone  Number? 

The  Rhealstone  metric  consists  of  quantitative  measure¬ 
ments  of  the  six  components  that  most  influence  the  per¬ 
formance  of  real-time  systems: 

Task  switching  time  is  the  average  time  the  system  takes 
to  switch  between  two  independent  and  active  (that  is,  not 
suspended  or  sleeping)  tasks  of  equal  priority,  as  Figure  1 
illustrates.  Task  switching  is  synchronous  and  nonpreemp- 
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tive,  as  when,  for  example,  the  real-time  control  software 
implements  a  time-slice  algorithm  for  multiplexing  equal- 
priority  tasks. 

Task  switching  time  is  a  fundamental  efficiency  measure 
of  any  multitasking  system.  Measurement  seeks  to  assess  the 
compactness  of  task  control  data  structures  and  the  effi¬ 
ciency  with  which  the  executive  manipulates  the  data  struc¬ 
tures  in  saving  and  restoring  contexts  Task  switching  time 
is  also  influenced  by  the  host  CPt  i’s  architecture,  instruction 
set,  and  features  (provided  the  executive  uses  them). 

Additionally,  task  switching  time  is  a  measure  of  the 
executive’s  list  management  capabilities  because  an  execu¬ 
tive  typically  organizes  its  data  structures  into  ordered  lists 
and  shuffles  the  nodes  according  to  circumstances 

Preemption  time  is  the  average  time  it  takes  a  higher- 
priority  task  to  wrest  control  of  the  system  from  a  running 
task  of  lower  priority  Preemption  usually  occurs  when  the 
higher-priority  task  moves  from  an  idle  to  a  ready  state  in 
response  to  some  external  event.  For  example,  when  an 
attached  device  generates  an  interrupt,  the  interrupt  service 
routine  attempts  to  w  ake  up  the  task  to  service  the  request. 
Preemption  time  is  (he  average  time  the  executive  takes  to 
recognize  an  external  event  and  switch  cotrol  of  the  system 
from  a  running  task  of’lower  priority  to  an  idle  task  of  higher 
priority 

Though  conceptually  similar  to  task  sw  itching  (Figure  1), 
preemption  usually  takes  longer.  This  is  because  the  execu¬ 
tive  must  first  recognize  the  wake-up  action  and  assess  the 
relative  priorities  of  the  running  and  requested  tasks,  and 
only  then  switch  tasks  if  appropriate. 

Virtually  all  multiuser  multitasking  executives  assign  task 
priorities,  and  many  let  the  application  designer  change 
priorities  dynamically  For  this  reason  preemption,  along 
with  interrupt  latency,  is  the  most  significant  real-time  per- 
f( >rma  nee  pa  ramete  r. 

Interrupt  latency  time,  illustrated  in  Figure  2.  is  the  time 
between  the  CPI  ’  s  receipt  ot  an  interrupt  request  and  the 
execution  of  the  first  instruction  in  the  interrupt  service 
routine.  Interrupt  latency  time  reflects  only  the  delay  intro¬ 
duced  by  the  executive  and  the  processor  and  does  not 
include  delays  occurring  on  the  bus  or  interfaces  to  external 
devices 

Semaphore  shuffling  time  is  the  delay  between  a  task's 
release  of  a  semaphore  (usually  by  calling  the  executive’s 
"relinquish  semaphore"  primitive  i  and  the  activation  of 
another  task  blocked  on  the  "wait  semaphore”  primitive. 
No  other  tasks  should  lx1  scheduled  in  between,  although 
at  least  three  tasks  w  ith  different  priorities  should  lx  active. 

The  focus  on  semaphore  shuffling  time  is  o  measure  the 
overhead  associated  with  mutual  exclusion.  In  most  real- 
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time  systems,  multiple  tasks  compete  for  the  same  resources. 
Semaphore-based  mutual  exclusion  is  a  convenient  way  to 
ensure  that  a  nonshareable  resource  serves  only  one  master 
at  a  time. 

Figure  3  illustrates  semaphore  shuffling.  Here  Task  1  runs 
for  a  time  and  then  takes  control  of  a  resource  by  requesting 
its  semaphore.  Eventually  Task  1  is  suspended  and  Task  2 
starts.  After  a  time,  Task  2  requests  the  semaphore  presently 
owned  by  Task  1.  Unable  to  continue,  Task  2  stops,  and 
Task  1  again  awakens.  At  the  end  of  its  period,  Task  1 
relinquishes  the  semaphore.  The  executive  recognizes  that 
the  semaphore  is  now  free/ 
available  for  suspended  Task 
2.  Semaphore  shuffling  time 
is  the  period  between  Task  1 
releasing  the  semaphore  and 
the  resumption  of  Task  2. 

Advanced  real-time  execu¬ 
tives  recognize  relative  priori¬ 
ties  in  a  “wait  semaphore”  situ¬ 
ation;  that  is,  when  multiple 
tasks  are  waiting  for  a  sema¬ 
phore,  the  executive  sched¬ 
ules  them  so  that  the  highest- 
priority  task  goes  to  the  head 
of  the  queue.  The  Rhealstone 
measure  doesn’t  give  an  ex¬ 
ecutive  extra  credit  for  priori¬ 
tized  semaphore  queues,  but 
such  a  capability  may  be  im¬ 
portant  to  the  software  de¬ 
signer. 

Deadlock  breaking  occurs 
when  a  higher-priority  task 
preempts  a  lower-priority  task 
that  holds  a  resource  needed 
by  the  higher-priority  task.  The 
deadlock  breaking  metric  measures  the  average  time  it  takes 
the  executive  to  resolve  the  conflict. 

Deadlocks  are  a  common  multitasking  problem,  yet  not 
all  executives  handle  deadlocks  effectively,  if  at  all.  A  com¬ 
mon  executive  solution  is  to  temporarily  raise  the  priority 
of  the  running  task  above  that  of  the  interrupting  task  until 
the  lower-priority  task  releases  the  needed  resource.  At  that 
point,  the  temporary  priority  is  lowered  and  the  new  task 
can  run. 

Figure  4  illustrates  deadlock  breaking  along  a  time  line. 
Here,  low-priority  Task  1  takes  ownership  of  a  resource  and 
is  then  preempted  by  Task  2,  which  has  medium  priority. 
This  task  runs  until  the  highest-priority  task  preempts  it. 
Task  3  presently  requests  the  critical  resource,  which  is  still 


held  by  the  suspended  Task  1 .  The  first  phase  of  deadlock 
breaking  time  then  occurs  as  the  executive  decides  what  to 
do  about  the  contention.  Eventually  the  executive  raises  the 
priority  of  Task  1  so  that  it  can  run.  When  Task  1  releases 
the  critical  resource,  the  executive  suspends  it  and  enters 
the  second  phase  of  deadlock  breaking,  which  entails  rein¬ 
stating  Task  3  and  giving  it  control  of  the  resource. 

Deadlock  breaking  is  thus  the  sum  of  times  required  to 
resolve  an  ownership  dispute  between  a  low-priority  task 
holding  a  resource  and  a  higher-priority  task  that  needs  it. 

Datagram  throughput  time  is  the  number  of  kilobytes 
per  second  one  task  can  send  to  another  via  calls  to  the 
primitives  of  the  real-time  executive  — without  using  a  pre¬ 
defined  common  message  buffer  in  the  system’s  address 

space  or  passing  a  pointer.  The 
sending  task  must  receive  an 
acknowledgement,  as  Figure 
5  depicts.  Executives  typi¬ 
cally  provide  pipes,  message 
queues,  and/or  stream  files  for 
this  purpose. 

The  goal  of  measurement 
in  the  datagram  throughput 
category  is  to  average  inter¬ 
task  communications  speed. 
Datagram  throughput  is  of  pri¬ 
mary  importance  in  applica¬ 
tions  where  one  task  collects 
data  from  the  outside  world 
and  sends  it  to  another  task 
for  processing.  An  acknowl¬ 
edgement  of  receipt  is  essen¬ 
tial  to  assure  the  sending  task 
that  the  data  is  safely  in  the 
hands  of  the  receiver  before 
the  sender  overwrites  its  buff¬ 
ers  with  new  data. 

Computing  the 
Rhealstone  Number 

Measurement  of  these  six  aspects  of  real-time  performance 
yields  a  set  of  time  values  in  the  microsecond  to  millisecond 
range.  In  order  to  combine  the  six  results  into  a  single 
meaningful  figure,  express  all  times  in  seconds  and  invert 
them  arithmetically.  For  example,  if  activity  N  takes  200 
microseconds,  the  time  in  seconds  is  0.0002  and  the  Rheal¬ 
stone  component  is  1/0.0002  =  5000.  The  frequency  of  N  is 
5000  per  second.  (Note:  Datagram  throughput  time  is  al¬ 
ready  expressed  in  kilobytes  per  second,  so  no  further 
conversion  is  necessary.) 

There  are  two  related  reasons  for  expressing  Rhealstone 
components  in  terms  of  frequency  per  second.  Performance 
becomes  directly  proportional  to  value  — the  bigger  the 
number,  the  better  the  performance.  This  leads  to  the  sec- 


Request  for  Suggestions 

The  Rhealstone  proposal  published  here  is  a  draft.  DDJ 
invites  interested  readers  to  submit  suggestions  for  im¬ 
provements.  To  the  fullest  extent  possible,  we  will  incor¬ 
porate  reader  feedback  into  the  Rhealstone  standard. 
Current  plans  call  for  the  final  version  to  be  published 
(along  with  a  model  set  of  benchmark  tasks  written  in 
C)  in  the  June  1989  issue  of  DDJ. 

Please  send  suggestions  in  writing  to  Kent  Porter  at 
DDJ,  501  Galveston  Dr.,  Redwood  City,  CA  94063.  Alter¬ 
natively,  address  them  to  Kent  at  CompuServe  76704,51 
or  MCI  KPORTER.  Include  your  name,  title,  company, 
and  a  brief  summary  of  your  real-time  experience. 

We  cannot  accept  suggestions  by  telephone,  so  please 
DO  NOT  CALL. 

Deadline  for  suggestions  is  March  1,  1989.  A  list  of  all 
contributors  to  this  standard  will  be  published  with  the 
final  specification.  — K.P. 
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Figure  1:  Task  switch  time  preemption  time 
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ond  reason  — the  Rhealstone  metric  is  then  consistent  with 
other  industry  benchmarks  such  as  Whetstones  and  Dhry- 
stones. 

An  objective  Rhealstone  number  can  now  be  calculated 
as 

rl  +  r2  +  r3  +  r4  +  r5  +  r6  = 
objective  Rhealstones/second 

where  rl  is  the  task  switching  time  component,  r2  is  preemp¬ 
tion  time,  and  so  on. 

The  objective  Rhealstone  number  sum  is  useful  for  ex¬ 
pressing  the  overall  performance  of  a  real-time  platform:  for 
example,  the  “claim”  number  used  by  the  vendor  of  real¬ 
time  executive  A  running  on  microprocessor  X.  The  objec¬ 
tive  Rhealstone  sum  is  based  on  the  assumption  that  all 
Rhealstone  components  are  equally  influential  in  determin¬ 
ing  system  performance.  This  may  be  true  in  general,  but  it 
is  probably  not  true  of  any  specific  real-time  application. 

Weighting  the  Rhealstone  Components 

Evaluators  can  tailor  the  Rhealstone  figures  to  their  applica¬ 


A  =  interrupt  latency 


Note:  CPU  receives  interrupt  at  time  "t” 
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Figure  2:  Interrupt  latency 


A  =  Semaphore  shuffle  time 


Legend: 
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Figure  3-'  Semaphore  shuffle 
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Figure  4:  Deadlock  break  time 
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tions  by  using  weighting  coefficients.  Herein  lies  one  of  the 
strongest  features  of  the  Rheastone  measurement. 

Say  a  designer  estimates  that  interrupts  will  occur  five 
times  as  often  as  task  switches;  semaphores  and  intertask 
messaging  will  not  be  used  at  all.  In  this  case,  then,  the 
weighting  coefficients  for  semaphores  and  datagrams  are  0 
and  the  weighting  coefficient  for  interrupts  is  numerically 
five  times  as  great  as  the  weight  for  task  switching,  say  10 
and  2,  respectively.  The  other  two  components  (preemption 
and  deadlock  breaking),  having  unknown  weights,  receive 
“default”  coefficients  of  1. 

Such  information  leads  us  to  an  application-specific  Rheal¬ 
stone  equation  of 

nl*rl  +  n2*r2  +  n3*r3  +  n4*r4  +  n5*r5  +  n6*r6  = 
application  Rhealstones/second 

where  the  n  factors  are  weight  coefficients.  Note  that  a 
coefficient  must  be  either  zero  (when  the  component  is 
irrelevant  to  the  specific  application’s  performance)  or  a 
positive  value  that  gives  the  Rhealstone  component  its  rela¬ 
tive  importance  in  the  application's  performance. 

An  application  designer  typically  has  several  alternatives 
among  microprocessors  and  real-time  systems  software. 
Using  a  matrix  in  which  the  coefficients  are  uniformly  ap- 
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plied  to  each  alternative,  the  designer  can  easily  select  the 
best  platform  for  the  application:  The  platform  with  the 
largest  application-specific  Rhealstone  value  “wins.” 

The  beauty  of  the  Rhealstone  metric  lies  in  its  ability  to 
express  real-time  performance  objectively,  while  allowing 
designers  to  tailor  and  measurements  to  specific  applica¬ 
tions.  The  Rhealstone  number  allows  vendors  to  state  — in 
terms  universally  understood  — the  relative  performances 
of  products  and  application  designers  to  extrapolate  these 
performances  to  a  given  real-time  system. 


Evaluators  can  tailor 
the  Rhealstone  figures 
to  their  applications  by 
using  weighting 
coefficients 


Data  Acquisition 

Real-time  systems  are,  in  general,  “black  boxes”  operating 
within  closed,  well-defined  universes  of  possibilities  that 
change  dynamically.  A  real-time  system  runs  forever,  deal¬ 
ing  with  circumstances  as  they  arise.  Unlike  a  compiler  or 
some  other  utility  program,  a  real-time  system  has  no  de¬ 
fined  beginning  and  ending.  This  makes  it  difficult  to  meas¬ 
ure  real-time  performance. 

A  number  of  tools  let  us  look  into  the  black  box  and  find 
out  where  it  spends  its  time.  One  is  a  hardware  probe  or 
in-circuit  emulator,  which  feeds  software  that  reports  how 
many  times  each  machine  instruction  executes.  Another  is 
a  statistical  profiler,  a  software  monitor  awakened  by  an 
event  such  as  a  clock  tick,  which  collects  and  reports  infor¬ 
mation  about  what  the  observed  system  is  doing  each  time 
it  looks.  There  are  other  tools  as  well,  such  as  software 
simulators  driven  by  scripts. 

The  Rhealstone  methodology  specifies  which  aspects  of 
performance  must  be  measured  and  how  they  are  to  be 


Figure  5:  Datagram  throughput 


treated  in  order  to  arrive  at  a  figure  of  merit;  the  methodol¬ 
ogy  does  not  describe  how  data  for  each  component  should 
be  obtained.  The  only  stipulation  is  that  someone  else, 
using  the  same  configuration  and  measurement  techniques, 
must  be  able  to  arrive  independently  at  the  same  perform¬ 
ance  components.  The  verifiability  of  both  the  individual 
component  figures  and  the  Rhealstone  sum  depends,  of 
course,  on  compliance  with  a  uniform  method  for  reporting 
Rhealstones. 

Reporting  Rhealstone  Results 

A  Rhealstone  report  must  include  the  following: 

•  The  hardware  platform  for  which  results  are  shown,  in¬ 
cluding  the  processor  type  and  speed  in  MHz. 

•  Relevant  details  of  the  platform  configuration.  Examples 
are  the  major/minor  version  of  any  software,  whether 
cache  memory  is  employed  for  instruction  prefetch  by 
pipelined  processors  and  memory  wait  states. 

•  The  method  by  which  the  Rhealstone  components  were 
obtained. 

•  The  individual  Rhealstone  components. 

The  last  is  the  most  stringent  requirement  of  a  Rhealstone 
report.  Inclusion  of  the  individual  Rhealstone  components 
allows  others  to  apply  performance  figures  to  their  circum¬ 
stances.  In  the  absence  of  by-category  results,  an  objective 
Rhealstone  number  has  little  meaning. 

The  overall  intent  is  reproducibility;  anyone  should  be 
able  to  take  the  same  configuration,  apply  the  same  meas¬ 
urement  techniques,  and  come  up  with  the  same  results 
with  a  reasonable  margin  for  error,  regardless  of  the  actual 
application.  Independent  verification  is  the  key  to  reliable 
Rhealstone  measurements. 

Giving  Credit  Where  Due 

The  Rhealstone  concept  was  originally  devised  by  Rabindra 
P.  Kar  of  the  Intel  Systems  Group,  Hillsboro,  Ore.,  in  re¬ 
sponse  to  the  need  to  measure  enhancements  to  iRMX  and 
Intel’s  other  real-time  executives.  Recognizing  that  this  idea 
could  lead  to  an  industry  standard  for  measuring  real-time 
performance,  Frank  Vaughan,  the  division’s  PR  manager, 
approached  DD/s  editor-in-chief  Jon  Erickson.  Jon  enthusi¬ 
astically  endorsed  the  concept,  and  senior  technical  editor 
Kent  Porter  is  coordinating  it. 

From  its  inception,  the  objective  of  this  project  has  been 
to  remove  any  vendor  preference  from  the  Rhealstone  met¬ 
ric.  This  paper  has  already  been  circulated  to  a  number  of 
vendors,  users,  and  academics  for  comment.  The  Rheal¬ 
stone  measurement  was  also  the  subject  of  a  panel  discus¬ 
sion  at  the  Real-Time  Programming  Conference  held  in 
Anaheim,  Calif.,  last  November.  Now  DDJ invites  interested 
readers  to  submit  written  suggestions  and  criticisms,  (see 
sidebar)  so  that  we  can  forge  this  proposal  into  an  industry¬ 
wide,  vendor-independent  measure  of  real-time  perform¬ 
ance. 

Availability 

All  source  code  for  articles  in  this  issue  is  available  on  a 
single  disk.  To  order,  send  $14.95  (Calif,  residents  add  sales 
tax)  to  Dr.  Dobb’s  Journal ,  501  Galveston  Dr.,  Redwood 
City,  CA  94063,  or  call  800-356-2002  (inside  Calif.)  or  800-533- 
4372  (outside  Calif.).  Please  specify  the  issue  number  and 
format  (MS-DOS,  Macintosh,  Kaypro). 
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ARTICLES 


Real-Time  Modeling  with 


MS-DOS 

Who  says  MS-DOS  isn ’t  a  real-time  operating  system ? 


David  Bowling 


The  phrase  real-time  has  been 
thrown  around  a  lot  in  the  past 
few  years,  mostly  as  a  buzzword 
to  impress  people.  Yet  the  question 
still  asked  is,  what  is  a  real-time  sys¬ 
tem?  Basically,  real-time  systems  are 
those  systems  that  are  able  to  respond 
to  specific  events  within  a  specified 
time.  Given  this  definition,  even  Unix- 
based  computers  are  real-time  systems 
if  we  specify  our  response  time  in  sec¬ 
onds  — which,  in  some  cases,  is  very 
acceptable.  Because  the  temperature 
in  a  100,000-sq  ft  building  can’t  change 
much  in  a  few  minutes,  a  heating  and 
cooling  system  in  a  large  building  will 
work  fine  if  it  can  respond  to  a  change 
in  the  building’s  temperature  in  less 
than  a  minute.  At  the  other  end  of 
the  spectrum,  the  stuff  I  work  with  — 
flight  simulators  and  flight  controllers  — 
requires  response  times  down  in  the 
milliseconds.  For  example,  an  autopi¬ 
lot  on  a  small  fighter  aircraft  must  re¬ 
spond  to  any  disturbances  in  less  than 
about  20  milliseconds  to  keep  the  air¬ 
plane  from  going  unstable  (crashing). 

As  stated  earlier,  real-time  systems 
respond  to  events.  An  event  can  be 
almost  anything.  The  most  common 
type  of  real-time  event  in  a  computer 
system  is  a  hardware  interrupt.  One 
common  hardware  interrupt  is  gener- 


David  Bowling  is  a  project  engineer  at 
Honeywell  Defense  Avionics  Systems  Di¬ 
vision  and  is  responsible  for  the  soft¬ 
ware  design  and  development  of  non¬ 
linear  real-time  simulators.  His  cur¬ 
rent  projects  include  simulators  for  the 
B-52,  C-135,  C-130,  and  C-17 aircraft. 
He  can  be  reached  at  6213  Antigua 
NE,  Apt.  F,  Albuquerque,  NM  87111. 


ated  when  a  key  is  pressed.  Generally, 
the  desired  real-time  response  to  this 
hardware  interrupt  is  the  appearance 
of  a  character  on  the  computer  screen. 
On  a  heavily  loaded  minicomputer,  this 
simple  task  can  sometimes  take  sec¬ 
onds.  The  delay  from  the  time  the  event 
occurs  to  the  time  the  computer  re¬ 
sponds  is  called  interrupt  latency.  In¬ 
terrupt  latency  is  a  scale  by  which  real¬ 
time  computers  are  measured.  Using 
this  scale,  MS-DOS  excels  as  a  real-time 
operating  system.  Because  of  the  stan¬ 
dard  hardware  and  the  wealth  of  infor¬ 
mation  on  how  to  program  it,  functions 
can  be  directly  tied  to  hardware  inter¬ 
rupts.  The  interrupt  latency  with  MS- 
DOS  ends  up  being  the  time  required 
to  jump  to  an  interrupt  service  routine  — 
which  is  not  very  long. 

When  modeling  something  in  real 
time,  the  event  we  respond  to  is  a 
clock-generated  interrupt.  The  clock  gen¬ 
erates  its  hardware  interrupt  at  set  in¬ 
tervals  known  as  the  frame  time.  In 
real-time  modeling,  we  respond  to  the 
clock  interrupt  by  computing  or  mod¬ 
eling  what  a  system  will  do  over  the 
frame.  If,  at  every  clock  pulse,  we  model 
what  our  system  did  since  the  last  clock 
pulse  (over  one  frame),  we  end  up 
predicting  what  the  system  will  do  at 
the  precise  time  the  actual  system  would 
do  it.  A  familiar  example  of  real-time 
modeling  is  the  game  Flight  Simulator. 
Flight  Simulator  models,  or  predicts, 
what  a  Cessna  182  will  do  at  the  pre¬ 
cise  time  an  actual  Cessna  182  would 
do  it. 

Designing  a  Real-Time 
Multitasking  Environment 

The  first  thing  we  need  to  implement 


a  real-time  model  is  a  multitasking  en¬ 
vironment.  Because  MS-DOS  isn’t  mul¬ 
titasking,  we’re  going  to  implement  our 
own  simple,  real-time  multitasking  sys¬ 
tem.  Our  system  will  have  two  tasks  — 
one  foreground  and  one  background. 
The  foreground  task  will  do  the  real¬ 
time  modeling;  the  background  task 
will  be  used  to  input  data  and  display 
the  output  of  the  model. 

The  best  way  to  illustrate  how  the 
two  tasks  interact  is  with  time  lines  (see 
Figure  1).  Every  time  we  get  a  clock 
interrupt,  the  foreground  task  is  acti¬ 
vated.  The  foreground  task  then  runs 
to  completion  (see  Figure  la).  The  ob¬ 
vious  limitation  of  the  foreground  task 
is  that  it  must  take  less  time  to  com¬ 
plete  than  the  duration  of  one  frame. 
The  background  task  will  be  an  end¬ 
less  loop  that  continuously  checks  for 
input  and  displays  output  (see  Figure 
lb).  But,  the  only  time  allotted  for  the 
background  task  is  the  time  between 
the  end  of  the  foreground  task  and  the 
next  clock  interrupt.  Because  the  back¬ 
ground  task  has  no  knowledge  of  the 
real-time  task  the  trick  is  getting  both 
of  the  tasks  to  work  together.  The  fore¬ 
ground  task  interrupts  the  background 
task,  does  its  thing,  and  when  finished 
resumes  the  background  task  where  it 
was  interrupted  (see  Figure  lc). 

You  might  have  noticed  that  this 
scheme  sounds  a  lot  like  a  simple  inter¬ 
rupt  service  routine.  Well,  that’s  all  it 
is.  All  we  really  did  was  give  all  the 
functions  different  titles.  The  program 
becomes  the  background  task  and  the 
interrupt  service  routine  becomes  the 
real-time  task.  The  only  real  difference 
in  implementation  is  that  the  computer 
spends  more  time  in  the  interrupt  serv- 


26 


Dr.  Dobb’s Journal,  February  1989 

83 


ice  routine  (our  real-time  task)  than  in 
the  program  (our  background  task). 

Creating  a  Program  Structure 

By  creating  an  interrupt-driven  fore¬ 
ground  task  that  interrupts  a  continuous- 
loop  background  task,  we  can  imple¬ 
ment  a  real-time  system  with  MS-DOS. 
But  the  problem  of  how  to  create  and 
start  both  tasks  from  our  main  program 
still  remains. 

Our  main  program  can  be  viewed 
as  consisting  of  an  initialization  sec¬ 
tion,  a  background  task  loop,  and  a 
termination  section.  In  the  initializa¬ 
tion  section,  we  set  up  our  foreground 
and  background  tasks  and  initiate  the 
foreground  interrupt.  In  the  termina¬ 
tion  section,  we  disable  the  foreground 
interrupt  and  restore  normal  operation. 
Although  all  this  can  be  done  in  one 
long  main  program,  I  find  a  modular 
approach  to  programming  facilitates  un¬ 
derstanding  as  well  as  modification. 

Using  a  modular  approach,  I  devel¬ 
oped  a  generic  main  program  for  any 
simple  real-time  model  (see  Listing  One, 
page  78).  I  used  C  because  of  its  pow¬ 
erful  instruction  set,  which  lends  itself 
to  manipulating  hardware  interrupts  and 
timer  chip  programming. 

The  initialization  section  of  the  ge¬ 
neric  program  consist  of  calling  three 
setup modules:  two set_up_user .  .  .mod¬ 
ules  to  perform  any  special  foreground 
or  background  initialization  for  our  par¬ 
ticular  real-time  application  and  one 
to  set  up  the  real-time  interrupt.  Simi¬ 
larly  the  termination  section  of  the  ge¬ 
neric  program  consists  of  an  error  han¬ 
dler  and  three  set-down  modules:  one 
to  turn  off  the  real-time  interrupt  and 
two  set_down_user  .  .  .  modules  to  per¬ 
form  any  special  foreground  or  back¬ 
ground  termination  for  our  real-time 
application.  As  an  example,  in  the  sim¬ 
ple  spring-mass  system  discussed  later 
in  this  article,  I  use  the  set_up_user_ 
backgroundjtaskC )  and  set_doum_user_ 
background_task( )  functions  to  get  the 
EGA  card  in  and  out  of  graphics  mode. 

Spawning  the  Real-Time  Task 

But  what’s  inside  the  functions  set_up_ 
real_time_task( )  and  set_down_real_ 
time_task(  J  ?  As  in  setting  up  any  other 
interrupt  service  routine,  we  redirect 
the  interrupt  vector  to  our  real-time 
function  {real_time_task( )).  This  is 
where  Borland’s  Turbo  C  really  comes 
in  handy.  Turbo  C  has  two  functions  — 
getvectC )  and  setvectC )  that  make  ma¬ 
nipulating  the  interrupt  vectors  a  snap 
(see  Listing  Two,  page  78). 

Setting  up  the  real-time  task  involves 
four  simple  steps: 

1 .  Save  the  clock  interrupt  service  rou¬ 
tine  address  (hardware  interrupt  vector 


0x08).  The  Turbo  C  function  getvect( ) 
is  used  for  this. 

2.  Set  an  unused  interrupt  vector  to 
point  to  the  original  clock  interrupt  (I 
used  interrupt  0x50).  We  will  want  to 
continue  calling  the  clock  interrupt  so 
we  don’t  alter  our  computer’s  system 
time.  The  Turbo  C  function  setvectC ) 
is  used  for  this. 

3.  Overwrite  the  address  of  the  origi¬ 
nal  clock  interrupt  with  the  address  of 
our  real-time  function.  The  Turbo  C 
function  setvectC )  is  also  used  for  this. 

4.  Reprogram  the  system  clock.  I’ll  talk 
more  about  this  in  the  next  section, 
“Setting  the  Frame  Time.” 

Setting  down  the  real-time  task  is  even 
simpler: 

1.  Overwrite  the  address  of  our  real¬ 
time  task  with  the  original  clock  inter¬ 
rupt.  Remember  we  saved  it  when  set¬ 
ting  up  the  real-time  task. 

2.  Reset  the  system  clock  to  its  boot¬ 
up  configuration. 

Actually,  I  lied  earlier.  We  can’t  tie  our 
real-time  function  directly  to  the  inter¬ 
rupt;  we  have  to  do  a  little  housekeep¬ 
ing  before  we  call  the  actual  real-time 
task,  user_defined_real_time_taskC  ) 
(see  Listing  Three,  page  78).  This  is  the 
function  we  will  write  to  do  our  model¬ 
ing.  When  we  called  set_up_real_time_ 
taskC X  we  overwrote  the  vector  to  the 
clock  interrupt  that  keeps  the  system 
time.  If  we  do  nothing,  time  will  stand 
still  while  the  program  is  running.  The 


Figure  1:  Real-time  clock  interrupt  time 


first  time  I  realized  this,  the  computer 
told  me  it  was  10:30  when  actually  the 
time  was  1  o’clock  in  the  morning. 

So,  to  avoid  losing  track  of  time,  we 
need  to  call  the  original  clock  interrupt 
routine  in  conjunction  with  our  real¬ 
time  task.  It  is  also  a  good  idea  to 
enable  interrupts  during  the  real-time 
function  to  make  sure  things  such  as 
the  keyboard  are  still  serviced.  But  most 
important,  we  need  to  have  some  way 
to  check  and  control  if  we  reenter  the 
real-time  function.  If  the  real-time  task 
takes  longer  to  run  than  the  frame  time, 
we  end  up  reentering  the  function.  In 
simpler,  more  confusing,  terms  if  we 
haven’t  finished  the  real-time  function 
when  the  next  clock  interrupt  occurs, 
we  call  the  real-time  function  again, 
before  we  finish  it  the  first  time.  This 
has  a  tendency  to  bring  the  computer 
to  a  halt  very  quickly  (see  time  line  of 
Figure  2). 

To  prevent  frame  overruns  from  lock¬ 
ing  up  the  computer  and  to  report  the 
occurrence  of  the  overrun  we  use  two 
flags  — the  flag  running  and  the  flag 
over_run.  By  setting  the  flag  running 
to  TRUE  in  the  interrupt  routine,  before 
the  user-defined  function  is  called,  and 
then  resetting  it  to  FALSE  before  return¬ 
ing  to  the  background  task,  it  provides 
us  with  an  indication  of  task  comple¬ 
tion  within  the  allotted  frame  time.  If 
we  enter  our  foreground  interrupt  serv¬ 
ice  routine  and  running  is  TRUE  this 
means  we  are  in  the  middle  of  the 
user-defined  function  from  the  last  in¬ 
terrupt  and  we’ve  just  reentered  the 
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(continued  from  page  27) 


function.  When  this  happens  we  set 
the  flag  over_run  to  TRUE  and  immedi¬ 
ately  return  to  our  previous  foreground 


routine,  still  executing  (see  Figure  2b). 
Once  over_run  is  TRUE \  we  never  again 
call  the  user-defined  function.  Upon 
the  completion  of  each  background 
loop  we  examine  overturn  in  the  main 
program.  If  set,  we  jump  out  of  the 


background  loop,  enter  the  termina¬ 
tion  section,  and  report  the  overrun 
error  to  the  user. 

Setting  the  Frame  Time 

It  turns  out  that  the  frame  time  of  the 
system  clock  is  never  what  we  want.  I 
usually  find  it’s  too  large.  This  can  be 
easily  corrected  by  reprogramming  the 
timer  that  controls  the  system  clock. 
But  we  also  need  to  take  into  account 
that  once  we  change  the  clock  timer, 
the  computer  might  no  longer  keep 
accurate  time.  I  choose  to  limit  the 
reprogramming  of  the  timer  to  integer 
divisions  of  the  original  frame  time.  If 
we  use  only  integer  divisors,  we  can 
maintain  the  time  of  day  simply  by 
calling  the  original  clock  interrupt  every 
“divisor”  frames.  Remember,  because 
we  saved  the  address  of  the  original 
clock  interrupt  in  old_clock _func  and 
then  set  interrupt  0x50  to  point  to  it, 
we  can  call  the  original  clock  interrupt 
by  generating  a  software  interrupt  0x50. 

PC  clones  use  variations  of  the  Intel 
8253  timer  chip  to  generate  the  system 
clock  interrupts.  When  MS-DOS  boots, 
it  sets  up  the  8253  to  generate  inter¬ 
rupts  every  54.9  msecs.  This  happens 
to  be  the  longest  interval  that  a  PC  can 
generate,  the  shortest  being  838  nsecs. 
The  longest  interrupt  is  generated  by 
setting  the  counter  to  count  65,536  clock 


ticks  (this  is  done  by  setting  the  16-bit 
decrement  counter  to  0).  Because  the 
timer  counter  is  an  integer,  not  only 
do  we  need  to  use  a  divisor  that’s  an 
integer  but  also  it  needs  to  divide  evenly 
into  65,536  (no  remainder).  Any  power 
of  2  will  work.  We  set  the  divisor  in  the 
function  set_up_user_real_time_task(  ) 
by  assigning  it  to  the  external  variable 
user_define_divisor.  For  example,  if  we 
want  interrupts  about  every  14  msecs, 
we  program  the  clock  with  65,536/ 
4=16,384  ( user_deflne_divisor  =  4).  This 
actually  gives  a  frame  time  of  13-73 
msecs.  Just  rememberto  use  13-73  msecs 
in  all  your  real-time  equations.  The  ac¬ 
tual  code  that  sets  the  timer  is  shown 
in  Listing  Four,  page  78.  Once  repro¬ 
grammed,  we  only  need  to  call  the 
original  clock  interrupt  every  four  clock 
interrupts  (see  Listing  Three). 

Communicating  Between  Tasks 

Now  that  we  have  the  two  tasks  run¬ 
ning,  we  need  to  get  them  talking  to 
each  other.  The  easy  way  to  do  this  is 
with  memory  common  to  each  func¬ 
tion  (external  variables).  The  common 
term  for  this  memory  is  DATAPOOL. 
The  best  way  to  demonstrate  this  is 
with  a  simple  example  (see  Listing  Five, 
page  78).  The  code  has  a  background 
task  that  continually  prints  out  the  value 


of  i,  and  the  real-time  task  continually 
changes  i  at  the  rate  of  the  frame  time. 
The  variable  i  is  common  to  both  tasks 
and  allows  them  to  communicate  with 
each  other. 

Limitations 

There  aren’t  too  many  limitations  to 
either  the  background  or  the  foreground 
task,  but  if  ignored  all  heck  will  break 
out: 

•  The  real-time  task  can’t  take  more 
time  to  run  than  the  frame  time.  Actu¬ 
ally  it  should  take  less  than  about  75 
percent  of  the  frame  time.  If  no  time  is 
left,  the  background  task  will  never 
have  time  to  run. 

•  MS-DOS  is  not  reentrant.  If  DOS  calls 
are  made  in  one  task,  they  can’t  be 
made  in  the  other.  If  the  background 
task  is  interrupted  by  the  real-time  task 
while  in  a  DOS  function,  then  the  real¬ 
time  task  makes  a  DOS  call,  and  the 
computer  will  probably  crash.  This 
doesn’t  really  create  a  problem  because 
most  DOS  functions  can’t  be  completed 
in  a  frame.  If  you  need  to  talk  to  a 
device  in  real-time,  you  should  write 
your  own  device  driver. 

•  Turbo  C’s  void  interrupt  function  saves 
all  the  80x86’s  registers.  What  it  fails  to 
do  is  save  the  registers  and  status  of  the 
80x87.  This  means  that  either  the  back¬ 


ground  or  the  real-time  task;  but  not 
both,  can  use  floating-point  math  (if 
you  don’t  have  a  coprocessor,  ignore 
this).  In  many  cases  this  also  doesn’t 
pose  a  problem.  In  a  lot  of  cases  the 
background  task  doesn’t  do  any  math, 
it  just  outputs  data.  If  you  have  an 
assembler,  inserting  the  three  lines  of 
the  in-line  assembler  of  Listing  Six,  page 
78,  in  real_time_task( )  will  rectify  the 
problem. 

Debugging  Real-Time  Tasks 

Debugging  the  real-time  part  of  a  sys¬ 
tem  can  pose  a  problem.  If  something 
happens,  the  interrupts  run  wild  and 
the  computer  usually  crashes. 

Debuggers  not  designed  for  real¬ 
time  systems  usually  don’t  work.  In 
effect,  debuggers  stop  the  program  at 
each  line  in  the  code.  This  is  fine  ex¬ 
cept  a  debugger  will  not  stop  the  clock 
interrupts.  This  means  that  if  the  de¬ 
bugger  is  in  the  real-time  function,  at 
the  next  clock  interrupt,  the  real-time 
function  will  reenter  itself.  This  is  sure 
to  cause  a  system  crash. 

The  old-fashion-way  to  debug  a  pro¬ 
gram  is  by  placing  print  statements  at 
strategic  locations  in  the  code.  This 
works  fine  if  the  code  doesn’t  have  to 
be  completed  in  a  specified  time.  The 
problem  with  a  real-time  task,  again, 
is  that  the  print  statement  will  usually 
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take  longer  to  complete  than  the  frame 
time,  causing  the  task  to  reenter  itself. 

The  way  to  get  around  this  is  not  to 
debug  in  real  time.  Set  up  both  the 
background  and  real-time  functions  as 
background  tasks,  calling  one  after  the 
other  (see  Listing  Seven,  page  78).  Now 
you  can  use  any  method  of  debugging. 


A  Simple  Spring-Mass  System 

Now  what  we’ve  all  been  waiting  for, 
a  real-time  model.  I’ve  included  a  real¬ 
time  program  that  models  a  simple 
spring-mass  system.  You’re  probably 
wondering  why  you  need  a  real-time 
system  to  model  a  spring-mass  system. 
You  really  don’t,  but  you  can  impress 
you’re  friends  when  you  show  them 
the  program  and  tell  them  it’s  a  real¬ 
time  model.  Actually,  a  spring-mass  sys¬ 
tem  is  an  excellent  application  to  dem¬ 
onstrate  the  concepts  of  real-time  mod¬ 
eling.  It  turns  out  that  the  frequency  at 
which  the  system  should  oscillate  (how 
often  it  bounces  back  and  forth)  can 
be  computed  easily. 

The  system  shown  in  Figure  3  has  a 
period  of: 

u  =  2*\/t(1  -  ?2) 


The  term  id  is  how  often  the  mass 
should  bounce  up  and  down  in  sec¬ 
onds.  The  spring-mass  program  uses 
the  following  values  for  m,  k,  and  m 
=  1.0182969  slugs,  k  =  10.0  lbs/inch, 
and  £  =  0.1.  These  values  give  a  period 
of  2.0  seconds. 

This  is  the  period  of  a  real  spring- 
mass  system.  If  we  went  out  and  bought 
a  lead  weight  that  had  a  mass  of  m, 
hung  it  under  a  spring  with  a  constant 
k  and  damping  ratio  £,  set  the  system 
in  motion,  and  used  a  stopwatch  to 
time  how  long  it  took  to  complete  one 
cycle,  the  stopwatch  would  read  2.0 
seconds. 


„  / 1.0134145 

*  =  r^(1 


Td  =  2.0  seconds 


0.012) 


If  we  just  write  a  normal  program  to 
model  this  (non-real-time),  the  rate  at 
which  the  program  will  oscillate  (the 
time  as  measured  by  the  stopwatch)  is 
anyone’s  guess.  What  we’re  going  to 
do  in  our  real-time  model  is  model 
what  the  mass  would  do  at  the  exact 
time  the  lead  weight  would  do  it.  Now, 
if  everything  works,  the  program  will 
display  a  graphical  model  of  a  mass 
having  a  period  of  two  seconds.  If  we 
hang  the  lead  weight  next  to  the  com¬ 
puter  screen  and  start  both  the  weight 
and  computer  at  the  same  time,  the 
lead  weight  and  computer  model  will 
move  in  unison.  You’ll  have  to  run  the 
program  to  prove  it  to  yourself. 

And  what’s  amazing  is,  it  doesn’t 
matter  what  computer  you  run  the  pro¬ 


gram  on,  from  the  slowest  XT  to  the 
fastest  386  the  graphics  display  will 
always  have  the  same  period  — that  is, 
as  long  as  the  computer  has  a  copro¬ 
cessor  (you’ll  overrun  the  frame  time 
without  one).  Ah,  the  magic  of  real 
time.  The  only  thing  that  will  change 
on  different  computers  is  how  often 
the  screen  is  updated.  The  faster  your 
computer,  the  faster  the  display  will 
be  updated. 

Implementing  the  Spring-Mass 
System 

Using  a  little  college-level  dynamics, 
the  differential  equation  of  motion  can 
be  written  for  the  system  as  follows: 


mi  +  ci  +  kx  =  0 


This  equation  gives  us  the  acceleration 
of  the  mass;  but  what  we  want  is  the 
position  of  the  mass.  All  we  have  to 
do  to  get  the  position  is  solve  this  equa¬ 
tion  (a  second-order-homogeneous,  lin¬ 
ear  differential  equation)  — that  is: 

?  °  sin  \/l  —  f2w„f+ 

1-t2 


Xa  cos  vl  —  f  2Wnt 

where: 

•  x  0  is  the  initial  velocity  of  the  sys¬ 
tem.  This  is  set  to  0  in  our  model. 

•  con  is  the  circular  frequency  of  the 
system;  with  (0n  =  V (k/m ) 

•  t  is  the  current  time.  We  increment 
this  by  the  frame  time  every  frame  — 
that  is,  t=  t  +  frame  time. 

•  x0  is  the  initial  position  of  the  system. 
This  is  set  to  30.0  in  our  model. 

•  £  is  the  damping  ratio  of  the  spring- 
mass  system,  with  ;  _  c_i 


Once  we  substitute  these  values  into 
our  position  equation,  we  get: 

x  =  sin  >/l  =  <W+ 

(unV/l  -  ?2 


This  equation  is  the  essence  of  our 
real-time  model.  The  only  thing  left  is 
the  frame  time.  For  our  spring-mass 
system,  I  picked  a  frame  time  of  54.9/4 
=  13.73  msec,  or  0.01373  seconds. 

Conclusion 

The  real-time  modeling  program  is  bro¬ 
ken  into  three  files.  The  first  file  con¬ 
tains  all  the  real-time  kernel  functions 
(see  realtime. c  in  Listing  Eight,  page 
78).  The  next  two  files  contain  all  the 
user  functions,  massfor.c  (Listing  Nine, 
page  80)  contains  all  the  real-time,  or 
foreground,  functions  — set_up_user_ 
real_time_task( ),  set_down_user_  real_ 
time_task( ),  and  user_defined_real_ 
time_task( ).  massbck.c  (Listing  Ten, 
page  80)  contains  all  background  func¬ 
tions  — set_up_user_background(  ),set_ 
down_user_background( ),  and  user_ 
defined_background_task(  ). 

To  implement  your  own  real-time 
model,  just  replace  massfor.c  and 
massbck.c  with  your  own  .  .  ,_user_.  .  . 
functions.  And  who  says  MS-DOS  isn’t 
a  real-time  operating  system? 
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ARTICLES 


A  Benchmark  Apologia 

Credible  benchmarks  are  oftentimes  the  exception, 
rather  than  the  rule 


G.  Michael  Vose  and  Dave  Weil 


Battered  and  berated,  benchmarks 
might  remind  you  of  Wiley  E. 
Coyote:  They  keep  getting  blown 
up  but  they  never  seem  to  go  away. 
Consistently  outsmarted  by  those  cun¬ 
ning  optimizing  compiler-writing  road- 
runners,  benchmarks  put  on  a  new  face 
almost  yearly  and  dive  back  into  the 
performance-testing  fray. 

Wiry  do  we  bother  with  benchmarks? 
What  have  they  done  for  us  lately?  If 
they  are  so  easy  to  trick,  what  is  to  be 
gained  by  testing  software  with  bench¬ 
marks?  Will  compiler  technology  al¬ 
ways  be  one  step  ahead  of  benchmarks, 
which  supposedly  help  us  evaluate  new 
software?  Which  comes  first:  the  test 
suite  or  the  product  to  test? 

On  the  plus  side,  benchmarks  can 
help  us  sort  out  real  compiler  perform¬ 
ance  from  compiler  vendor  hype.  They 
can  help  uncover  the  flaws  in  a  com¬ 
piler  or  show  where  a  compiler  is  strong. 
Benchmarks  even  occasionally  expose 
bugs  and  language  implementation 
errors. 

But  benchmarks  can  also  mislead 
us  into  thinking  a  compiler  doesn’t  per¬ 
form  well,  when  the  real  problem  is  the 
benchmark  itself.  Conversely,  a  com¬ 
piler  may  show  outstanding  perform¬ 
ance  on  a  benchmark  only  to  prove 
mediocre  in  real-world  situations.  Know¬ 
ing  where  the  problem  lies  — in  the 
compiler  or  in  the  benchmark — can 
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be  tricky. 

Ignoring  the  vast  problems  encoun¬ 
tered  in  using  benchmarks  to  measure 
computer  hardware  performance,  let’s 
look  at  the  practice  of  benchmarking 
language-compiler  software  to  see  if 
benchmarks  can  tell  us  anything  use¬ 
ful.  This  discussion  can  also  highlight 
the  pitfalls  we  might  encounter  in  de¬ 
signing  and  using  compiler  benchmarks 
and  evaluating  their  results. 

What  To  Test ? 

Benchmarks  often  try  to  do  too  much. 
They  often  attempt  to  test  several  dif¬ 
ferent  qualities  of  a  compiler  and  then 
represent  the  results  of  those  tests  as 
one  monolithic  total.  This  is  sort  of  like 
using  a  college  graduate’s  overall  grade 
point  average  to  figure  out  how  good 
he  or  she  will  be  at  math.  This  flaw  in 
benchmarks  raises  a  fundamental  ques¬ 
tion  about  what  they  are  trying  to  meas¬ 
ure. 

The  primary  performance  issues  for 
compiler  testers  encompass  several  fun¬ 
damental  compiler  operations:  code  qual¬ 
ity,  including  its  compactness  and  its 
speed  of  execution;  compiling  speed; 
compiler  features,  such  as  support  for 
different  memory  models  and  compiler 
settings,  or  switches;  and  standards  con¬ 
formance. 

The  secondary  compiler  issues  sub¬ 
ject  to  testing  by  benchmarks  include 
the  environment  of  the  compiler  and 
the  operation  of  the  compiler  on  differ¬ 
ent  hardware  platforms.  So  the  first  step 
in  designing  benchmarks  is  to  figure 
out  what  to  measure.  After  you  decide 
what  you  want  to  measure,  then  you 
can  set  out  to  design  a  test  algorithm 
to  generate  some  data. 

Testing  individual  statements  or  ex¬ 
pressions  is  extremely  difficult.  Design¬ 
ing  a  test  to  determine  the  speed  of 
pointer  dereferencing  or  integer  math 


operations  exposes  the  benchmark 
writer  to  a  variety  of  pitfalls.  These 
pitfalls  include  the  use  of  loops  to  ex¬ 
tend  the  execution  of  the  test  code  to 
some  meaningful,  measurable  time  pe¬ 
riod.  Using  loops  to  iterate  some  piece 
of  test  code  fifty  thousand  to  one  hun¬ 
dred  thousand  times  to  obtain  a  bench¬ 
mark  time  of  one  to  two  seconds  raises 
the  question  of  whether  the  bench¬ 
mark  is  measuring  the  test  code  or  the 
compiler’s  loop  overhead.  In  bench¬ 
marks  that  run  for  only  one  to  two 
seconds,  a  time  differential  of  only  one- 
third  of  a  second  may  create  times  too 
small  to  measure  accurately. - 

Loops  also  frequently  fall  victim  to 
compiler  optimizations.  A  good  com¬ 
piler  can  pull  loop  invariant  code  out 
of  a  loop  and  thereby  distort  the  result 
of  a  benchmark.  In  some  extreme  cases, 
as  we’ll  explain  in  one  of  the  examples 
that  follow,  an  optimizing  compiler 
might  do  away  with  a  loop  altogether. 
Compilers  can  also  unroll  a  loop  and 
break  down  the  loop  to  a  serial  se¬ 
quential  operation,  while  leaving  oth¬ 
ers  inside;  this  also  will  distort  a  bench¬ 
mark’s  results  unless  you  are  trying  to 
measure  a  compiler’s  ability  to  opti¬ 
mize  loop  code.  But  such  a  test  may 
not  tell  you  anything  about  the  quality 
of  the  code  generated  for  the  body  of 
the  loop. 

One  way  to  lessen  the  problems  of 
using  loops  in  benchmarks  is  to  place 
a  large  body  of  code  within  the  loop. 
Large  code  blocks  do  not  necessarily 
prevent  loop  optimizations  from  tak¬ 
ing  place,  but  they  do  ensure  that  the 
loop  overhead  is  not  significant  com¬ 
pared  with  the  time  spent  doing  the 
operations  inside  the  loop  — suppos¬ 
edly  what  you  are  trying  to  measure. 

Trying  to  test  individual  statement 
execution  probably  isn’t  useful  any¬ 
way.  Even  if  you  could  determine  that 
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a  compiler  dereferenced  pointers  at  blaz¬ 
ing  speeds,  an  application  probably 
wouldn’t  spend  much  of  its  time  dere¬ 
ferencing  pointers.  Testing  individual 
expressions  might  not  paint  an  accu¬ 
rate  portrait  of  a  compiler’s  perform¬ 
ance  for  a  total  application.  If  you 
wanted  to  know  how  well  a  compiler 
handles  floating-point  operations,  the 
best  test  you  could  devise  would  be  a 
floating-point  intensive  application,  such 
as  an  FFT  algorithm.  Using  real  work¬ 
ing  code  can  often  yield  more  mean¬ 
ingful  performance  data  about  compil¬ 
ers  than  an  artificially  contrived  test 
can. 

Knowing  exactly  what  you  are  test¬ 
ing  becomes  crucial  in  a  variety  of  situ¬ 
ations.  One  common  area  of  confusion 
is  that  gray  area  where  a  compiler  and 
an  operating  system  overlap.  For  ex¬ 
ample,  does  a  disk  I/O  benchmark  test 
a  compiler’s  ability  to  handle  files  or  its 
calls  to  the  operating  system?  Does  that 
matter  as  long  as  you  always  bench¬ 
mark  compilers  under  the  same  operat¬ 
ing  system?  Do  disk  I/O  routines  ever 
go  directly  to  the  hardware  and  bypass 
the  operating  system? 

A  recently  published  operating  sys¬ 
tem  benchmark  suffered  from  a  misun¬ 
derstanding  of  the  gray  area  where  com¬ 
pilers  and  operating  systems  intersect. 
The  benchmark  sought  to  test  the  op¬ 
erating  system’s  virtual  memory  man¬ 
ager.  It  created  a  large  array  and  ac¬ 
cessed  elements  in  the  array.  But  the 
compiler  used  to  compile  the  bench¬ 
mark  mapped  the  array  in  such  a  man¬ 
ner  as  to  cause  a  segment  swap  with 
each  array-element  access.  The  result¬ 
ing  test  of  the  virtual  memory  manager 
turned  out  to  be  a  test  of  the  compiler’s 
memory  manager  instead.  The  operat¬ 
ing  system  got  blamed  for  poor  per¬ 
formance,  but  the  compiler  was  the 
culprit. 

A  common  pitfall  in  designing  com¬ 
piler  tests  is  a  failure  to  isolate  the 
routines  that  do  the  work  that  you  ac¬ 
tually  want  to  measure.  To  measure  the 
speed  of  matrix  multiplication,  for  ex¬ 
ample,  a  test  might  set  up  two  arrays 
and  then  multiply  them.  Measuring  the 
time  needed  to  set  up  the  arrays,  as 
well  as  the  time  needed  to  make  the 
matrix  multiplications,  does  not  tell  you 
how  well  the  compiler  generates  code 
to  do  matrix  math.  The  timing  routine 
needs  to  be  placed  around  the  multi¬ 
plication  operation,  not  around  all  the 
declaration  and  set-up  code. 

Today  you  must  possess  a  knowl¬ 
edge  of  optimization  techniques  in  or¬ 
der  to  test  compilers.  If  you  want  to 
measure  code  compactness,  particularly 
for  a  modern  optimizing  compiler,  you 
must  create  test  algorithms  that  cannot 
be  reduced  in  size  by  a  given  optimiza¬ 


tion  technique  unless  you  specifically 
want  to  measure  the  implementation 
of  that  optimization.  Not  knowing  how 
a  given  piece  of  test  code  might  be 
optimized  leaves  you  wide  open  to 
generating  misleading  data.  Another  com¬ 
plication  is  that  you  also  can’t  always 
assume  that  a  compiler  optimizes  code 
just  because  the  vendor  claims  it  can; 
one  well-known  Unix  C  compiler  pur¬ 
ports  to  do  common  subexpression  elimi¬ 
nation  but  actually  performs  this  opti¬ 
mization  in  only  the  simplest  of  cases. 

Evaluating  Results 

Possibly  the  hardest  part  of  using  bench¬ 
marks  is  interpreting  their  results.  The 
proper  design  and  coding  of  bench- 
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marks  minimizes  this  problem.  But  even 
well-done  tests  can  be  overinterpreted 
or  occasionally  misinterpreted. 

Many  benchmarks  leave  themselves 
open  to  improper  interpretation  because 
they  fail  to  produce  verifiable  results. 
If  a  compiler’s  code  executes  an  algo¬ 
rithm  25  percent  faster  than  its  rivals 
but  calculates  a  wrong  answer,  how 
do  you  interpret  its  performance?  If 
you  don’t  know  it  calculated  an  incor¬ 
rect  answer,  you  may  arrive  at  an  un¬ 
warranted  conclusion.  Benchmarks 
should  always  calculate  a  verifiable  so¬ 
lution  to  a  problem. 

Interpreting  benchmarks  also  suffers 
from  an  intrinsic  fault  of  benchmarks: 
their  size.  Benchmark  code,  because  it 
needs  to  be  portable  and  easily  read, 
frequently  is  brief.  But  can  tests  using 
a  small  piece  of  code  be  extrapolated 
to  similar  performance  characteristics 
when  code  size  grows  to  hundreds  or 
thousands  of  lines?  Small-test  code  usu¬ 
ally  gets  compiled  with  a  small-  or  me¬ 
dium-memory  model;  will  the  results 
of  these  restricted-memory  operations 
apply  to  laige-  and  huge-memory  model 
programs? 

Compilers  may  store  data  differently 
for  specific  memory  models,  particu¬ 
larly  for  large  data  models.  One  com¬ 
piler  may  store  data  in  the  near  data 
segment  until  this  segment  overflows 
and  then  store  subsequent  data  in  far 
data  segments;  another  may  choose  to 
store  all  data  larger  than  a  certain  thresh¬ 
old  size  — or  all  uninitialized  data  — in 
far  data  segments.  For  example,  Micro¬ 


soft  C  always  stores  uninitialized  array 
data  in  a  far  data  segment.  The  com¬ 
piler  does  not  know  how  big  the  array 
will  be,  because  arrays  can  have  dif¬ 
ferent  sizes  in  different  modules  (as 
long  as  they  are  not  initialized),  and 
the  linker  resolves  the  space  allocation 
problem  by  allocating  space  for  the 
largest  size.  This  is  called  common 
model;  the  name  is  taken  from  the  For¬ 
tran  concept  of  Common  data.  Initializ¬ 
ing  the  array  will  ensure  that  it  goes 
into  the  near  data  segment  if  it  is  less 
than  32K  in  size.  This  memory  model 
specific  treatment  of  data  can  affect  the 
performance  of  a  compiler  on  a  bench¬ 
mark,  such  as  the  Sieve.  These  factors 
can  be  controlled  in  most  compilers  via 
initialization,  by  keywords  such  as  near 
or  far,  or  by  control  of  the  data  thresh¬ 
old  size. 

Now  that  we've  entered  the  32-bit 
era,  another  frequent  benchmark  prob¬ 
lem  is  whether  ints  are  16  or  32  bits. 
One  compiler  vendor  recently  related 
that  several  of  his  customers  called  to 
complain  that  his  new  compiler  was 
25  percent  slower  than  a  popular  com¬ 
peting  compiler  on  a  certain  integer- 
math  benchmark.  The  benchmark  re¬ 
ally  only  used  16-bit  integers,  but  peo¬ 
ple  testing  a  32-bit  80386  compiler  de¬ 
clared  all  the  integers  as  32  bits.  The 
compiler  had  to  add  extra  code  to  cope 
with  storing  16-bit  numbers  in  32-bit 
data  areas  — code  that  slowed  it  down 
by  25  percent.  Recoding  in  16  bits 
showed  this  compiler  to  be  superior 
to  the  competing  compiler.  This  inci¬ 
dent  shows  how  the  assumptions  made 
when  running  and  interpreting  bench¬ 
marks  can  create  false  impressions. 

Another  common  problem  with  in¬ 
terpreting  benchmark  results  is  inequali¬ 
ties  in  testing  procedures.  For  example, 
a  tester  once  walked  into  a  room  full 
of  80386  machines  and  started  plug¬ 
ging  in  a  disk  containing  an  executable 
file  of  what  he  thought  was  a  good 
benchmark.  As  he  went  from  machine 
to  machine  recording  test  results,  he 
uncovered  some  wide  disparities.  Later 
snooping  revealed  that  the  machines 
had  different-sized  caches  and  different 
expanded  memory  managers;  both  the 
caches  and  memory  managers  had  been 
installed  at  boot  time.  Therefore  the 
benchmark  results  were  skewed  by  fac¬ 
tors  not  immediately  apparent.  The 
tester’s  mistake,  of  course,  was  in  not 
carefully  controlling  all  the  factors  that 
could  affect  the  results. 

Another  example  of  inequitable  test 
procedures  shows  up  in  some  tests  of 
file  I/O.  One  recent  benchmark  at¬ 
tempted  to  measure  the  efficiency  of 
low-level  file  I/O  by  writing  a  large  file 
to  disk  and  then  performing  random 
seeks  in  the  file,  reading  and  writing 
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pieces  of  the  file.  When  this  operation 
used  media  such  as  a  floppy  disk,  run¬ 
ning  the  same  program  consecutively 
with  different  compilers  while  deleting 
the  test  file  between  runs  resulted  in 
each  compiler  performing  the  test  more 
slowly  than  the  previous  one.  Was  this 
because  the  compilers  were  really  less 
efficient?  The  problem  here  stemmed 
from  the  fact  that  the  files  were  created 
on  different  areas  of  the  disk  (farther 
out  each  time)  because  of  the  oper¬ 
ating  system’s  scheme  for  allocating 
disk  sectors.  Therefore  the  disk  head- 
seek  time  became  significant  (because 
of  the  way  the  file  was  written)  and 
affected  each  subsequent  run.  When 
the  test  was  rerun  with  a  reformatted 
disk  to  ensure  that  the  file  was  always 
created  in  the  same  place  on  the  disk, 
each  compiler  ran  the  benchmark  in 
almost  the  identical  amount  of  time. 
Were  they  all  equally  good  at  low-level 
file  I/O?  Profiling  this  benchmark  re¬ 
vealed  that  it  spent  more  than  95  per¬ 
cent  of  its  time  in  the  operating  system 
and  less  than  five  percent  of  its  time  in 
the  actual  filehandling  code,  so  the  bench¬ 
mark  was  really  measuring  the  oper¬ 
ating  system.  The  only  compiler  that 
had  a  signifkandy  different  time  (faster) 
on  this  benchmark  did  some  internal 
buffering  to  cut  down  on  the  number 
of  system  calls  made  (this,  however, 
subverted  the  use  of  low-level  I/O)  to 
force  information  direcdy  to  the  disk. 

A  compiler’s  options  also  complicate 
the  benchmark  problem.  When  testing 
compilers  you  must  know  what  com¬ 
piler  switches  to  set  to  generate  the 
equivalent  code  from  each  compiler 
to  make  the  tests  as  fair  as  possible. 
Optimization  levels  are  a  prime  exam¬ 
ple.  If  you  decide  to  run  all  bench¬ 
marks  using  the  default  switch  settings 
for  all  the  compilers  you  test,  some 
compilers  will  default  to  no  optimiza¬ 
tion,  others  will  default  to  full  opti¬ 
mization,  and  still  others  will  fall  some¬ 
where  in  between.  This  lack  of  care  in 
testing  can  mislead  for  the  following 
reasons. 

•  You  provide  no  information  on  what 
these  defaults  were  for  each  com¬ 
piler. 

•  The  testing  compares  apples  to  or¬ 
anges. 

•  Most  users  do  not  exhibit  the  same 
lack  of  care  in  running  their  com¬ 
piler,  except  perhaps  when  first  get¬ 
ting  accustomed  to  it. 

Stack  checking  is  another  example  of 
an  area  where  compiler  defaults  can 
differ.  Some  compilers  turn  stack  check¬ 
ing  on  by  default,  and  others  turn  it 
off.  On  a  benchmark  such  as  the  Fibo¬ 
nacci,  stack  checks  could  have  a  huge 


effect  on  execution  time  even  though 
virtually  every  compiler  provides  some 
user  control  over  stack  checks.  Bench- 
markers  must  be  sensitive  to  the  need 
for  compilers  to  be  compared  on  equal 
terms. 

The  Good  and  the  Bad 

There  are  many  examples  of  both  good 
and  bad  benchmarks.  The  Dhrystone, 
Whetstone,  and  Sieve  benchmarks  have 
been  around  for  quite  some  time,  and, 
although  not  perfect,  are  at  least  well 
understood. 

The  Dhrystone  benchmark,  Version 
1.1,  is  susceptible  to  some  string-han¬ 
dling  optimizations.  It  also  produces 
no  output  that  you  can  check  for  accu¬ 
racy.  But  the  Dhrystone  still  is  one  of 
the  better  benchmarks,  because  it  does 
test  a  good  mix  of  statements  and  op¬ 
erations.  One  major  exception  is  floating¬ 
point  operations:  Dhrystone  does  no 
floating-point  tests  even  though  some 
testers  make  the  mistake  of  judging 
floating-point  performance  by  running 
the  Dhrystone.  A  new  version  of  the 
Dhrystone  currently  being  written  will 
address  these  problems. 

The  Whetstone  benchmark  does  test 
floating-point  operations  and  has  also 
been  around  for  a  long  time.  Whet¬ 
stone  performance  can  get  a  boost  from 
compilers  that  insert  in-line  code  for 
certain  routines,  and  this  benchmark 
also  contains  some  loop  invariant  code 
that  can  be  taken  out  of  a  loop.  The 
Whetstone  benchmark  also  exhibits  a 
frustrating  lack  of  verifiability,  because 
it  produces  no  output  that  you  can 
check  but  performs  many  complex  op¬ 
erations  that  open  the  door  to  a  lot  of 
potentially  wrong  answers. 

The  Sieve  benchmark  tests  a  com¬ 
piler’s  ability  to  perform  integer  opera¬ 
tions,  memory  references,  and  simple 
control  structures,  such  as  loops.  The 
Sieve  calculates  a  testable  result,  prime 
numbers,  and  deserves  high  marks  as 
a  test  whose  output  you  can  verify. 
But,  like  other  benchmarks,  the  Sieve 
tests  just  a  few  operations  in  a  small 
memory  environment  and  therefore  can¬ 
not  tell  you  much  about  the  many  op¬ 
erations  that  it  doesn’t  test.  Plus,  as 
mentioned  earlier,  the  Sieve’s  results 
can  be  misleading  if  you  don’t  account 
for  an  individual  compiler’s  method  of 
handling  uninitialized  arrays. 

Other  well-known  benchmarks  leave 
a  lot  to  be  desired.  The  so-called  Loop 
and  Float  benchmarks  have  major  flaws, 
as  do  some  disk  I/O  benchmarks.  One 
version  of  the  Fibonacci  benchmark 
frequently  gets  misinterpreted. 

The  Float  benchmark  provides  a  clas¬ 
sic  example  of  how  an  optimizing  com¬ 
piler  can  destroy  a  poorly  written  test 
algorithm.  The  Float  algorithm  (see  - 


Example  1)  performs  a  series  of  multi¬ 
plication  and  division  operations  in¬ 
side  a  loop.  An  optimizing  compiler 
can  reduce  this  code  to  a  simple  as¬ 
signment  operation,  c  =  b.  The  com¬ 
piler  first  propagates  constants  and 
discovers  that  they  have  a  sequence  of 
assignments  of  the  form 

for  (...)( 

c  =  CONST_VAL_l ; 

C  =  CON  ST_VAL_2 ; 
c  =  CONST_VAL_l ; 
c  =  CONST_VAL_2; 

.... 

The  compiler  will  then  throw  away  the 
extra  stores  to  c,  leaving  only  C  = 
CONST_VAL_2.  Next  the  loop  optimizer 
hoists  this  code  out  of  the  loop,  be¬ 
cause  it  is  invariant,  leaving  simply  c  =  b. 
This  program  could  be  modified  in  one 
of  several  simple  ways  to  prevent  this 
optimization.  Initializing  the  variables 
a  and  b  with  a  function  call,  as  in 
init(&a,  &h); ,  will  prevent  constant  propa¬ 
gation.  Alternatively,  modifying  the  body 
of  the  loop  so  that  a  or  b  or  both  also 
get  modified  would  prevent  this  opti¬ 
mization,  unless  the  compiler  was  also 
smart  enough  to  do  the  following  in¬ 
duction  analysis: 

for  (....)( 

c  =  a  *  b; 
a  *=  a; 
b-=a; 

i" 


txupl*  1 

/*  The  floating  point  arithmetic  benchmark 

*  does  repeated  multiplications  & 

divisions  in  a  loop  that  is 

*  large  enough  to  make  the  looping  time 

insignificant.  This 

*  program  is  from  the  August  1983  issue 

of  Byte  magazine. 

*/ 

♦include  <stdio.h> 

♦define  C0NST1  3.141597E0 

♦define  C0NST2  1.7839032E4 

♦define  COUNT  50000 

main  () 

{ 

double  a,  b,  c; 

unsigned  int  i; 

time_0 (); 

a  =  C0NST1; 

b  =  C0NST2; 

for(  i  =  0;  i  <  COUNT;  ++i) 

{ 

c  =  a  *  b; 
c  =  c  /  a; 
c  =  a*b; 
c  =  c  /  a; 
c  =  a  *  b; 
c  =  c  /  a; 
c  =  a  *  b; 
c  =  c  /  a; 
c  =  a  *  b; 
c  =  c  /  a; 
c  =  a  *  b; 
c  =  c  /  a; 
c  =  a  *  b; 
c  =  c  /  a; 

) 

fprintf  (stderr,  "%d\n",  time_n()); 

} 
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Exaapl*  2 

/*  The  Fibonacci  benchmark  tests 


♦include  <stdio.h> 

♦define  NT1MES  34 
♦define  NUMBER  24 

main  () 

{ 

int  i; 

unsigned  value,  fib(); 
time_0 () ; 

printf  ("%d  iterations:  ",  NTIMES) ; 

for(  i  -  1;  i  <=  NTIMES;  i++  ) 
value  =  fib (NUMBER); 

printf  ("\n"); 

fprintf  (stderr,  "%d\n",  time_n () ) ; t 
} 

unsigned  fib(x) 
int  x; 

{ 

if(  x  >  2  ) 

return  (fib(x-l)  +  fib(x  -  2)).: 

else 

return  (1); 

) 


The  Whetstone  benchmark  provides 
good  examples  of  this  kind  of  unoptimi- 
zable  loop. 

The  Fibonacci  test  provides  another 
example  of  how  benchmarks  can  mis¬ 
lead  if  the  results  are  not  interpreted 
correctly.  This  benchmark  (see  Exam¬ 
ple  2)  computes  a  Fibonacci  number 
sequence  using  recursion.  But  using 
iteration  might  be  more  efficient.  This 
benchmark  really  tests  function-call  over¬ 
head.  The  issue  here  boils  down  to  the 
question:  What  do  the  results  mean? 

This  benchmark  is  small  enough  and 
straight  forward  enough  that  most  com¬ 
pilers  generate  similar  code  for  it.  But 
test  results  show  that  compilers  that 
often  do  well  on  most  other  bench¬ 
marks  sometimes  lose  badly  on  this 
one.  The  reason  has  to  do  with  register 
variables.  If  a  compiler  does  not  imple¬ 
ment  register  variables,  the  code  for 
the  path  that  computes  fib(x-l)  +  fib 
(x-2);  will  look  like  this  (in  pseudo¬ 
assembler): 

push(x-l) 
call  fib 

push  ax  ;  save  result  in  memory 

push(x-2) 

call  fib 

pop  bx  ;  retrieve  saved  result 
add  ax,bx  ;  add  current  result  and 
saved  result 

A  compiler  that  implements  register  vari¬ 
ables  produces  this  code: 

push(x-l) 
call  fib 

mov  si, ax  ;  save  result  in  register 

push(x-2) 

call  fib 

add  ax, si  ;  add  current  and  save 

results 


This  latter  sequence  will  always  exe¬ 
cute  faster.  Because  these  compilers 
must  save  and  restore  the  value  of  the 
register  si  every  time  the  function  is 
called  — and  because  this  path  is  taken 
only  one-half  the  times  that  Jib  is  called  — 
the  overhead  of  the  save/restore  on 
each  call  is  greater  than  the  overhead 
to  save/restore  the  intermediate  result 
in  memory.  The  compiler  that  uses  reg¬ 
ister  variables,  contrary  to  what  your 
expectations  may  be,  runs  slower  than 
one  that  does  not. 

In  most  cases,  however,  register  vari¬ 
ables  help  produce  more  compact  code 
and  enhance  an  algorithm’s  execution 
speed.  This  Fibonacci  algorithm  really 
is  an  exception  rather  than  the  rule 
(other  ways  to  alleviate  this  problem 
include  saving/restoring  si  only  in  the 
path  where  it  is  used).  But  benchmark- 
ers  seldom  engage  in  this  kind  of 
analysis. 

The  Loop  benchmark  was  originally 
created  to  factor  out  loop  overhead  in 
benchmarks  that  used  loops  to  artifi¬ 
cially  increase  a  benchmark’s  running 
time  rather  than  increase  the  number 
of  operations  at  the  source  level.  The 
problem  with  this  technique  is  that  many 
compilers  that  perform  loop  optimiza¬ 
tions  will  remove  these  loops,  not  as  a 
benchmark  ploy,  but  because  other  loop 
optimizations  may  result  in  empty  loop 
bodies.  For  example,  loop  unrolling 
on  loops  that  iterate  a  small  number  of 
times,  as  in 

float  a[4];, 

for  (i  =  0;  i  <  4;  i++)  ( 

a[i]  =  (float)i; 

) 

might  well  be  expanded  to  four  indi¬ 
vidual  assignments  and  the  loop  re¬ 
moved  entirely. 

A  better  solution  to  the  problem  of 
dealing  with  loop  overhead  is  to  sim¬ 
ply  make  sure  that  the  body  of  the  loop 
is  large  and  complex  enough  that  the 
loop  overhead  is  insignificant. 

So  how  can  you  protect  yourself  from 
misleading  benchmark  claims?  Always 
insist  on  benchmarks  that  provide  veri¬ 
fiable  output  so  that  you  can  at  least 
be  certain  the  code  a  compiler  gener¬ 
ates  will  correctly  execute  instructions. 
Read  benchmark  code  whenever  you 
can  to  judge  the  vulnerability  of  the 
test  algorithms  to  optimization.  And  be 
sure  to  find  out  if  all  the  conditions 
were  the  same  when  a  given  test  was 
performed  on  competing  systems. 

The  Acid  Test 

There  will  probably  never  be  a  perfect 
compiler  benchmark.  Compiler  tech¬ 


nology  marches  forward  at  a  steady 
rate,  and  performance  tests  almost  al¬ 
ways  follow  the  creation  of  new  com¬ 
piler  techniques. 

To  protect  yourself  as  you  evaluate 
compilers,  you  need  to  remember  a 
few  simple  but  important  ideas: 

•  Understand  what  a  test  really  meas¬ 
ures. 

•  Understand  optimizations  and  how 
they  affect  code. 

•  Understand  that  compilers  make  as¬ 
sumptions  about  data  storage,  optimi¬ 
zations,  and  so  on. 

•  Understand  the  importance  of  an  equal 
environment  for  running  tests. 

•  Take  care  in  interpreting  benchmark 
results. 

The  true  measure  of  any  compiler  is 
how  well  it  suits  your  programming 
style  and  application  needs.  Bench¬ 
marks  might  be  more  useful  if  they 
measured  compiler  performance  on  a 
variety  of  common  tasks,  ranging  from 
heavily  compute-bound  tasks  (for  ex¬ 
ample,  the  FFT  program  for  floating¬ 
point  operations,  [scalar]  matrix  inver¬ 
sion  for  array  manipulation,  table  look¬ 
ups  or  tree  manipulation  for  pointers) 
to  I/O  bound  operations  (for  example, 
an  object  decoder,  such  as  the  one 
used  at  Microsoft).  Similar  kinds  of  ap¬ 
plications  could  test  other  library-re¬ 
lated  items,  such  as  string  manipula¬ 
tion,  memory  allocation,  and  the  like. 
Benchmarks  that  are  too  simple  tell 
you  little,  and  most  compilers  end  up 
looking  much  the  same. 

Developments  of  the  future  will  no 
doubt  create  a  need  to  test  multitasking 
compiler  operations,  real-time  applica¬ 
tions,  and  multiprocessor  systems.  These 
complex  systems  will  only  add  to  the 
problems  of  creating  realistic  and  cred¬ 
ible  benchmarks.  But  knowing  the  pit- 
falls  can  help  us  differentiate  the  signal 
from  the  noise. 
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ARTICLES 


A  C++  Multitasking  Kernel 


In  a  multitasking  environment,  C++  lets  you  define 

tasks  as  object 


About  two  years  ago,  the  com¬ 
pany  I  work  for  started  using  a 
multitasking  kernel  on  our  Mul¬ 
tibus  II  SCSI  and  communications  con¬ 
trollers.  This  was  my  first  exposure  to 
a  multitasking  kernel,  and  I  was  curi¬ 
ous  about  the  algorithms  required  to 
run  multiple  threads  of  code  on  a  sin¬ 
gle  processor.  I  decided  to  try  to  write 
a  small  preemptive  kernel  (a  kernel 
that  switches  tasks  by  using  a  timer)  for 
the  MS-DOS  environment.  For  my  first 
attempt  I  used  Turbo  C,  and  I  wrote  a 
small  working  kernel  in  a  couple  of 
weeks.  The  kernel  stole  the  MS-DOS 
timer-tick  interrupt  and  switched  be¬ 
tween  tasks  (C  functions  that  repeat 
forever)  with  each  timer  tick. 

When  the  Zortech  C++  compiler  came 
out  for  MS-DOS  machines,  I  immedi¬ 
ately  bought  it  and  started  to  rewrite 
my  kernel.  C++  objects,  I  thought,  were 
perfect  for  a  multitasking  kernel.  Tasks 
would  be  objects  that  the  task_control 
object  would  communicate  with  and 
switch  between.  C++  would  also  allow 
task  objects  to  make  all  of  their  data 
private,  and  task  objects  could  be  cre¬ 
ated  with  a  constructor  that  required 
parameters.  The  task_control  object 
would  also  keep  all  data  private  and 
supply  several  routines  so  that  users 
could  add  tasks,  start  and  stop  multi¬ 
tasking,  and  so  on. 

I  used  Modula-2  for  the  model  when 
designing  task  communication.  The  sig¬ 
nal  object  is  modeled  on  the  Modula-2 
data  type  that  you  see  in  many  Modu¬ 
la-2  packages.  This  object  is  used  by  a 
task  to  send  or  receive  a  message,  and 
it  supplies  a  fast  and  lean  interface.  I 
added  a  block  routine  (which  allows  a 
task  to  voluntarily  give  up  control)  and 
a  task-control  routine  that  allows  a  task 
to  stop  task  switching  if  it  is  calling  a 
routine  that  is  not  reentrant  (MS-DOS, 
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BIOS,  or  C  library  routines). 

The  kernel  presented  here  may  seem 
like  a  very  minimal  kernel,  and  that’s 
because  it  was  meant  to  be.  If  you 
understand  how  the  kernel  works,  how¬ 
ever,  you  will  find  that  it  is  easy  to 
expand  and  customize.  There  are  many 
different  design  philosophies  for  ker¬ 
nels,  but  I  think  that  this  kernel  sup¬ 
plies  what  you  need  for  most  program¬ 
ming  situations. 

Objects  and  Task-Switching 
Overview 

This  kernel  uses  three  C++  classes: 
task_control,  task,  and  signal.  If  you 
are  new  to  C++,  a  quick  explanation 
might  be  in  order. 

A  “class”  is  similar  to  a  C  structure; 
in  fact,  in  C++  a  structure  is  a  class  in 
which  all  members  are  public.  The  data 
in  a  class  can  be  public  or  private.  A 
class  can  also  have  "methods”  (another 
name  for  a  function)  associated  with  it. 
An  object  is  a  variable  of  a  specific 
class.  When  an  object  is  instantiated, 
space  is  allocated  for  all  of  the  data 
(public  and  private)  and  a  set  of  meth¬ 
ods  (functions)  then  exist  to  interface 
with  that  object.  These  methods  are 
used  just  like  data  in  a  structure,  with 
the  .  (period  [structure  field  selection]) 
operator  or  the  ->  (arrow  [structure  field 
selection  with  indirection])  operator. 
This  does  not  mean  that  there  are  sepa¬ 
rate  copies  of  a  method’s  code  for 
each  object.  The  Zortech  compiler  (and 
also,  I  assume,  C++  preprocessors) 
passes  to  the  method  a  hidden  pointer 
to  the  object.  This  pointer  is  used 
by  the  method  to  access  the  object’s 
data. 

When  I  talk  about  objects,  I  will  also 
refer  to  “constructors”  and  “destruc¬ 
tors.”  A  constructor  is  called  when  an 
object  is  declared;  it  is  used  to  initialize 
the  object,  A  destructor  is  called  when 
an  object  goes  out  of  scope;  it  is  most 
often  used  to  free  the  memory  allo¬ 
cated  by  the  constructor. 


All  of  the  data  in  each  of  this  kernel’s 
objects  is  private  to  prevent  someone 
from  accidently  destroying  the  work¬ 
ings  of  the  kernel.  A  few  public  rou¬ 
tines  (or  methods)  are  provided  for 
initialization  and  for  communicating 
with  the  task_control  object. 

A  signal  object  is  a  queue  of  task 
objects.  The  data  for  a  signal  object  is 
two  task-object  pointers,  which  are  used 
to  create  a  queue  (a  head  and  tail 
pointer).  This  is  the  simplest  object  in 
the  kernel.  It  has  only  two  methods: 
get_task_q,  which  gets  the  next  pointer 
to  a  task  object  from  the  queue,  and 
put_task_q,  which  appends  to  a  task 
object  pointer  to  the  queue.  These  meth¬ 
ods  are  private  and  can  only  be  called 
by  the  task_control  object  (which  is  a 
friend  of  a  signal  object).  A  constructor 
for  signal  objects  initializes  the  queue 
head  and  tail  pointers. 

A  task  object  contains  several  pieces 
of  data  that  are  used  by  the  task_control 
object.  Except  for  a  constructor  and  a 
destructor,  there  are  no  methods  for 
interfacing  with  a  task  object.  Signal 
objects  and  the  task_control  object  are 
“friends”  of  task  objects.  This  means 
that  they  may  directly  manipulate  the 
private  data  of  a  task  object.  I  did  this 
to  avoid  the  overhead  that  I  might  in¬ 
cur  by  using  methods  to  interface  with 
task  object  private  data.  C++  supports 
in-line  functions,  but,  unfortunately,  the 
Zortech  compiler  does  not  generate  in¬ 
line  code  in  all  cases. 

When  a  task  object  is  declared,  the 
constructor  is  called  and  the  private 
data  is  initialized.  A  workspace  or  stack 
is  allocated  for  the  task  object.  A  task 
“image”  is  set  up  in  the  allocated  mem¬ 
ory.  The  “image”  is  an  area  of  memory 
that  has  an  image  of  all  of  the  registers 
(8086)  of  the  task  when  it  was  last 
stopped.  In  this  case,  we  want  to  set 
up  a  register  image  to  be  used  the  first 
time  the  task  is  switched  to.  The  task 
object  carries  a  pointer  to  the  task  im¬ 
age  which  is  loaded  into  the  stack 
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(continued  from  page  45) 


pointer  when  you  want  to  activate  the 
task. 

See  the  structure  called  task_image 
in  Listing  One,  (task.hpp)  page  84,  to 
get  an  idea  of  how  this  task  image 
looks.  It  shows  how  the  stack  would 
look  after  an  interrupt  handler  had  been 
entered  and  all  of  the  registers  had 
been  saved,  which  is  how  the  kernel 
saves  the  image  of  a  running  task  be¬ 
fore  switching  to  another  task. 

When  the  task  image  is  set  up,  a 
routine  called  getCS  is  called  to  get  the 
code  segment  of  the  task.  This  is  neces¬ 
sary  because  of  a  compiler  bug  that 
returns  the  contents  of  the  DS  register 
when  you  try  to  get  the  segment  of  a 
wear  function  pointer.  Because  of  this, 
the  kernel  will  only  work  with  the  small 
model  of  the  compiler. 

The  task  object  also  carries  a  task- 
state  flag  and  a  pointer  to  a  task  object. 
This  next_task  pointer  is  used  by  the 
signal’s  methods  to  append  and  re¬ 
move  task  objects  from  a  signal  queue. 
The  destructor  for  a  task  object  frees 
the  memory  allocated  for  a  task  ob¬ 
ject’s  stack  or  workspace. 

The  task_control  object  takes  care 
of  switching  between  tasks  and  pro¬ 
vides  an  interface  to  the  outside  world. 
Its  methods  allow  a  task  to  wait  for  or 
send  a  signal,  turn  on  and  off  task 
switching,  and  so  on.  Before  multi¬ 
tasking  is  started,  task  objects  must  be 
added  to  the  task_control  object  with 
a  call  to  add_new_task.  The  taskjontrol 
object  has  a  signal  object  called  ready, _q 
to  which  all  tasks  that  are  ready  to  run 
are  added.  This  object  is  not  really  used 
to  signal  tasks,  but  it  is  used  because  a 
signal  object  is  a  queue.  After  all  of  the 
task  objects  have  been  added,  a  call  to 
start_tasks  saves  the  old  timer-tick  in¬ 
terrupt  handler,  installs  a  new  interrupt 
handler,  and  starts  up  the  first  task 
when  the  first  timer  interrupt  occurs. 
The  taskjcontrol  object  continues  to 
switch  between  tasks  until  stop_tasks 
is  called.  When  this  happens,  the  origi¬ 
nal  timer-tick  interrupt  handler  is  rein¬ 
stalled,  and  execution  is  resumed  at 
the  point  after  the  start_tasks  routine 
was  called. 

When  the  kernel  is  running,  tasks 
are  switched  18.2  times  a  second.  When 
a  timer-tick  interrupt  occurs,  the  task 
that  is  running  is  appended  to  ready j 
and  the  next  task  to  run  is  removed 
from  the  head  of  ready_q.  The  new 
task  runs  until  the  next  timer  interrupt 
and  the  process  is  repeated. 

Tasks  can  also  voluntarily  give  up 
control  and  call  the  kernel  to  run  the 
next  task  on  the  ready_q.  A  task  may 
block,  send  a  signal,  or  wait  for  a  sig- 
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nal.  Using  send  and  wait  allows  tasks 
to  communicate. 

A  task  can  use  taskjontrol:  :block( ), 
which  takes  no  parameters  and  is  called 
by  a  task  to  voluntarily  give  up  control. 
The  calling  task  is  appended  to  ready_q 
and  the  next  task  to  run  is  removed 
from  the  head  of  ready _q.  This  is  used 
by  a  task  to  allow  other  tasks  to  run 
when  it  is  done. 

A  task  calls  taskjcontrol: :wait(  )  with 
the  address  of  a  signal  object  to  wait 
for  a  signal  from  another  task.  The 
calling  task  is  appended  to  the  signal 
object’s  queue,  and  the  next  task  to  run 
is  removed  from  the  head  of  ready_q. 

Tasks  call  taskjontrol::send( )  with 
the  address  of  a  signal  object  to  send 
a  signal  to  a  waiting  task.  If  there  are 
any  task  objects  in  the  signal  object’s 
queue,  the  task  from  the  head  of  the 
queue  is  removed  and  appended  to 
ready _q.  The  calling  task  object  is  then 
appended  to  ready_q.  The  next  task 
to  run  is  removed  from  the  head  of 
ready jq. 

The  taskjontrol  object  has  two  meth¬ 
ods  to  enable  and  disable  task  switch¬ 
ing  by  the  timer-tick  interrupt.  This  al¬ 
lows  a  task  to  prevent  a  switching  if  it 
is  calling  a  routine  (MS-DOS,  BIOS,  or 
C  library)  that  is  not  reentrant.  Call 
taskjontrol: :lock( )  to  disable  task 
switching  and  taskjontrol: :unlock( ) 
to  reenable  task  switching.  These  rou¬ 
tines  do  not  affect  a  task  that  is  volun¬ 
tarily  giving  up  control  and  calling  the 
kernel  (block,  send,  or  wait). 

One  warning  about  the  taskjontrol 
object:  there  can  only  be  one.  If  you 
look  in  Listing  Two  on  page  84,  you 
will  find  a  global  variable  called  gljptr, 
which  is  a  pointer  to  a  taskjontrol 
object.  In  the  constructor  for  a  task_ 
control  object,  this  pointer  is  initialized 
to  the  address  of  the  taskjontrol  ob¬ 
ject  (the  “this”  pointer).  The  pointer 
gljptr  is  used  by  the  timer-tick  inter¬ 
rupt  handler  and  the  savejmage  rou¬ 
tine  in  Listing  Three  (timer.asm),  page 
88.  This  is  the  hidden  pointer  (passed 
to  a  C++  routine)  that  is  needed  for 
calling  taskjontrol: :taskjwitch( ).  This 
code  is  a  little  ugly,  but  it  allows  the 
task-switching  code  to  be  written  in 
C++,  and  it  allows  task_switch  to  ac¬ 
cess  the  private  data  of  task  and  signal 
objects  (by  being  a  friend). 

Details  of  Task  Switching 

Task  switching  would  not  be  possible 
if  you  could  not  save  a  task  image  of 
all  of  the  8086  registers.  This  is  accom¬ 
plished  by  the  timer_bandler  and  the 
savejmage  routines  in  Listing  Three. 
These  routines  both  do  the  same  thing: 


they  save  the  task  image  on  the  task’s 
stack  by  pushing  the  necessary  regis¬ 
ters  and  then  call  the  C++  taskjwitch 
routine.  Let’s  look  at  these  routines  more 
closely. 

The  new  timer-tick  interrupt  handler 
is  timer_handler.  It  saves  all  necessary 
registers  and  restores  the  DS  register 
so  the  C++  code  can  find  its  data.  The 
original  timer-tick  interrupt  handler  is 
called  to  take  care  of  the  hardware 
needs  for  the  timer  interrupt.  Next,  sev¬ 
eral  parameters  are  pushed  to  prepare 
for  a  call  to  the  C++  taskjwitch  rou¬ 
tine.  I  will  discuss  these  parameters 
later.  After  the  taskjwitch  routine  is 
called,  a  far  pointer  to  the  new  task 
object’s  image  is  returned.  The  sp  and 
ss  registers  are  loaded  with  this  pointer, 
and  the  new  task  object’s  registers  are 
popped  from  the  stack.  An  iret  instruc¬ 
tion  is  executed,  and  we  are  running 
our  new  task. 

The  savejmage  assembly  routine  is 
called  by  the  C++  block,  send,  and  wait 
methods.  This  routine  is  used  to  save 
the  image  of  a  task  just  as  timer_handler 
does.  This  routine  is  a  little  tricky  be¬ 
cause  it  is  passed  two  parameters  (a 
flag  and  a  signal  pointer)  on  the  stack. 
These  parameters  are  popped  off  the 
stack  to  pass  to  the  C++  taskjwitch 
routine,  then  pushed  back  on,  and  then 
the  stack  is  rearranged  so  the  flags  and 
a  far  return  address  are  on  the  stack  (as 
if  an  interrupt  occurred).  The  rest  of 
the  registers  are  pushed  as  in 
timer_handler.  The  rest  of  the  routine 
is  just  like  the  timer_handler  routines; 
the  C++  taskjwitch  method  is  called, 
and  on  return  the  SS  and  SP  registers 
are  set  up  to  run  the  next  task. 

The  taskjwitch  method  is  called  by 
the  timer  handler  and  save,  Jmage  rou¬ 
tines.  These  routines  pass  a  far  pointer 
to  the  image  of  the  currently  running 
task.  The  pointer  to  the  task  object  is 
put  on  ready_q  or  on  the  queue  of  a 
signal.  The  flag  passed  by  the  routines 
is  used  to  tell  taskjwitch  where  it  was 
called  from,  taskjwitch  needs  to  know 
if  a  timer  interrupt  or  a  send,  wait,  or 
block  call  occurred.  Once  taskjwitch 
decides  what  task  should  run,  the  far 
pointer  to  this  task’s  image  is  returned 
to  the  savejmage  or  timer_handler. 
The  task  runs  after  registers  are  re¬ 
stored  and  an  iret  is  executed. 

I  hope  that  this  has  shown  how  easy 
task  switching  really  is.  The  important 
part  of  task  switching  is  saving  all  of 
the  registers  of  the  running  task  and 
then  saving  a  far  pointer  to  that  area 
of  memory.  Each  task  has  its  own  stack 
(memory  that  has  been  allocated  with 
malloc).  The  far  pointer  points  into 
this  allocated  stack  to  the  area  where 
the  registers  were  pushed.  Restoring  a 
task  to  its  last  running  state  just  re- 
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quires  getting  the  far  pointer,  loading 
it  into  the  ss  and  sp  registers,  restoring 
the  registers,  and  doing  an  iret.  The 
new  task  will  then  be  running. 

A  Multitasking  Demo  Program 

To  compile  the  multitasking  program 
shown  in  Listing  Four,  page  90,  which 
demonstrates  the  concepts  discussed 
so  far,  type  ztc  taskdemo  task  timer. 
The  Zortech  ztc  program  looks  at  each 
of  the  source  files  and  runs  the  C++ 
compiler  or  assembler  as  necessary. 
The  linker  then  creates  the  executable 
file. 

The  taskdemo  program  has  five  tasks 
that  demonstrate  all  of  the  ways  that 
tasks  can  be  switched.  Not  much  hap¬ 
pens  in  the  program.  The  five  tasks 
run,  and  counters  are  incremented.  The 
taskO  task  takes  care  of  printing  the 
counters  for  the  other  four  tasks.  Let’s 
look  at  each  task. 

The  taskO  task  makes  a  lock( )  call 
to  make  sure  it  is  not  switched  until  it 
has  finished  writing  to  the  screen.  The 
counter  for  each  of  the  other  four  tasks 
is  printed.  Then  stop_tasks( )  is  called 
if  a  key  has  been  pressed.  If  no  key  has 
been  pressed,  the  unlock( )  routine  is 
called  to  reenable  task  switching.  The 
block( )  routine  is  then  called  to  allow 
other  tasks  to  run. 

The  task!  and  task2  tasks  increment 
their  counters  and  will  run  until  a  timer 
interrupt  occurs.  These  tasks  will  re¬ 
ceive  a  big  chunk  of  time  to  run,  so  the 
counters  increment  very  quickly. 

The  to&3task  increments  its  counter 
and  then  calls  waitj ),  which  allows 
the  next  task  to  run.  Next,  task4  incre¬ 
ments  its  counter  and  then  calls  send(  ), 
which  causes  task3  to  be  placed  on 
ready_q.  The  call  to  send( )  allows  the 
next  task  on  the  ready_q  queue  to  run. 
The  net  effect  of  this  is  that  the  count¬ 
ers  of  taskj  and  task4  increment  very 
slowly,  because  each  task  allows  an¬ 
other  task  to  run  after  incrementing  its 
counter. 

Multitasking  Kernel  Philosophy 

It  should  be  easy  to  change  or  add 
features  to  this  simple  kernel.  For  ex¬ 
ample,  in  the  Modula-2  implementa¬ 
tions  of  send( )  that  I  have  seen,  if 
there  is  no  task  on  the  signal  queue, 
then  a  flag  is  set  so  the  next  task  to 
wait  on  the  signal  queue  will  get  this 
message.  In  my  version  of  the  kernel, 
this  message  would  be  lost.  If  you  do 
not  think  a  message  should  be  lost, 
then  just  add  a  flag  to  the  signal  class. 

Modula-2-style  task  communication 
was  the  perfect  approach  for  the  “sim¬ 
ple  and  lean”  kernel  approach.  It  al¬ 
lows  the  task_control  object  to  get  by 
with  a  very  small  data  structure,  be¬ 
cause  signal  objects  carry  around  all 


of  the  data  they  need.  The  interface  to 
these  signal  objects  consists  of  a  cou¬ 
ple  of  simple  and  fast  methods  to  get 
and  put  pointers  on  a  queue.  The 
task_control  object  uses  the  same  sim¬ 
ple  methods  to  get  the  next  task  to  run 
off  of  ready_q.  If  you  would  like  to  see 
a  more  complete  explanation  of  Modu¬ 
lar-style  task  communication,  I  recom¬ 
mend  Chapter  16  of  the  book  Modu¬ 
la-2:  A  Software  Development  Approach. 

I  do  have  a  couple  of  suggestions 
on  how  to  improve  this  kernel.  Assign¬ 
ing  a  priority  to  a  task  can  be  a  handy 
feature.  This  would  simply  entail  add¬ 
ing  a  ready_q  to  the  task_control  ob¬ 
ject  for  each  priority  level,  or  perhaps 
using  an  array  of  ready _q  queues.  Do 
not  use  too  many  different  priority  lev¬ 
els;  five  would  probably  be  enough. 
The  task_switch  routine  would  then 
search  the  ready_ q queues,  highest  pri¬ 
ority  first,  to  find  the  next  task  to  run. 
When  a  task  was  appended  to  a 
ready_q,  you  could  simply  check  the 
task’s  priority  and  append  it  to  the  cor¬ 
rect  ready_q. 

Adding  a  way  for  a  task  to  sleep  for 
a  number  of  clock  ticks  might  be  useful 
as  well.  This  would  be  a  little  more 
complicated,  and  there  are  several  ap¬ 
proaches  you  could  take.  I  hope  you 
can  see,  however,  that  adding  these 
features  or  customizing  the  kernel  will 
be  very  simple. 
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ARTICLES 


A  Timed  Event 
Network  Scheduler 
in  Forth 


Forth  is  particularly  well  suited  to  the  development 
of  real-time  kernels 


Gregory  R.S.  Ilg  and  RJ.  Brown 


The  Timed  Event  Network  Sched¬ 
uler  (TENS)  is  a  scheduler  we 
have  developed  that  is  well  suited 
for  real-time  process  control  and  in¬ 
dustrial  automation  applications.  One 
of  its  main  features  is  that  it  has  its  own 
high-level  language,  which  is  an  exten¬ 
sion  of  Forth,  in  which  dependencies 
among  different  events  are  specified. 
When  any  action  or  time  duration  in 
the  system  is  altered,  other  modifica¬ 
tions  are  not  necessary  in  order  to  main¬ 
tain  and  preserve  these  dependencies. 
At  compilation  time,  the  critical  path 
through  the  network  and  its  path  length 
(measured  in  units  of  time)  are  dis¬ 
played.  Because  of  this  approach,  you 
can  easily  see  which  processes  need 
to  be  streamlined  in  order  to  increase 
system  throughput.  The  TENS  paradigm 
was  inspired  by  the  critical  path  method 
(CPM)  scheduling  techniques  used  to 
manage  large  projects. 

We  implemented  TENS  using  Labo¬ 
ratory  Microsystems’  UR/FORTH,  Ver¬ 
sion  1.03,  under  PC-DOS  3  3  running 
on  several  XT-  and  AT-compatible  com¬ 
puters.  So  far,  TENS  has  been  used  to 
control  the  time  sequencing  of  the  fluid 
and  pneumatic  valves  in  a  piece  of 
complex  medical  equipment.  Our  in¬ 
tent  was  for  a  mechanical  engineer  to 
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be  able  to  tune  the  system  timing  with¬ 
out  the  aid  of  a  software  engineer.  The 
results  were  quite  favorable.  The  me¬ 
chanical  engineer  quickly  grasped  the 
concepts  of  network  sequencing  and 
was  able  to  develop  some  of  the  net¬ 
work  topology  without  software  engi¬ 
neering  assistance  and  was  easily  able 
to  tune  the  timing  of  the  network  to 
meet  stringent  design  requirements. 

This  article  describes  the  TENS  sys¬ 
tem  and  provides  examples  of  its  use. 
The  programs  shown  in  Listings  One 
and  Two,  page  92,  do,  however,  make 
use  of  several  Forth  packages  that,  be¬ 
cause  of  their  length,  are  not  repro¬ 
duced  here.  The  packages  are  included 
in  the  companion  DDJ source  disk  and 
in  the  DDJ  Forum  on  CompuServe.  The 
TENS  system  can  be  used  for  any  pur¬ 
pose  as  long  as  credit  is  given  to  Elijah 
Laboratories. 

Description  of  TENS 

Each  node  in  a  TENS  network  has  as¬ 
sociated  with  it  an  action  to  be  per¬ 
formed  when  the  node  is  first  activated, 
a  delay  time,  and  an  action  to  be  per¬ 
formed  after  the  delay  time.  The  node 
is  then  exited.  Both  actions  behave  like 
normal  Forth  colon  definitions  and  may 
use  any  number  of  normal  Forth  words. 

Each  node  knows  its  immediate  suc¬ 
cessors  and  predecessors  in  the  net¬ 
work  and  cannot  be  activated  until  all 
its  predecessors  have  exited.  When  a 
node  exits,  it  informs  all  its  successors 
that  it  has  done  so.  Each  node  keeps 
track  of  which  of  its  predecessors  have 
already  exited  by  means  of  a  flag  for 
each  predecessor.  When  notified,  this 
node  examines  all  these  flags  to  deter¬ 


mine  if  it  is  now  eligible  to  run.  When 
the  conditions  for  node  activation  have 
been  met,  all  the  flags  are  cleared  be¬ 
fore  the  node  is  activated. 

Each  TENS  network  is  distinguished 
by  a  single  entry  and  a  single  exit, 
called  the  head  and  tail,  respectively. 
Between  the  network  head  and  tail 
there  may  be  zero  or  more  nodes,  sub¬ 
ject  to  the  constraint  that  there  are  no 
cycles.  (A  cycle  would  exist  in  the  situ¬ 
ation  that  an  ultimate  successor  of  a 
node  could  be  that  node’s  predeces¬ 
sor.)  A  network  is  known  by  its  head, 
and  typically  the  head  has  a  name  that 
appears  as  a  Forth  word  in  the  diction¬ 
ary.  To  run  such  a  network,  you  exe¬ 
cute  its  name  as  you  would  any  other 
Forth  word.  These  networks  can  in  turn 
be  used  to  construct  larger  networks. 

A  TENS  Example 

Let’s  suppose  TENS  were  used  in  the 
development  of  the  Egg-Master  vend¬ 
ing  machine  illustrated  in  Leo  Brodie’s 
book  entitled  Thinking  FORTH.  (Fig¬ 
ure  1  is  an  adaption  of  the  concept.) 
One  of  the  networks  it  might  use  could 
be  represented  as  shown  in  Figure  2 
and  Listing  One.  This  network  is  re¬ 
sponsible  for  handling  the  omelette  se¬ 
lection  available  on  the  Egg-Master.  Simi¬ 
lar  networks  would  handle  the  other 
selections.  The  word  EGG_MASTER  in 
Listing  One  handles  the  selection  of 
which  network  to  run  and  would  be 
hooked  to  the  power-up  vector  of  the 
machine.  The  network  in  Figure  2, 
whose  head  is  Start-Cook-Omelette,  runs 
the  nodes  Preheat-Griddle  and  Mix- 
Omelette  in  parallel.  The  node  Pour- 
Mixture  waits  for  both  the  nodes  Mix- 


52 

94 


Dr.  Dobb’s Journal,  February  1989 


REAL-TIME  KERNEL 

(continued  from  page  52) 


Omelette  and  Preheat-Griddle  to  com¬ 
plete  before  it  runs.  This  is  obviously 
necessary  because  the  ingredients  must 
be  mixed  and  the  griddle  must  be  hot 
before  the  mixture  is  poured  onto  the 
griddle. 

The  node  Mix-Omelettd  in  the  Cook- 
Omelette  network  is  itself  a  network 
that  is  a  subnetwork  of  Cook-Omelette , 
but  it  can  also  be  a  subnetwork  of 
other  networks  (such  as  a  Cook-Scram¬ 
bled  network,  should  the  Egg-Master 
Supreme  ever  make  it  out  of  the  R&D 
lab).  This  is  the  network  analogy  to  the 
linear-threaded  concept  of  factoring. 
Because  factoring  is  fundamental  to 
writing  good  Forth  code,  we  felt  it  was 
important  to  carry  this  practice  into  the 
parallel  data-flow  paradigm.  TENS  per¬ 
mits  factoring  of  networks,  thereby  in¬ 
creasing  their  reusability  and  test¬ 
ability. 

Run-Time  Data  Structures 

Each  network  is  implemented  by  a  net- 
work-head  data  structure  that  contains 
pointers  to  the  initial  and  terminal  nodes 
of  the  network.  The  network  head  also 
provides  storage  for  the  critical  path 
length. 

Each  node  is  implemented  as  a  com¬ 
pound  data  structure.  It  is  composed 
of  a  fixed  area  containing  the  CFAs  of 
the  entry  and  exit  action  words,  the 


Figure  1:  The  Egg-Master  vending 
machine 


delay  time,  its  path  length  from  the 
start  node,  a  pointer  to  a  linked  list  of 
successors,  and  a  variable-length  array 
of  pointers  to  its  predecessors.  This 
array  is  terminated  with  a  NULL  pointer. 
Each  node  in  the  linked  list  of  succes¬ 
sors  is  implemented  as  a  pair  of  cells. 
The  first  cell  points  to  the  next  node 
in  the  linked  list,  and  the  second  cell 
points  to  the  successor  node  in  the 
TENS  network  (see  Figure  3). 

Run-Time  Processing 

Each  TENS  network  is  created  by  a 
CREATE  DOES>  word  whose  DOES> 
clause  references  the  word  TENS  (see 
Listing  Two).  This  word  sets  a  trapdoor 
with  CATCH ;  entry-action  throws  back 
to  it  when  the  entire  network  has  fin¬ 
ished  executing.  After  this  trapdoor  is 
established,  the  timer  is  started  and  a 
pointer  to  the  first  node  is  passed  to 
entry-action,  which  throws  back  to  the 
trapdoor  if  the  pointer  is  NULL.  If  it  is 
not  NULL,  then  the  entry-action  CFA  is 
performed.  Next,  this  node  is  put  on 
the  timer  queue  for  the  required  delay 
time. 

The  timer  queue  is  managed  in  ac¬ 
cord  with  “An  Efficient  Algorithm  for 
Large  Priority  Queues,”  by  R.  J.  Brown 
(. DDJ ,  June  1987).  The  priority  is  the 
dispatch  time,  which  causes  each  node 
to  be  removed  from  the  queue  when 
its  dispatch  time  occurs.  As  the  flow  of 
control  proceeds  through  the  network, 
there  will  be  many  nodes  on  the  timer 


Figure  2:  A  network  for  omlette  selection 


queue. 

When  a  node  is  dispatched  from  the 
timer  queue,  its  pointer  is  passed  to 
exit-action,  which  causes  that  node’s 
Exit-Action  to  be  performed.  At  this 
point,  the  node  is  exiting,  and  its  suc¬ 
cessors  are  notified.  If  there  are  no 
successors,  then  the  entire  network  has 
finished  running  and  the  trapdoor  is 
thrown  back  to.  As  each  node  receives 
notification,  it  checks  to  see  if  all  its 
other  predecessors  have  also  exited.  If 
they  have,  then  that  node  is  activated. 
This  activation  and  exiting  process  is 
applied  iteratively  as  the  TENS  sched¬ 
uler  traverses  the  network.  When  subnet¬ 
works  are  present,  recursion  occurs  be¬ 
cause  more  than  one  network  is  active 
at  a  time. 

Although  TENS  implements  a  data¬ 
flow  paradigm  for  parallelism,  it  is  not 
a  multitasking  system.  All  of  the  paral¬ 
lelism  results  from  having  active  nodes 
on  the  timer  queue  waiting  for  the  de¬ 
lay  interval  between  their  Entry-Action 
and  their  Exit-Action.  For  this  reason, 
these  actions  should  have  negligible 
processing  time  relative  to  the  delay 
time. 

Compile-Time  Processing 

During  compilation  the  run-time  data 
structures  must  be  built  (see  Listing 
Two).  The  network  head  is  instantiated 
by  the  defining  word  NETWORK,  which 
leaves  a  pointer  to  this  head  on  the 
stack  for  use  by  END-NETWORK. 
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Each  node  in  the  network  can  know 
only  its  predecessors  at  compile  time 
because  Forth  dees  not  generally  allow 
forward  references.  After  all  nodes  of 
the  network  have  been  compiled,  the 
word  END-NETWORK  lexically  delim¬ 
its  the  entire  network  and  causes  addi¬ 
tional  compile-time  processing  to 
occur. 

The  first  (and  the  only  essential)  post¬ 
processing  operation  is  the  generation 
of  successor  links.  This  is  performed 
by  a  depth-first  traversal  of  the  net¬ 
work,  starting  at  the  tail  and  penetrat¬ 
ing  toward  the  head.  Each  pair  of  cells 
on  a  successor  list  is  allocated  as  it  is 
needed. 

Once  the  successor  links  have  been 
established,  the  length  from  the  head 
to  each  node  is  computed  by  a  similar 
depth-first  search  and  then  is  saved 
with  that  node.  Therefore,  the  critical 
path  length  will  be  found  in  the  tail 
node. 

The  names  of  the  nodes  on  the  criti¬ 
cal  path  are  displayed  starting  with  the 
tail.  By  choosing  the  predecessor  with 
the  largest  path  length,  we  are  able  to 
stay  on  the  critical  path.  As  each  node 
on  the  critical  path  is  encountered,  its 
name  (as  stored  in  the  dictionary 
header)  is  printed  on  the  screen. 

As  a  result  of  this  compile-time  post¬ 
processing,  not  only  is  the  network 
linked  in  both  directions  but  also  the 
length  of  the  critical  path  is  computed 
and  the  names  of  the  nodes  it  contains 
are  displayed.  The  length  of  the  critical 
path  is  a  useful  statistic  for  the  design¬ 
ers  because  only  those  nodes  that  are 
actually  on  the  critical  path  can  have 


Figure  3:  The  structure  of  a  node 


an  effect  on  the  critical  path  length. 
Thus,  designers  need  direct  their  tun¬ 
ing  efforts  only  to  these  nodes — by 
changing  the  delay  time  of  any  node, 
they  can  affect  the  time  required  to  run 
the  entire  network.  When  the  duration 
of  a  node  is  changed,  it  is  not  neces¬ 
sary  to  change  the  times  of  any  other 
nodes  to  keep  the  process  in  step.  This 
is  the  beauty  of  the  network-schedul¬ 
ing  data-flow  paradigm. 

The  display  of  the  critical  path  and 
its  length,  together  with  the  cell  in  each 
node  to  hold  that  node’s  path  length, 
can  be  removed  after  development  to 
produce  a  cross-compiled  system  with¬ 
out  the  extra  overhead  if  so  desired. 

Conclusion 

By  having  nontrivial  processing  done 
at  compile  time,  a  large  amount  of  work 
is  factored  into  the  compilation  of  the 
network  instead  of  into  its  execution. 
The  Forth  language  is  particularly  well 
suited  to  the  implementation  of  this 
approach  because  the  full  facilities  of 
the  language  are  available  not  only  to 
execute  the  program  but  also  to  build 
that  same  program.  Most  other  higher- 
level  languages  have  no  such  facility. 
The  C  language  has  a  limited  compile¬ 
time  processing  facility.  Most  good  as¬ 
semblers  have  a  macro  capability,  but 
these  are  separate  languages  distinct 
from  the  language  that  specifies  the 
run-time  behavior  of  the  program.  Lisp 
is  the  only  other  well-known  language 
that  has  as  good  a  compile-time  proc¬ 
essing  facility;  however,  Lisp  is  gener¬ 
ally  too  slow  to  be  effective  in  real-time 
applications  on  microprocessors.  Forth 
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is  deliberately  designed  to  provide  real¬ 
time  performance  on  micros. 
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ARTICLES 


Benchmarking  C  Statements 

Getting  the  most  out  of  your  C  programs 


David  L.  Fox 

Programmers  will  expend  consid-  question  of  which  statement  would  be  gramming  of  the  8253  chip.  Note  that 
erable  (sometimes  excessive)  ef-  faster  arises  often  enough  in  C  to  war-  this  solution  requires  a  high  degree  of 
fort  to  reduce  the  execution  times  rant  a  tool  to  help  answer  it.  hardware  compatibility, 

of  their  programs.  Widely  held  maxims  In  order  to  be  really  useful  a  C  state-  For  other  systems  with  low-resolu- 
such  as  “pointers  are  faster  than  array  ment  benchmarking  program  must  sat-  tion  clock( )  functions,  the  statement 
indexing”  or  “multiply  is  faster  than  isfy  a  number  of  requirements.  First,  it  under  test  can  be  enclosed  in  a  loop 
divide”  don’t  always  apply  to  a  par-  should  be  easy  to  use;  that  is,  the  pro-  and  repeated  many  times.  This  increases 
ticular  situation;  any  program  might  bene-  gram  should  require  a  minimum  from  the  total  time  required  to  a  value  that 
fit  from  a  little  tool-aided  exploration  the  programmer.  In  sbench,  often  the  can  be  measured  with  a  low-resolution 
and  the  optimization  of  any  code  con-  only  information  required  is  a  list  of  the  timer.  Putting  the  statement  under  test 
suming  a  disproportionate  share  of  CPU  statements  to  be  compared.  Sbench  gen-  inside  a  loop  is  not  an  ideal  solution 
cycles.  Most  programmers  go  first  to  a  erates  a  test  program  from  such  a  list  because  it  can  lead  to  multiple  side 
profiler,  which  measures  the  fractions  and  compiles,  links,  and  executes  it.  effects  and  increase  the  confusion  an 
of  the  total  execution  time  consumed  C  programs,  however,  contain  more  optimizing  compiler  can  create.  Sbench 
by  various  parts  of  a  program.  Once  than  simple  executable  statements.  In  provides  for  both  the  higher-resolution 
the  profiler  has  identified  the  time  criti-  order  to  compare  various  ways  of  read-  version  of  clock( )  and  the  repeating 
cal  portions  of  code,  the  programmer  ing  data  from  a  file,  for  example,  buff-  loop  solutions  to  the  timing  problem, 
can  fine  tune  those  parts  with  sbench.  ers  and  file  descriptors  must  be  de-  The  final  requirement  of  a  C  bench- 

Sbench  is  a  program  generator.  It  dared  and  the  file  must  be  opened  marking  tool  is  that  its  generated  test 
reads  a  list  of  C  statements  and  creates  before  any  input  statements  can  be  exe-  programs  should  run  on  a  wide  variety 
a  test  program  to  measure  the  execu-  cuted.  Some  mechanism  must  be  pro-  of  systems  and  compilers.  The  emerg- 
tion  time  of  each  statement  individu-  vided  to  allow  for  declaring  variables  ing  ANSI  C  standard  will  make  port- 
ally.  This  allows  a  quick  and  easy  com-  (both  global  and  local),  including  other  ability  much  easier  to  achieve  in  the 
parison  of  the  performances  of  various  files,  and  executing  the  initialization  future,  but  unfortunately,  compiler  sup- 
altemative  methods  of  accomplishing  code  required  for  the  statements  to  be  port  of  the  draft  standard  is  uneven, 
a  given  task.  Sbench  also  makes  it  much  tested.  Sbench’s  solution  is  to  try  to  generate 

easier  to  explore  the  performance  of  a  The  most  important  requirement  a  programs  that  avoid  system  specific  fea- 
compiler  in  a  variety  of  situations.  C  statement  benchmarking  program  tures  and  provide  for  various  imple- 

Sbench  is  of  primary  interest  to  pro-  must  satisfy,  of  course,  is  that  it  pro-  mentations  of  C  by  use  of  #if  condi- 
grammers  of  real-time  systems  and  oth-  vided  some  way  to  measure  the  execu-  tional  compilation  directives.  ANSI  C 
ers  concerned  with  optimizing  small  tion  time  of  the  statements  under  test,  is  used  in  the  version  of  sbench  pre¬ 
regions  of  code.  Limitations  on  the  per-  The  draft  ANSI  C  standard  contains  the  sented  here,  but  “old  style”  C  (K&R) 
formance  of  a  program  imposed  by  the  library  function  clock( ),  which  seems  alternatives  are  provided  too.  I  have 
execution  of  a  few  lines  of  bottleneck  ideal  for  this  purpose.  clock( )  returns  compiled  the  generated  test  programs 
code  are  not  unusual.  Furthermore,  it  an  implementation’s  best  approxima-  with  four  different  MS-DOS  C  compil- 
is  not  always  obvious  where  and  when  tion  of  the  processor  time  used  by  a  ers.  I  do  not  have  access  to  other  hard- 
such  bottlenecks  occur.  program.  Unfortunately,  clock( )  is  not  ware,  so  portability  to  non-MS-DOS  sys- 

universally  available,  even  on  compil-  terns  is  untested. 

Sbench  ers  that  claim  to  support  ANSI  C.  In  The  code  for  sbench  itself  does  not 

I  was  inspired  to  write  sbench  by  Ralph  most  MS-DOS  implementations,  the  reso-  maintain  the  level  of  compiler  inde- 
E.  Griswold’s  “Benchmarking  Icon  Ex-  lution  of  the  clock  function  is  18.2  ticks  pendence  the  programs  it  generates 
pressions,”  (19  October  1987,  The  Icon  per  second,  inadequate  for  timing  indi-  do.  The  sbench  code  uses  several  fea- 
Project,  University  of  Arizona),  which  vidual  statements  that  may  take  only  a  tures  introduced  in  the  ANSI  draft  stan- 
describes  a  similar  tool  for  the  Icon  few  microseconds  to  execute.  dard  and  not  supported  by  most  K&R 

programming  language.  Icon  presents  sbench  solves  both  problems  by  pro-  C  compilers.  In  particular,  function  pro- 
a  programmer  with  even  more  opera-  viding  a  customized  version  of  clock( )  totypes  and  concatenation  of  adjacent 
tors  and  alternatives  than  C,  but  the  with  much  higher  timing  resolution,  string  constants  are  used  throughout 

Sbench’s  timing  function  can  be  imple-  the  code.  I  have  not  added  the  condi- 
David  has  been  developing  program -  mented  on  the  IBM  PC  and  compa-  tional  compilation  switches  needed  to 
mer’s  tools  for  several  years.  He  is  the  tibles  by  reprogramming  the  8253  timer  allow  compilation  with  either  K  &  R  or 
chief  scientist  at  Minimum  Instruction  chip.  Byron  Sheppard’s  “High-Perform-  ANSI  style  of  compiler  because  the 
Set  Computer  Inc.  and  can  be  reached  ance  Software  Analysis  on  the  IBM  PC”  switches  would  have  increased  the  size 
at PO.  Box  1528,  Golden,  CO  80402.  ( Byte ,  January  1987)  details  this  pro-  and  decreased  the  readability  of  the 
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code. 

Benchmark  programs  rarely  do  any¬ 
thing  more  than  print  times,  and  conse¬ 
quently,  they  can  be  invalidated  by 
sufficiently  smart  optimizing  compil¬ 
ers.  Sbench  is  susceptible  to  this  prob¬ 
lem.  One  solution  is  not  to  use  the 
optimizer  for  the  test  code.  This  has  the 
severe  drawback,  however,  that  the 
times  will  not  correspond  to  the  times 
in  the  real,  optimized  code.  The  best 
solution  is  to  include  enough  realistic 
code  in  your  test  that  the  optimizer  will 
make  the  same  improvements  it  would 
in  the  actual  application. 

There  are  also  some  tricks  you  can 
use  to  prevent  the  optimizer  from  com¬ 
pletely  removing  your  test  code.  Few 
microcomputer  C  compilers  optimize 
across  function  calls,  so  passing  the 
results  of  any  calculations  to  an  exter¬ 
nal  function  will  usually  convince  an 
optimizer  that  the  results  are  being  used. 
Also  helpful  in  preventing  the  optimizer 
from  removing  the  loops  is  to  use  the 
loop  index  variable  in  any  calculation. 
Finally,  note  that  some  optimizers  make 
fewer  changes  in  code  using  global 
variables  than  in  code  with  local  vari¬ 
ables. 

Sbench  Code 

The  code  for  sbench,  the  statement 
benchmark  generator,  is  in  Listing  One, 

page  98.  The  operation  of  the  program 
is  quite  simple  — sbench  collects  state¬ 
ments  from  the  input  into  three  linked 
lists,  one  for  global  declarations,  one 
for  local  declarations,  and  one  for  the 
statements  to  be  timed.  Global  lines  are 
copied  into  the  beginning  of  the  gener¬ 
ated  test  program,  external  to  any  func¬ 
tion.  Local  lines  are  copied  into  the 
main  function  of  the  test  program  be¬ 
fore  any  executable  statements.  Finally, 
the  statements  to  be  timed  are  copied 
into  the  test  program.  The  three  ele¬ 
ments  are  combined  with  fragments  of 
code  to  make  a  complete  program.  The 
additional  code  fragments  required  to 
complete  the  program  are  given  by  the 
pgm*  string  variables  defined  in  lines 
70  to  95. 

Global  lines  must  occur  first  in  the 
input  and  are  separated  from  local  lines 
by  a  line  beginning  with  96%.  Local 
lines  must  precede  any  test  statements 
and  are  indicated  by  a  single  initial  % 
character.  Any  statement  may  be  split 
over  several  physical  lines  by  the  usual 

C  convention  of  ending  lines  to  be 
continued  with  a  \  character. 

Once  the  test  program  is  created, 
sbench  attempts  to  compile  and  exe¬ 
cute  it  with  the  system  commands  in 
lines  215  to  225.  The  programmer  can 
use  a  command-line  option  (-g)  to  pre¬ 
vent  compilation  of  the  test  program. 

Unless  the  programmer  gives  it  another 
name  with  the  -/  option,  the  test  pro¬ 
gram  is  called  statbm.c.  Sbench  will 
not  delete  the  test  program  so  it  may 
be  (re)compiled  if  the  programmer 
wants  to  compare  various  compilers 
and/or  options. 

Listing  Two  on  page  101,  contains 
the  code  for  the  routine  getline(  X  which 
reads  a  line  of  arbitrary  length  and  com¬ 
bines  continued  physical  lines  into  one 
logical  line.  Listing  Three,  page  101, 
contains  the  command-line  option  pars¬ 
ing  routine  getopt( ).  getopt( )  is  a  Unix 
function,  available  in  only  some  micro¬ 
computer  C  implementations.  Because 
getopt( )  is  not  specified  in  the  ANSI 
draft  standard,  I  have  included  it  here. 

clock( X  the  microsecond  resolution 
clock  function,  is  given  in  Listing  Four, 
page  102.  clock( /is  very  hardware  and 
compiler  dependent.  The  code  in  List¬ 
ing  Four  should  be  portable  to  IBM 
PC  compatible  systems  with  C  compil¬ 
ers  that  have  the  ability  to  control  inter¬ 
rupts  and  access  hardware  ports.  List¬ 
ing  Four  can  be  used  as  a  guide  for 
implementation  on  other  systems.  Its 
function  has  been  described  in  detail 
in  Byron  Sheppard’s  Byte  article. 

Results 

Listing  Five(a),  page  103,  is  an  example 
of  an  input  file  for  sbench.  No  global 

C  BENCHMARKING 

The  remainder  of  the  test  input  com¬ 
pares  using  subscripts  and  pointers  for 
initializing  and  copying  an  array.  Each 
statement  tested  is  a  for  loop  split  into 
two  or  more  lines  to  illustrate  the  use 
of  the  continuation  character  (  \).  Us¬ 
ing  pointers  for  the  unoptimized  code 
is  slightly  faster  for  initializing  and  copy¬ 
ing.  The  optimizer  removes  the  ad¬ 
vantage  in  the  initialization  loop  but 
increases  the  advantage  in  the  copy 
loop.  The  conclusion  to  be  drawn  from 
this  is  that  micro  performance  will  vary 
substantially  depending  on  the  exact 
details  of  the  code.  When  tuning  code 
for  maximum  performance,  you  have 
to  test  the  specific  code  for  your  appli¬ 
cation.  Sbench  makes  it  easy  to  try  a 
large  number  of  variations. 

Further 

Like  all  tools,  sbench  doesn’t  do  every¬ 
thing,  and  there  are  a  few  ways  in 
which  it  could  be  improved  or  extended. 
One  simple  improvement  would  be  to 
provide  a  mechanism  for  passing  op¬ 
tions  from  sbench’s  command  line 
through  to  the  compiler  and/or  to  the 
test  program  itself  when  compiling  the 
test  program.  Another  would  be  to  ex¬ 
tend  the  program  to  generate  test  pro¬ 
grams  in  other  languages  by  providing 
alternate  definitions  of  the  code  frag¬ 
ments  in  the  pgm'strings  — a  fairly  easy 
improvement  to  make.  Finally,  note  that 

the  idea  of  using  programs  to  generate 
or  manipulate  other  programs  is  ex¬ 
tremely  powerful.  Code  similar  to 
sbench’s  could  be  used  to  insert  com¬ 
mands  in  a  test  program  for  profiling 
by  routine,  block,  or  line. 

A  Caution 

While  the  fine  tuning  encouraged  by 
this  tool  has  its  place,  don’t  get  carried 
away  by  the  notion  of  speed.  Faster  is 
not  always  better;  readability,  main¬ 
tainability,  and  portability  are  at  least 
as  important  as  speed  for  most  pro¬ 
grams.  As  always,  the  programmer  must 
weigh  the  importance  of  conflicting  re¬ 
quirements. 
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is  available  on  a  single  disk.  To  order, 
send  $14.95  (Calif,  residents  add  sales 
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variables  are  used,  so  the  global  sec¬ 
tion  is  empty  except  for  a  comment. 
Note  that  in  addition  to  variable  decla¬ 
rations,  the  global  section  could  con¬ 
tain  #include  commands,  definitions 
of  functions  called  by  the  test  code,  or 
any  other  valid  C  code.  Several  local 
variables  are  declared  in  lines  3  to  6. 
Executable  code  to  perform  required 
initialization  could  also  be  placed  in 
the  local  section. 

The  first  two  test  statements  (Listing 
Five’s  lines  7  and  8)  add  two  float  and 
double  variables,  respectively.  The  re¬ 
sults  in  Listing  Five(b)  were  obtained 
using  floating  point  software  with  the 
Zortech  C  compiler.  They  show  clearly 
why  float  variables  should  not  be  used 
when  speed  is  important.  When  the 
optimizer  is  used  in  compiling  the  test 
code,  the  results  in  Listing  Five(c)  are 
obtained.  The  execution  time  appears 
to  have  been  reduced  to  almost  zero  — 
the  optimizer  has  recognized  that  the 
results  of  the  additions  are  not  used 
anywhere  and  has  completely  removed 
all  the  code  generated  by  the  addi¬ 
tions.  Inspection  of  the  object  code 
confirms  this.  The  apparent  results  of 

1  to  2  microseconds  in  Five(b)  are  due 
to  just  round  off  error  and  uncertainty 
in  the  timing  function. 
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ARTICLES 


Debugging  TSR  Programs 

Turbo  Debugger  can  take  the  pain  out  of  buggy 
TSRs  —  if  you  know  the  trick 


One  of  the  most  unnerving  as¬ 
pects  of  writing  terminate-and- 
stay-resident  (TSR)  programs  is 
debugging  them.  Compounding  this 
troublesome  fact  is  that  many  commer¬ 
cial  debuggers,  including  Debug,  don’t 
have  the  ability  to  debug  TSR  programs. 
One  solution,  of  course,  is  to  buy  a 
sophisticated  (and  expensive)  debug¬ 
ger,  but  this  isn’t  always  the  most  at¬ 
tractive  or  economical  solution  unless 
you  are  developing  TSR  programs  on 
a  full-time  basis. 

Because  I  found  Borland’s  Turbo  De¬ 
bugger  to  be  a  good,  low-cost  debug¬ 
ger,  I  decided  to  investigate  ways  of 
making  it  handle  TSR  programs  in  an 
easy  and  respectable  manner.  The  tech¬ 
niques  I  developed,  and  that  I  describe 
here,  have  been  used  to  debug  com¬ 
mercially  available  TSR  programs  (Soft¬ 
ware  Bottling’s  Flash-Up  and  Speed 
Screen,  for  instance). 

Furthermore,  there’s  no  reason  why 
the  same  techniques  can’t  be  applied 
to  debuggers  other  than  Turbo  Debug¬ 
ger.  In  this  article,  I’ll  briefly  describe 
how  TSR  programs  work,  then  talk 
about  how  you  can  debug  them  when 
things  go  wrong.  As  an  example,  I’ll 
use  a  typical  (but  bare  boned)  TSR 
program  called  KEYSWAP  (assembled 
in  Turbo  Assembler)  and  look  into  why 
you  can’t  normally  debug  it  with  Turbo 
Debugger.  This  sample  TSR  program 
makes  the  keys  F8  and  F10  act  as  if  you 
had  pressed  the  up  arrow  and  down 
arrow,  respectively.  In  many  ways, 
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KEYSWAP  is  the  foundation  of  a  key¬ 
board  macro  program. 

The  TSR  Problem 

A  TSR  program  really  has  two  parts: 
The  first  part  actually  performs  the  func¬ 
tions  you  designed  it  to  perform,  and 
the  second  part  consists  of  the  code 
that  loads  the  program,  chains  to  any 
interrupt  vectors,  and  terminates  with 
a  special  DOS  int  21h  call  to  stay  resi¬ 
dent.  Example  1  illustrates  the  flow  of 
a  typical  TSR  program. 

If  you  run  a  TSR  program  such  as 
KEYSWAP  with  a  debugger  in  the  nor¬ 
mal  manner — that  is,  you  do  a  file/ 
load  and  then  run  it  — you  will  simply 
get  a  message  saying  that  the  program 
and  terminated  and  some  error  code. 
When  you  quit  the  debugger,  your  pro¬ 
gram  will  not  be  resident  because  both 
the  debugger  and  your  program  will 
terminate.  If  you’ve  chained  to  any  in¬ 
terrupts,  your  system  will  probably  crash 
because  the  chained  interrupt  vectors 
will  still  be  there  but  your  program  and 
the  debugger  will  be  gone.  This  means 
any  chained  interrupt  vectors  will  be 
pointing  into  what  could  be  random 


instructions  and  data. 

The  concept  behind  the  solution  to 
this  sort  of  problem  is  actually  quite 
simple.  Instead  of  terminating  KEY- 
SWAP  using  the  normal  terminate-but- 
stay-resident  DOS  interrupt  function,  I 
take  advantage  of  the  DOS  load-and- 
execute  function  to  load  and  execute 
COMMAND.COM.  The  effect  of  this  is 
twofold:  first  KEYSWAP  seems  to  be 
memory-resident,  and  second,  Turbo 
Debugger  is  there  at  the  touch  of  a  hot 
key  if  you  need  to  debug  the  program. 

Using  and  Debugging  a  Typical 
TSR  Program 

To  use  the  sample  TSR  program  as  an 
executable  program,  assemble  KEY- 
SWAP.ASM  (Listing  One,  page  104)  into 
KEYSWAP. OBJ  by  typing  TASM  KEY- 
SWAP  (assuming  you’re  using  Turbo 
Assembler).  Do  not  include  the  file 
TSRDEBUG.ASM  in  Listing  Two,  page 
105.  Next  create  the  executable  file  KEY- 
SWAP.  COM  from  KEYSWAP.  OBJ  by  typ¬ 
ing  TLINK  KEYSWAP  /T.  You  can  then 
load  the  TSR  program  into  memory  by 
typing  KEYSWAP  at  the  DOS  prompt. 
(As  this  article  is  about  debugging  TSR 


;  This  portion  remains  resident 
tsr  data 

tsr  interrupt  handlers 
tsr  other  programs 

;  This  portion  is  freed  when  the  DOS  Terminate 
;  and  stay  resident  function  is  executed. 

data  area 
load  entry  point: 
create  stack 

call  other  check  routines 

(e.g.,  DOS  version,  parameters,  available  memory,  etc.) 
chain  tsr  interrupt  handlers 
determine  size  of  tsr  to  keep 
call  DOS  TSR  function 
end 


Example  1:  Typical  structure  of  a  TSR  program 


Dr.  Dobb’s  Journal,  February  1989 


67 

99 


DEBUGGING  TSRs 

(continued  from  page  67) 


programs  and  not  about  how  to  write 
them,  I  have  not  provided  KEYSWAP 
with  the  ability  to  check  if  it  has  been 
already  loaded  in  memory  or  the  ability 
to  be  unloaded  from  memory,  except 
by  rebooting.) 

To  debug  the  program,  you  assem¬ 
ble  and  link  KEYSWAP.ASM  as  before, 
except  now  you  include  the  file  TSRDE- 
BUG.ASM  (Listing  Two).  To  assemble 
KEYSWAP.ASM  and  include  the  spe¬ 
cial  debugging  code  in  file  TSRDE- 
BUG.ASM,  type  TASM  KEYSWAP /DDE- 
BUG.  A  file  called  KEYSWAP.OBJ  is 
then  created.  Next,  link  KEYSWAP.OBJ 
to  create  KEYSWAP  .COM  and  KEY- 
S WAP. MAP  by  typing  TUNK  KEYSWAP 
A M  /T.  Finally,  type  TMAP  KEYSWAP 
to  create  the  file  KEYSWAP. TDS,  which 
contains  symbolic  information  for  Turbo 
Debugger,  from  KEYSWAP.  MAP. 

You  should  now  have  files  called 
KEYSWAP.COM  and  KEYSWAP.TDS 
ready  to  use  for  debugging.  All  other 
files  are  not  required  by  the  debugger. 

To  run,  start  Turbo  Debugger  and 
load  KEYSWAP.COM  using  the  file/ 
load  menu  selection,  then  press  F9  to 
execute.  KEYSWAP  will  chain  intl6 
handler  on  interrupt  I6h.  It  will  then 
call  the  procedure  tsr_simulate,  which 
frees  all  memory  starting  from  the  label 
load_tsr.  It  then  proceeds  to  chain 
int9handler.  After  saving  the  stack  reg¬ 
isters  into  a  memory  location,  KEYSWAP 


loads  and  executes  COMMAND.COM, 
which  must  be  in  the  root  directory  of 
drive  C: .  At  this  point  you  will  get  the 
DOS  prompt.  Your  program  and  Turbo 
Debugger  are  now  both  memory-resi¬ 
dent,  and  you  can  debug  and  set  break¬ 
points  by  activating  the  debugger. 

To  activate  the  debugger,  press  Ctrl- 
Enter.  The  program  will  be  interrupted 


The  debugging  concept 
presented  in  this  article 
will  work  in  a  similar 
manner  for  .EXE 
programs  that  run  TSRs 


because  int9handler  checks  whether 
Ctrl-Enter  was  pressed,  and  if  it  was, 
the  handler  executes  the  breakpoint 
int  3,  which  is  the  breakpoint  interrupt 
to  activate  any  debugger.  (If  you  have 
a  hardware  switch,  known  as  an  NMI 
switch,  you  may  use  it  instead  of  Ctrl- 
Enter.) 

The  CPU  window  will  show  the  point 
at  which  execution  was  interrupted. 
Because  the  int  3  instruction  is  in 


KEYSWAP,  you  can  press  PgUp  or  PgDn 
and  view  both  code  and  symbols.  You 
can  also  go  to  a  procedure  by  pressing 
Alt-G  (Goto)  and  entering  a  label  that 
is  public  in  your  program. 

You  can  now  set  breakpoints  in  the 
KEYSWAP  code  at  the  points  where 
you  want  to  break  and  start  tracing.  As 
an  example,  set  a  breakpoint  at  the 
label  flOpressed ,  which  is  in  int  16- 
handler  and  was  declared  public.  The 
instruction  at  this  label  is  executed  when 
you  press  the  F10  key  while  in  your 
application.  Press  Alt-F2  and  enter  the 
label  name.  This  sets  a  breakpoint.  Press 
F9  (Run)  to  exit  from  the  debugger  and 
return  to  the  DOS  prompt. 

(Make  sure  that  you  do  not  alter  any 
registers  or  flags  or  start  executing  at 
another  instruction.  Do  not  try  to  do 
any  disk  access  either,  such  as  loading 
a  different  program.  You  may  have  inter¬ 
rupted  DOS  in  the  middle,  and  be¬ 
cause  DOS  is  not  reentrant,  another 
DOS  call  is  all  DOS  needs  to  crash  your 
system.) 

To  run  your  application  and  use 
KEYSWAP,  press  the  F10  key  when 
you  want  to  move  the  cursor  down, 
and  your  debugger  will  activate  be¬ 
cause  the  breakpoint  has  been  reached. 
Trace  to  check  what  your  program  is 
doing,  and  debug  as  you  would  with 
any  other  program.  Pressing  F9  (Run) 
will  return  you  to  your  application. 

To  exit  from  the  debugger  and  termi¬ 
nate  KEYSWAP,  type  the  Exit  command 
at  the  DOS  prompt.  This  command  re¬ 
turns  you  to  KEYSWAP  at  the  instruc¬ 
tion  immediately  following  the  load-and- 
execute  function  in  the  tsr_simulate 
procedure.  The  procedure  will  then  un¬ 
chain  the  interrupt  handlers  and  termi¬ 
nate  using  the  normal  DOS  terminate 
function.  (For  a  list  of  the  DOS  func¬ 
tions  used  in  this  program,  see  Exam¬ 
ple  2.)  You  can  now  quit  the  debugger 
or  restart  KEYSWAP. 

Flow  of  KEYSWAP  Without  the 
DEBUG  Code 

When  KEYSWAP  starts  up,  it  first  sets 
up  its  own  stack.  Always  use  your  own 
stack  as  if  it  were  your  own  parachute. 
The  next  step  is  to  chain  the  int  16- 
handler  keyboard  handler  so  that  you 
can  check  for  the  F8  and  F10  keys.  The 
last  step  is  to  determine  the  size  of  the 
program  you  wish  to  keep  in  memory. 
You  normally  do  not  want  to  keep  the 
loading  portion  of  KEYSWAP,  so  you 
figure  out  the  size  by  taking  the  offset 
of  the  loader’s  starting  address,  which 
is  the  label  load_tsr.  You  now  call  DOS 
to  terminate  but  stay  resident. 

On  entry,  intl6handler  checks  to 
see  if  the  keyboard  function  called  for 
is  a  “getkey".  If  not,  it  jumps  directly 
to  the  old  interrupt  vector.  If  the  func- 


Note:  The  following  is  a  list  of  the  DOS  INT  21h  functions  used 
in  KEYSWAP.  Remember  that  if  any  DOS  function  returns  with  the 
CARRY  flag  set,  the  function  had  a  problem.  Usually  reason  for  the 
error  is  returned  in  the  AX  register.  For  more  information,  see 
the  DOS  Technical  Reference  manual  or  one  of  the  dozens  of  books 
on  the  subject. 

Set  the  vector  of  interrupt: 

Input:  AH  =  25h,  AL  =  interrupt  # 

DS:DX  =  segment  S  offset  value  of  new  interrupt  handler 

Terminate  but  stay  resident: 

Input:  AH  =  31h,  AL  =  errorlevel 

DX  =  #  of  paragraphs  to  keep 

Get  the  vector  of  interrupt: 

Input: 

AH  =  35h,  AL  =  interrupt  # 

Output : 

ES:BX  =  segment  S  offset  value  of  the  current  interrupt  handler 
Shrink  allocated  memory: 

Input:  AH  =  4Ah,  ES  =  Segment  to  shrink 

BX  =  paragraphs  to  keep 

Load  S  Execute: 

Input:  AH  =  4Bh,  AL  =  0  (If  AL  =  3  then  it  only  loads) 

ES:BX  =  segment  and  offset  of  params  block 

(for  param  block  format  see  the  program) 

DS:DX  =  segment  &  offset  of  command  (ASCIIZ  string) 
Output:  None,  but  all  registers  including  SS  and  SP  are 
destroyed. 

Terminate  program: 

Input:  AH  =  4Ch,  AL  =  error  level 


Example  2:  DOS  functions  used  in  KEYSWAP 
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tion  is  a  get  key,  intl6handler  calls  the 
old  interrupt  to  get  the  key.  Upon  re¬ 
turn,  it  inspects  the  ax  register  for  an 
F8  or  F10  key.  If  either  of  those  keys 
was  pressed,  it  substitutes  the  corre¬ 
sponding  up  or  down  arrow  keys  into 
ax  and  returns  to  the  original  caller. 

KEYSWAPwith  the 
Debug  Code 

To  debug  KEYSWAP  you  must  com¬ 
pile  it  with  the  /ddebug  option,  as  noted 
earlier.  You  will  notice  that  I  use  the 
conditional-assembly  directives  if .  .  .  def 
.  .  .  else  .  .  .  endifxa  include  the  debug¬ 
ging  code.  This  code  is  in  the  file  TSRDE- 
BUG.ASM.  The  debugging  code  adds 
the  following  procedures:  int9handler, 
tsr_simulate,  and  unchain_vector. 

The  procedure  int9handler  checks 
to  see  if  the  Ctrl-Enter  key  was  pressed 
and  then  executes  an  int  3  to  activate 
Turbo  Debugger.  The  procedure  tsr_ 
simulate  frees  memory,  starting  at  the 
label  load_tsr.  It  then  executes  COM¬ 
MAND.  COM,  at  which  point  the  DOS 
prompt  appears.  When  you  terminate 
your  debugging  and  wish  to  go  back, 
type  Exit  at  the  DOS  prompt,  which 
returns  you  to  the  debugger  to  recover 
the  stack  registers  and  unchains  the 
vectors  int9handler  and  intl6handler. 
It  will  then  execute  the  normal  DOS 
terminate  function.  The  procedure 
unchain_vectoruncha.\ns  the  int  Chand¬ 
ler  vector  when  you  have  finished  and 
puts  back  the  original  one.  If  you  do 
not  do  this,  and  exit  from  the  debugger, 
you  will  eventually  crash  the  computer. 
The  debug  code  also  adds  working 
storage  for  these  three  procedures. 

Caveats,  Conditions,  and  Other 
Warnings 

While  debugging  your  memory-resident 
program  with  Turbo  Debugger,  the  pro¬ 
gram  memory  size  is  the  size  of  Turbo 
Debugger  plus  your  program  size.  Do 
a  CHKDSK  after  your  program  runs  to 
see  how  much  memory  is  left. 

If  you  interrupted  your  program  by 
pressing  Ctrl-Enter  or  with  a  breakpoint, 
you  should  not  try  to  use  any  of  Turbo 
Debugger’s  menu  functions  that  access 
the  disk.  These  include  such  choices 
as  file/load  and  options/save.  If  you 
do  attempt  to  use  filing  choices,  you 
may  crash  DOS.  The  reason  is  that  DOS 
is  not  reentrant,  and  so  it  cannot  be 
called  again  when  busy.  This  includes 
calls  to  DOS  from  the  debugger.  Micro¬ 
soft  provides  an  undocumented  func¬ 
tion  to  detect  if  DOS  is  busy  but  I  will 
not  discuss  it  here. 

If  Ctrl-Enter  does  not  respond,  the 
chances  are  that  your  program  crashed 


in  some  loop  and  interrupts  have  been 
turned  off,  which  means  that  the  key¬ 
board  interrupts  are  ignored  by  the  CPU. 
If  you  have  an  NMI  switch,  try  using  it 
to  see  if  your  program  is  stuck  in  a 
loop.  Beware,  though,  because  the  only 
way  out  may  be  by  rebooting. 

Never  leave  int  3  (breakpoint)  in¬ 
structions  in  your  finished  program. 
Although  they  are  supposed  to  be  harm¬ 
less  if  no  debugger  is  loaded,  I  have 
known  some  machines  that  will  not 
run  programs  containing  int  3s.  (I  had 
to  write  a  TSR  program  to  trap  the  int 
3s!) 

The  reason  why  I  use  Ctrl-Enter  and 
int9handler  to  activate  the  debugger 
is  because  Turbo  Debugger’s  hot  key 
(Ctrl-Break)  will  not  activate  when  in¬ 
side  applications.  You  could,  however, 
remove  int9handler  if  you  have  an 
NMI  hardware  switch.  I  also  recom¬ 
mend  changing  the  Turbo  Debugger 
hot  key  from  Ctrl-Break  to  something 
else. 

The  debugging  concept  presented 
in  this  article  will  work  in  a  similar 
manner  for  .EXE  programs  that  run  TSR 
programs,  although  you  do  have  to 
take  the  different  segments  into  ac¬ 
count.  You  can  also  extend  this  con¬ 
cept  to  languages  such  as  C  and  Pascal 
when  you  create  TSR  programs  using 
them.  These  languages  have  a  built-in 
load-and-execute  function;  the  trick  is 
to  know  how  much  memory  to  free 
before  you  call  it. 

Conclusions 

No  matter  how  well  we  design,  no 
matter  how  well  we  code,  and  no  mat¬ 
ter  how  much  we  know,  our  programs 
will  not  necessarily  run  bug  free  once 
compiled.  That  goes  twice  for  TSR  pro¬ 
grams.  The  trick  is  to  minimize  the  time 
it  takes  to  debug  using  tools  such  as 
Turbo  Debugger.  I  hope  this  article 
will  give  you  an  extra  tool  in  the  battle 
against  Tyranno-Saurus  Rex  (TSR)  bugs. 
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APL  PLUS  System  n 

An  inside  look  at  the  evolution  of  APL*PLUS/PC from  STSC 


TSC’s  recent  introduction  of  its 
API 'PLUS  System  II  (SII)  for  80386- 
based  PC  compatibles  may  be  one 
of  the  most  significant  events  in  the 
APL  world  for  some  time.  SII  succeeds 
STSC’s  highly  successful  APL*PLUS/PC 
(APL/PC)  as  its  flagship  microcomputer 
product.  Enhancements  include  nested 
arrays,  improved  handling  of  work¬ 
spaces,  and  more. 

APL/PC  had  some  limitations,  mainly 
a  consequence  of  its  dependence  on 
the  8088  processor.  I  had  hoped  STSC’s 
new  interpreter  would  take  full  advan¬ 
tage  of  the  80386  and  include  fixes  to 
the  more  noticeable  shortcomings  of 
APL/PC  while  maintaining  essentially 
the  same  interpreter  and  close  com¬ 
patibility  between  the  two  systems. 

What  STSC  has  produced  is  differ¬ 
ent.  You  do  get  the  expected  80386 
enhancements,  plus  nested  arrays.  SII, 
however,  carries  over  some  of  the  prob¬ 
lems  of  APL/PC  and  adds  a  few  new 
ones.  SII  is  twice  as  expensive  as  APL/ 
PC,  with  no  special  price  for  an  up¬ 
grade.  It  requires  an  80387  coprocessor 
to  take  full  advantage  of  its  extra  speed; 
and  there  are  many  changes  from  APL/ 
PC,  making  SII  incompatible  with  its 
predecessor. 

Before  getting  into  a  detailed  discus¬ 
sion  of  SII,  let’s  take  a  brief  look  at  the 
overall  system.  Once  the  basics  have 
been  covered,  this  review  looks  at  the 
new  product  from  the  point  of  view  of 
the  APL/PC  user,  focusing  on  the  en¬ 
hancements  that  SII  provides. 

Functionality 

Like  APL/PC,  SII  is  an  implementation 
of  standard  APL  in  the  commonly  ac¬ 
cepted  sense:  A  program  written  in  stan¬ 
dard  VSAPL,  not  using  shared  variables 
or  system-specific  code,  can  be  ported 
to  SII  and  run  with  little  or  no  modifi¬ 
cation. 

SII  includes  most  of  the  extensions 
to  the  APL  language  found  in  APL/PC. 
These  extensions  include: 

•  APL  files 

•  hfmt,  sfi,  nvr 
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•  SSI,  0IDLOC ;  SSIZE 

•  BVR ,  0DEF 

(vector  function  representations) 

•  Event  handling  (via  BE1X,  OALX ,  USA) 

•  Primitives  match  ,  without ,  find 

In  addition,  SII  includes  several  PC- 
specific  features  found  in  APL/PC,  such 
as: 

•  ffCALL  (to  support  machine-language 
subroutines) 

•  OPEEK,  U POKE 

•  UEDIT 

Full-screen  editor 

•  Full  screen  management  via  0WIN, 
0WGET,  OWPUT 

•  OGPRINT,  and  so  forth,  for  graphics 
management 

•  Access  to  native  files 

•  Calls  to  DOS  commands  via  OCMD 

•  Direct  access  to  DOS  directory'  func¬ 
tions  (for  example,  0CHDIR) 

New  features  in  SII  include  nested  ar¬ 
rays,  and  system  functions,  and  vari¬ 
ables  such  as  BED,  0FHIST,  0PR,  BSAVE , 
and  OPSAVE.  Missing  are  detached  I/O 
facilities  (such  as  BIN  and  BOUT),  and 
several  BPEEK and  BPOKE  locations  have 
been  disabled.  Also  removed  are  the 
little-used  system  variables  BKEYW, 
BHNAMES,  and  BHTOPIC. 

I  should  mention  that  SII’s  work¬ 
spaces  and  files  are  not  compatible 
with  APL/PC.  SII  has  no  means  of  read¬ 
ing  an  APL/PC  workspace  directly,  but 
the  system  does  include  a  workspace 
of  defined  functions  that  allow  full  ac¬ 
cess  to  APL/PC  files.  Thus,  files  can  be 
transferred  back  and  forth  using  these 
functions,  and  hence  workspaces,  via 
the  standard  functions  WSTOFILE  on 
the  source  system  and  FILETOWS  on 
the  target  system. 

Enhancements 

SII  offers  several  enhancements.  Most 
notably,  SII  uses  Phar  Lap’s  DOS  exten¬ 
der  to  run  80386  protected  mode  under 
standard  DOS,  Version  3  3  or  later.  Use 
of  the  80386  processor  has  allowed 
STSC  to  make  several  fixes  to  APL/PC’s 
shortcomings. 

New  are  4-byte  integer  and  bit 
Boolean  data  types.  API/PC  stored  both 
in  2  bytes.  In  fact,  APL/PC  Booleans 
were  one  of  that  system’s  weak  points. 


Not  only  did  they  take  up  far  too  much 
space  but  also  the  interpreter  had  no 
special  code  for  Boolean  calculations. 
In  executing  +/A=B,  for  example,  the 
interpreter  now  knows  A=B  is  Boolean 
and  therefore  is  able  to  calculate  the 
plus  reduce  efficiently.  APL/PC  did  not 
do  so. 

Another  enhancement  is  that  there 
is  no  limit  on  variables  nor  a  perform¬ 
ance  penalty  for  large  arrays.  Earlier 
versions  of  APL/PC  limited  object  size 
to  64K.  Athough  this  limitation  was 
relaxed  in  later  versions,  the  manipula¬ 
tion  of  objects  greater  than  64K  was 
rather  sluggish. 

There  is,  however,  one  caution.  Be¬ 
cause  SII  uses  protected  mode,  BCALL 
machine  language  written  for  APL/PC 
will  not  work. 

Workspaces 

Workspaces  are  now  limited  only  by 
the  amount  of  available  memory.  (The 
theoretical  limit  is  2  gigabytes.)  Part  of 
the  APL  system  (the  DOS  extender  and 
APL  session  manager)  is  located  in  the 
first  640K  of  system  memory,  and  the 
APL  interpreter  is  located  in  memory 
above  1  Mbyte.  Any  other  free  memory 
above  1  Mbyte  is  available  for  the  APL 
workspace.  STSC  recommends  a  mini¬ 
mum  of  2-Mbytes  RAM,  leaving  a  work¬ 
space  of  about  750K.  This  compares 
to  about  400K  of  workspace  with 
APL/PC. 

Several  workspaces  are  supplied,  in¬ 
cluding  complex  numbers,  eigenvalue 
calculations,  upload  and  download  to 
mainframe  APL  systems,  printer  driv¬ 
ers,  and  some  utilities.  A  major  feature 
here  is  extensive  support  of  GSS'CGI 
graphics,  which  consists  of  a  work¬ 
space  plus  several  files  accommodat¬ 
ing  a  wide  range  of  graphics  devices. 

Nested  A  rrays 

SII  now  includes  a  fairly  basic  nested 
array  capability  made  up  of  the  follow¬ 
ing: 

•  enclose  and  disclose 

•  split  and  mix 

•  type 

•  depth 

•  each  operator 
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Enclose,  split,  and  mb:  can  be  modified 
by  the  axis  operator.  SII  also  supports 
strand  notation  and  scattered  assign¬ 
ment,  and  it  allows  user-defined  func¬ 
tions  as  arguments  to  operators.  User- 
defined  operators,  however,  are  not 
supported. 

Nested  arrays  presented  one  pleas¬ 
ant  and  unexpected  surprise  when  I 
reviewed  the  system.  My  programs  typi¬ 
cally  depend  on  the  ability  to  package 
APL  objects  (such  as  representing  a  list 
of  APL  objects  in  a  single  object).  In 
using  SII,  I  was  initially  concerned  that 
most  of  my  systems  would  not  work 
without  a  good  package  capability.  Of 
course,  programmers  can  implement 
packages  with  ordinary  APL  functions, 
but  I  had  expected  this  to  be  much  too 
slow,  as  it  had  been  with  APL/PC. 

Nested  arrays  came  to  the  rescue. 
Using  them  I  was  able  to  write,  in  a 
couple  of  hours,  a  complete  package 
emulator  that  is  efficient  enough  for 
general  use.  The  package  runs  an  or¬ 
der  of  magnitude  slower  than  the 
APL/PC  assembler  functions,  but  I  find 
that  acceptable. 

Indeed,  only  a  couple  of  problems 
remain  to  be  solved  before  dispensing 
altogether  with  assembler  or  system 
package  functions.  Because  emulators 
store  functions  in  their  vector  represen¬ 
tations,  locked  functions  can’t  be  han¬ 
dled,  and  the  intermediate  compilations 
produced  when  a  function  is  first  exe¬ 
cuted  are  thrown  away. 

Session  Manager 

Several  enhancements  have  been  made 
to  the  user  interface.  A  session  man¬ 
ager,  implemented  independently  from 
the  APL  interpreter,  now  handles  the 
APL  session  and  one  or  more  edit  ses¬ 
sions  (the  ring  editor).  New  functions 
that  you’ll  find  include  search  and  re¬ 
place  (in  any  session),  copy  or  block 
move  within  or  among  sessions  or  APL 
objects,  undo  several  erasures,  restore 
current  line,  and  search  for  matching 
parenthesis  or  bracket.  Especially  use¬ 
ful  are  token  search  and  replace  and 
the  ability  to  set  stop  and  trace  when 
editing  functions.  Additionally,  pop- 
down  menus  provide  an  alternative 
means  of  selecting  various  options. 

Various  keystrokes  have  been  added 
and  others  changed  to  support  these 
capabilities.  In  fact,  the  underlying  key¬ 
board  driver  itself  has  been  extensively 
redesigned.  Some  changes  would  be 
needed  to  APL/PC  functions  referenc¬ 
ing  keyboard  numbers,  but  overall,  the 
use  of  the  keyboard  is  much  better  and 
more  logical  than  with  APL/PC. 

There  are  a  couple  of  minor  prob¬ 


lems,  though.  A  drawback  to  the  new 
ring  editor  is  that  only  one  editing  ses¬ 
sion  at  a  time  can  be  handled  under 
program  control.  Also,  the  session  man¬ 
ager  appears  slightly  slower  than  the 
APL/PC  when  displaying  output. 

Character  Set 

Like  APL/PC,  SII  offers  both  the  tradi¬ 
tional  APL  keyboard  and  a  text  key¬ 
board  called  the  Unified  keyboard.  I 
am  not  happy  with  either.  The  tradi¬ 
tional  APL  keyboard  is  a  nuisance  to 
use  because  it  remaps  several  standard 
keys,  such  as  the  apostrophe,  colon, 
and  semicolon,  to  new  positions.  Thus, 
it  is  difficult  to  become  fluent  in  both 
the  APL  and  standard  keyboard  lay¬ 
outs.  The  whole  question  of  the  char¬ 
acter  set  and  keyboard  layout  was  hotly 
debated  a  few  years  ago  in  the  APL 
industry  for  this  reason. 

Two  different  solutions  were  pro¬ 
posed  for  the  PC,  both  using  Alt  or 
Shift-Alt  key  combinations  to  represent 
special  APL  characters.  The  main  dif¬ 
ference  lay  in  the  choice  of  the  primary 
alphabet.  STSC’s  Unified  keyboard  treats 
the  uppercase  alphabet  as  primary  and 
lowercase  as  emphasized,  whereas 
Sharp’s  Union  keyboard  uses  the  re¬ 
verse.  In  retrospect,  it  is  quite  clear  that 
the  Union  keyboard  is  correct;  it  fol¬ 
lows  the  normal  practice  of  written  lan¬ 
guages  and  computer  languages  that 
allow  both  uppercase  and  lowercase 
alphabets.  In  practice,  I  find  the  rever¬ 
sal  of  the  usage  of  uppercase  and  low¬ 
ercase  alphabets  in  the  Unified  key¬ 
board  disconcerting,  and  I  still  use  the 
APL  keyboard  (as  does  nearly  every¬ 
one  else).  At  some  stage,  STSC  should 
reverse  its  policy  and  its  alphabets! 

Documentation  and  Support 

The  documentation  is  up  to  STSC’s  usual 
excellent  standard.  It  includes  a  com¬ 
prehensive  reference  manual,  a  users’ 
guide,  a  manual  of  GSS  graphics,  and 
a  pocket  quick  reference. 

I  have  used  STSC’s  customer-sup- 
port  help  line  several  times  and  am 
happy  to  report  its  staff  members  are 
invariably  courteous  and  efficient.  STSC 
also  goes  out  of  its  way  to  ensure  that 
a  variety  of  hardware  is  supported  by 
its  system. 

Minor  Improvements 

Several  minor  improvements  are  note¬ 
worthy.  First,  note  that  screens  other 
than  25  rows  by  80  columns  are  now 
fully  supported.  Also,  notice  symbol 
table  sizes  are  now  increased  automati¬ 
cally  so  that  using  )SYMBOLS  when 
first  creating  a  workspace  is  unneces¬ 
sary.  Maximum  symbol  size  is  now 
32767. 

Improvements  to  the  default  format¬ 


ting  of  numbers  are  as  follows.  First, 
formatting  of  small  numbers  switches 
to  exponential  notation  only  when  the 
exponent  is  -  7  or  smaller.  In  contrast, 
APL/PC  had  exponential  notation  start¬ 
ing  at  -  3,  which  often  produced  un¬ 
readable  numeric  displays.  Second,  nu¬ 
meric  matrices  are  now  formatted  col¬ 
umn  by  column  so  that  each  column 
is  formatted  to  its  own  width  instead 
of  to  the  width  of  the  widest  column. 
Curiously  enough,  formatting  of  nu¬ 
meric  matrices  in  APL/PC  was  so  slow 
that  it  was  more  efficient  to  format  us¬ 
ing  a  defined  function  that  formatted 
each  column  separately  and  catenated 
the  results.  Even  in  SII,  using  the  de¬ 
fined  function  is  only  maiginally  slower; 
clearly  an  inefficient  algorithm  is  being 
used  here. 

Printer  support  is  extensive,  but  per¬ 
haps  I  might  make  one  request.  I  use 
a  LaserJet  II  printer,  for  which  STSC 
provides  an  APL  font.  It’s  a  12-point 
font,  however,  which  is  too  large  for 
function  listings.  Condensed  mode  is 
an  improvement  but  still  is  still  unsatis¬ 
factory.  I’d  like  to  see  STSC  supply  APL 
fonts  in  a  variety  of  sizes. 

Problems 

SII  does  have  a  few  problems.  To  start 
with,  there  are  some  changes  that  bring 
little  or  no  benefits,  yet  they  invalidate 
a  lot  of  existing  software,  making  life 
more  difficult  for  programmers. 

For  instance,  automatic  formatting 
applied  when  defining  functions  has 
been  disabled,  leaving  the  original 
source  unchanged.  This  formatting  was 
extremely  useful:  It  made  code  much 
easier  to  read;  it  meant  programmers 
need  not  waste  time  manually  pretty¬ 
ing  the  code;  and  utilities  such  as  line 
relabelers,  comparison  functions,  and 
search  and  replace  functions  could  take 
advantage  of  the  standard  format. 

STSC  supply  a  utility  [trianglejVR, 
which  (supposedly)  converts  any  vec¬ 
tor  representation  to  either  its  canonical 
vector  representation  in  APL/PC  or  a 
similar  representation  in  SII.  In  neither 
case,  however,  does  this  work  correctly! 

Next,  APL  files  can  now  be  accessed 
by  giving  their  DOS  path  rather  than 
the  APL  library  number  used  previously. 
(Incidentally,  the  library  number  is  still 
recommended  by  STSC  for  compatibil¬ 
ity.)  Thus,  rather  than  referring  to  a  file 
as  11  TABLES,  I  can  now  use  a  few 
more  keystrokes  and  enter  C:  \APL\ 
l/ULS\  TABLES.  This  seemingly  inno¬ 
cent  extension  confers  no  real  benefit 
to  users,  but  it  has  the  serious  draw¬ 
back  that  code  accessing  APL  files  may 
no  longer  work  properly  and  algorithms 
that  access  files  have  to  be  much  more 
complex  than  before. 
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A  related  issue  is  that  there  is  no 
longer  a  default  APL  library,  which  raises 
the  question  of  how  to  access  a  file  or 
workspace  given  only  its  name  (not  its 
library  number  or  full  DOS  path).  This 
feature  was  especially  useful  in  sys¬ 
tems  intended  for  distribution  when 
the  library  number  or  DOS  path  was 
not  known  in  advance. 

Timing 

This  was  a  real  surprise  for  me.  On  my 
machine,  there  is  no  overall  significant 
difference  in  performance  between  S1I 
and  APL/PC.  In  fact,  some  common 
functions  consistently  perform  slower 
in  SII.  An  example  is  the  standard  vector- 
to-matrix  utility,  which  typically  runs 
about  20  percent  slower  (even  after 
compilation).  These  results  differ  from 
STSC’s  advertised  speedups  of  between 
50  to  500  percent.  There  are,  however, 
several  factors  to  take  into  account. 

The  use  of  80386  machine  language 
should,  in  theory,  enable  quite  signifi¬ 
cant  improvements  over  the  same  pro¬ 
grams  written  in  8088  code.  I  suspect 
this  has  happened  but  has  been  offset 
by  the  more  complex  interpreter  re¬ 
quired  by  nested  arrays. 

TSC  strongly  recommends  using  a 
coprocessor  (which  I  do  not  have)  be¬ 


cause  SII  makes  much  better  use  of 
coprocessing  than  does  APL/PC.  In  par¬ 
ticular,  with  a  coprocessor  on-board, 
STSC  claims  a  six  time  speedup  for 
integer  arithmetic  and  four  times  for 
floating-point  arithmetic  and  mixed  primi¬ 
tives.  The  company’s  claim  for  overall 
speedup  is  more  modest:  30  to  50  per¬ 
cent  in  total  processing  time. 

SII  also  has  a  form  of  intermediate 
compilation  for  its  functions.  The  first 
time  a  function  is  executed,  it  runs 
slowly  while  the  function  itself  is  inter¬ 
nally  redefined.  It  runs  faster  the  next 
time  around.  The  vector-to-matrix  func¬ 
tion,  for  example,  doubled  in  size  from 
532  bytes  to  1,024  bytes,  while  timing 
improved  about  12  percent.  This  is  nice, 
but  it  requires  functions  to  be  workspace- 
resident.  Those  who  prefer  to  store 
their  systems  on  file  (essential  for  large 
applications)  will  find  there  is  no  way 
of  storing  the  compiled  code,  so  func¬ 
tions  must  be  recompiled  each  time 
they  are  run. 

I  think  it’s  unrealistic  to  use  stand¬ 
alone  benchmarks  to  compare  the  per¬ 
formance  of  SII  and  APL/PC.  The  larger 
workspace  of  SII  allows  more  data  to 
be  operated  on  simultaneously  and  can 
allow  more  efficient  nonlooping  algo¬ 
rithms  to  be  written.  The  use  of  4-byte 
integers  enables  more  use  of  integer  arith¬ 
metic  rather  than  floating  point,  and  bit 
Boolean  manipulation  is  much  faster 


than  with  APL/PC’s  2-byte  Booleans. 

The  overall  performance  of  systems 
written  in  SII  should  therefore  be  better 
than  those  written  with  APL/PC  — even 
for  users  without  a  coprocessor.  At  the 
same  time,  there  appears  to  be  some 
room  for  improvement  in  efficiency. 
APL/PC  users  hoping  to  move  up  to  a 
blindingly  fast  implementation  may  be 
disappointed. 

Conclusion 

Overall,  SII  is  a  more  attractive  product 
than  APL/PC.  In  particular,  it  fits  in 
with  STSC’s  long-term  strategy  for  its 
PAL  product  range.  In  the  past,  STSC 
has  been  criticized  for  supporting  too 
great  a  variety  of  APL  interpreters,  which 
were  not  closely  compatible  with  each 
other  and  which  apparently  stretched 
STSC’s  development  resources  too  thin. 
The  plan  now  is  to  support  one  pri¬ 
mary  product,  the  Portable  APL*PLUS 
System,  with  implementations  on  the 
PC  (SII),  VAX,  and  various  Unix  ma¬ 
chines;  370  (VM\XA  and  MVS\XA)  im¬ 
plementations  are  to  follow.  APL/PC 
will  continue  to  be  supported  but  will 
not  become  part  of  this  product  range. 
Sooner  or  later,  therefore,  serious  users 
of  APL/PC  will  want  to  bite  the  bullet 
and  make  the  change  to  SII. 

DDJ 

Vote  for  your  favorite  feature/article. 

Circle  Reader  Service  No.  8. 


104 


REAL-TIME  MODELING 

Listing  One  (Text  begins  on  page  26.) 

Listing  Four 

♦include  <dos.h> 

void  set  timer (  divisor  ) 

int  divisor; 

♦define  TRUE  -1 

{ 

♦define  FALSE  0 

int  cnt; 

int  lo,  hi; 

void  user  defined  background  task(); 

void  set  up  user  background  task(); 

cnt  =  65536  /  divisor; 

void  set  down  user  background  task(); 

void  set  up  user  real  time  task(); 

void  set  down  user  real  time  task(); 

hi  =  cnt  /  256; 

void  set  up  real  time  task(); 

void  set  down  real  time  taskQ; 

outportb (  0x43,  0x36  ); 

int  not  done  =  TRUE; 

outportb (  0x40,  lo  ) ;  /‘write  tic  counter*/ 

outportb (  0x40,  hi  ); 

} 

int  over_run  =  FALSE; 

main ( ) { 

set  up  user  real  time  task();  /‘initialization  section*/ 

set  up  real  time  task(); 

set  up_user_background_task () ; 

End  Listing  Four 

while (  not  done  &&  !  over  run) {  /‘background  task  loop*/ 

user_defined_background_task () ; 

} 

Listing  Five 

set  down  real  time  task();  /‘termination  section*/ 

set  down  user  background  task(); 

set_down_user_real_time_task () ; 

int  i  -  0;  /*  DATAPOOL  */ 

if (  over  run  ) 

user  defined  background  task(){ 

printf ("Error  exit,  frame  over  run\n"); 

) 

printf ("i  =  %d\n",  i  ); 

) 

user  defined  real  time  function(){ 

End  Listing  One 

i  +=  1; 

) 

End  Listing  Five 

Listing  Two 

void  interrupt  real_time_task () ; 
void  interrupt  (‘old  clock  func)(); 

Listing  Six 

void  set  timer (); 

int  user  define  divisor  =  1;  /‘initialize  in  case  user  forgets*/ 

union { 

char  coprocessor  state [94]; 

void  set  up  real  time  task() 

int  control  word; 

{ 

} float  save; 

void  interrupt  (‘getvect  () )  () ; 

/*  save  coprocessor  state  */ 

old  clock  func  =  getvect (  0x08  );/*save  original  clock  vector*/ 

asm  fsave  float  save. coprocessor  state 

setvect (  0x50,  old  clock  func  ); /‘store  in  unused  location*/ 

asm  fldcw  float  save. control  word 

setvect (  0x08,  real  time  task  );  /‘overwrite  with  real-time*/ 

set_timer(  user_define_divisor  );  /‘set  system  timer*/ 

/*  restore  coprocessor  state  */ 

void  set  down  real  time  task(){ 

asm  frstor  float  save . coprocessor  state 

setvect (  0x08,  old  clock  func  );  /‘restore  clock  vector*/ 

set  timer (  1  );  /‘reset  system  timer*/ 

) 

End  Listing  Six 

End  Listing  Two 

Listing  Seven 

Listing  Three 

while(  not  done  &&  !  over  run  )(  /*  non  real-time  debugging*/ 

user  defined  background  task(); 

user_defined_real_time_task () ; 

int  running  =  FALSE; 

End  Listing  Seven 

void  interrupt  real  time  task(){ 

enable () ; 

if (  ! running  &&  lover  run  ){ 
running  =  TRUE; 

Listing  Eight 

user  defined  real  time  task();  /‘real-time  function*/ 

}else( 

over_run  =  TRUE; 

♦include  <dos.h> 

♦define  TRUE  -1 

if (  inter  count  ==  user  define  divisor  ) ( 

♦define  FALSE  0 

geninterrupt (  0x50  );  /‘call  system  clock*/ 

inter  count  =  0; 

void  user  defined  background  task(); 

) else { 

void  set  up  user  background  task(); 

outport (  0x20,  0x20  );  /*8259  end  of  interrupt  routine*/ 

void  set  down  user  background  task(); 

inter  count  +=  1; 

void  set  up  user  real  time  task(); 

}; 

void  set  down  user  real  time  task(); 

void  set  up  real  time  task(); 

running  =  FALSE; 

void  set_down  real  time  task(); 

int  not  done  =  TRUE; 

int  over  run  =  FALSE; 

End  Listing  Three 

main  ()  { 

set  up  user  real  time  task();  /‘initialization  section*/ 

set  up  real  time  task(); 

set_up_user_background_task () ; 

(continued  on  page  80) 
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Listing  Eight  (Listing  continued,  text  begins  on  page  26.) 

Listing  Nine 

while(  not  done  &&  i  over  run) {  /‘background  task  loop*/ 

double  x;  /*  DATAPOOL  */ 

user_defined_background_task () ; 

extern  int  user  define  divisor; 

♦define  m  1.0134145  /*  define  spring-mass  constants  */ 

set  down  real  time  task();  /‘termination  section*/ 

♦define  k  10.0 

set  down  user  background  task(); 

♦define  zeta  0.01 

set_down  user  real  time  task(); 

♦define  x_o  30.0 

if (  over  run  ) 

♦define  frame  time  0.013725 

printf ("Error  exit,  frame  over  run\n"); 

} 

double  t  =  0.0;  /*  real-time  */ 

double  cl;  /*  real-time  constants  */ 

/******************************************************/ 

double  c2; 
double  c3; 

void  interrupt  real_time_task () ; 
void  interrupt  (‘old  clock  func)(); 

double  c4; 

void  set  timer (); 

void  set  up  user  real  time  task(){ 

int  user  define  divisor  =  1;  /*  initialize  in  case  user  forgets  */ 

double  omega; 

double  temp; 

void  set_up_real_time  task() 

double  sqrt(); 

void  interrupt  (‘getvect () ) () ; 

user  define  divisor  =4;  /*  set  user  divisor  counter  */ 

old  clock  func  =  getvect (  0x08  );  /‘save  original  clock  vector*/ 

omega  =  sqrt (  k  /  m  ) ; 

setvect(  Ux50,  old_clock_func  );  /‘store  in  unused  location*/ 
setvect(  0x08,  real  time  task  );  /‘overwrite  with  real-time*/ 

temp  =  sqrt (  1.0  -  zeta  *  zeta  ); 

set  timer(  user  define  divisor  );  /‘set  system  timer*/ 

} 

cl  -  -  zeta  *  omega;  /*  compute  real-time  constants  */ 

c2  =  zeta  *  x_o  /  temp; 
c3  -  temp  *  omega; 

void  set  down  real  time  task(){ 

c4  =  x  o; 

setvect(  0x08,  old_clock_func  );  /‘restore  clock  vector*/ 
set  timer (  1  );  /‘reset  system  timer*/ 

) 

} 

void  set_down  user_real_time_task () (  /*  no  set  down  necessary  */ 

/******************************************************/ 

void  user  defined  real  time  task()( 

union ( 

double  cos(); 

char  coprocessor  state [94]; 

double  sin(); 

int  control  word; 

double  exp(); 

}  float  save; 

/*  spring-mass  model  */ 

x  =  exp(  cl  *  t  )  *  (  c2  *  sin(  c3  *  t  )  +  c4  *  cos (  c3  *  t  )  ); 

int  running  =  FALSE; 
int  inter_count  =  0; 

t  +=  frame_time; 

void  interrupt  real  time  task(){ 

/*  save  coprocessor  state  */ 

asm  fsave  float_save.coprocessor_state 

asm  fldcw  float__save. control  word 

End  Listing  Nine 

enable ( ) ; 

if (  ! running  &&  !over_run  ){ 
running  =  TRUE; 

user_defined_real_time  task();  /‘real-time  function*/ 

}else{ 

Listing  Ten 

over_run  =  TRUE; 

♦include  "graphics. h" 

♦define  FALSE  0 

if  (  inter  count  ==  user  define  divisor  ){ 

♦define  TRUE  -1 

geninterrupt (  0x50  );  /‘call  system  clock*/ 

inter  count  =  0; 

extern  int  not  done; 

}else( 

extern  double  x;  /*  DATAPOOL  */ 

outport (  0x20,  0x20  );  /*8259  end  of  interrupt  routine*/ 

inter  count  +=  1; 

int  x  off  =  320; 

); 

int  y_off  =  100; 

running  =  FALSE; 

stationary [11] [4]  =  (  {  0,  0,  0,  -5  ),  /*  base  */ 

{  0,  0,  7,  0  }, 

/*  restore  coprocessor  state  */ 

{  -40,  -5,  40,  -5  }, 

asm  frstor  float  save .coprocessor  state 

{  -35,  -5,  -30,  -12  }, 

) 

(  -25,  -5,  -20,  -12  }, 

(  -15,  -5,  -10,  -12  ), 

/a*************************************,,***************/ 

{  -5,  -5,  0,  -12  ), 

(  5,  -5,  10,  -12  }, 

void  set  timer (  divisor  ) 

{  15,  -5,  20,  -12  }, 

int  divisor; 

{ 

{  25,  -5,  30,  -12  }, 

{  35,  -5,  40,  -12  )  }; 

int  cnt; 

int  lo,  hi; 

void  set  up  user  background  task(){ 

int  i,  j; 

int  g_driver  =  EGA; 
int  g  mode  =  EGAHI; 

cnt  =  65536  /  divisor; 

char  d_path[]  =  {""); 

hi  =  cnt  /  256; 

int  g_error; 

outportb(  0x43,  0x36  ); 

outportb(  0x40,  lo  );  /‘write  tic  counter*/ 

outportb(  0x40,  hi  ); 

} 

if(  registerbgidriver (  EGAVGA  driver  )  <  0  )(  /*  EGA  driver  */ 

printf ("ERROR:  can't  register  ega/vga  driver\n"); 
exit () ; 

}; 

initgraph(  &g_driver,  4g_mode,  d_path  ); 
g  error  =  graphresult () ; 

if (  g  error  <  0  ) ( 

printf ("ERROR:  %s\n",  grapherrormsg (g  error)  ); 

exit (  0  ) ; 

End  Listing  Eight 

setcolor (  YELLOW  ); 

for(  i  =  0;  i  <  2;  ++i  ){  /*  setup  spring  */ 

setactivepage (  i  ); 

for (  j  =  0;  j  <  11;  ++ j  ) ( 

line(  stationary! j] [0]  +  x  off,  stationary [j] [1]  +  y  off. 

stationary [ j] [2]  +  x_off,  stationary! j] [3]  +  y_off ) ; 

(continued  on  page  82) 
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Listing  Ten  (Listing  continued,  text  begins  on  page  26.) 

} ; 

} 


void  set_down_user_background_task ( ) 

{ 

closegraph () ; 

} 

/*  spring  */ 


} ; 

/*  mass  */ 


void  user_defined_background_task () ( 
double  ratio; 
int  x_spring; 
int  i,  j; 

static  int  start  =  1; 
static  int  buff [2] [100] [4] ; 
static  int  cnt[2]; 
static  int  b  =  0; 
static  int  p  =  0; 

if  (  start  ) { 
set_page (  p  ) ; 

p  =  (  p  )?  0:  1; 

setactivepage(  p  ); 

); 


int  move[  6] [4]  -  {  { 


=  { 

{  7.0 

0.0, 

-7.0, 

5.0 

), 

{  -7.0 

5.0, 

7.0, 

10.0 

}, 

{  7.0 

10.0, 

-7.0, 

15.0 

}, 

(  -7.0 

15.0, 

7.0, 

20.0 

}, 

{  7.0 

20.0, 

-7.0, 

25.0 

}, 

{  -7.0 

25.0, 

7.0, 

30.0 

}, 

{  7.0 

30.0, 

-7.0, 

35.0 

}, 

{  -7.0 

35.0, 

7.0, 

40.0 

}, 

{  7.0 

40.0, 

-7.0, 

45.0 

}, 

(  -7.0 

45.0, 

7.0, 

50.0 

}, 

{  7.0 

50.0, 

-7.0, 

55.0 

)r 

{  -7.0 

55.0, 

7.0, 

60.0 

) 

-30, 

5, 

30,  5 

)  r 

-30, 

40, 

30,  40 

), 

-30, 

5,  - 

30,  40 

1, 

30, 

5, 

30,  40 

}, 

0, 

0, 

0,  5 

), 

o, 

0, 

7,  0 

)  ); 

if  (  kbhitO  )  { 
not_done  =  FALSE; 

); 


x_spring  =  x  +  30.0; 

ratio  =  1.0  +  (  (double) x  /  60.0  ); 


cnt[b]  =  0; 

setcolor (  RED  );  /*  draw  mass  */ 

for (  i  =  0,  j  =  cnt[b];  i  <  6;  ++i,  ++j  ){ 
buff [b] ( j] [0]  =  move[i] [0]  +  x_off; 
buff [b] [j] [1]  =  move[ij [ 1 ]  +  y_off  +  x_spring  +  30; 
buff [b] ( j] [2]  =  move [ i ] [2]  +  x_off; 
buff [bj [ jj [3]  -  move[i] [3]  +  y_off  +  x_spring  +  30; 
line (  buff [b] [ j] [0] ,  buff [b] [ j] [1] ,  buff [b] [ j] [2] ,  buff [b] [ j] [3]  ); 

); 

cnt[b]  +=  6; 


setcolor (  GREEN  );  /*  draw  spring  */ 

for  (  i  =  0,  j  =  cnt[b);  i  <  12;  ++i,  ++j  ){ 
buff [b] [ j] [0]  =  stretch[i] [0]  +  x_off; 

buff [b] [ j] [1]  =  (int)  (  stretch [i] [1]  *  ratio  )  +  y_off; 

buff [b] [ j] [2]  =  stretchfi] [2]  +  x_off; 

buff [bj [ j] [3]  =  (int)  (  stretch [i] [3]  *  ratio  )  +  y_off; 

line (  buff [b] [ j]  [0] ,  buff [b] [ j] [1] ,  buff [b] [ j] [2] ,  buff [b] [ j]  [3]  ); 

}; 

cnt [b]  +=  12; 


b  = 


(  b  )?  0:  1; 


set_page (  p  ) ; 

P  =  (  p  )?  0:  1; 

setactivepage (  p  );  /*  switch  page  */ 

if (  !  start  ) { 

setcolor (  BLACK  );  /*  undraw  picture  */ 

for(  i  =  0;  i  <  cnt [b] ;  ++i  ) 

line (  buff [b] [i]  [0] ,  buff [b]  [i]  [1] ,  buff [b] [i] [2] f  buff [b] [i] [3]  ); 
)else{ 

start  =  0; 

); 

) 


set_page(n)  /*  set  visual  page  */ 

int  n; 

{ 

int  far  *farptr; 
int  addr; 

setvisualpage (  n  ) ; 

farptr  =  (int  far  *) 0x00400063;  /*  status  register  address  */ 

addr  =  * (farptr)  +  6; 

while (  (  inport (  addr  )  &  0x08  )  ==  0x08  );  /*  while  in  vert 

retrace  */ 

while (  (  inport (  addr  )  &  0x08  )  !=  0x08  );  /*  while  not  in  vert 

retrace  */ 


) 

End  listings 
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C++  KERNEL 


issssass 


listing  One  (Text  begins  on  page  45.) 

/********************************************/ 

/*  TASK . HPP  */ 

/*  Tom  Green  */ 

/*  This  file  contains  classes  needed  to  use  multitasking  kernel  */ 

/*  include  this  file  in  your  source  code  and  then  link  with  */ 

/*  task.cpp  and  timer. asm  */ 

/*  this  is  used  when  a  task  is  initialized  */ 

/*  this  is  a  pointer  to  a  function  */ 
typedef  void  (*func_ptr) (void) ; 

/*  this  is  used  for  interrupt  handler  to  call  old  interrupt  handler  */ 

/*  this  is  a  far  pointer  to  a  function  */ 
typedef  void  (far  *far_func_ptr) (void) ; 

/*  this  is  how  the  registers  will  look  on  the  stack  for  a  task  */ 

/*  after  they  have  been  saved  for  a  task  switch,  the  sp  and  ss  */ 

/*  registers  will  point  to  this  when  a  task  is  started  from  the  */ 

/*  interrupt  handler  or  save_image  */ 

typedef  struct  task_image{ 
unsigned  int  bp; 
unsigned  int  di; 
unsigned  int  si; 
unsigned  int  ds; 
unsigned  int  es; 
unsigned  int  dx; 
unsigned  int  cx; 
unsigned  int  bx; 
unsigned  int  ax; 
unsigned  int  ip; 
unsigned  int  cs; 
unsigned  int  flags; 

}task_image; 

/*  a  task  object,  contains  information  needed  by  task_control  object  */ 
/*  to  do  task  switching  and  a  pointer  to  the  task's  workspace  (stack)  */ 

class  task{ 
private: 

friend  class  task_control;  //  task_control  object  needs  access 
friend  class  signal;  //  signal  needs  access  to  next_task 

task_image  far  *stack_ptr;  //  task  stack  ("image")  pointer 
unsigned  char  task_state;  //  task  state  flag 
unsigned  char  ^workspace;  //  address  of  allocated  task  stack 
task  *next_task;  //  pointer  to  next  task  in  queue 

puolic: 

task(func_ptr  func, unsigned  int  workspace_size) ;  //  constructor 
task();  //  destructor 

}; 


Listing  Two 


/*  this  is  a  queue  for  tasks  */ 
/*  it  is  called  signal  so  user  can  define  a  signal  for  task  */ 
/*  communication  */ 


class  signal{ 
private: 

friend  class  task_control;  //  task_control  needs  access 
task  ‘head; 
task  *tail; 

task  *get_task_q(void) ;  //  get  next  task  off  of  < 

void  put_task  q(task  *tptr) ;  //  append  task  to  queue 
public: 

signal (void) (head=tail=0; } ;  //  constructor 


//  get  next  task  off  of  queue 


//  constructor 


/*  task_control  object  */ 

/*  routines  and  methods  to  interface  with  and  control  tasks  */ 

/*  this  object  will  initialize  and  restore  interrupt  vectors,  */ 

/*  keep  track  of  timer  ticks,  and  switch  execution  between  the  */ 

/*  task  objects  */ 

class  task_control{ 
private: 

signal  ready_q;  //  queue  of  tasks  ready  to  run 

task  *current_task;  //  current  active  task 

task_image  far  *old_stack_ptr;  //  return  to  this  stack  when  done 
unsigned  int  task_running;  //  task  switching  enabled  flag 
unsigned  long  timer_ticks;  //  18.2  ticks/second 
unsigned  int  task_lock;  //  lock  out  task  switching 
task_image  far  *task_switch (task_image  far  *stk_ptr, 

unsigned  int  flag, 
signal  *sig) ; 

public: 

task_control (void) ;  //  constructor 

void  add_new_task (task  *new_task) ;  //  add  new  task  object  to 

//  ready  q 

void  start_tasks (void) ;  //  start  switching  tasks  on 

//  ready_q 

void  stop_tasks (void) (task_running=0; } ; 

unsigned  long  get_timer_ticks (void) (return (timer_ticks) ;) ; 
void  lock (void) (task  lock=l;};  //  current  task  can  not  be 


void  unlock (void) (task_lock=0; } ; 
void  send(signal  *sig) ; 


void  wait (signal  *sig) ; 
void  block (void) ; 


//  switched 

//  allow  task  switching 
//  put  task  from  sig  q  on 
//  ready  q 
//  put  task  on  sig  q 
//  task  allows  next  to  run 


TASK.CPP 
by  Tom  Green 


/*  this  file  implements  the  methods  used  by  task_control  and  task  */ 

/*  objects  */ 

♦include  <stdio.h> 

♦include  <stdlib.h> 

♦include  <dos.h> 

♦include  <int.h> 

♦include  "task.hpp" 

/*  task  states  */ 

♦define  TASK_INACTIVE  0 

♦define  TASK_ACTIVE  1 

♦define  TASK_READY  2 
♦define  TASK_WAITING  3 

♦define  TASK_ERROR  Oxff 

/*  flags  for  interface  routines  */ 

♦define  TASK_TIMER_INTR  0 

♦define  TASK_SEND  1 

♦define  TASK_WAIT  2 

♦define  TASK_BLOCK  3 

/*  system  timer  interrupt  or  "timer  tick"  */ 

♦define  TIMER_INT  8 

/*  routines  we  need  from  timer. asm  */ 
unsigned  int  getCS(void); 
extern  void  timer_handler (void) ; 

extern  void  save_image (unsigned  int  flag, signal  *sig); 

/*  global  for  timer_handler  to  call  old  interrupt  routine  */ 
far_func_ptr  old_timer_handler; 

/*  this  is  really  ugly.  */ 

/*  when  constructor  for  task_control  object  is  called  we  save  the  */ 

/*  this  pointer  for  task  switch  routine  to  call  our  task_control  object  */ 
/*  task_switch.  this  means  we  can  only  have  1  task_control  object,  sorry  */ 
task_control  *gl_tptr; 

/*  constructor  for  a  new  task,  workspace  will  be  the  stack  space  for  */ 

/*  the  task,  when  the  timer  interrupt  happens  the  tasks  "image"  */ 

/*  is  saved  on  the  stack  for  use  later  and  the  taskimage  *stack_ptr  */ 

/*  will  point  to  this  image  */ 

task: : task (func_ptr  func, unsigned  int  workspace_size) 

{ 

task_image  *ptr; 

/*  get  stack  or  "workspace"  for  task  */ 

if ( (workspace= (unsigned  char  *) malloc (workspace_size) ) ==NULL) { 
task_state=TASK_ERROR;  //  do  not  let  this  one  run 
return; 

} 

/*  now  we  must  set  up  the  starting  "image"  of  the  task  registers  */ 

/*  ptr  will  point  to  the  register  image  to  begin  task  */ 

ptr= (task_image  *) (workspace+workspace_size-sizeof (task_image) ) ; 

/*  now  save  the  pointer  to  the  register  image  */ 
stack_ptr=MK_FP (getDS () , (unsigned  intjptr); 

ptr->ip= (unsigned  int) func;  //  offset  of  pointer  to  task  code 
ptr->cs=getCS () ;  //  segment  of  pointer  to  task, 

//  compiler  bug 

ptr->ds=getDS () ; 

ptr->f lags=0x200;  //  flags,  interrupts  on 

task_state=TASK_INACTIVE;  //  task  is  inactive 

next  task=0; 


/*  destructor  for  a  task  object  *1 

task: :task (void) 

{ 

free (workspace) ; 


/*  get  the  next  task  off  of  a  task  queue  */ 

task  *signal : :get_task_q (void) 

( 

task  *temp; 

temp=head; 
if (head) 

head=head->next_task; 
return (temp) ; 


/*  append  a  task  to  the  end  of  a  task  queue  */ 

void  signal : :put_task_q (task  *tptr) 

{ 

if (head) 

tail->next_task=tptr; 

else 

head=tptr; 

tail=tptr; 

tptr->next_task=0; 

} 


End  Listing  One 
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Listing  Three  (Listing  continued,  text  begins  on  page  45) 

;no  need  to  clean  up  the  stack  because  it  will  change 
sti 

mov  ss,dx  ;new  ss  returned  in  dx 

mov  sp,ax  ;new  sp  returned  in  ax 

pop  bp  /restore  registers 

pop  di 


_tiraer_handler  endp 


;  void  save_image (unsigned  int  flag, signal  *sig)  -  send,  wait,  block 
;  etc.  all  call  through  here  to  save  the  "image"  of  the  task,  this 

;  code  simulates  what  will  happen  with  an  interrupt  by  saving  the  task 

;  image  on  the  stack,  the  flag  passed  is  passed  on  to  the  task_control 

;  object  task  switcher  so  it  knows  if  it  was  called  by  the  timer 

;  interrupt  handler,  send,  wait,  block,  etc.  the  second  parameter 
;  is  a  signal  pointer  which  is  used  by  send  and  wait  and  is  passed 
/  through  to  the  task  switcher. 

.************************************************************************ 
_save_image  proc  near 

public  _save_image 

/since  this  is  a  C  call  we  can  destroy  some  registers  (ax  bx  cx  dx) , 

/so  now  we  will  set  up  the  stack  as  if  an  interrupt  call  had  happened, 
/leave  parameters  on  stack,  because  calling  routine  will  adjust  on 
/return,  bx  and  cx  will  have  the  parameters  that  were  passed, 
pop  ax  /get  return  address  offset  on  stack 

pop  bx  /get  first  parameter  off  stack 

pop  cx  /get  second  parameter  off  stack 

push  cx  /put  them  back  on  stack 

push  bx 

pushf  /save  flags  for  iret 

mov  dx,cs  /get  code  segment 

push  dx  / save  code  segment  for  return  address 

push  ax  /push  saved  return  address  offset 

push  ax  / save  everything 

push  bx 

push  cx 

push  dx 

push  es 

push  ds 

push  si 

push  di 

push  bp 

sti 

mov  ax,sp  /stack  pointer  parameter 

push  cx  /second  parameter  passed 

push  bx  /first  parameter  passed 

mov  bx,ss 

push  bx  /far  pointer  to  stack,  parameter  passed 

push  ax 

mov  ax,_gl_tptr  /push  hidden  pointer  for  C++  object 
push  ax 

/stack  is  now  set  up  for  call  to  task_control  object  task_switch 
cli  /turn  off  interrupts  for  task  switch 

call  _ task_control_task_switch 

/no  need  to  clean  up  the  stack  because  it  will  change 
sti 

mov  ss,dx  /new  ss  returned  in  dx 

mov  sp,ax  /new  sp  returned  in  ax 

pop  bp  /restore  registers 


ax,sp  /stack  pointer  parameter 
cx  /second  parameter  passed 

bx  /first  parameter  passed 

bx,  ss 

bx  /far  pointer  to  stack,  parameter  passed 

ax 

ax,_gl_tptr  /push  hidden  pointer  for  C++  object 


pop 

pop 

pop 

pop 

pop 

pop 

pop 

pop 

pop 

iret 

_save_image 


void  task3 (void) / 
void  task4 (void) z 

/*  our  task_control  object  (just  1  please)  */ 
task_control  tasker/ 

void  main (void) 

{ 

/*  task  objects  */ 
task  tO ( (func_ptr) taskO, 1024) / 
task  tl ( (func_ptr) taskl, 1024) / 
task  t2  ( (func__ptr)  task2,  1024)  / 
task  t3 ( (func_ptr) task3,  1024)  / 
task  t4  ( (func_ptr) task4, 1024) / 

/*  add  task  objects  to  our  task_control  object  ready  q  */ 

tasker .add_new_task (fit 0) / 

tasker . add_new_task (fitl) z 

tasker . add_new_task (&t2) z 

tasker . add_new_task (&t3) / 

tasker . add_new_task (&t4)  / 

/*  use  zortech  display  package  */ 
disp_open () / 
disp_move (0, 0) / 
disp_eeop () / 

/*  start  tasks  up  and  wait  for  them  to  finish  */ 
tasker .start_tasks () ; 

disp_move (0, 0) / 
disp_eeop() / 
disp_close () / 

} 

static  unsigned  long  counter []=( 0L, 0L, 0L, 0L, 0L) / 
static  signal  sigz 

/*  task  0  prints  the  values  of  the  counters  for  the  other  4  tasks.  */ 
/*  lock  is  used  to  prevent  task  switching  while  the  screen  is  being  */ 
/*  updated,  when  the  task  is  finished,  block  is  called  to  transfer  */ 
/*  control  to  the  next  task  on  the  ready  q  */ 

void  taskO (void) 

( 

whiled)  ( 

/*  disable  task  switching  */ 
tasker .lock  () / 
disp_move (5, 10) / 

disp_printf ("Task  1  %lx", counter (1 )) / 

dispjnove (5,50)/ 

disp_printf ("Task  2  %lx", counter [2] ) / 

disp_move (15, 10) / 

disp_printf ("Task  3  %lx", counter [3] ) / 

dispjnove (15, 50) / 

disp_printf ("Task  4  %lx", counter (4 ]) / 

/*  if  key  pressed  then  stop  the  kernel  and  return  */ 
if  (kbhitO) 

tasker . stop_tasks ( ) / 

/*  re-enable  task  switching  */ 
tasker .unlock () / 

/*  let  next  task  run  */ 
tasker. block  () / 


/*  tasks  1  and  2  just  update  counters,  these  tasks  will  run  until  */ 

/*  a  timer  interrupt  occurs,  so  they  get  a  very  large  chunk  of  time  */ 
/*  to  run,  so  the  counters  increase  rapidly  */ 

void  taskl (void) 

{ 

while (1) { 

counter [1] ++/ 

) 

} 

void  task2 (void) 

[ 

while (1) ( 

counter [2] ++/ 

} 


End  Listing  Three 


Listing  Four 


TASKDEMO . HPP 
by  Tom  Green 


/*  this  file  is  a  demonstration  of  how  to  use  the  C++  multitasking  */ 
/*  kernel.  5  tasks  are  run  and  the  various  means  of  task  switching  */ 
/*  and  communication  are  shown  */ 

/*  you  must  have  the  Zortech  C++  compiler  ver  1.5  and  linker  and  */ 

/*  Microsoft  MASM  5.xx  to  compile  this  code.  */ 

/*  type  "ztc  taskdemo  task  timer"  and  the  ztc.com  will  take  */ 

/*  care  of  compiling,  assembling,  and  linking  */ 

♦include  <stdio.h> 

♦include  <disp.h> 

♦include  "task.hpp" 

void  taskO (void) / 
void  taskl (void) / 
void  task2 (void) / 


/*  task  3  waits  for  a  signal  from  task  4  each  time  the  counter  is  */ 

/*  incremented,  when  a  task  waits,  it  is  put  on  a  signal  q  and  the  */ 

/*  next  task  on  the  ready  q  is  run.  this  means  task  3  and  4  counters  */ 

/*  will  increment  very  slowly,  in  task  4  when  a  signal  is  sent,  the  */ 

/*  task  signal  q  is  checked  for  a  task  to  put  on  the  ready  q.  the  task  */ 
/*  sending  the  signal  is  then  placed  on  the  ready  q  */ 

void  task3 (void) 

( 

while (1) { 

counter [3]++/ 

/*  wait  for  a  signal  from  task  4  */ 
tasker. wait (fisig)  / 


void  task4 (void) 

( 

while (1) { 

counter [4] ++/ 

/*  send  signal  to  task  3  */ 
tasker . send (fisig) / 


End  Listings 
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REAL-TIME  KERNEL 


(  This  word  waits  until  the  head  of  the  timer  queue  is  past 
its  dispatch  time,  and  then  dequeues  the  head  element  from  the 
timer  queue  for  subsequent  processing.  ) 

:  wait-till  (  —  node  )  \  take  next  node  off  queue 

TQ  0  0=  ABORT”  Empty  timer  queue  " 

BEGIN  TQ  0  key  0  now@  <  UNTIL  \  wait  until  its  time 
TQ  pq-deque  \  then  remove  it 

• "  DQ  "  ; 


(  The  following  structures  are  used  in  the  word  "notify" .  The 
first  is  passed  as  a  parameter  block,  and  the  second  is  SPREAD 
as  a  SHEET.  ) 


Listing  Two  (Listing  continued,  text  begins  on  page  52.) 


0  st rue  n.parm 
lw  n.parm  n.pred 

lw  n.parm  n.succ 

0  st rue  n.temp 
lw  n.temp  n.trig 


\  passed  parameters. . . 
\  ptr  to  predecessor 
\  ptr  to  its  successor 

\  temporaries... 

\  trigger  indicator 


(  This  word  searches  the  predecessor  list  of  a  node  for  a 
match  with  the  cfa  of  a  completing  predecessor.  When  the  match 
is  found,  the  low  order  bit  of  the  predecessor  address  is  set 
as  a  flag  to  indicate  that  that  predecessor  has  completed.  If 
all  such  flags  are  set,  "n.trig"  is  set  to  trigger  the  node.  ) 

:  set -done-flag  (  _n.temp  —  _n.temp  )  \  set  pred's  done  fg 

AT  #[  parm  n.parm  n.succ  )+  SH@  Pred's  \  pt  to  succ's  preds 


BEGIN  DUP  @  ?DUP  WHILE 

AT  #[  parm  n.parm  n.pred  ]+  SH@ 

IF  DUP  1  | !  THEN 

DUP  0  AT  n.trig  SH@  AND 

AT  n.trig  SH !  w+  REPEAT  DROP  ; 


\  for  all  preds 
\  we  got  a  match? 

\  yes,  set  done  flag 
\  figure  new  trigger 

\  save  it  4  continue 


(  This  word  clears  all  the  done  flags  that  were  set  to  trigger 
the  activation  of  a  node.  This  word  is  performed  just  prior  to 
activating  the  node,  thus  preparing  it  for  re-triggering  at  a 
later  time.  ) 


clear-done-flags 

AT  #[  parm  n.parm  n.succ  ]+ 
SH@  Pred's 

BEGIN  DUP  0  ?DUP  WHILE 

[  1  NOT  ]#  AND  OVER  ! 
w+  REPEAT  ; 


\  clear  succ's  done  flags 
\  point  to  successor 
\  point  to  his  predecessors 
\  for  all  predecessors 
\  clear  its  done  flag 
\  loop  to  end  of  list 


DUP  >R 
ASucc' s 

BEGIN  DUP  0  ?DUP  WHILE 
NIP  DUP  w+  @  2  PICK  = 
IF  R>  3DR0P  EXIT  THEN 
REPEAT 
HERE  SWAP  ! 

NIL  , 

R>  link-to-pred' s  ; 


\  remember  predecessor  ptr 
\  point  to  successor  ptr 
\  for  all  successors... 

\  duplicate? 

\  yes,  skip  this  node 
\  until  end  of  list 
\  append  new  CONS  cell 
\  CDR  is  NIL 
\  CAR  is  successor  node 
\  fix  his  predecessors  too! 


(  This  word  kicks  off  the  action  to  reverse  link  the  event 
network  by  passing  the  address  of  the  first  node  to  the 
recursive  network  traversal  algorithm.  It  takes  the  address 
of  the  network  list  head  as  its  parameter.  ) 


fix-Succ's  (  head  - 
w+  0 

link-to-pred' s  ; 


\  generate  successor  lists 
\  point  to  last  node 
\  link  it  to  its  predecessors 


(  This  word  recursively  traverses  the  network  accumulating  the 
maximum  path  length  to  each  node.  This  length  from  the  first 
to  last  nodes  is  the  critical  path  length,  or  network  delay.  ) 

:  set-path-len  (  Anode  old-path-length  —  ) 

SWAP  >R  \  save  this  node's  pointer 

R@  delay  0  +  \  add  this  delay  to  old  len 

R@  path-length  0  \  get  current  len 

MAX  DUP  \  new  len  is  max  of  the  two 

R@  path-length  !  \  save  new  len 

R>  Pred's  >R  \  point  to  pred  ptrs  list 

BEGIN  R>  DUP  w+  >R  0  ?DUP  WHILE  \  for  all  predecessors... 

OVER  RECURSE  REPEAT  \  set  their  path  length  too 

DROP  R>  DROP  ;  \  clean  up  and  exit 


(  This  word  calls  the  recursive  network  traversal  routine  to 
compute  the  length  of  the  critical  path  through  the  network. 

The  result  is  stored  in  the  network's  list  head.  ) 

:  set -path-lengths  (  nethead  —  ) 

DUP  w+  @  \  point  to  last  node 

0  \  initial  path  length  is  zero 

set-path-len  \  recursively  set  path  lengths 

DUP  0  path-length  0  \  get  computed  critical  path  length 

SWAP  2  w*+  !  ;  \  save  it  in  network  head 


(  The  "notify"  word  tells  a  successor  to  a  node  that  one  of 
its  predecessors  has  completed.  If  all  of  its  predecessors 
have  completed,  then  that  successor  node  is  started.  ) 


:  notify  (  pred  succ  —  ) 
sizeof  n.temp  SPREAD 
1  AT  n.trig  SH! 
set-done-flag 
AT  n.trig  SH@  IF 

clear-done-flags 


\  notify  a  successor 
\  make  room  for  temps 
\  cock  the  trigger 
\  set  pre.d's  done  flag 
\  has  succ  been  triggered? 

\  yes,  clear  his  done  flags 


CRUSH  NIP  entry-action  \  4  start  him  up! 


ELSE  CRUSH  2DROP  THEN 


\  no,  just  return... 


(  This  word  is  executed  after  a  node  has  been  removed  from  the 
timer  queue  after  waiting  its  required  delay  time.  It  causes 
the  exit  action  routine  for  that  node  to  be  performed,  and  then 
notifies  all  the  successors  of  that  node  that  it  has  completed 
execution.  ) 


exit-action  <  node  —  ) 

DUP  word-2  PERFORM 
DUP  ASucc's  DUP  0  NIL  = 

IF  T  tens. ball  THROW  THEN 
BEGIN  @  ?DUP  WHILE 
2DUP  w+  0  notify 
REPEAT  DROP  ; 


\  complete  a  node 
\  do  after  delay  stuff 
\  point  to  successor  chain 
\  if  none,  we're  done! 

\  for  all  his  successors 
\  notify  them  he's  done 
\  then  clean  up  4  exit 


(  This  is  the  "Timed  Event  Network  Scheduler",  the  entry  point 
for  the  DOES>  word  of  a  timed  event  network.  Running  such  a 
network  is  done  by  executing  the  name  of  the  network,  which 
calls  TENS  with  the  address  of  the  network  list  head.  ) 


TENS  (  net  —  ) 

tens. ball  CATCH  IF 

DROP  EXIT  THEN 

start-now  @  entry-action  BEGIN 

wait-till  exit-action  AGAIN  ; 


\  run  a  timed  event  net 
\  exit  via  trap  door? 

\  yes,  stop  timer,  exit 
\  no,  start  first  node 
\  wait,  then  finish  it 


(  This  word  displays  the  name  of  a  network  and  its  critical 
path  length  in  milliseconds.  It  is  used  as  a  tuning  aid.  ) 


:  .pathlen  (  nethead  —  ) 

CR 

."  Critical  path  of  " 
DUP  BODY>  >NAME  .NAME 
. "  is  " 

2  w*+  @ 

10  184  */ 

."  seconds  long.  " 

CR  ; 


\  display  critical  path  length 
\  start  on  a  new  line 
\  indentify  it 
\  show  network  name 
\  more  verbiage 
\  fetch  length  in  ticks 
\  convert  to  seconds 
\  display  the  number 
\  more  verbiage 
\  and  a  new  line 


(  This  word  displays  the  critical  path  on  the  screen  at 
compilation  time  to  facilitate  tuning.  ) 


.critpath  (  nethead  —  ) 

. "  Critical  path  is:  "  w+  0 
BEGIN  ?DUP  WHILE 
CR  4  SPACES 
DUP  BODY>  >NAME  .NAME 
Pred's  >R  0  0  BEGIN 
R>  DUP  w+  >R  0 
?DUP  WHILE 
DUP  path-length  0 
2  PICK  OVER  MAX 
OVER  =  IF  2 SWAP  THEN 
2DROP  REPEAT  R>  2DROP 
REPEAT  CR  ; 


\  point  to  last  node 
\  for  each  node  on  critpath 
\  indent  to  look  pretty 
\  display  its  name 
\  for  each  predecessor 
\  get  a  predecessor  pointer 
\  as  long  as  they  exist 
\  get  its  path  length 
\  take  maximum  of  old  4  new 
\  update  max  4  ptr 
\  discard  excess  baggage 
\  loop  till  done 


(  The  Top-of-Stack  is  used  by  END-NETWORK  to  generate  the 
successor  lists  for  all  of  the  nodes  in  the  network.  For  this 
reason,  the  last  node  instantiated  *MUST*  be  the  unique 
terminal  node  for  the  network.  Likewise,  the  first  node 
instantiated  *MUST*  be  the  unique  initial  node  for  the 
network.  ) 


(  This  word  links  a  node  into  the  successor  lists  of  all  of 
its  predecessors.  After  this  has  been  done  recursively  for 
all  the  successors  of  that  node,  ad  infinitum,  then  the  entire 
event  network  will  be  linked  both  forwards  and  backwards.  ) 


F:  link-to-pred 

:  link-to-pred' s  (  node  —  ) 
DUP  Pred's  >R 
BEGIN  R@  0  ?DUP  WHILE 


\  declare  forward  reference 

\  fix  up  forward  Inks  in  network 
\  point  to  it  predecessor  list 
\  for  all  its  predecessors... 


OVER  SWAP  link-to-pred  \  link  this  node  to  its  pred 


R>  w+  >R  REPEAT 
DROP  R>  DROP  ; 


\  point  to  next  pred  ptr 
\  tidy  up  stacks 


R:  link-to-pred  (  node  pred  —  ) 


\  ping  pongs  with  word  above 


:  END-NETWORK  (  head  first  last 
ROT  >R  SWAP 
R@  ! 

R@  w+  ! 

R0  fix-Succ's 
R@  set-path-lengths 
R@  .pathlen 
R>  .critpath  ; 


\  save  head,  put  first  on  top 
\  save  first  in  head 
\  save  last  in  head 
\  generate  successor  lists 
\  compute  critical  path  length 
\  display  critical  path  length 
\  display  critical  path 


(  The  following  word  is  used  to  begin  the  definition  of  a 
timed  event  network.  The  network  is  terminated  by  the  word 
END -NETWORK.  ) 


NETWORK  (  —  ) 

CREATE  HERE 


\  begin  a  timed  event  network 
\  give  it  a  name  and  remember  where 


(continued  on  page  96) 
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REAL-TIME  KERNEL 


C  BENCHMARKING 


Listing  Two  (Listing  continued,  text  begins  on  page  52.) 

NIL  ,  NIL  ,  \  initialize  first  &  last  pointers 

NIL  NIL  \  initialize  2  pointers  on  stack 

0  ,  \  initialize  critical  path  length 

DOES>  TENS  ;  \  runs  the  scheduler  when  called 


{  This  is  the  format  for  declaring  a  node  in  a  TENS  network. 


NODE  <node-name> 
Predecessor 
Entry-Action 
Delay 

Exit-Action 

END-NODE 


predl  . . .  predn 
wordl  . . .  wordn 
n  \  tics 
wordl  . . .  wordn 


NIL  EQU  ANODE 

NODE  (  —  ) 

CREATE 

HERE  EQU  ANODE 
sizeof  TEnode  ALLOT 
0  ANODE  path-length  ! 
NIL  ANODE  ASucc's  ! 
DROP  ?IF  ANODE 
ELSE  ANODE  DUP  THEN  ; 


Predecessors 

DUP 

te.ball  CATCH  NIL  = 

IF  BEGIN  DEPTH  >R  EVAL 
DEPTH  R> 

-  1  =  IF  , 

ELSE 

T  ABORT"  Illegal  Predecessor 
THEN 

AGAIN  THEN 

DROP 

CP  0  ANODE  word-1  ! 

HERE  PFA,  nest  JMP, 


\  pointer  to  current  node 

\  define  network  step  node 
\  make  a  dictionary  header 
\  remember  where  it  is 
\  make  room  for  it 
\  initialize  path  length 
\  terminate  successor  chain 
\  set  1st 
\  &  last  pointers 


\  start  predecessor  list 
\  insert  cushion 
\  to  end  predecessor  list 
\  mark  stack  &  eval  token 
\  did  eval  return  a  value 
\  yes,  store  it  as  a  pred 
\  no,  more  than  one  value? 

\  yes,  abort  with  a  msg! 

\  no  value,  treat  as  comment 
\  build  predecessor  list 
\  remove  cushion 
\  make  entry  action  header 
\  stuff  cfa  and  pfa  into  it 
\  compile  entry  action 


Entry-Action  NIL  ,  T  te.ball  THROW  ;  \  end  predecessor  list 


Delay 

COMPILE  EXIT 
(COMPILE]  [ 

;  IMMEDIATE 


Exit -Act ion 

ANODE  delay  ! 

CP  0  ANODE  word-2  ! 
HERE  PFA,  nest  JMP, 


END-NODE 

COMPILE  EXIT 
(COMPILE]  ( 

;  IMMEDIATE 


\  specify  delay  time 
\  last  word  in  entry  action 
\  set  interpret  state 
\  must  run  while  compiling 


\  specify  exit  action 
\  save  delay  time 
\  make  exit  action  header 
\  stuff  cfa  &  pfa  into  it 
\  force  compile  state 


\  terminate  node  definition 
\  last  word  in  exit  action 
\  set  interpret  mode 
\  must  run  while  compiling 


End  Listings 


Listing  One  (Text  begins  on  page  60.) 

II  /*  sbench. c  —  C  statement  benchmark  generator.  */ 

21  /*  Released  to  the  public  domain  by  David  L.  Fox,  1988.  */ 

31 

41  /*  This  program  will  read  a  list  of  C  statements  and  generate  a  test 
51  program  to  time  the  execution  of  each  statement  in  the  list. 

61  The  list  should  have  the  form: 

7 |  zero  or  more  global  declarations 
81  %% 

91  %zero  or  more  local  declarations  or  statements 
10 1  one  or  more  test  statements 

111  The  global  and  local  declarations  and  statements  are  not  timed. 

121  Every  local  statement  must  have  a  %  in  column  1.  Every  test  statement 

13|  should  be  on  one  logical  line.  Physical  lines  ending  with  \  are 
14 |  continued,  a3  in  C,  so  long  logical  lines  may  be  split. 

151 

161  The  program  is  run  with  a  command  in  the  form: 

17 |  sbench  [  -cx  )  |  -f  name  I  (  -n  xx  ]  (  -o  )  [  -g  )  [  files  ...  | 

181  If  no  input  files  are  given  sbench  reads  the  standard  input. 

1 9 1  Available  options  are: 

201  -c  x  Select  compiler:  x-a  Aztec,  x-d  Datalight, 

211  x-e  Ecosoft,  x-t  Turbo,  x-z  Zortech. 

22!  -f  name  Write  generated  program  to  file  name. 

23 1  -n  xx  Execute  each  statement  xx  times. 

241  -o  Optimize  when  compiling  benchmark. 

251  -g  Generate  test  program  only;  do  not  try  to  compile. 

261  •/ 

27 |  linclude  <3tdio.h> 

281  linclude  <stdlib.h> 

291  linclude  <string.h> 

301  linclude  <ctype.h> 


♦define  OUTFNAME  "statbi 

struct  listel  ( 

struct  listel  ‘next; 
char  ‘line; 

struct  llist  { 

struct  listel  ‘head; 
struct  listel  ‘tail; 


/*  Default  name  of  generated  program.  ’/ 

'  One  element  in  a  linked  list  of  lines.  */ 
'  Link  to  next  element.  •/ 

1  Pointer  to  the  text  of  the  line.  •/ 


Head  of  the  list. 
Tail  of  the  list. 


/*  The  following  enum  type  is  used  to  identify  the  compilers  used: 
enum  cctag  (  aztec  -  'a',  datalight  =  'd',  ecosoft  =■  'e', 
turboc  -  't',  zortech  -  'z'(; 

struct  cmdline  (  /•  Contains  parts  of  command  lines  for  compiler: 

enum  cctag  tag;  /*  Identifies  compiler.  •/ 
char  *cmd;  /’  Beginning  of  command  line.  */ 

char  ‘optimize;  /*  Command  line  option  to  invoke  optimizer, 

char  *lib;  /*  Libraries  added  to  end  of  command  line. 

/*  The  libraries  named  should  contain  the  high  resolution  * 
/*  clock 0  function  if  it  is  used.  The  exact  contents  of  t! 
/*  lib  strings  will  depend  on  how  your  hard  disk  is  organizi 
)  compilers i |  -  (  /*  Compilers [0)  is  tne  aefauit.  •/ 

{  aztec,  "c  -lx  -lm  -dMu_CLOCK",  "  +  f",  ""  ), 

(  datalight,  "die  -dMu_CLOCK",  n-o",  "WlibWdlcWxs .  lib"  ), 

(  ecosoft,  "ecc  -dMu_CLOCK  -lecox",  ""  }, 

I  turboc,  "tcc  -dMu_CLOCK" ,  "-G",  "WlibWtcWxs.lib"  I, 

(  zortech,  "ztc  -dMu_CLOCK",  *-o“,  "WlibWztcWxs. lib"  ) 


struct  cmdoptns  {  / 

unsigned  int  ntimes; 
char  • out f name; 
int  deept; 


struct  cmdline  ‘compiler; 
options; 


Information  extracted  from  command  line.  *, 
/»  Repeat  count  for  SUT.  */ 

/*  Name  of  output  file.  */ 

.'*  Flag,  r.or.-zerc  optimizes  test  program. 


/•  Pointer  to  command  line  details. 


/*  These  strings  form  parts  of  the  generated  program:  */ 

char  ‘pgmincl  *  "linclude\t<stdio.h>\nlinclude\t<time.h>\n\n"; 

char  ‘pgmhdr  -  "lifdef\tMu  CLOCKXn"  /*  Using  high-res  clockO?  */ 

" lundef \tCLK_TCK\nldefIne \tCLK_TCK\tl000000L\nlendif \n" 

"lifdefit _ STDC _ \n"  /*  _ STDC _  indicates  an  ANSI  */ 

"int  main (int  arge,  char  “argv)  ( \n"  /•  conforming  implementation  */ 
"\tvoid  sbdummy (unsigned  int);\n"  ,'*  with  prototypes.  */ 

"lelsein"  /*  Otherwise,  use  KSR  style  function  definitions.  * 

"int  mainfarge,  argv) \nint  argc;\nchar  “argv;  (\n\tint  sb_dummy ( ) ; \n" 
"lendi£\n\tclock_t  sb_t0,  sbcime,  sb_empty; \n” 

"\tunsigned  int  sb_index,  so_nexpr,  soniter; \n"; 
char  ‘ogmend  = 

"'.treturn  0;\n)\nlifdef\t _ STDC_  r.void  sb  dummy  (unsigned  int  il  •"  r." 

"lelseinint  sb_dummy  (n'.nunsignea  ir.t  nlendi  f '  r.\t  return;  •  n  i \n“  ; 

char  ‘pgminit  =  "clock!)  ;\n"  '*  Start  clock,  avoid  first  call  overhead.  *,' 

"sbnexpr  =  0; \nso_niter  =  *u;\n"; 
char  ‘pgmstart  -  "sb_t9  =  clock 0;\n"; 

char  ‘pgmloop  »  " for- ( sb_index-0;  sb_index  <  sb_niter;  *+sb_index)  i Sn" 
"sb_dummy <sb_ index ) ;\n";  *  Keep  optimizers  from  gutting  loop.  *' 

char  ‘pgmnoioop  -  ”'\n";  •  Put  expression  to  be  timed  in  a  block.  •/ 

char  ‘pgmempty  -  "!\nsb_empty  -  clock!)  -  sD_t0;\n";  /*  Time  empty  stmt.  ' 
char  'pgmstop  *  "!\nsb_time  *  clock!)  -  sb_t0;\n"  '*  Print  results.  •/ 

"p’rintf  (\"Statement  %u  required  % 6 . 1  f  microseconds  to  execute,  " 

"%u  iterationis  timed. Wn\", \n+»sb_nexpr, " 

" ( ( (double) ( sb_t ime-so  empty ) ) * ( 1900000 . /CLK_TCK) ) / sb_niter ,  sb_niter , " 
"sbniter  >  l  ?  \"s\"  :  \"\");>n"; 

/*  Function  prototypes.  *' 

void  docmdlme  ( int  arqc,  cnar  “argv,  struct  cmdoptns  ‘optptr)  ; 
char  'get line (FILE  •); 

mt  get opt (int  arge,  char  ‘argvli,  char  *!; 
void  Iladdlstruct  Hist  'last,  char  *str)  ; 
void  outerr (void) ; 

void  writeiines istruct  llist  ‘list,  FILE  ‘outfiie); 
void  usage(void); 

, •  External  variables  communicate  with  getoptl).  •/ 

extern  int  optind;  /•  Index  of  next  command  line  argument  in  argv.  ‘ ' 

extern  char  ‘optarg;  /*  Argument  for  a  command  line  option  (-o  arg) .  */ 

int 

mam  (ir.t  arge,  char  “argv)  | 
char  cmdbuf(256],  *str; 

FILE  *  infile,  ‘outfiie; 
struct  Hist  *llp, 

global 1,  /*  Global  declaration  iines.  */ 

locall,  /*  Local  declaration  lines.  */ 

testl;  /•  Lines  to  be  tested.  */ 

struct  listel  'lep; 


ILE  ‘outfiie) ; 


/*  Global  declaration  iines. 
/*  Local  declaration  lines.  • 
/•  Lines  to  be  tested.  */ 


/*  Set  up  default  values.  */ 

infile  =  stdin; 

options .out f name  -  OUTFNAME; 

options -ntimes  -  1; 

options .doopt  =*  0; 

options .compiler  ■  scompilerslO) ; 

docmdline (arge,  argv,  soptions); 


/*  Process  command  line  options.  */ 
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1251 
1261 
1271 
1281 
129! 
130| 
131 1 
1321 

131 ! 
1351 
1361 
137! 
1381 
1391 
1101 
1411 
1421 
1431 
144  I 
1451 
1461 
1471 
148  i 
149l 
1501 
151! 
152! 
1531 
154  l 
155! 
1561 
1571 
1581 
1591 
1601 
161i 
162| 
1631 
164  l 
1651 
1661 
167  1 
1681 
1691 
1701 
171! 
1721 
1731 
174  I 
1751 

1771 

1781 

179! 

1301 

1811 

182i 

1831 
184  i 
1851 
1861 
1371 


1901 

191  i 

1 92 
133: 
194i 
195' 
196  i 
197: 
1981 
1991 
203; 
201 1 
202! 
2031 
2041 
205! 
2061 
207  i 
2081 
209  ’ 
210! 

212 

2131 

214i 

2161 
217| 
2181 
2191 
2201 
2211 
2221 
2231 
224! 
2251 
2261 
2271 
2201 
2291 
2301 
2311 
2321 
2331 
234| 
2351 
2361 
237| 
2381 
2391 
2401 
2411 
2421 
2431 
244  I 
2451 
2461 
247| 
2481 
2491 
2501 
2511 


global!. head  =■  global!. tail  =  locall.head  =  locall.tail  = 
test 1. head  »  testl.tail  -  NULL; 

."  Once  through  the  loop  for  each  input  file.  */ 
do  { 

if  (optmd  <  argc)  1 

<*  Try  to  open  a  file  from  the  command  line.  */ 
if  iiinfiie  *  fopen idigv joptindi ,  "r") )  --  NULL) 

fprintf (stderr,  "Failed  to  open  input  fileNn"); 
continue;  '  *  Try  the  next  fiie.  •/ 


else  i 

.  •  There  are  are  no  files  on  the  commana  line;  •/ 

! *  use  the  standara  input.  */ 
infile  »  stdin; 
if  (isatty(filenoistdin) ) ) 

fprintf (stderr,  "Enter  list  of  statements: in") ; 


/*  Now  read  the  file  and  append  its  contents  to 
a  linked  list  of  lines.  */ 

lip  =*  igiobail;  i •  First  section  contains  glooax  statements.  ’ 
wmle  ((str  =  getline t infile) )  !  =  NULL)  < 
if  (strncmplstr,  "»%",  2)  ==  0) 

.ip  =  itesti;  *  Founa  end  of  global  section.  *• 

else  if  ( "str  «*  *  4' ) 

llaadi&locall,  str+l);  /*  This  is  a  local  declaration.  *' 
else  lladd(llp,  str); 

if  (ferror ( inf ile) )  i  • *  Getline  returns  NULL  on  error  or  EOF.  */ 
perror |argv[opcind] ) ; 
fprintf (stderr,  "Reaa  errorln") ; 
exit  (1) ; 


if  (fclose(infiie) )  ( 
perror (aravfoptind! ) ; 

fprintf (stderr,  "Error  ciosing  input  filelNn"); 
exit  (1) ; 

I 

!  while  (++optind  <  argc); 

/*  Done  with  input,  begin  output  phase.  */ 
if  ((outfiie  =  fopen (options. outfname,  "w"))  =-  NULL)  i 
perror (options. outfnamej  ; 

fprintf (stderr,  "Can't  create  output  fileNn"); 
exit  (1) ; 


/•  Select  and  write  the  pieces  of  the  generated  program.  */ 
if  ( fprintf (outfiie,  "Ns",  pgmincl)  <  0)  outerrl); 
wntelines (Sgloball,  outfiie);  /*  Write  giobal  lines.  */ 

if  1  fprintf (outfiie,  "Ns",  pgmhdr)  <  0)  outerrl);  /•  Main  program.  •/ 
wntelines  (Slocaii,  outfiie);  /*  Write  iocai  lines.  */ 

/*  Write  code  to  initialize  variables.  »/ 

if  ( fprintf  (outfiie,  pgmimt,  options  .ntimes)  <  0)  outerrl); 

/*  Write  code  to  time  execution  of  an  empty  expression.  • ' 
if  ( fprintf (outfiie,  "Ns",  pgmstart)  <  0)  outerrl); 

if  (options .ntimes  >  1)  :  Need  looping  code?  •• 

if  ( fprintf  (outfiie,  ”*s”,  pgmiccpi  •-  0)  outerru; 

eise  ■ 

.f  i fprintf (outfiie,  “Ns*,  pgmnoloop)  <  7)  outerrl); 
if  :  fprintf  (outfiie,  " 1  s  “ ,  pgr.empty)  <  3)  outerrl); 

•  Write  code  to  time  execution  of  statements.  •/ 
for  Hep  *  testl.heaa;  lep;  .ep  *  lep->next)  : 

if  ( fprintf  (outfiie,  "Ns",  pgmstart)  <  2)  outerru; 

-f  (options. ntimes  >  li  /•  Need  looping  coae? 

if  (fprintf  (outfiie,  "Ns",  pgmioopl  <  3)  outerrl); 

eise  • 

-f  (fprintf  (outfiie,  "«s",  pgmnoicopt  <  j)  outerrl); 

•  Here  is  wnere  tr.e  expression  is  written  into  the  program.  •  ' 
i:  ( fprintf  (outfiie,  "*s",  .eo->linei  <■  1)  outerrl); 

if  ' fprintf (outfiie,  "»s",  pgmstop)  <  ')  outerrl);  •  lutput  * 

if  'fprintf (outfiie,  “*s",  pgmena)  <  1)  outerru ;  •  Wrap  up.  • 

if  ( fclose (outf i le) )  tuterrli; 

if  I  opt  ions . compi »er  ’■  NCLLi 

/*  Compile  and  execute  test  program.  */ 
sprintf (cmdbuf , "Ns  Ns  Ns  Ns",  options. compiler->cmd, 
options .doopt  ?  options . compi ler->optimize  : 
options . outfname,  options . compiler->lib) ; 

if  (systemlcmdbuf) )  (  /*  MS-DOS  doesn't  return  error  codes.  */ 

fprintf (3tderr,  "Compilation  errorNn"); 
exit  (1) ; 

) 

•strchr (options. outfname,  '.')  -  'NO';  /*  Chop  off  ".exe"  •/ 

system (options. outfname) ; 

) 

return  0; 


/*  lladd  --  Add  a  new  line  to  the  tail  of  a  linked  list.  */ 
void 

lladdlstruct  Hist  “list,  char  *str)  ( 
struct  listel  *lep; 

/*  Create  a  new  list  structure.  •/ 

if  ( < iep  =  (struct  iistei  *)mailoc(sizeof (struct  listel)))  —  NULLi  ( 
fprintf  (stderr,  "Mot  enough,  memory \n")  ; 
exit  (1) ; 

I 

Iep->line  -  str;  /*  Add  the  line  to  it  " f 

lep->next  -  NULL;  /•  and  mark  it  as  the  tail.  •/ 

if  (list->tail  !-  NULL) 

list->tail->next  »  lep;  /*  Link  it  to  the  old  tail.  •/ 
iist->tail  =■  lep;  /•  Make  it  the  new  tail.  •/ 

if  (list->head  —  NULL) 

iist->head  -  lep;  /*  First  element  is  head.  */ 

return; 


/*  docmdline  --  Extract  options  from  command  line.  *.' 
void 


2521 
2531 
2541 
2551 
2561 
2571 
259! 
2591 
2601 
261 1 
2621 
2631 
264  l 
2651 
2661 
267! 
268  l 
2691 
2701 
2711 
2721 
2731 
274  1 
2751 
2761 


docmdline  lint  argc,  char  **argv,  struct  cmdoptns  *optptr)  i 
int  c,  i; 


enum  cctag  tag; 


while  ( (c  -=  getoptlargc,  argv,  "c:f:n:og"))  !-  EOF)  f 
switch(c)  ( 

case  's' :  /*  Select  compiler.  »/ 

tag  =  tolower ("optarg! ; 

for  (i  =0;  l  <  sizeof (compilers) /sizeof (compilers (0] ) ;  ♦♦i)  I 
if  (tag  --  compilers iij  .tag)  (  ,'*  Is  this  the  one?  */ 

optptr->compiler  ■  Scompilers (ij ; 
break; 

> 

I 

if  (i  >-  sizeof (compilers) /sizeof (compilers (0] ) )  f 
<*  Didn't  find  compiler.  */ 

fprintf (stderr,  "Unknown  compiler:  NsNn",  optarg) ; 
usage  ( ) ; 

) 

break; 

case  ' f ' :  /•  Name  of  generated  program  from  command  line.  */ 

if  (NULL  —  (optptr->outfname  =  malloc (strlen (optarg) +1) ) )  ( 
fprintf (stderr ,  "Not  enough  memoryNn") ; 
exit  (1) ; 


2781 

2791 

2801 

2811 

2821 

2831 

2841 

2851 

2861 

2871 

2881 

2891 

2901 

2911 

2921 

2931 

294  I 

295  l 
296; 
297i 
2981 
2  991 
3001 
30H 
3021 
3031 
3041 
3051 
3061 
3071 
3381 
3091 
3101 
311! 
3121 
3131 


J  1  5  I 
3161 
317i 
318! 
3191 

320 

321 

322 

323 

324 


strcpy (optptr->out£name,  optarg) ; 
break; 

case  'g' :  /•  Don't  compile.  •/ 

optptr->compiler  »  NULL; 
break; 

case  'n':  /*  Execute  statement  n  times.  */ 

optptr->ntimes  -  strtoi (optarg,  NULL,  0); 
break; 

case  'o':  /*  Use  optimizer  when  compiling  benchmark.  */ 

optptr->doopt  -  1; 
break; 

default : 

usage ( ) ; 


void 

•usage tvoia)  *  Print  help  message  and  exit.  • 

fprintf  (stderr.  "Usage:  soench  options  j  i  files  ...  ;\n" 

"  Available  options  are:'n" 

*  -c  x  Select  compiler:  x=a  Aztec,  x-d  Datalight, ,n" 
x-e  Ecosoft,  x«t  Turbo,  x-z  ZortechNn" 

“  -t  name  Write  generated  program  to  file  name.Nn" 

"  -n  xx  Execute  each  statement  xx  times. 'n* 

"  -o  Optimize  when  compiling  benchmark.  .,-." 

"  -g  Generate  test  Drogram  only;  ao  not  try  to  compile. \n") ; 

exit(l)  ; 


/•  wntelines  —  Output  all  lines  in  a  list.  • ' 
void 

writennes  (struct  iiist  "list,  FILE  ‘outfiie!  • 
struct  .istei  "lep; 

for  i  lep  -  List->head;  lep  !-  NULL;  lep  ■  lep->r.ext)  1 

if  ( fprintf  (outf  lie,  "^s‘n",  lep->lme)  <  3i  ojterrd; 

return; 

I 


/•  outerr  —  Display  a  message  and  aoort  following  an  output  error.  •/ 
void 

outerr (void)  ( 

perror (options. outfname) ; 

fprintf (stderr,  "Error  writing  output  file”); 
exit (1) ; 


End  Listing  One 


Listing  Two 


11  /*  getline. c  --  Sead  a  line  from  a  stream.  •/ 
2!  ^include  <stdio.h> 

3i  *include  <stdiib.h> 

4  1  finclude  <stnng.h> 


6l  tdefine  MEMINCR  256  .  *  Size  of  memory  block  used  for  (mire)alioc.  »/ 

71  /*  getline  —  Read  one  iine  from  file  infile  into  a  mailoc'ed  string. 

81  Lines  ending  with  \  are  combined  with  the  following  line. 

9 i  Return  NULL  on  error  or  EOF;  otherwise,  a  pointer  to  the  string.  */ 

10 1  char  * 

111  getiir.elFILE  "infile) 

12 i  ;  char  *p,  *q; 

13  >  uit  c; 

14  unsigned  avail; 


18! 
191 
201 
21 1 

23 1 
24; 
25! 
261 
271 
281 
291 
301 
311 
32! 
331 
341 
351 
361 
37| 


?  =  q  =  maiioci i unsigned) MEMINCR) ; 
avai*  =  MEMINCR  -  1; 
for  (;;)  > 

if  ( f c  =  aetc (infile) )  =■  EOF)  i 
*p  =  'NO'; 

if  (p  >  a)  return  q; 
else  return  NULL; 

if  ( ("p*+  -  c)  ' \n' )  ( 

if  (p  <«  q+1  ! !  p [-2 ’  !-  '\\')  { 

*p  -  'Non¬ 
return  q; 

i  /"else  Continued  line.  */ 

) 

if  (—avail  —  0)  ( 

/•  Need  more  memory.  */ 

*p  -  ' NO'  ; 

if  ( (q  =  realloclq,  (Size_t) (p-q  *  MEMINCR  +  1)))  =-  NULL) 
return  NULL; 
avail  -  MEMINCR; 

p  =  strchr (q,  ' ’ 3' l ;  /*  Find  end  of  string  in  case  it  moved.  *' 


391  ) 


End  Listing  Two 
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Listing  Three 


'*  getopt. c  --  "rux-like  ccmmano-i  me  option  parser.  •> 

21  ♦include  <staio.n> 

5:  ♦include  <scrmg.n> 

4  me  opt md;  •  Ir.aex  zz  .text  argument  m  arav".  * 

:■  mar  ‘optarg;  .  *  Pointer  to  option  argument.  •• 

*  getopt  —  Returns  option  .steers  one  at  a  time, 

3 1  EOF  wnen  r.o  more  options  remain,  and  ?  for  unknown  option. 

3 1  Cptstr  contains  legal  option  letters.  A  colon  following  a 

. 0 1  letter  indicates  tnat  option  requires  an  argument.  *' 

2;  getopt  lint  argc,  char  ‘argv;;,  o.-.ar  ‘optstrl 
.31  static  char  *cp; 

4  i  char  *p; 


651  •  *  Get  BIOS  tick  count  (reaa  3ICS  ram  directly  for  speed  and 

66l  to  avoid  turning  on  interrupts). 

67i  count  -  ‘(unsigned  long  far  ■ i MX_FP (BIOS_DS,  3_TIKP)  -  mitcount; 
681  mt_on();  *  Interrupts  back  cn. 

69 i  eimticks  *  iunsigned)-I  -  ( (nsb  <<  3)  Isb) ; 

■’0!  u3_cmp  -  count ‘usBTIK; 

71i  return  us_tmp  *  ( (long) tim_tiOKS*us_TTIK  *  us_t mp4 SCALE) /SCALE; 

721  ) 


End  Listing  Four 


Listing  Five 


3 


22: 
23! 
24  i 

261 
27| 
281 
291 
301 
311 
321 
331 
.14  1 
351 
361 
37| 
38| 
391 
401 
411 
421 


if (cptina  -»  j) 

:p  »  arqvf **optma;  -  1;  •  First  call.  • 

if  (•  argv ( opt mdj  :=  optir.a  >=  argc) 

return  EOF;  •  Vo  core  options.  * 

-‘optind; 

return  EOF;  •  —  mdicates  ena  of  options.  • 


i f  ( ( p  -  strchr  (optstr,  ‘cp—n  —  NULL) 
fputs ("unknown  option:  ",  jtoerr); 
putc ( * (cp-1) ,  stderri; 
putcl'Nn',  stderr) ; 
if(*cp  —  'NO') 

cp  -  argv[++optind)  +  1; 
return  ' ?' ; 

) 

if <*(p+l>  =-  ' :') 

{  if(*cp  --  'NO')  /*  Get  argument.  */ 

optarg  -  argv(++optind) ; 

else 


optarg  -  cp; 

cp  ■  argv(++optind|  +  1; 

) 

else  if ( *cp  —  ' NO' ) 

cp  -  argv(+-+optind]  +  1;  /*  Set  up  for  next  argv. 

return  *p; 


End  Listing  Three 


Listing  Four 


1|  /•  Test  data  for  statement  benchmark  generator. 
21  %% 

3 1  %f loat  f,  g  -  10.,  h  -  20.; 

4|  ^double  c,  d  -  10.,  e  -  20.; 

5 1  %int  i  =  10,  j,  *p,  *q; 

6 1  iint  array[50],  another(50! ; 

7 1  f  -  g+h;  /*  Float  addition.  */ 

31  c  -  d*e;  /*  Double  addition  */ 

9|  /•  Initialize  an  array  using  subscripting.  */N 
101  for  (i-0;  i  <  50;  ++i)N 
111  array (i)  -  0; 

121  /•  Initialize  an  array  using  pointer.  */N 
1 3 1  for  (p  -  array;  p  <  array  *  50;  **p) N 
14|  *p  -  0; 

151  /*  Copy  using  array  subscripts.  *'\ 

161  for  (i=0;  i  <  50;  *+i)N 

171  array[i)  -  another(i); 

18 1  /*  Copy  u3ing  pointers.  */N 

19 i  for  (p  =  array,  q-another;  p  <  array  *  50;  **p, 
201  *p++  =  •q+'t-; 

211  (a) 

221  Test  input 


241  Statement  1  required 
251  Statement  2  required 
26 1  Statement  3  required 
27 l  Statement  4  required 
281  Statement  5  required 
291  Statement  6  required 
301 
311 
321 

331  Statement  1  required 
341  Statement  2  required 
351  Statement  3  required 
36 |  Statement  4  required 
37i  Statement  5  required 
38|  Statement  6  required 
39; 


1215.0  microseconds 
560. C  microseconds 
1671.3  microseconds 
1606.0  microseconds 
1320 . C  microseconds 
1794.0  microseconds 
(b) 

Results 

2.0  microseconds 
1.0  microseconds 
813.0  microseconds 
SI 3.0  microseconds 
1112.0  microseconds 
777,0  microseconds 


to  execute, 
to  execute, 
to  execute, 
to  execute, 
to  execute, 
to  execute. 


to  execute, 
to  execute, 
to  execute, 
to  execute, 
to  execute, 
to  execute, 


1  iteration  timed. 
1  iteration  timed. 
1  iteration  timed. 
1  iteration  timed. 
1  iteration  timed. 
1  iteration  timed. 


1  iteration  timed. 
1  iteration  timed. 
1  iteration  timed. 
1  iteration  timed. 
1  iteration  timed. 
1  iteration  timed. 


40! 


Results  with  optimizer  on 


2 

3 


31 

91 

101 

121 
131 
14  | 
151 
161 
171 
181 
191 
201 
211 
22  I 
231 
24  1 
251 
261 
27  | 
281 
291 
30! 
311 
321 
331 
34  I 
351 
36) 
371 
381 
391 
401 
411 
42! 
431 
44  I 
451 
46! 
471 
48  i 
491 
501 
511 
52  1 
531 
54  I 
551 
561 
57  1 
581 
591 
601 
611 
62  l 

631 

641 


/*  clock. c  —  Microsecond  resolution  clock  routine.  •/ 
/*  Implements  in  C  the  timer  chip  tweaking  described  by  •/ 
/*  Byron  Sheppard,  _Byte_,  Jan  1987,  p  157-164.  */ 
/*  Replaces  standard  clock!)  from  the  library.  •/ 
/*  The  definition  of  CLKTCK  in  time.h  may  have  to  *' 
<•  be  changed  to  130000CL.  */ 
/*  Does  not  correctly  handle  intervals  spanning  *.' 
/*  midnight  or  intervals  greater  than  about  6  hours.  */ 
♦include  <time.h> 


Interrupt  handling  and  i/o  ports  are  compiler  dependent. 
The  following  set  of  preprocessor  directives  selects  the 
correct  include  files  and  macros  for  various  compilers. 


_ ZTC _ 

<dos.h> 

<int.h> 

inportb 

outportb 


♦lfder 
♦include 
♦include 
♦define 
♦define 
♦else 
fifdef 
♦include 
♦define 
♦define 
♦else 

♦error  Unknown  compiler 

♦endif 

♦endif 


_ TURBOC_ 

<dos.h> 
int  off 


disable 

enable 


/*  Constants  */ 

♦define  CCNTVAL  0x34  ==  0011C100  Control  byte  for  3253  timer.  */ 

Sets  timer  0  to  2-byte  read/write,  mode  2,  binary.  * 
♦define  TODATA  0x40  /*  Timer  0  data  port  address.  •/ 

♦define  TMODE  0x43  /*  Timer  mode  port  address.  •/ 

♦define  BIOS_DS  0x40  /*  BIOS  data  segment.  •/ 

♦define  B_TIKP  0x6c  /*  Address  of  BIOS  (18.2/s)  tick  count.  */ 

♦define  SCALE  10000  /*  Scale  factor  for  timer  ticks.  */ 

/*  The  following  values  assume  18.2  BIOS  ticks  per  second  resulting  from 
the  8253  being  clocked  at  1.19  MHz.  *' 

♦define  usBTIK  54925  /*  Microsec  per  BIOS  clock  tick.  */ 

♦define  f_BTIK  4595  /*  Fractional  part  of  microsec  per  BIOS  tick.  */ 

♦  define  us  TTIK  8381  /*  Microsec  Der  timer  tick  *  SCALE  (4/4.77  MHz)  . 


clock_t 
clock (void)  ( 

unsigned  char  msb,  Isb; 
unsigned  int  tim_ticks; 
static  int  init  *  0; 
unsiqnea  long  count,  uscmp; 
static  unsigned  long  init_count; 


if  (0  —  init)  i 

init  =  l;  .'*  This  is  the  first  call,  to  sec  up  timer.  *•' 
mt_off  0  ; 

outportb  (TMODE,  CONTVAL)  ;  *  Write  new  control  byte  to  timer.  *  ■' 

outportb  (TODATA,  0);  Initial  count  =  0  “  65636.  */ 

outportb (TODATA,  0); 

mit_count  -  ‘(unsigned  long  int  far  *)MK_FP (BIOS_DS.  B_TIKP) ; 
int_on ( ) ; 

return  0;  / *  First  call  returns  zero.  * / 


int_off();  Don't  want 

outDortb (TMODE,  0); 

Isb  -  inportb (TODATA) ; 
msb  =  inportb (TODATA) ; 


interrupt  while  getting  time. 

•  Latcn  count.  " 

•  Read  count .  * ' 


End  Listings 
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DEBUGGING  TSRs 


Listing  One  (Text  begins  on  page  67.) 


KEYSWAP  program 

By  Costas  Menico. 

Software  Bottling  Company 
6600  Long  Island  Expressway 
Maspeth,  N.Y.  11378 
718-458-3700 

This  program  will  swap  the  F8  &  F10  key  for  the  Up  and  Down 
arrow  keys . 

Demonstrator  program  for  debugging  memory  resident  program 
using  Turbo  Debugger. 


.model  small 


;  Set  key  values. 

;  For  the  SCAN  and  ASCII 
;  see  the  BIOS  manual 
f8key  equ  4200h  ; 

flOkey  equ  4400h 

upkey  equ  4800h  ; 

downkey  equ  5000h  ; 


codes  of  any  other  keys, 

define  the  F8  key 
define  the  F10  key 
define  the  up  arrow  key 
define  the  down  arrow  key 


DOSCALL  equ  <int  21h> 
LOADSEG  MACRO  segrl,  segr2 
push  segr2 
pop  segrl 
ENDM 


DOS  interrupt  call 
Load  segment  register 
macro . 


;  Publics  area 

public  start,  oldintl6,  intl6handler,  exit,  test_for_key 
public  load_tsr,  tsr_terminate,  chain_vector,  flOpressed 

;  Start  Code 
.code 

assume  cs:_text,  ds:_text,  es:_text,  ss: nothing 


Our  program  start 


org  lOOh  ;  COM  file  starting  program  address, 

start : 

jmp  load_tsr  ;  Load  our  program  resident. 

;  Data  area.  Since  this  is  COM  file  all  data 
;  and  code  are  in  the  Code  segment, 
evendata 

oldintl6  dd  0  ;  Area  for  old  interrupt  16h  vector, 

stackbot  dw  128  dup('?')  ;  Our  stack  bottom, 

stacktop  equ  $-2  ;  Our  stack  top. 


Entry  to  keyboard  handler. 

We  get  here  when  any  application  or  DOS 
executes  an  INT  16h. 

Input:  AH=0  -  Get  a  key 

Output:  The  key  in  AX 

Input:  AH=1  -  Check  for  key 

Ouput:  The  available  key  in  AX 

Input:  AH=2  -  Get  shift  flags 

Output:  The  shift  flags  in  AL 


intl6handler  proc  far 

pushf  ;  Save  flags  status, 

or  ah,  ah  ;  Are  we  getting  a  key? 

je  test_for_key  ;  Yes  -  goto  to  test  for  F10. 


popf  ;  No  -  pop  flags  and 

jmp  cs:oldintl6  ;  jump  to  old  interrupt  handler. 


;  Get  a  pressed  key  and  test  if  it  was 
;  and  F10 
test_for_key: 
popf 
pushf 

call  cs:oldintl6 


Pop  the  original  flags. 
Push  them  again 

and  simulate  INT  16h. 


pushf 

cmp  ax,  flOkey 
jne  is_it_f8 
flOpressed: 

mov  ax,  downkey 
jmp  short  exit 
is_it_f 8 : 

cmp  ax,  f8key 
jne  exit 
mov  ax,  upkey 

exit : 

popf 


Save  flags, 
is  this  an  F10  key? 
no  -  check  for  F8. 

yes  -  set  swap  key  in  ax. 


is  this  an  F8  key? 
no  -  exit 

yes  -  set  swap  key  in  ax. 
Pop  the  saved  flags. 


iret  ;  Return  to  caller  with  key  in  ax. 

intl6handler  endp 


IFDEF  DEBUG 

;  Assemble  this  section  to  debug  the  TSR  with  Turbo 
;  Debugger.  You  must  assemble  with  the  /DDEBUG  option, 
include  tsrdebug.asm 

END  IF 


Load  KEYSWAP,  and  terminate  but  stay  resident.  ; 

Once  KEYSWAP  is  loaded  all  code  from  here  on  is  discarded.  ; 


load_tsr : 

;  Set  SP  to  our  internal  stack  area 


cli  ;  Do* not  interrupt  while 

mov  sp,  offset  stacktop  ;  stack  pointer  is  being  adjusted. 

sti  ;  Now  interrupt. 

call  chain_vector  ;  Install  our  keyboard  interrupt. 

IFDEF  DEBUG 

;  Assemble  this  section  to  debug  the  TSR  with  Turbo 
;  Debugger.  You  must  assemble  with  the  /DDEBUG  option, 
call  tsr_simulate 

ELSE 

;  Assemble  this  section  to  run  without  the  debugging, 
call  tsr_terminate 

END  IF 


Save  old  interrupt  16  vector; 
and  point  it  to  our  handler  ; 


chain_vector  proc  uses  ax  bx  dx  es 

mov  ax,  351 6h  ;  Get  the  int  16h  keyboard  vector. 

DOSCALL 

mov  word  ptr  oldintl6,  bx;  Save  old  vector  in  our  data  area, 
mov  word  ptr  oldintl6[2],  es 

mov  ax,  251 6h  ;  Set  the  new  vector  of  our 

mov  dx,  offset  intl6handler;  interrupt  16h  keyboard  handler. 

DOSCALL 

ret 

chain_vector  endp 


Terminate  and  stay  resident  ; 


;  Get  offset  address  of  program 
;  code  to  discard. 

;  Convert  to  pargraphs. 

;  Round  off  to  the  next  paragraph. 

;  Terminate  &  stay  resident  function. 


@CurSeg  ends 
end  start 


tsr_terminate  proc 

mov  dx,  offset  load_tsr 
mov  cl,  4 
shr  dx,  cl 
inc  dx 

mov  ax,  3100h 
DOSCALL 

tsr_terminate  endp 


Listing  Two 


End  Listing  One 


Include  file  TSRDEBUG.ASM 

Assemble  this  code  if  you  will  debug  with  Turbo  ; 

Debugger  ;  You  must  assemble  with  the  /DDEBUG  option.  ; 


public  param, 

,  command 

_com 

public  tsr_simulate, 

unchain_vector,  int9handler 

BREAKPOINT 

equ  <int 

3>  ;  Debugger  break  point 

ctrlflag 

equ  4 

;  Ctrl  key  BIOS  indicator  flag. 

enterscan 

equ  28 

;  Scan  code  for  Enter  key. 

kbdf lags 

equ  417h 

;  BIOS  keyboard  flags  location 

;  Load  i  Execute  parameter  block  structure 
execparam  struc 

envstr_addr 

dw  0 

;  Environment  pointer 

cmdline_ofs 

dw  0 

;  Offset  to  command  line. 

cmdline_seg 

dw  0 

;  Segment  to  command  line. 

fcbl_ofs 

dw  0 

;  Offset  of  fcbl . 

fcbl_seg 

dw  0 

;  Segment  of  fcbl 

fcb2  ptr 

dw  0 

;  Offset  of  fcb2. 

fcb2_seg  dw  0 

execparam  ends 

;  Segment  of  fcb2. 

oldint9 

dd  0 

;  Area  for  old  int  9  vector. 

paramvals 

i 

A 

O 

offset  cmd  line, ?, offset  fcbl, ?, of fset 

Shows  below  how  the  data  above  is  initialized. 


comment  A 

o, 

; 

Use  current  environment 

offset 

cmd  line, ?  ; 

Point  to  command  line. 

offset 

fcbl,? 

; 

Offset  &  Seg 

of  fcbl. 

offset 

fcb2, ? 

'' 

Offset  &  Seg 

of  fcb2. 

param 

execparam  <paramvals> 

command_com 

db  ' c: 

\command. com' , 0 

cmd_line 

db  0, 

Odh 

;  Command 

line  is  null 

savess 

dw  0 

;  Save  SS 

here. 

savesp 

dw  0 

;  Save  SP 

here. 

fcbl 

db  16 

dup(0)  ;  Blank  area  for  FCB1 

f  cb2 

db  27 

dup(0)  ;  Blank  area  for  FCB2 

Int  9  handler.  Ctrl-Enter  key  check. 

Each  time  a  key  is  pressed  it  is  checked  if  the  Ctrl  &  Enter  key 
were  pressed  simultaneously.  If  they  were  then  we  interrupt 
Turbo  Debugger 


int9handler  proc  far 
pushf 
push  ax 
push  ds 
xor  ax,  ax 
mov  ds,  ax 


Save  the  flags 
Save  ax 
Save  dx 

Point  DS  to  segment  0 

(continued  on  page  106) 
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DEBUGGING  TSRs 

Listing  Two  (Listing  continued,  text  begins  on  page  67.) 

;  Is  the  Ctrl  key  pressed? 

test  byte  ptr  ds: 

[kbdflags],  ctrlflag 

je  exitint9 

;  No  -  call  old  int  9  &  exit. 

in  al,  60h 

;  Yes  -  get  the  scan  code  of  key. 

cmp  al,  enterscan 

;  Is  it  the  Enter  key? 

je  breakkey 

;  Yes  -  go  to  break  Turbo  Debug 

exitint9: 

;  No  -  call  old  int  9  &  exit 

pop  ds 

;  Pop  ds  &  ax  before  jump. 

pop  ax 

popf 

;  Pop  flags 

jmp  cs:oldint9 

;  Jump  to  the  old  int  9 

breakkey: 

pop  ds 

;  Pop  ds  6  ax  before  jump. 

pop  ax 

popf 

;  Pop  flags 

in  al,  61h 

;  Reset  the  keyboard  controller 

mov  ah,  al 

;  for  next  key. 

or  al,  80h 

out  61h,  al 

xchg  ah,  al 

out  61h,  al 

mov  al,  20h 

;  Enable  interrupts 

out  20h,  al 

BREAKPOINT 

;  Execute  our  break  point. 

;  Turbo  Debugger  STOPS  HERE!. 

;  To  find  out  what  the  program 

;  was  doing  press  F7  (Trace)  twice. 

iret 

int9handler  endp 

;  Simulate  Terminate  and  stay  resident  ; 

;  Frees  unecessary  memory  and  loads  &  executes  COMMAND.COM  ; 

tsr  simulate  proc 

;  Free  unused  memory. 

LOADS EG  ES,  CS 

;  Point  ES  to  our  segment. 

mov  bx,  offset  load  tsr  ;  Get  offset  address  of 

mov  cl,  4 

;  program  code  to  discard. 

shr  bx,  cl 

inc  bx 

;  round  off  to  the  next  paragraph 

mov  ah,  4ah 

;  Shrink  allocated  block  function 

DOSCALL 

;  call  DOS 

;  Save  stack  registers 

mov  savess,  ss 

;  Save  stack  segment . 

mov  savesp,  sp 

;  Save  stack  pointer. 

;  Chain  unto  int 

for  debugger  break  key. 

mov  ax,  3509h 

;  Get  the  int  9  keyboard  vector. 

DOSCALL 

mov  word  ptr  oldint9,  bx  ;  Save  old  vector  in  our  data  area. 

mov  word  ptr  oldint9[2],  es 

mov  ax,  2509h 

;  Set  the  new  vector  of  our 

mov  dx,  offset  int9handler;  interrupt  9  keyboard  handler. 

DOSCALL 

;  Load  and  execute 

COMMAND . COM 

LOADSEG  ES,  CS 

;  Point  ES  to  our  segment 

mov  dx,  offset  command  com;  Point  to  COMMAND.COM  file  path. 

mov  bx,  offset  param  ;  Get  address  of  param  block. 

mov  [bx] .cmdline  seg,  ds  ;  Get  segment  of  the  command  line. 

mov  [bx].fcbl  seg, 

ds  ;  Get  segment  of  fcbl 

mov  [bx].fcb2  seg, 

ds  ;  Get  segment  of  fcb2 

mov  ax,  4b00h 

DOSCALL 

;  Load  and  execute  COMMAND.COM. 

;  Upon  return  form 

load  and  execute,  all 

;  registers  are 

destroyed  and  the  necessary 

;  ones,  must  be 

recovered. 

cli 

;  Turn  interrupts  off. 

mov  ss,  cs : savess 

;  Recover  stack  segment. 

mov  sp,  cs: savesp 

;  Recover  stack  pointer. 

sti 

LOADSEG  DS,  CS 

;  Recover  data  segment 

;  Unchain  all  our 

handlers,  and  terminate  program. 

mov  ax,  2509h 

;  Unchain  our  int  9  vector  and 

Ids  dx,  oldint9 

;  put  original  in. 

DOSCALL 

call  unchain_vector  ;  Unchain  our  keyboard  handler 

mov  ax,  4c00h 

;  Terminate  program. 

DOSCALL 

tsr_simulate  endp 

;  Unchain  vectors  before  exiting  debugger  ; 

unchain  vector  proc  uses  ds  ax 

mov  ax,  251 6h  ; 

Unchain  our  vector  and  put 

Ids  dx,  oldintl6  ; 

original  in. 

DOSCALL 

ret 

unchain_vector  endp 

End  listings 
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COLUMNS 


PROGRAMMING  PARADIGMS 


In  picking  Stepstone’s  Objective  C  as 
a  key  element  in  the  NeXT  develop¬ 
ment  platform,  Jobs  and  company  made 
what  had  to  be  a  tough  choice.  It’s  the 
kind  of  choice  that  will  mean  more  as 
time  goes  on:  It’s  what  one  writer  calls 
a  wye. 

By  wyes,  novelist  John  Barth  means 
those  choice  points  in  people’s  lives, 
roads  taken  or  not,  that  lead  to  some¬ 
place  very  different  from  the  alternate 
routes.  The  letter  Y  is  used  as  a  meta¬ 
phor  for  significant  choice  points.  That’s 
what  this  column  is  about:  the  wyes  of 
object-oriented  programming.  Some  of 
these  represent  choices  among  prod¬ 
ucts,  some  are  just  bullets  on  feature 
lists,  and  none  is  as  widely  discussed 
as  it  should  be,  at  least  if  you  believe 
Chuck  Duff  of  The  Whitewater  Group. 

I  talked  with  Duff  and  Digitalk’s  Jim 
Anderson,  developers,  respectively,  of 
Actor  and  Smalltalk/V,  and  both  expo¬ 
nents  of  a  “pure”  approach  to  object- 
oriented  programming.  What  follows 
is  based  on  their  experiences  and  per¬ 
spectives  out  on  their  branches  of  the 
various  OOP  wyes.  It  is  not  an  objec¬ 
tive,  balanced  view  of  the  choices  a 
programmer  faces,  but  rather  a  look  at 
the  choices  two  programmers  made, 
and  how  they  came  to  make  them. 

Pure  vs  Hybrid  OOP 

NeXT  sidestepped  the  pure  object-ori¬ 
ented  approach  exemplified  by  Small¬ 
talk  and  Actor,  and  opted  for  a  hybrid 
approach  to  object-oriented  program¬ 
ming.  There  are  compelling  reasons 
for  taking  the  branch  NeXT  took,  as 
there  are  compelling  reasons  for  fol¬ 
lowing  the  purer  path.  (This  use  of  the 
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word  “pure”  is  intended  to  be  non- 
judgmental  and  relative.  Imagine  quotes 
around  the  word  wherever  it  appears.) 
But  the  paths  do  seem  to  be  divergent, 
and  the  choice  of  whether  to  build  on 
a  pure  object-oriented  model  or  to  em¬ 
ploy  object-oriented  extensions  to  a 
familiar  language  model  will  take  the 
chooser  to  radically  different  places. 


Tough  Choice 


“Where  Smalltalk  and  Actor  came  from 
is  one  world,  and  this  is  really  an  en¬ 
tirely  different  world,”  Duff  says. 

Although  NeXT  chose  Objective  C, 
it’s  another  C-based  object-oriented 
system  — C++  — that  is  getting  the  bulk 
of  the  attention  just  now.  And  although 
Bjame  Stroustrup  developed  C++  from 
Simula,  the  same  root  from  which  all 
object-oriented  languages  grew,  it  is  a 
fundamentally  different  approach  from 
the  Smalltalk  model  (as  is  Objective  C). 
Stroustrup  is  explicit  about  his  inten¬ 
tions  in  developing  C++,  and  they  in¬ 
clude  efficiency  and  compatibility  with 
C.  C++  is  an  extension  of  C,  and  as 
such  permits  programming  style  that 
is  more  procedural  than  object-oriented; 
it’s  this  mixing  of  metaphors,  more  than 
any  particular  missing  features,  that 
seems  to  disturb  the  purists. 

From  the  pure  object-oriented  pro¬ 
gramming  branch,  this  approach  of  ex¬ 
tending  C  in  an  object-oriented  direc¬ 
tion  looks  at  best  quaint  and  at  worst 
wrong-headed.  Anderson  expresses 
what  seems  like  genuine  puzzlement 
at  the  NeXT  decision,  and  Duff  clearly 
sees  C++  as  a  sell-out  of  the  paradigm, 
popular  only  because  of  AT&T  and  its 
visibility  in  the  public  domain.  “From 
my  point  of  view,”  Duff  says,  “it  really 
compromises  a  lot  of  the  benefits  of 
object-oriented  programming.” 

Jim  Anderson  agrees.  He  sees  one 
of  the  main  benefits  of  object-oriented 
programming  is  that  the  solution  is  close 
to  the  problem.  “You  don’t  lose  sight 
of  your  problem  in  the  solution;  in  fact, 
you  develop  an  increased  understand¬ 
ing  in  the  system  you  create.”  That 
benefit,  he  thinks,  requires  an  unadul¬ 
terated  paradigm.  Of  Digitalk’s  customer 
base,  he  says,  “We  know  that  the  non¬ 
professional  programmer,  the  scientist, 


the  doctor  is  a  common  customer.  Pro¬ 
gramming  isn’t  his  job;  he  needs  results 
quickly,  and  (appreciates)  the  solution 
being  close  to  the  problem,  which  I 
think  Smalltalk  gives  you.  But  we’re 
also  getting  a  lot  of  programmers,  be¬ 
cause  they’re  getting  bloody  noses  with 
C  or  even  with  C++.” 

Duff  and  Anderson,  of  course,  have 
axes  to  grind:  They  are  selling  products 
that  lie  on  the  other  arm  of  the  wye. 
But  unlike  most  programmers,  Duff  has 
been  down  both  branches.  When  he 
talks  about  C++,  he’s  seeing  it  in  the 
light  of  Neon.  As  he  tells  the  story: 

“My  initial  focus  was  on  Forth. 
(When)  I  was  at  Kriya  Systems,  I  was 
the  author  of  Typing  Tutor,  and  I  had 
to  write  Typing  Tutor  for  the  Macin¬ 
tosh.  Forth,  as  an  extensible  language, 
was  not  really  working,  in  my  view, 
because  the  extensibility  was  just  too 
powerful.  I  was  intrigued  by  the  Small¬ 
talk  books,  and  that  seemed  to  repre¬ 
sent  a  situation  in  which  you  could 
channel  the  extensibility  into  a  more 
pragmatic  framework.  If  you  extended 
the  system  (and  I  extended)  the  sys¬ 
tem,  we  could  probably  understand 
each  other’s  extensions,  because  there 
was  this  consistent  technology  for  do¬ 
ing  it.” 

His  researches  into  object-oriented 
programming  and  his  background  in 
Forth  led  to  Neon:  “Neon  was  an  object- 
oriented  extension  to  Forth,  but  it  was 
a  hybrid  language  in  that  you  still  had 
Forth  around  and  you  could  still  blow 
yourself  out  of  the  water  any  time  you 
wanted  to  and  completely  corrupt  the 
object  metaphor.  My  focus  in  Neon 
was  on  making  Smalltalk  practical,  be¬ 
cause  at  that  time  there  was  no  Small¬ 
talk  that  was  really  useful  on  a  personal 
computer;  in  fact  I  think  Neon  was  the 
first  object-oriented  language  that  was 
commercially  available  for  a  personal 
computer.” 

Neon,  however,  failed  to  take  the 
world  by  storm,  and  Duff  himself  had 
some  second  thoughts  about  the  ap¬ 
proach.  After  the  Neon  experience,  he 
was  convinced  that  a  pure  object-ori¬ 
ented  model  was  better,  if  it  could  be 
achieved  without  compromising  effi¬ 
ciency.  In  the  hybrid  approach,  he  saw 
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too  many  ways  for  the  base  language 
to  collide  with  the  object  model.  It  was 
appealing  to  envision  a  language  in 
which  even  the  basic  syntactical  con¬ 
structs  would  be  constructed  accord¬ 
ing  to  the  messaging  paradigm.  That 
appeal,  and  some  frustration  with  Small¬ 
talk  as  it  existed  then,  led  Duff  to  de¬ 
velop  Actor. 

Today,  there  are  several  pure  object- 
oriented  languages  available  on  per¬ 
sonal  computers  but  surprisingly  little 
direct  comparison  of  these  products 
with  one  another  or  with  the  hybrids. 
Although  an  advertisement  for  Interac¬ 
tive  Software  Engineering’s  pure  object- 
oriented  programming  language  Eiffel 
does  a  feature-list  comparison  with  C++, 
you  won’t  find  many  comparative  re¬ 
views.  (That  ad  also  adds  insult  to  in¬ 
jury  by  quoting  Stroustrup  repeatedly 
on  object-oriented  features  that  C++ 
lacks.)  Duff  thinks  that  the  reason  we 
don’t  see  much  direct  comparison  of 
the  hybrid  vs  the  pure  implementations 
is  that  the  two  approaches  are  seen  as 
incommensurable:  “Right  now,  it’s  just 
sort  of  parallel  evolutionary  paths.” 

“C++  has  an  immense  amount  of 
support,  but  a  lot  of  it  is  (from)  C 
programmers,  to  (whom)  it’s  just  a  bet¬ 
ter  C.  They  don’t  have  anything  to  com¬ 
pare  it  to.”  Some  C  vendors  pitch  C++ 
as  precisely  a  better  C,  scarcely  men¬ 
tioning  its  object-oriented  nature  in  their 
ads. 

Duff  wants  to  see  the  hard  questions 
asked  in  print.  “Eventually  what’s  go¬ 
ing  to  have  to  happen  is  that  we’re 
going  to  have  to  say,  ‘What  is  this  tech¬ 
nology  about?  What  are  the  benefits 
that  we’re  looking  for?  And  what  lan¬ 
guage  features  have  to  be  there  to  pro¬ 
vide  those  benefits?’  We  have  to  look 
behind  the  scenes,  and  that’s  not  hap¬ 
pening  right  now.  We’re  going  to  have 
to  take  a  hard  look  at  what  we  want  the 
technology  to  do  for  us,  what  compro¬ 
mises  we’re  willing  to  make  in  the  lan¬ 
guage  to  accomplish  that.” 

Inheritance  vs 
Flat  Programming 

The  key  to  the  object-oriented  para¬ 
digm  is  inheritance.  It’s  what  delivers 
the  benefits,  and  it’s  the  essence  of  the 
choice  to  OOP  or  not  to  OOP,  Duff 
believes.  Anderson  sees  reusability  as 
its  greatest  benefit:  It  buys  the  pro¬ 
grammer  reusability  by  factoring  out 
the  general,  the  abstractions,  and  let¬ 
ting  general  solutions  be  specialized. 

It  was  precisely  the  quest  for  reus¬ 
ability  that  initially  turned  Anderson 
on  to  object-oriented  programming.  If 
Duff  found  his  path  only  after  follow¬ 
ing  a  Forth  thread,  Anderson’s  enlight¬ 
enment  came  from  watching  the  world’s 
biggest  software  company  fail  and  real¬ 


izing  that  he  knew  where  it  had  gone 
wrong. 

Anderson  was  working  for  Computer 
Science  Corp.  when  it  got  a  contract 
with  Basic  4  Corp.  Basic  4  was  selling 
a  business  minicomputer  with  a  very 
good  Business  Basic  and  getting  a  lot 
of  similar  jobs:  to  do  an  accounting 
system  for  a  bakery,  to  do  an  account¬ 
ing  system  for  a  trucking  company, 
and  so  on.  Basic  4  had  tried  contracting 
the  development  out  to  individual  con¬ 
sultants  but  wasn’t  happy  with  the  re¬ 
sult,  when  they  hit  upon  the  idea  of 
contracting  with  CSC  to  do  a  general 
accounting  system  that  could  be 
tweaked  for  the  particular  applications. 

CSC  found  itself  unable  to  reuse  the 
software  in  going  from  job  to  job.  “It 
was  just  too  much  of  a  mess  to  snip 
out  the  pieces,  the  common  stuff  that 
could  be  used  for  all.”  As  it  was  be¬ 
coming  clear  that  the  project  was  not 
working  out,  Jim  Anderson,  working 
in  another  branch  of  CSC,  was  reading 
the  1981  Byte  issue  on  Smalltalk  and 
making  connections. 

“That  was  one  of  the  things  that  I 
saw  in  Smalltalk:  the  reusability  be¬ 
cause  of  inheritance.  Basic  doesn’t  have 
much  structure.  What  you  need  is  to 
look  at  the  similarities  and  the  differ¬ 
ences.  The  similarities  are  the  abstrac¬ 
tions,  and  the  general  things  that  apply 
to  all,  and  the  differences  are  the  spe¬ 
cializations  in  subclasses.  Basic  just 
doesn’t  give  any  help  in  that  area.” 

CSC’s  problem  in  creating  a  general¬ 
ized  accounting  system  ultimately  led 
Anderson  and  George  Bosworth  to  start 
Digitalk  and  to  develop  a  Smalltalk  im¬ 
plementation  for  the  PC  and  now  for 
the  Mac.  “I  haven’t  been  able  to  go 
back  and  solve  that  problem,  but  I  can 
certainly  envision  having  multiple  ap¬ 
plications  in  Smalltalk:  abstract  accounts 
receivable,  then  Trucker’s  accounts  re¬ 
ceivable,  and  so  on,  all  in  there  at  once.” 

Duff  points  to  the  granularity  of  re¬ 
usable  code  that  inheritance  provides. 
“You  can  isolate  a  smaller  section  of 
code  that  is  more  likely  to  be  reusable 
as  a  unit  than  if  it  were  five  or  ten  times 
its  size.  As  size  increases,  the  likeli¬ 
hood  of  reusability  goes  down,  because 
the  more  functionality  there  is,  the  more 
likely  it  is  that  it’ll  be  inconsistent  with 
future  uses.” 

In  fact,  Duff  finds  that  the  object- 
oriented  style  seems  naturally  to  lead 
programmers  to  break  functionality 
down  into  small  pieces.  That’s  a  value 
that  rings  true  for  Duff,  an  old  Forth 
coder.  One  of  Chuck  Moore’s  rules  of 
Forth  programming  is  that  no  Forth 
word  should  be  longer  than  two  or 
three  lines.  “In  a  sense  I’ve  found  the 
same  thing  to  be  true  in  Actor:  that 
short  methods  and  short  classes  and  a 


larger  number  of  smaller  classes  is  usu¬ 
ally  a  better  situation  because  it  gives 
you  that  granularity  where  you  can  pick 
and  choose  what  you  want  to  reuse.” 

But  inheritance  supplies  a  level  of 
quality  or  reliability  to  the  reusable  code 
that,  Duff  argues,  would  not  be  there 
otherwise.  “If  I  develop  a  library  and  I 
give  it  to  you  and  you  need  it  to  work 
a  little  bit  differently,  you  start  to  edit 
my  code.  There  is  a  portion  that  we 
share,  but  it’s  no  longer  cleanly  deline¬ 
ated  from  what  I  initially  wrote.  This 
means  that  we  now  have  two  separate 
maintenance  problems.  I  can  no  longer 
simply  give  you  a  bugfix  for  you  to 
blindly  apply  to  your  code,  because 
you  might  have  changed  it.  That  prob¬ 
lem  is  made  much  less  severe  by  in¬ 
heritance,  because  we  can  agree  that 
you  don’t  edit  my  code;  you  override 
pieces  of  it.  Then  I  can  give  you  up¬ 
dates  and  it’s  not  going  to  compromise 
your  system.” 

Inheritance  is  also  what  makes  object- 
oriented  programming  hard  for  many 
programmers  to  adapt  to.  Novices  seem 
to  have  less  trouble,  suggesting  that  it’s 
an  unlearning,  rather  than  a  learning 
problem.  At  Carlton  University  in  Ot- 
towa,  they  now  use  Smalltalk  in  the 
Introduction  to  Programming  course 
in  the  computer  science  department. 
They’ve  progressed:  A  few  years  ago  it 
was  being  used  only  in  a  graduate  AI 
course,  and  last  year  it  was  introduced 
in  a  second-year  data  structures  class. 
But  there  is,  as  Anderson  puts  it,  “defi¬ 
nitely  a  weirdness  factor.” 

“One  of  my  problems  in  learning 
Smalltalk,”  he  confesses,  “was  that  I 
wanted  to  translate  it  into  something 
familiar.  I  was  constantly  fighting  the 
ideas.  Nonprogrammers  don’t  have  to 
make  this  kind  of  translation  all  the 
time,  so  I  think  they  accept  it  more 
quickly.” 

And  the  weirdness  factor  hits  imme¬ 
diately,  as  you  are  approaching  the 
problem,  conceptualizing,  analyzing, 
not  thinking  about  code  yet.  Anderson 
again:  “I  can  remember  programming 
in  Pascal,  approaching  a  problem,  and 
the  first  thought  would  be:  ‘OK,  what 
kind  of  record  structures  do  I  need  to 
define  for  this  problem?’  It’s  startling 
to  go  into  Smalltalk  and  approach  a 
new  problem  and  the  question  is,  ‘OK, 
what  kind  of  (preexisting)  collections 
do  I  use  for  this  problem?’  You  don’t 
start  by  defining  something  new  but 
by  reusing  something  that  exists.” 

Multiple  Inheritance  vs 
Single  Inheritance 

Multiple  inheritance  means  the  possi¬ 
bility  of  belonging  to  two  different 
classes  at  once,  neither  of  which  is  a 
subclass  of  the  other.  It’s  a  deviation 
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from  a  strict  tree-structured  arrange¬ 
ment  of  classes,  such  as  the  Linnean 
classification  of  organisms.  In  the  real 
world,  objects  belong  to  different 
classes.  Some  object-oriented  systems 
have  multiple  inheritance,  most  don’t. 

Neither  The  Whitewater  Group’s  Ac¬ 
tor  nor  Digitalk’s  Smalltalk  supports  mul¬ 
tiple  inheritance,  but  both  companies 
are  looking  into  the  technique.  When 
a  customer  asks  about  multiple  inheri¬ 
tance,  the  companies  ask  what  the  cus¬ 
tomer  has  in  mind  to  do  with  it. 

Duff  says  that  the  customers  usually 
haven’t  thought  about  it  very  much. 
“It’s  a  bullet  on  a  features  list,”  he  says. 


Inheritance  is  also  what 
makes  object-oriented 
programming  hard  for 
many  programmers  to 
adapt  to.  Novices  seem 
to  have  less  trouble, 
suggesting  that  it’s  an 
unlearning,  rather  than 
a  learning  problem 


“The  people  who  have  thought  about 
it  know  it’s  fraught  with  pitfalls.” 

What  are  these  pitfalls  of  multiple 
inheritance?  Well,  it’s  naive  to  think 
that  you  can  combine  an  A  and  a  B  to 
come  up  with  a  meaningful  AB.  A  and 
B  typically  will  have  similar  but  not 
quite  identical  properties  that  collide 
with  each  other.  Consider  the  case  of 
two  multiply  inherited  classes  with  in¬ 
stance  variables  having  the  same  name. 
Each  may  want  to  preserve  its  own 
copy  of  that  instance  variable,  or  they 
may  want  to  share  it.  There  are  equally 
valid  cases  of  each  kind.  When  faced 
with  these  collisions,  you  have  to  de¬ 
cide  what  to  do  about  them;  specifi¬ 
cally,  you  have  to  establish  a  collisions- 
resolving  philosophy.  Do  you  just  em¬ 
ploy  an  arbitrary  rule?  That  really  isn’t 
good  enough.  Do  you  ask  the  pro¬ 
grammer  on  a  case-by-case  basis  to 
make  the  resolution?  Do  you  develop 
a  collision-resolving  expert  system?  It’s 
not  a  simple  matter. 

“It’s  things  like  this  that  have  kept 
us  from  approaching  multiple  inheri¬ 
tance  until  just  recently,”  Duff  says. 
Anderson  can  think  immediately  of  one 
instance  in  the  design  of  his  Smalltalk 
system  when  multiple  inheritance  would 
have  come  in  handy.  “It’s  nice  to  have 


a  lot  of  things  (that  are  not  descendants 
of  the  stream  class)  that  act  like  streams.” 
He  managed  to  get  the  effect  of  multi¬ 
ple  inheritance  without  the  structure, 
but  “if  we  had  had  multiple  inheritance 
we  would  have  used  it  there.”  But  would 
the  costs  in  complexity  that  multiple 
inheritance  brings  with  it  have  justified 
the  convenience  that  would  have  been 
gained  in  this  case?  Anderson  doubts  it. 

Duff  says  you  have  to  weigh  these 
costs  in  designing  a  language.  “You 
have  to  say,  ‘Is  the  productivity  benefit 
there?  Are  they  spending  more  time  in 
the  multiple  inheritance  technology  than 
they  would  have  just  getting  around  it 
with  single  inheritance?”’  The  White- 
dddwater  Group  regularly  teaches  pro¬ 
grammers  how  to  simulate  multiple 
inheritance  in  a  single  inheritance  sys¬ 
tem.  In  a  single  inheritance  environ¬ 
ment,  you  can  achieve  multiple  inheri¬ 
tance  by  adding  the  classes  that  you 
want  to  inherit  from  as  components  or 
instance  variables  and  then  using  those 
components  of  the  object  as  sort  of  ex¬ 
perts  to  fill  in  that  domain  of  behavior. 
Then  you  just  pass  through  the  protocol 
of  those  objects  to  the  outside  by  intro¬ 
ducing  methods  in  the  class.  It  works. 

The  approach  suggests  a  broad  de¬ 
sign  principle  for  object-oriented  pro¬ 
gramming,  and  it  applies  particularly 
strongly  to  multiple  inheritance.  Duff 
says  that  his  people  have  found  that  it’s 
possible  to  overuse  inheritance.  “In  gen¬ 
eral,  it’s  better  to  err  in  the  direction  of 
encapsulating  too  much,  in  other  words 
including  something  as  an  instance  vari¬ 
able  instead  of  inheriting  from  it,  be¬ 
cause  it’s  very  likely  that  you  might 
inherit  inappropriate  behavior.” 

Inherit  inappropriate  behavior?  Here’s 
what  he  has  in  mind:  “You  want  to 
create  something  that  holds  a  collec¬ 
tion  of  other  things,  let’s  say  a  picture 
class  that  holds  a  collection  of  graphi¬ 
cal  objects.  One  way  to  do  that  is  to 
make  it  a  descendant  of  one  of  the 
collection  classes,  like  Array.  A  picture 
is  an  array,  only  it’s  a  special  kind  of 
array.  The  problem  is,  you  may  want  a 
picture  that  can  have  a  dictionary  in¬ 
stead  of  an  array  as  its  collection.  Also, 
there  are  many  things  that  are  appro¬ 
priate  for  arrays  that  are  not  appropri¬ 
ate  for  pictures.  You  end  up  having  to 
circumvent  a  lot  of  inappropriate  in¬ 
herited  behavior.” 

Multiple  inheritance  exacerbates  the 
problem  because  with  multiple  inheri¬ 
tance  you  have  not  just  one  but  many 
classes  from  which  you  need  to  filter 
out  inappropriate  behavior,  in  addition 
to  resolving  the  redundancies.  But  Ac¬ 
tor  is  likely  to  support  multiple  inheri¬ 
tance  before  long. 

“The  direction  that  I’m  heading,”  Duff 
explains,  “is  decoupling  inheritance  of 


protocol  — or  methods  — from  inheri¬ 
tance  of  representation — or  instance 
variables.  One  way  to  do  that  is  to  be 
able  to  group  a  piece  of  code  into  a 
thing  that’s  like  a  class,  except  that  it 
doesn’t  specify  any  representation.  It’s 
just  a  set  of  methods  that,  since  they 
don’t  refer  to  instance  variables,  can 
be  generically  inherited.  You  can  then 
say,  in  addition  to  the  class  that  I  in¬ 
herit  from,  I  also  inherit  these  proto¬ 
cols  that  allow  me  to  behave  like  an 
object  of  this  virtual  type  — virtual  (in 
that)  you’re  not  specifying  anything 
about  its  representation.  It  simplifies  a 
lot  of  these  resolution  problems.  You 
don’t  have  to  worry  about  instance  vari¬ 
ables;  you  can  just  deal  at  the  level  of 
what  functionality  I  inherit.” 

And  it’s  really  not  accurate  for  me  to 
say  that  Digitalk  doesn’t  support  multi¬ 
ple  inheritance;  it’s  there  in  the  com¬ 
pany’s  Smalltalk  products.  It’s  just  not 
visible.  “In  ST/VB-286  and  the  Mac  prod¬ 
uct,”  Anderson  says,  “we  have  actually 
implemented  the  mechanism  for  multi¬ 
ple  inheritance,  but  we  don’t  have  a 
(supporting)  user  interface.  We  don’t 
know  how  to  present  it  to  the  user.” 
The  user  interface  is  an  area  of  active 
research  at  Digitalk,  and  Anderson  feels 
that  the  company  was  really  founded 
to  make  object-oriented  programming 
accessible.  Accessibility  means  a  lucid 
user  interface,  he  believes.  If  and  when 
they  figure  out  how  to  present  the  tech¬ 
nique  so  that  it  doesn’t  complicate  the 
programmer’s  life  too  much,  they  will 
no  doubt  implement  multiple  inheri¬ 
tance  for  real.  If  and  when  they  do,  the 
solution  is  likely  to  involve  context,  a 
concept  that  Digitalk  programmers  are 
currently  exploring  avidly. 

From  the  point  of  view  of  putting 
valuable  functionality  in  the  program¬ 
mer’s  hands,  it’s  good  that  Digitalk  and 
The  Whitewater  Group  are  moving  to¬ 
ward  multiple  inheritance,  because  there 
are  real  benefits  in  having  multiple  in¬ 
heritance:  The  real  world  has  multiple 
inheritance,  and  if  you  want  to  simu¬ 
late  aspects  of  the  real  world,  should 
you  try  to  get  along  without  this  natural 
technique?  On  the  other  hand,  the  pro¬ 
grammer  has  to  decide  if  it  is  worth  the 
hassle.  It’s  really  not  a  trivial  choice  for 
the  language  designer  or  for  the  pro¬ 
grammer. 

As  Jim  Anderson  says,  “It’s  definitely 
a  controversial  topic.” 
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COLUMNS 


C  PROGRAMMING 


TINYCOMM:  The  Tiny  Communications  Program 


This  month’s  column  is  about  asyn¬ 
chronous  serial  communication  and 
how  it  fits  into  the  “C  Programming” 
column  project.  We  will  develop  the 
first  of  a  series  of  tools  designed  to 
connect  one  computer  to  another  with 
modems  and  the  telephone  system.  To 
illustrate  these  tools,  we  will  build  TI¬ 
NYCOMM,  a  tiny  communications  pro¬ 
gram  with  the  ability  to  originate  or 
answer  calls  with  another  computer, 
converse  interactively  with  the  keyboard 
and  screen,  capture  messages  to  a  disk 
log  file,  and  upload  message  files. 

Just  as  December’s  TWRP,  the  Tiny 
Word  Processor,  is  no  competition  for 
the  high-end  word  processors,  TI¬ 
NYCOMM  is  no  threat  to  Smartcom, 
Procomm,  or  Qmodem.  Our  “C  Pro¬ 
gramming”  column  project  is  slowly 
gathering  a  collection  of  small  but  use¬ 
ful  tools  that  we  will  eventually  inte¬ 
grate  into  a  program  targeted  to  a  spe¬ 
cific  purpose.  In  the  meantime  we  can 
learn  from  these  small  examples,  see¬ 
ing  how  the  C  language  is  applied  in 
building  such  applications. 

You  do  not  need  an  in-depth  under¬ 
standing  of  serial  input/output  and  mo¬ 
dems  to  use  this  month’s  code,  but  it 
could  help  you.  I  recommend  Master¬ 
ing  Serial  Communications  by  Peter 
W.  Gofton,  1986,  Sybex  Inc.  The  book 
belabors  the  complexity  of  serial  I/O, 
and  that  is  a  genuine  concern.  You  will 
leam  here,  however,  that  the  basic  steps 
for  making  a  modem  connection  to  a 
remote  computer  involve  a  minimum 
of  C  code. 


Al  Stevens 


Communications 

When  humans  converse,  we  use  chan¬ 
nels  of  communication  appropriate  to 
the  conversations  and  our  proximity 
to  one  another.  The  most  common  chan¬ 
nel  is  the  spoken  word  issued  within 
earshot  of  the  participants.  Less  com¬ 
mon  are  fortune  cookies,  convicts  clank¬ 
ing  on  water  pipes,  and  bottled  mes¬ 


sages  floating  in  the  ocean,  but  what¬ 
ever  the  medium  and  the  message,  some 
are  better  suited  than  others. 

People  can  choose  convenient  me¬ 
dia  as  time  and  opportunity  permits, 
but  when  computers  converse,  the  me¬ 
dium  must  be  exactly  matched  to  the 
message.  A  participant  in  an  electronic 
conversation  must  use  a  medium 
known,  agreeable,  and  available  to  the 
other  participants. 

Therefore,  if  you  want  to  send  a 
message  to  your  mother  and  she  has  a 
computer,  modem,  and  communica¬ 
tions  software,  your  computer  can  call 
her  computer.  If  hers  can  answer  the 
phone  and  receive  the  message,  she 
will  eventually  get  to  read  it.  That  may 
or  may  not  require  the  participation  of 
one  or  both  of  you  at  the  time  of  the 
transmission.  She’d  probably  prefer  a 
call. 

The  Communicating  Hardware 

Programs  that  communicate  with  re¬ 
mote  computers  must  manage  two  lay¬ 
ers  of  hardware:  the  modem  and  the 
serial  port.  The  local  modem  translates 
the  local  program’s  data  into  tones  that 
are  sent  across  telephone  lines  to  the 
remote  modem.  The  local  modem  then 
receives  the  remote  modem’s  tones  and 
translates  them  into  data.  The  com¬ 
puter  sends  and  receives  data  values 
to  and  from  the  modem  through  the 
serial  port.  Management  of  this  com¬ 
munication  requires  functions  for  the 
serial  port  and  the  modem.  Which  way 
you  select  to  do  this  depends  on  the 
hardware  itself.  We  will  use  the  IBM 
PC  serial  ports  and  Hayes-compatible 
modems. 


The  Asynchronous  Serial  Port 

A  serial  port  is  a  bit  stream  device  that 
is  used  in  applications  where  eight  data 
lines  are  not  available  and/or  the  dis¬ 
tances  between  devices  preclude  the 
use  of  the  lower  signal  strengths  of  the 
computer. 

The  asynchronous  serial  port  adds  a 
start  bit  and  one  or  two  stop  bits  to 
each  byte.  There  may  be  a  parity  bit 
that  may  use  odd  or  even  parity.  A  byte 
may  consist  of  from  five  to  eight  data 
bits.  The  transmission  speed  is  ex¬ 
pressed  in  bits  per  second  and  is  called 
the  “baud  rate.”  Senders  and  receivers 
of  asynchronous  serial  messages  must 
agree  on  the  number  of  data  bits;  the 
number  of  stop  bits;  whether  odd,  even, 
or  no  parity  exists;  and  the  baud  rate 
of  the  transmission. 

The  IBM  PC  can  have  one  or  two 
serial  ports.  A  program  can  communi¬ 
cate  with  one  of  these  serial  ports  by 
reading  and  writing  the  port  registers 
directly,  by  calling  the  serial  I/O  ROM 
BIOS  functions,  or  by  using  DOS.  Each 
approach  has  advantages  and  disadvan¬ 
tages.  The  book  mentioned  earlier  ex¬ 
plains  these  trade-offs;  space  prevents 
me  from  offering  you  the  comprehen¬ 
sive  treatment  the  subject  requires.  For 
our  purposes,  you  may  assume  that  I 
have  weighed  the  benefits  and  made 
the  best  selection  for  the  examples  at 
hand.  We  will  use  direct  port  address¬ 
ing  and  an  interrupt  service  routine  for 
the  receiver  side  of  the  serial  transmis¬ 
sions. 

These  functions  employ  an  XON, 
XOFF  protocol  where  the  receiving  com¬ 
puter  effectively  turns  the  sender’s  trans¬ 
missions  on  and  off.  When  its  input 
buffer  gets  nearly  full,  the  receiver  sends 
the  XOFF  character  to  the  sender.  The 
sender  suspends  transmitting  until  the 
receiver  sends  the  XON  character.  The 
receiver  watches  its  buffer  as  charac¬ 
ters  are  removed  and  sends  the  XOFF 
when  the  level  is  below  the  safety 
margin. 

File  transfer  protocols  such  as 
XModem  and  Kermit  use  their  own 
packet  management  techniques  to  han- 
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C  PROGRAMMING  |  available  signal  set  to  generate  inter-  |  seconds.  Any  program  that  will  use  the 

(continued  from  page  115)  rupts.  The  8259  programmable  inter-  functions  in  serial. c  must  first  call  inter- 

rupt  controller  is  written  to  allow  the  ceptjtimer  to  attach  to  the  timer  inter- 

dle  such  delays.  XModem  can  be  a  proper  IRQ  line  to  cause  an  interrupt,  rupt  vector.  Before  returning  to  DOS, 

problem  in  networks  because  the  Then  the  interrupt  controller  is  reset  the  program  must  call  restore Jimerlo 

XModem  protocol  specification  includes  and  all  UART  input  registers  read  to  reset  the  vector.  If  you  use  the  modem 

fixed  timeout  periods  that  can  be  ex-  clear  any  stray  interrupts  that  might  be  functions  in  modem. c  you  do  not  need 

ceeded  by  latent  delays  introduced  by  hanging  around.  to  make  these  calls,  because  the  mo- 

the  network.  The  local  communications  The  restore_serialint  function  in  se-  dem  functions  do  it  for  you. 

software  must  know  when  one  of  these  rial. c  should  be  called  at  the  end  of  a  serial. h  has  two  macros  named 

protocols  is  in  use,  because  they  are  program  that  has  used  serial  input/  set_timer  and  timed_out  that  operate 

often  used  to  transmit  binary  files  —  output.  This  function  returns  the  serial  the  timer.  The  first  macro  sets  a  timer 

files  that  might  have  the  XON  or  XOFF  interrupt  vector  to  its  original  value.  value  in  seconds.  The  second  macro 

characters  as  valid  data  bytes.  During  The  clear_serial_queue  function  re-  returns  a  true  value  if  the  most  recent 

these  transmissions,  the  XON/XOFF  pro-  sets  the  serial  receiver’s  circular  buffer  setting  has  elapsed.  set_timer  puts  a 

tocol  is  disabled.  to  an  empty  condition.  This  function  value  into  the  rtc&ervariable.  The  value 

Listing  One,  page  138,  is  serial. h.  is  used  by  the  modem  manager  to  get  in  ticker  is  approximately  18.2  times 

This  header  file  declares  the  prototypes  rid  of  any  unneeded  text  condition  re-  the  number  of  seconds  to  count;  the 

and  macros  for  the  serial  port  func-  sponses  from  the  modem.  timer  interrupt  occurs  18.2  times  per 

tions.  It  also  defines  status  register  sig-  The  interrupt  service  routine  new-  second.  The  newtimer  interrupt  chains 

nals,  the  timer  interrupt  vector,  and  comint  is  for  serial  input.  It  resets  the  the  interrupt;  then,  if  ticker  is  greater 

some  control  parameters  for  our  pro-  interrupt  controller,  reads  the  serial  in-  than  zero,  newtimer  decrements  it. 

gram.  The  comstat  macro  reads  the  put  byte,  and  stuffs  it  into  the  circular  When  the  timed_out  macro  finds  that 

status  of  the  serial  port.  The  in-  buffer  unless  the  character  is  an  XON  ticker  is  not  greater  than  zero,  it  returns 

put_char_ready  macro  returns  a  true  or  XOFF  with  XON/XOFF  protocols  a  tme  value. 

value  if  there  is  a  byte  waiting  in  the  enabled.  In  this  case  the  function  sets  sleep  uses  the  timer  to  suspend  the 

serial  input  buffer  and  a  false  value  if  a  flag  so  the  transmitter  knows  to  sus-  program  for  a  specified  number  of  sec- 

not.  pend  or  resume  transmissions.  If  XON/  onds.  Turbo  C  already  has  just  such  a 

Listing  Two,  page  138,  is  serial. c.  XOFF  is  enabled  and  the  buffer  is  at  function  in  its  library,  but  Microsoft  C 

These  functions  manage  serial  port  or  beyond  its  threshold,  newcomintirans-  does  not. 

initialization,  input,  and  output.  The  mits  the  XOFF  character  to  tell  the  Note  that  the  Turbo  C  functions 

initcomport  function  initializes  the  sender  to  hold  up  for  a  while.  getvect  and  setvect  are  used  to  read  and 

communications  port  by  using  the  struc-  The  readcomm  function  waits  for  a  write  the  serial  and  timer  interrupt  vec- 
ture  named  initcom  to  contain  the  byte  to  be  available  in  the  receiver’s  tors.  If  you  are  using  Microsoft  C,  these 

initialization  parameters  that  are  writ-  circular  buffer  and  then  extracts  it  for  are  changed  to  _dos_getvect  and 

ten  to  the  8250  universal  asynchronous  the  calling  function.  A  program  that  _dos_setvect ,  the  MSC  equivalents.  If 

receiver/transmitter  (UART).  The  inte-  polls  for  serial  input  should  call  this  you  are  porting  this  software  to  a  com- 

gers  named  COMPORT,  PARITY,  function  only  after  getting  a  true  return  piler  that  does  not  support  the  inter- 

STOPBITS,  WORDLEN,  and  BAUD  are  from  the  input_char_ready  macro  be-  rupt  function  type,  you  must  use  as- 

initialized  with  the  default  values  as-  cause  readcomm  waits  for  a  character  sembly  language  for  the  entry  and  exit 

sumed  by  the  functions.  to  be  received.  When  readcomm  sees  to  each  of  the  interrupt  functions.  The 

The  initcomport  function  sets  up  the  that  the  buffer  is  at  a  safe  level  after  book  I  mentioned  earlier  has  an  exam- 

serial  receiver  interrupt  process.  In  this  newcomint  has  transmitted  the  XOFF,  pie  of  this  technique, 

process,  all  serial  input  characters  are  readcomm  transmits  the  XON  charac-  The  serial  port  detects  the  break  con- 

read  by  the  interrupt  service  routine  ter  to  tell  the  sender  to  resume  trans-  dition,  framing  error,  parity  error,  and 

named  newcomint ,  which  collects  the  missions.  overrun  error,  any  of  which  might  hap- 

characters  as  they  are  read  into  a  circu-  Programs  that  read  ASCII  text  from  pen.  Why  do  we  not  check  and  correct 
lar  buffer.  The  initialization  steps  and  a  remote  computer  with  seven  data  bits  for  these  conditions?  We  do  not  for  two 

the  serial  input  and  output  operations  and  odd  or  even  parity  should  logically  reasons:  First,  the  exchange  of  human- 

use  definitions  derived  from  the  port  AND  the  return  from  readcomm  with  readable  ASCII  data  assumes  that  the 

number  for  COM1  or  COM2.  Those  0x7f  to  strip  the  parity  bit.  If  you  are  user  can  tell  when  the  characters  being 

definitions  are  in  serial. h.  (You  can  reading  a  binary  stream,  such  as  an  read  are  incorrect.  You  can  visually 

modify  the  code  to  work  with  other  archived  file,  you  should  accept  the  compensate  for  these  so-called  “line 

machines  that  use  the  8250  UART  and  full  eight-bit  value.  hits”  or  terminate  the  transmission  if 

the  8259  Programmable  Interrupt  Con-  The  writecomm  function  sends  the  the  errors  exceed  a  tolerable  threshold, 
troller  by  changing  the  base  port  ad-  byte  in  its  parameter  to  the  remote  com-  Second,  the  other  exchanges  — upload- 

dress  defined  in  serial. h  as  BASEPORT  puter  through  the  serial  port.  Note  that  ing  and  downloading  files  with 

and  the  interrupt  request  line  named  readcomm  and  writecomm  return  a  false  XModem,  Kermit,  et  al. — have  their 

IRQ,  also  in  serial. h.)  First  the  current  value  if  the  port  times  out  as  a  result  own  error-correcting  protocols  involv- 

contents  of  the  serial  interrupt  vector  of  the  elapse  of  the  programmed  TIME-  ing  checksums,  timeouts,  and  retries, 

are  read  and  saved  away.  Then  the  OUT  value  with  no  character  being  We  will  explore  these  techniques  in 

vector  is  initialized  with  the  address  of  received  or  written.  TIMEOUT  is  de-  the  months  to  come. 

newcomint.  The  8250  UART  has  two  fined  in  serial. c  and  is  expressed  in 

registers  that  must  be  initialized.  The  seconds.  The  Modem 

program  asserts  the  data  terminal  ready  The  timer  functions  in  serial. c  pro-  Modems  are  semi-intelligent  devices  that 
(DTR),  request  to  send  (RTS),  and  user  vide  another  example  of  the  use  of  the  connect  remote  computers  with  tele- 
defined  output  2  (OUT2)  signals  in  the  interrupt  function  type.  These  timer  phone  lines  and  that  can  be  pro¬ 
modem  control  register,  and  writes  the  functions  process  timeouts  or  suspend  grammed  to  operate  in  different  ways, 

interrupt  enable  register  with  the  data  processing  for  a  specified  number  of  This  programming  implies  a  language 
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for  the  modem  — a  way  to  set  the  mo¬ 
dem’s  modes  and  read  the  modem’s 
status.  The  accepted  standard  for  this 
language  is  the  Hayes  command  set. 

Because  a  modem  supports  terminal 
connections,  it  recognizes  and  responds 
with  language  that  people  can  under¬ 
stand.  Well,  almost.  The  Hayes  com¬ 
mand  set  is  hardly  what  you  would  call 
a  natural  language,  but  a  person  can 
leam  it.  Oddly,  the  modem  speaks  a 
more  cogent  language  than  it  under¬ 
stands.  You  tell  it  ATE0M1V1S0  =  0  and 
it  answers  OK.  You  say  ATDT 
17033710188  and  it  says  BUSY,  CON¬ 
NECT,  NO  ANSWER,  or  NO  CARRIER. 
You  can  leam  its  language  if  you  want, 
but  any  communications  program  worth 
its  salt  will  know  the  language  and 
hide  it  from  you. 

Listing  Three,  page  139,  is  modem.h. 

It  has  configuration  parameters  and  pro¬ 
totypes  for  the  modem  functions.  The 
parameters’  strings  initialize  and  reset 
the  modem,  dial  a  number,  and  answer 
an  incoming  call.  In  some  communica¬ 
tions  programs,  these  parameters  are 
maintained  in  a  configuration  file  built 
by  a  setup  program.  We’ll  just  hard- 
code  them  this  way.  The  curly  charac¬ 
ters  in  the  RESETMODEM,  INITMODEM, 
and  HANG  UP  parameters  are  not  part 
of  the  Hayes  command  set.  Rather,  they 
tell  the  modout  function  to  wait  one 
second  while  sending  a  command  to 

the  modem. 

Vendors  who  sell  so-called  Hayes- 
compatible  modems  do  not  always  get 
it  right.  Also,  many  modems  have  con¬ 
figuration  micro  switches  that  set  de¬ 
fault  values.  The  string  value  of  the 
INITMODEM  parameter  is  one  that 
works  with  the  Toshiba  T-lOOO’s  inter¬ 
nal  modem  and  the  US  Robotics  Cou¬ 
rier  2400.  This  is  a  black  art.  If  you  have 
modem  problems  with  this  program, 
you  might  need  to  mess  with  the  pa¬ 
rameters,  the  micro  switches,  or  both. 

Listing  Four,  page  139,  modem. c  con¬ 
tains  the  functions  that  control  the  mo¬ 
dem.  The  initmodem  function  initial¬ 
izes  the  serial  port  and  the  modem.  It 
calls  inter cept_timer  to  let  the  program 
hook  the  timer  interrupt  vector.  Pro¬ 
grams  should  call  the  next  function, 
release_ modem,  before  they  terminate. 

It  restores  the  timer  and  serial  interrupt 
vectors  and  resets  the  modem.  If  you 
fail  to  use  this  procedure,  your  com¬ 
puter  will  go  off  into  the  reeds  and  the 
bulrushes  when  you  exit  to  DOS.  The 
placecall  function  dials  the  number  in 
the  PHONENO  parameter.  The  answer- 
call  function  prepares  the  modem  to 
automatically  answer  the  phone.  The 
disconnect  function  disconnects  the  mo¬ 
dem  from  the  phone  line.  The  modout 
function  is  used  by  the  others  to  send 
a  command  to  the  modem.  The  func¬ 
tion  tests  for  the  curly  character  in  the 

command  string  and  modout  calls  the 
sleep  function  in  serial,  c  to  tell  the  pro¬ 
gram  to  wait  one  second  for  each  curly 
character. 

A  program  that  supports  direct  con¬ 
nection  of  the  serial  ports  of  two  com¬ 
puters  with  no  modems  will  set  the 
direct_connection  variable  to  a  true 
value,  which  suppresses  the  modem 
commands.  This  mode  is  one  way  to 
test  a  communications  program  when 
two  phone  lines  are  not  available.  You 
must  connect  the  serial  ports  with  a 
“null  modem”  cable,  which  crosses  the 
send  and  receive  lines  — usually  pins 

2  and  3  — in  the  cable  connectors. 

TINYCOMM 

The  code  in  serial. h,  serial. c,  modem.h, 
and  modem,  c  represents  the  primitive 
functions  required  to  communicate  by 
modem.  To  use  these  functions,  you 
need  a  higher-level  communications  pro¬ 
gram.  Listing  Five,  page  139,  is  ti- 
nycomm.c,  the  bare  beginnings  of  such 
a  program.  Its  purpose  is  to  demon¬ 
strate  the  application  of  the  communi¬ 
cations  functions,  but  it  has  a  good  bit 
of  functionality  packed  into  such  a  tiny 
package. 

When  you  run  TINYCOMM,  you  can 
specify  the  serial  port  — 1  or  2  — and 
the  telephone  number  on  the  command 
line  as  shown  here: 

C  PROGRAMMING 

(continued  from  page  117) 

C>tinycomm  2  555-1212 

After  this  command,  you  see  this  menu. 

- TINYCOMM  Menu - 

P-lace  Call 

A-nswer  Call 

H-ang  Up 

L-og  Input  [OFF] 

S-end  Message  File 

T-elephone  Number  (???-????) 

E-xit  to  DOS 

Enter  Selection  > 

The  TINYCOMM  menu  selections  al¬ 
low  you  to  place  a  call,  tell  TINYCOMM 
to  prepare  to  answer  a  call,  hang  up, 
turn  the  disk  logging  off  traffic  on  and 
off,  send  an  ASCII  file  to  the  other  end, 
reprogram  the  telephone  number,  and 
exit  to  DOS. 

Once  a  connection  is  made,  TI¬ 
NYCOMM  sends  the  characters  you  type 
and  displays  the  characters  it  receives. 
These  displays  include  the  modem’s 
messages,  such  as  CONNECT  and  NO 
CARRIER.  TINYCOMM  expects  you  to 
read  these  messages  and  react  appro- 

priately.  There  is  no  automatic  recogni¬ 
tion  of  any  text  input  to  TINYCOMM. 
You  get  in  and  out  of  the  menu  by 
pressing  the  Esc  key. 

TINYCOMM’s  message,  upload,  and 
log  features  use  a  straight  ASCII  proto¬ 
col  with  XON/XOFF  enabled.  This  is 
acceptable  for  message  traffic  but  would 
not  work  at  all  for  the  transfer  of  binary 
formats  such  as  archived  or  executable 
files.  File  transfer  protocols  will  come 
in  a  future  installment. 

Ctrl  Break 

When  a  program  takes  over  an  inter¬ 
rupt  vector,  the  program  must  not  ter¬ 
minate  abnormally.  If  it  does,  the  inter¬ 
rupt  vector  will  still  point  to  the  mem¬ 
ory  formerly  occupied  by  the  program. 
The  next  time  the  interrupt  happens, 
the  system  will  be  awry.  TINYCOMM 
hooks  the  timer  and  serial  interrupt 
vectors,  so  we  must  not  allow  it  to  be 
terminated  other  than  through  the  nor¬ 
mal  exit  point  of  the  program  where 
these  vectors  are  restored. 

When  you  press  Ctrl  C  or  Ctrl  Break, 
DOS  normally  displays  the  AC  token 
and  aborts  the  program.  This  would 
be  one  of  those  unwanted  termina¬ 
tions  I  just  mentioned.  You  can  take 
over  the  Ctrl  Break  and  Ctrl  C  interrupt 
vectors  (Ox lb  and  0x23)  and  prevent 
the  termination,  but  the  stupid  ac  to- 

ken  still  gets  displayed,  messing  up 
your  well-planned  screen  display  and 
moving  your  cursor. 

One  way  to  defeat  this  dubious  fea¬ 
ture  of  DOS  is  to  avoid  using  DOS 
for  keyboard  input  and  screen  output 
functions.  TINYCOMM  uses  Turbo  C’s 
getch  and  putch  or  its  own  keyboard 
and  screen  functions  for  Microsoft  C, 
and  these  measures  effectively  avoid 
DOS. 

TINYCOMM  polls  the  keyboard  be¬ 
fore  calling  getch  and  polls  the  serial 
buffer  before  calling  getcomm.  This  tech¬ 
nique  allows  either  device  to  get  a  char¬ 
acter  in  edgewise,  which  is  necessary 
in  a  full  duplex  communications  op¬ 
eration.  The  two  usual  ways  to  poll  the 
keyboard  are  the  kbhit  function  and 
the  bioskey  (TC)  or  _bios_key  (MSC) 
function.  Unfortunately,  these  functions 
involve  the  Ctrl  Break  and  Ctrl  C  logic, 
so  we  cannot  use  them.  Instead  we 
must  use  BIOS  to  see  if  a  key  has  been 
pressed.  Both  compilers  have  the  int86 
function,  and  we  can  use  this  function 
to  call  BIOS  interrupt  0xl6,  which  man¬ 
ages  the  keyboard.  The  keyhit  function 
in  tinycomm.c  uses  int86 and  the  prob¬ 
lem  is  solved — well,  not  quite.  BIOS 
returns  its  results  in  the  zero  bit  of  the 
CPU’s  flags  register.  Turbo  C’s  int86 
includes  the  flags  register  in  the  REGS 
union  written  by  int8&,  the  Microsoft 
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C  version  does  not.  As  a  consequence, 
Microsoft  C  provides  no  way  that  I  can 
find  to  poll  the  keyboard  without  the 
offensive  AC  showing  up  and  perhaps 
aborting  the  program.  To  overcome  this 
obstacle,  we  use  the  assembly  language 
function  found  in  Listing  Six,  keyhit.asm 
(page  140). 

The  key  hit  function  is  the  only  Ctrl 
Break  defensive  measure  we  need  with 
Turbo  C.  Microsoft  C  is  not  as  easy.  The 
MSC  getch,  putch,  and  gets  functions 
let  the  break  operation  get  into  the  act. 
Therefore,  the  mscgetch,  mscputch,  and 
mscgets  functions  are  added  to  MSC- 
compiled  versions  of  tinycomm.c.  The 
gotoxy  and  clrscr  functions  are  clones 
of  similar  Turbo  C  functions. 

Listing  Seven,  page  140,  is  tinycomm 
.prj,  the  Turbo  C  environment  project 
make  file.  Set  your  compiler  defines 
option  (Alt-O/C/D)  to  these  parameters: 

MSOFT=  1  ;TURBOC=2;COMPILER= 
TURBOC 

Listing  Eight,  page  140,  is  tinycomm 
.mak,  the  make  file  for  Microsoft  C.  It 
uses  the  small  memory  model. 

Next  month  we’ll  overhaul  the  TI¬ 
NYCOMM  program  to  use  windows, 
help,  menus,  and  the  other  tools  in  our 
collection.  We  will  add  features  to  down¬ 
load  files,  program  the  serial  port’s  pa¬ 
rameters  from  a  menu,  use  the  direct 
connection  features  of  the  modem  man¬ 
ager,  access  a  phone  directory,  and 
maintain  the  program’s  setup  in  a  con¬ 
figuration  file.  We  will  insert  the  hooks 
to  add  file  transfer  protocols  (but  not 
the  protocols  yet).  As  I  develop  this 
program,  I  am  testing  it  by  using  it  for 
all  my  online  activities,  so  if  I  disappear 
some  night  in  the  middle  of  a  heated 
online  exchange,  you’ll  know  why. 

Availability 

All  source  code  for  articles  in  this  issue 
is  available  on  a  single  disk.  To  order, 
send  $14.95  (Calif,  residents  add  sales 
tax)  to  Dr.  Dobb’s  Journal ,  501  Galves¬ 
ton  Dr.,  Redwood  City,  CA  94063,  or 
call  800-356-2002  (inside  Calif.)  or  800- 
533-4372  (outside  Calif.).  Please  spec¬ 
ify  the  issue  number  and  format  (MS- 
DOS,  Macintosh,  Kaypro). 


DDJ 

(Listings  begin  on  page  138.) 

Vote  for  your  favorite  feature/article. 
Circle  Reader  Service  No.  11. 


120 


Dr.  Dobb’s  Journal,  February  1989 


124 


COLUMNS 


GRAPHICS  PROGRAMMING 


Graphics  programming  is  enthrall¬ 
ing  because  it  gives  immediate  feed¬ 
back,  translating  your  ideas  into  vivid 
visual  images.  It’s  also  challenging  — 
in  many  ways  it’s  one  of  the  most 
demanding  forms  of  programming  — 
and  overcoming  its  complexities  en¬ 
hances  the  satisfaction  of  it.  End  users 
have  come  to  expect  more  and  better 
graphics,  which  makes  the  discipline 
increasingly  important.  For  all  these 
reasons  and  more,  we  embark  this 
month  on  a  voyage  into  the  enchanted 
world  of  graphics  programming. 

In  this  column  I’m  going  to  discuss 
the  whole  scope  of  computer  graphics, 
starting  with  the  writing  of  pixels  — the 
basic  unit  of  visual  information  — and 
building  from  there.  In  time  I’ll  get  to 
such  lofty  subjects  as  shading  and  light 
sourcing  and  photorealism. 

High-level  graphics  rest  upon  a  hier¬ 
archy  of  lower-level  functions.  As  a 
result,  one  of  the  chief  projects  of  this 
column  will  be  to  develop  a  graphics 
application  program  interface  (API),  a 
library  of  routines  supporting  ever  more 
sophisticated  techniques  for  produc¬ 
ing  dazzling  visual  images.  The  API 
will  unfold  month  by  month,  building 
not  only  a  useful  toolset,  but  also  an 
understanding  of  the  concepts  and  al¬ 
gorithms. 

We’re  going  to  write  the  API  in  ge¬ 
neric  ANSI  C,  along  with  some  assem¬ 
bly  language  routines  for  performance. 
A  number  of  C  compilers  come  with 
built-in  graphics  libraries,  but  because 
there’s  no  consistency  from  one  to  the 
next,  the  API  will  be  completely  indepen¬ 
dent  of  any  vendor’s  library  or  C  dia¬ 
lect. 

The  hardware  model  is  the  EGA/ 
VGA  on  IBM  PCs  and  compatibles.  Note 
that  the  CGA  isn’t  included.  The  reason 
is  simple:  You  can’t  do  serious  graph¬ 
ics  development  on  a  board  that  pro¬ 
vides  only  four  colors  at  low  resolu¬ 
tion.  Some  might  say  you  can’t  on  the 
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EGA,  either,  which  furnishes  16  out  of 
64  colors.  While  there’s  merit  to  that 
point,  the  EGA  is  widely  available,  and 
it  provides  a  foundation  for  the  VGA. 
Initially  we’ll  work  with  the  EGA,  but 
eventually  we’ll  move  on  to  the  VGA’s 
much  richer  set  of  256  colors  at  a  time. 

This  puts  you  at  a  disadvantage  if 
you’re  working  with  a  different  hard¬ 


er.  Dobb’s Journal,  February  1989 


Pixelmania 


ware  environment,  but  it  doesn’t  ex¬ 
clude  you.  Virtually  all  of  the  low-level 
machine-specific  stuff  will  appear  be¬ 
tween  now  and  June:  routines  that  op¬ 
erate  on  pixels  or  otherwise  interface 
directly  with  the  video  controller.  Other 
hardware  graphics  systems  differ  in  de¬ 
tails,  but  all  must  read  and  write  pixels. 
So,  if  you’re  developing  on  a  different 
machine  or  video  board,  write  low- 
level  routines  that  parallel  those  pre¬ 
sented  here.  Most  of  the  higher-level 
functions  in  C  can  then  be  used  “as  is” 
to  keep  you  in  step  with  the  column.  I 
wish  I  could  publish  equivalent  low- 
level  routines  for  other  systems,  but  if 
I  did,  I’d  never  get  anything  else  done. 
And  my  purpose  is,  after  all,  to  explore 
the  meatier  issues  and  techniques  of 
graphics  programming. 

The  C  code  written  here  compiles 
with  Turbo  C  2.0  and  Microsoft  C  5.1. 
For  the  assembly  language  routines, 
I’m  using  Microsoft  MASM  5.1  syntax, 
which  also  assembles  under  Borland’s 
TASM. 

Now  let’s  get  started. 

How  to  Write  a  Pixel 

The  elementary  particle  of  graphics  in¬ 
formation  is  the  pixel,  a  contraction  for 
“picture  element.”  A  pixel  has  two  char¬ 
acteristics:  position  and  color. 

Its  position  is  expressed  by  a  coordi¬ 
nate  pair  consisting  of  the  X  (or  hori¬ 
zontal)  location  and  the  Y  (vertical) 
position.  The  top  left  comer  of  the 
display  is  at  (0,  0).  X  coordinates  in¬ 
crease  to  the  right,  and  Y  coordinates 
increase  downward.  Thus,  on  a  display 
of  640x350,  which  is  the  best  EGA  reso¬ 
lution,  the  lower  right  comer  of  the 
display  is  at  (639,  3491,  and  the  center 
is  at  (320,  175).  Note  that  the  X  coordi¬ 
nate  is  always  expressed  first  in  the 
pair. 

Most  PC-based  graphics  systems  — 
the  EGA,  VGA,  and  even  more  exotic 
chips  such  as  the  TI  340X0  — use  an 
indexed  color  scheme.  Here,  a  pixel’s 
color  is  not  absolute  but  instead  is  taken 


from  a  set  of  color  registers  called  the 
palette.  You  tell  a  pixel  to  assume  a 
certain  value.  That  value  refers  to  a 
palette  register  that  contains  the  actual 
color,  which  is  a  zoned  bitfield  con¬ 
taining  a  combination  of  red,  green, 
and  blue  hues  that  comprise  the  color 
blend  appearing  at  the  pixel  position. 
Thus,  the  pixel  value  is  an  index  to  a 
color  register.  As  it  refreshes  each  pixel, 
the  video  adapter  uses  the  pixel  value 
to  look  up  the  palette  register  where 
the  real  color  is  found. 

In  its  default  condition,  the  EGA/ 
VGA  has  certain  predictable  values  in 
the  palette  registers.  For  example,  pal¬ 
ette  register  1  contains  medium  blue. 
Thus,  PC  programmers  get  used  to  think¬ 
ing  that  1  means  blue.  By  changing  the 
content  of  palette  register  1,  however, 
you  can  instantly  change  all  pixels  with 
value  1  to  a  different  color. 

I’ll  talk  more  about  color  control  in 
April.  Meanwhile,  use  the  default  pal¬ 
ette  with  the  understanding  that  a  pixel 
value  refers  to  a  palette  register,  which 
can  contain  any  of  64  colors.  The  EGA 
has  16  palette  registers,  and  so  does  the 
VGA  when  running  in  EGA  emulation 
mode;  other  VGA  modes  have  256  pal¬ 
ette  registers  with  a  much  broader  se¬ 
lection  of  colors. 

The  simplest  way  to  write  a  pixel  is 
to  call  the  PC’s  ROM  BIOS  video  serv¬ 
ices  via  interrupt  lOh,  function  OCh.  In 
C  notation,  you  might  write  such  a  call 
as  follows: 

void  draw_point  (int  x,  int  y, 


union  REGS  r; 
r.h.ah  =  OxOC; 
r.h.al  =  pxval; 
r.x.cx  =  x; 
r.x.dx  =  y; 

int86  (0x10,  &r,  &r); 

1 

To  place  a  blue  pixel  in  the  center  of 
the  screen,  then,  you’d  write 

draw_point  (320,  175,  1); 

Unfortunately,  simplest  is  not  always 
best.  The  ROM  BIOS  video  services  are 
shockingly  inefficient.  On  my  10-MHz 
AT  clone,  the  best  throughput  is  a  lazy 
2,000  pixels  per  second  using  this  C 
function.  By  going  around  the  ROM 
BIOS  to  interface  directly  with  the  6845 
video  controller  using  assembly  lan¬ 
guage,  you  can  achieve  a  10. 5X  in¬ 
crease  in  throughput  — to  around  25,000 
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pixels  per  second  — without  sacrific¬ 
ing  reliability.  And  in  the  special  case 
discussed  next  month,  a  250X  improve¬ 
ment  (yes,  an  amazing  half  a  million 
pixels  per  second)  is  possible.  To  ac¬ 
complish  this  miracle,  it’s  necessary  to 
understand  something  about  the  6845 
video  controller  chip  (VCC)  and  the 
way  pixel  values  are  represented. 

Programming  6845 
Write  Mode  2 

Video  memory  in  the  EGA/VGA  con¬ 
sists  of  color  planes.  There  are  as  many 
color  planes  as  there  are  possible  bits 
in  a  pixel  value.  In  EGA  16-color  mode 
lOh,  a  pixel  can  have  any  value  from 
Oh  to  OFh,  or  four  bits,  and  thus  there 
are  four  color  planes. 

The  exact  details  of  how  this  is  im¬ 
plemented  are  not  important,  because 
the  VCC  manages  it  for  us.  What  is 
important  to  realize  is  that  pixels  are 
grouped  by  byte  across  the  width  of 
the  screen.  With  a  horizontal  granular¬ 
ity  of  640  pixels,  the  display  is  concep¬ 
tually  80  bytes  wide.  But  under  each 
byte  are  layered  a  number  of  other 
bytes  that  you  can’t  see:  in  EGA  mode 
lOh,  three  others  for  a  total  of  four. 

A  pixel’s  value  is  determined  by  find¬ 
ing  its  bit  position  within  the  topmost 
byte,  then  peering  downward  through 
the  corresponding  bit  positions  in  the 
other  three  layers.  The  bits  comprising 
the  pixel  value  are  thus  “stacked,”  with 
each  bit  on  a  different  plane.  A  plane 
is  a  region  of  display  memory:  28,000 
bytes  for  a  640x350  display.  The  pixel 
at  the  top  left  comer  derives  its  value 
from  the  high-order  bits  of  the  bytes  at 
offsets  0,  28,000,  56,000,  and  84,000. 

At  first  glance,  such  a  scheme  makes 
you  wonder  how  much  the  designers 
had  to  drink  before  they  dreamed  it 
up.  Closer  examination,  however,  re¬ 
veals  the  method  of  the  madness:  You 
can  add  another  color  plane  simply  by 
tacking  an  additional  28,000  bytes  onto 
the  end  of  the  display  memory,  with¬ 
out  rearranging  the  mapping  of  bytes 
to  pixels. 

The  6845  VCC  takes  care  of  all  the 
bit-twiddling  required  to  read  and  write 
pixels.  By  writing  a  series  of  values  to 
the  VCC  via  ports  in  the  range  3C4h 
through  3CEh,  you  program  the  6845 
to  perform  certain  pixel-oriented  op¬ 
erations.  Once  you’ve  programmed  the 
VCC,  read  from  or  write  to  the  pixel’s 
plane  0  video  buffer  address,  and  the 
VCC  transparently  intervenes  to  per¬ 
form  the  plane  indexing. 

In  order  to  update  individual  pixels, 
set  up  the  VCC  for  Write  Mode  2.  It’s 
also  necessary  to  load  a  bit  mask  speci¬ 


fying  the  pixel(s)  within  the  byte  (which 
represents  eight  pixels)  to  be  updated. 
Then  read  the  pixel’s  byte  location  in 
plane  0  of  the  video  buffer.  This  loads 
the  four  plane  bytes  into  the  6,845  latch 
registers.  By  writing  0  to  the  video  buffer 
address,  you  clear  the  mask-specified 
pixel(s);  then  you  write  the  new  palette 
register  value  to  the  same  address.  The 
VCC  updates  the  affected  bits  in  the 
latch  registers  and  copies  the  latches 
back  to  their  proper  memory  locations. 
The  pixel  change  takes  effect  instantly. 

Listing  One,  page  142,  is  the  low- 
level  assembly  language  routine 
DRAWPT.  ASM,  which  performs  this 
6845  VCC  interface  function.  It’s  writ¬ 
ten  to  be  called  from  C  with  the  proto¬ 
type 

void  far  draw_point  (int  x,  int  y); 

As  mentioned  earlier,  this  function 
achieves  over  ten  times  the  perform¬ 
ance  of  the  ROM  BIOS  equivalent. 

Note  that  public  and  external  sym¬ 
bols  must  be  prefixed  in  assembly  lan¬ 
guage  with  an  underscore.  This  com¬ 
plies  with  C  linkage  conventions.  Note 
also  that  DRAWPT.ASM  relies  on  an 
external  variable  called  colorl  to  fur¬ 
nish  the  new  pixel  value.  I  discuss  where 
that  variable  comes  from  next. 

Starting  the  GRAFIXAPI 

The  development  of  a  graphics  API 
begins  with  the  bare-bones  library  of 
four  functions  described  in  GRAFIX.H 
(Listing  Two,  page  146).  These  func¬ 
tions  are: 

•  Put  the  video  system  into  a  graphics 
mode. 

•  Restore  the  system  to  its  original  text 
mode. 

•  Write  a  pixel. 

•  Select  the  current  pixel  value. 

Of  these  functions,  one  is  a  separate 
program  (DRAWPT.ASM  from  Listing 
One),  while  the  other  three  are  found 
in  GRAFEX.C  (Listing  Three,  page  146). 
After  assembling  DRAWPT.ASM  and  com¬ 
piling  GRAFIX.C,  create  a  library  with 
the  DOS  utility  command 

LIB  GRAFIX  +GRAFIX+DRAWPT; 

This  pulls  GRAFIX.OBJ  and  DRAWPT. 
OBJ  into  the  single  object  file 
GRAFIX.LIB,  with  which  you  can  link 
your  application  programs. 

Let’s  briefly  discuss  the  elements  in 
GRAFIX.C.  The  init_video( )  function 
places  the  graphics  subsystem  into  the 
mode  specified  via  the  argument.  The 
two  modes  currently  supported  are  EGA 
and  VGA16,  defined  in  GRAFIX.H.  This 
function  does  a  number  of  things,  as  its 


length  suggests. 

Lines  46  -  76  inventory  the  video  sub¬ 
system.  Jeff  Duntemann’s  first  column 
arrived  as  I  was  writing  this  routine. 
By  a  happy  coincidence  it  contained  a 
method  for  detecting  the  video  equip¬ 
ment  that’s  simpler  than  mine,  so  I 
adapted  Jeffs  code  to  suit.  For  more 
on  how  it  works,  see  the  “Structured 
Programming"  column  in  this  issue. 
Note  that  the  VGA  emulates  EGA  modes, 
so  both  the  ega  and  vga  variables  are 
set  to  TRUE  when  a  VGA  is  detected. 

Assuming  that  an  EGA  or  VGA  is 
present,  lines  78  -  98  perform  a  num¬ 
ber  of  set-up  operations: 

•  Select  the  default  pixel  color. 

•  Save  the  current  text  mode,  video 
page,  and  cursor  position. 

•  Copy  the  text  screen  to  a  save  area 
on  the  heap  so  that  it  can  be  restored 
intact  later  when  you  return  from  graph¬ 
ics  mode. 

Lines  97-109  then  switch  the  system 
to  graphics,  providing  that  the  desired 
mode  is  supported.  Success  is  indi¬ 
cated  by  setting  the  result  variable  to 
TRUE.  Lines  110-117  check  the  result 
and  either  deallocate  the  text  screen 
save  area  when  unsuccessful  or  save 
the  graphics  mode  and  register 
pc_textmode( )  as  an  exit  function  when 
the  system  has  been  put  into  graphics. 
The  function  returns  the  result  variable 
so  that  the  caller  can  find  out  if  the  call 
succeeded. 

init_video( )  is  by  far  the  most  com¬ 
plex  function  in  the  library,  and  it  will 
probably  remain  so.  But  we’re  not  done 
with  it  yet.  In  later  installments  I’ll  ex¬ 
pand  it  to  accommodate  new  video 
modes,  as  well  as  to  initialize  the  color 
palette  and  a  data  structure  describing 
the  display  characteristics.  It’s  complete 
enough  for  now,  though. 

The  function  pc_textmode( )  restores 
the  graphics  system  to  its  original  state, 
with  the  screen  as  it  was  prior  to  invok¬ 
ing  graphics  and  the  cursor  correctly 
placed.  This  function  runs  only  if  the 
system  is  in  graphics;  the  oldmode  vari¬ 
able  is  always  0  (FALSE)  when  in  text 
mode,  and  something  else  when  in 
graphics.  There’s  a  reason:  init_video( ) 
registers  pc_textmode( )  as  an  exit  func¬ 
tion,  which  is  automatically  called  on 
program  termination.  There  is  no  C 
function  to  undo  the  atexit( )  call,  so 
pc_textmode( )  will  be  called  when  the 
program  ends  no  matter  what.  If  you 
were  already  in  text  mode  and  this 
safeguard  didn’t  exist,  the  call  to 
pc_textmode(  )  would  crash  the  system 
or  corrupt  the  display. 

The  final  function  is  set_colorl.  It 
simply  stores  the  argument  — the  cur¬ 
rently-selected  palette  register  for 
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pixels  — into  the  colorl  variable.  This 
variable  is  used  by  the  pixel-writing 
routine  and  will  also  be  used  by  the 
fast  line-drawing  routines  to  be  pre¬ 
sented  next  month. 

The  GRAFEX  library  is  an  absolute 
minimal  API.  Though  it  lacks  function¬ 
ality,  it  can  be  made  to  do  some  useful 
work.  The  STRIPES. C  program  (Listing 
Four,  page  146)  furnishes  a  small  pro¬ 
gram  that  you  can  use  to  test  your  copy 
of  the  library.  The  program  draws  a 
solid  rectangle  in  the  center  of  the  dis¬ 
play  with  multicolored  stripes  running 
northeast  to  southwest.  It  freezes  the 
display  until  you  press  a  key  and  then 
restores  the  original  text  screen.  After 
compiling  the  program,  link  it  with 
GRAFIX.LIB  and  the  runtime  library  for 
the  compiler  and  memory  model. 

Must  Readingfor  PC  Graphics 
Programmers 

If  you  do  much  graphics  programming, 
a  necessary  addition  to  your  reference 
bookshelf  is  Richard  Wilton’s  Program¬ 
mer’s  Guide  to  PC  &  PS/2  Video  Sys- 
tems ,  published  by  Microsoft  Press  in 
1987.  This  book  could  almost  be  subti¬ 
tled  “More  Than  Anyone  Would  Ever 
Want  to  Know  About.  .  .”  Its  531  pages 
bulge  with  excruciatingly  detailed  in¬ 
formation  about  the  CGA,  MCGA,  EGA, 
VGA,  and  Hercules,  including  numer¬ 
ous  listings  in  assembly  language  and 
a  fair  number  in  C  as  well.  Wilton  pre¬ 
sents  alternative  algorithms  for  such 
challenging  problems  as  drawing  cir¬ 
cles  and  doing  flood  fills,  with  lucid 
discussions  of  which  is  best  for  a  given 
circumstance.  My  copy  is  getting  dog¬ 
eared  from  heavy  use,  and  the  only 
criticism  I  have  so  far  is  that  the  listings 
are  in  faded  green,  which  is  hard  to 
read.  This  book  is  just  super. 

So  there  we  have  it,  the  modest  be¬ 
ginnings  of  an  epic  voyage  into  the 
infinitely  fascinating  innards  of  graph¬ 
ics  programming.  I  invite  you  to  rejoin 
me  here  each  month  as  we  explore  the 
crystal  caverns  of  this  magical  craft. 

Availability 

All  source  code  for  articles  in  this  issue 
is  available  on  a  single  disk.  To  order, 
send  $14.95  (Calif,  residents  add  sales 
tax)  to  Dr.  Dobb’s  Journal,  501  Galves¬ 
ton  Dr.,  Redwood  City,  CA  94063,  or 
call  800-356-2002  (inside  Calif.)  or  800- 
533-4372  (outside  Calif.).  Please  spec¬ 
ify  the  issue  number  and  format  (MS- 
DOS,  Macintosh,  Kaypro). 

DDJ 

(Listings  begin  on  page  142.) 

Vote  for  your  favorite  feature/article. 

Circle  Reader  Service  No.  9. 
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Run  Length  Encoding 

RLE  is  an  efficient — yet  simple — way  of  reducing  storage 

requirements 


Run  Length  Encoding  (RLE)  is  one 
of  several  techniques  that  can 
be  used  to  reduce  the  storage 
requirements  of  text  files,  databases, 
and  digital  images.  The  algorithm  is 
very  simple  to  implement,  it  produces 
output  files  that,  on  the  average,  re¬ 
quire  80  percent  of  the  input  file  space, 
and  executes  quickly.  Because  the  com¬ 
pression  factor  is  of  prime  interest,  it 
should  be  pointed  out  that  the  worst 
case  performance  of  the  algorithm 
causes  the  output  file  to  double  its  size. 
My  use  of  the  algorithm,  however,  for 
compressing  and  saving  the  digitized 
output  of  a  frame-grabber  board  has 
never  resulted  in  this  degeneracy. 

The  algorithm  works  as  follows:  An 
input  buffer  is  scanned  for  sequences 
of  identical  characters.  When  a  charac¬ 
ter  transition  occurs  the  repetition  count 
of  the  previous  character  (along  with  the 
character  itself)  is  sent  to  an  output  buffer. 

This  continues  until  the  end  of  the 
input  buffer  is  reached.  My  implemen- 

Robert  Zigon  is  a  senior  software  engi¬ 
neer  and  can  be  reached  at  4505  Can- 
dletree  Circle,  Apt.  7,  Indianapolis,  IN 
46254. 


Robert  Zigon 

tation  currently  uses  1  byte  for  the  repe¬ 
tition  count.  This  allows  for  sequences 
of  identical  characters  to  be  reduced 
to  exactly  2  bytes.  The  output  for  the 
input  buffer  looks  like  this: 

Input  Buffer  :  AAAA  BBBBBB  CC  D 

EEEEE 

Output  Buffer  :  4A  6B  2C  ID  5E 

In  this  example,  the  18  characters  in 
the  input  buffer  were  reduced  to  10 
characters  in  the  output  buffer  (the 
spaces  in  the  input  and  output  buffers 
are  there  to  make  it  easier  to  read). 
Notice  that  no  space  savings  was  gained 
by  compressing  the  CC  and  that  the 
space  requirements  of  the  D  doubled. 

Listing  One  contains  a  routine  called 
PACK  that  can  be  used  to  compress  an 
input  buffer.  The  code  is  written  in  the 
assembly  language  of  the  Intel  80X86 
family.  The  routine  is  designed  so  that 
multiple  calls  will  result  in  having  the 
output  concatenated  to  the  contents 
of  the  previous  call. 

After  the  information  is  packed  and 
saved  to  disk,  the  day  will  come  when 
you  will  need  to  unpack  it.  Unpacking 
is  significantly  easier.  A  repetition  count 
is  read  from  the  packed  buffer,  and  the 


corresponding  character  is  sent  to  the 
output  buffer  that  many  times.  The  string 
load  (LODSB)  mnemonic  permits  the 
efficient  reading  of  the  pairs,  while  the 
string  store  (STOSB)  and  REP  prefix 
perform  the  duplication  and  restora¬ 
tion  of  the  input  file.  Listing  One  also 
contains  the  necessary  UNPACK  rou¬ 
tine  to  accomplish  this. 

Run  Length  Encoding  is  a  fast  and 
efficient  technique  for  reducing  the 
space  requirements  of  an  input  file. 
Though  more  complex  algorithms  ex¬ 
ist  with  better  compression  factors  (and 
worse  compression  times),  its  elegance 
lies  in  its  simplicity. 

Availability 

All  source  code  for  articles  in  this  issue 
is  available  on  a  single  disk.  To  order, 
send  $14.95  to  Dr.  Dobb’s Journal,  501 
Galveston  Dr.,  Redwood  City,  C A 94063, 
or  call  415-366-3600,  ext.  221.  Please 
specify  the  issue  number  and  format 
(MS-DOS,  Macintosh,  Kaypro). 

DDJ 

Vote  for  your  favorite  feature/article. 
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RLE. asm 
Author  : 


Run  Length  Encoding  Routines 
Bob  Zigon 


PACK 

This  routine  will  pack  a  source  buffer  into  a  destination  buffer 
by  reducing  sequences  of  identical  characters  down  to  a  1  byte 
repetition  count  and  a  1  byte  character. 

INPUT  :  DS:SI  ---  Points  to  source  buffer  to  pack 
ES:DI  —  Points  to  destination 

DX  --  Number  of  characters  in  source  buffer  to  pack 
OUTPUT:  DI  —  Is  updated  to  allow  for  multiple  calls. 


proc 

near 

push 

ax 

push 

bx 

push 

cx 

lodsb 

mov 

bl,al 

xor 

cx,  cx 

;  Counts  number  of  characters  packed 

cld 

;  All  moves  are  forward 

lodsb 

;  Get  chara  into  AL 

inc 

cx 

;  Inc  chara  count 

sub 

dx,  1 

je 

p30 

;  Exit  when  DX  =  0 

cmp 

cx, 255 

;  255  characters  in  this  block  yet? 

jne 

p20 

;  If  not  then  jump 

mov 

[di-] ,  cl 

;  output  the  length 

inc 

di 

xor 

cx,  cx 

mov 

[di] , bl 

;  output  the  character 

inc 

di 

cmp 

al,bl 

;  Has  there  been  a  character  transition? 

je 

plO 

;  NOPE  ...  so  go  back  for  more 

mov 

[di] , cl 

;  output  the  length 

inc 

di 

xor 

cx,  cx 

mov 

[di] ,bl 

;  output  the  character 

inc 

di 

mov 

jmp 


bl,al 

plO 


;  Move  Latest  chara  into  BL 
;  Loop  back  for  more 


will  get  here  when  DX  finally  goes  to  zero. 
p30:  mov  al,cl  ;  Output  the  length 

;  Output  the  character 


mov  al,cl 
stosb 

mov  al,bl 
stosb 


pop 

pop 

pop 

ret 

endp 


UNPACK 

This  routine  will  unpack  a  sequence  of  characters  that  were 
previously  PACKed. 

NOTE  :  Source  Region  must  be  terminated  with  a  NULL. 

INPUT  :  DS:SI  —  Source  buffer  to  unpack 

ES:DI  --  Destination  buffer  to  unpack  into 

OUTPUT: 


unplO : 


unp40 : 
unpack 


proc  near 
push  ax 
push  cx 
xor  cx,cx 
cld 

lodsb 
cmp  al,0 
je  unp40 
mov  cl,al 
lodsb 

rep  stosb 
jmp  unplO 

pop  cx 
pop  ax 
ret 
endp 


Make  sure  CH  is  zero 
All  moves  are  forward 


Load  into  AL  a  character  from  DS : [SI ] 
Length  of  zero  is  end  of  region 


Length  goes  into  CL 
AL  has  chara  to  repeat 


Store  AL  to  [DI]  and  repeat  while  CX  <>  0 
Loop  back  forever 


End  Listing 
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STRUCTURED  PROGRAMMING 


The  Return  of  the  Shower  Curtain  Salesman 


It’s  a  crazy  business,  these  magazines. 

The  very  first  computer  magazine  I 
bought  was  a  Dr.  Dobb’s  Journal,  back 
in  my  COSMAC  days  of  late  76.  Still, 
it’s  got  to  be  one  of  the  very  few  seri¬ 
ous  mags  I  haven’t  yet  written  for.  So 
let  me  drive  a  stake  into  that  12-year 
record  by  introducing  myself  as  your 
new  “Structured  Programming”  colum¬ 
nist. 

Not  a  few  of  you  will  recognize  me 
as  that  grinning  gremlin  from  the  edito¬ 
rial  page  of  Turbo  Technix,  Borland’s 
incandescent  programmers’  magazine 
that  vividly  demonstrated  what  hap¬ 
pens  when  the  tail  of  a  circular  queue 
of  dollars  catches  up  with  and  seri¬ 
ously  overtakes  the  head.  After  a  heart¬ 
break  of  that  magnitude,  I  had  thought 
about  laying  aside  the  magic  keyboard 
forever.  However,  it  was  either  write 
or  sell  shower  curtains  to  discount  stores 
in  the  Missouri/Iowa/Minnesota  terri¬ 
tory  — and  if  you’re  reading  this,  well, 
my  decision  should  be  obvious. 

I  believe  that  in  starting  a  project  like 
this  it’s  only  fair  to  be  up  front  about 
my  biases.  With  all  due  respect  to  the 
Dr.  Dobb’s  majority,  I  don’t  think  all 
that  much  of  C.  Therefore,  a  significant 
part  of  the  mission  of  this  column  will 
be  to  demonstrate  that  there’s  nothing 
you  can  do  in  C  that  you  can’t  do  in 
Modula-2  or  Pascal,  and  with  less  need 
for  Band-Aids  and  Mad-Dog  Colombian 
Buzz-Beans.  (Tell  you  about  those  some 
day .  . .) 

I  strongly  favor  object-oriented  pro¬ 
gramming,  and  while  OOP  is  wasted 
on  mongrels  like  C++,  it’s  true  that 
there  are  few  OOP  options  for  DOS 
outside  the  C  sphere.  This  is  why  I’ll 
be  talking  about  Smalltalk  and  Actor 
from  time  to  time.  Whether  or  not  there 
will  ever  be  a  NeXT  machine  for  the 


Jeff  Duntemann 
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south  side  of  $10,000,  OOP  is  hot.  Read 
up  on  it.  Try  it  if  you  get  the  chance. 
(Digitalk’s  $99  Smalltalk/V  is  an  excel¬ 
lent  learning  vehicle.) 

Finally,  I’ve  been  a  Borland  employee 
in  the  past  and  still  have  ties  to  the 
company,  so  I  will  politely  decline  any 
invitations  to  review  Pascal  or  Modu¬ 
la-2  compilers  here  or  elsewhere.  While 


I  will  be  mentioning  programming  tools 
of  various  sorts  as  I  go,  the  emphasis 
will  be  on  awareness  rather  than  evalu¬ 
ation.  No  matter  what  they  tell  you,  a 
lot  of  powerful  stuff  still  comes  out  of 
garages,  and  I’ll  be  pointing  out  the 
best  of  it  as  I  find  it. 

I  recognize  that  Pascal  and  Modula 
aren’t  the  only  non-C  languages  kick¬ 
ing  around.  Ada?  I  don’t  know.  If  I  see 
a  good  one  that  doesn’t  cost  six  per¬ 
cent  of  the  gross  national  product,  I’ll 
try  it  out  and  let  you  know.  Cobol  or 
Fortran?  No  chance.  And  while  I  don’t 
promise  to  talk  about  Basic  I  don’t  prom¬ 
ise  not  to,  either. 

Your  input  is  solicited.  What  lan¬ 
guages  would  you  like  me  to  discuss? 
(Is  anybody  really  using  Smalltalk  on 
the  PC?)  Wiat  do  you  want  to  know 
how  to  do?  Do  you  care  about  OS/2? 
Windows?  TSRs?  High  level?  (How  to 
Design  a  Coherent  Program?)  Low  level? 
(How  to  Load  an  EGA  Font?)  Assem¬ 
bler  interface?  Send  me  a  laundry  list. 
Also,  tips  are  welcome;  I  only  have  two 
eyes  and  so  many  hours  in  the  day. 
Send  me  your  opinions  and  your  best 
mini  hacks.  What’s  hot?  What’s  not?  Be 
my  eyes  and  ears.  Bearer  of  the  best  tip 
of  each  month  gets  my  secret  recipe 
for  Structured  Chicken  Soup  plus  a  lit¬ 
tle  bag  of  Mad-Dog  Colombian  Buzz- 
Beans. 

Looking  For  Mr.  Goodboard 

The  problem  with  keeping  video  on 
the  back  plane  (as  the  PC  does  and  the 
Mac  does  not)  is  that  the  Vendor  Go¬ 
rilla  (guess  who)  keeps  changing  boards 
on  us.  There  are  now  two  different  text 
video  devices  for  the  PC  (monochrome 
and  color)  and  four  different  graphics 
devices  (CGA,  EGA,  MCGA,  and  VGA), 
not  counting  the  unlamented  PCjr.  To 
avoid  programming  to  the  least  com¬ 
mon  denominator  (and  there  isn’t  any 
truly  common  denominator),  you  have 
to  be  able  to  figure  out  which  board  is 


on  the  bus  before  you  go  out  and  try 
to  do  anything  adventurous  like  set  a 
mode  or,  lord  knows,  turn  the  cursor 
off. 

It’s  easier  than  it  sounds.  You  don’t 
have  to  do  anything  as  underhanded 
as  examining  bits  in  undocumented 
I/O  locations.  It’s  all  a  question  of  work¬ 
ing  with  video-specific  BIOS  calls. 

BIOS  support  for  video  exists  in  three 
layers,  corresponding  to  the  three  gen¬ 
erations  of  IBM  video  boards.  The  first 
generation  consists  of  the  original  color 
graphics  adapter  and  monochrome  dis¬ 
play  adapter.  Think  of  this  as  the  inner¬ 
most  video  BIOS  layer,  the  one  in  pla¬ 
nar  ROM.  (There  is  no  ROM  on  those 
two  first  generation  video  boards.) 

The  introduction  of  the  EGA  carried 
with  it  ROM  BIOS  enhancements  on 
the  video  board.  These  enhancements 
were  attached  to  the  main  planar  BIOS 
through  a  feature  called  ROM  scan. 
During  power-on  self-test  (POST),  the 
PC’s  BIOS  scans  memory  looking  for 
ROM  BIOS  extensions  identified  by  a 
special  signature.  In  essence,  the  INT 
10H  (video)  support  on  the  mother¬ 
board  was  replaced  by  a  software  in¬ 
terrupt  service  routine  on  the  EGA 
board,  simply  by  repointing  the  INT 
10H  vector  in  the  vector  jump  table  to 
the  routine  in  the  EGA  board’s  ROM. 

VGA  and  MCGA  BIOS  support  was 
provided  in  the  same  way  (on-board 
BIOS  connected  to  the  planar  BIOS 
through  ROM  scan),  but  it  is  a  superset 
of  the  EGA’s.  Wrapped  around  EGA, 
BIOS  support  is  a  third  layer  of  addi¬ 
tional  BIOS  video  services  that  don’t 
exist  on  any  board  prior  to  the  VGA 
and  MCGA. 

The  algorithm  for  detecting  adapters 
comes  down  to  this:  First,  identify  the 
generation  of  video  boards  by  looking 
for  each  layer.  In  other  words,  check 
for  VGA/MCGA-specific  features.  If  you 
can’t  find  that  outermost  layer,  you 
know  you  don’t  have  a  VGA  or  MCGA. 
Next,  look  for  the  second  layer,  EGA 
support.  If  you  can’t  find  that,  you  know 
you  don’t  have  an  EGA.  If  there’s  no 
EGA,  you’ve  defaulted  to  the  first  gen¬ 
eration  video  boards. 

Once  you  have  the  generation,  you 
can  use  BIOS  services  to  distinguish 
between  a  VGA  and  an  MCGA  or  be¬ 
tween  a  CGA  and  an  MDA.  Because 
the  EGA  is  the  only  board  in  its  genera- 
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STRUCTURED  PROGRAMMING 

(continued  from  page  132) 


The  Machine  Told  Me;  Note  Who 
Told  The  Machine? 

That’s  about  all  there  is  to  detecting 
standard  IBM  display  adapters.  In  most 
cases  it  devolves  to  asking  the  machine 
what  its  got.  Now,  I  can  never  quite  rid 
myself  of  the  fear  that  the  Anthropo¬ 
morphic  Fallacy  (that  is,  this  habit  of 
“asking  the  machine”  as  though  the 
machine  were  the  little  guy  behind  the 
counter  at  the  liquor  store)  will  throw 
me  a  curve.  It’s  worth  wondering  how 
the  machine  knows  what  it  has  — and 
how  likely  the  machine  is  to  be  right. 

In  the  case  of  the  EGA,  VGA,  and 
MCGA  the  machine  knows  because  dur¬ 
ing  POST,  ROM  scan  attached  the  video 
board’s  BIOS  chip  to  the  planar  BIOS. 
Because  what  you  are  doing  when  you 
are  calling  INT  10H  is  calling  a  routine 
in  a  ROM  chip  on  the  video  board,  you 
would  like  to  assume  that  the  board 
knows  what  it  is. 

If  only  IBM  made  video  boards,  that 
would  be  a  good  bet.  However,  I’ve 
seen  enough  totally  blatant  BIOS  bugs 
in  some  of  the  scruffier  Yuk  Foo  EGA 
clones  to  downgrade  that  certainty  to 
about  99  percent.  Not  enough  to  worry 
about,  but  keep  it  in  the  comer  of  your 
mind  if  a  client  ever  reports  truly  bi¬ 
zarre  behavior  on  the  part  of  your  soft¬ 
ware. 


For  the  CGA  and  MDA,  what  the 
BIOS  does  is  simply  report  the  state  of 
the  display  adapter  DIP  switches  (PC 
and  XT)  or  CMOS  RAM  bits  (AT).  Since 
human  beings  set  these  switches  or 
bits,  you’d  think  the  chances  for  error 
here  are  greater.  Not  so  — ironically,  if 
a  machine  tells  you  through  Query- 
AdapterType  that  it  contains  a  CGA  or 
MDA,  you  can  believe  it,  because  POST 
double  checks  the  switches  and  bits. 
The  MDA  and  CGA  are  fairly  simple 
creatures  whose  differences  far  out¬ 
weigh  their  similarities,  and  are  easy 
to  tell  apart  by  examining  refresh  buff¬ 
ers  and  I/O  locations. 

There  is  still  the  possibility  that  a 
weirdly  designed  CGA/MDA  combina¬ 
tion  board  might  fool  POST  into  mak¬ 
ing  the  wrong  determination,  but  I’ve 
used  a  few  such  boards  and  POST  has 
pegged  them  correctly  every  time. 

Keep  QueryAdapterType  handy.  Sev¬ 
eral  routines  and  utilities  in  upcoming 
columns  will  require  it. 

Dare  to  Hack  the  Hardware 

I  guess  I  was  marked  forever  when  I 
decided  to  wirewrap  my  first  computer 
(a  COSMAC  Elf,  lordy)  out  of  loose 
parts.  Those  people  who  view  with 
terror  the  idea  of  hooking  loose  wires 
onto  serial  or  parallel  ports  remind  me 
of  James  Thurber’s  granny,  who  wor¬ 
ried  endlessly  about  electricity  leaking 
out  of  empty  light  bulb  sockets  and 


slithering  around  the  house,  crackling 
at  her. 

Then  again,  if  you  decided  you 
wanted  your  machine  to  control  the 
motion  of  a  telescope,  what  would  you 
do?  Regardless  of  your  answer,  before 
doing  anything,  lay  hands  on  Bruce 
Eckel’s  new  book  Computer  Interfac¬ 
ing  With  Pascal  and  C.  With  wit  and 
some  superb  technical  figures,  Bruce 
captures  the  essence  of  making  elec¬ 
trons  out  of  bits  and  vice  versa.  Among 
the  described  devices  are  temperature 
sensors,  stepper  motor  drivers,  TRIAC 
switches,  digital/analog  converters 
(DACs),  op-amps,  optoisolators,  and 
numerous  others.  Most  of  the  I/O  is 
through  standard  PC  serial  and  par¬ 
allel  ports.  Bruce  does,  however,  relate 
how  to  create  your  own  PC  bus  proto¬ 
typing  board. 

Bruce  assumes  that  you  all  know 
how  to  program,  so  the  emphasis  is 
on  practical  interface  electronics.  The 
driver  code  is  in  Turbo  C  and  Turbo 
Pascal  and  is  disarmingly  simple.  Most 
of  the  interface  devices  can  be  cobbled 
together  out  of  Radio  Shack  parts  with¬ 
out  a  heavy  investment  in  money  or 
skill.  Having  done  some  of  this  stuff 
myself,  I  can  tell  you  that  it’s  easier 
than  it  may  seem.  With  Bruce’s  book 
in  front  of  you,  it  might  even  be  fun. 
Highly  recommended. 

BOO! 

It’s  Halloween,  and  I  just  handed  our 
last  Reese’s  Peanut  Butter  Cup  to  a 
six-foot  tall  cardboard  milkshake  with 
a  cowlick.  Nothing  much  more  will  get 
done  tonight,  I  suspect.  We’ll  pick  up 
the  subject  of  PC  display  adapters  next 
time.  For  now,  it’s  time  to  turn  out 
the  lights  and  go  engage  in  some  devil¬ 
try  of  my  own.  Perhaps  I’ll  be  truly 
wicked  and  scrawl  GOTO  100  on  my 
neighbor’s  garage  door  .  .  .  naw,  too 
nasty. 

Anybody  know  where  there’s  a  good 
outhouse? 

Products  Mentioned 

Computer  Interfacing  With 
Pascal  and  C 
Bruce  Eckel 
eisys 

1009  N.  36th  Str. 

Seattle,  WA  98103 
Book  $29  95  (postpaid) 

Listing  disk  $19. 95 


DDJ 


Vote  for  your  favorite  feature/article. 
Circle  Reader  Service  No.  10. 


PROCEDURE  QueryAdapterType ()  :  AdapterType; 
VAR 

Regs  :  Registers; 

Code  :  SHORTCARD; 


BEGIN 

Regs. AH  :=  1AH;  (*  Attempt  to  call  VGA  Identify  Adapter  Function  *) 

Regs .AL  :=  0;  (*  Must  clear  AL  to  0  ...  *) 

Intr (Regs, 1 OH) ; 

IF  Regs . AL  -  1AH  THEN  (*  ...so  that  if  $1A  comes  back  in  AL. . .  *) 

{*  ...we  know  a  PS/2  video  BIOS  is  out  there.  *) 
CASE  Regs.BL  OF  (*  Code  comes  back  in  BL  *) 

0  ;  RETURN  None  I 

1  :  RETURN  MDA;  I 

2  ;  RETURN  CGA;  I 

4  :  RETURN  EGAColor;  I 

5  :  RETURN  EGAMono;  I 

7  ;  RETURN  VGAMono;  I 

8  :  RETURN  VGAColor;  I 

0AH, 0CH  :  RETURN  MCGAColor;  | 

0BH  :  RETURN  MCGAMono;  I 

ELSE  RETURN  CGA 

END  (*  CASE  *) 

ELSE 

(*  If  it's  not  PS/2  we  have  to  check  for  the  presence  of  an  EGA  BIOS:  *) 
Regs. AH  :=  12H;  (*  Select  Alternate  Function  service  *) 

Regs.BX  :»  10H;  <*  BL=$10  means  return  EGA  information  *) 

Intr (Regs, 10H) ;  (*  Call  BIOS  VIDEO  *) 

IF  Regs.BX  <>  10H  THEN  (*  BX  unchanged  means  EGA  is  NOT  there...*) 
Regs. AH  :=  12H;  (*  Once  we  know  Alt  Function  exists...  *) 

Regs.BL  :=  10H;  (*  ...we  call  it  again  to  see  if  it's...  *) 

Intr (Regs, 10H) ;  (*  ...EGA  color  or  EGA  monochrome.  *) 

IF  {Regs .BH  =  0)  THEN  RETURN  EGAColor 

ELSE  RETURN  EGAMono 

END 

ELSE  (*  Now  we  know  we  have  an  CGA  or  MDA;  let's  see  which:  *) 

Intr (Regs, 11H) ;  (*  Equipment  determination  service  *) 

Code  :=  SHORTCARD (BITSET (Regs .AL)  *  BITSET{4. .5})  »  4; 

CASE  Code  OF 

1  :  RETURN  CGA  | 

2  :  RETURN  CGA  I 

3  :  RETURN  MDA 
ELSE  RETURN  None 

END  (*  Case'*) 

END 

END 

END  QueryAdapterType; 


Example  2  QUERYDSP.JPI 
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THE  FORTH  COLUMN 


The  German  Forth  community  has 
moved  a  step  closer  to  claiming  the 
domain  of  real-time  programming.  Ac¬ 
cording  to  Klaus  Schleisiek-Kern 
(DELTA-t),  a  German  real-time  congress 
with  a  strong  Forth  component  is  now 
being  planned.  Echtzeit  ’90  will  take 
place  in  Nuremberg,  the  home  of  the 
first  German  Forth  chip,  in  the  summer 
of  1990.  Sponsored  by  E-T-A  GmbH, 
the  chip  was  developed  by  Fraunhofer- 
Gesellschaft  Erlangen,  and  will  be  pro¬ 
duced  by  ELMOS  GmbH.  Klaus  will 
talk  about  it  at  the  1988  FORML  con¬ 
vention. 

In  other  Forth  news,  Friends  of  Forth 
are  invited  to  brush  up  on  their  syntax 
by  participating  in  Jack  Brown’s  ongo¬ 
ing  Forth  tutorial  on  the  British  Colum¬ 
bia  Forth  Board  (604-434-5886).  It  is 
also  being  networked  to  GENIE  (800- 
638-9636  sign-up)  and  the  East  Coast 
Forth  Board  (703-442-8695).  The  les¬ 
sons,  two  of  them  so  far,  are  well  writ¬ 
ten  and  have  excellent  examples  and 
homework  problems.  You  can  leave 
your  solutions  on  the  board  for  correc¬ 
tion  and  feedback.  The  course  is  based 
on  Tom  Zimmer’s  public-domain  F-PC 
Forth.  The  latest  version,  2.15,  is  avail¬ 
able  on  the  same  bulletin  boards,  al¬ 
though,  it  will  take  quite  a  while  to 
download  it.  Or  you  might  call  Offete 
Enterprises  (415-574-8250)  to  see  if  they 
already  have  it  on  a  low-cost  disk. 

AAA  X3J14  Meeting  Number  5 

The  ANS  Forth  Technical  Committee 
held  its  fifth  meeting  August  10  -  13  in 


Martin  Tracy 


Portland,  Ore.  For  the  first  time,  a  BA¬ 
SIS  document  was  presented  that  dif¬ 
fers  radically  in  format  from  the  Forth- 
83  Standard.  The  content  and  wording 
of  this  document,  nicknamed  “Brave 
New  Basis”  (BNB),  received  quite  a  bit 
of  attention  at  the  meeting.  Several  new 
terms  were  defined,  such  as  execution 
token ,  the  token  that  ’  (“tick”)  returns 


Forth  News 


for  EXECUTE  to  use.  You  can  get  a 
copy  of  the  latest  BASIS  by  sending  $5 
to  Martin  Tracy,  FORTH  Inc.,  Ill  N. 
Sepulveda  Blvd.,  Manhattan  Beach,  CA 
90266. 

The  meeting  dealt  with  over  70  tech¬ 
nical  proposals,  more  than  double  of 
the  previous  meeting.  There  was  a  feel¬ 
ing  that  the  BASIS  would  become  the 
draft  proposal  ANS  Forth  Standard 
(DPANS)  sometime  in  1989.  This  opti¬ 
mism  abated  somewhat  when  Charles 
Moore,  the  founder  of  the  Forth  lan¬ 
guage,  left  the  meeting  abruptly  after 
one  of  his  proposals  was  defeated.  I 
have  posted  the  draft  minutes  of  the 
meeting  and  the  current  technical  pro¬ 
posal.  Log  on  GENIE  as  files 
TCMINS5.ARC  and  TECHPROS.ARC,  re¬ 
spectively. 

Here  are  some  of  the  technical  high¬ 
lights  of  that  meeting: 

•  The  "  (quote)  string  literal  compiler 
was  added.  The  sequence  “ccc”  inside 
a  colon  definition  will  cause  the  ad¬ 
dress  and  length  of  the  string  ccc  to  be 
pushed  on  the  stack,  with  the  length 
on  top. 

•  2@,  2!,  2DUP,  2DROP,  2  SWAP, 
20VER,  2R>,  and  2>R  are  now  required 
words. 

•  ASCII  and  [ASCII]  have  been  added. 
ASCII  used  outside  of  a  definition  leaves 
the  ASCII  value  of  the  first  character  of 
the  following  word  on  the  stack. 

•  [ASCII]  has  an  equivalent  action  for 
use  within  a  definition. 

•  A  floating-point  extension  was  added. 
It  includes  the  functions  F+,  F-,  F*,  F/, 
F0<,  F0=,  F<  ;  the  memory  access  words 
F@  and  F!;  the  (separate)  stack  manipu¬ 


lators  FDUP,  FDROP,  FSWAP,  FOVER, 
and  FROT ;  and  the  defining  words  FCON- 
STANT  and  FVARIABLE.  At  present, 
there  is  no  proposal  for  floating-point 
input  or  output,  nor  is  there  any  way 
to  make  a  floating-point  number. 

•  The  text  file  operators  READ-LINE 
and  WRITE-CR  have  been  added  to  the 
file  extension. 

The  next  ANS  X3J14  committee  meet¬ 
ing  is  scheduled  for  the  end  of  January 
1989-  It  will  be  held  in  Los  Angeles, 
Calif.,  and  is  hosted  by  Ray  Duncan  of 
Laboratory  Microsystems.  Observers  are 
welcome.  Call  chair  Elizabeth  Rather 
at  FORTH  Inc.  (213-372-8493)  if  you 
are  planning  to  attend. 

1988ASYST 

International  Conference 

The  first  ASYST  International  Confer¬ 
ence  took  place  October  9-10  at  the 
University  of  Rochester,  N.Y.  ASYST  is 
one  of  the  better  known  data  acquisi¬ 
tion  and  analysis  packages  and  fea¬ 
tures  a  flexible  graphics  interface,  disk 
data  library  support,  and  a  rich  library 
of  mathematical  functions,  from  statis¬ 
tics  to  signal  processing.  And  best  of 
all,  it’s  programmable!  ASYST  is  written 
in  Forth,  and  much  of  the  language  is 
accessible  at  the  user  level. 

To  create  a  four-cycle,  256-point  sine 
wave,  for  example,  you  would  first  make 
an  array  of  256  successive  integers:  256 
REAL  RAMP 

The  elements  generated  by  RAMP 
range  from  1  to  256  and  are  located 
somewhere  in  a  heap.  A  token  repre¬ 
senting  this  array  is  left  on  the  stack. 
To  adjust  the  integers  to  range  from  0 
to  255,  subtract  one:  1  - 

The  subtraction  operator  knows  to 
subtract  the  scalar  one  from  each  ele¬ 
ment  in  the  array.  A  token  pointing  to 
the  resulting  array  is  left  on  the  stack. 
The  index  array  is  then  normalized  to 
range  from  0  to  a  little  less  than  2  PI: 

256  /  2  *  PI  * 

Finally,  take  four  times  the  sine  of  each 
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element: 

RAD  4  *  SIN 

To  duplicate  the  array  and  plot  is  a 
simple  matter: 

DUP  Y.AUTO.PLOT 

Of  course,  this  could  all  be  compiled 
into  a  colon  definition: 

:  FOURSINE  ( -  array) 

256  REAL  RAMP  1  -  256  / 

2  *  PI  *  4  *  SIN 
DUP  Y.AUTO.PLOT  ; 

ASYST  supports  the  GPIB  bus  and 
more  than  two  dozen  IBM  PC  data 
acquisition  and  control  drop-in  boards. 
I  was  impressed  by  their  (copyrighted) 
DAS  driver  specification,  which  de¬ 
scribes  a  logical  data  acquisition  and 
control  board  — timers,  triggers,  multi¬ 
channel  A/D,  DMA,  the  whole  nine 
yards.  This  specification  is  not  included 
in  the  ASYST  package  but  comes  with 
the  notice  that  “ASYST  authorizes  any 
person  or  entity  in  possession  of  this 
specification  to  reproduce  and  distrib¬ 
ute  copies  of  this  specification  free  of 
charge,  provided  that  such  copies  are 


complete  and  entire  and  contain  all 
copyright  notices  indicating  ASYST’s 
ownership  of  the  copyright  as  are  con¬ 
tained  in  the  original.”  Call  them  at 
716-272-0070. 

The  conference  was  smoothly  exe¬ 
cuted  by  veteran  Larry  Forsely,  who 
also  puts  together  the  Rochester  Forth 
Conference.  Here  are  some  of  the  pa¬ 
pers  you  missed: 

“A  General  Purpose  Stimulus  Pres¬ 
entation  and  Data  Acquisition  System 
for  the  Cognitive  Psychology/Evoked 
Potential  Laboratory,”  by  Dr.  George 
Fein,  UC  San  Francisco. 

“Femtosecond  Spectroscopy  with 
ASYST,”  by  Wayne  Know,  AT&T  Bell 
Labs. 

“Cables  and  Bits  (the  assessment  of 
lung  dysfunction),”  by  Dr.  Daniel 
Rayburn,  Walter  Reed  Institute  of  Re¬ 
search. 

There  were  more  than  40  papers  in 
all,  an  impressive  technical  program 
for  a  first  conference.  I  will  let  you 
know  when  the  proceedings  are  avail¬ 
able. 

A  Simple  Mandelbrot 

Hats  off  this  month  to  Marc  Hawley  for 
his  elegantly  simple  Mandlebrot  pro¬ 
gram.  The  plotting  routines,  in  their 


entirety,  can  be  found  on  screen  2  (see 
Listing  One,  page  149).  They  use  DOS 
calls  to  plot  pixels  on  an  IBM  high- 
resolution  (black  and  white)  graphics 
screen,  but  you  could  alter  them  for 
fancier  pictures.  The  routine  itself  is 
on  screen  3.  Several  different  views  are 
developed  by  simply  copying  the  screen 
and  editing  the  parameters.  The  famil¬ 
iar  inkblot  appears  from  one  to  ten 
minutes  after  execution.  The  MAN- 
DLZEN.ARC  file  itself  was  downloaded 
from  the  GENIE  FORTH  bulletin  board. 

Availability 

All  source  code  for  articles  in  this  issue 
is  available  on  a  single  disk.  To  order, 
send  $14.95  (Calif,  residents  add  sales 
tax)  to  Dr.  Dobb’s Journal ,  501  Galve¬ 
ston  Dr.,  Redwood  City,  CA  94063,  or 
call  800-356-2002  (inside  Calif.)  or  800- 
533-4372  (outside  Calif.).  Please  spec¬ 
ify  the  issue  number  and  format  (MS- 
DOS,  Macintosh,  Kaypro). 


DDJ 

(Listing  begins  on  page  149.) 

Vote  for  your  favorite  feature/article. 
Circle  Reader  Service  No.  13. 
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C  PROGRAMMING 


Listing  One  (Text  begins  on  page  1 1 5.) 

/* - serial. h - 

*  Serial  Port  Definitions 
*/ 

extern  int  ticker,  COMPORT; 
extern  char  *nextin,  *nextout; 

/* - serial  prototypes - */ 

void  initcomport (void) ; 

int  readcomm(void) ; 

int  writ ecomm( int ) ; 

void  clear_serial_queue (void) ; 

/* - timer  prototypes - */ 

void  sleep (unsigned) ; 
int  set_timer (unsigned) ; 
void  intercept_timer (void) ; 
void  restore_timer (void) ; 
void  restore_serialint (void) ; 

/* - macros - */ 

♦define  constat ()  (inp (LINESTATUS) ) 

♦define  input_char_ready ( )  (nextin ! =nextout) 

♦define  timed_out()  (ticker==0) 

♦define  set_timer (secs)  ticker=secs*l82/10+l 
♦define  XON  17 
♦define  XOFF  19 

/*  -  serial  port  addresses  - 

/*  -  8250  UART  base  port  address:  COM1  =  3f8,  COM2 
♦  define  BASEPORT  (0x3f 8- ( (COMPORT-1)  «8) ) 

♦define  TXDATA  BASEPORT  /*  transmit  data 

♦define  RXDATA  BASEPORT  /*  receive  data 

♦define  DIVLSB  BASEPORT  /*  baud  rate  divi 

♦define  DIVMSB  (BASEPORT+1)  /*  baud  rate  divi 

♦define  INTENABLE  (BASEPORT+1)  /*  interrupt  enab 

♦define  INTIDENT  (BASEPORT+2)  /*  interrupt  iden 

♦define  LINECTL  (BASEPORT+3)  /*  line  control 

♦define  MODEMCTL  (BASEPORT+4)  /*  modem  control 

♦define  LINESTATUS  (BASEPORT+5)  /*  line  status 


♦define  MODEMSTATUS  (BASEPORT+6) 


♦define  IRQ 
♦define  COMINT 
♦define  COMIRQ 
♦define  PIC01 
♦define  PIC00 
♦define  EOI 
♦define  TIMER 
/* - 


BASEPORT  /*  transmit  data  */ 

BASEPORT  /*  receive  data  */ 

BASEPORT  /*  baud  rate  divisor  lsb  */ 

(BASEPORT+1)  /*  baud  rate  divisor  msb  */ 

E  (BASEPORT+1)  /*  interrupt  enable  */ 

(BASEPORT+2)  /*  interrupt  ident'n  */ 

(BASEPORT+3)  /*  line  control  */ 

(BASEPORT+4)  /*  modem  control  */ 

US  (BASEPORT+5)  /*  line  status  */ 

,TUS  (BASEPORT+6)  /*  modem  status  */ 

—  serial  interrupt  stuff  -  * 

(4- (COMPORT-1) )  /*  0-7  =  IRQ0-IRQ7  V 

(12- (COMPORT-1))  /*  interrupt  vector  12/11* 
(-(1  «  IRQ)) 

0x21  / * 8259  Programmable  Interrupt  Controller* 
0x20  /*  "  "  "  "  * 

0x20  /*  End  of  Interrupt  command  V 

Oxlc  /*  PC  timer  interrupt  vector  *. 

—  line  status  register  values  -  * 


♦define  XMIT_DATA_READY  0x20 

/*  -  modem  control  register  values  - 

♦define  DTR  1 
♦define  RTS  2 
♦define  OUT2  8 

/*  -  interrupt  enable  register  signals 

♦define  DATAREADY  1 

/*  -  serial  input  interrupt  buffer  — 

♦define  BUFSIZE  1024 

♦define  SAFETYLEVEL  (BUFSIZE/4) 

♦define  THRESHOLD  (SAFETYLEVEL* 3) 

♦ifndef  TRUE 
♦define  TRUE  1 
♦define  FALSE  0 
♦endif 


Listing  Two 


/* - serial. c - 

*  Serial  Port  Communications  Functions 
*/ 

♦include  <stdio.h> 

♦include  <conio.h> 

♦include  <dos.h> 

♦include  "serial. h" 

♦if  COMPILER  ==  MSOFT 
♦define  getvect  _dos_getvect 
♦define  setvect  _dos_setvect 
♦endif 

char  recvbuff [BUFSIZE] ; 
char  ‘nextin  =  recvbuff; 
char  *nextout  =  recvbuff; 
int  buffer_count; 

int  COMPORT  =1;  /*  COM1  or  COM2 

int  PARITY  =  0;  /*  0  =  none,  1  =  odd,  2  =  even 

int  STOPBITS  =1;  /*  1  or  2 

int  WORDLEN  =8;  /*  7  or  8 

int  BAUD  =  1200;  /*  110,150,300,600,1200,2400 

int  TIMEOUT  =  10;  /*  number  of  seconds  to  time  out 

int  xonxoff_enabled  =  TRUE; 

static  int  waiting_for_XON; 

static  int  waiting_to_send_XON; 

int  ticker; 

/*  -  the  com  port  initialization  parameter  byte 

static  union  { 
struct  ( 

unsigned  wordlen  :  2; 
unsigned  stopbits  :  1; 
unsigned  parity  :  3; 
unsigned  brk  :  1; 

unsigned  divlatch  :  1; 

}  initbits; 
char  initchar; 

}  initcom; 


static  void  (interrupt  far  *oldtimer) (void) ; 
static  void  interrupt  far  newtimer (void) ; 
static  void  (interrupt  far  *oldcomint) (void) ; 
static  void  interrupt  far  newcomint (void) ; 

/* - initialize  the  com  port - */ 

void  initcomport (void) 

{ 

initcom. initbits. parity  =  PARITY  ==  2  ?  3  :  PARIT 

initcom. initbits. stopbits  =  STOPBITS-1; 

initcom. initbits . wordlen  =  WORDLEN-5; 

initcom. initbits .brk  =  0; 

initcom. initbits .divlatch  =  1; 

outp (LINECTL,  initcom. initchar) ; 

outp (DIVLSB,  (char)  ( (115200L/BAUD)  &  255)); 

outp (DIVMSB,  (char)  ( (115200L/BAUD)  »  8)); 

initcom. initbits .divlatch  =  0; 

outp (LINECTL,  initcom. initchar) ; 

/* - hook  serial  interrupt  vector - */ 

if  (oldcomint  ==  NULL) 

oldcomint  =  getvect (COMINT) ; 
setvect (COMINT,  newcomint) ; 

outp (MODEMCTL,  (inp (MODEMCTL)  |  DTR  |  RTS  |  OUT2) ) ; 
outp (PIC01,  (inp (PIC01 )  &  COMIRQ)); 
outp ( INTENABLE,  DATAREADY) ; 
outp (PIC00,  EOI); 

/* - flush  any  old  interrupts - */ 

inp (RXDATA) ; 
inp (INTIDENT) ; 
inp (LINESTATUS) ; 
inp (MODEMSTATUS) ; 


/*  -  restore  the  serial  interrupt  vector 

void  restore_serialint (void) 


if  (oldcomint) 

setvect (COMINT,  oldcomint); 


/*  -  clear  the  serial  input  buffer 

void  clear_serial_queue (void) 


nextin  =  nextout  =  recvbuff; 
buffer  count  =  0; 


/*  -  serial  input  interrupt  service  routine  -  */ 

static  void  interrupt  far  newcomint (void) 

( 

int  c; 

outp (PIC00, EOI) ; 

if  (nextin  ==  recvbuff +BUFSIZE) 

nextin  =  recvbuff;  /*  circular  buffer  */ 

c  =  inp (RXDATA) ;  /*  read  the  input  */ 

if  (xonxoff_enabled) 

if  (c  ==  XOFF)  /*  test  XON  */ 

waiting_for_XON  =1; 

else  if  (c  ==  XON)  /*  test  XOFF  */ 

waiting_for_XON  =  0; 

if  (Ixonxoff  enabled  I  I  (c  !=  XON  &&  c  !=  XOFF))  { 


End  Listing  One 


*nextin++  =  (char)  c; 
buffer  count++; 


/*  put  char  in  buff*/ 


if  (xonxof f_enabled  &&  ! waiting_to_send_XON  && 
buf fer_count  >  THRESHOLD)  ( 
while  ( (inp (LINESTATUS)  &  XMIT_DATA_READY )  ==  0) 


outp (TXDATA,  XOFF); 
waiting_to_send_XON  =  1; 


/*  send  XOFF 


/*  -  read  a  character  from  the  input  buffer  -  */ 

int  readcomm(void) 

( 

set_timer (TIMEOUT) ; 

while  ( ! input_char_ready ( ) ) 
if  (timed_out () ) 
return  FALSE; 

if  (nextout  ==  recvbuf f+BUFSIZE) 
nextout  =  recvbuff; 

— buffer_count; 

if  (waiting_to_send_XON  &&  buffer_count  <  SAFETYLEVEL)  ( 
waiting_to_send_XON  =  0; 
writecomm (XON) ; 

} 

return  *nextout++; 


/*  -  write  a  character  to  the  comm  port  -  */ 

int  writecomm (int  c) 

{ 

while  (waiting_for_XON) 
set _timer (TIMEOUT) ; 

while  ( (inp (LINESTATUS)  &  XMI T_DATA_RE AD Y )  ==  0) 
if  (timed_out () ) 
return  FALSE; 
outp (TXDATA,  c); 
return  TRUE; 


/*  -  intercept  the  timer  interrupt  vector  -  */ 

void  intercept_timer (void) 

{ 

if  (oldtimer  ==  NULL)  ( 

oldtimer  =  getvect (TIMER) ; 
setvect (TIMER,  newtimer); 
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/* - sleep  for  n  seconds - * / 

void  sleep (unsigned  secs) 

{ 

set_timer (secs) ; 
while  ( !timed_out () ) 

) 

/*  -  restore  timer  interrupt  vector  -  */ 

void  restore_timer () 

{ 

if  (oldtimer) 

setvect (TIMER,  oldtimer) ; 

} 

/* - ISR  to  count  timer  ticks - */ 

static  void  interrupt  far  newtimer() 

{ 

( ‘oldtimer )  () ; 
if  (ticker) 

— ticker; 

} 

End  Listing  Two 


Listing  Three 

/* - modem,  h - 

*  Modem  Definitions 
*/ 

/*  -  Hayes  modem  control  strings  -  */ 

♦define  RESETMODEM  "ATZ\r~" 

♦define  INITMODEM  ”ATE0MlS7=60Sll=55VlX3S0=0\r~" 

♦define  HANGUP  "~+++~ATH0\r~ATS0-0\r~" 

♦define  ANSWER  "ATS0=l\r~" 

/* - prototypes - */ 

void  initmodem (void) ; 
void  placecall (void) ; 
void  answercall (void) ; 
void  disconnect (void) ; 
void  release_modem(void) ; 

End  Listing  Three 


Listing  Four 

/* - modem,  c - */ 

♦include  <dos.h> 

♦include  <conio.h> 

♦include  "serial. h" 

♦include  "modem. h" 

char  DIAL [ ]  =  "ATDT"; 
char  PHONENO [21 ] ; 

int  direct_connection;  /*  true  if  connected  without  a  modem  */ 

/* - write  a  command  to  the  modem - */ 

static  void  modout(char  *s) 

{ 

while(*s)  { 

if  (*s  ==  '-') 
sleep (1) ; 

else  if  ( ! writecomm (*s) ) 
break; 

s++; 

} 

) 

/* - initialize  the  modem - */ 

void  initmodem (void) 

( 

intercept_timer () ; 
initcomport () ; 

if  ( !direct_connection)  ( 
modout (RESETMODEM) ; 
modout (INITMODEM) ; 

) 

) 

/* - release  the  modem - *  / 

void  release_modem (void) 

{ 

if  ( !direct_connection) 
modout (RESETMODEM) ; 
restore_timer () ; 
restore_serialint () ; 

} 

/* - place  a  call - */ 

void  placecall (void) 

{ 

if  ( !direct_connection)  { 
modout (DIAL) ; 
modout (PHONENO) ; 
modout ("\r") ; 
clear_serial_queue () ; 

} 

) 


/* - answer  a  call - */ 

void  answercall (void) 

{ 

if  ( !direct_connection)  ( 

modout (ANSWER) ; 
clear_serial_queue () ; 

} 

} 

/* - disconnect  the  call - */ 

void  disconnect (void) 

( 

if  ( !direct_connection)  { 

modout (HANGUP) ; 
clear_serial_queue ( ) ; 

} 

1  End  Listing  Four 


Listing  Five 

/* - tiny  comm,  c - */ 

♦include  <stdio.h> 

♦include  <string.h> 

♦include  <ctype.h> 

♦include  <conio.h> 

♦include  <stdlib.h> 

♦include  <dos.h> 

♦include  "serial. h" 

♦include  "modem. h" 

♦if  COMP I LER==MSOFT 
♦define  getch  mscgetch 
♦define  putch  mscputch 
♦define  gets  mscgets 
static  void  mscgets (char  *); 
static  int  mscgetch (void) ; 
static  void  mscputch (int) ; 
static  void  gotoxy (int, int) ; 
static  void  clrscr (void) ; 

♦endif 

int  keyhit (void) ; 

♦define  TMSG  "\r\n\r\nTINYCOMM:  «  Is  »\r\n" 

♦define  LOGFILE  "tinycomm.log" 

♦define  ESC  27 

extern  char  PHONENOU; 

extern  int  COMPORT; 

static  FILE  ‘logfp; 

static  FILE  ‘uploadfp; 

static  int  running=l; 

static  int  connected, answering; 

static  int  forcekey,  forcecom,  forcemenu; 

static  union  REGS  rg; 

/* - prototypes - */ 

static  void  tinymenu (void) ; 
static  void  log (int); 
static  void  upload (void) ; 

void  main (int  argc,  char  *argv(]) 

{ 

int  c; 

if  (argc  >  1) 

COMPORT  =  atoi (argv [ 1 ] ) ; 
if  (argc  >  2) 

strcpy (PHONENO,  argv[2]); 
initmodem () ; 
while  (running)  ( 

if  (! connected  I  I  forcemenu)  ( 
forcemenu  =  0; 

tinymenu ();  /*  display  and  process  the  menu  */ 

) 

/* - poll  for  a  keystroke - * / 

if  (keyhit ()  ||  forcekey)  { 

c  =  forcekey  ?  forcekey  :  getch (); 
forcekey  =  (answering  &&  c  ==  '\r')  ?  '\n'  :  0; 
if  (c  ==  ESC) 
tinymenu () ; 

else  if  (connected)  { 
if  (answering) 

log(c);  /*  answerer  echos  his  own  key  */ 
writecomm(c) ;  /*  transmit  the  keystroke  */ 

) 

} 

/* - poll  for  serial  input - */ 

if  (input_char_ready ()  II  forcecom)  { 
c  =  forcecom  ?  forcecom  :  readcomm(); 
forcecom  =  (answering  &&  c  ==  '\r' )  ?  ' \n'  :  0; 
log(c);  /*  display  the  serial  input  */ 

if  (answering) 

writecomm(c) ;  /*  answerer  echos  serial  input  */ 

} 

) 

release_modem ( ) ; 

} 

/* - display  and  process  the  TINYCOMM  menu - */ 

static  void  tinymenu (void) 

{ 

int  c; 
clrscr () ; 

gotoxy  (20,5) ,  cprintf(" - TINYCOMM  Menu - "); 

gotoxy (20, 7) ,  cprintf ("P-lace  Call"); 
gotoxy (20, 8) ,  cprintf ("A-nswer  Call"); 
gotoxy (20, 9) ,  cprintf ("H-ang  Up"); 

(continued  on  page  140) 
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Listing  Five  (Listing  continued,  text  begins  on  page  115  ) 

gotoxy(20,10) ,  cprintf ("L-og  Input  %s", 

logfp  ==  NULL  ?  "[OFF]"  :  "[ON]"); 
gotoxy (20, 11) ,  cprintf ("S-end  Message  File"); 
gotoxy (20, 12) ,  cprintf ("T-elephone  Number  (%s)", 

PHONENO [0]  ?  PHONENO  :  "???-????"); 
gotoxy (20, 13) ,  cprintf ("E-xit  to  DOS"); 
gotoxy (20, 14) ,  cprintf (connected  ? 

"Esc  to  return  to  session"  :  ""); 
gotoxy (20, 16) ,  cprintf ("Enter  Selection  >  "); 
c  =  getch() ; 
putch (toupper (c) ) ; 
switch  (toupper (c))  { 

case  'P':  /*  Place  a  call  */ 

if  (! connected)  ( 

cprintf (TMSG,  "Dialing"); 
initmodem ( ) ;  /*  initialize  the  modem  */ 

placecall();  /*  dial  the  phone  number  */ 
connected  =1; 

cprintf (TMSG,  "Esc  for  the  menu"); 


break; 

case  'A':  /*  Answer  a  call  */ 

if  (! connected)  ( 

cprintf (TMSG,  "Waiting") ; 

initmodem ();  /*  initialize  the  modem  */ 

answercall () ;  /*  wait  for  an  incoming  call  */ 
answering  =  connected  =1; 
cprintf (TMSG,  "Esc  for  the  menu"); 


break; 

case  ESC:  /*  Return  to  the  session  */ 

if  (connected) 

cprintf (TMSG,  "Esc  for  the  menu"); 
break; 

case  'L':  /*  Log  input  on/off*/ 

if  (logfp  ==  NULL) 

logfp  =  fopen (LOGFILE,  "a"); 
else  { 

fclose (logfp) ; 
logfp  =  NULL; 

) 

forcemenu++; 
break; 

case  'E':  /*  Exit  to  DOS  */ 

cprintf (TMSG,  "Exiting"); 
running  =  0; 

case  'H' :  /*  Hang  up  */ 

if  (connected)  { 

cprintf (TMSG,  "Hanging  up"); 
disconnect () ; 

connected  -  answering  =  0; 


break; 

case  'S':  /*  Send  a  message  file  */ 

upload () ; 
break; 

case  'T':  /*  Change  the  phone  number  */ 

cprintf (TMSG,  "Enter  Telephone  Number:  "); 
gets (PHONENO) ; 
forcemenu++; 
break; 

default: 

putch (7) ; 
break; 


/* - upload  an  ASCII  file - */ 

static  void  upload (void) 

{ 

char  filename [ 65 ] ; 
int  c  =  0; 

if  (uploadfp  ==  NULL  &&  connected)  { 

cprintf (TMSG,  "Enter  file  drive :path\\name  >  "); 
gets (filename) ; 

if  ((uploadfp  =  fopen (filename,  "r"))  ==  NULL) 
cprintf (TMSG,  "Cannot  open  file"); 
else  { 

cprintf (TMSG,  "Press  Esc  to  stop  sending  file" 
while  ((c  =  fgetc (uploadfp) )  !=  EOF)  ( 
if  (c  ==  '\n' )  ( 

writecomm(' \r' ) ; 

log  (answering  ?  '\r'  :  readcommO); 

) 

writecomm (c) ; 

log  (answering  ?  c  :  readcommO); 
if  (keyhitO) 

if  (getchO  ==  ESC)  { 

cprintf (TMSG,  "Abandoning  file"); 
break; 


#if  COMP I LER==TURBOC 

/* - use  bios  to  test  for  a  keystroke 

int  keyhitO 

{ 

rg.h.ah  =  1; 

int86(0xl6,  &rg,  Srg) ; 

return  ((rg.x. flags  &  0x40)  ==  0); 


#else 

/* - substitute  for  getch  for  MSC 

static  int  mscgetch (void) 

{ 

rg.h.ah  =  0; 
int86(0xl6,  &rg,  &rg) ; 
return  rg.h.al; 

} 


/* - substitute  for  putch  for  MSC 

static  void  mscputch(int  c) 

{ 

rg.x. ax  =  OxOeOO  |  (c  &  255); 
rg.x.bx  =  0; 
int86(0xl0,  &rg,  &rg) ; 


/*  -  gotoxy  clone  - 

static  void  gotoxy (int  x,  int  y) 

{ 

rg.h.ah  =  2; 
rg.x.bx  =  0; 
rg.h.dh  =  (char)  y-1; 
rg.h.dl  =  (char)  x-1; 
int86(0xl0,  &rg,  &rg) ; 


/*  -  clrscr  clone  - 

static  void  clrscr (void) 

{ 

rg.x. ax  =  0x0600; 
rg.h.bh  =  7; 
rg.x.cx  -  0; 

rg.x.dx  =  (24  «  8)  +  79; 
int86(0xl0,  &rg,  &rg) ; 


/* - - —  gets  clone  — 

static  void  mscgets(char  *s) 

{ 

int  c; 

while  (1)  ( 

if  ( (c  =  mscgetch  () ) 
break; 

mscputch  (c) ; 

*s++  =  (char)  c; 


End  listing  Five 


Listing  Six 


;  Use  this  in  MSC  C  programs  in  place  of  kbhit 
;  This  function  avoids  Ctrl-Break  aborts 

_text  segment  para  public  'code' 
assume  cs:_text 
public  _keyhit 
_keyhit  proc  near 

mov  ah, 1 

int  16h 

mov  ax,l 

jnz  keyret 

mov  ax, 0 

keyret :  ret 
_keyhit  endp 
_text  ends 
end 

Listing  Seven 

tinycomm  (serial. h,  modem. h) 
modem  (serial.h,  modem. h) 
serial  (serial.h) 

Listing  Eight 


End  listing  Six 


End  Listing  Seven 


I  TINYCOMM. MAK:  make  file  for  TINYCOMM.EXE  with  Microsoft  C/MASM 


fclose (uploadfp)  ; 
uploadfp  ==  NULL; 


.c.obj : 

Cl  /DMSOFT=l  /DCOMPILER=MSOFT  -c  -W3  -Gs  $*.c 


/*  -  echo  modem  or  keyboard  input  and  write  to  log  • 

static  void  log (int  c) 

{ 

putch (c) ; 
if  (logfp) 

fputc(c,  logfp); 


Clone  functions  to  keep  Ctrl-Break  from  crashing  the 
system  by  aborting  before  interrupt  vectors  get  restored 


tinycomm. obj  :  tinycomm. c  serial.h  modem. h  window. h 

modem. obj  :  modem. c  serial.h  modem. h 

serial. obj  :  serial. c  serial.h 

keyhit.obj  :  keyhit.asm 
masm  /MX  keyhit; 

tinycomm.exe  :  tinycomm. obj  modem. obj  serial. obj  keyhit.obj 
link  tinycomm+modem+serial+keyhit, tinycomm, , \lib\slibce 


End  Listings 
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Listing  One  (  Text  begins  on  page  121.) 


;  DRAWPT.ASM:  Writes  pixel  directly  to  6845  Video  Controller 
;  Microsoft  MASM  5 . 1 
;  C  prototype  is 

;  void  far  draw_point  (int  x,  int  y) ; 

;  To  be  included  in  GRAFIX.LIB 

;  K.  Porter,  DDJ  Graphics  Programming  Column,  February  '89 

.MODEL  LARGE 
.CODE 

PUBLIC  _draw_point 

;  Externals  in  GRAFIX.LIB 

EXTRN  _colorl  :  BYTE  ;  Pixel  color  reg  value 

EXTRN  _vuport  :  WORD  ;  far  ptr  to  vuport  structure 

;  Arguments  passed  from  C 


_draw_point 

push 

mov 


PROC  FAR 
bp 

bp,  sp 


Point  ES:[BX]  to  vuport  structure 
mov  ax,  _vuport+2 

mov  es,  ax 

mov  bx,  _vuport 

Clip  if  coordinates  outside  viewport 


jl 

jmp 

checkx:  mov 
cmp 

jl 

jmp 


cx,  y 

cx,  es:[bx+6] 
checkx 
exit 
ax,  x 

ax,  es:[bx+4] 


Arguments  passed  from  C 


;  Entry  processing 


get  pointer  segment 


get  y 

is  y  within  viewport? 
ok  if  so 
else  quit 
get  x 

is  x  within  viewport? 
ok  if  so 
else  quit 


Map  pixel  coordinates  to  current  viewport 


remap :  add 
mov 
add 
mov 


ax,  es: [bx] 

x,  ax 

cx,  es:[bx+2] 

y,  cx 


Point  ES  to  video  memory  segment 

mem:  mov  ax,  OAOOOh 

mov  es,  ax 

Row  offset  =  y  *  80; 
mov  bx,  y 

mov  ax,  80 

mul  bx 

mov  bx,  ax 

Column  offset  =  x  SHR  3 
mov  ax,  x 

mov  cl,  3 

shr  ax,  cl 

Complete  address  of  pixel  byte 
add  bx,  ax 

Build  bit  mask  for  pixel 
mov  cx,  x 

and  cx,  7 


Use  write  mode  2  (single-pixel  update) 
mov  dx,  03CEh 

mov  al,  5 

mov  ah,  2 

out  dx,  ax 

Set  6845  bit  mask  register 
mov  al,  8 

mov  ah,  cl 

out  dx,  ax 


;  offset  x  by  vuport. left 
;  save  remapped  X 
;  offset  y  by  vuport. top 
;  save  remapped  Y 


Get  y  argument 


Draw  the  pixel 


al,  es : [bx] 
al,  al 

byte  ptr  es : [bx] , 
al,  _colorl 
es : [bx] ,  al 


Result  in  AX 
Row  offset  in  BX 


Get  x 

Shift  operand 
Column  offset 


Get  x  again 

Isolate  low-order  bits 
Number  of  bits  to  shift 
Start  bit  mask 
Shift  for  pixel 
Save  it 


;  6845  command  register 
;  Specify  mode  register 
;  Write  mode  2 
;  Send 


;  Specify  bit  mask  register 
;  al  =  mask 
;  Send  bit  mask 


Load  6845  latch  registers 
Clear 

Zero  the  pixel  for  replace 
Get  the  pixel  value 
Write  the  pixel 


Restore  video  controller  to  default  state 
mov  dx,  03CEh 

mov  ax,  0005h  ;  write  mode  0,  read  mode  0 

out  dx,  ax 

mov  ax,  0FF08h  ;  default  bit  mask 

out  dx,  ax 

mov  ax,  0003h  ;  default  function  select 


dx, 

03CEh 

ax, 

0005h 

dx, 

ax 

ax, 

0FF08h 

dx, 

ax 

ax, 

0003h 

dx, 

ax 

ax, 

ax 

dx. 

ax 

ax. 

OOOlh 

dx. 

ax 

dx. 

03C4h 

ax. 

0F02h 

dx. 

ax 

sp, 

bp 

;  zero  Set /Reset 
;  zero  Enable  Set/Reset 


;  6845  address  reg 
;  Data  reg,  enable  all  planes 


107 |  pop  bp 

108|  retf 

109|  _draw_point  ENDP 
HOI  END 


Listing  Two 

/*  Include  file  for  GRAFIX.LIB  */ 
/*  EGA/VGA  graphics  subsystem  */ 
/*  K.  Porter,  DDJ  Graphics  Programming  Column  */ 
/* - - */ 


End  Listing  One 


/*  Supported  video  modes  */ 

♦define  EGA  0x10  / 

♦define  VGA16  0x11  / 

/*  Function  prototypes  */ 

/*  From  February,  '89  */ 

I* - */ 

int  far  init_video  (int  mode); 
void  far  pc_textmode  (void) ; 
void  far  drawjpoint  (int  x,  int  y) ; 
void  far  set_colorl  (int  palettereg) ; 


Listing  Three 


/*  EGA  640  x  350,  16/64  colors  */ 
/*  VGA  640  x  480,  16/64  colors  */ 


/*  init  display  in  video  mode  */ 

/*  PC  text  mode  */ 

/*  write  pixel  in  colorl  */ 

/*  set  foreground  color  */ 

End  Listing  Two 


/*  Library  source  file  GRAFIX.C  */ 
/*  EGA/VGA  graphics  subsystem  */ 
/*  Following  library  routines  are  external:  */ 
/*  DRAWPT.ASM  Feb  '89  */ 
/*  K.  Porter,  DDJ  Graphics  Programming  Column  */ 


♦include  <dos.h> 

♦include  <stdlib.h> 

♦include  <string.h> 

♦include  <stdio.h> 

♦include  "grafix.h" 

♦if  ! defined  TRUE 
♦define  FALSE  0 
♦define  TRUE  [FALSE 
♦endif 

/*  viewport  structure  */ 
typedef  struct  { 

int  left,  top,  width,  height; 
)  VUPORT; 


/*  Variables  global 
int  colorl, 

oldmode  =  0, 
gra fixmode  = 
ega  =  FALSE, 
vga  =  FALSE, 
colormonitor 
curpos, 
text page; 
unsigned  vidmem; 
char  far  ‘vidsave; 
VUPORT  def_vp  -  [0, 
far  * vuport; 


to  this  library  */ 

/*  foreground  color 
/*  pre-graphics  mode 
0,  /*  default  graphics ' mode 

/*  equipment  Booleans 

=  FALSE, 

/*  text  cursor  position 
/*  active  text  page 
/*  video  buffer  segment 
/*  video  buffer  save  area 
0,  640,  350),  /*  default  viewport 

/*  ptr  to  current  viewport 


int  far  init_video  (int  mode) 

/*  Initializes  video  adapter  and  defaults  for  mode 
/*  Sets  up  pc_t ext mode ( )  to  be  called  on  pgm  termination 
/*  Returns  TRUE  or  FALSE  indicating  success 
/*  This  function  will  be  expanded  in  a  later  version 
{ 

union  REGS  r; 
int  result  =  FALSE; 

/*  Determine  attached  adapter  and  monitor  */ 

r.h.ah  =  OxlA;  /*  VGA  inquiry  function 

r.h.al  =  0; 

int86  (0x10,  &r,  &r) ;  /*  ROM  BIOS  call 

if  (r.h.al  ==  OxlA) 
switch  (r.h.bl)  ( 

case  4  :  ega  =  TRUE;  /*  EGA  color 

colormonitor  =  TRUE; 
break; 

case  5  :  ega  =  TRUE;  /*  EGA  mono 

break; 

case  7  :  ega  =  TRUE;  /*  VGA  mono 

vga  =  TRUE; 
break; 

case  8  :  ega  =  TRUE;  /*  VGA  color 

vga  =  TRUE; 
colormonitor  =  TRUE; 


/*  VGA  color 


else  { 

r.h.ah  =  0x12; 
r.x.bx  =  0x10; 
int86  (0x10,  &r,  &r) ; 
if  (r.x.bx  !=  0x10)  ( 
ega  =  TRUE; 
r.h.ah  =  0x12; 
r.h.bl  =  0x10; 
int86  (0x10,  &r,  Sr); 
if  (r.h.bl  !=  0) 

colormonitor  =  TRUE; 

) 


No  VGA,  so  check  for  EGA  : 


if  EGA  present . . . 
/*  set  flag 


find  out  which  monitor 


/*  EGA  color 
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80| 

) 

811 

82| 

/*  Proceed  only  if  EGA  or  VGA  present  */ 

831 

if  (ega  I  vga)  { 

84  | 

set  colorl  (15); 

/*  default  pixel  color  */ 

851 

vuport  =  &def  vp; 

/*  default  viewport  */ 

86| 

87  | 

r.h.ah  =  OxOF; 

/*  get  current  screen  mode  */ 

881 

int86  (0x10,  &r,  &r) ; 

891 

oldmode  =  r.h.al; 

/*  store  it  */ 

90| 

textpage  =  r.h.bh; 

/*  also  active  text  page  */ 

911 

92| 

if  (colormonitor) 

/*  point  to  video  memory  */ 

93| 

vidmem  =  0xB800; 

94  | 

else 

95| 

vidmem  =  OxBOOO; 

961 

vidsave  =  malloc  (4096); 

/*  allocate  save  area  */ 

97| 

movedata 

/*  save  text  screen  contents  */ 

981 

(vidmem,  0,  FP_SEG  (vidsave),  FP  OFF  (vidsave),  4096); 

1001 

r.h.ah  =  3; 

/*  get  text  cursor  position  */ 

1011 

r.h.bh  =  textpage; 

102| 

int86  (0x10,  &r,  &r); 

1031 

curpos  =  r.x.dx; 

/*  and  save  it  */ 

104  | 

1051 

if  ( (mode  ==  EGA)  &&  ega) 

{ 

1061 

r.h.ah  =  0; 

107| 

r.h.al  =  mode; 

/*  set  EGA  mode  */ 

108| 

int86  (0x10,  &r,  &r) ; 

1091 

grafixmode  =  mode; 

/*  save  mode  */ 

1101 

atexit  (pc  textmode) ; 

/*  register  exit  function  */ 

nil 

result  =  TRUE; 

112| 

)  else 

1131 

if  ( (mode  ==  vga)  &&  vga)  ( 

114  | 

r.h.ah  =  0; 

1151 

r.h.al  =  mode; 

1161 

int86  (0x10,  &r,  &r); 

117| 

grafixmode  =  mode; 

118| 

atexit  (pc  textmode) ; 

1191 

def  vp. height  =  480; 

/*  fix  default  vuport  */ 

1201 

result  =  TRUE; 

121| 

} 

122| 

) 

1231 

if  (! result)  {  / 

*  unable  to  switch  to  graphics  */ 

124  | 

oldmode  =0; 

/*  so  cancel  text  screen  save  */ 

1251 

free  (vidsave) ; 

126| 

vidsave  =  0; 

127| 

} 

1281 

return  result; 

129| 

1301 

1311 

void  far  pc  textmode  (void) 

1321 

/*  SPECIFIC  TO  MS-DOS  */ 

1331 

/*  Restore  text  mode  */ 

134| 

/*  Automatically  called  on  pgm  termination  */ 

1351 

{ 

1361 

union  REGS  r; 

137| 

1381 

if  (oldmode)  { 

/*  if  not  in  text  mode  now...  */ 

1391 

r.h.ah  =  0; 

1401 

r.h.al  =  oldmode; 

/*  restore  text  mode  */ 

141| 

int86  (0x10,  &r,  &r); 

142| 

movedata 

/*  restore  text  screen  */ 

143| 

(FP  SEG  (vidsave) ,  FP 

OFF  (vidsave),  vidmem,  0,  4096); 

144  | 

free  (vidsave) ; 

/*  free  allocated  memory  */ 

145| 

vidsave  =0; 

/*  zero  pointer  */ 

1461 

oldmode  =  0; 

/*  reset  */ 

147| 

r.h.ah  =  2; 

/*  restore  old  cursor  position  */ 

1481 

r.h.bh  =  textpage; 

1491 

r.x.dx  =  curpos; 

1501 

int86  (0x10,  Sr,  Sr); 

1511 

) 

1521 

1531 

1541 

void  far  set  colorl  (int  palette  reg) 

1551 

/*  Select  pixel  color  from  palette  register  */ 

1561 

{ 

157| 

colorl  =  palette  reg; 

1581 

End  Listing  Three 

Listing  Four 

/*  STRIPES. C:  Demos  pixel-writing  with  GRAFIX  library  */ 

♦include  <conio.h> 

♦include  <stdio.h> 

♦include  <stdlib.h> 

♦include  "grafix.h" 

void 

main  () 

register  x,  y; 

int 

color; 

if 

(!init  video  (EGA))  { 

puts  ("No  EGA/VGA  present  in 

system:  Program  ended"); 

exit  (1); 

} 

else  { 

for  (y  =  95;  y  <  255;  y++)  { 

color  =  y  %  16;  /* 

first  color  this  row  */ 

for  (x  =  160;  x  <  480;  x++) 

{ 

set  colorl  (color);  /* 

set  color  this  pixel  */ 

draw_point  (x,  y) ; 

if  (++color  ==  16) 

color  =0;  / 

} 

wrap  around  palette  */ 

) 

getch() ; 

/*  hold  for  keypress  */ 

} 

End  Listings 
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Listing  One  (Text  begins  on  page  136.) 


\  MANDLZEN  9-16-88  M. HAWLEY 

\ 

This  file  contains  a  screen  for  graphics  words  for  an  IBM-PC 
BIOS  compatible.  The  word  GRAPH  puts  the  computer  in  high  res. 
graphics  mode.  PIXEL-ON  takes  two  numbers  off  the  stack  and  uses 
them  as  X,Y  coordinates  to  plot  one  pixel.  PIXEL-OFF  does  the 
same  but  turns  the  pixel  off.  All  other  words  are  FORTH-83 
written  in  L&P  F83. 

The  load  screen  loads  screen  2  ,  the  graphics  words 
and  screen  3  which  draws  a  small  sketch  of  the  Mandelbrot  Set 
in  under  8  minutes. 

The  other  screens  draw  bigger  versions  and  closeups.  Full 
blown  versions  take  up  to  4  hours  to  draw  on  my  8086  based  PC. 
LOAD  THE  SCREEN  YOU  WANT  TO  RUN.  You  can't  load  them  all  at  once 
because  they  all  use  the  same  variables  and  constants. 

\  M. HAWLEY 


\ 

HEX 

CODE  VIDEO 


AX  POP  DX  POP  CX  POP 


BP  PUSH 

SI  PUSH  10 

INT 

SI 

POP 

NEXT  END -CODE 

:  TEXT  0 

0  2  VIDEO  ; 

:  GRAPH  0 

0  6  VIDEO  ; 

CODE  PLOT 

AL  POP 

dx  : 

POP 

CX 

0C  ♦  AH  MOV 

BP  PUSH 

SI  PUSH  10 

INT 

SI 

POP 

NEXT  END-CODE 

CODE  PIXEL-ON  OCOl  ♦  AX  MOV  DX  POP  CX  POP 

BP  PUSH  SI  PUSH  10  INT  SI  POP  BP  POP  NEXT  END-CODE 

CODE  PIXEL-OFF  OCOO  ♦  AX  MOV  DX  POP  CX  POP 

BP  PUSH  SI  PUSH  10  INT  SI  POP  BP  POP  NEXT  END-CODE 

DECIMAL  ; 

\  MANDLZEN  One  screen  Mandlbrot  sketch 

VARIABLE  CX  VARIABLE  CY  VARIABLE  X 
-8192  CONSTANT  CYBASE  CYBASE  CY  !  -12000  CX  ! 

160  CONSTANT  CXSTEP  400  CONSTANT  CYSTEP 
:  MANDLZEN  GRAPH  269  X  !  370  270  DO  1  X  +! 

125  75  DO  0  0  X  0  I  PIXEL-ON 
30  0  DO  2DUP  DUP  8192  */  SWAP  DUP  8192  */ 

2DUP  +  0<  IF  X  @  J  PIXEL-OFF  2 DROP  LEAVE  THEN 
SWAP  -  CX  @  +  -ROT  4096  */  CY  @  +  LOOP  2 DROP 
CYSTEP  CY  + ! 

LOOP  CYBASE  CY  ! 

CXSTEP  CX  +!  LOOP  . "  Mandelbrot  by  Marc  Hawley 
."  POB  716,  Mt.  Vernon,  IN  47620  " 


\  MANDL1 


Full  screen  Mandelbrot  portrait 


VARIABLE  CX  VARIABLE  CY  VARIABLE  X 
-8192  CONSTANT  CYBASE  CYBASE  CY  !  -12000  CX  ! 

33  CONSTANT  CXSTEP  82  CONSTANT  CYSTEP 
:  MANDL1  GRAPH  OX!  500  0  DO  1  X  +! 

200  0  DO  0  0  X  @  I  PIXEL-ON 
50  0  DO  2DUP  DUP  8192  */  SWAP  DUP  8192  */ 

2DUP  +  0<  IF  X  0  J  PIXEL-OFF  2 DROP  LEAVE  THEN 
SWAP  -  CX  @  +  -ROT  4096  */  CY  @  +  LOOP  2 DROP 
CYSTEP  CY  + ! 

LOOP  CYBASE  CY  ! 

CXSTEP  CX  +!  LOOP  . "  Mandelbrot  by  Marc  Hawley 
POB  716,  Mt.  Vernon,  IN  47620  " 


\  MANDL1  full  screen 

-200  CONSTANT  CYBASE  CYBASE  CY  !  2000  CX  ! 

1  CONSTANT  CXSTEP  2  CONSTANT  CYSTEP  0  X  ! 

:  MANDL1  GRAPH  500  0  DO  1  X  +! 

200  0  DO  0  0  X  0  I  PIXEL-ON 
80  0  DO  2 DUP  DUP  8192  */  SWAP  DUP  8192  */ 

2 DUP  +  0<  IF  X  @  J  PIXEL-OFF  2 DROP  LEAVE  THEN 
SWAP  -  CX  0  +  -ROT  4096  */  CY  0  +  LOOP  2 DROP 
CYSTEP  CY  + ! 

LOOP  CYBASE  CY  ! 

CXSTEP  CX  + !  LOOP  ; 


\  MANDL3  full  screen 

-8192  CONSTANT  CYBASE  CYBASE  CY  !  -1024  CX  ! 

2  CONSTANT  CXSTEP  5  CONSTANT  CYSTEP  0  X  ! 

:  MANDL3  GRAPH  500  0  DO  1  X  +! 

200  0  DO  0  0  X  0  I  PIXEL-ON 
80  0  DO  2 DUP  DUP  8192  */  SWAP  DUP  8192  */ 
2DUP  +  0<  IF  X  @  J  PIXEL-OFF  2 DROP  LEAVE  THEN 
SWAP  -  CX  0  +  -ROT  4096  */  CY  @  +  LOOP  2 DROP 
CYSTEP  CY  + ! 

LOOP  CYBASE  CY  ! 

CXSTEP  CX  + !  LOOP  ; 


\  MANDL4  full  screen 

-8192  CONSTANT  CYBASE  CYBASE  CY  !  -1024  CX  ! 

2  CONSTANT  CXSTEP  5  CONSTANT  CYSTEP  0  X  ! 
:  MANDL4  GRAPH  500  0  DO  1  X  +! 
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200  0  DO  0  0  X  @  I  PIXEL-ON 
30  0  DO  2DUP  DUP  8192  */  SWAP  DUP  8192  */ 

2DUP  +  0<  IF  X  0  J  PIXEL-OFF  2 DROP  LEAVE  THEN 
SWAP  -  CX  0  +  -ROT  4096  */  CY  0  +  LOOP  2 DROP 
CYSTEP  CY  +! 

LOOP  CYBASE  CY  ! 

CXSTEP  CX  +!  LOOP  ; 


\  MANDL5  full  screen 

-8192  CONSTANT  CYBASE  CYBASE  CY  !  -824  CX  ! 

1  CONSTANT  CXSTEP  2  CONSTANT  CYSTEP  0  X  ! 

:  MANDL5  GRAPH  500  0  DO  1  X  +! 

200  0  DO  0  0  X  @  I  PIXEL-ON 
90  0  DO  2DUP  DUP  8192  */  SWAP  DUP  8192  */ 

2DUP  +  0<  IF  X  0  J  PIXEL-OFF  2 DROP  LEAVE  THEN 
SWAP  -  CX  @  +  -ROT  4096  */  CY  0  +  LOOP  2 DROP 
CYSTEP  CY  + ! 

LOOP  CYBASE  CY  ! 

CXSTEP  CX  + !  LOOP  ; 


-7250  CONSTANT  CYBASE  CYBASE  CY  !  -424  CX  ! 

1  CONSTANT  CXSTEP  2  CONSTANT  CYSTEP  0  X  ! 

:  MANDL6  GRAPH  500  0  DO  1  X  +! 

200  0  DO  0  0  X  @  I  PIXEL-ON 
20  0  DO  2 DUP  DUP  8192  */  SWAP  DUP  8192  */ 

2 DUP  +  0<  IF  X  @  J  PIXEL-OFF  2DROP  LEAVE  THEN 
SWAP  -  CX  0  +  -ROT  4096  */  CY  0  +  LOOP  2 DROP 
CYSTEP  CY  +! 

LOOP  CYBASE  CY  ! 

CXSTEP  CX  + !  LOOP  ; 


\  MANDELZEN  DOCUMENTATION  9-16-88  M. HAWLEY 

VARIABLES  CX  and  CY  are  the  X  and  Y  coordinates  of  the 
starting  point  for  the  graph.  Everything  is  scaled  up  by  a 
factor  of  8192,  so  -1  is  expressed  as  -8192,  .02  is  expressed 
as  164  and  so  on.  The  variable  X  is  a  kludge  I  had  to  use  to 
access  the  outermost  index  of  three  nested  loops  while  in  the 
innermost.  My  version  of  LfiP  F83  has  I  and  J  for  the  first 
two  indexes  but  no  I'  (  drat  ) . 

To  explore  different  parts  of  the  Mandelbrot  Set,  change 
the  starting  point  by  editing  CX  and  CY. 

CONSTANTS  CYBASE  is  the  base  value  for  CY.  After  the  program 
scans  through  the  range  of  values  being  tested  along  the  Y-axis 
CY  is  reset  to  CYBASE  for  the  next  vertical  scan. 

CXSTEP  and  CYSTEP  are  the  increments  by  which  CX  and  CY 
are  changed  each  time.  To  explore  a  large  part  of  the  Set  or 
all  of  it,  use  large  STEPs. 

\  DOCs  cont.  M. HAWLEY 

To  zoom  in  and  magnify  a  small  part  of  the  Set,  use  small 
STEPs.  For  the  best  proportion,  at  least  on  my  screen,  CYSTEP 
should  be  2  or  2  1/2  times  as  big  as  CXSTEP. 

PIXEL-ON  and  PIXEL-OFF  are  specific  to  IBM-PC  BIOS  ROM 
compatibles.  Given  two  numbers  on  the  stack,  they  turn  on 
or  off  the  pixel  at  that  (X,Y)  location  on  the  screen. 

You  will  notice  that  the  closeup  screens  magnify  the  view 
of  screen  3  (  MANDLZEN  )  up  to  160  diameters  just  like  a 
160  power  telescope  looking  at  a  celestial  object.  Yet,  the 

program  is  entirely  in  16  bit  scaled  integer  math  - 

no  floating  point.  I  originally  thought  that  THIS  program 
would  HAVE  to  be  in  floating  point. 

\  DOCs  M. HAWLEY 

I  first  wrote  it  in  floating  point.  It  ran  6  TIMES  SLOWER 
than  present  version.  For  my  fellow  intermediate  programmers 
take  notice.  I  now  finally  begin  to  understand  why  FORTH 
programmers  scoff  at  floating  point. 

THE  ALGORITHM  Two  numbers  are  kept  on  the  stack  representing 
the  real  and  imaginary  components  of  a  complex  number.  This 
number  is  repeatedly  put  through  the  transformation: 

Z  — >  Z*Z  +  c 

The  complex  number  is  sqared  and  added  to  another  complex 
number,  C  ,  which  is  the  point  being  tested  to  determine  whether 
it  is  in  the  Set.  C  is  represented  as  CX  ,  the  real  part,  and 
CY  the  imaginary  part.  The  sum  is  again  squared  and  added  to  C. 
This  is  repeated  untill  the  test  is  satisfied  (  Z  stays  small  ) 
or  failed  (  Z  gets  too  big  ) . 

\  DOCs  M. HAWLEY 

The  outer  loops  simply  scan  through  the  x  and  y  coordinates 
of  the  screen  or  some  part  of  the  screen  and  update  the 
variables . 

The  inner  loop  is  the  repetative  test  which  finds  Z*Z  +  C. 

The  odd  thing  about  squaring  an  imaginary  number  is  that  the 
result  is  always  negative.  (  A  positive  OR  negative  real  number 
squared  is  always  positive,  of  course.  )  So  what  we  need  on  the 
stack  for  the  real  part  of  Z*Z  +  C  is  ZR*ZR-ZI*ZI  +  CX 
and  for  the  imaginary  part  2*ZR*ZI  +  CY. 

Why  ?  Well  : 

Z*Z  =  (ZR  +  ZI)MZR  +  ZI) 

=  ZR*ZR  +  2*ZR*ZI  +  ZI*ZI  but  ZI*ZI  is  negative  so... 

=  ZR*ZR  +  2*ZR*ZI  -  ZI*ZI 

The  real  part  is  ZR*ZR  -  ZI*ZI  ,  imaginary  2*ZR*ZI 

Add  the  C  :  ZR*ZR-ZI*ZI+CX  ,  2*ZR*ZI+CY  qed. 

\  DOCs  M. HAWLEY 


The  inner  loop  first  puts  0  0  on  the  stack  for  starters. 


scaled  down  by  8192 


X  0  I  — >  0  0  X  I 

PIXEL-ON  — >  0  0  plot  the  point  being  checked 

— >  ZR  ZI  the  values  being  represented 

2  DUP  — >  ZR  ZI  ZR  ZI 

DUP  — >  ZR  ZI  ZR  ZI  ZI 

8192  */  — >  ZR  ZI  ZR  ZI*ZI  scaled  down  by  8192 

SWAP  — >  ZR  ZI  ZI*ZI  ZR 

DUP  — >  ZR  ZI  ZI*ZI  ZR  ZR 

8192  */  — >  ZR  ZI  ZI*ZI  ZR*ZR  scaled 

2 DUP  — >  ZR  ZI  ZI*ZI  ZR*ZR  ZI*ZI  ZR*ZR 

+  — >  ZR  ZI  ZI*ZI  ZR*ZR  ZI*ZI+ZR*ZR 

this  is  the  square  of  the  magnitude 
\  DOCs  M. HAWLEY 

The  magnitude  of  a  complex  number  is  its  distance  from  the 
origin,  the  0,0  point.  The  X  and  Y  coordinates  are  two  sides 
of  a  triangle  and  the  hypotenuse  is  the  magnitude.  Using  the 
Pythagorean  Theorem,  Mag*Mag  =  ZR*ZR  +  ZI*ZI 
If  the  magnitude  of  Z  is  over  2  the  point  will  continue  to 
grow  and  is  not  in  the  Set.  But  the  square  of  the  magnitude 
is  easier  to  find,  so  check  if  it  is  over  4.  Here  is  a  trick. 

If  you  scale  up  by  a  factor  of  1000  you  will  be  checking  for 

a  magnitude  of  4000.  Fine.  For  more  detail  you  might  try  a 
scale' of  2000  and  test  for  8000.  Still  fine.  Try  a  scale  of 
8000.  Trouble.  We  are  then  testing  whether  a  number  is  greater 
than  32000,  but  if  it  is  over  32768  it  will  show  up  as  a 
NEGATIVE  number  and  pass  the  test  it  should  fail.  SO  AHA  ! 

Use  a  scale  of  8192  and  test  for  32768  which  is  similar  to 
testing  for  a  negative  number.  Mag.  should  not  be  negative. 

\  DOCs  M. HAWLEY 

— >  ZR  ZI  ZI*ZI  ZR*ZR  ZI*ZI+ZR*ZR 

— >  ZR  ZI  ZI*ZI  ZR*ZR  magnitude. squared 

0<  — >  ZR  ZI  ZI*ZI  ZR*ZR  TF  less  than  zero  ? 

IF  — >  ZR  ZI  ZI*ZI  ZR*ZR 

X  0  J  PIXEL-OFF  if  test  failed,  erase  pixel 

2DROP  if  failed,  drop  two  numbers 

LEAVE  THEN  ZR  ZI  failed,  exit  test 

— >  ZR  ZI  ZI*ZI  ZR*ZR  if  test  passed 
SWAP  — >  ZR  ZI  ZR*ZR  ZI*ZI 

— >  ZR  ZI  ZR*ZR-ZI *ZI  real  part  of  Z*Z 
CX  @  — >  ZR  ZI  ZR*ZR-ZI*ZI  CX  real  part  of  C 

+  — >  ZR  ZI  ZRnew 

-ROT  — >  ZRnew  ZR  ZI 

4096  */  — >  ZRnew  2*ZR*ZI  scaled  (  2/8192  =  1/4096) 


imag.  part  of  C 
this  is  new  ZI 


CTSTEP  CY  + !  — >  increment  CY  ,  the  Y  axis  variable 

LOOP  — >  cycle  through  the  Y  axis 

CYBASE  CY  !  — >  reset  CY  for  the  next  CX  cycle 

CXSTEP  CX  + !  — >  increment  CX,  the  X  axis  variable 

LOOP  — >  cycle  through  the  X  axis 

;  — >  That's  all,  folks  ! 

I  would  like  to  hear  your  comments  and  improvements. 
Marc  Hawley  POB  716,  Mt .  Vernon,  IN  47620 
EXPLORE  AND  ENJOY  THE  MANDELBROT  SET 


0<  — : 

IF  — : 

X  0  J  PIXEL-OFF 
2  DROP 

LEAVE  THEN 


— > 

ZRnew 

2*ZR*ZI 

CY  0 

— > 

ZRnew 

2*ZR*ZI  CY 

+ 

— > 

ZRnew 

2*ZR*ZI+CY 

— > 

ZRnew 

ZInew 

LOOP 

— > 

test 

again  .  . . 

2  DROP 

— > 

clear 

stack  when  c 

End  listing 


Dr.  Dobb's Journal,  February  1989 


139 


PROGRAMMER'S  SERVICES 


OF  INTEREST 


Tools 

REGULUS-386  Builder,  a  software  de¬ 
velopment  kit  for  80386-based  PC  AT 
and  Compaq  compatible  systems,  has 
been  released  by  Alcyon  Corp.  This 
product  contains  the  REGULUS-386  op¬ 
erating  system  as  well  as  a  C  compiler, 
assembler,  linker,  debugger,  and  sup¬ 
port  upgrades  for  90  days. 

A  Unix-compatible,  real-time  operat¬ 
ing  system,  REGULUS-386  supports  sys¬ 
tem  calls  and  kernel  features.  Real-time 
operating  features  include  prioritized 
tasks,  context  switching,  intertask  com¬ 
munications,  contiguous  files,  and  di¬ 
rect  access  to  interrupts. 

REGULUS-386  Builder  sells  for  $1,500. 
Perpetual  upgrades  and  continued  sup¬ 
port  are  available  at  additional  cost. 
Reader  Service  No.  20. 

Alcyon  Corp. 

6888  Nancy  Ridge  Dr. 

San  Diego,  CA  92121-2232 
619-587-1155 

Abraxas  Software  has  announced  an 
OS/2  CASE  tool  called  PCYACC/2,  Ver¬ 
sion  2.0,  a  program  generator  capable 
of  generating  C  source  code  for  build¬ 
ing  assemblers,  compilers,  browsers, 
page  description  language,  language 
translators,  syntax  directed  editors,  and 
query  languages  for  OS/2. 

PCYACC/2  is  designed  to  generate 
ANSI  C  source  code  optimized  for  the 
Microsoft  and  Lattice  OS/2  compilers. 
The  generated  source  code  can  then 
be  compiled  to  generate  the  final  prod¬ 
uct.  Runtime  library  and  example 
sources  are  provided  to  be  used  as 
application  skeletons  for  new  prod¬ 
ucts. 

Demo  application  sources  include  a 
desktop  calculator,  an  infix  to  postfix 
translator,  and  an  implementation  of 
the  PlC(ture)  language.  Also  included 
are  a  code  execution  engine  to  display 
the  graphics  on  PS/2  screens  and  a  C++ 


to  C  translator.  Grammar  for  YACC, 
C++,  ISO  Pascal,  ANSI  C,  SQL,  Apple 
Hypertalk,  Smalltalk-80,  Prolog,  and 
dBase  III+  and  IV  is  included. 

Other  features  include  the  ability  to 
generate  code  for  large  grammars  on 
PS/2s,  syntax  trees  generated  at  run¬ 
time  by  target  products  for  debugging, 
and  error  recovery  support  for  target 
products. 

PCYACC/2  sells  for  $395;  multiple 
copy  discounts  and  site  licenses  are 
available.  Reader  Service  No.  21 . 
Abraxas  Software  Inc. 

7033  SW  Macadam  Ave. 

Portland,  OR  97219 
503-244-5253 

Version  1.3  of  Pro-C  has  been  released 
by  Vestronlx  Inc.  Pro-C  is  a  source 
code  applications  generator  for  MS- 
DOS,  QNX,  Xenix,  and  Unix.  Windows, 
one  of  the  product’s  features,  gives  de¬ 
velopers  the  ability  to  create  applica¬ 
tions  with  moving  windows,  multiple 
windows,  dynamically  sized  windows, 
scrolling  regions,  and  subscreens. 

Other  features  include  dBase  III  in¬ 
terface,  multiple  records,  help  functions, 
and  color  support.  Pro-C,  which  does 
not  require  a  runtime  environment,  sells 
for  $495.  Reader  Service  No.  23. 
Vestronix 
Allen  Square 
180  King  St.  S,  Ste.  230 
Waterloo,  Ontario,  Canada  N2J  IP8 
519-745-2700 

Island  Systems  has  announced  the 
availability  of  Turbo  Meta-Menu,  a  soft¬ 
ware  utilities  package  that  uses  the 
MetaWindow  graphics  driver  (from 
MetaGraphics  Software  Corp.)  for  Turbo 
Pascal  4  and  5  to  produce  a  user  inter¬ 
face  to  graphics  application  programs. 

Turbo  Meta-Menu  allows  software 
developers  to  create  horizontal  and  ver¬ 
tical  pull-down  menus,  pop-up  mes¬ 
sages,  button  menus,  and  more.  All 
structures  autosave  the  underlying  graph¬ 
ics  image  and  provide  a  mouse-drag 
feature. 

The  Turbo  Pascal  4  and  5  version  of 
Turbo  Meta-Menu  sells  for  $149;  the 
library  source  is  an  additional  $75.  The 
base  package  comes  with  a  reference 
manual,  demo  program  with  source, 
six  sample  programs  with  source,  and 
two  additional  utility  programs.  The 
package  includes  menu  and  message 
utilities  as  well  as  a  cursor  icon  editor 
and  an  automatic  menu-making  pro¬ 
gram.  Reader  Service  No.  22. 

Island  Systems 
7  Mountain  Rd. 


Burlington,  MA  01803 
617-273-0421 

Trio  Systems  has  begun  shipping  a 
new  release  of  its  C-Index  Database 
Toolkit  developed  for  Turbo  C.  The 
C-Index  library  is  now  available  in  a 
version  ready  to  run  with  Borland’s 
Turbo  C.  A  professional  development 
tool,  the  C-Index  Database  Toolkit  sup¬ 
ports  single  user,  multiuser,  and  net¬ 
work  applications  with  file-management 
facilities. 

The  C-Index  Database  Toolkit  fea¬ 
tures  B+  tree  indexing,  variable-length 
records,  direct  and  sequential  access, 
and  multiple  record  formats  per  file. 
The  C-Index  Database  Toolkit  for  Turbo 
C  uses  application  program  interface 
(API),  which  allows  the  library  to  be 
implemented  using  nine  subroutine 
calls.  This  product  sells  for  $99-  Reader 
Service  No.  24. 

Trio  Systems 

2210  Wilshire  Blvd.,  Ste.  289 
Santa  Monica,  CA  90403 
213-394-0796 

Solution  Systems’  C-Worthy  Interface 
Library  includes  features  such  as  screens 
and  windows,  form  interface  library, 
menus,  error  handling,  DOS  interface 
library,  and  system  and  context  sensi¬ 
tive  help. 

With  C-Worthy,  creating  a  window 
consists  of  three  function  calls:  Define 
the  window’s  characteristics,  select  it 
as  the  current  window,  and  display  it. 
Up  to  50  windows  can  be  active  at  one 
time.  The  windows  feature  also  includes 
screens  and  color  palettes. 

The  optional  form  interface  library 
is  designed  to  help  users  display  data 
input  forms  and  to  gather  and  validate 
user  input.  C- Worthy’s  menus  include 
pop-up,  Lotus  style,  pull-up,  and  pull¬ 
down  (MS  Windows  style).  C-Worthy’s 
system  error  library  is  a  collection  of 
over  120  error  handling  routines  that 
report  errors  returned  from  C-Worthy 
functions. 

The  DOS  interface  library  has  rou¬ 
tines  to  manage  data  files,  dates,  times, 
disk  drives,  subdirectories,  memory,  and 
other  DOS  operations.  The  help  fea¬ 
ture  creates  program  help  screens  in¬ 
teractively  using  C-Worthy’s  full  screen 
text  editor.  Each  help  message  can  have 
multiple  pages  of  text. 

C-Worthy  supports  Microsoft  C  4.0 
and  5.0,  Quick  C,  Turbo  C  1.0  and  1.5, 
and  Lattice  C  3.2.  System  requirements 
include  hard-disk  media  with  256K 
RAM,  MS-DOS  2.0  or  later,  and  IBM 
PC  or  compatible,  TI  Professional,  NEC 


Dr.  Dobb’s  Journal,  February  1989 

140 


151 


OF  INTEREST 

(continued  from  page  151) 


APC  III,  or  Vicor  9000.  C- Worthy  Inter¬ 
face  Library  sells  alone  for  $195,  with 
Form  Interface  Library  for  $295,  and 
with  Forms  and  Library  source  for  $495. 
Reader  Service  No.  25. 

Solution  Systems 
541  Main  St.,  Ste.  410 
S  Weymouth,  MA  02190 
617-337-6963 
800-821-2492 

Debuggers 

Wendin  Inc.  has  released  VM-DEBUG, 
a  debugging  tool  for  IBM  PCs,  XTs, 
ATs,  and  compatibles.  VM-DEBUG, 
which  stands  for  the  virtual  machine 
debugger,  is  an  interpreter  whose  lan¬ 
guage  is  8088  machine  code  extended 
with  the  real-mode  instructions  of  an 
80286. 

According  to  Wendin,  the  VM-DE¬ 
BUG  interpreter  can  stop  the  execution 
of  a  program  at  any  point,  examine  or 
alter  memory  or  register,  examine  the 
program,  and  determine  where  the  pro¬ 
gram  has  been.  In  addition,  the  prod¬ 
uct  can  trace  DOS,  or  the  ROMs,  and 
set  breakpoints  within  ROM.  VM- 
DEBUG  sells  for  $99-  Reader  Service 
No.  26. 

Wendin  Inc. 

Box  3888 

Spokane,  WA  99220-3888 
509-624-8088 

Language  Processors  Inc.  (LPI)  has 
announced  the  availability  of  Code- 
Watch,  an  interactive  source-level  de¬ 
bugger  to  be  used  with  LPI’s  Basic,  C, 
Cobol,  Fortran,  Pascal,  and  PL/I  pro¬ 
gramming  languages  operating  in  the 
Unix  and  Xenix  environments. 

Code  Watch  uses  the  language  of  the 
source  code  (not  machine  language) 
and  allows  commands  to  be  entered 
in  an  abbreviated  form.  Features  in¬ 
clude  action  lists,  macros,  stepping,  trac¬ 
ing,  and  program  execution  controlled 
by  the  developer  so  that  execution  may 
be  suspended  via  breakpoints  or  re¬ 
sumed  at  a  developer-specified  point. 

Available  on  most  Motorola  680X0 
series  systems  and  Intel’s  80386-based 
systems  under  Unix  and  Xenix,  Code- 
Watch  is  priced  from  $495  to  $2,495, 
depending  on  the  number  of  ports  and 
the  processor.  Reader  Service  No.  27. 
Language  Processors  Inc. 

959  Concord  St. 

Framingham,  MA  01701-  4613 
508-626-0006 

Prototyping 

Rapid  Prototyping  System  (RPS)  is  Gene¬ 
sis  Data  Systems’  new  presentation 
design  program  incorporating  several 


tools  for  project  prototyping,  interac¬ 
tive  tutorials,  product  demonstrations, 
program  design,  and  front-end  software 
management. 

RPS  features  a  prototyping  module 
that  enables  the  user  to  manipulate  and 
join  text,  graphics,  and  music  into  pres¬ 
entations  through  the  use  of  anima¬ 
tion,  transition,  branch,  subroutine,  and 
numerical/text  variable  commands. 

RPS  provides  a  screen  design  mod¬ 
ule  that  uses  the  IBM  extended  ASCII 
set  and  255  color  combinations  for  the 
creation  of  screens.  Graphics  or  text 
screens  can  also  be  captured  from  other 
programs  with  an  RPS  memory-resi¬ 
dent  module.  Both  user-designed  and 
captured  screens  can  be  used  in  the 
prototyping  module. 

RPS  contains  a  music  module  that 
uses  standard  musical  notation  for  the 
creation  of  new  tunes  or  the  duplica¬ 
tion  of  familiar  ones.  Tunes  can  be 
saved  to  a  file  and  accessed  by  the 
prototyping  module.  Tunes  may  be 
played  in  the  background,  either  as 
part  of  a  presentation  or  directly  from 
DOS. 

RPS  runs  on  IBM  PCs,  PS/2s,  and 
compatibles  equipped  with  a  floppy 
or  hard  drive  and  a  color,  monochrome, 
or  1TL  monitor.  The  $249-95  program 
requires  256K  and  DOS  2.0  or  later, 
and  it  is  not  copy  protected.  Reader 
Service  No.  28. 

Genesis  Data  Systems 

8415  Washington  Place  NE,  Ste.  A 

Albuquerque,  NM  87113 

505-821-9425 

800-777-1437 


Ada 

Intel  Corp.  has  demonstrated  its  vali¬ 
dated  Ada-386  compilation  package 
with  the  Intel  32-bit,  real-time  kernel 
iRMK  and  has  announced  plans  to  in¬ 
troduce  an  Ada-960  cross-compiler. 

The  Ada-386  cross  compilation  pack¬ 
age  runs  under  VAX/VMS  and  features 
a  set  of  language  tools,  which  a  de¬ 
signer  uses  to  go  from  code  develop¬ 
ment  to  optimizing,  downloading,  and 
debugging. 


The  package  enables  designers  to 
generate  32-bit  386  microprocessor  code 
supported  by  an  80387  numerics  copro¬ 
cessor.  The  “pragma  interface”  permits 
calls  to  high-level  languages,  including 
Intel’s  ASM-386,  PL/M-386,  and  C-386. 
Optional  download  and  debug  paths 
are  available  via  either  a  ROM-resident 
debug  monitor  or  by  using  Intel’s  ICE- 
386  for  transparent,  real-time  emula¬ 
tion. 

Intel  anticipates  similar  capabilities 
in  the  future  for  designers  using  the 
new  Ada-960  development  tools.  The 
validated  Ada-960  cross-compiler  will 
be  available  in  the  first  half  of  this  year. 

The  Ada-386  cross  compilation  pack¬ 
age  is  available  now.  Pricing  is  de¬ 
pendent  upon  the  class  of  VAX  host: 
The  price  for  MicroVAX  version  is 
$36,000.  The  price  for  the  Ada-386  cross 
compilation  package  includes  Intel’s 
90-day  support  offering  plus  12  months 
of  maintenance.  Reader  Service  No.  29. 
Intel  Corp. 

3065  Bowers  Ave. 

Santa  Clara,  CA  95052-8065 

503-696-2233 

800-548-4725 

Texas  Instruments  and  Tartan  Labo¬ 
ratories  have  announced  an  agreement 
to  jointly  develop  an  Ada  compiler  for 
a  digital  signal  processor  (DSP)  chip. 
Target  processor  for  the  compiler  is 
TI’s  SMJ320C30,  a  third-generation  DSP 
being  developed  for  military  applica¬ 
tions  requiring  advanced  signal  proc¬ 
essing  capabilities,  such  as  radar,  so¬ 
nar,  image  processing,  missile  guid¬ 
ance  and  tracking,  and  communica¬ 
tions.  The  companies  will  work  together 
to  define  the  capabilities  of  the  com¬ 
piler.  Completion  of  the  compiler  is 
expected  late  this  year. 

The  compiler,  to  be  hosted  on  a  DEC- 
VAX/VMS  system,  will  implement  Ada 
as  defined  in  ANSI/MIL-STD-1815A- 
1983  and  will  target  the  SMJ320C30  in¬ 
struction  set  architecture. 

Still  in  development,  the  32-bit 
SMJ320C30  is  a  third-generation  device 
in  TTs  family  of  DSP  chips  for  military 
applications.  The  SMJ320C30,  built  in 
CMOS  technology,  executes  single-cy¬ 
cle  instructions  in  60  nanoseconds  and 
can  perform  more  than  33  million  float¬ 
ing-point  operations  per  second 
(MFLOPs).  The  chip  can  perform  com¬ 
plex  algorithms  in  real  time.  Reader 
Service  No.  30. 

Texas  Instruments  Inc. 

Semiconductor  Group  (SC-871) 

P.O.  Box  809066 
Dallas,  TX  75380-9077 
800-232-3200,  ext.  700 
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Object  Oriented  Programming 
Dig! talk  Inc.  began  shipping  Smalltalk/ 

V  Mac,  the  Macintosh  version  of  its 
object-oriented  programming  system  for 
PCs.  This  product  consists  of  a  devel¬ 
opment  language  and  an  interactive 
development  environment.  Small  pieces 
of  Smalltalk  code  can  be  created,  high¬ 
lighted  with  the  mouse,  and  then  im¬ 
mediately  tested. 

Applications  developed  in  Smalltalk/ 

V  or  Smalltalk/V  286  (for  PCs  and  com¬ 
patibles)  can  be  ported  to  Smalltalk/V 
Mac,  and  the  application  “senses”  the 


environment.  The  resulting  application, 
without  being  modified,  will  display 
standard  Macintosh  windows,  as  well 
as  standard  zoom,  close,  and  grow 
boxes. 

Smalltalk/V  Mac  provides  access  to 
the  Macintosh  toolbox  and  MultiFinder 
compatibility,  including  background 
processing.  It  also  provides  multi-proc¬ 
essing  within  Smalltalk/V  Mac  applica¬ 
tions,  such  as  background  sorting.  The 
environment  includes  a  pushbutton  de¬ 
bugger.  Smalltalk/V,  including  a  tutorial/ 
user  guide  and  example  files,  sells  for 


$199-95.  Reader  Service  No.  31. 
Digitalk  Inc. 

9841  Airport  Blvd. 

Los  Angeles,  CA  90045 
213-645-1082 

Miscellaneous 

SofTools  Inc.  has  released  CASE:W,  a 
computer-aided  software  engineering 
tool  that  generates  the  windows  por¬ 
tion  of  applications.  It  includes  a  pro¬ 
gramming  environment  to  generate  pre¬ 
tested  window  code. 

The  package  features  a  front-end  pro¬ 
totyper  that  provides  a  way  to  describe 
the  application  program’s  windows  and 
controls.  Using  an  inference  engine, 
CASE:W  then  evaluates  the  prototype 
specification,  applies  the  stored  pro¬ 
gramming  knowledge,  and  generates 
the  window-based  application. 

CASE:W  produces  commented  code 
and  the  operating  controls  for  windows 
applications;  it  also  supports  windows 
controls,  such  as  menu  bars,  pop-up 
menus,  and  dialogue  boxes.  CASE:W 
generates  only  C  code,  but  program¬ 
mers  may  use  application  routines  in 
languages  that  can  receive  a  C  lan¬ 
guage  call  (such  as  assembler,  Pascal, 
Fortran,  Basic)  using  Microsoft’s  mixed 
language  conventions. 

The  product  also  interfaces  with  a 
variety  of  text  editors  and  has  a  facility 
that  regenerates  programmer-added 
codes  into  future  versions  of  a  pro¬ 
gram.  Additionally,  the  CASE:W  pro¬ 
gramming  environment  encompasses 
the  Microsoft  Software  Development 
Kit  components  (icon  editor,  font  edi¬ 
tor,  and  dialogue  editor)  and  12  other 
configurable  tools,  such  as  a  debugger, 
Spy,  Heapwalker,  and  Shaker. 

CASE:W  can  be  used  on  a  286-based 
machine  or  a  386  with  at  least  2  Mbytes 
of  main  memory.  The  package  also 
requires  the  Microsoft  Software  Devel¬ 
opment  Kit,  the  C  Compiler,  make  util¬ 
ity  and  linker,  and  a  DOS-  or  Windows- 
compatible  text  editor.  The  company 
recommends  the  use  of  Microsoft’s  Code¬ 
View  debugger.  CASE:W  sells  for  $1,495. 
Reader  Service  No.  32. 

SofTools  Inc. 

1  Dunwoody  Park,  Ste.  130 
Atlanta,  GA  30338 
404-399-6236 
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FORUM 


SWAINE'S  FLAMES 

Time,  Inc. 


This  month’s  Rhealstone  project  is 
in  the  DDJ tradition.  This  magazine 
began  as  a  project  to  promulgate,  and 
to  allow  programmers  to  refine  a  Basic 
interpreter.  The  very  subject  matter  of 
the  Rhealstone,  though,  points  to  the 
reason  there  isn’t  more  of  this  commu¬ 
nity  design  work  in  these  pages:  A 
magazine  does  not  live  in  real  time. 

I  got  a  call  from  Lee  Felsenstein  last 
week  (that  is,  right  around  Thanksgiv¬ 
ing,  real  time).  Lee  has  a  new  project 
in  mind,  a  non-Apple  hardware  plat¬ 
form  for  stackware:  HackerCard,  if  you 
will.  The  project  implies  some  interest¬ 
ing  programming  challenges,  not  to  men¬ 
tion  the  legal  hurdles,  that  would  be 
fun  to  hash  out  in  DDJ s  pages.  But 
given  the  time  factor,  the  hashing-out 
will  likely  be  done  elsewhere,  like  on 
line. 

We  in  magazine  publishing  call  this 
communication  barrier  “lead  time,”  and 
the  effect  is  exactly  as  though  we  were 
radioing  from  somewhere  beyond  Pluto 
(the  weeklies  from  Titan).  I  mentioned 
mail  order  electro-magnate  Drew  Kap¬ 
lan  in  a  column  I  wrote  in  October,  but 
when  Tyler  was  chatting  (real  time) 
with  Drew  a  month  later  at  Comdex, 
that  column  was  still  navigating  the 
asteroid  belt. 

To  give  you  an  outside-time  perspec¬ 
tive,  then:  As  I  write  this,  it’s  15  shop¬ 
ping  days  ’till  Christmas,  and  the  air¬ 
waves  are  filled  with  reminiscences  of 
the  thousand  days  of  the  New  Frontier. 
As  you  read  this,  it’s  somewhere  around 
Martin  Luther  King’s  birthday,  approach¬ 
ing  the  thousandth  hour  of  the  Bush 
Fringe.  Either  way,  a  good  time  to  be 
outside  time. 

Time  Travel  Makes  Me  Tense 

Sometimes  we  in  magazine  publishing 
will  have  to  deal  with  this  time  prob¬ 
lem  or  we’ll  be  relegated  to  rehashing 
the  past.  As  I  write  this,  both  the  35th 


anniversary  issue  of  Playboy  and  the 
20th  anniversary  issue  of  The  Whole 
Earth  Review -axe  remembering  Jack  Ker- 
ouak. 

Skipping  a  beat,  bimonthlies  wobble 
in  a  different  orbit  altogether:  I  already 
have  the  (recommended)  Jan./Feb.  ’89 
issue  of  Micro  Cornucopia ,  which  re¬ 
minds  me  that  Dave  Thompson,  (al¬ 
though  his  magazine  sometimes  seems 
to  lie  outside  the  plane  of  the  ecliptic,) 
is  a  serious  and  skilled  professional. 

As  is  Nick  Herbert.  You’ve  probably 
noticed  that  DDJ  doesn’t  cover  quan¬ 
tum  physics  very  thoroughly,  and  I 
doubt  that  that’s  going  to  change  soon. 
Let  me  then  recommend  a  good  book, 
and  a  very  good  writer.  Nick  Herbert’s 
Quantum  Reality  is  more  readable  than 
most  science  books,  and  it  deals  with 
some  remarkably  difficult  concepts,  in¬ 
cluding  Bell’s  Theorem. 

Bell’s  Theorem  permits  a  kind  of  in¬ 
stantaneous  connection-at-a-distance 
that  almost  suggests  that  we  could  re¬ 
orient  the  arrow  of  time.  Nick  Herbert’s 
second  book  is  out  now,  it’s  called 
Faster  Than  Light:  Superluminal  Loop¬ 
holes  In  Physics.  Uh-oh,  Toto.  Herbert 
is  exploring  the  possibility  of  superlu¬ 
minal  communication  at  his  National 
Science  Foundation  in  the  Santa  Cruz 
mountains.  Maybe  faster-than-light  com¬ 
munication  can  make  magazine  pub¬ 
lishing  timely. 

Over  the  Entrepreneurial  Edge 

A  year  ago  in  this  space  I  made  fun  of 
the  merchandising  of  Peter  Norton,  ac¬ 
cusing  him  of  aspirations  to  the  title  of 


Mr.  Cultural  Icon  of  1988.  Since  then, 
Peter’s  been  Dewar’s  Profiled  and  Lnc. 
Five  Hundreded.  I’d  like  to  take  this 
opportunity  to  apologize  to  Peter  for 
my  snide  remarks  and  to  offer  readers 
of  DDJ  a  50  percent  discount  on  the 
Mike  Swaine  coffee  mug  when  pur¬ 
chased  with  the  Mike  Swaine  tee  shirt. 

That  December  Peter  Norton  Com¬ 
memorative  Issue  of  Lnc.  magazine,  by 
the  way,  was  an  intriguing  study  in 
self-criticism.  (But  not  like  John  Dvorak’s 
still-asteroidal  March  1989  MacUser col¬ 
umn  on  MacUser  columnists,  which  I 
read  in  manuscript  in  November.) 

To  get  on  the  lnc.  500  list,  your  com¬ 
pany  has  to  grow  real  fast.  Getting  on 
the  lnc.  500  list,  suggest  the  lnc.  edi¬ 
tors  in  that  selfsame  lnc.  500  list  issue, 
may  not  be  a  healthy  goal  for  a  small 
company.  Making  the  list,  they  hint, 
may  even  be  a  sign  of  instability.  Fasci¬ 
nating.  Usually  we  in  publishing  apolo¬ 
gize  for  our  errors  after  we  make  them, 
if  at  all.  Bundling  the  apology  with  the 
error  is  an  innovative  way  to  beat  the 
lead  time. 

That  same  issue  also  featured  the 
Cary  Lu  Lynching.  Cary  had  claimed 
that  the  personal  computer  industry  is 
undergoing  enormous  and  rapid 
change,  that  no  major  software  com¬ 
pany  is  planning  to  introduce  a  new 
MS-DOS  product  after  1990,  and  that 
users  will  soon  find  themselves  in  a 
“microcomputer  mess.” 

Inc.  readers  didn’t  care  for  Cary’s 
negative  thinking;  and  frankly,  I  sus¬ 
pect  that  it’s  just  this  sort  of  naysaying 
that’s  kept  Cary  from  getting  a  Dewar’s 
Profile  all  these  years. 

Michael  Swaine 
editor-at-large 
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EDITORIAL 


Windows, 
Window 
Dressing, 
and  Ethics 


It  hasn’t  been  that  long  since  the  only  windowing  system  widely  used  by  PCs  was  that  on  the 
Macintosh.  Today  there  are  more  windowing  systems  than  you  can  shake  a  light  pen  at,  and 
you  can  bet  that  there’ll  be  a  lot  more  before  we’re  through  with  them.  To  give  you  an  idea  of 
what  I  mean,  consider  that  a  few  months  ago  the  Open  Software  Foundation  (OSF,  the  group 
formed  to  counter  AT&T  and  Sun’s  attempt  at  Unix  standardization)  asked  software  developers  to 
submit  windowing  systems  for  the  user  interface  of  the  OSF’s  upcoming  Unix  implementation. 
When  39  windowing  systems  were  submitted  for  consideration,  even  the  OSF  folks  were  a  little 
surprised. 

With  this  backdrop,  this  month  we’re  examining  a  few  of  those  windowing  systems,  focusing 
on  Presentation  Manager,  Microsoft  Windows,  and  X  Windows.  And  because  of  the  growing 
importance  of  windowing  systems,  we’ll  continue  this  examination  over  the  coming  months  by 
looking  at  interfaces  (the  “Rooms”  interface  from  Xerox  PARC  and  more  on  X  Windows  and  MS 
Windows)  and  windowing  tools. 

There’s  no  question  that  a  consistent  user  interface  makes  life  easier  for  users  if  application 
development  rules  are  set  and,  more  importantly,  if  developers  adhere  to  those  rules.  That’s  one 
thing  I  like  about  the  Macintosh.  Because  Apple  laid  down  some  pretty  clear  interface  rules  early 
on,  most  Mac  applications  look  more  or  less  the  same  and,  when  you  come  face-to-face  with  a 
new  program,  you  can  get  started  quickly,  relative  to  most  PC  applications  anyway. 

It  remains  to  be  seen  how  or  if  windowing  systems  will  make  life  easier  for  programmers.  What 
you  can  expect  to  see,  however,  is  the  continued  emergence  of  new  cross-platform  development 
tools  like  the  XVT  Toolkit  (reviewed  by  Margaret  Johnson  in  the  issue)  and  Glockenspiel’s 
CommonView  (to  be  promoted  by  Microsoft).  These  tools  let  you  write  common  code,  while  the 
toolkit  takes  care  of  system  specific  necessities  at  compile  time  — the  idea  being  that  your 
application  can  run  under  a  variety  of  windowing  systems  (PM,  Windows,  Macintosh,  X  Windows, 
or  whatever)  without  any  extra  coding  on  your  part. 

Incidentally,  as  Kee  Hinckley  points  out  in  this  issue,  the  decision  reached  by  the  OSF  wasn’t  for 
a  single  windowing  system,  but  instead  for  an  amalgamation  consisting  of  Microsoft’s  Presentation 
Manager,  HP’s  3-D  technology  (as  present  in  NewWave),  and  DEC’S  X  Windows  Toolkit.  This  is 
particularly  interesting  since,  with  Presentation  Manager,  it  will  be  possible  for  users  to  eventually 
see  a  consistent  graphical  interface  across  dissimilar  hardware  platforms.  With  Microsoft  report¬ 
edly  developing  a  non-OSF  Unix  version  of  PM,  the  day  when  diverse  systems  appear  alike  comes 
a  little  closer. 


Every  now  and  then  a  little  ethical  tune-up  seems  to  be  in  order.  Granted,  Mike  Swaine  has  for 
years  been  a  self-appointed  watchdog  of  journalistic  ethics,  pointing  out  foibles  whenever  they 
come  to  his  attention  and,  a  few  years  ago,  Phil  Lemmons  gave  a  discourse  on  computer 
journalism  and  ethics  in  an  editorial  in  Byte.  But  it  seems  time  for  another  reminder. 

What  brought  this  to  mind  was  a  message  that  recently  crossed  my  desk  whereby  a  prominent 
public  relations  firm  said  it  was  discontinuing  its  policy  of  paying  members  of  the  computer  press 
a  $1,000  finder  fee  for  putting  the  PR  firm  in  contact  with  companies  that  eventually  become 
clients.  Now  there  are  many  fine  folks  in  the  PR  business;  they  have  a  tough  job,  and  the  good 
ones  work  hard.  (I  know  because  I  talk  to  some  of  them  just  about  every  day).  And,  for  that  matter, 
the  press  has  an  equally  tough  job.  (At  least  that’s  what  I  keep  telling  my  boss.)  Even  though  the 
two  professions  must  endure  a  symbiotic  relationship,  it  is  important  to  remember  that  a  PR 
agency’s  allegiance  is  to  the  client  while  a  journalist's  responsibility  is  to  you,  the  reader.  Working 
together  is  one  thing,  but  money  changing  hands  goes  beyond  the  bounds  of  decency.  Shame  on 
the  those  who  offered  the  money,  but  more  shame  on  those  who  took  it.  The  only  good  thing 
about  the  whole  muddle  is  that  it  has  ended. 

To  be  fair,  I  asked  myself  if  my  reaction  was  sour  grapes  because  I  didn't  find  out  about  this 
opportunity  until  after  it  ended.  Maybe  so.  Perhaps  if  I’d  received  one  of  those  checks  just  before 
Christmas,  I’d  be  more  understanding.  . .  but  no,  it’s  wrong  and  no  amount  of  justification  can 
make  it  right. 


If  you’ll  remember,  last  month  we  changed  what  the  outside  of  the  magazine  looked  like  when 
we  introduced  our  new  DDJ\ ogo.  This  month  we’ve  extended  that  redesign  into  the  interior. 
Redesigning  a  magazine  isn’t  an  endeavor  that  is  undertaken  simply  for  the  sake  of  change.  There 
are  practical  reasons  too,  the  most  important  being  that  the  redesign  has  enabled  us  to  get  more 
text  on  the  same  size  page  without  shrinking  the  size  of  the  type.  This  in  turn  means  more  articles 
and  more  program  listings  for  you. 


Jonathan  Erickson 
editor-in-chief 


6 


Dr.  Dobb’s  Journal,  March  1989 

147 


LETTERS 


Forth  Source  for  Floating  Point 

Dear  DDJ, 

First,  I  like  DDJ.  I  think  it’s  the  best 
magazine  around  (together  with  Byte). 
I  fully  agree  with  Mr.  Price  (“Letters,” 
August  1988);  I  think  standardization  is 
useful  only  in  case  the  language  has 
been  designed  by  a  committee.  I  doubt 
if  it’s  smart  to  standardize  a  language 
some  15  years  after  its  introduction! 

Although  I  program  mostly  in  Basic 
or  C  (yes,  that  is  possible  on  a  little 
CBM  64,  praise  die  Lord!),  I’m  playing 
around  a  little  with  Forth.  But  I’ve  got  a 
problem,  and  I  think  your  readers 
could  help  me. 

I’m  looking  for  Forth  source  (FIG- 
FORTH)  for  floating  point  mathematics 
and  for  a  decompiler  for  Forth  words 
(or  just  hints  on  how  to  do  it  so  I  can 
program  them  myself).  Also,  could 
someone  tell  me  how  it’s  possible  that 
certain  C  functions,  such  as  PRINTFO, 
can  deal  with  a  variable  number  of 
parameters? 

Mark  van  Atten 
Krabbestraat  11 
3052  NR  Rotterdam 
The  Netherlands 


Will  Simulator  Support 
SubLOGIC  Scenery  Disks? 

Dear  DDJ, 

We  have  been  swamped  with  phone 
calls  from  owners  of  Microsoft  Flight 
Simulator,  Version  3,  concerned  that 
the  product  will  not  support  SubLOGIC 
Scenery  Disks. 

The  following  information  is  crucial 
for  loading  and  operating  Scenery 
Disks  with  Flight  Simulator  and  applies 
to  Europe  Scenery  Disk  as  well  as  Scen¬ 
ery  Disks  1-7,  Japan  and  San  Fran¬ 
cisco. 

Although  Flight  Simulator’s  manual 
does  not  include  any  reference  to  Scen¬ 
ery  Disk  support  outside  a  mention  on 
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page  75,  a  readme.doc  file  on  the  disk 
itself  does  explain  the  procedure  for 
converting  a  Scenery  Disk  to  a  scenery 
file  and  loading  the  file  to  a  hard  disk. 

You  can  load  a  Scenery  Disk  in 
either  of  two  ways:  as  a  copy-protected 
disk  from  drive  A  or  as  a  scenery  file 
loaded  into  the  same  hard  disk  subdi¬ 
rectory  as  Flight  Simulator.  To  load  the 
scenery  disk  from  drive  A,  you  first 
need  to  load  Flight  Simulator  from  the 
hard  drive  or  a  floppy  drive  (preferably 
on  drive  B,  but  you  can  operate  both 
from  drive  A  in  a  pinch). 

When  you’re  positioned  for  take-off, 
press  <Shift-E>  to  bring  up  the  scenery 
library  menu.  Choose  option  1  (floppy 
disk  in  drive  A)  or  the  number  associ¬ 
ated  with  the  scenery  file  you  wish  to 
use.  Then  invoke  the  NAV/COM  menu 
and  choose  selection  A  to  set  your  po¬ 
sition  within  the  scenery  area. 

This  should  have  Flight  Simulator  soar¬ 
ing  through  the  scenery  in  no  time.  Of 
course,  if  further  assistance  is  required, 
the  SubLOGIC  customer  support  de¬ 
partment  can  be  reached  toll  free  out¬ 
side  Illinois  at  800-637-4983  or  217-359- 
8482  within  the  state. 

Thanks  for  helping  to  get  the  word 
out. 

Deb  Israel 

SubLOGIC  Corp. 

Champaign,  Ill. 


Sold  on  Stony  Brook 

Dear  DDJ, 

I  certainly  enjoyed  Kent  Porter’s  Modu¬ 
la-2  compiler  review  in  the  September 
1988  issue  ("Examining  Room”).  My 
company  uses  the  Stony  Brook  Modu¬ 
la-2  compiler  to  develop  accounting 
applications  that  run  under  Microsoft 
Windows. 

We  are  always  on  the  lookout  for  a 
new  and  better  compiler,  so  we  read 
your  review  with  a  great  deal  of  eager¬ 
ness.  However,  none  of  the  compilers 
except  Stony  Brook  comes  close  to  meet¬ 
ing  our  needs.  This  was  such  a  surprise 
to  me  that  I  thought  your  readers  might 
want  to  know  why. 

1.  Stony  Brook  is  the  only  Modula-2 
compiler  that  can  be  used  to  develop 
well-behaved  Microsoft  Windows  ap¬ 
plications. 

2.  Stony  Brook  was  the  first  compiler 
(anywhere?)  to  be  able  to  compile  all 
types  of  OS/2  code. 

3.  The  memory  models  offered  by 
Stony  Brook  are  far  superior  to  the 
choices  offered  by  the  other  compilers. 

4.  The  interlanguage  support  offered 
by  Stony  Brook  is  superior  to  that  of 
other  models.  Others  don’t  do  an  ade¬ 
quate  job  because  of  limited  memory 


models,  calling  conventions,  and  nam¬ 
ing  conventions. 

5.  Stony  Brook’s  fast  compile  times  be¬ 
come  more  important  when  compiling 
large  commercial  grade  programs  with 
lots  of  modules. 

It’s  true  that  the  other  tools  are  some¬ 
what  crude,  but  the  editor  is  certainly 
customizable  — you  get  the  source 
code! 

Stony  Brook  will  be  coming  out  with 
(if  they  haven’t  already)  an  integrated 
environment  that  will  include  a  debug¬ 
ger.  It  should  compete  very  well  with 
TopSpeed’s  environment  and  debug¬ 
ger.  Thanks  for  giving  this  fledgling  lan¬ 
guage  space  in  your  magazine. 

Seth  K.  Pratt 

Accounting  By  Design 

Berkeley,  Calif. 


Marvin’s  Turn 

The  following  is  Marvin  Hymowech’s 
response  to  the  letter  of  James  R.  Van 
Zandt  of  Nashua,  New  Hampshire  (“Let¬ 
ters,”  December  1988)  regarding 
Marvin’s  August  1988  article  “Find  That 
Function.” 

Thanks  for  the  corrections.  Here  are 
some  other  fixes  communicated  to  me 
by  Lee  Meador  of  Richardson,  Texas: 

1.  Using  the  macros  isspaceO,  isal- 
num(),  etc.,  requires  that  you  first 
check  that  isascii(  )  is  true.  Therefore: 

(a)  In  get_fn_name(  )  in  bldfuncs.c,  re¬ 
place: 

while(  isspace(*name_ptr)  ) 

/*  skip  trailing  white  space  */ 
name_ptr— ; 

with: 

while(  isascii(*name_ptr)  && 

isspace(*name_ptr)  ) 

name_ptr— ; 

Also,  replace: 

while(  (isalnum(*name_ptr)  I  I  name 
_ptr  ==  ’  ’)  &&  name_ptr  >=  line  ) 
name_ptr--; 

with: 

while(  isascii(*name_ptr)  && 
(isalnum(*name_ptr)  I  I  name_ptr 
==  ’  ’)  &&  name_ptr  >=  line  ) 
name_ptr— ; 

(b)  Similarly,  in  get_names_one_file(  ) 
in  bldfuncs.c,  replace: 

/*  skip  white  space  V 
while(  (c  =  filter_data(fp_source)  != 
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(continued  from  page  10) 

EOF  &&  isspace(c)  ) 


with. 

/*  skip  white  space  V 
while(  (c  =  filter_data(fp_source)  != 
EOF  &&  isascii(c) 
&&  isspace(c)) 


2.  Once  you  are  in  a  quoted  string,  you 
have  to  call  fgetc(  )  for  the  quoted  char¬ 
acters,  rather  than  calling  filter_cmt(  ), 
to  allow  for  possible  comment  delimit¬ 
ers  within  quoted  strings.  Therefore,  in 
filter_quotes(  )  in  bldfuncs.c,  replace: 

switch(  c2  =  filter_cmt(fp_source)  ) 

with: 

switchf  c2  =  fgetc(fp_source)  ) 

Similarly,  replace: 

case  ’  \  \  ’:/*  beginning  of  an  escape 
sequence  */ 

filter_cmt(fp_source);/*  so  eat 
next  char  */ 

with: 

case  ’\V:/*  beginning  of  an  escape 

sequence  V 

fgetc(fp_source);  /*  so  eat  next 
char  */ 

3 ■  If  your  C  compiler  does  not  allow 
nested  comments,  then  in  filter_cmt(  ) 
in  bldfuncs.c,  replace: 

cmt_level++;/*  descend  one 
comment  level  */ 

uHth: 

cmt_level  =  1;/*  disregard  nested 

comments  V 


The  Squeaky  Wheel . . . 

Dear  DDJ, 

I  am  writing  to  you  regarding  the  lack 
of  industry-standard  software  upgrade 
policies.  Here  is  an  example  that  frus¬ 
trated  me  recently:  I  purchased  Micro- 
grafx  Draw,  and,  within  a  week,  the 
company  released  a  replacement  prod¬ 
uct  called  Micrografx  Draw  Plus.  The 
upgrade  cost  will  be  $149  95.  This  is  an 
outrageous  price;  other  companies, 
such  as  Microsoft,  offer  upgrade  soft¬ 
ware  at  a  more  reasonable  cost. 

I  talked  to  Micrografx  representatives 
about  their  policies  and  suggested  that 
they  offer  a  lower  upgrade  plan  for 


those  who  have  recently  purchased 
their  product.  For  their  part,  they  in¬ 
sisted  that  this  is  a  new  product  and  not 
just  an  upgrade  and  that  their  policy 
will  not  change.  I  questioned  them  on 
how  long  Micrografx  Draw  will  be  sold, 
and  they  said  that  it  is  replaced  by  Draw 
Plus.  I  do  not  believe  software  produc¬ 
ers  should  be  able  to  change  the  name 
of  a  product  just  to  escape  their  obliga¬ 
tion  to  customers  to  make  upgrades 
available  at  a  reasonable  cost. 

I  see  several  other  companies  with 
equally  poor  upgrade  policies.  Let’s  get 
the  software  producers  to  realize  that 
this  is  an  important  issue  that  needs  to 
be  changed. 

Chris  A.  Friend 

Friend  Dialogues  Inc. 

Shelby,  North  Carolina 

Micrografx  representative  Kenneth 
Mecca  responds:  We  appreciate  Dr. 
Dobb’s  Journal  and  Mr.  Friend  for  point¬ 
ing  out  this  problem;  we  had  just  begun 
to  notice  an  increase  in  negative  cus¬ 
tomer  feedback  concerning  this  up¬ 
grade. 

Based  on  these  events,  we  reviewed 
our  upgrade  policy  for  Micrografx 
Draw  Plus  and  made  a  change  to  re¬ 
flect  Mr.  Friend’s  suggestions,  as  well  as 
those  from  our  other  customers.  Effec¬ 
tive  immediately,  our  new  upgrade  pol¬ 
icy  for  Micrografx  Draw  Plus  calls  for 
free  upgrades  to  recent  purchasers  of  a 
previous  version  (30  days  or  for  any 
customer  that  purchases  an  obsolete  ver¬ 
sion  from  a  dealer)  and  a  $99  upgrade 
price  for  current  users  (longer  than  30 
days). 

In  addition,  customers  that  have  al¬ 
ready  purchased  the  $149-95  upgrade 
can  get  a  cash  refund  for  the  difference 
in  price  or  a  free  Micrografx  ClipArt 
library  (worth  $79)  of  their  choice. 

It  has  always  been  our  intent  to 
make  upgrading  as  painless  as  possi¬ 
ble,  and  we  certainly  support  any  effort 
that  will  promote  standardization  of 
upgrade  practices. 


Errata 

“Real-Time  Modeling  with  MS-DOS”  by 
David  Bowling,  (February  issue):  In  Fig¬ 
ure  1,  page  27,  the  first  two  time  lines 
are  reversed.  The  value  given  for 
“zeta,”  page  32,  column  3,  is  incorrect. 
The  value  of  the  proof  is  0.1  — it 
should  be  0.01.  The  equations  for  “x” 
on  page  34  are  reversed.  The  equation 
in  column  2  should  be  interchanged 
with  the  equation  in  column  3. 

DDJ 


ARCHIVES 


Syntactic  Sculpting 

"A  hacker  is  an  artist,  and  computer 
artistry  is  not  distinguished  from  other 
art  forms  except  in  the  medium 
chosen. . . . 

"It  is  the  nature  of  great  art  that  it 
compresses  a  great  deal  of  design, 
intellectual  sweat  and  individual 
personality  into  the  created  object.  There 
are  no  great  paintings  painted  by  a 
committee  or  artists.  Curiously,  it  seems 
to  matter  little  what  tools  the  artist  had, 
or  where  his  starting  point  was,  provided 
that  his  accomplishment  from  that  point 
exceeds  what  the  rest  of  us  could  have 
done.  Ansel  Adams  had  color  and  motion 
available,  but  he  chose  to  limit  himself  to 
black  and  white  stills — and  what  art  he 
created!  A  virtuoso  on  a  violin  produces 
art;  the  same  sound  from  a  Moog  is 
ho-hum. . . . 

", .  .Unlike  painting,  sculpture,  music, 
and  the  like,  few  people  can  really 
appreciate  the  artistry  in  a  computer 
product.  Perhaps  that  will  change.'' — 
Tom  Pittman,  "Festschrift  for  Doctor 
Dobb,"  DDJ,  February  1985. 


It’s  always  so  code  in  here! 

“DDJ  is  important  as  a  journal  because 
of  the  code.  It  was  started  to  publish 
code  and  it  has  always  published  code. 
It  publishes  more  code  than  any  other 
magazine.  And  its  still  my  belief  that 
people  [programmers]  learn  from  reading 
other  people  s  code. 

What  they  learn,  of  course,  is  how  to 
program  well:  they  pick  up  tricks, 
insights,  algorithms,  all  of  which  are 
particularly  well  expressed  when 
presented  in  a  form  in  which  they  will 
ultimately  be  realized:  as  code.  We  hope 
to  go  right  on  publishing  useful  and 
educational  code,  including  both 
programs  significant  in  themselves  and 
bits  of  code  that  demonstrate  some 
exemplary  algorithm  or  insight" — 
Michael  Swaine,  DDJ,  February  1985. 
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A  Presentation 
Manager  Application 

Template 


Here’s  a  PM  application  template  that  can  be  used  as 
the  starting  point  for  your  PM  programs 


Herbert  Schildt 


Beginning  with  version  1.1,  OS/2  has  included  the 
Presentation  Manager  (PM)  as  the  default  user  in¬ 
terface.  The  Presentation  Manager  provides  the  user 
with  a  windowed,  graphical  interface  in  which  much 
of  the  functionality  of  the  system  is  readily  displayed 
on  the  screen,  thus  making  the  operation  of  the  computer 
more  intuitive  than  that  of  the  traditional  command  line 
interface.  As  you  will  see,  however,  the  ease  of  end-user 
operation  has  a  price:  the  extra  time  and  effort  it  takes  to 
create  a  PM-compatible  program. 

This  article  explains  the  general  operation  of  a  Presenta¬ 
tion  Manager  application  program  and  develops  a  Pres¬ 
entation  Manager  application  template  in  C.  Programs  com¬ 
patible  with  the  Presentation  Manager  share  a  common 
structure.  The  elements  shared  by  these  PM-compatible  pro¬ 
grams  are  examined  here.  The  PM  application  template 
shown  at  the  end  of  this  article  can  be  used  as  the  starting 
point  for  your  own  programs. 

I  chose  C  for  this  article,  because  C  is  the  de  facto  language 
for  OS/2  and  Presentation  Manager.  There  are  two  main 
reasons  for  this.  First,  C  was  the  only  language  available 
when  OS/2  was  released.  Second,  the  OS/2  API  services 
strongly  resemble  the  C  standard  library  functions  and  ap¬ 
pear  to  be  optimized  for  it.  The  code  in  this  article  was 
compiled  with  Microsoft  C,  Version  5.1,  using  the  Microsoft 
OS/2  Software  Developer’s  Toolkit  version  of  OS/2  and  the 
Presentation  Manager.  With  minor  changes,  however,  the 
code  should  be  able  to  be  compiled  using  any  OS/2- 
compatible  C  compiler. 

What  1$  Hie  Presentation  Manager? 

Technically,  the  Presentation  Manager  is  a  user-interface 


Herb  Schildt  is  the  author  of  more  than  two  dozen  computer 
books,  with  topics  ranging  from  C  to  Modula-2.  This  article  is 
an  adaption  from  his  book  OS/2  Programming:  An  Intro¬ 
duction.  He  can  be  reached  at  RR  # 1 ,  Box  130,  Mahmomet, 
IL  61853- 


shell  that  runs  on  top  of  the  OS/2  operating  system  base. 
From  a  programming  point  of  view,  however,  the  Presenta¬ 
tion  Manager  virtually  appears  to  be  the  operating  system. 
This  is  because  the  Presentation  Manager  provides  several 
hundred  Application  Program  Interface  (API)  services, 
which,  to  a  large  extent,  replace  those  provided  by  the  basic 
OS/2  system.  From  the  programmers’s  point  of  view,  the 
Presentation  Manager  is  one  giant  toolbox  of  interrelated 
services  that  allows  the  creation  of  application  programs  that 
share  a  common  interface.  For  many  PM-compatible  pro¬ 
grams,  the  original  OS/2  API  services  are  irrelevant. 

The  goal  of  the  Presentation  Manager  is  to  enable  an  end 
user  who  has  basic  familiarity  with  the  system  to  sit  down 
and  run  virtually  any  application  without  prior  training.  So  in 
theory,  if  you  can  run  one  Presentation  Manager  program, 
you  can  run  them  all.  In  actuality,  of  course,  most  useful 
programs  will  still  require  some  sort  of  end-user  instruction, 
but  at  least  this  instruction  can  be  restricted  to  what  the 
program  does,  not  how  the  user  must  interact  with  it. 

Not  every  program  that  runs  under  Presentation  Manager 
will  necessarily  present  the  user  with  a  PM-style  interface.  As 
the  programmer,  you  can  override  the  basic  Presentation 
Manager  philosophy;  but  if  you  do,  you  had  better  have  a 
good  reason,  because  otherwise  the  users  of  your  programs 
will  be  disturbed.  If  you  are  writing  application  programs  for 
OS/2,  they  should  conform  to  the  general  PM  application 
interface  philosophy  if  they  are  to  be  successful  in  the 
marketplace. 

One  more  important  point:  Because  the  Presentation  Man¬ 
ager  must  have  complete  control  of  the  screen,  a  PM- 
compatible  program  will  not  be  able  to  use  any  of  C’s 
standard  console  input  or  output  functions.  This  means,  for 
example,  that  your  PM-compatible  programs  should  not  call 
gets( )  or  printfC ).  In  fact,  one  reason  there  are  many  PM  API 
services  is  that  a  large  amount  of  the  C  standard  library  had  to 
be  rewritten  when  window  support  was  introduced. 

Let’s  look  at  a  few  of  the  more  important  features  of  the 
Presentation  Manager. 
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The  DeskTop  Model 

With  few  exceptions,  the  point  of  a  window-based  user 
interface  is  to  provide  the  equivalent  of  a  desktop  on  the 
screen.  On  a  desktop  you  may  find  several  pieces  of  paper, 
one  on  top  of  another,  often  with  fragments  of  different 
pages  visible  beneath  the  top  page.  The  equivalent  of  the 
desktop  in  the  Presentation  Manager  is  the  screen.  The 
equivalents  of  pieces  of  paper  are  windows  on  the  screen. 
On  a  desk  you  can  move  pieces  of  paper  about,  maybe 
switching  which  piece  of  paper  is  on  top  or  how  much  of 
another  is  exposed  to  view.  Presentation  Manager  allows  the 


also  provides  special-purpose  windows.  The  most  common 
of  these  are  the  menu  and  dialog  boxes.  Briefly,  a  menu  is  a 
special  window  that  contains  only  a  menu  from  which  the 
user  makes  a  selection.  Instead  of  having  to  provide  the 
menu  selection  functions  in  your  program,  however,  you 
simply  create  a  standard  menu  window  using  PM  services. 

A  dialog  box  is  essentially  a  special  window  that  allows 
more  complex  interaction  with  the  application  than  that 
allowed  by  a  menu.  For  example,  your  application  might  use 
a  dialog  box  to  input  a  filename.  With  few  exceptions, 
nonmenu  input  is  accomplished  in  the  Presentation  Manager 


same  type  of  operations  on 
its  windows.  By  selecting  a 
window  you  can  make  it  cur¬ 
rent,  which  means  putting  it 
on  top  of  all  other  windows. 
You  can  enlarge  or  shrink  a 
window,  or  move  it  around 
on  the  screen.  The  Presenta¬ 
tion  Manager  lets  you  con¬ 
trol  the  surface  of  the  screen 
the  way  you  control  the  sur¬ 
face  of  your  desk. 

The  Mouse 

Unlike  DOS  and  the  original 
version  of  OS/2,  the  Presenta¬ 
tion  Manager  allows  the  use 
of  the  mouse  for  almost  all 
control,  selection,  and  draw¬ 
ing  operations.  Of  course, 
to  say  that  it  allows  the  use 
of  the  mouse  is  an  understate¬ 
ment.  The  fact  is  that  the  PM 
interface  was  designed  for 
mouse  input:  It  allows  the 
use  of  the  keyboard!  Al¬ 
though  it  is  possible  for  an 
application  program  to  ig¬ 
nore  the  mouse,  it  does  so 
only  in  violation  of  a  basic 
PM  design  philosophy  prin¬ 
ciple. 

In  general,  to  activate  a 
feature,  move  the  mouse 
pointer  to  that  feature  and 
double-click  the  left  mouse 
button.  A  double-click  is 
achieved  by  pressing  the  but- 


via  a  dialog  box. 

General  Operation  of  a  PM 
Application 

There  is  one  important 
point  that  you  must  fix  in 
your  mind:  A  PM  applica¬ 
tion  program’s  flow  is  fun¬ 
damentally  different  from  a 
“normal”  application.  You 
will  need  to  abandon  any 
preconceived  notions  of 
how  information  moves  in 
and  out  of  your  program  as 
well  as  what  constitutes  a 
program’s  main  loop.  Before 
we  look  at  any  concrete  PM 
services  or  examples,  let’s 
look  at  the  theory  behind  all 
PM-compatible  programs. 

PM  Application  Theory 

Programs  that  are  compat¬ 
ible  with  the  Presentation 
Manager  share  a  common 
skeleton.  In  its  most  straight¬ 
forward  implementation, 
when  the  program  begins,  it 
performs  the  following  func¬ 
tions,  in  the  order  shown. 

•  Initializes  the  Presentation 
Manager  relative  to  the  pro¬ 
gram 

•  Establishes  a  message 
queue 

•  Registers  a  special  function, 
referred  to  as  the  window 


ton  twice  in  rapid  succession.  Presentation  Manager  allows 
you  to  drag  objects  around  by  moving  the  mouse  pointer  to 
the  object,  pressing  and  holding  the  left  button,  and  moving 
the  mouse  pointer  and  object  to  a  new  location. 

Icons  and  Graphic  Images 

The  Presentation  Manager  allows  (but  does  not  require)  the 
use  of  icons  and  bit-mapped  graphic  images  as  a  means  of 
conveying  information  to  the  user.  The  theory  behind  the 
use  of  icons  and  graphic  images  is  found  in  the  old  adage  “A 
picture  is  worth  a  thousand  words.” 

An  icon,  in  OS/2  terminology,  is  a  small  symbol  that  is 
used  to  represent  some  function  or  program  that  can  be 
activated  by  moving  the  mouse  to  the  icon  and  double¬ 
clicking  on  it.  A  graphic  image  is  generally  used  to  simply 
convey  information  quickly  to  the  user. 

Menus  and  Dialog  Boxes 

In  addition  to  standard  windows,  the  Presentation  Manager 


function,  which  receives  input  from  the  Presentation  Man¬ 
ager; 

•  Creates  a  window  of  the  registered  class;  and 

•  Executes  a  loop,  which  reads  messages  from  the  queue  and 
dispatches  these  messages  to  the  window  function,  which 
takes  appropriate  action. 

The  window  function  (sometimes  called  wind-proc  or 
windowproc)  is  a  special  function  that  is  called  only  by  the 
Presentation  Manager,  not  by  your  program.  It  receives,  in  its 
parameters,  a  message  from  the  message  queue,  established 
in  the  second  step.  It  then  takes  different  actions  based  upon 
the  value  of  each  message.  (We  will  look  at  messages  in  a 
moment.) 

In  a  very  real  way,  a  PM  application  program  is  function¬ 
ally  similar  to  an  interrupt-driven  program.  At  any  point  in 
time,  the  program  may  receive  a  message  from  the  Presenta¬ 
tion  Manager  to  which  it  must  respond.  For  example,  your 
program  might  be  told  to  refresh  its  screen  or  that  the  user 
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has  made  a  menu  selection.  The  point  is  that  a  PM-compat- 
ible  program  is  event  driven.  If  you  have  never  written 
interrupt-driven  programs,  then  programming  for  the  Pres¬ 
entation  Manager  will  require  that  you  adjust  the  way  you 
think  about  your  programs  and  their  execution. 

When  a  PM  application  ends,  it  must  perform  these  three 
steps: 

1.  Destroy  the  window. 

2.  Destroy  the  message  queue. 

3.  Terminate  the  window  environment  relative  to  the 
application. 

The  Message  Loop 

Except  for  creating  and  destroying  the  windows  required  by 
your  program,  generally  the  only  other  thing  that  the  main( ) 
function  does  is  receive  and  dispatch  messages.  To  accom¬ 
plish  this  it  uses  a  loop  that  looks  something  like  this: 

while  (program  is  still  running)  1 
get  a  message; 

send  the  message  to  the  proper  window; 

1 

Essentially,  the  Presentation  Manager  communicates  with 
your  program  by  putting  messages  into  its  message  queue. 
Your  program  then  extracts  a  message  from  the  queue  and 
dispatches  it  to  the  proper  window  by  calling  another  PM 
service.  This  process  continues  until  the  program  is  termi¬ 
nated.  For  the  most  part,  messages  are  the  only  way  in  which 
your  program  receives  input.  (Remember,  a  PM  program 
cannot,  for  example,  call  scanf( )  to  read  input  from  the 
keyboard.)  Although  the  form  of  a  message  varies  some¬ 
what,  depending  upon  what  type  of  message  it  is,  all  mes¬ 


sages  are  integers.  Now  that  you  know  some  of  the  theory 
behind  the  Presentation  Manager  and  its  windows,  let’s  look 
at  some  specifics. 

Obtaining  an  Anchor  Block  Using  Winlnitialize 

One  of  the  first  things  that  you  will  want  your  PM  application 
to  do  is  to  obtain  an  anchor  block  handle  by  calling  Winlni- 
tialize,  whose  prototype  is  shown  here. 

void  far  *WinInitialize(unsigned  short  handle) 

Here,  handle  must  be  NULL.  Notice  that  the  function  returns 
a  void  far  pointer,  which  points  to  the  region  of  memory 
used  by  the  Presentation  Manager  to  hold  various  bits  of 
information  about  the  window  environment  relative  to  the 
application  program.  This  region  of  memory  is  called  the 
anchor  block,  and  the  pointer  to  it  is  called  the  anchor  block 
handle.  If  the  system  cannot  be  initialized,  a  NULL  is  re¬ 
turned.  The  anchor  block  handle  is  required  as  a  parameter 
by  many  PM  services. 

Unlike  the  core  API  services,  which  generally  return  0  for 
success,  many  of  the  PM  services  return  0  (NULL)  on  failure. 

(The  Microsoft  OS/2  Software  Developer’s  Kit  has  defined 
a  great  many  type  names.  For  example,  they  have  defined 
USHORT  as  an  unsigned  short  integer.  I  do  not  use  the 
Microsoft-type  names  in  this  article,  however,  for  two  rea¬ 
sons.  First,  when  learning  about  a  new  environment,  it  is 
important  to  know  exactly  what  type  of  data  you  are  dealing 
with.  Although  the  type  names  defined  by  Microsoft  are 
convenient,  they  disguise  the  nature  of  the  actual  data. 
Second,  and  more  important,  all  the  type  names  defined  by 
Microsoft  are  copyrighted  by  Microsoft.  Hence,  other  OS/2  C 
compilers  may  not  be  able  to  provide  them.) 

(continued  on  page  21) 
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(continued  from  page  18) 

Creating  a  Message  Queue 

After  initializing  the  window  system,  all  PM  applications 
must  create  a  message  queue  using  WinCreateMsgQueue, 
which  has  this  prototype: 

void  far  *WinCreateMsgQueue(void  far  'anchor_block, 

unsigned  short  size); 

The  anchor_block  is  the  handle  obtained  using  Winlnitialize. 
The  size  of  the  queue  is  determined  by  the  value  of  size,  or, 
if  size  is  NULL,  then  the  system  default  is  used.  Generally,  the 
system  default  queue  size  is  acceptable. 

Each  element  in  the  message  queue  is  contained  in  a 
structure,  called  QMSG  by  Microsoft,  defined  like  this: 

struct  ( 

void  far  *hwnd;  /*  handle  of  the  recipient 

window  */ 

unsigned  short  msg;  /*  the  message  */ 
void  far  *mpl;  /'  additional  message  info  V 

void  far  *mp2;  /*  additional  message  info  '/ 

unsigned  long  time;  /*  time  message  was 

generated  '/ 

POINT!  ptl;  /*  position  of  mouse  pointer  '/ 

1  QMSG; 

The  POINTL  structure  is  defined  like  this: 

struct  I 
long  x; 
long  y; 

1  POINTL; 

WinCreateMsgQueue  returns  a  handle  to  the  message  queue 
or  NULL  if  the  request  fails. 

Registering  a  Window  Class 

Before  you  can  actually  create  a  window,  you  must  register 
its  class  using  WinRegisterClass,  whose  prototype  is  shown 
here: 

unsigned  short  WinRegisterClass  (void  far  *anchor_block, 
char  far  'class name, 

(pascal  far  *  window_func)0, 
unsigned  long  style, 
unsigned  short  storage_bytes) 

Here,  anchor_block  is  a  pointer  to  the  anchor  block.  The 
string  pointed  to  by  classname  is  the  name  of  the  window 
class  being  registered.  This  may  be  any  name  of  your  own 
choosing.  The  address  of  the  window  function  must  be 
passed  as  the  third  parameter.  The  style  of  the  window  is 
specified  by  style.  Finally,  the  number  of  bytes  of  additional 
storage  beyond  that  needed  by  the  window  is  specified  by 
storage_bytes.  Your  program  may  use  this  extra  storage  for  its 
own  purposes.  For  the  example  in  this  article,  this  field  will 
tie  0. 

The  sort  of  window  being  registered  is  described  by  the 
value  of  style.  The  only  style  that  we  will  be  using  in  this 
article  has  the  value  4L  and  is  defined  as  CS_SIZEREDRAW  in 
the  PMWIN.H  header  file  provided  by  Microsoft.  Using  this 
style  causes  the  Presentation  Manager  to  inform  your  pro¬ 
gram  each  time  the  window  is  resized.  The  WinRegisterClass 
service  returns  nonzero  if  successful  and  NULL  on  failure. 

Creating  a  Window 

Once  you  have  initialized  the  window  system  relative  to  your 
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application,  created  a  message  queue,  and  registered  the 
class,  it  is  time  to  create  a  window. 

All  Presentation  Manager  windows  begin  with  a  frame, 
which  is  essentially  a  box.  Onto  this  frame  are  added  a 
number  of  optional,  but  desirable,  additions.  In  OS/2  these 
additional  features  are  actually  windows  in  their  own  right, 
which  are  attached  to  the  frame.  It  is  easier,  however,  to 
think  of  them  as  options  to  the  frame.  Let’s  look  at  these 
options  now. 

There  are  two  options  that  are  virtually  essential  to  all 
windows.  The  first  is  the  border.  The  border  is  important 
because  it  allows  the  user  to  move  or  resize  the  window 
using  the  mouse.  The  second  is  the  system  menu.  The 
system  menu  is  a  standard  menu  that,  minimally,  allows  the 
user  to  perform  the  following  operations:  restore  the  win¬ 
dow  to  its  original  size,  move  the  window,  resize  the  win¬ 
dow,  minimize  or  maximize  the  window,  and  close  the 
window.  Although  the  border  allows  a  more  convenient 
method  of  moving  or  resizing  the  window,  these  operations 
can  also  be  activated  from  the  system  menu.  When  a  window 
is  minimized,  it  is  shown  in  its  iconic  form  and  is  moved  to 
the  icon  region  of  the  screen.  Your  program  can  specify  what 
the  iconic  form  of  a  window  will  look  like  or  simply  let  the 
system  decide.  When  a  window  is  maximized,  it  takes  over 
the  entire  screen.  Closing  a  window  removes  it  from  the 
screen,  and  if  this  is  the  program’s  top-level  window,  it 
terminates  the  program. 

Most  of  the  time  you  will  also  want  to  add  three  other 
features  to  your  windows:  maximize  icons,  minimize  icons, 
and  a  title  that  identifies  the  window.  Although  it  is  possible 
to  maximize  and  minimize  the  window  using  the  system 
menu,  it  is  quicker  if  the  maximize  and  minimize  icons  are 
available,  because  the  user  can  activate  them  by  clicking  on 
them  with  the  mouse.  When  the  screen  holds  several  win¬ 
dows,  a  title  is  almost  necessary  in  order  to  remind  the  user 
which  window  is  which. 

Finally,  if  applicable  to  your  program,  you  will  want  to  add 
vertical  and  horizontal  scroll  bars  to  the  window.  By  clicking 
on  the  appropriate  points  on  these  scroll  bars,  the  user 
causes  the  contents  of  the  window  to  scroll  up,  down,  left,  or 
right.  The  region  enclosed  by  the  frame  and  used  by  your 
application  program  is  called  the  client  area. 

The  organization  of  a  standard  PM  window  is  shown  in 
Figure  1.  (Remember,  not  all  options  will  necessarily  be 
found  on  all  windows.)  Each  PM-compatible  program  cre- 


Figure  1:  The  layout  of  a  standard  window. 
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ates  at  least  one  main  window.  A  main  window  is  at  the 
topmost  level.  The  main  window  is  the  one  that  the  user 
associates  with  the  program.  Closing  the  main  window  ter¬ 
minates  the  program. 

There  are  two  general  categories  of  windows:  parents  and 
children.  It  is  possible  to  create  a  window  inside  of  another 
window.  In  this  case  the  newly  created  window  is  a  child  of 
the  main  window  and  is  enclosed  by  the  parent.  A  child 
window  can,  in  turn,  create  a  child  of  its  own,  and  so  on  up 
to  the  limits  imposed  by  the  size  of  the  screen. 

Each  window  is  associated  with  a  class.  There  are  several 
built-in  classes,  such  as  menus,  frames,  scroll  bars,  and  the 
like.  Windows  that  you  create,  however,  will  need  to  be 
given  class  names,  and  these  classes  must  be  registered  with 
the  Presentation  Manager.  All  windows  define  the  lower  left 
comer  as  location  0,0.  The  maximum  X  and  Y  dimensions 
are  dynamically  defined  as  the  window  changes  size  and 
shape.  The  maximum,  however,  is  determined  by  the  reso¬ 
lution  of  the  screen. 

Using  WinCreateStdWindow 

The  easiest  way  to  create  a  window  is  to  use  WinCreateStdWin¬ 
dow  Presentation  Manager  Service.  Its  prototype  is  shown 
here: 

void  far  *WinCreateStdWindow(void  far  *parent_handle, 
unsigned  long  style, 
void  far  *frame_data; 
char  far  'class  name, 
char  far  'title, 

unsigned  long  client_style, 
unsigned  module, 
unsigned  short  resource, 
void  far  "client_handle); 

The  parent_handle  must  be  the  handle  of  the  parent 
window.  When  a  program  begins  execution,  its  parent  is  the 
screen,  which  has  1  for  its  handle.  Microsoft  defines  this 


Macro  Name 

Value 

Meaning 

WS  VISIBLE 

0x80000000L 

make  window  visible 

WS  MINIMIZED 

OxOIOOOOOOL 

minimize  window 

WS  MAXIMIZED 

Ox00800000L 

maximize  window 

Figure  2:  The  most  common  values  for  the 
WinCreateStd  Window-style  parameter. 


Macro  Name 

Value 

Meaning 

FCF  TITLEBAR 

0x00000001 L 

include  title  bar 

FCF  SYSMENU 

Ox00000002L 

include  system  menu 

FCF  MENU 

0x00000004L 

include  user  menu 

FCF  SIZEBORDER 

0x00000008L 

include  sizing 

FCFMINBUTTON 

0x0000001 0L 

include  minimize 
icon 

FCFMAXBLnTON 

Ox00000020L 

include  maximize 
icon 

FCF_MINMAX 

0x00000030L 

include  both  min  and  max 
icons 

FCFVERTSCROLL. 

Ox00000040L 

include  vertical 
scroll  bar 

FCFJHORZSCFOl. 

Ox00000080L 

include  horizontal 
scroll  bar 

Figure  3 ■  The  values  for  the  frame_data 
parameter  to  point  to. 


value  by  the  macro  HWND_DESKTOP.  The  value  of  style 
determines  how  the  window  will  first  appear.  Its  most  com¬ 
mon  values  are  shown  in  Figure  2,  along  with  the  macro 
names  given  them  by  Microsoft. 

The  value  pointed  to  by  frame_data  sets  various  flags  that 
determine  how  the  window  will  behave.  This  value  can  be 
any  combination  of  the  values  shown  in  Figure  3,  along  with 
the  macro  names  given  them  by  Microsoft. 

The  classname  parameter  points  to  the  string  that  identifies 
the  class.  This  should  be  the  same  string  that  was  used  in  the 
call  to  WinRegisterClass.  The  string  pointed  to  by  title  will  be 
used  as  the  title  of  the  window  for  identification  purposes. 
For  most  purposes  the  client_style  parameter  should  be  0L, 
indicating  that  the  client  window  should  be  of  the  same  style 
as  the  window  class. 

The  resource  and  module  parameters  are  used  to  identify 
a  resource  module.  For  the  examples  in  this  chapter,  no 
resource  modules  are  needed,  so  these  parameters  should 
be  NULL  and  0,  respectively.  A  handle  to  the  client  window  is 
put  in  the  handle  pointed  to  by  client_handle.  The  Win¬ 
CreateStdWindow  service  returns  a  handle  to  the  frame  if 
successful  and  NULL  on  failure. 

WinGelMsg  and  WinDispafchMsg 

To  process  messages,  your  program  will  require  the  use  of 
WinGetMsg  and  WinDispatchMsg.  The  WinGetMsgC  )  pro¬ 
totype  is  shown  here: 

unsigned  short  WinGetMsgfvoid  far  *anchor_block, 

QMSG  far  'message, 
void  far  'window, 
unsigned  short  first, 
unsigned  short  last) 

The  message  retrieved  from  the  queue  is  put  in  the  queue 
structure  pointed  to  by  message.  If  window  is  not  NULL,  then 
it  causes  WinGetMsg  to  retrieve  messages  directed  to  only 
the  specified  window.  Most  of  the  time  your  application  will 
want  to  receive  all  messages.  In  this  case  window  should  be 
NULL.  All  messages  are  integers.  The  first  and  last  parameters 
determine  the  range  of  messages  that  will  be  accepted  by 
defining  the  end  points  of  that  range.  If  you  wish  to  receive 
all  messages,  then  first  and  last  should  both  be  zero. 

The  return  value  of  WinGetMsg  is  important.  It  returns  true 
unless  a  termination  message  is  received,  in  which  case  it 
returns  false.  This  is  the  way  your  program  will  know  it  is 
being  terminated. 

In  most  situations,  once  a  message  has  been  received  it  is 
simply  dispatched  to  the  correct  window  without  further 
processing  by  your  program  within  the  message  loop.  The 
service  that  sends  messages  along  their  way  is  WinDis¬ 
patchMsg,  whose  prototype  is  shown  here: 

void  far  'WinDispatchMsgfvoid  far  'anchor_block, 

QMSG  far  'message) 

By  calling  this  function  the  message  will  automatically  be 
routed  to  the  proper  window  function.  WinDispatchMsg 
returns  the  value  returned  by  the  window  function. 

Program  Termination 

Before  your  program  terminates,  it  must  do  three  things: 
Close  any  active  windows,  close  the  message  queue,  and 
deactivate  the  window  system  interface  created  by  the  Win- 
Initialize  service.  To  accomplish  these  things  the  Presenta¬ 
tion  Manager  provides  the  services  WinDestroyWindow, 
WinDestroyMsgQueue,  and  WinTerminate.  Their  prototypes 
are  shown  here: 

(continued  on  page  26) 
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(continued  from  page  22) 
unsigned  long  WinDestroyWindow(void  far 
*handle_window); 

unsigned  long  WinDestroyMsgQueue(void  far 
*handle_msgQ); 

unsigned  long  WinTerminate(void  far  ’anchor_block); 

Here,  handle_unndow  is  the  handle  of  the  window  to  be 
closed.  The  handle_msgQ  is  the  handle  to  the  message 
queue  to  be  destroyed.  And  the  window  system  is  discon¬ 
nected  by  calling  WinTerminate  with  the  anchor  block  han¬ 
dle. 

The  Window  Function 

As  mentioned  earlier,  all  programs  that  are  compatible  with 
the  Presentation  Manager  must  pass  to  the  PM  the  address  of 
the  window  function  that  will  receive  messages.  This  func¬ 
tion  must  be  declared  as  shown  here: 

void  far  *  pascal  far  window_func(void  far  ’handle, 
unsigned  short  message, 
void  far  ’paraml, 
void  far  *param2); 

The  window  function  receives  the  PM  messages  in  its 
parameters.  In  essence,  the  PM  sends  your  program  a  mes¬ 
sage  by  calling  the  window  function.  The  value  of  handle  is 
the  handle  of  the  window  receiving  the  message.  The  mes¬ 
sage  itself  is  contained  in  the  integer  message.  Finally,  some 
messages  require  further  information,  which  is  put  into  the 
paraml  and  param2  parameters. 

The  Presentation  Manager  can  generate  several  different 
types  of  messages.  Some  of  the  more  common  ones  are 
shown  in  Figure  4,  along  with  the  macro  names  assigned  to 
them  by  Microsoft. 

The  window  function  does  not  need  to  explicitly  process 
all  the  messages  that  it  receives.  In  fact,  it  is  common  for  an 
application  to  process  only  a  few  types  of  messages.  What 
happens,  then,  to  the  rest  of  the  messages  received  by  the 
window  function?  They  are  passed  back  to  the  PM  for  default 
processing  using  the  WinDefWindowProc  service.  Its  proto¬ 
type  is  shown  here: 

void  far  *WinDefWindowProc(void  far  ’handle, 
unsigned  short  message, 
void  far  ’paraml, 
void  far  *param2) 


Macro  name 

Value 

Meaning 

WM  BUTT0N1  DOWN 

0x0071 

button  1  down 

WM  BUTTON1UP 

0x0072 

botton  1  up 

WM  BUTTON  1DBLCLK 

0x0073 

double  click  on  button  1 

WM  BUTTON2DOWN 

0x0074 

button  2  down 

WM  BUTTON2UP 

0x0075 

button  2  up 

WM  BUTTON2DBLCLK 

0x0076 

double  click  on  button  2 

WM  BUTTON3DOWN 

0x0077 

button  3  down 

WM  BUTTON3UP 

0x0078 

button  3  up 

WM  BUTTON3DBLCLK 

0x0079 

double  dick  on  button  3 

WM  CHAR 

0x007A 

keystroke  occured 

WM  CREATE 

0x0001 

window  has  been  created 

WM  DESTROY 

0x0002 

window  is  being  destroyed 

WM  ERASEBACKGROUND 

0x004F 

OK  to  erase  background  request 

WM  H SCROLL 

0x0032 

horizontal  scroll 

WM  MOVE 

0x0006 

window  is  being  moved 

WM  MOUSEMOVE 

0x0070 

mouse  has  moved 

WM  PAINT 

0x0023 

window  display  needs  to  be 

refreshed 

WM  SHOW 

0x0005 

window  is  shown  or  removed 

WM  SIZE 

0x0007 

from  the  screen 
window  is  being  resized 

WM  VSCROLL 

0x0031 

vertical  scroll 

WM  QUIT 

0x002A 

window  being  terminated 

Figure  4:  Some  common  messages. 


As  you  probably  guessed,  the  WinDefWindowProc  simply 
passes  back  to  the  Presentation  Manager  the  parameters  with 
which  it  was  called. 

Putting  Together  the  Pieces 

Now  that  you  have  seen  services  needed  to  initialize  and  run 
a  simple  windowed  application  template,  it  is  time  to  put 
together  the  pieces.  The  program  shown  in  Listing  One 
(page  81)  creates  a  window  that  includes  a  system  menu,  a 
title,  a  sizing  border,  and  scroll  bars.  You  can  move  the 
window  around  the  screen,  minimize  or  maximize  it,  and 
change  its  shape.  For  the  moment,  don’t  concern  yourself 
with  the  window  function,  window_  func(  );  it  will  be  ex¬ 
plained  shortly. 

The  program  can  be  compiled  using  Microsoft  C,  Version 
5.1,  using  the  OS/2  Software  Developer’s  Kit.  You  may  need 
to  make  some  small  changes  if  you  are  using  a  different 
compiler.  Notice  that  the  program  defines  INCL_WIN.  This 
definition  is  needed  to  cause  the  prototypes  and  definitions 
for  the  window  system  to  be  loaded  if  you  are  using  the 
Microsoft  C  compiler.  Before  you  try  to  compile  this  pro¬ 
gram,  read  the  next  two  sections. 

The  Definition  File 

A  definition  file  is  used  to  specify  various  options  that  affect 
your  program.  All  definition  files  end  with  the  .DEF  exten¬ 
sion.  If  you  have  been  working  with  OS/2  for  a  while,  then 
definition  files  are  probably  no  stranger  to  you.  (A  detailed 
discussion  of  definition  files  is  beyond  the  scope  of  this 
article,  but  the  interested  reader  will  find  coverage  of  this 
topic  in  my  book  OS/2  Programming:  An  Introduction 
(Berkeley,  Calif.:  Osbome/McGraw-Hill,  1988).  But  unlike 
many  non-PM-compatible  programs  for  which  a  definition 
file  is  optional,  you  must  define  a  definition  file  in  the  link 
line  for  any  PM-compatible  program  you  write.  Aside  from 
other  reasons,  the  overriding  reason  for  this  is  that  you  will 
need  to  specify  more  stack  space  for  the  PM  application  than 
it  will  receive  by  default.  The  Presentation  Manager  template 
in  this  article  is  allocated  4096  bytes,  but  real  world  applica¬ 
tions  may  need  more  or  less  space.  Also,  it  is  a  good  idea  to 
specify  a  heap  size.  Again,  I  allocated  4096  bytes  for  this 
purpose,  but  your  programs  may  need  a  different  amount  of 
space.  You  must  also  include  an  EXPORTS  statement  in 
the  file  that  specifies  the  name  of  the  window  function.  The 
definition  file  for  the  template  is  shown  in  Listing  Two  (on 
page  81). 

Compiling  PM  Programs 

You  will  need  to  specify  some  different  compiler  options 
when  compiling  a  Presentation  Manager  program  than  you 
did  for  a  standard  program.  You  can  use  this  batch  file  if  you 
are  using  the  Microsoft  C  compiler: 

cl  -c  -G2sw  %l.c 

link  %1,„  os2,  %l.def; 

The  -G2sw  option  tells  the  compiler  to  use  a  32-bit  address 
for  all  code  and  data  references,  to  turn  off  stack  checking,  to 
assume  that  the  value  of  the  DS  register  is  different  from  the 
one  in  SS,  and  to  generate  80286  instructions.  Because  the 
Presentation  Manager  requires,  minimally,  an  80286  proces¬ 
sor,  there  is  no  harm  in  generating  80286  instructions.  (It  is 
possible  that  you  will  have  to  use  a  different  set  of  options 
even  if  you  are  using  Microsoft  C,  because  of  future  changes 
to  the  compiler  or  the  PM  environment.) 

Understanding  How  the  Template  Works 

The  operation  of  the  main ( )  function  is  straightforward.  It 
initializes  the  link  between  the  Presentation  Manager  and  the 
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program,  registers  a  new  window  class,  creates  a  window, 
and  executes  its  message  loop.  As  messages  are  received 
they  are  dispatched  to  the  window _func( )  by  calling  WinDis- 
patchMsg.  The  message  loop  terminates  when  the  WM_QU1T 
is  received.  This  message  is  generated  by  choosing  the  close 
option  in  the  window’s  system  menu. 

In  a  PM  application,  the  most  important  single  function  is 
the  window  function.  It  receives  the  messages  sent  by  the  PM 
and  takes  appropriate  action.  The  template  shows  entries  in 
the  switch  statement  for  only  the  most  common  of  the 
several  messages  that  can  be  generated  by  the  PM.  (Keep  in 
mind  that  any  message  that  your  program  does  not  wish  to 
process  must  be  passed  back  to  the  PM  via  the  WinDefWin- 
dowProc  service.)  Let’s  look  at  the  meaning  of  some  of  these 
messages. 

When  a  window  is  created,  the  WM_CREATE  message  is 
sent  to  the  window  function.  This  allows  your  program  to 
initialize  values  or  to  perform  other  startup  operations.  As 
you  know,  the  Presentation  Manager  allows  the  user  to  move 
and  resize  windows.  It  also  allows  the  user  to  cover  part  of  a 
window  with  another.  These  operations  imply  that  all  or  part 
of  the  window  must  be  redrawn  at  some  point  in  time.  The 
PM  generates  the  WM_PAINT  message  whenever  the  con¬ 
tents  of  the  window  must  be  refreshed.  One  common  mis¬ 
conception  about  the  Presentation  Manager  is  that  it  handles 
the  reconstruction  of  a  window  that  has  been  overlaid.  The 
truth  is  that  your  program  must  reconstruct  its  own  window 
whenever  the  WM_PAINT  message  is  received. 

The  WM_ERASEBACKGROUND  message  tells  your  pro¬ 
gram  that  the  window  needs  to  be  erased,  perhaps  because 
the  window  is  being  moved.  By  returning  TRUE,  you  are 
allowing  the  PM  to  do  this  for  you.  Otherwise  your  program 
must  do  it. 


Each  time  a  key  is  pressed,  the  WM_CHAR  message  is 
generated.  Each  time  the  user  requests  a  vertical  scroll,  the 
WM_VSCROLL  message  is  generated.  Each  time  a  horizontal 
scroll  is  requested,  the  WM_HSCROLL  message  is  generated. 
The  mouse  messages  are  self-explanatory. 

When  you  ran  this  program,  a  window  will  pop  up.  This 
window  can  be  resized,  moved,  minimized,  or  maximized. 
Other  than  those  basic  window  operations,  the  program 
does  nothing  else. 

Because  this  program  is  a  template  for  future  applications, 
it  does  not  do  anything  with  the  messages.  But  your  applica¬ 
tions  will  need  to.  Also,  keep  in  mind  that  when  your 
program  does  not  actually  need  to  concern  itself  with  a 
message,  such  as  a  program  that  does  not  have  scroll  bars,  its 
message  can  be  removed  from  the  switch  statement.  In  this 
case  the  default  processing  will  handle  it. 
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Dynamic  Link  Libraries 

Under  Microsoft  Windows 


Sharing  code  through  DLLs  is  one  way 
to  deal  efficiently  with  excess  baggage  in  a 
multitasking  environment 


Margaret  Johnson  and  Mark  Solinski 


With  so  many  people  consider¬ 
ing  the  benefits  of  OS/2, 
dynamic  link  libraries  (also 
known  as  dynalinks  or 
DLLs)  have  become  a  hot 
topic.  Few  people,  however,  realize  that 
DLLs  have  been  available  to  program¬ 
mers  for  more  than  two  years  as  part  of 
the  Microsoft  Windows  operating  envi¬ 
ronment.  As  a  matter  of  fact,  most  of  the 
Microsoft  Windows  environment  is  im¬ 
plemented  as  DLLs.  This  article  discusses 
the  virtues  of  DLLs  and  also  provides  a 
clear  example  of  a  DLL  that  can  be 
integrated  into  any  Windows’  applica¬ 
tion.  It  is  our  hope  that  developers  cur¬ 
rently  creating  run-time  libraries  for  MS- 
DOS,  with  plans  for  future  products 
under  OS/2,  would  consider  DLLs  Mi¬ 
crosoft  for  windows  as  one  of  the  plat¬ 
forms  for  their  products. 

DLLs  Versus  Run-Time  Libraries 

In  the  MS-DOS  world,  code  is  compiled 
and  linked  with  external  libraries  or 
object  modules  to  create  an  executable 
file.  Frequently,  routines  in  libraries  are 
generic,  consisting  of  often-used  func¬ 
tions  — for  example,  the  run-time  library 
included  with  the  compiler.  Each  execut¬ 
able  that  calls  a  routine  from  the  library 
contains  a  copy  of  the  code  for  that 
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function.  Under  typical  DOS  single¬ 
tasking  conditions,  and  assuming  it 
doesn’t  matter  how  large  the  executable 
file  is,  run-time  libraries  are  just  fine. 

However,  having  each  application 
carry  around  a  copy  of  common  code  is 
inefficient  in  a  multitasking  system  such 
as  Windows.  Windows  is  an  operating 
environment  that  sits  on  top  of  DOS 
and  creates  a  nonpreemptive,  event- 
driven  multitasking  environment  for  its 
applications.  This  common  code  “bag¬ 
gage”  can  cause  particularly  severe  prob¬ 
lems  because  Windows,  DOS,  and  your 
application  have  to  share  the  infamous 
640K  of  memory  (assuming  your  sys¬ 
tem  has  no  expanded  memory  and  the 
himem.sys  driver  is  not  installed). 

Windows  relieves  some  of  this  con¬ 
gestion  by  allowing  multiple  instances 
of  the  same  application  to  share  the 
same  code  space,  but,  unfortunately,  if 
multiple  applications  are  loaded,  code 
is  not  shared.  For  example,  if  each  ap¬ 
plication  calls  the  same  function  to 
smooth  data  from  a  run-time  library, 
then  Windows  will  allocate  code  space 
for  the  smooth  function  for  each  appli¬ 
cation.  As  anyone  who  has  run  multiple 
applications  under  Windows  knows, 
memory  is  to  Windows  what  water  is  to 
the  desert  — a  precious  resource  that 
should  not  be  wasted. 

If  a  function  resides  in  a  DLL,  then 
only  one  copy  will  be  loaded  no  matter 
how  many  applications  call  it.  This  ap¬ 
proach  keeps  the  application’s  execut¬ 
able  small  because  the  common  code  is 
not  included  in  each  application.  Also, 
the  code  is  dynamically  loaded  at  run 
time,  so  as  long  as  the  parameters 


passed  in  a  function  call  do  not  change, 
you  can  change  the  innards  of  a  func¬ 
tion  in  a  DLL  at  any  time  without  having 
to  recompile  and  relink  the  application. 
Thus,  judicious  use  of  DLLs  lets  you  cus¬ 
tomize  and  upgrade  your  applications 
without  producing  whole  new  versions. 

Loading  the  library  at  run  time  pro¬ 
vides  other  intriguing  opportunities. 
Some  packages  — for  example,  Actor 
from  Whitewater,  Excel  from  Microsoft, 
and  SQL  Windows  from  Gupta  — can 
integrate  DLL  functions  within  their  pro¬ 
grams.  This  ability  allows  developers  to 
use  their  own  warm  and  comfy  func¬ 
tions  in  extremely  powerful  existing  ap¬ 
plications.  But  wait,  there’s  more!  DLLs 
need  not  contain  any  code  or  data  at  all. 
They  can  also  be  completely  made  of 
system  resources  such  as  fonts,  bit  maps, 
icons,  or  cursors  — a  great  way  to  allow 
customization  of  applications  without 
having  to  distribute  source  code,  a  must 
for  library  developers. 

Problems  with  Creating  DLLs 

As  is  usually  the  case  in  life,  additional 
benefits  are  not  realized  without  some 
pain,  and  this  is  certainly  true  of  DLLs. 
There  are  two  big  differences  between 
code  in  a  DLL  and  code  in  a  standard 
run-time  library  under  MS-DOS.  The 
first  one  is  on  the  tip  of  the  tongue  of 
anyone  who  has  ventured  into  the  DLL 
domain  — the  infamous  SS!=DS  issue. 
The  second  difference  concerns  the  use 
of  global  variables. 

Normally,  when  C  code  is  compiled, 
it  is  assumed  the  data  segment  (DS)  is 
the  same  as  the  stack  segment  (SS).  This 
assumption  is  valid  when  passing  the 
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address  of  a  parameter  to  a  function  for 
the  small  (one  code  segment  and  one 
data  segment)  and  medium  (multiple 
code  segments  and  one  data  segment) 
models,  because  only  the  16-bit  offsets 
of  the  addresses  are  passed. 

DLLs,  however,  have  their  own  data 
segment  and  use  the  stack  of  the  caller. 
In  this  case,  the  stack  segment  does  not 
equal  the  data  segment  (SS!=DS)  and 
the  1 6-bit  offsets  are  not  valid  addresses 
because  all  automatic  variables — pa¬ 
rameters  and  local  variables  — are  kept 
on  the  stack  and  all  others  — globaland 
static  variables  — are  contained  in  the 
data  segment.  This  means  that  an  ad¬ 
dress  passed  to  a  function  must  contain 
both  the  segment  and  offset  as  32-bit  far 
pointers,  and  as  a  result,  some  of  the 
standard  C  run-time  library  functions 
cannot  be  used.  These  functions  are 
listed  in  an  appendix  of  the  Microsoft 
Software  Development  Kit  (SDK)  for 
Windows.  In  general,  any  of  the  buff¬ 
ered  I/O  functions  (/print/  /scan/ 
sscan/  and  so  on),  exec  functions  (for 
example,  execlp ,  execv),  and  spawn  func¬ 
tions  (for  example,  spawn),  spawnv ) 
are  off  limits. 

The  second  problem  occurs  because 
of  our  disposition  and  familiarity  with 
writing  single-tasking  software.  Because 
these  programs  need  not  be  reentrant, 
it  is  common  to  sprinkle  code  gener¬ 
ously  with  global  variables.  This  ap¬ 
proach  can  be  a  source  of  grief  to  the 
person  who  wishes  to  convert  existing 
code  to  work  in  a  DLL.  Although  code 
is  not  reentrant  in  Windows,  the  data  is 
reentrant  because  DLLs  have  only  one 
data  segment,  which  is  shared  by  all 
applications.  You  cannot  expect  a  vari¬ 
able  that  is  set  by  one  function  of  the 
DLL  to  contain  that  value  when  retrieved 
in  another  function. 

An  example  of  this  might  be  a  DLL 
that  contains  routines  for  plotting  the 
values  of  variables.  Usually  a  sequence 
of  calls  consisting  of  initialization,  set¬ 
ting  plot  variables,  graphing  the  plot, 
and  cleanup  would  be  used  to  perform 
this  function.  Putting  the  plotting  vari¬ 
ables  in  global  memory  assumes  each 
application  that  makes  this  series  of 
calls  has  its  own  data  area  to  hold  these 
variables.  If  two  applications  (A  and  B) 
coexist  and  application  A  makes  calls  to 
set  the  plotting  variables,  and  then  B 
does  the  same  before  A  can  make  a  call 
to  plot  the  variables,  the  variables  used 
by  the  DLL  will  be  set  to  B’s  prefer¬ 
ences,  not  A’s. 

Most  of  these  problems  are  inherent 
in  multitasking  and  shared-code  sys¬ 
tems  and  are  not  particular  “quirks”  of 
Microsoft  Windows.  The  solutions  to 
these  problems,  implemented  through 
careful  software  design,  will  certainly 
be  of  benefit  to  developers  who  wish  to 
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port  their  applications  and  libraries  to 
multitasking  environments,  including  OS/ 
2.  The  example  that  follows  illustrates 
how  a  simple,  extendable  help  facility 
can  be  added  to  any  application,  and 
can  be  customized  without  recompiling 
and  relinking  the  main  application. 


Help  Library 

The  help  library  we  have  created  fol¬ 
lows  the  convention  put  forth  in  the 
Microsoft  Windows  Application  Style 
Guide.  All  applications  that  follow 
these  guidelines  will  have  the  same  vis- 
(continued  on  page  32) 


caveats 

As  is  usually  the  case  in  life,  it  takes  a  little  more  to  get  a  little  more. 
This  is  certainly  true  with  DLLs.  There  are  two  big  differences  between  code 
in  a  DLL  and  code  in  a  standard  run-time  library  under  MS-DOS.  The  first  one 
is  on  the  tip  of  the  tongue  of  anyone  who  has  ventured  into  the  DLL  domain. 
This  is  the  SS  !=  DS  issue.  The  second  concerns  the  use  of  global  variables. 

Normally,  when  C  code  is  compiled,  it  is  assumed  that  the  data  segment  (DS) 
is  the  same  as  the  stack  segment  (SS) .  This  is  valid  when  passing  the  address 
of  a  parameter  to  a  function  for  the  small  (i.e.,  one  code  segment  and  one 
data  segment)  and  medium  (i.e.,  multiple  code  segments  and  one  data  segment) 
models  since  only  the  16-bit  offsets  of  addresses  are  passed. 

DLLs,  however,  have  their  own  data  segment  and  use  the  stack  of  the  caller. 

In  this  case,  the  stack  segment  does  not  equal  the  data  segment  (SS!=DS)  and 
the  16-bit  offsets  are  not  valid  addresses  since  all  automatic  variables 
(i.e.,  parameters  and  local  variables)  are  kept  on  the  stack  and  all  others 
(i.e.,  global  and  static  variables)  are  contained  in  the  data  segment.  This 
means  that  any  addresses  passed  to  a  function  must  contain  both  the  segment 
and  offset  (i.e.,  32-bit  far  pointers). 

Because  of  this,  some  of  the  standard  C  run-time  library  functions  cannot  be 
used.  These  are  listed  in  an  appendix  of  Microsoft's  Software  Development  Kit 
(SDK)  for  Windows.  In  general,  any  of  the  buffered  I/O  functions  (e.g., 
fprintf,  fscanf,  sscanf) ,  exec  functions  (e.g.,  execlp,  execv),  and  spawn 
functions  (e.g.,  spawnl,  spawnv )  are  off  limits. 

Because  programs  in  DOS  need  not  be  reentrant,  it  is  common  to  sprinkle  code 
generously  with  global  variables.  This  can  be  a  source  of  grief  to  the  person 
who  wishes  to  convert  existing  code  to  work  in  a  DLL.  Although  code  is  not 
reentrant,  the  data  is.  A  DLL  has  only  one  data  segment,  which  is  shared  by 
all  applications.  Don't  expect  a  variable  that  is  set  by  one  function  of  the 
DLL  to  contain  the  set  value  in  another  function.  A  common  case  is  plotting 
libraries.  Usually  the  sequence  of  calls  consists  of  setting  plot  variables, 
graphing  the  plot  using  the  plot  variables  set  previously,  then  performing 
any  cleanup. 

Putting  the  plotting  variables  in  global  memory  assumes  each  application  that 
makes  this  series  of  calls  has  its  own  data  area  to  hold  these  variables.  If 
these  routines  reside  in  a  DLL,  then  the  global  variable  that  sets  the  x 
origin  within  the  DLL  is  the  same  variable  used  by  any  application  that  calls 
this  routine.  For  example,  if  two  applications  (A  and  B)  coexist  and  applica¬ 
tion  A  makes  calls  to  set  the  plotting  variables,  and  then  B  does  the  same 
before  A  can  call  to  plot,  the  variables  used  by  the  DLL  will  be  set  to  B's 
preferences . 


Example  1:  The  user-defined  resource  named  CAVEATS. ASC 


cookbook 

Steps  to  Follow  when  Creating  a  DLL: 

1.  Create  the  resource  file. 

2.  Create  the  library  source  files. 

3.  Make  sure  you  have  an  initialization  function. 

4.  Create  the  module  definition  file. 

5.  Create  a  make  file  to: 

a.  Compile  library  and  initialization  source  files. 

b.  Use  rc  compiler  to  compile  any  resources. 

c.  Use  the  link4  linker  to  create  the  .EXE  file. 

d.  Attach  the  resources  to  the  .EXE  file. 

e.  Use  the  implib  tool  to  create  an  import  library. 


Example  2:  Another  user-defined  resource,  this  one  called  COOKBOOK.ASC 


references 

Two  books  are  definite  musts: 

Programming  Windows  by  Charles  Petzold 
(Microsoft  Press,  1988) 

Inside  OS/2  by  Gordon  Letwin  (Microsoft 

Press,  1988) 

852  pages  jam-packed  with  Windows  pro¬ 
gramming  tips  and  useful  code.  This  is  an 
incredible  source  for  Windows  developers. 

289  pages  from  the  chief  architect  for 
systems  software  at  Microsoft.  This  book 
is  great  for  getting  a  feel  for  what  OS/2 
has  to  offer  and  the  philosophy  behind 
it.  It  also  gives  a  good  feeling  for  the 
differences  between  the  API  for  Windows 
and  OS/2  without  getting  bogged  down  in 
the  code. 

Example  3-'  A  user-defined  resource  that prowdes  re/erence  in/ormation 
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(continued  from  page  29) 
ual  appearance  and  present  a  consistent 
user  interface  (keyboard,  mouse, 
screen,  and  other  ports).  Bells  should 
be  ringing  inside  your  head  when  you 
hear  phrases  such  as  “All  (your)  appli¬ 
cations  .  .  “same  visual and  “con¬ 


sistent  user .  .  . These  are  usually  some 
of  the  criteria  for  producing  function 
libraries.  Dynamic  libraries  are  an  even 
better  choice  because  sometimes  stan¬ 
dards  change  and  these  changes  can  be 
incorporated  into  a  new  library  an<J  be¬ 
come  immediately  available  to  all  the 


applications  that  used  the  old  library 
without  your  having  to  recompile  and 
relink. 

This  discussion  illustrates  another  fea¬ 
ture  of  DLLs  — the  ability  to  isolate  cus¬ 
tomization  code  into  different  libraries. 
Thus,  developers  need  only  publish  func¬ 
tion  specifications  for  the  routines  in 
the  library.  Microsoft  uses  this  technique 
for  its  hardware  drivers.  Printer  manu¬ 
facturers,  for  instance,  can  write  DLL 
libraries  that  take  advantage  of  the  best 
features  of  their  printers  and  provide 
the  same  “functional”  appearance  to 
Microsoft  Windows.  The  helplib.c  file 
(Listing  One,  page  82)  defines  the  “pub¬ 
lic”  protocol  for  the  help  library.  The 
two  functions  we  create  are  TopicsC ) 
and  Screen(  ).  Topics(  )  displays  a  list  of 
available  help  topics;  ScreenC )  displays 
the  text  relating  to  a  specific  topic. 
There  is  a  one-to-one  mapping  between 
a  screen  and  a  topic.  This  mapping  is 
enforced  by  using  the  same  token  name 
in  the  resource  file,  helplib.rc  (Listing 
Two,  page  82),  for  the  topic  strings  and 
the  user-defined  resources.  For  exam¬ 
ple,  the  token  for  the  “caveats”  topic 
string,  CAVEATS,  is  the  same  as  the 
token  for  the  name  of  the  user-defined 
resource  named  CAVEATS.  The  text  for 
this  screen  is  located  in  the  ASCII  file 
CAVEATS  .ASC  (see  Example  1).  This 
file  can  be  created  with  any  editor. 
There  is  one  file  per  screen.  Each  appli¬ 
cation  that  shares  the  help  library 
would  have  a  sequential  list  of  tokens 
(and  associated  text)  for  the  help  top¬ 
ics.  Examples  2,  3,  and  4  list  other  user- 
defined  resources  used  by  our  library. 

Both  functions  take  as  input  an 
IPSCREEN  type  variable  (as  defined  in 
helplib.h,  Listing  Three,  page  82).  This 
type  is  a  far  pointer  to  a  SCREEN  type 
that  is  typedefc d  as  a  structure  contain¬ 
ing  the  variables  wStart,  wEnd,  and 
wScreen.  TopicsC )  uses  the  wStart  and 
wEnd  token  settings  to  reference  the 
range  of  character  strings  to  load.  Both 
TopicsC )  and  ScreenC )  use  wScreen  to 
reference  the  user-defined  ASCII  file 
resources.  All  public  functions  (that  is, 
those  having  the  ability  to  be  invoked 
from  outside  the  library)  must  be  de¬ 
clared  as  FAR  PASCAL.  Declaring  a  func¬ 
tion  FAR  allows  it  to  be  accessed  from 
another  application  that  will  not  have 
the  same  code  segment.  The  PASCAL 
declaration  specifies  the  use  of  the  Pas¬ 
cal  calling  sequence,  which  means  that 
parameters  are  pushed  on  the  stack 
from  left  to  right  instead  of  from  right  to 
left,  as  in  C. 

Figure  1  shows  the  dialog  box  that 
pops  up  when  TopicsC )  is  called.  The 
dialog  box  displays  a  list  box  contain¬ 
ing  the  strings  mentioned  previously 
and  the  two  push  buttons  Help  and 
(continued  on  page  35) 


versus  run-time  libraries 

In  the  MS-DOS  world,  code  is  compiled  and  linked  with  external  libraries  or 
object  modules  to  create  an  executable.  Frequently,  routines  in  libraries  are 
generic,  consisting  of  often-used  functions.  An  example  of  this  is  the  run¬ 
time  library  included  with  the  compiler.  Each  executable  that  calls  a  routine 
from  the  library  contains  a  copy  of  the  code  for  that  function.  Under  typical 
DOS  single-tasking  conditions,  and  assuming  it  doesn't  matter  how  large  the 
executable  file  is,  run-time  libraries  are  just  fine. 

Having  each  application  carry  around  a  copy  of  common  code  is  inefficient  in 
a  multitasking  system  such  as  Windows.  Windows  is  an  operating  environment 
that  sits  on  top  of  DOS  and  creates  a  nonpreemptive,  event-driven  multitask¬ 
ing  environment  for  its  applications.  In  fact,  with  Windows,  this  is  even 
more  important  since  Windows  is  constrained  to  sit  on  top  of  DOS,  and  the  en¬ 
vironment  that  DOS  sits  in  only  allows  640K  of  memory  (assuming  no  expanded 
memory) .  In  Windows,  if  multiple  instances  of  the  same  application  are 
loaded,  they  will  share  the  same  code  space.  If  multiple  applications  are 
loaded,  however,  code  is  not  shared.  If  each  application  calls  the  same  func¬ 
tion  to  smooth  data  from  a  run-time  library,  then  Windows  will  allocate  code 
space  for  the  smooth  function  for  each  application.  As  anyone  who  has  run 
multiple  applications  under  Windows  knows,  memory  is  to  Windows  what  water  is 
to  the  desert — a  precious  resource  that  should  not  be  wasted. 

If  a  function  resides  in  a  DLL,  then  only  one  copy  will  be  loaded  no  matter 
how  many  applications  call  it.  This  also  keeps  the  application's  executable 
small  by  keeping  the  common  code  out  of  each  application.  Not  only  that,  but 
since  the  code  is  dynamically  loaded  at  run  time,  as  long  as  the  parameter 
sequence  of  the  function  call  does  not  change,  the  innards  of  a  function  in  a 
DLL  can  be  changed  without  forcing  the  application's  executable  to  be 
recompiled  and  relinked. 

Loading  the  library  at  run  time  allows  other  exciting  opportunities.  Some 
packages  allow  functions  in  a  DLL  to  be  called  within  their  program.  These 
include  Actor  from  Whitewater,  Excel  from  Microsoft,  and  SQL  Windows  from 
Gupta.  Thus,  the  developers  can  use  his  warm  and  comfy  functions  in  extremely 
powerful  existing  applications.  But  wait,  there's  more!  DLLs  need  not  contain 
any  code  or  data  at  all!  They  can  also  be  completely  made  of  resources  such 
as  fonts,  bit  maps,  icons,  or  cursors. 


Example  4:  A  fourth  user-defined  resource,  stored  in  the  ASCII  file 
VSRUNTTME.ASC 


'M 


Figure  1:  The  dialog  box  that  pops  up  when  TopicsC )  is  called 
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(continued  from  page  32) 

Cancel.  The  Screen( )  function  is  called 
if  you  wish  to  get  help  on  the  high¬ 
lighted  topic.  As  shown  in  Figure  2, 
Screen(  )  displays  a  dialog  box  that  con¬ 
tains  the  help  text  in  a  scrollable  win¬ 
dow  along  with  the  four  push  buttons 
Topics,  Next,  Previous,  and  Cancel.  Push¬ 
ing  Topics  returns  you  to  the  Topics 
dialog  box.  Pushing  Next  displays  the 
text  for  the  next  help  topic  listed  in  the 
Topics  dialog  box  list;  and  pushing  Pre- 


DLLs  need  not  contain 
any  code  or  data  at 
all.  They  can  also  be 
completely  made  of 
system  resources  such 
as  fonts,  bit  maps, 
icons,  or  cursors 


vious  displays  the  previous  one.  You 
can  also  call  Screen( )  directly  to  dis¬ 
play  a  specific  help  text. 

The  “private”  protocol  of  the  DLL  is 
implemented  in  the  file,  helpdlg.c  (List¬ 
ing  Four,  page  82).  The  ScreenDlgProc, 
Screen  WndProc,  and  TopicDlgProc  func¬ 
tions  process  the  messages  that  Micro¬ 
soft  Windows  sends  to  the  dialogs.  Typi¬ 
cally,  we  are  most  concerned  with  the 
user-interface  messages  such  as  scroll¬ 
ing  the  window  and  moving  it  around 
and  the  system  messages  such  as  redis¬ 
playing  a  portion  of  the  screen  that  is 
now  visible  because  it  was  moved  in 
front  of  a  window  that  was  previously 
obscuring  it.  A  full  discussion  of  the 
Microsoft  Windows  message  system  is 
beyond  the  scope  of  this  article  and  we 
recommend  that  those  people  interested 
in  the  subject  get  a  copy  of  Program¬ 
ming  Windowsby  Charles  Petzold  (Micro¬ 
soft  Press,  1988)  — an  invaluable  aid  for 
all  Windows  programmers. 

Another  important  part  of  the  private 
protocol  of  the  DLL  is  the  maintenance 
of  the  screen  information.  One  “fea¬ 
ture”  of  a  DLL  is  reentrancy.  This  com¬ 
plicates  matters  if  you  need  to  maintain 
global  data.  One  way  of  keeping  track 
of  global  data  is  to  allocate  extra  bytes 
to  the  window  structure  when  register¬ 
ing  the  window  class.  We  have  done 


versus  run  tine  libraries 

In  the  MS-DOS  world,  code  is  compiled  and 
linked  with  external  libraries  or  object 


references 

Two  books  are  definite  musts: 

Programming  Windows  by  Charles  PetzDld 
Microsoft  Press:  1988 

852  pages  Jam-packed  with  Windows  programming 
tips  and  useful  code.  This  is  an  incredible 
source  for  Windows  developers. 


JS 


Topics  j 

Previous 

( 

Figure  2:  ScreenC )  displays  a  dialog  box  that  contains  the  help  text  in  a 
scrollable  window  along  with  the  four  push  buttons  Topics,  Next,  Previous,  and 
Cancel. 
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(continued  from  page  35) 
this  by  setting  the  cbWndExtra  field  to 
sizeofrHANDLE)  bytes  when  register¬ 
ing  the  help  screen  window  class  in 
libinitc.c  (Listing  Five,  page  87).  When 
ScreenWndProc( /receives  a  WM_CRE- 
ATE  message,  it  allocates  a  chunk  of 
local  memory  to  hold  the  window’s 
screen  information  and  puts  the  handle 
into  the  window  structure  at  offset  0. 
This  allows  easy  retrieval  when  an 
event  occurs  that  requires  the  help  win¬ 
dow’s  screen  data. 

DLL  libraries  are  different  from  ap¬ 
plications  in  that  they  don’t  and  can’t 
invoke  the  C  run-time/Windows  initiali¬ 
zation.  Any  initialization  that  the  library 
needs  must  be  done  by  the  developer, 
usually  with  a  short  assembly  program 
that  in  turn  calls  a  C  function  in  the 
library  to  perform  the  initialization, 
libintc.c  and  libinita.asm  (Listing  Six, 
page  87)  provide  this  service. 

The  final  piece  of  our  help  library 
puzzle  is  the  module  definition  file, 
helplib.def  (Listing  Seven,  page  88).  The 
primary  purpose  of  the  module  defini¬ 
tion  file  is  to  define  the  characteristics 
of  the  data  and  code  segments,  the 
local  heap,  and  the  exported  functions. 
If  this  were  a  module  definition  file  for 
a  Windows  application,  it  would  also 
include  a  parameter  for  the  stack  size, 
which  is  not  necessary  in  a  DLL  be¬ 
cause  the  DLL  uses  the  calling  appli¬ 
cation’s  stack.  Also  because  all  libraries 
have  only  one  data  segment,  the  option 
SINGLE  must  be  used  on  the  DATA 
definition  line. 

The  EXPORTS  section  defines  the  func¬ 
tions  that  are  accessible  to  the  outside 
world.  Of  course,  ScreenO  and  Top¬ 
ics ( )  are  in  this  list,  but  so  are  the 
functions  ScreenDlgProc,  ScreenWnd- 
Proc,  and  TopicsDlgProc.  This  is  neces¬ 
sary  because  these  DLL  routines  are 
called  by  Windows  to  process  user  in¬ 
put  and  that  is  why  these  functions  are 
declared  FAR  PASCAL.  The  LINK4 
linker  uses  the  module  definition  file  to 
add  the  necessary  information  to  the 
.EXE  file,  which  allows  run-time  linking 
and  execution  of  the  library  routine. 

The  make  file,  helplib  (Listing  Eight, 
page  88)  uses  the  files  discussed  previ¬ 
ously  to  create  the  library  files 
helplib.lib  and  helplib.exe.  The  com¬ 
piler  switch  that  is  necessary  for  a  DLL 
is  the  -Alnw  switch  (or  -Asnw  for  a 
small  model).  This  switch  is  needed  to 
ensure  that  SS!=DS. 

Testing  the  Library 

The  help  library  we  provide  gives  an 
overview  of  this  article  and  a  step-by- 
step  description  of  the  process  of  creat¬ 
ing  a  library.  We  have  also  included 
two  examples  of  how  the  library  can  be 
used.  The  first,  helpdemo.exe,  and  its 
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associated  source  code  (in  Listings  Nine  - 
Eighteen,  pages  89  -  91)  shows  how 
easy  it  is  to  call  a  DLL  from  a  Windows 
application.  The  function  HelpDe- 
moMsg( )  sets  up  the  screen  information 
and  calls  the  Topics( )  function  in  the 
DLL  whenever  the  FI  key  is  pressed  or 
the  Help!  menu  item  is  selected. 

The  second  example,  helplib.act  (List¬ 
ing  Nineteen,  page  91),  is  written  in 
Actor,  an  incrementally  compiled  lan¬ 
guage  for  developing  Windows  appli¬ 
cations.  This  example  illustrates  how 
different  DLLs  can  be  specified  at  run 
time.  As  long  as  the  application  knows 
what  functions  a  library  contains,  it  can 
load  the  library,  execute  the  function, 
and  then  free  the  library.  Actor  pro¬ 
vides  a  way  to  experiment  with  chang¬ 
ing  libraries  on  the  fly  and  seeing  how 
these  changes  affect  the  way  your  ap¬ 
plication  behaves. 

Conclusion 

Dynamic  link  libraries  provide  a  great 
way  to  reuse  code.  With  correct  modu¬ 
lar  design,  applications  can  be  custom¬ 
ized  without  having  to  recompile  and 
relink.  DLLs  perform  best  when  they 
are  called  to  process  data  and  then  re¬ 
turn.  This  is  because  the  DLL  is  shared 
by  all  the  applications  in  the  system  that 
call  the  library,  and  therefore  global 
data  cannot  be  maintained.  One  way  to 
overcome  this  limitation  is  to  store  in¬ 
formation  specific  to  the  window  in  the 
window’s  data  structure. 

We  hope  this  article  gives  you  a  taste 
of  the  flexibility  of  DLLs.  Developers 
who  have  built  DLLs  for  Microsoft  Win¬ 
dows  have  had  an  early  taste  of  OS/2 
programming.  Those  people  who  de¬ 
velop  third-party  libraries  for  sale  to  the 
PC  programming  community  will  find 
great  acceptance  from  the  Microsoft  Win¬ 
dows  community  and  will  also  provide 
an  easy  platform  for  porting  their  librar¬ 
ies  to  OS/2. 
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Writing 

Portable  Applications  with 

X/GEM 

How  does  X/GEM  compare  with  other 
windowing  systems? 


Bill  Fitter 


What  are  the  main  issues  in 
creating  portable  graphics 
applications?  For  example, 
how  do  you  implement  for¬ 
eign  language  versions  of 
your  software?  And  how  do  you  handle 
the  fundamental  differences  among  vari¬ 
ous  hardware  platforms?  To  achieve  port¬ 
ability,  you  need  to  follow  certain  gen¬ 
eral  guidelines.  The  rules  depend  partly 
on  what  your  application  does,  and 
partly  on  what  you  want  to  port  to.  This 
article  explores  these  and  other  prob¬ 
lems,  showing  how  it’s  done  with  X/ 
GEM,  and  comparing  the  X/GEM  so¬ 
lution  with  other  common  windowing 
systems. 

Let’s  begin  by  discussing  what  X/ 
GEM  is. 

X/GEM  is  based  on  the  older  Gra¬ 
phical  Environment  Manager  (GEM),  in¬ 
troduced  in  1984  by  Digital  Research 
(DRI).  GEM  enables  graphics  applica¬ 
tions  to  run  on  a  broad  range  of  com¬ 
puters,  ranging  from  Ataris  to  low-end 
8088  based  PCs  and  compatibles.  X/ 
GEM  provides  a  GEM  compatible  ap¬ 
plication  program  interface  (API)  that 
functions  on  higher-end  workstations, 
thus  allowing  GEM  programs  to  be  more 
easily  ported  to  these  more  powerful 
computers.  X/GEM  currently  works  with 
DRI’s  FlexOS  (a  multitasking,  multiuser, 
real-time  operating  system),  and  ver¬ 
sions  are  in  the  works  for  Presentation 
Manager  and  the  X  Window  system. 

The  X/GEM  API  provides  two  sets  of 
run-time  application  services,  shown  in 
Figure  1.  The  first,  called  the  virtual 
device  interface  (VDI),  is  where  graph¬ 
ics  portability  is  implemented.  The  sec¬ 
ond  is  the  application  environment  serv¬ 
ices  (AES),  which  provides  the  user  in¬ 
terface  building  blocks  for  an  appli¬ 
cation.  Built  on  top  of  the  VDI,  the  AES 


Bill  Fitter  is  the  X/GEM  project  manager 
with  Digital  Research  (DRI)  in  Mon¬ 
terey,  Calif.  He  can  be  reached  at  408- 
649-3896. 


also  provides  functions,  that  enhance 
portability  to  both  single  tasking  and 
multitasking  operating  environments.  X/ 
GEM  doesn’t  provide  file  system  func¬ 
tions.  Instead,  GEM  applications  rely  on 
the  services  provided  by  the  underlying 
operating  system. 

This  basic  structure  of  the  X/GEM 
API  — a  user-interface-function  set  rest¬ 
ing  atop  device  independent  graphics  — 
is  similar  to  Windows  and  the  Macin¬ 
tosh.  All  three  systems  implement  a  user 
interface  “policy:”  that  is,  the  basic  look 
and  feel  shared  by  all  applications  run¬ 
ning  in  that  windowing  environment. 

X  Window  takes  a  different  approach. 
Its  implementors  went  to  great  lengths 
to  provide  a  “policy-free”  interface.  For 
example,  the  Xlib  interface  does  not 
contain  any  window  control  mecha¬ 
nisms.  Instead  it  abdicates  this  policy  to 
an  X  “window  manager”  responsible 
for  providing  the  look  and  feel  of  the 
interface.  This  design  has  merits,  be¬ 
cause  all  X  applications  can  be  made  to 
behave  in  a  fashion  deemed  appro¬ 
priate  by  the  window  manager.  At  MIT, 
before  X  was  developed,  there  were 
many  different  vendors  supplying  soft¬ 
ware  and  hardware,  leading  to  a  Tower 
of  Babel  effect.  Now  for  applications 
that  use  X,  a  person  needs  to  leam  only 
one  window  manager  in  order  to  use 
an  application  from  any  vendor.  This 
also  allows  new  ways  of  interacting  with 
the  user  to  be  developed,  which  is  use¬ 
ful  because  the  art  of  user-interface  de¬ 
sign  is  still  in  its  infancy. 

The  X  Window  philosophy,  however, 
also  has  drawbacks.  One  is  increased 
application  complexity  due  to  the  need 
to  negotiate  with  a  window  manager 
which,  for  example,  may  not  allow  a 
window  to  be  arbitrarily  located  on  the 
display  device.  A  second  problem  is 
that  this  design  requires  more  comput¬ 
ing  resources.  That  might  not  be  an 
issue  in  a  workstation  environment,  but 
it  is  on  a  low-end  personal  computer. 

Another  X  Window  problem  is  the 


proliferation  of  window  managers,  each 
of  which  sets  forth  its  own  user-inter¬ 
face  policy.  As  of  this  writing  no  clear 
winner  has  emerged,  with  the  result 
that  end  users  are  confused  about 
which  window  manager  to  select.  The 
Open  Software  Foundation  (OSF) 
hopes  to  end  the  dilemma  by  choosing 
one  as  the  X  Window  user-interface 
standard.  A  number  of  vendors  have 
proposed  their  solutions  to  OSF,  in¬ 
cluding  DRI  with  X/GEM.  Whatever  the 
outcome,  end  users  could  benefit  by 
having  a  single  style  of  user  interface 
across  the  entire  range  of  supported 
applications  and  computers.  Another 
beneficiary  is  programmers,  who  will 
then  be  able  to  write  portable  applica¬ 
tions  for  a  consistent  environment  with 
few  worries  about  hardware  and  oper¬ 
ating  system  differences. 

Now  let’s  consider  some  specific  is¬ 
sues  that  arise  when  you  want  to  make 
your  graphics  application  portable. 

Dealing  with  Graphics  Devices 

Windowing  systems  such  as  Presenta¬ 
tion  Manager  and  X  Window  provide  a 
set  of  functions  that  draw  to  the  screen 
as  independently  of  the  actual  physical 
device  as  possible.  These  functions  also 
return  information  about  the  device  so 
that  the  program  can  deal  with  specifics 
and  idiosyncrasies  consistently. 

In  X/GEM,  the  VDI  handles  graphics- 
device  portability.  The  VDI  is  built 
around  a  conceptual  graphics  model 
called  a  workstation  (not  to  be  con¬ 
fused  with  those  powerful  high-end  per¬ 
sonal  computers  going  by  the  same 
name).  X/GEM  VDI  workstations  are 
specific  graphical  devices  available  to 
an  application.  Thus,  the  display  and 
the  printer  are  both  VDI  workstations. 
When  an  application  opens  a  worksta¬ 
tion,  the  appropriate  graphical  device 
driver  is  loaded.  The  device  driver  trans¬ 
lates  high-level  VDI  commands  into  the 
low-level  actions  necessary  to  produce 
graphical  information  on  the  target  de- 
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vice  or  to  receive  information  from  it. 

This  approach  is  similar  to  that  taken 
by  other  windowing  systems.  In  Win¬ 
dows  the  approximate  equivalent  is 
called  a  display  context,  on  the  Macin¬ 
tosh  it  is  called  a  grafPort,  and  in  Xlib  it 
is  called  a  graphics  context. 

X/GEM  furnishes  multiple  classes  of 
workstations.  These  include  screens,  plot¬ 
ters,  printers,  cameras,  scanners,  and 
metafiles  (files  containing  sets  of 
graphic  commands).  In  general,  the 
application  can  send  a  given  set  of  com¬ 
mands  to  the  screen  and  then  issue  the 
same  set  of  commands  to  the  printer  or 
metafile  device  to  create  a  more  endur¬ 
ing  copy  of  the  output.  Graphic  systems 
such  as  the  Macintosh  and  X  don’t  have 
the  same  kind  of  generality  built  into 
their  graphics  models,  choosing  instead 
to  support  primarily  the  screen  display 
device. 

One  of  the  most  important  issues  in 
writing  portable  graphics  applications 
concerns  the  concept  of  uniform  ren¬ 
dering.  Graphical  devices  span  a  wide 
range  of  addressability  and  resolution. 
Many  displays  for  PCs  — the  Macintosh 
being  a  notable  exception  — use  pixels 
that  are  not  square.  This  means  that  a 
square  box  with  ten  units  of  measure¬ 
ment  in  height  and  width  will  show  up 
as  a  rectangle.  The  ratio  of  height  to 
width  is  called  the  aspect  ratio  of  the 
device. 

Microsoft  Windows  handles  the  as¬ 
pect  ratio  by  providing  some  half- 
dozen  functions  to  scale  coordinates 
for  a  display  context.  The  application 
programmer  selects  from  coordinate  sys¬ 
tems  that  are  metric,  English,  arbitrary, 
or  raster  dependent.  Each  coordinate  is 
scaled  automatically  at  output  time. 

In  contrast,  the  X/GEM  VDI  uses  pri¬ 
marily  raster  coordinates.  This  means 
the  application  must  do  its  own  scaling. 
The  GEM  designers  felt  that  the  appli¬ 
cation  is  best  able  to  decide  how  to  do 
the  scaling  in  the  most  efficient  manner. 
For  example,  some  CAD  applications 
need  to  scale  in  floating  point,  whereas 
many  publishing  applications  can  use 
integer  or  fixed  point  scaling. 

The  X/GEM  VDI  provides  aspect  ra¬ 
tio  information  so  that  the  application 
can  handle  coordinate  translation  in  the 
most  appropriate  manner.  The  height 
and  width  of  a  pixel  (in  microns)  is 
returned  by  the  VDI  call  that  opens  the 
workstation.  Listing  One,  page  92,  illus¬ 
trates  how  this  is  done  with  a  simple 
integer  scaling  function. 

Speaking  in  Foreign  Tongues 

As  new  markets  open,  it  becomes  in¬ 
creasingly  important  to  be  able  to  trans¬ 
late  applications  into  other  languages. 
Doing  this  easily  requires  a  strategy 
other  than  the  traditional  use  of  em¬ 


bedded  text  literals  in  the  source  code.  where.  Thus,  for  example,  you  can  use 

With  X/GEM,  foreign  language  port-  RCS  to  place  a  string  object  in  a  dialog 

ability  can  be  achieved  by  placing  all  box,  change  the  text  as  necessary,  re- 

the  application’s  text  messages  in  re-  position  and  tweak  it,  and  then  label  the 

source  files.  One  of  the  system’s  most  object  for  access  by  the  application, 

important  portability  feature  is  the  AES  The  difference  between  constructing  a 

function  for  object  and  resource  han-  moderately  complex  dialog  with  the  RCS 

dling.  The  GEM  Programmer’s  Tool  to  versus  a  compiled  language  is  incredible, 

build  and  edit  these  resources  is  called  The  RCS  produces  a  resource  file.  It 
the  resource  construction  set  or  RCS.  can  also  produce  a  file  format  suitable 
RCS  provides  tools  for  constructing  for  compiling  directly  into  the  program, 

and  displaying  menus,  windows,  and  You  might  do  this  for  a  variety  of  rea- 

dialog  boxes  in  files  independent  of  the  sons,  such  as  protecting  the  resource 

application  code.  Each  object  has  a  po-  information  or  reducing  distribution  com- 

sition  and  size,  along  with  type  and  plexity  by  eliminating  the  resource  file 

data  information.  The  objects  are  or-  altogether.  The  penalty  for  doing  so  is 

ganized  hierarchically,  thus  allowing  loss  of  portability  to  some  extent, 

them  to  be  defined,  displayed,  and  ma-  The  resource  file  shown  in  Listing 
nipulated  relative  to  each  other.  Exam-  Two,  page  92,  contains  a  single  dialog 

pies  include  icons,  text,  boxed  text,  box  with  two  button  objects.  Without 

boxes,  editable  text  fields,  and  pro-  going  into  detail  about  the  construction 

grammer-defined  objects.  of  a  resource,  there  are  a  few  things  to 

The  collection  of  objects  for  a  given  note.  First,  it  took  less  than  three  min- 

application  is  grouped  together  in  a  utes  from  start  to  finish  to  create  the 

resource  file.  When  a  GEM  application  dialog.  Figure  2  shows  the  RCS  display 

initializes  itself  at  run  time,  it  calls  the  during  the  design.  Next,  the  structure  of 

AES  to  load  the  resource  file.  The  re-  the  resource  file  is  well  defined  and 

source  file  contains  all  the  text  that  the  therefore  described  by  the  first  few  de¬ 
user  sees,  separate  from  the  executable  fines,  which  give  critical  array  sizes, 

code.  This  allows  a  programmer  to  pre-  Finally,  the  RCS  generates  an  include 

pare  a  resource  file  for  each  supported  file  with  the  contents: 

foreign  language  without  recompiling 

the  application.  ^define  SAMPLDLG  0  /*  TREE  V 

One  warning:  If  you  intend  to  trans-  ^define  BTNCANCL  4  /*  OBJECT  in 
late  menu  and  dialog  items,  leave  TREE  #0  7 

plenty  of  extra  visual  space  in  the  en-  ^define  BTNOK  3  /*  OBJECT  in 

closing  boxes  for  the  translated  mes-  TREE  #0  V 

sages.  For  example,  translating  from  Eng¬ 
lish  to  German  usually  requires  between  The  #defines  give  indices  into  the  re- 
50  and  100  percent  more  characters  per  source  array  so  that  the  application  can 
message.  refer  to  specific  objects.  These  data  ob- 

The  RCS  also  allows  an  application  jects  change  values  according  to  user 
designer  to  get  quick  feedback  about  input,  thus  allowing  the  application 
the  user  interface,  even  before  a  large  to  determine  exactly  what  the  user 
amount  of  code  is  written.  Instead  of  entered, 
using  the  application’s  programming  lan¬ 
guage,  you  use  the  interactive  RCS  tools  What  about  the  OS? 
to  specify  exactly  what  gets  placed  The  capabilities  and  characteristics  of 


Figure  1:  X/GEM  structure 
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various  operating  systems  (DOS  vs 
FlexOS  vs  Unix  vs  OS/2)  also  influence 
strategy  in  writing  portable  applications. 
Two  critical  areas  are  file  and  event 
handling.  Many  GEM  applications  call 
directly  the  native  operating  system’s 
file-handling  primitives.  This  is  done 
primarily  to  avoid  the  overhead  of  C 
run-time  libraries.  Another  reason  for 
avoiding  the  run-time  libraries  is  that 
they  usually  build  in  bulky  support  to 
handle  screen  output,  such  as  printf( ). 
In  general,  applications  running  under 
a  windowing  manager  such  as  GEM 
and  Windows  cannot  use  the  operating 
system’s  screen  and  keyboard  I/O  serv¬ 
ices  at  all;  all  I/O  must  go  through  the 
environment  manager. 

An  application  targeted  toward  sev¬ 
eral  operating  systems  needs  a  file  sys¬ 
tem  interface  that  can  be  readily  ported 
to  any  of  them.  One  way  to  deal  with 
this  problem  is  to  use  the  standard  rou¬ 
tines  (that  is,  j open  ( ),  J close  ( ), 
fread  (  ), /write  (  ),  and  so  on)  provided 
with  the  C  run-time  library,  and  pay  the 
price  in  overhead  for  portability.  An¬ 
other  way  is  to  emulate  the  file  system 
calls  of  one  operating  system  on  an¬ 
other.  For  example,  DRI  furnishes  a 
DOS  emulation  run-time  library  for  the 
X/GEM  product  on  FlexOS. 

The  AES  provides  a  degree  of  oper¬ 
ating  system  independence  by  provid¬ 
ing  a  file-selector  mechanism  enabling 
an  application  to  solicit  a  file  specifica¬ 
tion  from  the  end  user.  This  lets  the 
user  navigate  through  the  file  system 
and  change  directories  as  necessary  to 
find  or  specify  the  desired  file.  DRI 
plans  to  tailor  the  mechanism  for  each 
supported  operating  system  in  order  to 
hide  the  subtleties  of  file  system  naviga¬ 
tion  from  the  user. 

The  AES  also  provides  an  event 
driven  input  model  with  which  applica¬ 
tions  can  work  effectively  in  a  broad 
range  of  environments.  The  application 


waits  for  multiple  events,  where  an 
event  could  be  a  keypress,  a  mouse 
button  press,  a  timer  tick,  or  certain 
kinds  of  messages.  These  messages  in¬ 
clude  notifications  that  the  user  has  re¬ 
quested  a  menu  item,  or  changed  the 
size  or  position  of  a  window.  A  mes¬ 
sage  can  also  be  information  from  other 
applications.  The  point  is  that  the  appli¬ 
cation  doesn’t  have  to  actively  poll  the 
environment  looking  for  something  to 
happen.  Instead  it  suspends  activity  un¬ 
til  a  specified  event  occurs.  This  greatly 
enhances  portability  to  multitasking  en¬ 
vironments;  the  application  becomes  a 
“good  neighbor”  in  the  computing  en¬ 
vironment  by  not  wasting  unnecessary 
CPU  resources. 

The  X/GEM  event  structure  in  Listing 
Three,  page  92,  looks  complicated,  but 
it’s  easy  to  understand.  The  program 
fills  in  the  e  Jlags  field  with  a  bitmask 
containing  those  events  that  it  wants  to 
wait  for.  When  a  bit  for  a  specific  event 
is  turned  on,  the  structure  element  con¬ 
trolling  that  event  must  be  filled  in.  In 
the  example  shown  in  Listing  Four,  page 
92,  the  program  waits  for  one  of  two 
things  to  happen:  either  a  keypress  or 
an  elapsed  time  of  ten  seconds.  The 
application  can  also  wait  for  a  button 
press,  a  message,  or  for  the  mouse  to 
enter  or  leave  one  of  two  rectangular 
regions  on  the  screen. 

In  Windows  and  in  X,  the  application 
notifies  the  system  that  it  will  wait  for  a 
number  of  different  types  of  messages. 
This  is  roughly  equivalent  to  the 
evnt_event( )  mechanism  of  GEM,  ex¬ 
cept  that  events  are  serialized  because 
the  application  can  only  receive  a  sin¬ 
gle  message  at  a  time.  The  Macintosh 
has  a  much  cruder  mechanism,  where 
it  cycles  through  a  loop,  polling  certain 
functions  to  see  if  anything  has  hap¬ 
pened.  This  works  fine  when  a  single 
application  is  running  on  the  machine, 
but  it  causes  conflicts  and  excessive 


overhead  when  multiple  applications 
are  polling  at  the  same  time. 

Moving  Among  Different 
Processors 

The  wide  differences  among  microproc¬ 
essor  architectures  demand  a  careful 
strategy  where  portability  is  in  the  pic¬ 
ture.  The  main  requirements  are  pro¬ 
gramming  in  a  portable  language  such 
as  C,  along  with  careful  attention  to, 
and  independence  of,  byte  ordering, 
integer  size,  and  correct  and  consistent 
use  of  pointers.  These  and  other  con¬ 
cerns  were  discussed  in  Greg  Black- 
ham’s  article  “Building  Software  for  Port¬ 
ability”  (DDJ,  December  1988). 

With  respect  to  X/GEM  programs, 
there  is  one  additional  set  of  portability 
issues.  In  order  to  minimize  the  amount 
of  code  in  GEM  applications,  the  X/ 
GEM  bindings  are  defined  to  use  the 
mixed  model  programming  applicable 
to  the  segmented  Intel  architectures.  To 
simplify,  an  application  can  use  either 
long  pointers  — access  to  the  entire  ad¬ 
dress  space  at  the  expense  of  code  com¬ 
pactness  — or  short  pointers,  which  de¬ 
crease  executable  program  size  but  can 
only  address  up  to  64K  from  a  fixed 
location.  GEM  applications  are  mostly 
in  small  models  (short  pointers)  with 
certain  kinds  of  pointers  being  kept  in 
long  format.  Although  this  is  an  extra 
burden  to  the  application  programmer, 
it  can  be  readily  handled  by  the  strict 
parameter  type  checking  available  in 
most  up-to-date  C  compilers. 

Writing  portable  applications  takes  a 
different  design  philosophy  and  tool 
set  than  developing  for  a  single  system. 
There’s  nothing  mysterious  about  the 
process;  it’s  just  different,  requiring  ob¬ 
servance  of  some  common  sense  rules. 
A  well-crafted  user-interface  subsystem 
such  as  X/GEM,  which  was  specifically 
created  for  multiplatform,  multi-device 
portability,  can  also  greatly  ease  the 
headaches  of  moving  software  from  one 
environment  to  another  that  differs  radi¬ 
cally. 

Availability 

All  source  code  for  articles  in  this  issue 
is  available  on  a  single  disk.  To  order, 
send  $14.95  (Calif,  residents  add  sales 
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Network  Windowing 

Using  the 
X  Window  System 

For  networks, 

X  is  the  biggest  game  in  town 


Jim  Gettys 


The  X  Window  system  is  a  de¬ 
vice  independent,  multitasking 
windowing,  and  graphics  sys¬ 
tem  designed  to  operate  across 
heterogeneous  networks.  As 
such,  X  supports  high-performance  graph¬ 
ics  and  window-management  mecha¬ 
nisms  to  provide  a  hierarchy  of  over¬ 
lapping,  resizable  windows.  The  X  sys¬ 
tem  is  based  upon  a  client/server  archi¬ 
tecture  whereby  the  client  (that  is,  the 
application  program)  requests  that  the 
server  (the  program  that  controls  the 
user-interface  at  the  workstation)  be 
responsible  for  drawing  text,  windows, 
and  other  objects.  Through  this  client/ 
server  architecture,  applications  can  run 
on  any  machine  in  the  network  and  can 
be  accessed  by  any  workstation  or  PC 
running  on  an  X  server. 

The  X  Window  system  was  originally 
designed  at  the  Massachusetts  Institute 
of  Technology  (MIT)  to  provide  a  ge¬ 
neric,  network  windowing  environment 
for  dissimilar  bit-mapped  workstations. 
The  system  makes  it  possible  for  MIT  to 
network  its  collection  of  incompatible 
computers,  which  have  accumulated  at 
the  institute  over  the  years.  X,  which  is 
now  a  de  facto  standard  and  is  publicly 
available,  provides  efficient  workgroup 


Jim  Gettys  was  an  original  member  of 
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computing,  connecting  the  dissimilar 
computing  environments  that  exist  in 
many  situations. 

The  X  Window  system  includes  the 
Xlib  graphics  subroutine  library,  the  X 
network  protocol  (which  handles  trans¬ 
mission  between  client  applications  and 
server  processes  running  on  remote  work¬ 
stations),  an  X  toolkit  (which  program¬ 
mers  use  to  build  graphical-user  inter¬ 
faces),  and  several  window  managers. 
The  window-manager  program  is  dis¬ 
tinct  from  the  base  window-system 
server  and  provides  part  of  the  user 
interface  for  manipulating  existing  ap¬ 
plications  on  the  screen.  The  application 
itself,  however,  in  combination  with  an 
X  toolkit,  actually  specifies  the  bulk  of 
the  window  interface  and  defines  the 
application’s  “look  and  feel.”  X  con¬ 
tains  mechanisms  for  implementing 
many  interface  styles  and,  unlike  some 
interfaces  (such  as  the  Macintosh),  does 
not  mandate  a  single  style.  Because  X  is 
supported  by  virtually  every  major  work¬ 
station  vendor  and  more  than  24  or¬ 
ganizations,  any  application  residing  on 
a  multi-vendor  network  and  adhering 
to  the  de  facto  X  standard  for  window¬ 
ing  on  high-performance  bit-mapped 
workstations  can  be  accessed  by  all 
X-based  workstations.  X  defines  an  open- 
systems  architecture  — one  that  is  inde¬ 
pendent  of  devices,  networks  and  op¬ 
erating  systems  — that  accommodates  a 
range  of  workstations.  X  servers  have 
been  implemented  on  workstations  and 
PCs  from  Digital  Equipment  Corp., 
Apollo  Computer,  Sun  Microsystems, 
and  Apple  Computer,  as  well  as  MS- 
DOS  and  OS/2-based  PCs. 


Network  Transparency 

The  X  Window  system,  written  in  C, 
provides  a  network  transparent  client/ 
server  architecture  that  spares  you  from 
coding  communications  services  be¬ 
tween  connected  clients  and  servers. 
Clients  establish  connections  with  any 
number  of  servers.  These  servers  han¬ 
dle  graphics  and  windowing  functions 
(called  X  server  processes)  and  receive 
requests  from  clients  in  the  form  of  Xlib 
graphics  library  calls.  Fast  asynchronous 
communication  between  clients  and  serv¬ 
ers  is  performed  by  the  X  Network  Pro¬ 
tocol. 

X  applications  and  toolkits  usually 
interface  to  the  Xlib  subroutine  library 
on  the  host.  Xlib  in  turn  converts  the 
parameters  passed  to  the  procedural 
interface  into  the  X  network  protocol 
format,  and  translates  messages  from 
the  server  into  return  values  for  the 
application.  Xlib  also  provides  a  set  of 
utility  routines  needed  by  most  appli¬ 
cations. 

In  addition  to  Xlib,  applications  can 
interface  to  a  variety  of  programming 
libraries  as  needed.  These  include  the  X 
Toolkit  (used  to  build  graphical-user 
interfaces),  industry-standard  libraries 
(such  as  GKS  and  PHIGS)  that  can  be 
layered  on  top  of  Xlib,  and  extension 
libraries  that  provide  programming  in¬ 
terfaces  to  X  server  extensions  such  as 
3-D  graphics,  Display  PostScript,  and 
imaging. 

Common  X  Applications 

X  applications  allow  you  in  effect,  to 
reach  out  across  a  network  via  a  con¬ 
sistent  and  intuitive  graphical-user  in- 
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(continued  from  page  42) 
terface  to  access  remote  applications 
and  high-performance  resources  any¬ 
where  on  the  network.  This  network 
transparency  lets  you  intermix  operat¬ 
ing  systems  in  workgroups  and  access 
applications  regardless  of  the  system 
those  applications  run  on.  For  example, 
you  can  display  in  separate  windows 
on  a  PC  applications  running  on  a  VAX/ 
VMS  system,  a  Unix  workstation  from 
Digital,  Sun  Microsystems,  Hewlett- 
Packard,  and  IBM  computers.  Through 
X,  you  can  access  multiple  applications 
and  display  and  control  them  within 
hierarchical-style  windows  on  this  work¬ 
station.  Applications  can  be  running 
either  on  the  workstation  or  on  remote 
hosts.  The  X  Window  system’s  network 
transparency  makes  remote  applications 
appear  as  if  they  were  running  on  your 
workstation. 

Although  an  X  application  can  be 
accessed  by  any  bit-mapped  graphics 
workstation  on  the  network,  the  pro¬ 
gram  actually  executes  on  the  whatever 
available  computer  is  best  suited  to  proc¬ 
ess  the  program.  For  example,  a  PC  that 
lacks  the  perfonnance  and  memory  to 
run  a  weather  prediction  program  can 
access  a  Cray  supercomputer  running 
the  program  while  you  interact  with  the 
application  through  a  window  on  the 
PC.  Again,  X  masks  the  differences  in 
operating  systems. 

Applications  can  be  designed  with 
mouse-driven  front  ends  that  allow  you 
to  scan  and  navigate  through  multiple 
databases  scattered  throughout  a  net¬ 
work.  A  stockbroker,  for  instance,  can 
review  and  compare  multiple  documents 
presented  on  his  screen  at  the  same 
time,  each  containing  stock  information 
from  various  news  wires.  The  broker 
can  “cut  and  paste”  information  of  the 
same  data  formats  from  these  windows 
into  another  window,  and  electronically 
mail  the  contents  of  the  window  imme¬ 
diately  to  a  client  with  whom  he  is 
talking  on  the  phone.  The  client,  after 
reviewing  the  information  from  a  desk¬ 
top  terminal,  can  place  an  order  to  pur¬ 
chase  stock  while  the  broker  fills  in  an 
order  form  in  another  window  and 
sends  it  to  the  client  for  confirmation. 
The  stock  information  can  be  coming 
from  news  wires  running  on  one  sys¬ 
tem  that  knows  nothing  about  the  mail 
system,  and  nothing  about  the  order 
form  application  and  its  host. 

Software  Portability 

In  addition  to  providing  an  architecture 
for  distributed  applications,  X  also  sim¬ 
plifies  the  porting  of  software.  This 
should  be  music  to  your  ears  if  you 
traditionally  have  had  to  customize  an 
application  to  match  each  hardware  and 


software  environment  that  you  want 
your  application  to  run  on.  Through  X, 
one  common  application  interface 
reaches  all  platforms  because  X  is  inde¬ 
pendent  of  machine  architecture,  oper¬ 
ating  system,  and  resolution  and  dis¬ 
play  characteristics.  Application  pro¬ 
grams  written  to  support  X  can  often 
run  on  another  vendor’s  system  simply 
through  recompilation. 

The  portability  of  X  has  been  amply 
demonstrated  by  the  X  Testing  Consor¬ 
tium,  a  group  of  vendors  jointly  devel¬ 
oping  tests  to  help  firms  validate  their  X 
implementations.  To  date,  the  test  soft¬ 
ware  runs  on  all  the  computer  architec¬ 
tures  of  contributing  companies  with 
virtually  no  changes,  Developers  have 
had  prerelease  test  software  (containing 
more  than  200  programs)  up  and  run¬ 
ning  in  one  day. 

Because  X  is  device  independent,  you 
do  not  need  to  rewrite,  recompile,  or 
relink  an  application  for  each  new  hard¬ 
ware  display.  Applications  can  be  writ¬ 
ten  to  be  independent  of  monochrome 
and  color  displays  or  displays  with  vary¬ 
ing  resolution  and  other  characteristics. 
Furthermore,  every  graphics  function 
defined  by  the  system  will  work  on 
virtually  every  supported  display.  If  graph¬ 
ics  functions  were  not  made  to  work  on 
all  displays,  “inquire”  operations  (like 
the  GKS-graphics-standard  inquire) 
could  be  used  to  determine  the  set  of 
implemented  functions  for  a  particular 
display  at  run-time.  (However,  using 
GKS  inquire  operations  would  require 
run-time  analysis  for  every  application, 
adding  overhead  and  producing  incon¬ 
sistent  user  interfaces.) 

X  Extensions 

Vendors  implementing  their  own  ver¬ 
sions  of  X  can  extend  the  system  over 
time.  The  most  recent  version  of  X, 
Version  11,  provides  hooks  to  extend  X 
to  support  functions  such  as  the  Dis¬ 
play  PostScript  imaging  model,  PEX  3- 
D  graphics  (see  accompanying  box), 
and  standard  compound-document  in¬ 
terchanges.  XI 1  also  adds  a  graphics 
state  for  improved  performance  and  de¬ 
fines  precise  semantics  for  output  rou¬ 
tines.  The  XI 1  tape,  publicly  available 
for  a  nominal  fee  from  MIT,  includes  a 
sample  X  server,  the  Xlib  library  of  X 
routines,  the  X  Toolkit,  several  window 
managers,  and  other  contributed  soft¬ 
ware. 

Unlike  other  windowing  systems,  X 
has  a  basic  philosophy  of  providing 
only  low-level  mechanisms  and  defers 
policy  decisions  to  developers.  X  will 
create  a  window,  but  the  application 
must  tell  it  whether  the  window  should 
have  a  particular  border  or  color.  X 
gives  low-level  “raw”  functionality  in 


order  to  provide  a  simple,  clean  system 
on  which  to  build.  If  policy  decisions 
were  made  at  a  low  level,  the  system 
would  not  grow  so  easily  or  allow  for 
future  advances  in  user-interface  tech¬ 
nology. 

X  User  Interface  Toolkits 

As  previously  stated,  X  provides  the 
mechanisms  to  move,  resize,  and  ma¬ 
nipulate  windows  but  does  not  dictate 
the  actual  appearance  of  the  windows. 
These  are  defined  by  various  develop¬ 
ers.  One  such  toolkit  is  the  public- 
domain  Xtk  toolkit  included  with  the 
MIT  distribution  tape.  Another  is  Digi¬ 
tal’s  DECwindows  X  User  Interface 
(XUI),  which  is  a  collection  of  user- 
interface  components  called  “widgets,” 
which  are  analogous  to  objects.  These 
widgets  include  scroll  bars,  pop-up 
menus,  window  borders,  and  dialog 
boxes.  Digital’s  widget  library  is  built 
on  top  of  the  lower-level  “intrinsics” 
found  in  the  X  Toolkit.  Intrinsics  are  the 
basic  set  of  rules  governing  widgets: 
how  the  widgets  are  created  and  de¬ 
stroyed,  how  they  receive  input  events, 
how  they  are  stored  in  a  resource  file  to 
be  initiated  at  runtime,  and  other  char¬ 
acteristics.  You  can  build  interfaces  on 
their  applications  that  maintain  a  high 
degree  of  portability  and  consistency 
with  the  X  standard  using  Digital’s  XUI. 

To  build  graphical-user  interfaces,  you 
design  any  number  of  custom  widgets 
from  the  X  Toolkit,  or  use  sample  wid¬ 
gets  from  the  X  Toolkit  as  well  as  wid¬ 
gets  provided  or  sold  separately  by  ven¬ 
dors.  Because  all  widgets  sit  on  top  of 
the  same  foundation  (the  intrinsics),  an 
application  and  its  widgets  can  be 
ported  from  one  X-based  computer  to 
another.  Each  computer  provides  a  port¬ 
able  foundation,  yet  each  application  is 
customized  and  differentiated  by  its  own 
“look  and  feel.”  Consistent  graphical- 
user  interfaces  enable  applications  to 
have  similar  looks  and  feels,  function 
similarly,  and  operate  intuitively 
through  mouse-driven  graphical  icons 
and  pull-down  menus.  This  simplifies 
the  learning  process  for  users. 

From  the  three-level  stack  of  pro¬ 
gramming  interfaces  — widgets,  intrin¬ 
sics,  and  Xlib  — an  application  calls  on 
any  one  interface,  or  any  combination 
of  interfaces  as  required  by  the  pro¬ 
gram.  If  you  are  developing  a  spread¬ 
sheet,  for  instance,  your  program  might 
call  on  intrinsics  to  customize  a  widget 
that  displays  cells  in  a  spreadsheet,  and 
access  Xlib  routines  to  draw  graphics 
on  the  screen.  Although  it  is  possible 
for  applications  to  directly  access  the 
server  via  the  X  protocol,  you  should 
use  the  higher-level  Xlib  graphics  rou¬ 
tines  to  manage  communication. 
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The  X  protocol  defines  data  struc¬ 
tures  used  to  transmit  requests  between 
clients  and  servers.  X  transmission  is 
asynchronous.  This  enables  requests  to 
be  sent  without  waiting  for  the  com¬ 
pletion  of  previous  requests.  Pipelining 
techniques  in  both  the  server  and  Xlib 
speed  the  processing  of  requests.  Any 
requests  depending  on  the  completion 
of  other  requests  are  blocked,  pending 
execution  of  those  other  requests.  Er- 


PEX3-D 
Graphics  for  X 

While  the  PEX  project  is  supported  by  a 
number  of  companies  and  organiza¬ 
tions  — including  DEC,  Tektronic,  Hew¬ 
lett-Packard,  Apollo,  Sun  Microsystems, 
and  the  Open  Systems  Foundation  — 
the  actual  implementation  work  will  be 
done  by  Sun  under  the  direction  of 
Robert  Scheifler,  director  of  the  X  Con¬ 
sortium.  Sun  will  develop  a  public  im¬ 
plementation  of  PEX  and  provide  the 
full  network  and  graphics  code  neces¬ 
sary  to  generate  3-D  graphics  on  an  X 
display. 

Scheifler,  who  was  the  principal  ar¬ 
chitect  of  X,  says  “PEX  adds  a  signifi¬ 
cant  new  functionality  to  X.”  He  went 
on  to  tell  DDJ  that  the  PEX  project  is 
especially  significant,  and  personally  grati¬ 
fying,  because  “it  is  another  indication 
of  how  well  the  industry  can  pull  to¬ 
gether  when  the  right  technology  is 
recognized.”  Scheifler  added  that  “in¬ 
terest  in  PHIGS  throughout  the  world 
has  been  heating  up  recently,  espe¬ 
cially  because  it  is  about  to  become  an 
official  ISO  standard.  It  is  the  right  thing 
at  the  right  time.” 

The  preliminary  release  of  the  soft¬ 
ware  will  be  in  mid-1989,  with  public 
release  (including  documentation)  sched¬ 
uled  for  late  1990.  The  PEX  implemen¬ 
tation  will  become  part  of  the  MIT  X 
Consortium  software  release  and  will 
be  available  at  distribution  cost  with  no 
licensing  restrictions. 

On  a  related  topic  Scheifler  indicated 
that  similar  projects  may  be  announced 
by  the  X  Consortium  sometime  in  the 
future,  particularly  projects  taigeted  at 
object-oriented  programming.  “The  con¬ 
sensus  is  that  object-oriented  program¬ 
ming  is  fundamental  to  user-interface 
building,”  he  said.  “We  are  looking  into 
application  development  environments 
and  the  next  generation  of  toolkits  of 
which  object-oriented  languages  are  a 
key  ingredient.” 

— eds. 


rors  are  also  generated  asynchronously, 
and  clients  must  be  prepared  to  receive 
error  messages  at  aibitrary  times. 

In  general,  the  X  protocol  also  de¬ 
scribes  connections  between  clients  and 
servers,  windows  (which  allow  interac¬ 
tion  between  you  and  the  application), 
events  (which  notify  the  application  of 
mouse  and  keyboard  actions  and  pro¬ 
vide  a  way  to  control  communication 
between  multiple  applications),  and 
graphics  routines  (which  allow  an  ap¬ 
plication  to  draw  information  on  a  dis¬ 
play).  These  are  described  later. 

Connections 

Because  X  is  network  and  operating 
system  independent,  applications  can 
run  on  any  machine  in  the  network. 
The  X  protocol  defines  data  structures 
used  to  transmit  requests  between  cli¬ 
ents  and  servers.  Applications  do  not 
generate  protocol  requests  themselves. 
Instead,  applications  call  Xlib  and  other 
layered  libraries.  X  uses  asynchronous 
stream-based  interprocess  communica¬ 
tion  instead  of  the  traditional  procedure 
call  or  kernel-call  interface.  This  asyn¬ 
chronous  communication  improves  net¬ 
work  speed  by  enabling  requests  to  be 
sent  without  needing  to  wait  for  the 
completion  of  previous  requests. 
Nearly  any  form  of  reliable  data  trans¬ 
port  may  be  used.  Current  implanta¬ 
tions  include  TCP/IP  and  DECnet. 

Pipelining  techniques  in  the  server 
and  Xlib  help  accelerate  processing  of 
requests.  Some  X  requests,  however, 
have  return  values  (state  queries,  for 
example)  that  depend  on  the  comple¬ 
tion  of  previous  requests.  The  X  proto¬ 
col  will  block  any  further  requests  until 
the  server  has  generated  a  reply  and 
sent  it  back  to  the  client.  Errors  are 
generated  asynchronously  so  clients 
must  be  prepared  to  receive  error  re¬ 
plies  at  arbitrary  times  after  the  offend¬ 
ing  requests. 

A  connection  (that  is,  the  communi¬ 
cation  path  between  the  server  and  cli¬ 
ent  program)  can  exist  between  proc¬ 
esses  on  the  same  machine  or  on  dif¬ 
ferent  machines.  A  client  program  usu¬ 
ally  has  one  connection  to  a  server  over 
which  requests  and  events  are  sent. 
When  processes  are  on  the  same  ma¬ 
chine,  the  X  protocol  is  often  sent  using 
shared  memory  or  other  local  transport 
facilities  of  the  system,  rather  than  TCP 
or  DECnet. 

To  interact  with  you,  a  client  must 
first  open  a  connection  with  an  X  Server 
using  a  common  transport  mechanism. 
(DECwindows,  for  example,  uses 
DECnet/OSI  or  TCP/IP).  The  client 
passes  version  and  authorization  pro¬ 
tocol  information  in  a  packet  to  the 
server  along  with  a  code  that  indicates 


the  byte  order  used  by  the  client.  If  the 
byte  order  differs  from  the  server’s  ma¬ 
chine  architecture,  the  server  will  use 
the  byte  order  code  to  swap  the  bytes 
of  incoming  requests.  A  swapping 
takes  place,  for  example,  between  a 
server  running  on  a  Macintosh  and  a 
client  application  running  on  a  VAX 
processor. 

If  a  request  to  open  a  connection  is 
successful,  a  reply  is  sent  back  to  the 
client.  This  reply  contains  information 
about  the  server  and  the  associated  dis¬ 
play  hardware  including  display  reso¬ 
lution,  physical  dimensions,  color-han¬ 
dling  abilities,  and  a  vendor  identifica¬ 
tion  string. 

Windows 

Once  a  connection  is  made,  you  can 
interact  with  multiple  applications  that 
are  displayed  within  windows  employ¬ 
ing  a  window  manager,  which  is  simply 
another  client  program,  that  helps  you 
manipulate  windows  on  the  screen. 
From  the  programmer’s  perspective,  win¬ 
dows  are  hierarchical  and  can  be  cre¬ 
ated  inside  other  windows  to  any  depth 
necessary  for  an  application. 

Each  screen  has  a  root  window  that 
displays  a  background  color  or  pattern 
and  serves  as  the  root  of  the  window 
tree  for  that  display.  Windows  can  be 
displayed  fully  on  die  screen,  partially, 
or  completely  hidden.  To  display  a  win¬ 
dow,  the  client  sends  the  server  a  Map- 
Window  request.  Graphics  output  to  a 
window  is  clipped  to  the  boundaries  of 
the  window.  A  window,  therefore,  be¬ 
comes  a  virtual  graphics  terminal  for  an 
application,  allowing  multiple  applica¬ 
tions  to  share  a  screen  and  not  over¬ 
write  another  application’s  output. 

Each  window  has  a  height  and  width 
and  Z  position  that  indicates  its  position 
within  a  stack  of  other  windows.  In 
addition,  windows  carry  other  attrib¬ 
utes  that  identify  their  location  on  the 
screen,  their  mapped  state,  and  their 
relationship  to  parent  and  sibling  win¬ 
dows.  The  border  pixel  attribute  is  used 
to  draw  a  border  around  a  window. 
Through  a  background  pixel  and 
pixmap  attribute,  an  application  can  spec¬ 
ify  either  a  single  pixel  value  or  a  com¬ 
plete  pixmap  (a  rectangular  anay  of 
pixels  in  main  memory)  as  the  window 
background.  Through  this  attribute,  a 
server  can  redraw  a  window’s  back¬ 
ground  color  itself  without  sending  a 
request  to  an  application. 


50 
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(continued  from  page  50) 

An  application  that  creates  a  window 
can  specify  bit  and  window  “gravity”  to 
the  server  to  indicate  which  pixels 
should  be  retained  when  a  window  is 
resized,  or  how  children  windows 
should  be  positioned  when  the  parent 
window  is  resized.  For  example,  a  text 
application  might  specify  “NorthWest- 
Gravity”  to  indicate  that  the  upper-left 
information  should  be  preserved  when 
the  window  is  reduced  to  size. 

Many  Xlib  routines  are  used  primar¬ 
ily  by  a  window  manager  or  toolkit 
rather  than  by  applications.  Typical  rou¬ 
tines  include  changing  the  parent  of  a 
window,  grabbing  the  pointing  device 
or  keyboard,  altering  event  dispatching 
and  processing,  changing  the  keyboard 
encoding,  determining  the  resident 
color  maps,  and  modifying  the  list  of 
hosts  that  have  access  to  the  server. 

All  pixels  in  X  have  uninterpreted 
color  values,  although  the  application 
can  allocate  and  define  a  color  map  to 
gain  control  of  the  mapping  between 
pixel  values  and  colors  displayed  on 
screen.  X  encourages  sharing  of  color 
maps  between  applications.  Pixel  val¬ 
ues  can  be  allocated  as  read  only,  and 
shared  in  a  color  map  (optionally  by 
name),  or  as  read/write  and  exclusive 
in  a  color  map.  Applications  that  use 
low-level  X  routines  are  expected  to 
query  the  hardware  capabilities  at  con¬ 
nection  set-up  time  and  adjust  their  us¬ 
age  accordingly. 

X  graphics  routines  can  be  directed 
to  a  window  or  to  an  arbitrary  pixmap. 
Pixmaps  and  windows  are  referred  to 
as  “drawables”  and  all  X  drawing  op¬ 
erations  are  passed  drawable  as  a  pa¬ 
rameter.  Instead  of  passing  all  parame¬ 
ters  that  describe  a  drawing  operation 
to  the  server  on  each  graphics  request, 
the  server  keeps  state  in  a  data  structure 
called  a  graphics  context  (GC).  The  GC 
is  passed  as  an  argument  to  each  graph¬ 
ics  call  and  includes  information  about 
the  foreground  and  background  colors, 
line  widths  and  styles,  polygon  fill  rule, 
stipple  patterns,  text  fonts,  and  a  client- 
supplied  clipping  region.  Applications 
can  create  more  than  one  GC  to  alter¬ 
nate  quickly  between  states  on  sequen¬ 
tial  output  calls. 

Events 

X  applications  are  event  driven  with 
events  being  sent  to  an  application  from 
a  number  of  sources,  including  the  X 
server  and  X  toolkit,  as  well  as  other 
applications.  Events  are  generated  by 
the  X  server  when  you  type  on  the 
keyboard  or  move  the  mouse  or  other 
pointing  device.  Some  event  types  are 
generated  as  side  effects  of  client  re¬ 
quests.  Each  event  includes  a  time 
stamp,  a  bitmask  indicating  the  up/ 


down  state  of  all  modifier  keys  and 
mouse  buttons  just  before  the  event, 
the  window  the  mouse  is  in,  and  details 
about  the  change  the  event  describes. 

An  application  is  notified  when  the 
pointing  device  or  cursor  enters  or 
leaves  a  window.  A  single  window  is 
globally  designated  as  the  “input  fo¬ 
cus.”  This  window  receives  all  keyboard 
input  specified  by  the  event  until  the 
input  focus  is  set  to  a  different  window. 
An  event  is  generated  when  a  window 
gains  or  loses  input  focus.  In  X,  applica- 

From  the 
programmer’s 
perspective,  windows 
are  hierarchical  and 
can  be  created  inside 
other  windows  to  any 
depth  necessary  for  an 
application 


tions  are  expected  to  regenerate,  on 
request,  any  information  displayed  in 
windows.  When  a  window  changes  size 
or  becomes  visible,  the  server  may  need 
to  tell  the  application  which  parts  of  the 
window  to  redraw.  This  triggers  an 
event.  Some  X  implementations  may 
invoke  backing  store  and  save  orders  to 
reduce  repainting,  but  applications  must 
still  be  able  to  repaint  a  window  on 
request. 

Graphics  Performance 

Graphics  operations  in  X  are  designed 
to  be  simple  and  fast.  They  are  rela¬ 
tively  low  level  compared  to  PostScript, 
PHIGS,  or  GKS,  but  are  still  well-suited 
to  create  high-performance,  visually  so¬ 
phisticated  applications.  Tasks  requir¬ 
ing  a  higher-level,  graphics-oriented  in¬ 
terface  can  use  layered  graphics  librar¬ 
ies  or  intermix  calls  to  the  layered  li¬ 
braries  with  basic  X  graphics  functions. 

The  Xlib  contains  about  300  routines 
that  either  map  directly  to  X  Protocol 
requests  or  provide  utility  functions  to 
the  client.  Xlib  routines  allow  a  client 


application  to  create,  destroy,  manipu¬ 
late,  and  configure  windows.  There  are 
also  routines  for  lines,  polygons,  arcs, 
text,  block  pixel  transfers,  stipple  and 
tile  filling,  and  color-map  manipulation. 
Routines  such  as  PolyLine  and  PolyRec- 
tangle  perform  multiple  operations 
based  on  a  list  of  points. 

Operating  on  an  array  of  objects  is 
more  efficient  than  making  multiple 
graphics  calls  due  to  the  X  requests 
overhead.  The  protocol  to  draw  one  or 
more  rectangles  is  PolyRectangle, 
which  takes  a  drawable  (a  pixmap  or 
window),  a  graphics  context,  and  a  list 
of  rectangles  as  parameters. 

For  example,  X  shows  that  graphics 
performance  over  an  Ethernet  network 
is  excellent,  and  ususally  functions  at 
the  speed  of  the  display  device  (often 
higher  when  the  application  is  running 
remotely  rather  than  locally!).  Although 
the  semantics  of  server  operations  are 
tightly  connected  to  the  X  protocol,  a 
fair  degree  of  freedom  exists  in  the 
actual  design  and  implementation  of 
the  server  itself.  The  quality  of  the 
server  implementation  is  one  way  ven¬ 
dors  can  add  value  to  their  competing  X 
offerings. 

The  MIT  sample  server  (on  the  MIT 
distribution  tape)  consists  of  a  section 
of  highly  portable  code,  and  a  section 
of  device-dependent  code.  The  sample 
server  was  designed  to  make  device¬ 
independent  code  as  large  as  possible, 
thus  simplifying  implementation  at  the 
expense  of  performance.  Reimple¬ 
menting  the  server  to  be  entirely  device 
dependent  may  provide  the  best  per¬ 
formance,  but  would  require  a  major 
effort  to  support  each  new  workstation 
product. 

Conclusion 

Over  time,  extensions  to  support  3-D 
graphics,  imaging,  and  even  live  video 
will  be  added  to  both  the  X  architecture 
and  to  development  tools  with  the  goal 
of  providing  added  functionality,  but 
not  at  the  expense  of  compatibility.  With 
this  in  mind,  software  developers 
should  consider  the  following  criteria 
when  evaluating  a  specific  implemen¬ 
tation  of  X:  quality  and  robustness  of 
code,  performance  between  clients  run¬ 
ning  X  applications  and  remote  work¬ 
stations  running  X  servers,  the  vendor’s 
X  development  environment,  and  the 
level  of  difficulty  required  to  integrate  a 
software  developer’s  own  extensions 
and  software  into  the  X  environment. 
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Extended  Directory 
Searches  Using  C++ 

Here’s  what  you  can  do  when  DOS’s  DIR 
just  won’t  do  the  job 


John  M.  Dlugosz 


Any  decent  program  that  deals 
with  files  must  have  some  way 
to  parse  and  construct  file 
names.  Consider,  for  example, 
a  simple  non-interactive  pro¬ 
gram  that  accepts  input  and  output  file 
names  on  the  command  line.  A  simple 
program  would  accept  a  pair  of  names 
and  blindly  use  them.  A  more  robust 
program  would  check  for  validity, 
check  for  the  extension  and  supply  a 
default  if  needed,  and  generate  the  out¬ 
put  name  from  the  input  name  if  the 
second  parameter  is  missing. 

In  this  article  I’m  presenting  a  pro¬ 
gram  called  MATCH. CPP  that  lets  you 
use  C++  to  extract  drive,  path, 
basename,  and  extension  components 
from  an  MS-DOS  filename,  and  create  a 
filename  from  component  parts.  This 
program  makes  use  of  a  C++  class 
called  dir_scanner  that  is  much  more 
convenient  than  similar  methods  tradi¬ 
tionally  used  in  C.  MATCH. CPP,  when 
used  with  the  other  files  included  in  this 
article  (DIRSCAN.HPP,  DIRSCAN.CPP, 
and  SCANHELP.ASM)  and  with  your  stan¬ 
dard  library,  form  a  complete  program. 
The  latter  half  of  main(  )  shows  the  use 
of  a  dir_scanner,  as  well  as  a  sugges¬ 
tion  of  how  you  can  send  a  dir_data  to 
a  text  file. 

Dirpafh 

The  first  class,  called  “dirpath,”  is  de¬ 
fined  in  Listing  One  (DIRPATH. CPP), 
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page  99,  as  a  structure.  In  C++  a  struc¬ 
ture  ( struct )  is  a  class.  The  only  differ¬ 
ence  between  the  two  is  that  class  mem¬ 
bers  are  private  unless  stated  otherwise, 
while  struct  has  all  public  members. 
Notice  that  the  members  of  the  struc¬ 
ture  are  character  arrays  to  hold  the 
various  pieces  of  a  file  name.  You  can 
read  their  contents  or  change  them,  just 
like  any  ordinary  structure.  The  magic 
is  in  the  member  functions:  The  « 
operator  parses  a  string  into  the  struc¬ 
ture,  and  »  concatenates  all  the  pieces 
together  into  a  full  name. 

In  addition  to  the  two  operators,  a 
pair  of  constructors  is  provided  as  well. 
If  a  dirpath  is  initialized  with  a  single 
string,  it  is  parsed  into  the  structure  (it 
simply  calls  operator«  inline).  Alter¬ 
natively,  you  can  initialize  a  dirpath  with 
four  strings  and  they  are  copied  into  the 
four  fields.  Listing  Two,  page  99,  illus¬ 
trates  the  usage  of  the  dirpath. 

Now  let’s  take  a  close  look  at  the  guts 
of  dirpath.  Both  constructors  are  inline 
functions,  and  are  stated  in  the  header. 
Listing  Three  (DIRPATH. CPP),  page  99, 
shows  the  implementation  of  «  and 
».  Defining  the  «  operator  is  just  like 
defining  any  other  function  whose  name 
is  opera tor«.  The  operator  is  used  be¬ 
tween  two  items,  but  only  one  parame¬ 
ter  is  given.  The  left  argument  is  this, 
which  is  automatically  present  in  any 
member  function.  The  this  parameter  is 
always  a  pointer  to  the  class  of  which 
the  function  is  a  member.  You  rarely 
need  to  refer  to  the  name  this,  because 
the  members  may  be  referred  to  di¬ 
rectly — that  is,  you  could  say  this- 
> drive,  but  drive  alone  will  do. 


Dirpath  is  straightforward.  It  checks 
to  see  if  a  drive  letter  is  present,  and 
places  it  into  drive  if  found.  Next,  the 
string  is  scanned  for  the  last  slash  (sub¬ 
directory  separator)  and  dot.  The 
pieces  found  go  their  separate  ways, 
via  the  copy( )  function.  Dirpath  copies 
a  string  but  will  not  overflow  the  desti¬ 
nation. 

The  operator  »  reconstructs  a  name 
from  the  components.  It  is  rather  sim¬ 
ple  but  is  loaded  with  failsafes.  Even 
though  the  parse  will  have  put  a  colon 
after  the  drive  name,  a  backslash  after 
the  path,  and  begun  the  extension  with 
a  dot,  you  might  have  replaced  some  of 
the  fields  and  not  been  as  neat.  The 
operator  »  will  generate  a  valid  file¬ 
name. 

Dirscan 

Programs  that  deal  with  filenames  will 
probably  want  to  deal  with  generic  file¬ 
names.  In  DOS,  the  wildcard  characters 
*  (asterisk)  and  ?  (question  mark)  are 
used  to  abbreviate  a  name  or  to  select  a 
group  of  similar  names.  The  use  of  *  is 
very  weak,  however;  for  example,  the  * 
must  be  the  last  character  in  the  base  or 
extension.  It  would  be  much  nicer  if 
you  could  have  as  many  *s  as  you  like 
and  put  them  anywhere  in  the  name. 

This  leads  us  to  a  class  called 
dir_scanner.  In  C  you  would  probably 
use  functions  like  dirfirst( )  and  dir- 
next(  )  or  perhaps  opendirj )  and  read- 
dir( ).  These  functions  are  difficult  and 
clumsy  to  use  and  have  subtle  differ¬ 
ences  among  compilers.  In  C++  an  iter¬ 
ator  class  makes  things  much  easier. 
Take  a  look  at  Listing  Four  (DIR- 
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SCAN.HPP),  page  99. 

The  structure  for  DOS’s  directory  en¬ 
tries  is  described  by  the  class  dir_data. 
Notice  that  this  is  a  class  and  not  a 
struct.  The  reserved  area  is  private. 
Other  than  that,  dir_data  behaves  like 
an  ordinary  struct  in  that  the  members 
may  be  freely  used,  like  in  C.  Because 
the  class  has  no  member  functions  and 
no  friends,  the  reserved  area  cannot  be 
accessed  anywhere  in  the  program.  In 
C  you  could  say  that  this  area  is  hands- 
off;  in  C++  you  can  mean  it. 

When  you  want  a  directory  listing, 
you  declare  a  variable  of  type  dir_scan- 
ner.  The  constructor  takes  the  wild  file 
specification  and  the  mode.  If  the  sec¬ 
ond  parameter  is  missing,  zero  is  taken 
as  a  default. 

The  dir_scanner  class  is  an  iterator. 
Iterators  come  in  different  forms,  re¬ 
flecting  the  way  they  are  intended  to  be 
used.  The  simplest  case  is  a  single 
function  that  returns  the  next  value 
each  time  it  is  called,  and  some  senti¬ 
nel  value  or  error  code  when  no  ele¬ 
ments  remain.  (There  might  be  an  infi¬ 
nite  number  of  elements,  in  which  case 
you  do  not  have  to  worry  about  the  end 
of  the  series.)  A  two-step  iterator,  on 
the  other  hand,  has  two  steps.  One 
function  advances  to  the  next  element 
and  reports  on  the  success  or  failure  of 
the  operation.  Another  function  fetches 
the  current  element.  A  two-step  iterator 
is  popular  for  two  reasons:  You  might 
refer  to  the  current  element  several 
times  before  advancing,  and  it  may  be 
easier  to  structure  the  loop  if  you  know 
in  advance  that  an  element  is  present. 
(Listing  Eight  [MATCH.CCP],  page  100, 
demonstrates  the  use  of  class 
dir_scanner.) 

Both  parts  of  the  iterator  are  not  or¬ 
dinary  functions.  The  fetch  function  is 
operator ( ).  This  is  a  popular  choice  for 
iterators  or  other  classes  where  one  func¬ 
tion  is  dominant.  Overloading  the  func¬ 
tion  call  operator  may  look  strange  at 
first  but  is  quite  handy.  This  function 
may  be  defined  with  any  number  of 
arguments  (zero,  in  this  case).  If  argu¬ 
ments  are  present,  they  are  placed  be¬ 
tween  the  ( )  just  like  in  a  function  call. 
Defining  the  function,  the  name  opera¬ 
tor  )  is  given  followed  by  an  argument 
list.  This  function  returns  an  item  of 
type  dir_data  by  reference.  Other  lan¬ 
guages  (like  Pascal)  let  you  pass  by 
reference,  but  C++  lets  you  return  by 
reference  as  well.  Here,  the  function  is 
inline,  and  return  by  reference  is  used 
for  efficiency. 

The  function  to  advance  and  test  is 
not  an  ordinary  function  either.  This  is 
an  overloading  of  the  int  operator.  Cast¬ 
ing  a  dir_scanner  to  an  int  causes  this 
function  to  be  called.  This  result  is 
handy  because  you  can  use  a  dir_scan¬ 
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ner'm  a  while  loop.  If  dis  a  dir_scanner ; 
while(d)  (...  causes  d  to  be  implicitly 
casted  to  an  int.  The  construct  (int)d  is 
familiar  to  C  programmers,  and  int(d)  is 
equivalent  and  preferred  in  C++.  Both 
would  cause  operator  int  to  be  called. 

If  the  use  of  the  operators  is  confus¬ 
ing,  you  might  want  to  imagine  them  as 
functions  bool  nextf  )  and  void  fetch(  ). 

Implementation 

The  dir_scanner  must  somehow  find 
out  which  files  are  on  the  disk.  The 


Class  dirpath  lets  you 
extract  drive,  path, 
basename,  and 
extension  components 
from  a  MS-DOS 
filename,  and  create  a 
filename  from 
component  parts 


class  dir_scanner  is  portable  and  easy 
to  use.  It  is  in  the  implementation  of  the 
class  that  you  can  use  all  the  tricks  and 
environment-specific  knowledge.  The 
implementation  in  Listing  Five 
(DIRSCAN.CPP),  page  99,  is  for  MS- 
DOS. 

Most  C  libraries  include  functions  to 
read  the  directory,  they  are,  however, 
all  different.  Most  also  have  a  way  to 
call  DOS  functions,  but,  again,  differ¬ 
ences  in  implementations  make  calling 
DOS  functions  more  trouble  than  it’s 
worth.  The  functions  are  quite  simple, 
so  it  is  easier  to  call  them  in  assembly 
language  than  it  is  to  figure  out  how  to 
do  it  in  C++  for  any  given  implementa¬ 
tion. 

In  DOS,  the  “find  first”  and  “find 
next”  call  uses  a  data  area  that  must  be 
preserved.  Because  it  is  allowed  to  have 
more  then  one  dir_scanner  going  at 
the  same  time,  each  instance  must  have 
its  own  data  — another  reason  not  to 
use  the  functions  that  came  with  the 
library.  In  the  case  of  Zortech,  for  ex¬ 
ample,  the  supplied  functions  use  an 
internal  static  buffer.  Listing  Six 
(SCANHELP.ASM),  page  100,  contains 
the  two  assembly  language  functions. 

The  constructor  for  dir_scanner  calls 


dirscan  JindfirstJ  J,  and  the  advance  and 
test  function  calls  dirscan_Jindnext(). 
In  Listing  Five,  this  accounts  for  about 
ten  lines.  There  is  much  more  here  then 
necessary  for  simply  providing  a  shell 
for  DOS’s  directory  searching  functions. 

Wildcard  Names 

Under  DOS’s  filename  search  (int  21 
functions  4e  and  40,  the  file  name  may 
contain  wildcards.  A  ?  matches  any  char¬ 
acter,  and  an  *  finishes  out  the  name. 
The  *  must  be  the  last  character  in  the 
base  or  extension.  I  decided  to  imple¬ 
ment  a  much  more  robust  system.  First, 
asterisks  should  be  allowed  anywhere 
in  the  name,  and  multiple  *s  should  be 
allowed.  So  names  like  A*ED.*,  *88.*F*, 
and  *I*.*I*  are  legal.  (The  last  example 
will  find  any  name  that  contains  an  /.) 

The  key  is  to  ask  DOS  for  all  files, 
and  sort  out  the  matches  within  the 
dir_scanner.  A  function  that  matches 
enhanced  wildcard  specifications  is  the 
cornerstone.  The  way  to  allow  multiple 
*s  is  to  use  recursion.  The  algorithm 
(Listing  Seven,  version  a,  page  100)  is 
“the  strings  match  if  the  first  characters 
match  and  the  rest  of  the  strings 
match.”  There  is  no  need  to  worry 
about  breaking  the  name  into  base  and 
extension  because  the  pattern  will  con¬ 
tain  a  dot,  it  must  match  the  dot  in  the 
filename,  and  the  filename  will  always 
contain  a  dot. 

The  function  matchname( )  looks  at 
the  first  character  of  the  pattern.  If  the 
first  character  is  an  *,  it  tries  to  match  the 
rest  of  the  pattern  with  the  name.  If  it 
does  not  match,  it  skips  a  character  in 
the  name  and  tries  again.  It  continues 
this  way  until  a  match  is  found  (the  * 
can  stand  for  any  number  of  characters) 
or  until  the  end  of  the  name  is  reached. 
This  recursive  handling  of  *  is  funda¬ 
mental  to  the  enhanced  pattern  match¬ 
ing.  If  the  first  character  of  the  pattern  is 
a  ?,  the  first  character  of  the  name  can 
be  anything  except  a  nul. 

The  technique  in  Listing  Seven(a) 
would  be  great  in  Prolog,  but  it  has 
something  to  be  desired  in  C.  The  over¬ 
head  of  recursion  is  high.  On  the  other 
hand,  the  name  is  only  13  characters 
long,  so  maybe  it  is  OK.  But  some  obvi¬ 
ous  improvements  can  be  made  with 
regards  to  consecutive  ordinary  charac¬ 
ters.  With  the  exception  of  *,  all  the 
recursion  is  at  the  end  of  execution. 
Whenever  the  recursive  call  is  being 
returned,  you  can  replace  the  call  with 
a  jump  (rather  than  pushing  parame¬ 
ters,  assign  the  new  values  to  them, 
then  jump  back  to  the  beginning  of  the 
function). 

Listing  Seven(b)  shows  the  result  of 
applying  tail-end  recursion  elimination 
to  Listing  Seven(a).  The  meaning  is  the 
same,  but  it  has  much  less  recursion.  It 
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(continued  from  page  56) 
is  a  rather  ugly  sight  in  C++,  though. 
The  last  step  (Listing  Seven[cD  is  to  get 
rid  of  all  the  GOTOs.  Sometimes  the 
literal  translation  of  the  algorithm  can 
be  transformed  in  good  code.  This  was 
much  simpler  than  trying  to  come  up 
with  a  good  function  from  scratch. 

Now  the  dir_scanner  could  use 
matchname( )  to  match  filenames,  but 
it  does  more  than  this.  The  match- 
name( )  function  is  instead  called  from 


A  number  of  C++ 
classes  are  much  more 
convenient  than 
similar  methods 
traditionally  used  in  C 


multi_match(  ).  The  dir_scanner  accepts 
search  strings  with  multiple  wild 
names.  Separating  the  names  by  +  finds 
matches  to  the  first  or  the  second.  Sepa¬ 
rating  with  a  semicolon  will  find  all  the 
names  that  match  the  first  and  do  not 
match  the  second.  Furthermore,  the  mul¬ 
tiple  name  specification  can  be  pre¬ 
ceded  by  drive  and  path  information. 
The  MATCH. CPP  program  (Listing 
Eight,  page  100)  lets  you  try  out  these 
searches. 

The  constructor  dir_scanner.:scan- 
ner( )  separates  the  path  from  the 
search  string  by  breaking  it  at  the  last 
slash.  The  name  is  replaced  by  *.*  and 
sent  to  the  DOS  primitive.  It  returns 
all  files  in  the  directory  and  multi_ 
match( )  decides  which  ones  to  keep. 
The  search  specification  is  then  sent  to 
buildlists(  ). 


The  multiple  names  are  separated  by 
buildlists( )  into  two  lists.  The  goodlist 
includes  all  the  regular  names,  and  the 
badlist  contains  the  names  that  were 
preceded  with  semicolons.  It  scans  the 
string  to  count  the  names,  and  allocates 
storage  for  the  two  lists.  The  lists  point 
into  the  single  buffer,  and  nulls  placed 
into  the  buffer  (overwriting  the  +  or  ;) 
break  it  into  individual  strings.  This 
works  better  than  allocating  a  bunch  of 
small  strings  from  the  heap. 

The  function  multi_match( 9  decides 
if  a  name  matches  the  search  request. 
The  name  is  accepted  if  it  matches  any 
of  the  names  in  the  goodlist  and  does 
not  match  any  of  the  names  in  the  bad¬ 
list.  Each  of  the  tests  uses  the 
matchnameO  function  with  its  en¬ 
hanced  wildcards. 

But  matchname  only  works  if  the 
names  are  normalized.  Specifically,  both 
name  and  pattern  must  contain  a  dot.  If 
the  filename  does  not  contain  a  dot,  it  is 
appended  on  the  end.  The  search  string 
is  processed  more  so  it  accepts  more 
flexible  input. 

Now  you  have  several  more  tools  for 
your  C++  programs.  These  should  let 
you  write  more  powerful  programs  and 
write  programs  easier.  After  all,  that 
was  the  idea  when  you  moved  up  to 
C++. 

Availability 

All  the  source  code  for  this  issue  is 
available  on  a  single  disk.  To  order, 
send  $14.95  (Calif,  residents  add  sales 
tax)  to  Dr.  Dobb’s  Journal,  501  Galves¬ 
ton  Dr.,  Redwood  City,  CA  94063,  or 
call  800-356-2002  (inside  Calif.)  or  800- 
533-4372  (outside  Calif.).  Please  specify 
the  issue  number  and  format  (MS-DOS, 
Macintosh,  Kaypro). 


DDJ 

(listings  begin  on  page  99.) 

Vote  for  your  favorite  feature/article. 
Circle  Reader  Service  No.  7. 


Command 

Use 

*.EXE+*.COM 

Examines  all  EXE  and  all  COM  files 

T*T.*;TEST.BAT 

Searches  for  all  files  that  begin  and  end  in  T 
except  for  TEST.BAT 

*.*;COMMAND.COM 

Searches  for  all  files  except  COMMAND.COM 

D:\FOO\*.EXE+*.COM;*K*.* 

Finds  all  EXE  and  COM  files  in  D:\FOO\  that  do 
not  contain  the  letter  K  in  their  names 
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Table  1:  Sample  uses  of  the  Match  program. 
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Coping  With 
Complex  Programs 

Quality  control  using 
software  metrics 


Karanjit  S.  Siyan 


At  one  time  or  another,  almost 
every  software  developer  has 
had  to  face  the  beast  of  soft¬ 
ware  complexity.  One  of  the 
most  common  methods  of  meas¬ 
uring  software  complexity  is  counting 
the  number  of  lines  of  code  in  the  pro¬ 
gram.  This  is  an  example  of  a  “software 
metric.”  Generally  speaking,  a  software 
metric  measures  the  characteristics  of  a 
program  in  quantitative  terms.  Expe¬ 
rience  reveals  that  the  number  of  lines 
of  code  is  a  simplistic  and  unrealistic 
way  of  measuring  the  complexity  of  a 
program.  A  better  software  metric  is 
needed  — one  that  can  measure  the  “con¬ 
tent”  of  a  program.  Another  metric  is 
one  that  can  provide  an  estimate  of  the 
difficulty  in  understanding  the  program, 
writing  a  similar  program,  and  estimating 
how  many  errors  you  can  expect  to  see 
in  this  program. 

Freedom  Technologies  has  been  us¬ 
ing  several  software  metrics  for  manag¬ 
ing  development  efforts.  Many  of  these 
measures  are  based  on  intuitive  under¬ 
standing  of  how  complex  a  program  is. 
For  example,  a  program  that  exhibits 
excessive  decision  making  can  be  some¬ 
what  difficult  to  follow.  A  program  that 
makes  use  of  many  global  variables  can 
be  extremely  difficult  to  modify  and 
maintain  because  of  the  tight  degree  of 
unwanted  coupling  and  “side-effects,” 
and  the  dreaded  “ripple-effect”  where 
one  innocuous  change  can  result  in  the 
program  not  working. 

Size  and  Flow  Metrics 

Different  approaches  have  been  sug- 
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gested  to  measure  those  characteristics 
that  make  up  complex  programs. 
Broadly  speaking,  these  approaches  can 
be  categorized  into  two  groups:  size 
metrics  and  control-flow  metrics. 

Size  metrics  are  based  on  the  prem¬ 
ise  that  the  “larger”  the  program,  the 
more  complex  it  is.  The  size  of  a  pro¬ 
gram  is  not  necessarily  based  on  the 
number  of  lines  of  code.  A  more  mean¬ 
ingful  measure  of  this  size  would  be 
based  on  the  number  of  procedures, 
number  of  operators,  number  of  vari¬ 
ables,  and  so  forth. 

Control-flow  metrics  attempt  to  meas¬ 
ure  complexity  based  on  the  decisions  — 
statements  such  as  if,  for,  while,  case, 
etc.  — used  in  a  program,  and  the  levels 
of  nesting.  Some  measures  use  graph 
theory  by  viewing  the  abstract  flow  of 
program  control  as  a  directed  graph. 

The  two  most  popular  families  of 
metrics  that  fall  into  this  category  are 
the  Software  Science  (size  metric)  and 
the  Cyclomatic  Complexity  (control- 
flow  metric).  At  least  one  tool  from  SET 
Labs  Inc.  (Portland,  Ore.),  called  PC- 
METRIC,  computes  these  metrics  and 
runs  on  MS-DOS-based  systems  for 
languages  such  as  C,  Modula-2,  and 
Pascal. 

Assessing  Validity  of  a  Metric 

To  determine  if  measurement  of  a  cer¬ 
tain  characteristic  of  a  program  con¬ 
tributes  to  the  complexity  of  a  program, 
the  following  two  facts  must  be  estab¬ 
lished:  1.  Does  the  characteristic  com¬ 
puted  by  the  metric  actually  contribute 
to  complexity?  and  2.  Does  the  compu¬ 
tation  of  a  metric  reflect  how  much 
complexity  is  being  contributed? 

The  answers  to  these  questions  are 
based  on  a  statistical  analysis  of  the 
programs.  Some  aspect  of  the  program¬ 


ming  process  — development  time,  num¬ 
ber  of  errors  during  development,  and 
so  forth — is  compared  with  the  com¬ 
puted  metric.  As  an  example,  if,  for  a 
large  sample  of  programs,  the  time  to 
develop  a  program  increases  with  a 
larger  value  of  the  computed  metric, 
then  the  computed  metric  indicates  more 
complex  programs.  The  degree  to 
which  a  computed  metric  is  related  to 
the  programming  process  is  called  cor¬ 
relation.  A  well-developed  theory  ex¬ 
ists  in  statistics  for  measuring  the  corre¬ 
lation  between  variables.  The  better  the 
correlation  between  the  software  met¬ 
ric  (product  metric)  and  an  attribute  of 
the  programming  process  (process  met¬ 
ric),  the  greater  the  effectiveness  of  the 
software  metric. 

Another  approach  is  to  partition  the 
set  of  sample  programs  into  groups 
based  on  some  characteristic  (such  as 
the  number  of  decisions).  The  average 
number  of  errors  can  be  measured  in 
these  groups.  If  the  number  of  errors  is 
found  to  increase  for  groups  that  have  a 
larger  number  of  decisions,  the  soft¬ 
ware  metric  of  “number  of  decisions” 
does  contribute  to  program  complexity. 

Software  Science 

The  Software  Science  metrics  were  de¬ 
veloped  in  the  early  1970s  by  Maurice 
Halstead  of  Purdue  University.  Halstead 
observed  that  all  programs  are  made  up 
of  operators  and  operands.  By  coming 
up  with  a  measure  based  on  operators 
and  operands,  you  can  get  a  better  idea 
of  how  complex  the  program  really  is. 
The  following  four  parameters  can  be 
counted  for  any  program: 

nl  =  number  of  unique  operators 

N1  =  total  number  of  operators 

n2  =  number  of  unique  operands 
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N2  =  total  number  of  operands 

Halstead’s  entire  theoretical  frame¬ 
work  is  based  on  these  four  parame¬ 
ters.  For  example,  the  “length”  of  a 
program  (N)  is  defined  as  the  total  num¬ 
ber  of  operators  and  operands  used. 
Also,  the  vocabulary  (n)  of  a  program  is 
the  total  number  of  unique  operators 
and  operands. 

N  (Length)  =  N1  +  N2 

an  (Vocabulary)  =  nl  +  n2 

Software  Science  Counting  Rules 

What  is  an  “operator,”  and  what  is  an 
“operand”  in  a  program?  How  do  you 
compute  the  values  of  nl,  Nl,  n2,  N2 
for  a  program?  The  best  way  to  illustrate 
this  is  through  an  example.  Figure  1  is  a 
program  fragment  and  Figure  2  shows 
a  tally  of  the  operators  and  operands. 
Notice  that  paired  items  such  as  (1,  (  ) 
are  counted  as  operators.  In  some  situ¬ 
ations,  there  may  be  differences  in  opin¬ 
ion  as  to  what  is  an  operator  and  what 
is  an  operand.  The  statement  goto  Label 
can  be  legitimately  viewed  as  consisting 
of  the  operator  goto  and  the  operand 
Label.  You  could  also  treat  the  whole 
statement  as  an  operator.  Several  re¬ 
searchers  have  shown  that  minor  dif¬ 
ferences  in  counting  rules  have  little 
impact  on  the  effectiveness  of  Software 
Science  as  long  as  the  rules  are  applied 
consistently. 

The  Length  Equation  and  Purity  Ratio 

Several  interesting  relations  are  derived 
based  on  the  count  of  operators  and 
operands.  The  first  one  is  the  predicted 
“length”  of  a  program.  Remember,  that 


Figure  1:  Program  fragment  1 
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rules  applied  to  theprrogram  in  Figure  1 


the  actual  “length”  (N)  is  defined  as  Nl 
+  N2  or  simply  the  count  of  all  the 
operators  and  operands  in  a  program. 
Halstead  theorized  that  a  well-written 
program  should  have  a  predicted 
length,  NA  (pronounced  N-hat)  as 
shown  here: 

NA  =  [nl  x  log2(nl)]  +  [n2  x  log2(n2)] 

This  equation  is  called  the  length  equa¬ 
tion.  If  the  actual  length,  N,  is  different 
from  the  predicted  length,  the  program 
could  have  any  of  the  following  six 
classes  of  impurities:  canceling  of  opera¬ 
tors,  ambiguous  operands,  synonymous 
operands,  common  subexpressions,  un¬ 
necessary  replacements,  or  unfactored 
expressions. 

Based  on  N  and  NA,  the  purity  ratio 
is  defined  as  NA/N.  A  purity  ratio  of  1 
would  imply  few  impurities.  C  programs 
usually  have  a  purity  ratio  greater  than 
1.  This  means  that  the  actual  length,  N, 
is  less  than  the  predicted  length,  NA. 
This  could  be  because  logic  can  be 
expressed  very  succinctly  in  C. 

What  is  interesting  about  the  length 
equation  is  that  the  first  term  [nl  x  log2 
(nl)]  can  be  treated  as  a  constant.  The 
rationale  for  this  is  that  the  number  of 
unique  operators  in  a  programming  lan¬ 
guage  is  finite,  and  most  programmers 
have  a  small  subset  of  operators  they 
regularly  use.  The  second  term  [n2  x  log2 
(n2)]  is  the  one  that  has  a  greater  impact 
on  the  predicted  length.  If  you  can  com¬ 
pute  an  accurate  estimate  of  how  many 
operands  will  be  used  in  a  program, 
you  can  predict  how  large  a  program  is 
going  to  be. 

Program  Volume  and  Estimated  Errors 

Halstead  also  theorized  that  if  a  pro¬ 
gram  has  “n”  (n  ”  nl  +  n2),  unique 
operators  and  operands,  the  number  of 
bits  used  to  represent  or  encode  these 
as  a  binary  number  would  be  log2(n). 
Since  there  are  “N”  (N  =  Nl  +  N2)  such 
usages  of  these  operators  and  oper¬ 
ands,  the  total  number  of  bits  used  to 
represent  the  program  would  be 
N  x  log2(n).  This  expression  is  termed 
the  volume  (V)  of  a  program. 

V  (Volume)  =  N  x  log2(n) 

Consider  two  programs,  each  with  200 
uses  of  operators  and  operands  (N  = 
200).  The  first  program  uses  16  unique 
operators  and  operands,  while  the  sec¬ 
ond  uses  64  unique  operators  and  op¬ 
erands.  The  volume  for  the  first  pro¬ 
gram  is  200  x  log2  (16)  =  800,  while  the 
volume  for  the  second  program  is 
200  x  log2(64)  =  1200.  The  volume  is  a 
better  estimate  of  program  size  than  a 
simple  count  of  operators  and  oper¬ 


ands  (N),  since  the  value  is  larger  with  a 
larger  number  of  unique  operators  and 
operands. 

Another  way  of  looking  at  the  pro¬ 
gram  volume  is  that  N  total  operators 
and  operands  will  require  log2(n)  men¬ 
tal  lookups  using  the  best  search  algo¬ 
rithm.  The  total  number  of  mental  look¬ 
ups  is  N  x  log2(n),  same  as  the  program 
volume.  On  the  average,  people  tend 
to  make  mistakes  every  E0  mental  com¬ 
parisons.  Work  done  by  psychologists 
shows  that  the  value  of  E0  is  about 
3,000  to  3,200.  The  number  of  estimated 
errors,  BA  is 

BA  =  V  /  E0  =  [N  X  log2(n)]  /  E0 

A  programmer  with  superior  ability 
will  have  a  larger  value  of  EO,  and  some¬ 
one  with  an  inferior  ability  will  have  a 
lower  value  of  E0.  The  programmer 
with  superior  ability  will  make  fewer 
errors.  If  the  actual  number  of  errors  is 
recorded  for  a  number  of  programs,  a 
project  manager  can  determine  the  E0 
values  for  the  team  members. 

Program  Effort  and  Estimated  Time 

You  can  expect  that  the  effort  required 
to  develop  a  program  will  be  greater  for 
a  program  with  larger  program  volume. 
A  parameter  called  “effort”  (or  E)  is  de¬ 
fined  as 

E  =  V/L 

where  V  is  the  volume  of  a  program 
and  L  is  an  estimate  of  the  level  of 
abstraction  in  a  program.  The  level  of 
abstraction  is  defined  as 

L  =  V*  /  V 

where  V  is  the  volume  measure  (as 
previously  defined)  and  the  new  V*  is 
the  volume  a  program  would  have  if  it 
could  be  represented  as  a  procedure 
call  within  the  language.  An  example 
will  clarify  this. 

Consider  a  program  to  print  a  report 
from  a  data  file.  A  procedure  call  to  this 
program  could  be  written  as 

PrintReport(DataF  ile) 

The  volume  (V*)  of  this  statement 
would  be  3  x  log2(3)  =  4.74.  The  vol¬ 
ume  (V*)  is  called  the  potential  volume. 
An  estimate  for  L  (LA)  is  often  used 
instead  of  the  equation  L  =  V*/V,  which 
is  based  on  the  number  of  operators 
and  operands.  This  estimate  is  given  by 
the  following  empirical  formula: 

LA  =  2/nl  x  n2/N2 

A  good  thing  about  this  estimate  for 
the  level  of  abstraction  is  that  it  is  easily 
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computed  by  a  simple  analysis  without 
knowing  too  much  about  the  internal 
structure  of  a  program. 

What  do  all  the  given  equations  mean5 
Halstead  suggested  that  the  effort  (E) 
represents  the  number  of  “mental  discrimi¬ 
nations”  a  programmer  would  have  to 
perform  in  order  to  write  the  program. 
A  psychologist,  Stroud,  found  that  hu¬ 
mans  are  capable  of  making  five  to 
twenty  mental  discriminations  per  sec¬ 
ond.  This  number  is  called  the  Stroud 
Number,  S.  You  now  have  the  follow¬ 
ing  equation: 

Estimated  time  to  develop  a  program, 

TA  =  E  /  S 

A  common  value  of  “S”  for  program¬ 
mers  is  18. 

Cydomatic  Complexity 

Tom  McCabe  suggested  that  the  cyclo- 
matic  number  of  a  program’s  control 
flow  graph  would  be  an  accurate  esti¬ 
mate  of  how  complex  a  program’s  flow 
of  control  is.  The  control  flow  graph  is 
similar  to  a  flowchart.  Each  node  in  this 
graph  consists  of  a  basic  block.  A  basic 
block  is  a  segment  of  code  that  has  a 
single  entry  point  and  a  single  exit 
point,  and  there  is  no  transfer  of  control 
within  the  basic  block.  Figure  3  is  a 
fragment  of  code  and  Figure  4  is  its 
control  graph.  The  cydomatic  number 
of  a  flow  graph  is  defined  as 

Cydomatic  Number  of  graph  “G,” 

V(G)  =  e  -  n  +  2 

where  n  is  the  number  of  nodes  in  the 
graph,  and  e  is  the  number  of  edges  or 
lines  connecting  each  node.  In  Figure 
4,  n  is  4,  and  e  is  4,  giving  a  cydomatic 
number  of  2. 

A  simpler  way  of  calculating  the  cyclo- 
matic  number  is  to  add  1  to  the  sum  of 
all  the  decision-making  statements  ( if, 
while,  for,  and  so  on).  In  the  example  in 
Figure  3,  there  is  only  one  ^statement, 
and  adding  1  gives  2. 

Extended  Cydomatic  Complexity  is 
defined  as  including  not  just  decision¬ 
making  statements,  but  also  decision¬ 
making  predicates.  Examples  of  dedsion- 
making  predicates  are  the  logical  expres¬ 
sions  in  an  if  statement  that  are  con- 


Inrtf ); 

r  Node  A  7 

if  (ReportOption) 

GenReport(RoportOption) ; 

r  Node  B7 

else 

i 

ReportError(ReportOption) ; 

r  Node  C  7 

Finish( ); 

r  Node  07 

Figure  3-'  Program  fragment  2 


Dr.  Dobb’s Journal,  March  1989 
174 


nected  by  logical  and,  or.  A  shortcut 
method  of  calculating  the  Extended  Cy- 
clomatic  Complexity  is 

Sum  of  the  number  of  decisions, 

ANDs,  ORs  +  1. 

The  following  if  statement  has  an  Ex¬ 
tended  Cydomatic  Complexity  of  5  be¬ 
cause  there  is  1  if  statement,  2  AND 
(&&),  1  OR  (I  I). 

if  (  _dbStatus  ==  0  &&  IsValidf  )  I  I 

_dbStatus  >  10  &&  IsExprf  )) 

1 

return  0; 

1 

Uses  of  Software  Metrics 

The  useful  thing  about  all  these  metrics 
is  that  they  actually  help  develop  better 
code.  Here  are  some  examples. 

After  writing  a  piece  of  code,  a  soft¬ 
ware  developer  can  compute  the  soft¬ 
ware  metrics  (using  a  tool,  of  course,) 
to  provide  feedback  about  potentially 
troublesome  aspects  of  a  program.  The 
software  metrics  can  be  compared 
against  a  norm  that  is  user-definable. 
Remedial  action,  if  necessary,  can  then 
be  taken.  This  could  be  a  different  ap¬ 
proach  or  algorithm  that  will  produce 
less  complex  code,  breaking  the  pro¬ 
gram  down  to  simpler  modules.  There 
are  applications  where  even  the  best 
solution  may  be  very  complex.  In  this 
case,  software  metrics  can  identify  the 
modules  that  need  better  and  extra  docu¬ 
mentation. 

A  small  percentage  of  modules  in  a 
software  system  has  an  inordinate 
amount  of  errors.  Software  metrics  can 
identify  the  more  error-prone  modules, 
and  greater  resources  can  be  allocated 
to  testing  them.  During  the  maintenance 
phase,  software  metrics  can  be  used  as 
one  of  the  tools  to  measure  the  amount 


n  =  4 
e  =  4 

V  (G)  =  e  -  n  +  2 
=4-4+2 
=  2 

Figure  4-  Control  flow  graph  for  pro¬ 
gram  fragment  2 


of  effort  and  time  required  to  make 
changes  to  existing  modules. 

Software  metrics  should  be  viewed 
as  one  of  the  tools  (among  many)  to 
help  manage  the  process  of  developing 
software.  However,  this  tool  is  not  a 
replacement  for  common  sense. 

In  some  programs,  the  metrics  may 
not  accurately  capture  complexity  and 
flag  the  programs  as  being  overly  com¬ 
plex  or  less  complex  than  they  actually 
are.  Common  sense  will  aid  in  deter¬ 
mining  if  the  metric  results  are  reason¬ 
able.  Applying  the  metrics  to  one  or 
two  individual  programs  may  be  disap¬ 
pointing.  Software  metrics  work  best 
when  applied  to  a  large  group  of  pro¬ 
grams. 

Validity  of  Software  Science 
and  Cydomatic  Complexity 

While  much  of  the  literature  in  software 
metrics  reports  studies  supporting  the 
software  metrics  described  in  this  arti¬ 
cle,  several  researchers  have  expressed 
doubts  about  its  validity.  Shen,  Conte, 
and  Dunsmore  voice  most  of  the  objec¬ 
tions  raised  by  researchers.  Much  of  the 
criticism  is  directed  at  certain  assump¬ 
tions  made  by  Halstead  and  the  meth¬ 
odology  used  by  those  studies  that  sup¬ 
port  Software  Science.  These  objections 
drive  home  the  point  that  software  met¬ 
rics  are  effective  in  a  statistical  sense 
when  applied  consistently  to  a  large 
number  of  programs. 
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The  Portability 
Dream 


Now  you  can  develop  an  application  that  will  run 
under  Windows  and  the  Mac 


Margaret  Johnson 


Some  might  say  that  the  creation 
of  portable  code  between  win¬ 
dowing  environments,  such  as 
Microsoft  Windows  and  the  Macin¬ 
tosh  User  Interface,  is  an  impos¬ 
sible  dream.  After  all,  the  architectures 
within  which  these  environments  oper¬ 
ate  are  widely  disparate.  The  Extensible 
Virtual  Toolkit  (XVT),  however,  is  a 
package  from  the  Advanced  Program¬ 
ming  Institute  that  promises  to  virtual¬ 
ize  the  code  between  these  diverse  en¬ 
vironments  to  the  point  where  the  proc¬ 
ess  of  porting  code  between  them 
should  be  just  a  matter  of  source  trans¬ 
fer,  creation  of  resources  (such  as 
menus,  dialog  boxes,  and  strings),  and 
recompilation.  XVT  is  a  collection  of  C 
functions  that  attempts  to  abstract  the 
major  features  of  a  windowing  envi¬ 
ronment’s  application  programming  in¬ 
terface  (API).  XVT  is  a  virtual  toolkit, 
because  it  acts  as  the  interface  to  the 
native  toolkit.  A  user  of  this  package 
stays  away  from  direct  calls  to  either  the 
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Windows  Software  Development 
Toolkit  (SDK)  or  the  Macintosh  User 
Interface  Toolbox. 

XVT  is  currently  available  only  for 
the  Mac  and  Windows.  Advanced  Pro¬ 
gramming  Institute  is  working  on  a  ver¬ 
sion  of  XVT  for  the  OS/2  Presentation 
Manager,  and  also  promises  a  future 
version  for  X-Windows.  Compilers  sup¬ 
ported  by  XVT  include  MS-C  (Version 
5.x)  for  Windows,  and  both  Lightspeed 
C  (Version  3-0)  and  MPW  C  (Version 
2.0.2)  on  the  Mac. 

Those  who  stand  to  gain  the  most 
from  XVT  are  developers  who  are  fa¬ 
miliar  with  C  but  are  new  to  graphical 
user  interface  (GUI)  programming,  de¬ 
velopers  who  don’t  want  to  invest  the 
time  and  energy  necessary  in  order  to 
feel  comfortable  developing  programs 
for  either  (or  both)  Windows  or  the 
Mac,  and  developers  who  don’t  require 
features  that  are  unique  to  a  particular 
API.  The  package  contains  enough  built- 
in  code  to  also  benefit  the  developer 
who  creates  applications  specific  to  the 
Mac  or  to  Windows.  XVT’s  built-in  rou¬ 
tines  include  functions  for  file  handling, 
printing,  managing  the  clipboard,  font 
handling,  dialog  management,  and  a 
facility  for  easily  including  a  help  sys¬ 


tem  within  an  application. 

Portability  Between  Environments 

To  reach  the  dream  of  100  percent  port¬ 
ability,  the  process  of  virtualization  can¬ 
not  compromise  too  many  features  of 
an  environment.  The  application  de¬ 
termines  which  features  can  be  com¬ 
promised.  Although  the  Mac  and  Win¬ 
dows  are  conceptually  similar,  there  are 
enough  differences  in  their  implemen¬ 
tations  to  make  abstractions  to  some  of 
their  features  difficult,  if  not  impossible. 
Both  APIs  have  terrific  features  that  are 
specific  to  their  respective  environments. 
For  example,  Windows  allows  child  win¬ 
dows,  the  sending  and  posting  of  in¬ 
tratask  messages,  dynamic  link  librar¬ 
ies,  the  dynamic  data  exchange  for  in¬ 
tertask  messages,  mapping  modes 
(MM_LOENGLISH,  MM_ANISOTROPIC, 
and  so  forth),  window  property  lists, 
subclassing,  and  atom  tables.  Because 
Windows  provides  a  nonpreemptive 
form  of  multitasking,  its  API  contains 
functions  that  allow  an  application  to 
yield  to  other  Windows  applications  dur¬ 
ing  processing. 

On  the  other  hand,  the  Mac  supports 
more  choices  for  menu  styles,  such  as 
hierarchical,  tear-off,  and  popup 


70 


Dr.  Dobb’s  Journal,  March  1989 

175 


menus.  It  also  allows  nonrectangular 
and  shadowed  windows.  In  addition, 
the  Mac’s  API  contains  functions  that 
support  internationalization  and  file  han¬ 
dling  dialogs;  Windows  does  not  in¬ 
clude  these  functions.  The  differences 
between  Windows  and  the  Mac  can  be 
interpreted  as  constraints  to  the  XVT 
API.  With  the  exception  of  the  standard 
file-open-and-save  dialogs,  the  special 
features  listed  above  for  Windows  and 
the  Mac  are  not  part  of  the  XVT  pack¬ 
age.  In  addition,  the  version  that  I  re¬ 
viewed  (1.2)  does  not  include  support 
for  bitbltting  (bit  block  transfers),  the 

XVT  is  a  virtual 
toolkit,  because  it  acts 
as  the  interface  to  the 
native  toolkit 


user  of  color,  internationalization,  RS- 
232  communications,  sound,  and  map¬ 
ping  modes. 

Handing  Over  Control 

When  I  began  reviewing  XVT,  I  noticed 
that  I  took  the  side  of  what  the  product 
lacks,  rather  than  what  it  has  to  offer. 
This  perspective  most  likely  results  from 
both  my  long  hours  spent  becoming 
familiar  with  the  Windows  SDK,  and 
my  current  interest  in  Mac  develop¬ 
ment.  It’s  the  perspective  of  a  devel¬ 
oper  who  is  asked  to  move  from  a 
low-level  language,  such  as  assembler, 
to  a  higher-level  language,  such  as  C: 
Some  control  must  be  taken  away.  This 
is  a  hard  thing  to  come  to  terms  with. 
Once  I  gave  XVT  a  chance,  however,  I 
was  surprised  at  how  many  of  the  more 
important  features  are  available. 

These  features  include  support  for 
dialog  boxes,  windows  (in  the  sense  of 
Microsoft’s  Multiple  Document  Interface, 
as  described  in  the  MS-Window’s  SDK 
Application  Style  Guide),  text,  file  han¬ 
dling,  printing,  drawing  primitives,  han¬ 
dling  the  clipboard,  and  15  of  what 
XVT’s  developers  believe  are  the  most 
popular  events  that  can  occur  to  a  win¬ 
dow.  The  dialog  boxes  can  contain  push 
buttons,  radio  buttons,  check  boxes, 
scroll  bars,  static  text,  edit  boxes,  and 
listbox  controls.  The  drawing  primitives 
allow  the  drawing  of  rectangles  (with 
or  without  rounded  comers),  ovals,  arcs, 
pie  pieces,  lines  (with  or  without  ar¬ 


rows),  and  polygons. 

XVT’s  15  Window-related  events  fall 
far  short  of  the  approximately  100  pos¬ 
sible  event  messages  that  are  available 
under  Windows.  Although  the  Mac  also 
has  15  events,  they’re  not  identical  (in 
meaning)  to  XVT’s  events.  XVT’s  events 
are  probably  sufficient,  however,  for 
the  90  percent  case.  They  include  mes¬ 
sages  for  mouse  down,  mouse  up, 
mouse  movement,  mouse  double  click, 
keyboard  input,  window  update,  win¬ 
dow  activation/deactivation,  window  de¬ 
struction,  vertical  scroll  bar  activity,  hori¬ 
zontal  scroll  bar  activity,  menu  com¬ 
mands,  close  window,  resize  window, 
selection  from  the  font  or  style  menu, 
and  a  request  to  quit  the  application. 

Taking  the  Plunge 

The  XVT  product  that  I  received  in¬ 
cluded  a  loose-leaf  binder  jampacked 
(almost  to  the  point  of  explosion!)  with 
pages  including  the  “XVT  Programmer’s 
Manual,”  a  question  and  answer  sheet 
covering  the  most  often  asked  ques¬ 
tions,  information  on  enhancements  and 
changes  since  version  1.1,  two  574- 
inch  360K  floppy  disks  for  the  PC,  two 
372-inch  800K  floppy  disks  for  the  Mac, 
and  a  registration  form.  The  program¬ 
mer’s  manual  is  divided  into  sections 
for  installation  and  usage,  a  user’s 
guide,  a  reference  to  each  function  (docu¬ 
mented  with  a  description,  example, 
and  list  of  associated  functions),  tech¬ 
nical  notes  (giving  insight  on  how  to 
implement  techniques  not  covered  else¬ 
where),  and  a  quick  reference. 

I  felt  the  documentation  did  a  good 
job  of  explaining  both  the  objective  of 
SVT  and  the  functions  that  are  imple¬ 
mented  to  reach  that  objective.  The  only 
major  complaint  is  a  lack  of  an  index  for 
each  section.  This  is  promised  for  a 
later  release. 

To  use  XVT  on  the  PC,  it’s  necessary 
to  first  install  the  Windows  operating 
environment  (2.x),  the  SDK  (2.x),  and 
Microsoft’s  C  compiler  (5.x).  On  the 
Mac  side,  I  used  Lightspeed  3.0.  Note 
that  all  of  this  software  assumes  the 
presence  of  a  hard  disk. 

Installation  of  XVT  on  the  PC  side  is 
easy.  First  create  the  five  subdirectories 
\XVT\ BIN,  \XVT\ EXAMPLES,  \XVT\ 
INCLUDE,  \XVT\LIB,  and  \XVT\ 
SOURCE  on  the  hard  disk.  Then  copy 
the  contents  of  the  subdirectories  on 
the  XVT  floppy  to  the  corresponding 
subdirectories  on  the  hard  disk.  The 
second  floppy  contains  a  program 
called  XVTDraw  that  highlights  the  us¬ 
age  of  XVT  in  a  Windows  draw  pack¬ 
age.  It  is  for  demonstration  purposes 
only. 

Once  XVT  is  installed,  life  is  easier  if 
the  lines  that  set  the  INCLUDE  and  LIB 


paths  in  AUTOEXEC.BAT  are  modified 
to  allow  the  XVT  paths.  For  example: 

SET  INCLUDE=\MSC\INCLUDE;\XVT 

\  INCLUDE 

SET  LIB= \  MSC\  LIB;  \  XVT\  LIB 

Note  that  all  this  discussion  about  paths 
assumes  \XVT  is  the  parent  directory.  If 
this  isn’t  the  case,  a  minor  annoyance  is 
encountered.  The  file  XVTRSRC.HRC  (lo¬ 
cated  in  the  XVT  INCLUDE  subdirec¬ 
tory)  and  the  ,rc  files  included  with  the 
examples,  hardcode  pathnames  that  as¬ 
sume  the  parent  directory  to  be  \XVT. 
This  minor  inconvenience  should  be 
handled  by  the  installation. 

The  Mac  version  of  XVT  contains  the 
BIN,  EXAMPLES,  INCLUDE,  and  LIB  fold¬ 
ers.  I  loaded  the  INCLUDE  and  LIB  fold¬ 
ers  into  the  Think  C  folder,  and  created 
a  new  folder  to  contain  the  BIN  and 
EXAMPLES  folders. 

XVT  includes  nine  examples  that 
show  off  the  package’s  abilities.  The 
best  way  to  sally  up  to  XVT  is  to  first 
read  the  technical  overview  and  then 
follow  the  examples.  These  examples 
cover  the  use  of  the  clipboard,  scroll¬ 
ing,  the  use  of  the  font  style  menu, 
tracking  with  the  mouse,  directory  ma¬ 
nipulation,  and  dialog  boxes.  All  ex¬ 
amples  are  well  thought  out  and  pro¬ 
vide  a  great  starting  point  for  applica¬ 
tions  development. 

Taking  Issue 

I  wish  XVT  handled  some  characteris¬ 
tics  on  the  PC  side  differently.  In  par¬ 
ticular,  the  XVT  functions  are  not 
in  a  dynamic  link  library  (DLL),  and 
thereby  zapping  more  of  my  valuable 
memory  resource  and  data  area  than 
necessary  (for  more  insight  into  DLL, 
see  “Dynamic  Link  Libraries  Under  Mi¬ 
crosoft  Windows,”  elsewhere  in  this 
issue).  Putting  the  XVT  functions  into  a 
DLL  would  offer  considerable  advan¬ 
tages.  The  code  would  be  shared  not 
only  between  instances  of  an  applica¬ 
tion,  but  also  between  applications. 
Also,  any  static  or  global  data  defined 
and  used  exclusively  by  the  library 
would  not  eat  into  an  application’s  pre¬ 
cious  local  data.  The  Advanced  Pro¬ 
gramming  Institute  plans  to  implement 
the  OS/2  library  as  a  DLL,  but  there  are 
no  plans  to  do  the  same  for  the  Win¬ 
dows  library. 

Another  problem  is  that  although  the 
XVT  functions  were  created  using  the 
medium  model,  the  code  segments  were 
not  separated.  This  approach  creates  a 
huge  code  segment  (around  60K)  that 
degrades  the  performance  of  Windows 
and,  consequently,  the  performance  of 
the  application.  If  the  application  is  of 
any  size,  the  performance  of  Window’s 
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memory  manager  is  really  improved  by  make  for  future  versions  of  XVT  is  that 
breaking  the  code  up  into  multiple  seg-  the  system  font  be  used  as  the  default, 
ments.  Luckily,  this  step  can  be  han¬ 
dled  by  creating  a  map  listing  and  add-  Hello  World! 

ing  the  code  segment  names  to  the  The  simplest  application  created  with 
module  definition  file.  An  example  is  XVT  must  contain  the  following: 
provided  in  the  Installation  and  Users 
Guide.  •  a  menu 

Note  that  windows  in  XVT  are  ere-  •  an  initial  window  data  structure 
ated  with  a  NULL  brush  for  the  back-  •  an  application  initialization  function 
ground.  This  means  that  an  application  named  appl_init( ) 
must  paint  the  client  rectangle  each  time  •  an  application  cleanup  function 
it  receives  an  update  event.  The  time  named  appl_cleanup( ) 
this  unnecessary  call  takes  to  paint  the  •  a  main  event  function  named  main_ 
client  rectangle  each  time  an  update  event( )  that  is  called  by  XVT  when 
event  occurs  is  quite  noticeable.  one  of  the  15  defined  events  occurs 

In  Windows,  once  the  application’s 

background  brush  is  set  to  a  non-null  Listings  One  through  Three,  illustrate 

brush,  the  application  need  not  worry  the  difference  between  XVT  code  (List- 

about  updating  the  background.  When  ing  One,  page  102),  Mac  (Listing  Two, 

XVT  is  used  on  a  Mac,  application  calls  page  102),  and  Windows  code  (Listing 

EraseRect( )  to  update  the  background.  Three,  page  104)  for  the  classic  “Hello 

In  both  of  these  cases,  XVT  should  take  World!”  example.  Figure  1  shows  the 

care  of  updating  the  background.  output  from  either  of  these  examples. 

The  size  of  the  application’s  main  Although  the  application  is  very  simple, 

window  is  predefined  as  the  full  I  think  it  gives  the  flavor  of  the  way  that 

screen.  This  makes  the  main  window  XVT  abstracts  the  features  of  the  PC  and 

look  maximized,  even  though  the  size  Mac  environments.  I  used  Lap-Link  (Mac) 

boxes  are  the  same  as  those  used  for  a  to  transfer  files  between  the  two  ma- 

normal  window.  If  the  programmer  is  chines.  XVThello.c  compiled  without  a 

not  allowed  to  enter  the  screen  coordi-  hitch  in  both  environments.  Once  I  set 

nates  for  the  main  window,  then  the  up  the  resource  and  library  files,  the 

size  of  the  main  window  should  default  programs  I  tested  ran  as  advertised, 

to  the  default  overlapped  window  size 
that  Windows  provides. 

One  final  suggestion  that  I  would 


Figure  1:  Output  from  either  the  Mac  or  Windows. 


Final  Note 

To  summarize,  whether  XVT  will  fill  a 
particular  need  is  clearly  up  to  the  ap¬ 
plication.  Some  important  features,  such 
as  the  dynamic  data  exchange  in  Win¬ 
dows  and  the  more  advanced  intertask 
communications  in  OS/2  Presentation 
Manager,  would  be  difficult  to  repro¬ 
duce  in  the  Mac  environment,  and  are 
thus  not  included  into  XVT.  Every  day, 
there  is  talk  about  packages  soon  to  be 
introduced  that  promise  improved  port¬ 
ability  between  GUI  implementations. 
For  instance,  Microsoft  and  Glocken¬ 
spiel  have  announced  a  product  called 
CommonView.  According  to  informa¬ 
tion  that  I  can  gather  at  this  time,  Com¬ 
monView  is  implemented  as  a  DLL  and 
provides  C+  +  classes  for  most  Win¬ 
dows  objects.  It  claims  a  high  percent¬ 
age  of  portability  between  Windows 
and  OS/2  PM.  The  developers  also  hope 
to  have  ports  for  X-Windows,  News, 
and  the  Mac  at  some  unknown  future 
date.  But  that’s  the  future,  and  XVT  is 
available  now.  I  am  impressed  with  both 
the  amount  of  effort  invested  in  this 
package  and  with  its  capabilities.  The 
folks  at  the  Advanced  Programming  In¬ 
stitute  have  shown  the  impossible 
dream  to  be  a  reality  for  a  significant 
number  of  features  found  in  a  window¬ 
ing  environment. 

DDJ 

(Listings  begin  on  page  102.) 

Vote  for  your  favorite  feature/article. 

Circle  Reader  Service  No.  10. 


72 


Dr.  Dobb’s  Journal,  March  1989 

177 


The  OSF 

Windowing  System 


The  OSF  user  interface  is  built  around  several 
graphical  user-interface  technologies 


Kee  Hinckley 


Two  months  after  its  formation  in 
1988,  the  Open  Software  Foun¬ 
dation  (OSF)  released  a  Request 
For  Technology  (RFT)  to  organi¬ 
zations  to  submit  their  X  Win¬ 
dow  System-based  user-interface  tech¬ 
nologies  for  inclusion  in  the  OSF’s  fu¬ 
ture  implementation  of  Unix.  After  re¬ 
viewing  the  39  systems  that  were  sub¬ 
mitted,  the  members  of  the  OSF  staff 
responsible  for  the  “user  environment 
component”  or  UEC  (that  is,  the  gra¬ 
phical  user  interface)  culled  the  list  to 
23  qualified  candidates.  The  UEC  staff 
then  divided  these  into  four  areas  of 
interest;  Window  Managers,  User  Inter¬ 
face  Toolkits,  User  Interface  Manage¬ 
ment  Systems,  and  Graphical  Desktops. 

Early  this  year,  the  OSF  announced  a 
hybrid  UEC  windowing  system  selected 
called  the  “OSF/Motif  user  interface  sys¬ 
tem”  built  around,  not  one,  but  several 
graphical  user  interface  technologies: 
Digital  Equipment  Corp.’s  (DEC)  toolkit 
to  provide  the  interface  toolkit,  Hewlett- 
Packard  to  provide  the  window  appear¬ 
ance,  and  Microsoft’s  Presentation  Man¬ 
ager  for  the  user  interface’s  behavior. 

The  Selection  Scope 

OSF  intentionally  worded  the  initial  RFT 
so  as  to  encourage  submissions  in  a 
variety  of  areas  that  otherwise  might 


Kee  is  a  software  engineer  currently  on 
loan  to  the  Open  Software  Foundation 
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not  have  been  recognized  at  the  outset 
of  the  process.  This  revealed  a  wide 
variety  of  submissions  exhibiting  diverse 
strengths.  Many  of  these  submissions 
were  of  potential  interest  for  inclusion 
in  the  core  offering,  but  were  not  yet 
appropriate  for  a  variety  of  reasons. 
Some  are  in  technology  areas  where 
the  market  has  not  yet  settled  on  a 
single  model  or  set  of  techniques.  Oth¬ 
ers,  depended  on  technologies  not  yet 
widely  available  to  some  OSF  mem¬ 
bers,  or  required  base  technologies  that 
as  yet  are  not  standardized.  Rather  than 
ignore  these  products  completely,  OSF 
created  a  model  to  facilitate  channeling 
them  in  directions  compatible  with  the 
OSF  base  offerings,  and  potentially  into 
the  base  offering  set  itself. 

At  the  center  of  this  model  is  the  UEC 
core  offering  made  up  of  a  style  guide, 
which  provides  a  description  of  the  be¬ 
havior  and  a  reference  appearance;  user 
interface  toolkit,  which  provides  a  stan¬ 
dard  graphical  user  interface  layer;  pres¬ 
entation  description  language,  which 
provides  quick  turn-around  and  easy 
modification  of  user  interfaces;  and  win¬ 
dow  manager,  which  gives  the  user  a 
standard  environment  for  manipulating 
application  windows. 

The  second  ring  of  the  technology 
model  is  the  OSF  catalog  program.  The 
catalog  program  encompasses  technolo¬ 
gies  that  use  or  are  integrally  compat¬ 
ible  with  the  core  offerings,  but  which 
OSF  is  not  ready  to  include  in  the  core. 
Submissions  currently  under  considera¬ 
tion  for  inclusion  in  the  catalog  pro¬ 


gram  include:  open  dialogue,  a  pres¬ 
entation  and  dialog  management  sys¬ 
tem  submitted  by  apollo  computer;  base/ 
open  user  interface  management  sys¬ 
tem,  a  dialog  management  system  sub¬ 
mitted  by  the  Swedish  telecom  group; 
and  generic  window  manager,  a  U1MS 
for  building  window  managers,  submit¬ 
ted  by  Groupe  Bull. 

The  final  ring  of  the  technology 
model  is  the  OSF  research  program. 
This  includes  areas  of  interest  in  which 
OSF  is  encouraging  investigation,  but 
which  are  not  necessarily  compatible 
with  the  core  offerings  and  may  not  be 
as  portable.  UEC  offerings  currently  un¬ 
der  consideration  for  this  program  in¬ 
clude  the  Andrew  Window  System,  sub¬ 
mitted  by  Camegie-Mellon  University. 

The  core  offering  is  currently  avail¬ 
able  to  OSF  members  in  snapshot  form 
(that  is,  prerelease  versions  in  source 
code  form).  The  first  version  of  the 
UEC,  available  in  the  summer  of  1989, 
will  be  portable  to  both  System  V  and 
BSD  Unix  systems.  The  initial  catalog 
and  research  technology  offerings  will 
be  available  in  a  similar  time  frame. 

The  OSF/Motif  toolkit  is  based  on  the 
X  Intrinsics,  a  toolkit  framework  pro¬ 
vided  with  MIT’s  X  Window  System 
(Version  11,  Release  3).  The  Intrinsics 
use  an  object-oriented  model  to  create 
a  class  hierarchy  of  graphical  objects 
known  as  “widgets.”  Widgets  have  an 
associated  set  of  “resources,”  some  of 
which  are  specific  to  a  particular  class 
of  widget,  others  inherited  from  super¬ 
classes.  Resource  values  are  specifiable 

Dr.  Dobb’s  Journal,  March  1989 


178 


both  by  the  application  program  (either 
directly  or  through  the  presentation  de¬ 
scription  language)  and  by  the  user 
(through  a  standard  set  of  files  that  are 
read  by  the  Intrinsics).  They  determine 
the  actual  appearance  and  behavior  of 
any  particular  instance  of  a  widget  and 
give  the  user  and  application  designer  a 
great  deal  of  latitude  for  customization. 
For  example,  a  PushButton  widget  has 
resources  to  set  the  top  and  bottom 
“shadow”  colors  that  give  it  a  3-D  ap¬ 
pearance.  Other  resources  set  the  color 
of  the  button,  the  color  of  the  text,  and 
a  list  of  callback  procedures  for  each  of 
a  wide  variety  of  events  (arm,  disarm, 
activate  .  .  .  ).  Most  applications  need 
not  set  more  than  a  few  resources;  the 
OSF/Motif  Toolkit  provides  reasonable 
defaults  for  the  rest,  on  both  color  and 
black  and  white  systems. 

One  of  the  strengths  of  the  OSF/ 
Motif  toolkit  is  the  extensibility  pro¬ 
vided  by  its  object-oriented  model.  It  is 
easy  for  the  application  designer  to  add 
new  widgets,  even  without  access  to 
the  OSF/Motif  source  code.  Thus,  ven¬ 
dors  and  third  parties  can  create  en¬ 
tirely  new  graphical  objects  that  are  spe¬ 
cific  to  their  applications,  or  they  can 
sub-class  from  an  existing  class  to  add 
functionality  to  a  particular  widget  (for 
example,  a  Text  widget  that  does  a 
specific  type  of  command  completion). 
This  extensibility  allows  the  toolkit  to 
grow  and  advance  in  the  future  as  new 
user  interface  techniques  are  developed. 

The  Style  Guide 

The  user  interface  portion  of  a  program 
can  be  broken  into  two  parts  — its  “ap¬ 
pearance”  and  its  “behavior”  (that  is,  its 
“look  and  feel”  respectively).  It  was  the 
opinion  of  the  OSF  membership,  con¬ 
sultants,  and  staff  that  the  behavior  was 
by  far  the  more  important  of  the  two.  As 
a  result,  the  OSF/Motif  style  guide  sets 
forth  the  manner  in  which  the  applica¬ 
tion  should  interact  with  the  user,  but 
not  how  the  graphical  objects  them¬ 
selves  should  appear.  It  does,  however, 
address  some  layout  issues,  because 
the  location  of  certain  common  func¬ 
tions  (such  as  the  Help  button)  clearly 
affects  the  user’s  behavior.  The  visuals 
furnished  with  the  toolkit  provide  a  dis¬ 
tinctive  and  intuitive  3-D  appearance, 
however,  vendors  and  software  devel¬ 
opers  are  free  to  modify  this  appear¬ 
ance  as  they  wish. 

The  behavior  of  the  OSF  offering  is 
compliant  with  the  Presentation  Man¬ 
ager,  as  specified  by  the  joint  HP/Mi¬ 
crosoft  submission.  This  provides  the 
user  with  a  well-designed  and  well- 
tested  interface.  In  addition,  it  provides 
an  interface  that  is  familiar  to  anyone 
having  used  Macintoshes,  PCs,  or  other 
systems  descended  from  the  Xerox  user 


interface  research.  This  creates  a  high 
level  of  “user-transferability”  between 
personal  computers  and  workstations, 
a  goal  clearly  set  forth  by  the  OSF  mem¬ 
bership. 

The  Window  Manager 

Unlike  many  window  systems,  the  X 
Window  System  is  “policy-free”with  re¬ 
gards  to  application  windows.  Instead  a 
separate  application  is  provided,  which 
allows  the  user  to  move,  resize,  iconize, 
or  otherwise  manipulate  windows.  (Unix- 
based  window  systems  traditionally  have 
a  concept  of  an  “icon”  different  than 
that  in  graphical  desktops.  Rather  than 
representing  a  file  or  folder,  these  icons 
represent  running  programs  that  the  user 
temporarily  doesn’t  want,  taking  up 
large  amounts  of  screen  space.)  Win¬ 
dow  managers  provide  the  window 
“dressing”  (special  areas  around  the  win¬ 
dow  border,  which  are  used  to  perform 
these  functions)  and  they  can  imple¬ 
ment  policies  concerning  where  certain 
windows  can  go,  whether  windows  can 
overlap,  and  where  to  put  the  icons. 

The  OSF/Motif  Window  Manager  pro¬ 
vides  the  user  with  standard  Presenta¬ 
tion  Manager  behavior.  It  is  highly  cus¬ 
tomizable,  however,  and  allows  the  user 
to  redefine  the  contents  of  the  window 
manager  menus,  control  the  amount 
and  behavior  of  the  window  dressing, 
and  alter  many  other  aspects  of  window- 
related  interactions. 

The  Presentation  Description  Language 

The  PDL  is  a  language  for  describing 
widget  resources.  Normally  the  appli¬ 
cation  programmer  must  make  a  series 
of  calls  to  build  up  a  widget  descrip¬ 
tion,  and  then  create  the  widget.  With 
the  OSF/Motif  PDL,  the  programmer 
(or  interface  designer)  creates  a  text  file 
that  contains  a  description  of  each  of 
the  widgets  and  their  resources.  This 
description  is  then  compiled  into  a  re¬ 
source  file.  The  application  code  sim¬ 
ply  makes  a  call  to  load  this  file  and  the 
widgets  are  automatically  created  and 
initialized.  This  separation  of  applica¬ 
tion  and  interface  allows  the  interface 
designer  to  make  many  changes  to  the 
overall  appearance  and  layout  of  an 
application  without  having  to  modify, 
recompile,  or  relink  the  application 
itself. 

Native  Language  Support 

One  of  the  primary  goals  of  the  RFT 
process  was  to  support  non-English  lan¬ 
guages.  While  this  area  still  requires  a 
great  deal  of  work  (particular  in  the 
area  of  simultaneously  supporting  8-bit 
and  16-bit  character  sets),  the  OSF  of¬ 
fering  does  begin  to  address  the  prob¬ 
lems.  This  is  done  by  using  a  Unix 


“environment  variable”  (the  X/Open 
specified  LANG  variable)  to  determine 
the  current  default  language.  (Environ¬ 
ment  variables  are  set  from  the  stan¬ 
dard  Unix  command  interpreters  — usu¬ 
ally  when  the  user  logs  in  — and  can  be 
read  via  a  system  call  by  any  interested 
program.)  The  toolkit  uses  this  informa¬ 
tion  to  load  the  user  and  application 
resource  files  appropriate  for  that  lan¬ 
guage.  Because  the  text  of  an  interface 
is  stored  in  the  resource  file,  it  allows 
the  developer  to  easily  construct  inter¬ 
faces  that  can  be  localized  to  particular 
language  environments.  In  addition,  this 
facility  can  be  used  by  programs  that 
wish  to  support  more  than  one  lan¬ 
guage.  By  specifying  the  language  name 
explicitly  they  can  override  the  default 
and  load  all,  or  part  of  their  resources, 
from  a  specific  language  file;  even  if 
that  file  did  not  exist  when  the  applica¬ 
tion  was  originally  built. 

Summary 

The  OSF  UEC  system  represents  nearly 
six  months  of  open  input  and  close 
scrutiny  of  a  wide  variety  of  user  inter¬ 
face  technologies.  Its  availability  across 
a  wide  range  of  Unix  platforms,  and 
its  high-level  user  interface  toolkit 
should  increase  the  incentive  of  soft¬ 
ware  vendors  to  port  to  the  Unix  mar¬ 
ket.  In  addition,  the  UEC  work  at  OSF 
does  not  end  with  the  current  offering. 
Future  activities  being  considered  in¬ 
clude:  work  on  providing  a  printing/ 
imaging  toolkit;  system  information  APIs 
for  graphical  desktops,  shells  or  cyber¬ 
space  decks;  higher-level  user  interface 
APIs  that  don’t  require  access  to  the 
underlying  system;  compound  docu¬ 
ment  support  for  multi/hyper-media  docu¬ 
ments;  and  on-line  help  facilities; 
among  others. 
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PRESENTATION  MANAGER 


listing  One  (Text  begins  on  page  16.) 

/*  A  Presentation  Manager  Application  skeleton.  */ 

♦define  INCL_PM 
♦include  <os2.h> 

♦include  <stddef.h>  /*  get  definition  of  NULL  */ 

void  far  *  pascal  far  window_func (void  far  *,  unsigned  short, 

void  far  *,  void  far  *); 


char  class []  =  "MyClass"; 

main ( ) 

{ 

void  far  *hand_ab; 
void  far  *hand_mq; 

void  far  *hand_frame,  far  *hand_client; 

QMSG  q_mess; 

unsigned  flags  =  FCF_SYSMENU  I 

FCF_S I ZEBORDER  |  FCF_TITLEBAR  | 
FCF_VERTSCROLL |  FCF_HORZ SCROLL  I 
FCF_M INMAX; 

hand_ab  =  Winlnitialize (NULL) ; 


hand_mq  =  WinCreateMsgQueue (hand_ab,  0); 


if ( IWinRegisterClass (hand_ab, 
class, 

window_func, 

CS_SIZEREDRAW, 

0)) 

exit (1) ; 


/*  anchor  block  */ 

/*  class  name  */ 

/*  address  of  window  function  */ 
/*  window  style  */ 

/*  no  storage  reserved  */ 


hand_frame  =  WinCreateStdWindow (HWND  DESKTOP, 
WS_VISIBLE, 

(void  far  *)  sflags, 

(char  far  *)  class, 

(char  far  *)  "My  Window", 

0L,  /*  resource  modules  */ 

NULL, 

0, 

&hand_client) ;  /*  client  handle  */ 


/*  message  loop  */ 

while (WinGetMsg (hand_ab,  &q_mess,  NULL,  0,  0) ) 
WinDispatchMsg  (harid_ab,  &q_mess)  ; 

WinDestroyWindow(hand_frame) ; 


WinDestroyMsgQueue (hand_mq)  ; 
WinTerminate (hand_ab) ; 


/*  If  required  by  your  application,  you  may  also  need  to 
process  these  mouse  messages: 

WM_BUTTON 1 UP 
WM_BUTT0N1DBLCLK 
WM_BUTTON2UP 
WM_BUTTON2DBLCLK 
WM_BUTTON3UP 
WM_BUTTON3DBLCLK 
*/ 

) 

/*  All  messages  not  handled  by  the  window_func, 
must  be  passed  along  to  the  PM  for  default 
processing. 

*/ 

return  WinDefWindowProc (handle,  mess,  parml,  parm2) ; 


End  listing  One 


Listing  Two 


NAME  skeleton 
HEAPSIZE  4096 
STACKSIZE  4096 
EXPORTS  window  func 


End  Listings 


/*  This  is  the  window  function.  */ 

void  far  *  pascal  far  window_func (void  far  ‘handle, 

unsigned  short  mess, 
void  far  ‘parml, 
void  far  *parm2) 


switch (mess)  { 

case  WM_CREATE: 

/*  Perform  any  necessary  initializations  here.  */ 
break; 

case  WM_PAINT: 

/*  Refresh  the  window  each  time  the  WM_PAINT  message  is  received.  */ 
break; 

case  WM_ERASEBACKGROUND : 

/*  By  returning  TRUE,  the  PM  automatically  erases 
the  old  window  each  time  the  window  is  resized 
or  moved.  Without  this,  your  program  must 
manually  handle  erasing  the  window  with  it  changes 
size  or  location. 

*/ 

return (TRUE)  ; 
case  WM_CHAR : 

/*  Process  keystrokes  here.  */ 
break; 

case  WM_HSCROLL : 

/*  Process  horizontal  scroll  request.  */ 
break; 

case  WM_VSCROLL : 

/*  Process  vertical  scroll  request.  */ 
break; 

case  WM_MOUSEMOVE : 

/*  Process  a  mouse  motion  message.  */ 
break; 

case  WM_BUTT0N1D0WN: 

/*  1st  mouse  button  is  pressed.  */ 
break; 

case  WM_BUTTON2DOWN : 

/*  2nd  mouse  button  is  pressed.  */ 
break; 

case  WM_BUTTON3DOWN: 

/*  3rd  mouse  button  is  pressed.  */ 
break; 
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DYNAMIC  LINK 


listing  One  (Text  begins  on  page  28.) 


‘MODULE:  HELPLIB.C 

‘COMMENTS:  contains  the  functions  Screen  and  Topics  (see  HELPDLG.C) 

♦include  <windows.h>  /‘used  by  all  modules  written  for  Windows*/ 
♦include  "helplib.h"  /*  library's  include  file  */ 

♦define  HELPLIB 

♦include  "prothelp.h"  /*  function  prototypes  */ 

*  external  variables 

extern  HANDLE  hlnst;  /‘set  by  initialization  funct.  in  libinitc.c*/ 
/****************************************************************** 

*  global  variables 

***********************************»******************************/ 
LP SCREEN  lpsc; 

BOOL  TOPICS; 

BOOL  SCR; 


rcinclude  HELP. dig 
rcinclude  TOPICS. dig 


Listing  Three 


End  Listing  Two 


*  Local  variables 

static  FARPROC  lpfnScreenDlgProc; 

static  FARPROC  lpfnTopicsDlgProc; 

*  FUNCTION:  Screen 

*  PURPOSE:  Display  help  text  on  a  topic. 

BOOL  FAR  PASCAL  Screen (  LPSCREEN  sc  ) 

(MSG  msg; 

HWND  hWnd; 

LockData (0) ; 
lpsc  =  sc; 

if  (! (lpfnScreenDlgProc  =  MakeProcInstance (ScreenDlgProc, hlnst) ) ) 
return  FALSE; 

if  ( ! (hWnd  =  CreateDialog (hlnst, "HELP_BOX",GetActiveWindow() , 
lpfnScreenDlgProc) ) ) 

return  FALSE; 

while  (GetMessage  (&msg, NULL, 0, 0) ) 

(if  ( ! IsDialogMessage (hWnd, &msg)  ) 

(TranslateMessage (&msg) ; 

DispatchMessage (&msg) ; 


*  FILE:  helplib.h 

*  PURPOSE:  include  file  for  the  helplib  DLL 

typedef  struct  ( 

WORD  wScreen; 

WORD  wStart; 

WORD  wEnd; 

} SCREEN,  FAR  *  LPSCREEN,  NEAR  ‘NP SCREEN; 
♦define  ID_SCREEN_HELP  100 

♦define  ID_LB_TOPICS  101 

♦define  ID_NEXT_HELP  102 

♦define  ID_PREVIOUS_HELP  103 

♦define  ID_TOPICS_HELP  104 

♦define  ID_SCROLL_HELP  105 

♦define  VSRUNTIME  300 

♦define  CAVEATS  301 

♦define  COOKBOOK  302 

♦define  REF  303 

♦define  A  500 

♦define  B  501 

♦define  C  502 

♦define  IDS  MEMERROR  1000 


FreeProcInstance (lpfnScreenDlgProc) ; 


if  (TOPICS) 

(Topics (lpsc) ; 


End  Listing  Three 


UnlockData (0) ; 
return  TRUE; 


*  FUNCTION:  Topics 

*  PURPOSE:  to  present  a  listbox  of  currently  available  help  topics. 

VOID  FAR  PASCAL  Topics (  LPSCREEN  sc  ) 

(LockData (0) ; 
lpsc  =  sc; 

lpfnTopicsDlgProc  =  MakeProcInstance (TopicsDlgProc, hlnst) ; 

DialogBox (hlnst, "TOPICS_BOX" , GetActiveWindow ( ) , lpfnTopicsDlgProc) ; 
FreeProcInstance (lpfnTopicsDlgProc) ; 

if  (SCR) 

( Screen (lpsc) ; 


UnlockData (0) ; 
return; 


Listing  Two 


*  FILE:  helplib. rc 

*  PURPOSE: resource  file  for  the  helplib  DLL 

♦include  <style.h> 

♦include  "helplib.h" 

♦define  TABGRP  (WS  TABSTOP  |  WS_GROUP) 


VSRUNTIME  TEXT 
CAVEATS  TEXT 
COOKBOOK  TEXT 
REF  TEXT 


vsruntime . asc 
caveats . asc 
cookbook. asc 
ref .asc 

a.  asc 

b. asc 


STRINGTABLE 

BEGIN 

I D S_MEME RROR 
VSRUNTIME, 
CAVEATS, 
COOKBOOK, 


"Out  of  Memory" 

"versus  run  time  libraries" 
"caveats" 

"cookbook” 


Listing  Four 


MODULE:  HELPDLG.C 


♦include  <windows.h> 
♦include  "helplib.h" 
♦define  HELPLIB 
♦include  "prothelp.h" 
♦include  "string. h" 


/‘required  for  all  Windows  applicati 
/‘library's  include  file  */ 


/*  function  prototypes  */ 
/*  strlen  */ 


End  Listing  One 


*  to  allow  multiple  screens  from  different  apps/instances 

typedef  struct  screenStruct  ( 

WORD  wScreen; 

WORD  wStart; 

WORD  wEnd; 

int  nPage; 

int  nTopics; 

int  nNumLines; 

HWND  hScroll ; 

int  nVscrollPos; 

) HELPSCREEN,  ‘NPHELPSCREEN; 

/******** ********************************************  ****** 

*  local  variables 

♦define  GWW_SCREENHANDLE  0 

♦define  MAXBUFLEN  80 

♦define  MAXLINES  250 

♦define  LOCAL  static 

*  scroll  bar  positioning  variables 

LOCAL  int  nVscrollMax; 

*  buffer  to  hold  the  help  text 


LOCAL  char  szText [MAXLINES) [MAXBUFLEN] ; 

*  screen  information 
LOCAL  NPHELPSCREEN  sptr; 

*  local  function  prototypes 

LOCAL  VOID  NEAR  getText  (  VOID  ) ; 

LOCAL  VOID  NEAR  setScroll  (  VOID  ) ; 

LOCAL  VOID  NEAR  setNewHelp  (  HWND  ) ; 

LOCAL  HANDLE  NEAR  setToScreen  (  HWND  ) ; 

LOCAL  BOOL  NEAR  di f ferentScreen  (  HWND  ) ; 

LOCAL  BOOL  NEAR  initScreen  (  HWND  ) ; 

LOCAL  VOID  NEAR  freeScreen  (  HANDLE 


(continued  on  page  84) 
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Listing  Four  (Listing  continued,  text  begins  on  page  28.) 

Listing  Four  (Listing  continued,  text  begins  on  page  30.) 

*  external  variables 

{ 

****************************************************************/ 

case  WM  CREATE: 

extern  HANDLE  hlnst;  /*set  by  the  initial,  function  in  libinitc.c*/ 

if  ( ! initScreen (hWnd) ) 

extern  LPSCREEN  lpsc;  /‘passed  in  by  the  calling  function*/ 

break; 

extern  BOOL  TOPICS; /‘used  by  ScreenDlgProc  when  user  requests 

hDC  =  GetDC(hWnd); 

Topics*/ 

GetTextMetrics (hDC, itm) ; 

extern  BOOL  SCR;  /‘used  by  TopicsDlgProc  when  user  requests 

ReleaseDC (hWnd, hDC) ; 

Help*/ 

xChar  =  tm.tmAveCharWidth; 

/*********************************************************************** 

yChar  =  tm.tmHeight  +  tm.tmExternalLeading; 

*  Function:  ScreenDlgProc 

TOPICS  =  FALSE; 

*  Purpose:  To  respond  to  the  Push  Buttons:  Topics,  Next,  Previous,  and 

break; 

*  Cancel  on  the  Screen!)  dialog  box. 

case  WM  SIZE: 

***********************************************************************/ 

hScreen  =  GetWindowWord (hWnd, GWW  SCREENHANDLE) ; 

BOOL  FAR  PASCAL  ScreenDlgProc (HWND  hDlg,  WORD  wMessage,  WORD  wParam, 

sptr  =  (NPHELPSCREEN) LocalLock (hScreen) ; 

LONG  IParam) 

yClient  =  HIWORD (IParam)  ; 

{ int  i ; 

sptr->nPage  =  yClient  /  yChar  ; 

static  BOOL  bImoved=FALSE; 

LocalUnlock (hScreen) ; 

HWND  hWndScreen; 

break; 

HANDLE  hScreen; 

case  WM  SETFOCUS: 

switch (wMessage) 

hScreen  =  GetWindowWord (hWnd,  GWW  SCREENHANDLE); 

{ 

sptr  =  (NPHELPSCREEN) LocalLock (hScreen) ; 

case  WM  INITDIALOG: 

SetFocus (sptr->hScroll) ; 

hScreen  =  setToScreen (hDlg) ; 

LocalUnlock (hScreen) ; 

sptr->nTopics  =  sptr->wEnd  -  sptr->wStart  +  1; 

break; 

sptr->hScroll  =  GetDlgltem (hDlg, ID  SCROLL  HELP); 

/*  the  WM  VSCROLL  message  is  sent  by  the  ScreenDlgProc,  which  has 

getText ( ) ; 

*  already  taken  care  of  sptr 

LocalUnlock (hScreen) ; 

*/ 

break; 

case  WM  VSCROLL: 

case  WM  MOVE: 

switch  (wParam) 

bImoved=TRUE; 

{ 

break; 

case  SB  TOP: 

case  WM  VSCROLL : 

nVscrollInc  =  -sptr->nVscrollPos; 

if  (blmoved) 

break; 

{hScreen  =  setToScreen (hDlg) ; 

case  SB  BOTTOM: 

getText () ; 

nVscrollInc  ■  nVscrollMax  -  sptr->nVscrollPos; 

setScroll {) ; 

break; 

LocalUnlock (hScreen) ; 

case  SB  LINEUP: 

bImoved=FALSE; 

nVscrollInc  =  -1; 

) 

break; 

hWndScreen  =  GetWindow (hDlg, GW  CHILD); 

case  SB  LINEDOWN: 

SendMessage (hWndScreen, WM  VSCROLL, wParam, IParam) ; 

nVscrollInc  =  1; 

break; 

break; 

case  WM  COMMAND 

case  SB  PAGEUP: 

hScreen  =  setToScreen (hDlg) ; 

nVscrollInc  =  min(-l,  -sptr->nPage)  ; 

hWndScreen  =  GetWindow (hDlg, GW  CHILD); 

break; 

switch  (wParain) 

case  SB  PAGEDOWN: 

{ 

nVscrollInc  =  max(l,  sptr->nPage)  ; 

case  ID  PREVIOUS  HELP: 

break; 

sptr->wScreen  =  sptr->wStart  +  (sptr->wScreen-sptr->wStart+ 

case  SB  THUMBPOSITION : 

(sptr->nTopics-l) )  %  sptr->nTopics; 

nVscrollInc  =  LOWORD (IParam)  -  sptr->nVscrollPos; 

setNewHelp (hWndScreen) ; 

break; 

LocalUnlock (hScreen) ; 

default : 

break; 

nVscrollInc  =  0; 

case  ID  NEXT  HELP: 

} 

sptr->wScreen  =  sptr->wStart  +  (sptr->wScreen-sptr->w 

if  (nVscrollInc  =  max (-sptr->nVscrollPos, 

Start+1)  %sptr->nTopics; 

min (nVscrollInc,  nVscrollMax  -  sptr->nVscrollPos) ) ) 

setNewHelp (hWndScreen) ; 

{ sptr->nVscrollPos  +=  nVscrollInc; 

LocalUnlock (hScreen) ; 

ScrollWindow (hWnd,  0,  -yChar  *  nVscrollInc,  NULL,  NULL); 

break; 

UpdateWindow (hWnd) ; 

case  ID  TOPICS  HELP: 

SetScrollPos (sptr->hScroll, SB  CTL, sptr->nVscrollPos, TRUE) ; 

TOPICS  =  TRUE; 

} 

case  IDCANCEL : 

freeScreen (hScreen) ; 

case  WM  PAINT: 

DestroyWindow (hDlg) ; 

hScreen  =  GetWindowWord (hWnd,  GWW  SCREENHANDLE); 

break; 

sptr  =  (NPHELPSCREEN) LocalLock (hScreen) ; 

default : 

BeginPaint (  hWnd,  &ps  ) ; 

return  FALSE; 

nPaintBeg  =  max (0, sptr->nVscrollPos  +  ps . rcPaint .top/yChar  -  1); 

) 

break; 

nPaintEnd  =  min  (sptr->nNumLines, 

sptr->nVscrollPos  +  ps . rcPaint .bottom  /  yChar); 

case  WM_ACTIVATE:  /*  when  the  dialog  is  activated,  check  to 

for  (i=nPaintBeg;  i  <  nPaintEnd;  ++i) 

*  see  if  the  correct  screen  mode  is 

(TextOut (ps.hdc, xChar, yChar  *  (1  -  sptr->nVscrollPos+i) , 

*  is  selected. 

*/ 

if  (IwParam) 

szText [i] , strlen (szText [ i ] ) ) ; 

} 

EndPaint (hWnd, &ps) ; 

break; 

LocalUnlock (hScreen) ; 

case  WM  PAINT:  /*  User  could  be  switching  'tween  n  application's 

break; 

*  (or  n  instances)  Help  Dialogs 

case  WM  DESTROY: 

*/ 

PostQuitMessage (0)  ; 

hScreen  =  setToScreen (hDlg) ; 

if  (differentScreen (hDlg) ) 

default : 

(getText () ; 

return  DefWindowProc (  hWnd,  wMessage,  wParam,  IParam  ); 

if  (WM  ACTIVATE  ==  wMessage) 

I 

return  0L; 

} 

(SetFocus (sptr->hScroll) ; 

setScroll () ; 

} 

LocalUnlock (hScreen) ; 

*  Function:  TopicsDlgProc 

*  Purpose:  To  respond  to  the  list  box  and  push  button  messages 

return  FALSE; 

*  of  the  Topics ()  dialog  box. 

default : 

******************************************************************* / 

return  FALSE; 

BOOL  FAR  PASCAL  TopicsDlgProc (HWND  hDlg,  WORD  wMessage,  WORD  wParam, 

} 

LONG  IParam) 

return  TRUE; 

(int  i; 

} 

LOCAL  char  szBuf f [MAXBUFLEN] ; 

*  Function:  ScreenWndProc 

switch (wMessage) 

{ 

‘  Purpose:  To  respond  to  messages  received  by  the  Screen ()  window. 

*  Notes:  The  WM  VSCROLL,  WM  PAINT  message  handling  was  derived  from 

case  WM  INITDIALOG: 

Programming  Windows  by  Charles  Petzold,  pp.  117-122. 

SetSysModalWindow (hDlg) ; 

for  (i=lpsc->wStart; i<=lpsc->wEnd; ++i) 

long  FAR  PASCAL  ScreenWndProc (HWND  hWnd,  WORD  wMessage,  WORD  wParam, 

(LoadString (hlnst, i, szBuff, MAXBUFLEN) ; 

LONG  IParam) 

SendDlgltemMessage (hDlg, ID  LB  TOPICS, LB  ADDSTRING, 0, 

(LONG) (LPSTR) szBuff) ; 

} 

LOCAL  int  xChar,yChar; 

LOCAL  int  yClient; 

SendDlgltemMessage (hDlg, ID  LB  TOPICS, LB  SETCURSEL, 0, OL) ; 

LOCAL  TEXTMETRIC  tm; 

SCR  =  FALSE; 

int  i; 

break; 

int  nVscrollInc; 

case  WM  COMMAND: 

int  nPaintBeg, nPaintEnd; 

switch (wParam) 

{ 

HDC  hDC; 

HANDLE  hScreen; 

case  ID  LB  TOPICS: 

switch (wMessage) 

if  ( (HIWORD (IParam) )  !=  LBN  DBLCLK) 
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case  IDOK: 

lpsc->wScreen  =  (WORD) SendDlgltemMessage (hDlg, ID_LB_TOPICS, 
LB_GETCURSEL, 0,0L)  +  lpsc->wStart; 

SCR=TRUE; 
case  IDCANCEL: 

EndDialog (hDlg, TRUE) ; 
break; 
default : 

return  FALSE; 


break; 

default: 

return  FALSE; 


*  Function:  getText 

*  Purpose:  To  retrieve  the  help  text  for  the  current  screen  from  the 

*  Help  library's  resource  file. 
********************************************************************* 

LOCAL  VOID  NEAR  getText  (  ) 

{ LPSTR  lpText , lpTextBeg; 

HANDLE  hRes; 

hRes  =  LoadResource (hlnst, 

FindResource (hlnst, MAKEINTRESOURCE (sptr->wScreen) , "TEXT") ) ; 
lpText  =  LockResource (hRes) ; 
sptr->nNumLines=0 ; 
lpTextBeg  -  lpText; 

while  (*lpText  !=  '\0'  &s  *lpText  !=  '\xlA'  ) 

{if  (*lpText  —  ' \r' ) 

{* lpText  =  '\0'; 

lstrcpy (szText [sptr->nNumLines++] , lpTextBeg) ; 
if  (sptr->nNumLines  >=  MAXLINES) 
break; 

*lpText=' \r' ; 

lpText  =  AnsiNext (lpText) ; 
if  (* lpText  =  '\1') 

lpText  =  AnsiNext (lpText) ; 
lpTextBeg  =  lpText; 

} 

else 

lpText  =  AnsiNext (lpText) ; 

) 

* lpText  =  '\0'; 

lstrcpy (szText [sptr->nNumLines++] , lpTextBeg) ; 

GlobalUnlock (hRes) ; 

FreeResource (hRes) ; 


*  Function:  setScroll 

*  Purpose:  To  set  the  scroll  bar  control's  range  and  initial  position. 
LOCAL  VOID  NEAR  setScroll (  ) 

{nVscrollMax  =  max(0,  sptr->nNumLines  +  2  -  sptr->nPage) ; 
if { InVscrollMax) 

(ShowScrollBar (sptr->hScoll, SB_CTL, FALSE] ; 

) 

else 

SetScrollRange (sptr->hScroll,  SB_CTL,0,  nVscrollMax,  FALSE); 
SetScrollPos  (sptr->hScroll,  SB_CTL, sptr->nVscrollPos, TRUE) ; 


*  Function:  setNewHelp 

*  Purpose:  Get  the  right  screen  help  info 

LOCAL  VOID  NEAR  setNewHelp (HWND  hWnd) 
{sptr->nVscrollPos  =  0; 
getText () ; 
setScroll ()  ; 

InvalidateRect (hWnd, NULL, TRUE) ; 

SetFocus (sptr->hScroll) ; 


sptr  =  (NPHELPSCREEN) LocalLock (hScreen) ; 
sptr->wScreen  =  lpsc->wScreen; 
sptr->wStart  =  lpsc->wStart ; 
sptr->wEnd  =  lpsc->wEnd; 

LocalUnlock (hScreen) ; 

SetWindowWord (  hWnd,  GWW_SCREENHANDLE,  hScreen  ); 
return  TRUE; 


*  Function:  freeScreen 

*  Purpose:  All  done  with  the  screen,  so  release  the  memory. 

LOCAL  VOID  NEAR  freeScreen (HANDLE  hScreen) 

{lpsc->wScreen  =  sptr->wScreen; 
lpsc->wEnd  =  sptr->wEnd; 
lpsc->wStart  =  sptr->wStart; 

LocalUnlock (hScreen) ; 

LocalFree (hScreen) ; 

) 


End  listing  Four 


Listing  Five 


*  Utilities  library  C  language  initialization. 

*/ 

♦include  <windows.h> 

♦include  "helplib.h" 

♦include  "prothelp.h" 

*  function  prototypes 
♦define  LOCAL  static 

int  NEAR  PASCAL  LiblnitC  (  HANDLE  ) ; 

LOCAL  BOOL  NEAR  registerWindow  (  VOID  ) ; 


HANDLE  hlnst; 

*  C  init  called  from  the  asm  entry  point  init. 

*  We  require  that  the  library  have  exactly  one  DS.  See  libinita 

*  The  DS  can  (should)  be  moveable. 

int  NEAR  PASCAL  LiblnitC (HANDLE  hlnstance) 

{ 

hlnst  =  hlnstance; 
return (registerWindow () ) ; 


LOCAL  BOOL  NEAR  registerWindow  (  ) 


( WNDCLASS  WndClass; 
WndClass . style 
WndClass . lpf nWndProc 
WndClass .cbClsExtra 
WndClass . cbWndExtra 
WndClass .hlnstance 
WndClass . hlcon 
WndClass . hCursor 
WndClass .hbrBackground 
WndClass . IpszMenuName 
WndClass . IpszClassName 


/*  Window  class  structure  */ 
=  CS_HREDRAW  |  CS_VREDRAW; 

=  ScreenWndProc; 

=  0; 

=  sizeof (HANDLE) ; 

=  hlnst; 

=  NULL; 

=  LoadCursor (NULL,  IDC_ARROW) ; 
=  COLOR_WINDOW+l ; 

=  NULL; 

=  "Screen"; 


return  RegisterClass (SWndClass)  ; 


*  Function:  setToScreen 

*  Purpose:  Lock  the  screen  pointer  to  the  correct  screen  info. 

LOCAL  HANDLE  NEAR  setToScreen (HWND  hWnd  ) 

(HANDLE  hScreen; 

HWND  hWndScreen; 

hWndScreen  =  GetWindow (hWnd, GW_CHILD) ; 

hScreen  =  GetWindowWord (hWndScreen,  GWW_SCREENHANDLE) ; 

sptr  =  (NPHELPSCREEN) LocalLock (  hScreen  ); 

return  hScreen; 


End  listing  Five 


Listing  Six 


*  Function:  differentScreen 

*  Purpose:  Find  out  if  hDlg  references  the  same  window  as  the  last  call 
*********************************************************************/ 

LOCAL  BOOL  NEAR  differentScreen (HWND  hDlg) 

{LOCAL  HWND  hWnd  =  NULL; 
if  (hWnd  !=  hDlg) 

{hWnd  =  hDlg; 
return  TRUE; 

) 

return  FALSE; 

} 

/********************************************************************* 

*  Function:  initScreen 

*  Purpose:  Set  up  the  screen  on  a  WM_CREATE  message. 
********************************************************************/ 

LOCAL  BOOL  NEAR  initScreen (HWND  hWnd) 

{HANDLE  hScreen; 
char  szMemErr [15] ; 

if  (! (hScreen  =  LocalAlloc (LHND, sizeof (HELPSCREEN) )) ) 

{LoadString (hlnst, IDS_MEMERROR, szMemErr,  15)  ; 

MessageBox (  GetParent (hWnd) ,  szMemErr,  NULL,  MB_ICONEXCLAMATION) ; 
return  FALSE; 

) 


;  LIBINITA. ASM  -  -  -  Define  entry  point  and  perform  initialization 
;  for  libraries  that  have  their  own  data  segments. 

TITLE  LIBINITA 

?PLM  =  1 
?WIN  =  1 
memM  =  1 

. xlist 

include  cmacros.inc 
.  list 

externFP  <LocalInit> 

externFP  <UnlockSegment> 

externNP  <LibInitC> 

;  cx  =  size  of  the  heap  as  defined  in  the  .def  file. 

;  di  =  "Instance  handle".  This  is  the  C  hlnstance  passed  to  WinMain. 

;  NOTE:  For  a  WINDOWS  library,  hModule  is  interchangeable  with 

;  hlnstance. 

;  This  is  a  handle  to  the  global  object  containing  the  DS  if 

;  there  is  one.  If  there  is  no  DS  for  a  library,  it  is  the 

;  module  handle,  which  is  also  a  pointer  to  the  module  since 


(continued  on  page  88) 
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listing  Six  (Listing  continued,  text  begins  on  page  28.) 

;  that's  a  fixed  global  object. 

;  NOTE:  The  meaning  and  contents  of  hlnstance  are  undocumented 

;  and  should  not  be  relied  upon.  That  is,  you  may 

;  assume  that  the  value  in  di  may  be  passed  to  any 

;  routine  expecting  hlnstance.  Making  any  other 

;  assumptions  is  VERY  dangerous  since  the  contents  of 

;  hlnstance  may  change  in  future  versions. 

;  ds  =  data  segment  for  our  heap. 

;  es:si  =  pointer  to  the  command  line. 


INIT  SEGMENT  BYTE  PUBLIC  'CODE' 


assume  CS: 

INIT  ;  ???? 

assume  vs  assumes?  ??????????????? 

assumes  DS 

NOTHING  ;  ???? 

assume  vs  assumes?  ??????????????? 

assumes  ES 

NOTHING  ;  ???? 

assume  vs  assumes?  ??????????????? 

cProc  LiblnitA,  <FAR,  PUBLIC,  NODATA> ,  <si,di> 

cBegin 

xor 

ax,  ax 

;  Return  failure  if  there  is  no  heap. 

jcxz 

ourexit 

cCall 

Locallnit, <ds, ax, cx> 

;  Set  up  our  DS  for  doing  LocalAllocs 

or 

ax,  ax 

jz 

ourexit 

cCall 

LiblnitC, <di> 

;  Do  any  C  initialization. 

push 

ax 

;  di  =  hlnstance. 

;  Save  the  return  value. 

mov 

ax,  -1 

cCall 

UnlockSegment, <ax> 

;  NOTE  that  we  leave  DS  unlocked. 

pop 

bx 

;  This  implies  that  we  must  use 
;  Lock/UnlockData  as  we  enter  and 
;  any  routines  which  access  our 
;  data  segment. 

or 

ax,  ax 

;  Check  if  either  one  failed. 

jz 

ourexit 

or 

bx,bx 

jnz 

ourexit 

xor 

ax,  ax 

ourexit : 
cEnd 

_INIT  ENDS 
end  LiblnitA 


End  Listing  Six 


Listing  Seven 

LIBRARY  helplib 

DESCRIPTION  'Copyright  1988,  mkj' 

STUB  'WINSTUB.EXE' 

CODE  LOADONCALL  MOVEABLE  DISCARDABLE 

DATA  MOVEABLE  SINGLE 

HEAPSIZE  2048 

CODE  MOVEABLE 

SEGMENTS  _INIT  PRELOAD  MOVEABLE  DISCARDABLE 

HELPLIB  MOVEABLE  LOADONCALL  DISCARDABLE 

EXPORTS 

Screen  @1 

Topics  @2 

ScreenDlgProc  @3 
ScreenWndProc  @4 
TopicsDlgProc  @5 


End  Listing  Seven 


Listing  Eight 

# 

#  FILE:  helplib 

#  PURPOSE:  make  file  for  the  helplib  DLL 

# 

COMP  =  -c  -Alnw  -Gsw  -Zp  -Os  -FPa  -W2  -D  LINT_ARGS 

OBJS  =  helplib. obj  helpdlg.obj  libinita.obj  libinitc.obj  helplib. res 

LOBJS  =  helplib+helpdlg+libinita+libinitc 

. rc . res : 
rc  -r  $*.rc 

. asm. obj : 
masm  $*; 

helplib. res :  helplib. rc  helplib. h  vsruntim.asc  caveats.ascN 

cookbook. asc  ref.asc  help. dig  topics. dig 

helplib. obj:  helplib. c  helplib. h  prothelp.h 

cl  $ ( COMP )  -NT  $*  $*.c 


helpdlg.obj:  helpdlg.c  helplib. h  prothelp.h 

cl  $ (COMP)  -NT  HELPLIB  $*.c 

libinita.obj:  libinita.asm 

masm  $*; 

libinitc.obj:  libinitc.c 

Cl  $ (COMP)  -NT  _INIT  $*.C 

helplib.exe:  $ (OBJS)  helplib. def 

link4  $ (LOBJS) , helplib. exe/align: 16, /map/li,mwinlibc 
mlibw  mlibca  /NOE  , helplib. def 
rc  helplib. res  helplib.exe 

implib  helplib. lib  helplib. def 


End  Listing  Eight 


Listing  Nine 

*  FILE:  helpdemo.c 

*  PURPOSE:  to  demonstrate  the  use  of  the  helplib  DLL 
»******************************************************************/ 

♦include  <windows.h> 

♦include  "helpdemo.h" 

HANDLE  hlnstance;  /*The  Instance  handle  */ 

char  szClass(lO);  /"Window  class  name  (see  the  .rc  file)  */ 

char  szTitle[40);  /"Window  title  (see  the  .rc  file)  */ 

char  szAbout[40);  /"About  box  string  (see  the  .rc  file  */ 

static  HWND  hWnd; 

long  FAR  PASCAL  WndProc  (HWND,  unsigned,  WORD,  LONG) ; 

BOOL  NEAR  Initialize (  HANDLE,  int  ); 

"Application  main  program. 

*********************************************************************/ 
int  PASCAL  WinMain(  hlnst,  hPrevInst,  IpszCmdLine,  nCmdShow  ) 

HANDLE  hlnst;  /"Our  instance  handle  */ 

HANDLE  hPrevInst;  /"Previous  instance  of  this  application*/ 

LPSTR  IpszCmdLine;  /"Pointer  to  any  command  line  params*/ 

int  nCmdShow;  /"Parameter  to  use  for  first  ShowWindow*/ 

{ 

MSG  msg;  /"Message  structure  */ 

HANDLE  hAccel;  /"Accelerator  handle  */ 

/*  Save  our  instance  handle  in  a  global  variable  */ 
hlnstance  =  hlnst; 

/*  Initialize  application,  quit  if  any  errors  */ 
if(  !  Initialize  (  hPrevInst,  nCmdShow  )  ) 

(return  FALSE; 

) 

/"Main  message  processing  loop.  Get  each  message,  then 
"translate  keyboard  messages  and  finally  dispatch  each 
*  message  to  its  window  function. 

*/ 

hAccel  =  LoadAccelerators (hlnstance, szClass) ; 
while  (  GetMessage(  &msg,  NULL,  0,  0  )  ) 

(if  ( ITranslateAccelerator (hWnd,  hAccel,  &msg) ) 
(TranslateMessage (  &msg  ); 

DispatchMessage (  &msg  ) ; 

) 

> 

return  msg.wParam; 

) 

/""***** *********** ******* **************************  **************** 
"Initialize  the  application. 

BOOL  NEAR  Initialize (  hPrevInst,  nCmdShow  ) 

HANDLE  hPrevInst;  /"Previous  instance  handle,  0  if  first  */ 

int  nCmdShow;  /"Parameter  from  WinMain  for  ShowWindow  */ 

( 

WNDCLASS  WndClass;  /"Class  structure  for  RegisterClass  */ 

HMENU  hMenu;  /"Handle  to  the  (system)  menu  */ 

if (  !  hPrevInst  )  { 

/*  Initialization  for  first  instance  only  */ 

/*  Load  strings  from  resource  file  */ 

LoadString(  hlnstance,  IDS_CLASS,  szClass,  sizeof (szClass)  ); 
LoadString (  hlnstance,  IDS_TITLE,  szTitle,  sizeof (szTitle)  ); 
/*  Register  our  window  class  */ 

WndClass. style  =  CS_HREDRAW  |  CS_VREDRAW; 

WndClass . lpfnWndProc  =  WndProc; 

WndClass . cbClsExtra  =  0; 

WndClass . cbWndExtra  =  0; 

WndClass . hlnstance  =  hlnstance; 

WndClass. hlcon  =  LoadIcon(  NULL,  IDI_APPLICATION  ); 

WndClass . hCursor  =  LoadCursor(  NULL,  IDC_ARROW  ); 

WndClass . hbrBackground  =  COLOR_WINDOW  +  1; 

WndClass . IpszMenuName  =  szClass; 

WndClass . IpszClassName  =  szClass; 

if (  !  RegisterClass  (  SWndClass  )  ) 
return  FALSE; 

) 

else 

(/*  Initialization  for  subsequent  instances  only  */ 

/*  Copy  data  from  previous  instance  */ 

GetlnstanceData (  hPrevInst,  szClass,  sizeof (szClass)  ); 

GetlnstanceData  (  hPrevInst,  szTitle,  sizeof (szTitle)  ); 

) 

/*  Initialization  for  every  instance  */ 
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Listing  Nine  ( Listing  continued,  text  begins  on  page  28.) 


/*  Create  the  window  */ 
hWnd  =  CreateWindow ( 

szClass,  /*  Class  name  */ 

szTitle,  /*  Window  title 

WS_OVERLAPPEDWINDOW 
CWJJSEDEFAULT,  /*x  */ 

0,  /*y  */ 

CW_USEDEFAULT,  /*x  width  */ 

0,  /*y  width  */ 

NULL,  /‘Parent  hWnd  (n> 

NULL,  /‘Menu  handle  */ 

hlnstance,  /‘Owning  instano 

NULL  /‘Parameter  to  p, 


/*  window  style  */ 


/*x  */ 

/ *y  */ 

/*x  width  */ 

/*y  width  */ 

/‘Parent  hWnd  (none  for  top-level)  */ 
/‘Menu  handle  */ 

/‘Owning  instance  handle  */ 

/‘Parameter  to  pass  in  WM_CREATE  (none) 


/*  Insert  "About..."  into  system  menu  */ 

LoadString  (  hlnstance,  IDS_ABOUT,  szAbout,  sizeof (szAbout)  ); 
hMenu  =  GetSystemMenu (hWnd,  FALSE); 

ChangeMenu (hMenu,  0,  NULL,  999,  MF_APPEND  |  MF_SEPARATOR) ; 
ChangeMenu (hMenu,  0,  (LPSTR) szAbout,  IDS_ABOUT,  MF_APPEND  | 

MF_STRING) ; 

/*  Make  the  window  visible  */ 

ShowWindow (  hWnd,  nCmdShow  ) ; 

/*  Got  all  the  information,  update  our  display  */ 

UpdateWindow (  hWnd  ); 


EndPaint (hWnd, &ps) ; 
return  TRUE; 


BOOL  FAR  PASCAL  AboutDlgProc (  hDlg,  message,  wParam,  IParam  ) 
HWND  hDlg; 
unsigned  message; 

WORD  wParam; 

LONG  IParam; 

( 

if  (message  ==  WM_COMMAND) 

(EndDialog (  hDlg,  TRUE  ); 
return  TRUE; 

} 

else  if  (message  ==  WM_INITDIALOG) 
return  TRUE; 
else  return  FALSE; 


End  Listing  Ten 


Listing  Eleven 


End  Listing  Nine 


listing  Ten 


*  The  message  functions. 

♦include  "windows. h" 
♦include  "helpdemo.h" 
♦include  "helplib.h" 
♦include  "prothelp.h" 

extern  HANDLE  hlnstance; 


/*  library's  help  file  */ 

/*  prototypes  for  library's  functions  */ 


*  FILE:  wndproc.c 

*  PURPOSE:  The  functions  WndProc  and  About  for  the  helplib  DLL  demo. 

it************************************.*******************.*********/ 

♦include  "windows. h" 

♦include  "helpdemo.h" 
extern  HANDLE  hlnstance; 

/******************  Message  function  prototypes  ** ***************** / 
extern  VOID  HelpDemoMsg  (  HWND,  WORD,  LONG  ) ; 

/******************  local  function  prototype  **********************/ 
BOOL  NEAR  paint  (  HWND  ) ; 

long  FAR  PASCAL  WndProc (  HWND,  unsigned,  WORD,  LONG  ); 

BOOL  FAR  PASCAL  AboutDlgProc (  HWND,  unsigned,  WORD,  LONG  ); 

long  FAR  PASCAL  WndProc (  hWnd,  message,  wParam,  IParam  ) 

HWND  hWnd; 
unsigned  message; 

WORD  wParam; 

LONG  IParam; 

( 

FARPROC  IpprocAbout; 
switch  (message) 

{ 

case  WM_SYSCOMMAND: 
switch  (wParam) 

{ 

case  IDS_ABOUT: 

/‘Bind  callback  function  with  module  instance*/ 
IpprocAbout  =  MakeProcInstance (  (FARPROC) About 

DlgProc, 
hlnstance) ; 

DialogBox  (  hlnstance,  MAKEINTRESOURCE 

(ABOUTBOX) ,  hWnd, 
IpprocAbout  ) ; 

FreeProcInstance(  (FARPROC) AboutDlgProc  ); 
break; 
default : 

return  DefWindowProc (  hWnd,  message,  wParam, 

IParam  ) ; 

) 

break; 

case  WM_COMMAND: 

switch (wParam) 

{ 

case  IDM_HELP : 

HelpDemoMsg  (hWnd,  wParam,  IParam) ; 
break; 


/*******************  iocai  function  prototypes 
VOID  HelpDemoMsg  (  HWND,  WORD,  LONG  ); 

/********************************************** 
VOID  HelpDemoMsg (  hWnd,  wParam,  IParam  ) 

HWND  hWnd; 

WORD  wParam; 

LONG  IParam; 

(SCREEN  sc; 

sc.wStart  =  VSRUNTIME; 
sc.wEnd  =  REF; 

Topics (&sc) ; 


End  Listing  Eleven 


Listing  Twelve 


*  FILE:  prothelp.h 

*  PURPOSE: function  prototypes  for  the  helplib  DLL 

♦ifndef  HELPDLG 

♦define  HELPDLG  extern 
♦endif 

♦ifndef  HELPLIB 

♦define  HELPLIB  extern 
♦  endif 


HELPLIB  BOOL  FAR  PASCAL  Screen 
HELPLIB  VOID  FAR  PASCAL  Topics 
HELPDLG  BOOL  FAR  PASCAL  ScreenDlgProc 
HELPDLG  BOOL  FAR  PASCAL  TopicsDlgPrOC 
HELPDLG  LONG  FAR  PASCAL  ScreenWndProc 
extern  LPSTR  FAR  PASCAL  lstrcpy 
extern  int  FAR  PASCAL  lstrlen 


(  LP SCREEN  ) ; 

(  LPSCREEN  ) ; 

(  HWND,  WORD,  WORD,  LONG  ); 
(  HWND,  WORD,  WORD,  LONG  ) ; 
(  HWND,  WORD,  WORD,  LONG  ); 
(  LPSTR,  LPSTR  ) ; 

(  LPSTR  ) ; 


End  Listing  Twelve 


case  WM_PAINT : 

paint (  hWnd  ) ; 
break; 

case  WM_DESTROY: 
case  WM_CLOSE: 

PostQuitMessage (  0  ); 
break; 
default : 

return  DefWindowProc (  hWnd,  message,  wParam, 


/*****.************************************************* 
*  Paint  procedure  (for  processing  of  WM_PAINT  messages) 

BOOL  NEAR  paint  (  hWnd  ) 

HWND  hWnd; 

{ 

PAINTSTRUCT  ps; 

BeginPaint (hWnd, &ps) ; 


Listing  Thirteen 


FILE:  helpdemo.h 

PURPOSE:  include  file  for  the  help  DLL  demonstration  window 


/“*““  strings  ““ 
♦define  IDS_CLASS 

♦define  IDS_TITLE 

♦define  IDS_ABOUT 

/ ********  menus  ***** 
♦define  ABOUTBOX 

♦define  I DM  HELP 


0  /‘String  Table  ID  for  the  Class  Name*/ 

1  /‘String  Table  ID  for  the  Title  */ 

2  /‘String  Table  ID  for  the  About  box*/ 

3  /*  About  dialog  resource  ID  */ 

1000  /*  Menu  resource  ID  */ 


End  listing  Thirteen 
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Listing  Fourteen 


NAME  HELPDEMO 

DESCRIPTION  'Help  DLL  Demonstration,  Copyright  1988,  mkj' 
STUB  ' WINSTUB.EXE' 

CODE  LOADONCALL  MOVEABLE  DISCARDABLE 

DATA  MOVEABLE  MULTIPLE 

HEAPSIZE  2048 

STACKS I ZE  4096 

EXPORTS 

WndProc  @1 

AboutDlgProc  @2 


End  Listing  Fourteen 


Listing  Fifteen 


FILE:  helpdemo.rc 

PURPOSE:  used  with  the  helplib  DLL  for  demonstration 


#include  <style.h> 
(finclude  "helpdemo.h" 


STRINGTABLE 

BEGIN 

IDS_CLASS 

IDS_TITLE 

IDS_ABOUT 

END 


"HelpDemo" 

"Help  Demonstration" 
"About ..." 


ABOUTBOX  DIALOG  22,  17,  154,  75 
STYLE  WS_P0PUP  |  WS_DLGFRAME 
BEGIN 

CTEXT  "DLL  Example" 

CTEXT  "Help  Library  Demonstration" 
CTEXT  "Version  1.00" 

CTEXT  "Copyright  )  1988,  mkj" 


-1,  o, 

5,  154,  8 

-1,  o. 

14,  154,  8 

-1, 

30, 

34,  94,  8 

-1, 

0, 

47,154,  9 

DEFPUSHBUTTON  "Ok" 


IDOK,  61,  59,  32,  14,  WS_GROUP 


HelpDemo  MENU 
BEGIN 

MENUITEM  "\aFl=Help" , 
END 


I DM  HELP, HELP 


HelpDemo  ACCELERATORS 
BEGIN 

VK_F1,  IDM_HELP,  VIRTKEY 

END 


End  Listing  Fifteen 


Listing  Sixteen 


TOPICS_BOX  DIALOG  LOADONCALL  MOVEABLE  DISCARDABLE  28,  19,  206,  79 

STYLE  WS_DLGFRAME  |  WS_POPUP 

BEGIN 

CONTROL  ID_L3_T0PICS,  "listbox",  LBS_NOTIFY  | 

BORDER  |  WS_VSCROLL  I  WS_CHILD  |  TABGRP,  12,  18,  144,  49 
CONTROL  "&Help",  IDOK,  "button",  BS_DEFPUSHBUTTON  I 

WS_TABSTOP  I  WS_CHILD  I  TABGRP,  165,  17,  32,  14 
CONTROL  "Cancel",  IDCANCEL,  "button”,  BS_PUSHBUTTON  I 
WSTABSTOP  |  WS_CHILD  ,  165,  43,  32,  14 
CONTROL  "Help  Topics  on  DLL's",  103,  "static",  SS_LEFT  I 
WS_CHILD,  12,  5,  100,  11 

END 


End  Listing  Sixteen 


Listing  Seventeen 

HELP  BOX  DIALOG  LOADONCALL  MOVEABLE  DISCARDABLE  10,  9,  262,  131 
STYLE  WS_BORDER  I  WS_CAPTION  |  WS_POPUP  I  WS_SYSMENU  |  WS_VISIBLE 
CAPTION  "Help" 

BEGIN 

CONTROL  "",  ID  SCREEN  HELP,  "Screen",  WS_BORDER  I  WS_CHILD  | 

TABGRP,  9,  9,  234,  90 

CONTROL  ID  SCROLL_HELP,  "scrollbar",  SBS_VERT  I 

WS_CHILD  |  WS_CLIPSIBLINGS,  242,  9,  8,  90 
CONTROL  "SNext",  ID  NEXT_HELP,  "button",  BS_DEFPUSHBUTTON  I 

WS_TABSTOP  I  WS_CHILD,  76,  105,  44,  16 
CONTROL  "^Previous",  ID_PREVIOUS_HELP,  "button",  BS_PUSHBUTTON  I 
WSTABSTOP  I  WS_CHILD,  139,  105,  44,  16 
CONTROL  "Cancel",  IDCANCEL,  "button",  BS_PUSHBUTTON  I 

WS_TABSTOP  |  WS_CHILD,  201,  105,  44,  16 
CONTROL  "^Topics”,  ID_TOPICS_HELP,  "button",  BS_PUSHBUTTON  I 

WS_TABSTOP  I  WS_CHILD,  14,  105,  44,  16 

END 

End  Listing  Seventeen 
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listing  One  (Text  begins  on  page  38.) 

/*  GEM  uses  16  bit  quantities  for  raster 
coordinates  */ 
typedef  short  int  WORD; 

WORD  pxl_width,  pxl_height; 

WORD  work_in[ll],  ws_handle,  work_out [57] ; 

/*  Open  the  workstation  after  filling  in  initial 
defaults  into  work_in[]  */ 

if(  v_opnwk (work_in, &ws_handle, work_out)  ==  FAILURE  ) 

{  /*  Handle  fatal  error  */  } 

/*  After  successful  open,  ws_handle  identifies  the 
desired  workstation  and  work_out  contains  57 
units  of  information  about  the  device, 
including  the  width  and  height  of  each  pixel  in 
microns  */ 

pxl_width  =  work_out[3]; 
pxl_height  =  work_out[4]; 

/*  Returns  a  value  in  y  units  that  is  scaled  to  x 
units  */ 

WORD  scale_y(WORD  raw_y) 

{ 

return  raw_y  *  pxl_width  /  pxl_height; 


/*  Draw  a  square  on  the  screen  that  is  "x_units" 
wide  and  looks  square  */ 

VOID  draw_square(WORD  x,  WORD  y,  WORD  x_units) 

{ 

WORD  xy [10] ; 

xy[0]  =  x;  xy [  1 )  *»  y; 

xy [ 2 ]  =  x+x_units;  xy [ 3 ]  =  y; 

xy[4]  =  x+x_units;  xy[5]  -  y+scale_y (x_units) ; 

xy[6]  =  x;  xy[7]  -  y+scale_y (x_units) ; 

xy [8]  =  x;  xy[9]  =  y; 

v_pline (ws_handle, 5, xy) ; 


End  Listing  One 


listing  Two 

SAMPLE  SOURCE  OUTPUT  FROM  RESOURCE  CONSTRUCTION  SET 


♦define  TOOBJ  0 
♦define  FREEBB  1 
♦define  FREE IMG  1 
♦define  FREESTR  4 

BYTE  *rs_strings[]  =  { 

"This  is  a  Sample  Dialog", 

"with  an  image  and  two  buttons.", 

"OK", 

"Cancel"}; 

WORD  IMAGO []  =  { 

0x7FF,  OxFFFF,  0xFF80,  OxCOO, 

0x0,  OxCO,  0xl83F,  0xF03F, 

0xF060,  0xl87F,  OxF860,  0x1860, 

0xl87F,  0xF860,  0x1860,  0xl87F, 

0xF860,  0x1860,  0xl87F,  OxF860, 

0x1860,  0xl87F ,  0xF860,  0x1860, 

0xl87F,  0xF860,  0x1860,  0xl87F, 

0xF860,  0x1860,  0xl87F,  0xF860, 

0x1860,  0xl87F,  0xF86O,  0x1860, 

0xl87F,  0xF860,  0x1860,  0xl87F, 

0xF860,  0x1860,  0xl83F,  0xF03F, 

OxF060,  OxCOO,  0x0,  OxCO, 

0x7FF,  OxFFFF,  OxFFBO,  0x0, 

0x0,  0x0,  0x3F30,  0xC787, 

Ox8FEO,  0xC39,  OxCCCC,  OxCCOO, 

0xC36,  OxCFCC,  0xF80,  0xC30, 

OxCCCD,  OxCCOO,  Ox3F30,  0xCCC7, 

OxCFEO,  0x0,  0x0,  0x0); 

LONG  rs_frstr[]  =  { 

0); 

BITBLK  rs_bitblk[]  =  { 

0L,  6,  24,  0,  0,  1}; 

LONG  rs_frimg[]  =  { 

0); 

ICONBLK  rsiconblk [ ]  =  { 

0}; 

TEDINFO  rs_tedinfo[]  =  { 

0); 

OBJECT  rs_object[]  =  { 

-1,  1,  5,  G_BOX,  LASTOB,  SHADOWED,  0x21100L,  0,0,  43,9, 


2, 

-1, 

-1,  G 

STRING, 

NONE,  NORMAL,  OxOL, 

10,4, 

23,1, 

3, 

-1, 

-i»  g" 

"STRING, 

NONE,  NORMAL,  OxlL, 

7,5, 

30,1, 

4, 

-1, 

-It  g' 
8,1," 
-1,  G 

^BUTTON, 

SELECTABLE,  NORMAL, 

0x2L, 

10,7, 

5, 

-1, 

BUTTON, 

SELECTABLE,  NORMAL, 

0x3L, 

24,7, 

0, 

-1, 

-1,  G_ 

IMAGE, 

LASTOB,  NORMAL,  OxOL, 

19,1 

,  6,3) 

LONG  rs_trindex[]  =  { 
0L}; 


struct  foobar  { 
WORD  dummy; 


WORD  ‘image; 

}  rs_imdope [ ]  =  { 

0,  & IMAGO [0] } ; 

♦define  NUM_STRINGS  4 
♦define  NUM_FRSTR  0 
♦define  NUM_IMAGES  1 
♦define  NUM_BB  1 
♦define  NUM_FRIMG  0 
♦define  NUM_IB  0 
♦define  NUM_TI  0 
♦define  NUM_OBS  6 
♦define  NUM_TREE  1 

BYTE  pname [ ]  =  "SAMPLE.RSC"; 


End  Listing  Two 


Listing  Three 

/*  mevent.h  -  define  structure  for  GEM  evnt_event()  */ 

typedef  struct  mevent 

( 

UWORD  eflags;  /*  events  to  wait  on  */ 

UWORD  e_bclk;  /*  num  button  clicks  */ 

UWORD  e_bmsk;  /*  which  mouse  buttons  */ 

UWORD  e_bst;  /*  button  up  or  down  */ 

UWORD  e_mlflags;  /*  return  on  entry  or  exit  */ 

GRECT  e_ml;  /*  rect  1  x, y, width, height  */ 

UWORD  e_m2flags;  /*  return  on  entry  or  exit  */ 

GRECT  e_m2;  /*  rect  2  x, y, width, height  */ 

LONG  e_mepbuf;  /*  message  buffer  pointer  */ 

ULONG  e_time;  /*  time  to  wait  (ms)  */ 

WORD  e_mx;  /*  return  x  */ 

WORD  e_my;  /*  return  y  */ 

UWORD  e_mb;  /*  return  which  buttons  */ 

UWORD  e_ks;  /*  return  kb  state  */ 

UWORD  e_kr;  /*  return  kb  code  */ 

UWORD  e_br;  /*  return  num  button  clicks  */ 

CHAR  e_reserved[24] ;  /*  for  system  use  */ 

}  MEVENT; 

WORD  evnt_event (  MEVENT  *  ); 


End  Listing  Three 


Listing  Four 

MEVENT  ev_str; 

ev_str .e_f lags  =  E_KEYBD  |  E_TIMER; 
ev_str .e_time  =  10000L;  /*  in  milliseconds  */ 

retflags  =  evntevent (  iev_str  ); 
if  (  ret  flags  &  E  KEYBD  ) 

{ 

/*  The  user  pressed  a  key: 

Key  code  of  key  pressed  returned  in  ev_str.e_kr; 

State  of  shift  and  control  keys  in  ev_str.e_ks  */ 

} 

if (  retflags  &  ETIMER  ) 

< 

/*  10,000  milliseconds  have  elapsed  since  the  call 
*/ 

} 


End  Listings 
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Listing  One  (Text  begins  on  page  55.) 

//  DIRPATH . HPP  Copyright  1988  by  John  M.  Dlugosz 

struct  dirpath  { 
char  drive [3]; 
char  path [65]; 
char  base [9]; 
char  ext [5]; 

void  operator«  (char  const*name);  //throw  a  name  into  the  structure 
void  operator»  (char  *name);  //extract  name  from  structure 
dirpath(char  const*  name)  |*this  «  name;) 

dirpath (char  const*  d,  char  const*  p,  char  const*  b,  char  const*  e) 
(strcpy (drive, d) ; strcpy (path,p) ; strcpy (base,b) ; strcpy (ext, e) ; ) 
dirpath  ()  {) 

}; 


End  Listing  One 

Listing  Two 


//  example  using  dirpath 
//by  John  M.  Dlugosz 

♦include  <stream.hpp> 

♦include  <string.h> 

♦include  <dirpath.hpp> 

char  infile[67],  outfile[67); 

void  checkfiles  (char  const*  name) 

(  /*  find  input  and  output  filenames  */ 

dirpath  d  (name); 

if  (*d.ext  ==  '\0')  //supply  default  extension  for  input  file 
strcpy (d.exe,  ".C");  //notice  dot  in  included 
d  »  infile; 
strcpy  (d.ext,  ".OBJ"); 
d  »  outfile; 

) 


End  Listing  Two 

Listing  Three 

File:  DIRPATH. CPP 

Copyright  1988  by  John  M.  Dlugosz,  all  rights  reserved 
parse  and  combine  file  names 
*****************************************************/ 

//  you  must  define  NULL  for  your  compiler.  Most  have  a  way  of 
//  checking  the  model  being  compiled  under. 

♦ifdef  LPTR 
♦define  NULL  OL 
♦else 

♦define  NULL  0 
♦endif 

♦include  <string.h> 

♦include  "dirpath . hpp" 

static  void  copy  (char  *dest,  char  const*  source,  char  const*  const 

limit,  int  count) 

( 

while  (count —  &&  source  <=  limit)  *dest++  =  *source++; 

*dest=  '\0'; 

} 

/*  /\/\/\/\/\/\/\/\/\/\/\/W\/\/\/\A/\/\  */ 

void  dirpath:  :operator«  (char  const*  name) 

I 

//takes  a  pathname  and  splits  it  up  into  its  components. 

//any  or  all  of  the  components  may  be  missing. 

//first,  locate  DRIVE  letter 
if  (strlen (name)  >=  2  &&  name [1] ==' : ' )  { 
drive [0]=  name(0] ; 
drive [1]=  '  ; 

drive [2] =  '\0'; 
name  +=  2;  } 

else  drive [0]=  '  \0';  //no  drive  found 

// locate  last  slash  and  dot 
char  *p; 

char  *last_slash=  NULL,  *dot=  NULL; 
for  (p=  name;  *p;  p++) 

if  (*p  ==  '\V  II  *p  ==  '/')  last_slash=  p; 
else  if  (*p  ==  '.')  dot=  p; 

//  p  now  points  to  the  \0  at  the  end  of  the  string 

if  (last_slash)  {  //path  exists,  copy  up  to  and  including  the  last  slash 
copy  (path,  name,  last_slash,  64); 
name=  last_slash+l; 

) 

else  *path=  '\0'; 

if  (dot)  {  //break  int  base  and  ext 
copy  (base,  name,  dot-1,  8); 
copy  (ext,  dot,  p-1,  4); 

) 

else  {  //rest  of  string  is  base  name,  no  ext. 
copy  (base,  name,  p-1,  8)  ; 

*ext=  ' \0' ; 

) 


/*  /\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\  */ 


void  dirpath:  :operator»  (char  *name) 

{ 

//concatenate  the  parts  together  into  a  full  name. 

//the  name  parameter  better  be  long  enough, 
if  (*drive)  { 

*name++  =  *drive; 

*name++  =  ) 

if  (*path)  { 

strcpy  (name,  path); 

name  +=  strlen  (name) ; 

if  (name[-l)  !=  '/'  &&  name[-l]  !=  '\\') 

*name++  =  '\V; 

) 

strcpy  (name,  base); 
if  (*ext)  ( 

if  (*ext  !=  '.')  strcat  (name,"."); 
strcat  (name,  ext); 

) 

)  End  Listing  Three 

listing  Four 


//  DIRSCAN .  HPP  Copyright  1988  by  John  M.  Dlugosz 

/*  these  values  for  attribute  parameter  in  constructor 
are  passed  through  to  DOS's  function  4e  */ 

♦define  fa  READ  ONLY  0x01 


♦define  fa_HIDDEN  0x02 
♦define  fa_SYSTEM  0x04 
♦define  fa_LABEL  0x08 
♦define  fa_DIR  0x10 
♦define  fa  ARCHIVE  0x20 


class  dirdata  { 

char  reserved [21 ] ; 
public: 

unsigned  char  attribute; 
unsigned  time; 
unsigned  date; 
unsigned  long  size; 
char  name [13]; 

); 

class  dir_scanner  { 

char  **goodlist,  **badlist; 
int  goodcount,  badcount; 
dir_data  current_entry; 
bool  done; 
bool  firsttime; 

void  near  buildlists  (char  *filespec) ; 
bool  near  multi_match () ; 
public: 

dir_scanner  (char  *filespec,  unsigned  attributed); 
dir_scanner () ; 

operator  int ( ) ;  //look  up  next  entry,  return  1. 

If  no  next,  return  0. 

dir_datas  operator()  ()  (return  current_entry; }  //fetch  current 

entry 

)  ; 


End  Listing  Four 


Listing  Five 


File:  DIRSCAN. CPP 

Copyright  1988  by  John  M.  Dlugosz,  all  rights  reserved 
implementation  of  class  dir_scanner,  which  does 
enhanced  file  matching  in  a  directory  list. 

enum  bool  (FALSE, TRUE) ; 

♦define  NULL  0L  //define  NULL  properly  for  your  compiler  and  model 
♦include  <string.h> 

♦include  "dirscan . hpp" 

//  these  two  function  in  assembly  language  (file  SCANHELP . ASM) 
extern  int  dirscan_f indf irst  (char  const  far  *name,  unsigned  attribute, 

dir_data  const  far  *dta) ; 

extern  int  dirscan_f indnext  (dir_data  const  far  *dta) ; 

/*  l\l\/\l\l\l\l\/\l\l\/\l\l\/\l\l\l\l\/\l\  */ 

static  void  near  dir_scanner : :buildlists  (char  ‘pattern) 

( 

goodcount=  badcount=  0; 

for  (char  *p=  pattern;;)  (  //  pass  1  —  count  them 

while  (*p  ==  '  '  ||  *p  ==  '\t')  p++; 
if  (*p  ==  '\0')  break; 
if  (*p  ==  ';')  badcount ++; 
else  goodcount++; 

do  p++;  while  (*p  !=  '  '  &&  *p  !=  '\t'  &&  *p  !=  &&  *p  !=  '+' 

&&  *p  ! =  ' \ 0 ' ) ; 

) 

typedef  char*  POINTER;  III  need  a  type  name  so  I  can  use  NEW 
goodlist=  new  POINTER  [goodcount];  //  allocate  arrays 
badlist=  new  POINTER  [badcount]; 
int  gcount=0,  bcount=  0; 

/*  I  remember  the  location  of  the  end  of  the  substring  in  lastbreak. 
After  parsing  the  next  string,  I  stick  a  ' \0'  here.  I  do  this 
one  string  behind  because  it  will  overwrite  the  '+'  or  */ 

char  *lastbreak=  NULL;  //NULL  means  none  found  yet 

(continued  on  page  100) 
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Listing  Five  (Listing  continued,  text  begins  on  page  55.) 

for  <;;)  {  //  pass  2  —  chop  it  up 

while  {‘pattern  ==  '  '  ||  ‘pattern  ==  'Nt')  pattern++; 

/*  Embedded  whitespace  tolerated.  You  can  even  omit  the  '+'  and 
seperate  names  with  spaces.  But  if  you  do  have  a  '+' 

or  ';',  it  must  immediately  preceed  the  name  */ 
if  (‘pattern  ==  'NO')  break;  //end  of  the  string 
if  (‘pattern  ==  ';')  //add  to  BAD  list 
badlist [bcount++] =  ++pattern; 
else  {  //add  to  GOOD  list 

if  (‘pattern  ==  '+')  pattern++; 
goodlist [gcount++] =  pattern;  } 
if  (lastbreak)  ‘lastbreak-  'NO'; 

while  (!  (*pattern=='  '  ||  *pattern==' \t'  I  I  ‘pattern--' NO'  II 
‘pattern—';'  II  *pattern==' +' ) )  pattern++; 
lastbreak=  pattern; 

} 


/*  A/N/N/N/N/N/N/N/N/N/N/N/N/N/N/N/N/N/N/N  */ 

dirscanner : :dir_scanner  (char  ‘filespec,  unsigned  attribute) 

( 

char  dir[67],  *lastslash=  NULL,  *p; 
int  max=  63; 

firsttime=  TRUE; 

//  seperate  the  path  information  from  the  search  specification 
for  (p=  filespec;  ‘p;  p++) 

if  (*p  —  II  *p  ==  '  / '  II  *p  —  'NN')  lastslash=  p; 

//  notice  that  both  \  and  /  are  acceptable. 
p=  dir; 

if  (lastslash)  //copy  directory  information 

//  if  it  is  too  long,  it  is  truncated.  You  might  want  to  check  and 
//  return  an  error  if  this  happens  (max  will  be  -1  after  the  loop) 
while  (max —  &&  filespec  <=  lastslash)  *p++=  *filespec++; 

//  if  it  is  too  long,  it  is  truncated.  You  might  want  to  check  and 
//  return  an  error  if  this  happens  (max  will  be  -1  after  the  loop) 
strcpy  (p,  "*.*"); 

buildlists  (lastslash  ?  lastslash+1  :  filespec); 

/*  the  first  name  is  read  differently  then  the  others.  So  read  the 
first  here,  and  set  firsttime  so  the  advance  and  test  function 
will  not  advance.  */ 

if  (0  !=  dirscan_findf irst (dir,  attribute,  &current_entry) )  done-  TRUE; 
else  { 

done-  FALSE; 
return;  } 


/*  /N/N/N/N/N/N/N/N/N/N/N/N/N/N/N/N/N/N/N/N  */ 

dir_scanner: :dir_scanner () 

{ 

delete  goodlist; 
delete  badlist; 

) 

/*  AAAAAAAAAAAAAAAAAA/NA  */ 

static  bool  near  matchname  (char  const*  pattern,  char  const*  name) 
( 

while  (‘pattern)  { 

if  ((‘pattern  ==  ‘name)  ||  (‘pattern  ==  '?'  &&  ‘name))  { 
pattern++; 
name++; 

) 

else  if  (‘pattern  --'*')  { 
for  <;;)  { 

if  (matchname  (pattern+1,  name))  return  TRUE; 
if  (‘name)  name++; 
else  return  FALSE; 

} 

) 

else  return  FALSE; 

} 

return  ‘name  ==  'NO'; 


/*  /NA/N/N/N/N/N/N/N/N/N/N/N/N/N/N/N/N/N/N  */ 

static  char  *  near  normalize  (char  const*  pattern) 

{ 

static  char  buf [16); 
if  (‘pattern  =='.')  { 

//  if  no  basename,  insert  '*'.  i.e.  ".EXE”  =>  "*.EXE” 
buf [0] =  '*'; 

strcpy  (buf+1,  pattern); 
return  buf;  ) 

else  if  (! strchr (pattern, '.') )  { 

//  if  no  dot,  extension  of  '  *' .  i.e.  "FOO"  =>  "FOO.*" 
strcpy  (buf,  pattern) ; 
strcat  (buf,  ".*"); 
return  buf;  ) 
return  pattern; 

} 

/*  /N/N/N/N/N/N/N/N/N/N/N/N/N/N/N/N/N/N/N/N  */ 

static  void  near  check_for_dot  (char*  name) 

{  /‘if  name  does  not  contain  a  dot,  add  one  to  the  end  */ 
while  (‘name) 

if  (‘name  ==  '.')  return; 
else  name++; 

*name++  =  '  . ' ; 

‘name-  'NO'; 

) 

/*  /N/N/N/N/N/N/N/N/N/V/N/N/N/N/N/N/N/N/N/N  */ 

static  bool  near  dir_scanner: :multi_match ( ) 

{ 

/*  a  match  occurs  if  the  name  does  not  match  anything  on  the  badlist. 


and  does  match  something  on  the  goodlist  */ 
check_for_dot  (current_entry . name) ; 
int  count; 

for  (count-  0;  count  <  badcount;  count++) 

if  (matchname  (normalize (badlist [count ]) ,  current_entry . name) ) 

return  FALSE; 

for  (count-  0;  count  <  goodcount;  count++) 

if  (matchname  (normalize (goodlist [count] ) ,  current_entry.name) ) 

return  TRUE; 

return  FALSE; 

} 

/*  /N/N/N/N/N/N/N/N/N/N/N/N/N/N/N/N/N/N/N/N  */ 

dir_scanner: : operator  int () 

{  /*  this  is  the  advance  and  test  function  */ 

while  (Idone)  { 

if  (! firsttime)  ( 

if  (0  !=  dirscan_f indnext  (&current_entry) )  { 
done-  TRUE; 
return  FALSE;  } 

) 

else  firsttime-  FALSE; 
if  (multi_match () )  return  TRUE; 

) 

return  FALSE; 

} 

/*  /N/N/N/N/N/N/N/N/N/N/N/N/N/N/N/N/N/N/N/N  */  End  Listing  Five 


Listing  Six 

;SCANHELP .ASM  Copyright  1988  by  John  M.  DLugosz,  all  rights  reserved 
; extern  int  dirscanfindfirst  { 

;  char  const  far  ‘name,  unsigned  attribute,  dir_data  const 

;  far  *dta) ; 

;extern  int  dirscan_f indnext  (dir_data  const  far  *dta); 

.MODEL  LARGE, C 

;  to  adapt  to  any  memory  model,  make  sure  the  RET  is  the  right  kind, 

;  and  that  the  parameters  are  accessed  properly  on  the  stack  frame. 

;  In  MASM  5.1,  just  change  the  preceeding  line.  LARGE  and  SMALL 
;  versions  are  enogth  to  service  any  model,  because  the  data  size 
;  does  not  matter  thanks  to  the  prototypes, 


.CODE 

dirscan_findfirst  proc  uses  DS,  fname:DWORD,  attribute : WORD,  dta:DW0RD 
Ids  DX, dta 
mov  AH, lah 

int  21h  ;set  disk  transfer  area 

Ids  DX, fname 

mov  CX, attribute 

mov  AH, 4 eh 

int  21h  ;find  it. 

jc  error 

xor  AX, AX  ; return  0  for  ok. 
error:  ;error  code  is  already  in  AX 

ret 

dirscan_findfirst  endp 


dirscan_f indnext  proc  uses  DS,  dta: DWORD 
Ids  DX,dta 
mov  AH, lah 

int  21h  ;set  disk  transfer  area 

mov  AH,4fh 

int  21h  ;find  it. 

jc  error 

xor  AX, AX 

error:  ; error  code  already  in  AX 
ret 

dirscan_findnext  endp 


End  Listing  Six 


Listing  Seven 

//  Version  A 

static  bool  near  matchname  (char  const*  pattern,  char  const*  name) 
{ 

if  (‘pattern  —  ' ?' ) 

return  (‘name  !=  'NO'  &&  matchname  (pattern+1,  name+1); 
else  if  (‘pattern  =='*')  ( 
while  (*++name) 

if  (matchname  (pattern+1,  name))  return  TRUE; 
return  FALSE 
} 

else  if  (‘pattern  —  ‘name)  { 

if  (‘pattern  —  'NO')  return  TRUE; 
else  matchname  (pattern+1,  name+1); 

} 

else  return  FALSE; 

) 


//  Version  B  -  apply  tail-end  recursion  elimination 

static  bool  near  matchname  (char  const*  pattern,  char  const*  name) 

{ 

restart : 

if  (‘pattern  =='?')  ( 

if  (!*name)  return  FALSE; 

pattern++; 

name++; 
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goto  restart; 

} 

else  if  (‘pattern  =='*')  { 
while  (*++name) 

if  (matchname  (pattern+1,  name) )  return  TRUE; 
return  FALSE 
} 

else  if  (‘pattern  !=  ‘name)  return  FALSE 
else  if  (‘pattern  ==  '\0')  return  TRUE; 
else  { 

pattern++; 

name++; 

goto  restart; 

} 


//  Version  C  -  get  rid  of  goto's 

static  bool  near  matchname  (char  const*  pattern,  char  const*  name) 
( 

while  (‘pattern)  { 

if  (‘pattern  ==  ‘name)  ||  (‘pattern  ==  'V  &&  ‘name)  ( 
pattern++; 
name++; 

) 

else  if  (‘pattern  =='*')  ( 
for  (;;)  { 

if  (matchname  (pattern+1,  name)  return  TRUE; 
if  (‘name)  name++; 
else  return  FALSE; 


else  return  FALSE; 
} 

return  ‘name  ==  '\0'; 

) 


End  Listing  Seven 


Listing  Eight 

File:  MATCH. CPP 

Copyright  1988  by  John  M.  Dlugosz,  all  rights  reserved 
demonstration  of  dir_scanner 


enum  bool  (FALSE,  TRUE); 
finclude  <stream.hpp> 

# include  "dirscan.hpp" 

# include  <ctype.h>  //toupperO  needed 

/*  The  nl  macro  might  already  be  in  stream. hpp.  If  it  is  not, 
you  might  want  to  add  it.  Otherwise,  define  it  here.  */ 
#define  nl  <<  "\n" 

/*  /\A/\/\/\A/\/W\/\/\/\/\A/\/W\/\  */ 

ostream&  operator«  (ostreamS  o,  dir_data&  d) 

{ 

/*  let  output  streams  handle  directory  entries.  This  just  prints 
the  name,  but  you  might  want  to  enhance  it  to  print  the  date, 
size,  etc.  */ 
o  «  d.name; 
return  o; 

) 

/*  AAAAAAAAAAAAAAAAAAAA  */ 

void  upcase  (char*  s) 

{  /*  convert  string  to  all  caps  */ 

while  (*s)  { 

*s=  toupper  (*s); 
s++; 

) 

) 

/*  AAAAAAAAAAAAAAAAAAAA  */ 


main  (int  argc,  char*  argv[]) 

{ 

char  s  [80] ; 
dirdata  f; 

if  (argc  <  2)  {  //prompt  user 
cout  «  "enter  search  request: 
cin  >>  s; 
cout  nl; 


else  strcpy  (s,  argv[l]);  //use  command  line  if  present 
//  the  dir_scanner  is  assumes  parameter  is  ALL  CAPS 
upcase  (s) ; 

dirscanner  d  (s);  //notice  second  parameter  is  missing. 


int  number=  0; 
while  (d)  { 
f=  d ( ) ; 
number ++; 
cout  «  f  nl; 


//count  how  many  found 
//advance  and  test  function  called  here 
//fetch  function  called 
//count  it 
//display  it 


cout  <<  number  «  "  files  found."  nl; 
} 


so  default 
is  used. 


End  listings 
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Listing  One  (Text  begins  on  page  70.) 


XVT  "Hello  World" 


♦include  "xvt.h" 
♦include  "xvtmenu.h" 


/*  standard  XVT  header  */ 

/*  standard  XVT  menu  tags  */ 


init_mgrs ( ) 

< 

InitGraf (&thePort) ; 
InitFonts () ; 

FlushEvents (everyEvent,  0) ; 
InitWindows ()  ; 

InitCursor () ; 


Required  application  setup  structure. 


APPL_SETUP  appl_setup  =  { 

0, 

0, 

"Hello  World!", 
W_D0C, 

TRUE, 

FALSE, 

FALSE, 

TRUE, 

FALSE, 

FALSE 


/*  menu  bar  resource  ID  (use  default)  */ 

/*  about  box  resource  ID  (use  default)  */ 
/*  application's  name  */ 

/*  type  of  initial  window  */ 

/*  size  box  on  initial  window?  */ 

/*  vert,  scroll  bar  on  initial  window?  */ 
/*  horz.  scroll  bar  on  initial  window?  */ 
/*  close  box  on  initial  window?  */ 

/*  want  std.  font  menu?  (includes  sizes)  * 
/*  want  std.  style  menu?  */ 


set_parameters () 

{ 

drag_rect  =  thePort->portRect; 

SetRect (&grow_bounds,  64,  64,  thePort->portRect . right, 
thePort->portRect .bottom) ; 

) 

/****************************************************** 
make_window () 

{ 

hello_window  =  GetNewWindow(128,6w_record,-lL) ; 


eventloop () 


Main  application  entry  point. 


void  main_event (win,  ep) 
WINDOW  win; 

EVENT  *ep; 


switch (ep->type) 


case  EJJPDATE: 

get_client_rect (win, &rct) ; 
set_pen (4white_pen) ; 
draw_rect (&rct) ; 

draw_text (10, 100,  "Hello  World!", 
break; 

case  E_COMMAND : 

if  (ep->v. cmd.tag  ==  M_FILE_QUIT) 
terminate ( ) ; 
break; 

case  E_CLOSE: 

terminate () ; 
break; 

case  E_QUIT : 

if  (ep->v. query) 
quit_OK ( ) ; 

else 

terminate () ; 

break; 


Application  cleanup.  Nothing  to  ■ 


void  appl_cleanup  () 

{ 


Application  initialization. 


BOOLEAN  appl_init() 

( 

return (TRUE) ; 


End  Listing  One 


EventRecord  event; 

while  (1) 

(SystemTask () ; 

GetNextEvent (everyEvent,  &event) ; 
switch (event . what ) 

{ 

case  mouseDown: 

do_mouse_down (Sevent) ; 
break; 

case  updateEvt: 

do_update(&event) ; 
break; 

case  activateEvt: 

do_activate (&event) ; 
break; 

default : 
break; 


do_mouse_down (eventp) 

EventRecord  *eventp; 

( 

WindowPtr  mouse_window; 

switch (FindWindow  <mk_long (eventp->where) , &mouse_window) ) 

{ 

case  inContent: 

if  (mouse_window  !=  FrontWindow () ) 

SelectWindow(mouse_window) ; 
break; 

case  inDrag: 

DragWindow (mouse_window,  mk_long (eventp->where) , &drag_rect ) ; 
break; 

case  inGrow: 

grow_window (mouse_window,  mk_long (eventp->where) ,  &drag_rect); 
break; 

case  inGoAway: 

if  (TrackGoAway (mouse_window, mk_long (eventp->where) ) ) 
finish  () ; 
break; 

default : 
break; 


listing  Two 


do_update (event) 

EventRecord  ‘event; 


*  Mac  "Hello  World" 

********************************************************************* 
♦include  <QuickDraw.h> 

♦include  <WindowMgr . h> 

♦include  <ControlMgr . h> 

♦include  <EventMgr.h> 

♦include  <DeskMgr.h> 

♦include  <MenuMgr.h> 

GrafPtr  w_port; 

Rect  drag_rect,  grow_bounds; 

WindowRecord  w_record;  /*  storage  for  a  window's  information  */ 

WindowPtr  hello_window;  /*  a  pointer  to  that  storage  */ 

♦define  mklong(x)  (‘((long  *)&(x))) 

main ( ) 

( 

init_process () ;  /*  do  all  the  initialization  */ 

make_window ( ) ; 
event_loop () ; 


init_process ( ) 


init_mgrs ( )  ; 
set_parameters ( ) ; 


GrafPtr  save_graf; 

WindowPtr  updatewindow; 

if  (FindWindow (mk_long (event->where) , &update_window)  !=  inSysWindow) 
(if  (update_window  ==  hello_window) 

(GetPort (&save_graf ) ; 

SetPort (update_window) ; 

BeginUpdate (updatewindow) ; 

ClipRect (&update_window->portRect) ; 

EraseRect (&update_window->portRect) ; 

DrawGrowIcon (update_window) ; 
draw_content (update_window) ; 

EndUpdate (update_window) ; 

SetPort (save_graf ) ; 

) 


do_activate (event) 

EventRecord  ‘event; 

{ 

WindowPtr  event_window  =  (WindowPtr) event->message; 
if  (event_window  ==  hello_window) 

(DrawGrowIcon (event_window) ; 
if  (event->modif iers  &  1) 

SetPort (event_window)  ; 

} 


(continued  on  page  104) 
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Listing  Two  (Listing  continued,  text  begins  on  page  70.) 

/**********************************************************************/ 
grow_window (window, mouse_point ) 

WindowPtr  window; 

Point  mouse_point; 

{ 

long  new_bounds; 
inval_bars (window) ; 

new_bounds  =  GrowWindow (window,  mk_long (mouse_point) , &grow_bounds) ; 
if  (0  ==  new_bounds) 
return; 

SizeWindow (window, LoWord (new_bounds) , HiWord (new_bounds) ,TRUE) ; 
inval_bars (window) ; 

) 

/**********************************************************************/ 
inval_bars (window) 

WindowPtr  window; 

{ 

Rect  temp_rect,  port_rect; 
port_rect  =  window-- >portRect; 

SetRect  (&temp_rect,port_rect .  left,port_rect  .bottom-1 6, port_rect . 

right, port_rect .bottom) ; 

InvalRect (&temp_rect) ; 

SetRect (4temp_rect, port_rect . right-16, port_rect . top, port_rect . 

right, port_rect .bottom) ; 

InvalRect ( &temp_rect ) ; 

:************************************************/ 


/***************************** 
draw_content (window) 

WindowPtr  window; 

{ 

MoveTo (100,  100) ; 

Drawstring ("\pHello  World!"); 

) 

/***************************** 

finishO 

{ 

exit (0) ; 

} 


End  Listing  Two 


if(  !  RegisterClass (  &WndClass  )  ) 
return  FALSE; 


else 

( 

GetlnstanceData (hPrevInst,  szClass,  sizeof (szClass) ) ; 
GetlnstanceData (hPrevInst,  szTitle,  sizeof (szTitle) ) ; 

) 

hWnd  =  CreateWindow ( 

szClass,  /*  Class  name  */ 

szTitle,  /*  Window  title  */ 

WS_OVERLAPPEDWINDOW,  /*  window  style  */ 

CW_USEDEFAULT ,  /*  x  */ 

0,  /*  y  */ 

CWJJSEDEFAULT,  /*  x  width  */ 

0,  /*  y  width  */ 

NULL,  /*  Parent  hWnd  (none  for  top-level)  */ 

NULL,  /*  Menu  handle  */ 

hlnst,  /*  Owning  instance  handle  */ 

NULL  /*  Parameter  to  pass  in  WM_CREATE  (none)  */ 

)  ; 

ShowWindow(  hWnd,  nCmdShow  ); 

UpdateWindow(  hWnd  ); 

return  TRUE; 

) 

/******************************»**********.*.,.****. ********************* 
Process  the  messages 

***********************»***********************************************/ 
long  FAR  PASCAL  WndProc (hWnd,  wMessage,  wParam,  IParam) 

HWND  hWnd; 

WORD  wMessage,  wParam; 

LONG  IParam; 

(PAINTSTRUCT  ps; 

switch  (wMessage) 

(case  WM_PAINT : 

BeginPaint (hWnd, &ps) ; 

TextOut (ps.hdc, 10, 100, "Hello  World! ",  12) ; 

EndPaint (hWnd, ips) ; 
break; 
default: 

return  DefWindowProc (  hWnd,  wMessage,  wParam,  IParam  ); 
break; 

) 

return  0L; 

I 


Listing  Three 

End  listings 

♦include  <windows.h> 

♦include  "hello. h" 

BOOL  NEAR  Initialize  (  HANDLE  hlnst,  HANDLE  hPrevInst,  int  nCmdShow  ); 

long  FAR  PASCAL  WndProc  (  HWND  hWnd,  WORD  wMessage,  WORD  wParam,  LONG 

IParam) ; 

static  char  szClass [40]; 
static  char  szTitle [40]; 

int  PASCAL  WinMain (  hlnst,  hPrevInst,  IpszCmdLine,  nCmdShow  ) 

HANDLE  hlnst;  /*  Our  instance  handle  */ 

HANDLE  hPrevInst;  /*  Previous  instance  of  this  application 

*/ 

LPSTR  IpszCmdLine;  /*  Pointer  to  any  command  line  params  */ 

int  nCmdShow;  /*  Parameter  to  use  for  first 

ShowWindow  */ 

{ 

MSG  msg;  /*  Message  structure  */ 

if(  !  Initialize  (  hlnst,  hPrevInst,  nCmdShow  )  ) 
return  FALSE; 

while!  GetMessage(  fimsg,  NULL,  0,  0  )  )  { 

TranslateMessage (  imsg  ); 

DispatchMessage (  Smsg  ); 

) 

return  msg. wParam; 

) 

/************************************************************************ 

Initialize  the  application. 

Returns  TRUE  if  initialization  succeeded,  FALSE  if  failed. 

A***********************************************************************/ 

BOOL  NEAR  Initialize  (  hlnst,  hPrevInst,  nCmdShow  ) 

HANDLE  hlnst;  /*  Our  Instance  handle  */ 

HANDLE  hPrevInst;  /*  Previous  instance  handle,  0  if  first  */ 

int  nCmdShow;  /*  Parameter  from  WinMain  for  ShowWindow  */ 

{ 

WNDCLASS  WndClass;  /*  Class  structure  for  RegisterClass  */ 

HWND  hWnd;  /*  The  window  handle  */ 

HMENU  hMenu;  /*  Handle  to  the  (system)  menu  V 

if (  !  hPrevInst  ) 

{ 

LoadString(  hlnst,  IDS_CLASS,  szClass,  sizeof (szClass)  ); 

Loadstring (  hlnst,  IDS_TITLE,  szTitle,  sizeof (szTitle)  ); 

WndClass. style  =  CS_HREDRAW  |  CS_VREDRAW; 

WndClass .lpfnWndProc  =  WndProc; 

WndClass. cbClsExtra  =  0; 

WndClass. cbWndExtra  =  0; 

WndClass. hlnstance  =  hlnst; 

WndClass. hlcon  =  LoadIcon(  NULL,  IDI_APPLICATION  ); 

WndClass. hCursor  =  LoadCursor(  NULL,  IDC_ARROW  ); 

WndClass .hbrBackground  =  GetStockObject (WHITE_BRUSH) ; 

WndClass . IpszMenuName  =  NULL; 

WndClass. IpszClassName  =  szClass; 
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Is  Multiple 
Inheritance 
Necessary ? 


Amoebas  at  the  start 
Were  not  complex; 

They  tore  themselves  apart 
And  started  sex. 

— Arthur  Guiterman 

In  my  last  column  in  February,  I  re¬ 
ported  on  my  interviews  with 
Chuck  Duff  of  The  Whitewater 
Group  and  Jim  Anderson  of  Digi- 
talk,  two  proponents  of  a  more-or-less- 
pure  object-oriented  programming  para¬ 
digm.  Their  loyalty  to  this  more  or  less 
pure  paradigm  is  consistent  with  the 
fact  that  it’s  the  paradigm  to  which  each 
of  them  has  hitched  the  chariot  of  his 
reputation  and  personal  fortune.  Both 
Actor  (Duffs  baby)  and  Smalltalk/V  (An¬ 
derson’s)  are  more  or  less  pure  object- 
oriented  languages.  It  is  plausible  that 
others,  whose  chariots  are  otherwise 
harnessed,  might  disagree  with  some  of 
Duffs  and  Anderson’s  views,  and  such 
is  the  case.  That’s  what  makes  chariot 
races. 

Both  Anderson  and  Duff  express 
strong  reservations  about  multiple  in¬ 
heritance,  the  capability  for  an  object  to 
inherit  from  more  than  one  ancestor. 
Actually,  Smalltalk/V  has  the  facility  hid¬ 
den  within  it,  lacking  only  a  user  inter¬ 
face  to  make  it  available  to  the  pro¬ 
grammer;  and  there’s  a  multiple-inherit¬ 
ing  Actor  in  the  wings.  But  Anderson 
and  Duff  seem  less  than  enthusiastic 
about  biting  into  the  apple  of  multiple 
inheritance.  There’s  the  matter  of  name 
clashes,  for  instance.  As  Duff  explains 
it,  “there  are  cases  in  which  two  multiple- 
inherited  classes  with  instance  variables  — 
with  the  same  name  each  — may  want 
to  preserve  their  own  copy  of  that  in- 


Michael  Swaine 


stance  variable,  and  there  are  equally 
viable  cases  in  which  they  want  to 
share  it.”  There  is  no  algorithm  in  exis¬ 
tence  for  resolving  such  conflicts. 

When  an  object  begets  new  objects 
all  by  itself,  things  are  simpler.  Multiple 
inheritance  is  mysterious  and  messy.  If 
its  lure  is  strong,  there  may  be  wisdom 
in  resisting  temptation.  “Dragons  lie 


there,”  Duff  says,  expressing  a  diffi¬ 
dence  perhaps  appropriate  for  a  para¬ 
digm  still  in  its  adolescence. 

I  don’t  mean  to  put  down  adoles¬ 
cence,  or  its  preoccupations.  After  all,  I 
just  wrote  a  book  about  HyperTalk,  the 
semi-object-oriented  language  of  a  prod¬ 
uct  whose  creator  has  called  it  a  “soft¬ 
ware  erector  set.” 

But  there  comes  an  end  to  ado¬ 
lescence. 

The  French  Have  a  Word  for  It 

Unlike  Duff  and  Anderson,  Bertrand 
Meyer  has  gone  all  the  way.  Eiffel  is  the 
name  of  Meyer’s  object-oriented  pro¬ 
gramming  language,  which  incorporates 
multiple  inheritance.  In  fact,  Eiffel  de¬ 
pends  intimately  on  multiple  inheritance 
in  its  own  structure.  'Wide  Duff  and 
Anderson  wonder  if  the  customers  who 
ask  them  about  multiple  inheritance  are 
just  indulging  in  ivory-tower  fantasy, 
for  Meyer  it  is  a  fact  of  life. 

In  the  November/December  1988  is¬ 
sue  of  The  Journal  of  Object-Oriented 
Programming ,  Meyer  presents  the  view 
from  the  Eiffel  Tower: 

“Whenever  you  talk  about  multiple 
inheritance,  someone  is  bound  to  ask 
sooner  or  later  (usually  sooner)  what 
happens  in  the  case  of  name  clashes  — 
identically  named  features  in  two  or 
more  parent  classes.  No  doubt  the  ques¬ 
tion  is  legitimate,  but  the  gravity  with 
which  it  is  asked  — as  if  it  were  a  deep 
conceptual  issue  — has  been  an  unend¬ 
ing  source  of  bewilderment  to  me.  I 
believe  it  is  one  of  these  cases  in  which, 
if  you  only  take  a  minute  or  two  to  pose 
the  problem  cleanly,  the  solution  fol¬ 
lows  immediately. 

“First,  it  is  purely  a  syntactical  prob¬ 
lem,  due  to  conflicting  name  choices.  It 
has  nothing  to  do  with  the  fundamental 
properties  of  the  classes  involved.  Sec¬ 
ond,  nothing  is  wrong  with  the  parents; 
each  is  perfectly  consistent  as  it  stands. 
The  ‘culprit’  is  the  common  heir,  that 
tries  to  combine  two  classes  that  are 
incompatible  as  they  stand.  So  the  heir 
should  also  be  responsible  for  the  solu¬ 
tion.” 

Eiffel’s  solution  is  to  reject  such  am¬ 
biguities  with  a  compiler  error  mes¬ 


sage,  and  to  require  the  programmer 
to  resolve  them,  possibly  by  renaming 
one  or  both  features  ( my_father’s 
_temper,  myjmother’sjeyes).  Duff  has 
asked,  “Do  you  ask  the  programmer  on 
a  case-by-case  basis  to  make  the  resolu¬ 
tion?”  Meyer  obviously  thinks  that’s  a 
reasonable  solution. 

Meyer  says  that  users  of  a  class 
should  not  have  to  know  its  ancestry; 
the  interface  to  the  class  should  be  com¬ 
plete  and  consistent  on  its  own  terms. 
The  simple  expedient  of  appropriate 
renaming  is  enough,  he  says,  to  ensure 
that  name  clashes  don’t  get  in  the  way 
of  this  goal. 

Renaming  is  a  purely  syntactic  busi¬ 
ness,  and  Meyer  admits  that  “the  im¬ 
provement  it  brings.  .  .may  be  labeled  a 
cosmetic  one.”  But  this  is  not,  in  his 
view,  to  dismiss  it  as  trivial.  Meyer  does 
not  disdain  cosmetics. 

In  the  same  column,  Meyer  ridicules 
nonsensical  examples  of  multiple  in¬ 
heritance,  such  as  the  class  apple _p>ie 
inheriting  from  apple  and  pie,  or  class 
airplane  inheriting  from  fuselage  and 
engine,  pointing  out  that  an  apple  pie  is 
not  an  apple  and  an  airplane  is  neither 
a  fuselage  nor  an  engine.  And  he  pre¬ 
sents  some  real  examples  in  which  mul¬ 
tiple  inheritance  seems  called  for.  One 
of  these  is  the  class  window,  which  in 
the  implementation  he  describes,  inher¬ 
its  from  the  classes  rect_shape  and  tree. 
In  this  implementation,  a  window  is  a 
rectangle,  but  it  is  also  a  tree,  with  prop¬ 
erties  such  as  superwindows  and  subwin¬ 
dows  and  facilities  for  adding  and  de¬ 
leting  subwindows.  Meyer’s  description 
of  a  lazy  programmer  putting  together  a 
windowing  system  in  a  day  by  drawing 
on  existing  rect_shape  and  tree  classes 
gives  him  the  opportunity  to  show  the 
need  for  renaming,  even  when  there 
are  no  name  clashes. 

Without  renaming,  the  window  class 
inherits  tree  features  with  all  their  arbo¬ 
real  nomenclature  clinging  to  them.  A 
superwindow  is  called  a  parent_node, 
the  method  for  adding  a  subwindow  is 
called  insert_node.  Anyone  using  this 
class  would  likely  find  this  confusing. 
The  user  of  a  class  has  a  right  to  expect 
it  to  be  complete  and  consistent  on  its 
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(continued  from  page  107) 
own  terms.  Leaving  the  tree  terminol¬ 
ogy  in  the  window  class  is  a  pointless 
flaunting  of  ancestry,  Meyer  believes. 

Meyer  is  not  an  unbiased  reporter, 
but  clearly  one  who  has  tasted  the  fruits 
of  multiple  inheritance  and  cannot  go 
back  to  the  simpler,  more  innocent 
world  of  single  inheritance.  As  he  puts 
it,  “life  without  multiple  inheritance 
would  be.  .  .boring.” 

The  centerspread  of  that  issue  of  The 
Journal  of  Object-Oriented  Program¬ 
ming  is  a  picture  of  the  Eiffel  Tower.  It 
looks  like  something  that  an  adult  erec¬ 
tor  set  would  produce.  I  wonder  why 
Meyer  chose  that  image  to  symbolize 
his  product. 

A  Fig  Leaf  for  Actor 

With  the  end  of  adolescence  comes  a 
desire  for  privacy.  The  matter  is  one 
Chuck  Duff  has  been  giving  a  lot  of 
thought  to  recently. 

“There  is  no  privacy  provision  in  Small¬ 
Talk,”  Duff  says.  There’s  no  privacy 
provision  in  Actor,  either,  but  Duff  and 
the  programmers  at  The  Whitewater 
Group  are  working  on  that.  Duff  thinks 
that  privacy  is  important  to  the  future  of 
object-oriented  programming,  because 
without  it  “once  you  write  a  method,  it 
is  visible  to  all  of  your  descendant 
classes.  The  same  is  true  of  instance 
variables.  Without  more  control  over 
privacy  it  becomes  very  difficult  to  do 
things  like  multiple  inheritance  well.” 

I  suppose  it  would.  Duff  gives 
details: 

“There  are  really  three  categories  of 
things  in  an  object-oriented  system: 
There’s  an  object  that  is  of  the  class  for 
which  a  method  was  originally  written. 
That’s  the  most  local.  Then  there  are 
descendants  of  that  class;  they’re  not  as 
local;  they’re  almost  like  outsiders,  but 
they’re  privileged  outsiders  in  Small¬ 
Talk.  And  then  there  are  objects  of  com¬ 
pletely  different  classes. 

“Any  good  object-oriented  language 
will  make  things  opaque  to  outsiders; 
that’s  the  whole  point,  that’s  the  ab¬ 
stract  data  type  layer.  So  you  can’t  look 
into  the  representation  of  something 
that  you’re  not  related  to.  The  problem 
is  that  in  SmallTalk,  there’s  no  distinc¬ 
tion  between  art  object  of  the  class  and 
an  object  of  a  descendant  class,  so  you 
have  full  visibility  to  all  those  inherited 
methods  and  instance  variables,  and 
that  really  isn’t  appropriate.” 

The  first  level  is  drawing  the  curtains 
against  the  neighbors,  the  second  is 
closing  the  bedroom  door  against  the 
kids.  In  the  interest  of  making  the  code 
more  maintainable,  programmers  at  The 
Whitewater  Group  are  currently  con¬ 
sidering  how  to  implement  that  extra 
layer  of  privacy,  the  bedroom  door. 
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Responsible  Cox 

And  where  are  such  changes  as  multi¬ 
ple  inheritance  and  privacy  taking  object- 
oriented  programming?  Closer  to  the 
ideal  of  a  system  of  software  compo¬ 
nents  that  can  be  reused  to  solve  prob¬ 
lems  similar  to  the  one  for  which  they 
were  first  developed,  and  by  program¬ 
mers  other  than  the  developer,  and  that 
can  be  adapted  to  new  uses  without 
actually  being  modified?  Toward  a  sys¬ 
tem  that  minimizes  the  impact  of 
change  in  software  development?  That 
would  be  nice. 


Cox’s  idea  of  software 
ICs  may  be  a  bigger 
idea  than 
object-oriented 
programming 


One  person  who  has  thought  hard 
about  the  idea  of  reusable  software 
components  is  Brad  Cox,  whose  book 
Object-Oriented  Programming:  An  Evo¬ 
lutionary  Approach  gets  at  it  via  the 
concept  of  the  software  IC.  Although 
his  book  claims  to  be  about  object- 
oriented  programming,  Cox  takes  a  less 
pure  approach  than  Meyer,  Anderson, 
and  Duff,  presenting  all  his  examples  in 
the  hybrid  language  Objective-C  and 
advocating  what  he  calls  a  “hybrid  de¬ 
fense”  against  change.  He  uses  the  word 
“defense”  frequently  in  discussing  soft¬ 
ware  development;  for  Cox,  some  pro¬ 
tection  is  required  if  we  are  to  do  it 
responsibly. 

Cox’s  idea  of  software  ICs  may  be  a 
bigger  idea  than  OOP.  In  spelling  out 
some  of  the  desiderata  of  software  build¬ 
ing  blocks  that  can  serve  as  the  base  for 
a  pyramid  of  software  development,  he 
characterizes  the  pure  object-oriented 
approach  as  building  “armor-plated  ob¬ 
jects  that  communicate  by  sending  mes¬ 
sages.”  He  describes  conventional  pro¬ 
gramming  as  building  “efficient  but  brit¬ 
tle  software  systems,  surrounded  by 
static  defensive  structures  that  protect 
them  from  change.”  Encapsulation,  in¬ 
heritance,  and  dynamic  binding  are  tech¬ 
niques  that  can  overcome  the  deficien¬ 
cies  of  conventional  programming  when 
change  is  necessary.  But  encapsulation 
is  the  base  on  which  a  software  IC 
approach  must  be  built: 

“Encapsulation  is  the  foundation  of 


the  whole  approach.  Its  contribution  is 
restricting  the  effect  of  change  by  plac¬ 
ing  a  wall  of  code  around  each  piece  of 
data.  All  access  to  the  data  is  handled 
by  the  procedures  that  were  put  there 
to  mediate  access  to  the  data.”  Just  like 
IC  design,  “object-oriented  program¬ 
ming  ...  is  a  way  for  suppliers  to 
encapsulate  functionality  for  delivery  to 
consumers.” 

But  just  like  ICs,  such  components 
have  to  be  bug  free.  We’ve  all  encoun¬ 
tered  the  programmer  folk  wisdom  that 
“a  fully  debugged  program  is  one  that 
hasn’t  failed  recently.”  But  we  all  want 
to  believe  that  this  is  just  cynicism,  that 
it  is  possible  to  build  bug-free  software 
components  to  seal  up  black  boxes.  It's 
pleasant  to  imagine  that  a  programming 
system  could  be  built  that  meets  these 
desiderata,  that  by  some  reshuffling  of 
the  bits  we  could  remold  programming 
nearer  to  our  hearts’  desire.  That  we 
could  build  to  last  with  solid  blocks.  At 
the  moment  it  seems  a  poetic  fancy. 

Ah  love!  could  you  and  I  with  Him  conspire 
To  grasp  this  sorry  scheme  of  things  entire, 
Would  not  we  shatter  it  to  bits  — and  then 
Re-mould  it  nearer  to  the  Heart’s  Desire! 

I  suppose  we  would.  But  this  was 
Fitzgerald’s  third  version  of  the  stanza; 
he  continued  to  issue  updates  and  bug 
fixes  over  a  period  of  20  years.  Cox 
points  further  to  the  need  for  assigning 
responsibility  in  human-computer  sys¬ 
tems,  something  that  makes  no  sense 
without  bug  free,  absolutely  reliable  soft¬ 
ware  components.  Is  object-oriented 
programming  the  solution?  “Absolutely 
not,”  Cox  says.  Is  there  a  solution? 

The  German  Has  a  Word  for  It 

“Neuralnetworks.” 

It  was  almost  the  first  word  I  heard 
when  I  picked  up  the  phone  that  morn¬ 
ing  at  I  know  not  what  hour.  Pedants 
will  say  that  “neural  networks”  is  two 
words,  but  it  sounded  like  one  word  to 
me,  which  it  may  be  in  German,  al¬ 
though,  as  the  fog  cleared,  I  realized 
that  the  speaker,  while  indeed  German, 
was  speaking  English. 

It  was  my  friend  JurgenFey,  an  editor 
for  PC  Magazin,  a  German  affiliate  of 
DDJ.  Jurgen’s  English  is  excellent,  but 
some  of  what  he  was  saying  skimmed 
over  my  befogged  head  that  morning. 

I  did  get  it  that  Jurgen  was  putting 
together  a  special  Neural  Networks  is¬ 
sue  of  PC  Magazin.  None  better  for  the 
job,  I  thought,  since  Jurgen  has  been 
deeply  immersed  in  neural  network  re¬ 
search  for  over  a  year  now.  He’s  done 
hardware  and  software  development  in 
support  of  neural  net  systems,  and  has 
read  extensively  in  the  theory  of  neural 
nets.  Jurgenthinks  that  neural  nets  have 
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a  lot  of  potential,  but  no,  he  doesn’t  see 
neural  nets  as  the  ultimate  answer. 

As  part  of  his  work  in  putting  to¬ 
gether  the  special  issue,  he  told  me,  he 
had  ten  calls  to  make  that  day,  all  to  the 
United  States.  For  some  reason,  he  had 
started  with  me.  I’m  sure  the  other  nine 
people  had  to  offer  him  more,  and  I 
have  no  hesitation  in  recommending 
the  issue  to  anyone  interested  in  neural 
networks.  It  should  be  on  the  stands  in 
Germany  in  mid-March,  and  it  can  be 
ordered  through  M&T  Publishing.  “Of 
course,  it’s  all  in  German,”  Jiirgenapolo- 
gized,  with  the  usual  pause  in  which  he 
allows  me  to  reflect  upon  the  linguistic 
shortcomings  of  Americans  in  general 
and  me  in  particular. 

Jurgen  had  no  hesitation  in  recom¬ 
mending  to  me  an  excellent  article  on 
new  neuron  models,  though,  of  course, 
it  was  in  German.  I  think  he  said  that 
he’d  summarize  it  for  me  when  he 
comes  over  in  the  spring.  I  know  he 
said  that  a  remarkable  amount  of  neural 
network  work  (he  must  have  said  it 
better  than  that)  takes  the  McCulloch- 
Pitts  neuron  model  as  gospel.  In  fact, 
McCulloch  and  Pitts  didn’t  present  the 
model  very  seriously  back  in  1943,  and 
anyway,  “something  must  have  hap¬ 
pened  in  the  last  40  years.” 

He’s  right  about  McCulloch  and  Pitts. 

Warren  McCulloch  and  Walter  Pitts 
published  the  seminal  paper  on  neural 
nets  in  “The  Bulletin  of  Mathematical 
Biophysics”  in  1943-  The  paper  was 
titled  “A  logical  calculus  of  the  ideas 
immanent  in  nervous  activity,”  and  it 
really  was  about  logic,  not  biophysics. 
McCulloch  and  Pitts  departed  from  physi¬ 
ological  concerns  to  examine  what  the 
physiology  might  be  doing  — what  the 
hardware  might  be  computing.  To  do 
so,  they  presented  a  mathematical 
model  of  the  neuron. 

The  model  they  presented  described 
the  neuron  as  a  fixed-threshold  binary 
device.  When  its  inputs  exceeded  some 
fixed  threshold  of  activation,  the  neu¬ 
ron  fired,  and  that  was  it.  The  inputs 
could  be  excitatory  or  inhibitory,  but  all 
excitatory  inputs  had  the  same  weight 
and  any  inhibitory  input  had  effectively 
infinite  weight.  If  an  inhibitory  input 
was  active,  the  neuron  did  not  fire. 
Finally,  time  was  quantized,  so  that  a 
neuron  summed  its  inputs  and  re¬ 
sponded  during  a  phase  of  fixed 
length;  neural  activity  was  not,  in  the 
model,  continuous. 

This  model  was  sufficient  to  imple¬ 
ment  the  propositional  calculus,  which 
meant  that  combinations  of  neurons 
could  model  any  finite  (propositional) 
logical  expression.  Since  aspects  of  the 
model  were  based  on  actual  neural  re¬ 
search,  there  were  the  implications  that 
the  brain  could  be  understood  as  we 
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understand  computers,  and  that  com¬ 
puters  could  be  built  along  the  lines  of 
organization  of  the  brain.  A  lot  of  work 
was  predicated  on  the  assumption  that 
the  McCulloch-Pitts  model  of  simple  neu¬ 
rons  connected  in  a  complex  net  was  a 
useful  computational  model.  A  lot  of 
work  was  also  predicated  on  the  as¬ 
sumption  that  their  simple  neuronal 
model  was  correct. 

The  McCulloch-Pitts  neuron  model  is 
now  known  to  be  quite  wrong.  Neu¬ 
rons  are  not  simple  logic  elements. 
Their  action  is  not  all-or-none,  and  they 
are  closer  in  function  to  voltage-to- 
frequency  translators  than  to  logic  de¬ 
vices.  The  simple  model  has  proved 
pregnant  for  computer  science,  spawn¬ 
ing  a  great  deal  of  neural  nets  research 
and  some  early  application  work  that 
seems  promising.  But  for  modeling  the 
brain,  and  possibly  for  some  purely 
computational  purposes  as  well,  these 
new,  truer  models  of  neurons  need  to 
be  examined. 

The  new  models  are  not  simple  bi¬ 
nary  threshold  models.  They  add  pa¬ 
rameters  to  the  old  McCulloch-Pitts 
neuron  and  more  closely  model  real 
neural  response.  There  are  even  analog 
models. 

The  thought  of  building  a  complex 
system  out  of  analog  neurons  made  me 
nervous.  Analog  technology  always 
makes  me  uncomfortable;  if  it’s  ones 
and  zeros  I  have  a  hope  of  under¬ 
standing,  but  analog  is  inherently  in¬ 
scrutable. 

But  the  idea  of  analog  artificial  neu¬ 
rons  was  making  me  more  uncomfort¬ 
able,  and  in  explanation  I  can  only  offer 
Lee  Felsenstein’s  theory.  Felsenstein, 
who  created  the  Sol  and  Osborne  1 
computers  and  the  Pennywhistle  mo¬ 
dem,  and  many  other  things,  has  a  the¬ 
ory.  The  gist  of  it,  as  I  brought  it  up 
through  that  morning’s  fog,  is  that  men 
build  things  because  they  can’t  have 
babies. 

It’s  pointless  to  speculate  about 
whether  or  not  computers  will  ever  be 
intelligent.  No  one  knows  what  “intel¬ 
ligent”  means.  But  it  seems  to  me  likely 
that  computers  will  one  day  grow  be¬ 
yond  their  current  tool  status  to  be¬ 
come  entities  to  be  dealt  with  at  a  level 
of  interaction  now  reserved  for  other 
people.  I  don’t  suppose  we’ll  see  it.  If 
such  artificial  entities  will  one  day  share 
the  earth  with  Man,  their  birth  is  still  a 
long  way  in  the  future. 

But  I  couldn’t  help  wondering  that 
morning  if  the  gestation  period  had 
begun. 

DDJ 
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Last  month  we  added  functions  to 
our  library  of  C  tools  to  support 
serial  ports  and  modems  and  ex¬ 
plained  — ever  so  briefly  — the  ba¬ 
sics  of  serial  communications.  To  illus¬ 
trate  the  use  of  those  tools  and  princi¬ 
ples,  we  built  a  communications  pro¬ 
gram  called  TINYCOMM.  That  program 
uses  none  of  the  window,  menu,  and 
help  functions  from  our  ongoing  library 
collection.  Its  presentation  was  focused 
instead  on  a  terse  demonstration  of  the 
use  of  the  serial  and  modem  functions. 
This  month  the  TINYCOMM  program 
spawns  an  offspring  that  is  named 
SMALLCOM  and  that  uses  the  window, 
menu,  and  data  entry  tools  from  earlier 
columns  to  support  the  user  interface. 
SMALLCOM  has  more  of  the  features 
found  in  a  commercial  communications 
program  — features,  such  as  uploading 
and  downloading  files,  a  serial  port  con¬ 
figuration  file  that  can  be  changed  from 
the  program,  an  editor,  hooks  for  a 
phone  directory'  and  scripts,  hooks  for 
file  transfer  protocols  and  automatic  rec¬ 
ognition  of,  and  reaction  to,  the  Hayes 
modem  result  codes. 

SMALLCOM  Source  Code 

The  listings  for  SMALLCOM  are  Listing 
One,  smallcom.c,  page  131,  Listing  Two, 
smallcom.prj,  page  136,  Listing  Three, 
smallcom.mak,  page  136,  and  Listing 
Four,  smallcom.lnk,  page  136.  Small¬ 
com.c  is  the  source  code  for  the  pro¬ 
gram.  In  addition,  you  will  need  most 
of  the  library  source  programs  pub¬ 
lished  in  this  column  since  September 
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when  the  project  began.  Smallcom.prj 
is  the  Turbo  C  project  make  file  for 
building  the  program  from  the  Turbo  C 
environment.  Set  the  compact  memory 
model  and  define  these  global  macros 
either  as  #define  statements  in  win- 
dow.h  or  within  the  Compiler  Defines 
option  (Alt-O/C/D)  of  the  Turbo  C  en¬ 
vironment  as  shown  here: 


TURBOC= 1  ;MSOFT=2;COMPILER= 

TURBOC 

Smallcom.mak  and  smallcom.lnk  are  the 
Microsoft  C  make  file  and  linker  com¬ 
mand  file  to  build  the  program.  They 
assume  that  Microsoft  C  is  in  the  DOS 
execution  path,  that  the  MSC  libraries 
are  in  the  \  LIB  subdirectory,  and  that 
the  LIB  and  INCLUDE  environment  vari¬ 
ables  are  properly  set. 

Hooks 

Earlier  I  mentioned  hooks  in  the  pro¬ 
gram.  These  hooks  will  be  used  in  the 
coming  months  to  add  a  phone  direc¬ 
tory,  on-line  service  scripts,  and 
XModem  and  Kermit  file  transfer  pro¬ 
tocols.  The  hooks  are  function  pointers 
that  initially  have  NULL  values.  As  we 
add  features,  we  will  initialize  the  func¬ 
tion  pointers  with  the  addresses  of  the 
functions  for  the  features  we  want  to 
add.  This  hooking  technique  allows  us 
to  plan  for  expansion  while  preserving 
most  of  the  existing  code. 

The  phone  directory  hook  is  exe¬ 
cuted  by  the  directory  menu  selection. 
The  script  processor  hook  is  executed 
when  an  originating  call  makes  con¬ 
nection  with  the  remote  processor.  We 
will  decide  later  what  a  script  process 
really  is.  For  now  it  is  enough  to  know 
that  when  we  need  one,  it  will  be  there 
when  the  call  goes  through.  Scripts  are 
typically  related  to  specific  online  ser¬ 
vices,  so  SMALLCOM  will  associate 
scripts  with  phone  numbers  in  the  di¬ 
rectory.  The  file  transfer  protocol  hooks 
occur  at  two  levels.  The  higher  hook  is 
a  call  to  a  function  that  will  allow  the 
user  to  select  a  protocol  for  an  upload 
or  download.  The  address  of  the  func¬ 
tion  will  be  in  the  selectjtransfer Jrrotocol 
function  pointer  hook.  That  function 
must  return  a  subscript  into  an  array  of 
function  pointers  and  will  be  provided 
later.  There  is  an  array  for  uploads 
called  up _ protocol  and  one  for  down¬ 
loads  called  down jyrotocol.  These  two 
arrays  will  contain  the  addresses  of  the 
functions  that  implement  the  various 


protocols.  The  first  entries  in  both  ar¬ 
rays  are  the  addresses  of  the  ASCII  pro¬ 
tocol  functions,  which  are  included  in 
this  first  edition  of  SMALLCOM.  Others 
will  be  added  later. 

More  Communications  Processes 

To  use  the  modem  in  ways  needed  for 
SMALLCOM,  we  must  change  its  in¬ 
itialization  string  from  the  value  used 
last  month.  Modify  the  INITMODEM 
definition  in  modem.h  to  this  value: 

AT&ClE-0MlS7=60Sll=55VlX3S0=0\r 

Look  now  at  the  end  of  Listing  One, 
smallcom.c.  There  are  some  additional 
functions  for  managing  the  modem  and 
serial  port.  These  functions  were  not 
needed  in  last  month’s  TINYCOMM  pro¬ 
gram.  You  might  want  to  move  them 
into  serial. c  and  modem. c  as  appropri¬ 
ate.  I  will  explain  those  functions  here. 

The  testcarrier  function  uses  the  car¬ 
rier  macro  to  see  if  the  modem  has  lost 
the  carrier  detect  signal.  By  testing  this 
signal,  the  program  can  determine  that 
the  remote  processor  has  disconnected. 
First,  though,  you  must  configure  your 
modem  for  normal  operation  of  the 
carrier  detect  signal.  Many  modems  will 
optionally  assert  this  signal  at  all  times 
regardless  of  the  connection.  See  if  your 
modem  has  a  dip  switch  to  turn  the 
signal  off  and  use  that  as  the  default 
option.  Remember,  not  all  modems  are 
alike,  and  not  everyone  will  have  their 
modems  set  up  the  same. 

The  waitforconnect  function  is  used 
when  the  program  is  waiting  for  an 
incoming  call  or  waiting  for  an  origi¬ 
nating  call  to  be  answered.  When  an 
incoming  call  occurs,  the  function  can 
sense  the  baud  rate  of  the  caller  and 
adjust  the  local-baud  rate  accordingly. 
This  process  is  made  possible  by  the 
result  codes  returned  by  the  modem 
when  it  makes  the  connection. 

The  waitforconnect  function  calls  the 
waitforresult  function,  which  waits  for 
and  returns  the  modem’s  result  code. 
The  modem  returns  CONNECT,  CON- 
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NECT  1200,  or  CONNECT  2400  strings 
depending  on  the  caller’s  baud  rate.  For 
an  originated  call,  the  modem  will  re¬ 
turn  NO  CARRIER  if  the  called  party 
answers  without  a  carrier  detect  signal 
or  NO  ANSWER  if  the  called  party  does 
not  answer.  The  waitforresult  function 
translates  these  strings  into  integer  re¬ 
sult  codes. 

The  waitforresult  function  calls  the 
general-purpose  waitforstring  function. 
This  function  will  be  important  to  us 
later  when  we  get  into  script  process¬ 
ing.  You  pass  this  function  the  address 
of  an  array  of  characters,  each  of  which 
points  to  a  string.  The  function  watches 
the  serial  input  stream  to  see  if  the 
stream  matches  any  of  the  strings,  and 
returns  the  offset  of  the  matching  string 


Sometimes  I  violate 
my  own  rules  to  get  the 
job  done.  I  do  not 
attach  as  well  to 
dogmatism  as  I  do  to 
pragmatism. 

or  -1  if  the  TIMEOUT  value  elapses 
before  any  match  occurs.  This  use  of 
the  waitforstring  function  uses  an  array 
of  pointers  to  the  modem’s  result 
codes,  waitforstring  allows  you  to  use 
the  backslash  as  a  wild  card  character  in 
the  string  arguments. 

Help  Windows 

In  December  we  introduced  help  win¬ 
dows  into  our  tool  collection  and  illus¬ 
trated  their  use  by  including  the  feature 
in  the  TWRP  tiny  word  processor.  Help 
windows  are  recorded  in  a  file  named 
by  the  load_help  function  and  identi¬ 
fied  by  help  window  mnemonics  found 
in  the  data-entry  screen  FIELD  struc¬ 
tures  — the  MENU  structures  — and  the 
calls  to  the  set_help  function. 
SMALLCOM  includes  these  mnemon¬ 
ics,  but  I  am  not  publishing  the  text  for 
the  help  windows.  There  is  nothing 
more  to  be  learned  from  more  help 
text,  so  they  would  only  serve  to  use  up 
valuable  space  in  the  magazine.  You 
can  customize  new  help  windows  to 
your  preference,  or  you  can  omit  them. 
SMALLCOM  includes  most  of  TWRP  as 
its  integrated  editor,  so  you  can  copy 
December’s  twrp.hlp  to  a  file  you  will 
name  smallcom.hlpand  add  SMALLCOM- 
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specific  help  windows  to  it.  The  mne¬ 
monics  are  found  in  the  source  code  in 
smallcom.c. 

Configuration  File 

When  SMALLCOM  is  run,  it  looks  for  a 
file  named  smallcom.cfg.  If  that  file  ex¬ 
ists,  SMALLCOM  reads  its  contents  into 
the  variables  that  specify  the  default 
serial  port  and  modem  parameters  — 
which  port  is  being  used,  the  parity,  the 
number  of  stop  bits,  the  word  length, 
the  baud  rate,  whether  pulse  or  tone 
dialing  is  to  be  used,  and  what  the 
default  phone  number  is  for  calls  origi¬ 
nated  by  SMALLCOM.  If  the  file  does 
not  exist,  the  program  uses  the  values 
coded  into  those  variables  when 
SMALLCOM  was  compiled.  The 
SMALLCOM  menu  bar  includes  a  pop- 
down  menu  that  allows  you  to  change 
all  but  the  phone  number  and  to  write 
everything  including  the  phone  num¬ 
ber  to  a  new  copy  of  the  configuration 
file.  As  things  stand  right  now,  that  al¬ 
lows  you  to  configure  everything  ex¬ 
cept  the  phone  number. 

The  SMALLCOM  Screen  Format 

SMALLCOM  provides  a  large  window 
for  showing  the  text  passed  between 
processors  and  uses  the  menu  manager 
software  from  our  window  library.  The 
menu  bar  at  the  top  of  the  screen  has 
selections  named  “File,”  “Connect,”  “Pa¬ 
rameters,”  “Editor,”  and  “Directory.”  You 
can  get  to  one  of  these  selections  by 
pressing  F10  and  using  the  right  and  left 
arrow  keys  to  move  back  and  forth 
among  the  pop-down  menus,  or  you 
can  press  the  Alt  key  along  with  the  first 
letter  of  the  selection  you  want.  The 
“File,”  “Connect,”  and  “Parameters”  se¬ 
lections  pop-down  menus  for  further 
selections.  The  “Editor”  and  “Directory” 
selections  light  up  the  selection  on  the 
menu  bar  and  let  you  press  Enter  to 
execute  the  text  editor  or  phone  direc¬ 
tory.  The  bottom  of  the  screen  has  a 
status  bar  that  shows  what  is  going  on. 
The  “On/Off  Line”  message  tells  if  you 
are  connected  to  a  remote  computer. 
The  “Direct”  message  says  you  have 
selected  a  direct,  null-modem  connec¬ 
tion.  If  you  are  logging  text,  the  “Log¬ 
ging”  message  appears.  If  you  are  in 
the  modem's  answer  mode  waiting  for 
a  call,  the  “Answering”  message  ap¬ 
pears.  While  you  are  uploading  or  down¬ 
loading  a  file  the  “Uploading”  or  “Down¬ 
loading”  message  appears  with  as  much 
of  the  file’s  path  and  name  as  can  fit  on 
the  status  bar.  The  current  phone 
number  — the  one  that  will  be  dialed 
by  the  “Place  Call”  selection  on  the 
“Connect”  menu  — is  shown. 

The  “Parameters”  pop-down  menu 
allows  you  to  set  and  change  the  serial 
port  and  modem  parameters.  Their  in¬ 


itial  values  are  recorded  in  the 
smallcom.cfg  file.  You  use  the  Enter 
key  to  step  through  the  valid  settings 
for  each  parameter.  Any  changes  you 
make  on  the  menu  are  in  effect  for  as 
long  as  the  program  is  running.  If  you 
use  the  “Write  Parameters”  selection, 
the  current  settings  are  written  to  the 
smallcom.cfg  file  and  will  be  the  default 
values  the  next  time  you  run  the  pro¬ 
gram. 

You  cannot  communicate  through 
SMALLCOM  until  you  have  connected 
with  another  computer.  The  other  com¬ 
puter  can  be  running  SMALLCOM,  it 
can  be  an  online  service  or  bulletin 
board  system,  or  it  can  be  a  different 
communications  program  such  as  Pro- 
comm.  The  “Connect”  pop-down  menu 
has  selections  for  making  and  breaking 
connections.  When  you  select  “Place 
Call,”  SMALLCOM  dials  the  current 
phone  number  (shown  in  the  status 
line  at  the  bottom  of  the  screen  on  the 
right  side)  and  waits  for  the  remote 
computer  to  answer.  The  “Answer  Call” 
selection  puts  the  modem  into  answer 
mode.  Wdien  a  call  comes  in,  the  mo¬ 
dem  will  answer  the  phone  and  return 
a  status  message  that  tells  the  baud  rate 
of  the  caller.  The  “Hang  Up”  selection 
breaks  the  connection.  The  “Direct  Con¬ 
nection”  command  assumes  that  the 
connection  is  direct  with  a  null  modem 
cable  and  no  modem  commands  are 
involved. 

Once  one  of  these  connections  has 
been  made,  the  cursor  is  in  the  data 


SMALLCOM  has 
features  found  in  a 
commercial 
communications 
program 


window,  and  you  can  type  messages 
and  read  the  messages  that  arrive  from 
the  remote  computer.  You  can  use  the 
“File”  pop-down  menu  to  upload  and 
download  files  and  to  turn  the  system 
log  on  and  off.  The  system  log  is  a  file 
named  smallcom.log  that  records  eve¬ 
rything  sent  and  received  by  the  pro¬ 
gram.  If  smallcom.log  exists  when  you 
turn  the  option  on,  new  text  is  ap¬ 
pended  to  the  file. 
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Echoes 

When  two  computers  converse  across 
phone  lines,  one  of  them  has  placed  a 
call  and  the  other  has  answered.  The 
two  roles  are  somewhat  different.  The 
caller  will  expect  the  called  system  to 
echo  any  characters  that  the  caller 
sends  and  will  not  display  characters 
locally  as  they  are  being  typed.  The 
called  system  does  not  expect  the  caller 
to  echo  and  thus  displays  its  own  charac¬ 
ters  as  they  are  typed.  Therefore, 
SMALLCOM  must  remember  whether  it 
originated  or  answered  the  call  and  not 
echo  or  echo  accordingly.  (An  echo  is 
the  return  of  the  character  just  received. 
I  derived  this  behavior  empirically  by 
observing  the  behavior  of  other  com¬ 
munications  programs.)  If  you  call  a 
computer  and  upload  a  text  file,  the 
answering  computer  will  echo  each  char¬ 
acter  because  it  does  not  know  that  you 
are  not  typing.  If,  however,  the  called 
computer  is  told  to  download  the  file,  it 
does  not  echo  the  characters  you  sent, 
because  it  assumes  that  a  file  transfer  is 
underway.  These  are  the  rules  that 
SMALLCOM  obeys.  Therefore,  if  the 
called  computer  is  downloading  and 
the  caller  is  typing,  the  caller  will  not 
display  the  characters  on  its  screen  be¬ 
cause  no  echo  is  being  sent.  Conversely, 
if  the  caller  is  uploading  and  the  called 
system  is  not  downloading,  the  text  is 
displayed  at  both  locations  during  the 
transfer.  If  the  caller  is  uploading  and 
the  called  system  downloading,  neither 
computer  displays  the  text.  When  you 
select  the  “Direct  Connection”  mode, 
each  computer  displays  its  own  key¬ 
strokes  and  dees  not  echo  anything 
back  to  the  other.  Confused?  So  was  I 
when  I  worked  all  this  out. 

In  communication  jargon  these  pro¬ 
cedures  are  called  half  and  full  duplex 
transmissions,  and  some  communica¬ 
tions  programs  let  you  configure  for 
one  or  the  other.  My  objective  was  to  let 
the  program  determine  the  proper  mode 
based  on  its  recognition  of  the  circum¬ 
stances  at  hand 

These  echo  problems  pertain  to  typ¬ 
ing,  and  they  pertain  as  well  to  the 
ASCII  file-transfer  protocol  because  that 
protocol  looks  to  the  receiver  just  like 
typing.  If  you  don’t  tell  the  other  com¬ 
puter  that  you  are  sending  a  file,  it 
doesn’t  see  any  difference.  The  ASCII 
transfer  protocol  is  usually  used  to 
send  text  messages  that  were  prepared 
off  line,  but  it  can  also  be  used  to 
upload  files  that  do  not  have  critical 
content.  When  you  do  that,  the  receiv¬ 
ing  program  knows  a  file  transfer  is  in 
progress  because  you  tell  it  to  down¬ 
load  a  file.  When  we  get  into  the  binary 
file-transfer  protocols,  no  such  echo  con¬ 
cerns  will  bother  us  because  both  com- 
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puters  must  be  fully  aware  of  what  is 
going  on. 

Editor 

The  editor  selection  on  the  menu  bar 
calls  the  SMALLCOM  text  editor,  which 
is  an  integrated  version  of  the  TWRP 
tiny  word  processor  from  December. 
All  the  TWRP  commands  are  available, 
and  you  can  edit  a  text  file  of  up  to  800 
lines.  You  can  call  this  editor  while  you 
are  on  or  off  line.  It  can  be  used  to 
browse  messages  that  you  downloaded 
or  to  compose  answers.  Usually  you 
will  use  it  while  you  are  off  line  to  save 
connect  charges. 

Phone  Directory 

If  you  select  the  directory  entry  on  the 
SMALLCOM  menu  bar,  nothing  hap¬ 
pens  because  that  feature  is  stubbed 
out  for  now  with  a  NULL  in  its  hook 
function  pointer.  Next  month  we  will 
add  the  phone  directory.  It  will  allow  to 
add,  change,  and  delete  entries  and 
select  an  entry  as  the  current  one  to  be 
dialed.  Until  we  have  that  feature,  you 
must  hard-code  the  phone  number  into 
the  PHONENO  string  in  February’s  mo- 
dem.c. 

Discussions  with  Readers 

Some  readers  find  time  to  write  me  at 
the  magazine  or  leave  messages  for 
me  on  CompuServe.  (My  CIS  ID  is 
71101,1262.)  When  a  reader’s  question 
or  comment  raises  an  issue  or  provokes 
a  thought  that  might  interest  others,  I 
will  address  it  here. 

A  reader  asked  why  I  was  reinvent¬ 
ing  the  wheel.  Why  another  window 
package,  another  help  package,  another 
menu  manager,  another  editor,  another 
communications  program?  Why  any  of 
this  indeed?  My  answer  to  him  was  that 
the  point  of  the  “C  Programming"  col¬ 
umn  project  is  first  to  bring  to  you,  the 
readers-at-large,  a  collection  of  C  lan¬ 
guage  tools  that  you  can  use  in  your 
applications,  and  second  show  by  ex¬ 
ample  how  these  tools  are  programmed 
in  C.  I  am  not  trying  to  replace  any 
programs  that  you  might  already  be 
using,  programs  that  do  all  and  more  of 
what  this  software  does.  If  all  you  want 
is  what  Procomm  does,  you  should  get 
Procomm.  It’s  a  good  program,  and  it 
costs  much  less  than  the  time  you  will 
devote  working  with  and  learning  the 
software  tools  in  this  column.  If,  on  the 
other  hand,  you  want  to  learn  how 
programs  like  Procomm  are  developed 
and,  at  the  same  time,  collect  the  tools 
that  go  into  such  developments,  then 
you  are  in  the  right  place.  Such  lessons 


and  software  tool  collections  are  the 
backbone  of  this  column  and  are  con¬ 
sistent  with  the  12-year  legacy  of  DDJ. 

One  reader  cleverly  matched  one  of 
my  crotchets  with  one  of  my  programs 
and  suggested  I  practice  what  I  preach. 
Being  neither  preacher  nor  teacher,  I 
practice  what  I  practice  and  offer  those 
practices  as  examples  of  things  that 
might  benefit  programmers.  Sometimes 
my  programming  practices  stray  from 
the  disciplines  held  by  the  distant  gurus 
as  proper  programming  habits.  Some¬ 
times  I  violate  my  own  rules  to  get  the 
job  done.  I  do  not  attach  as  well  to 
dogmatism  as  I  do  to  pragmatism. 

Availability 

All  the  source  code  for  articles  in  this 
issue  is  available  on  a  single  disk.  To 
order,  send  $14.95  (Calif,  residents  add 
sales  tax)  to  Dr.  Dobb’s  Journal,  501 
Galveston  Rd.,  Redwood  City,  CA  94063, 
or  call  800-356-2002  (inside  Calif.)  or 
800-533-4372  (outside  Calif.).  Please  spec¬ 
ify  the  issue  number  and  format  (MS- 
DOS,  Macintosh,  Kaypro). 

DDJ 

(Listings  begin  on  page  131.) 

Vote  for  your  favorite  feature/article. 
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Lines  Galore 


If  the  lowly  pixel  is  the  foundation  of 
computer  graphics,  the  line  is  its 
cornerstone.  Now  that  we’ve  figured 
out  how  to  draw  a  pixel  on  the 
EGA/VGA  screen  efficiently,  it  would 
seem  that  combining  them  to  form  lines 
is  no  big  deal.  Not  so,  as  we’ll  see  this 
month  in  developing  a  couple  of  ways 
to  draw  lines  and  some  combinations 
thereof. 

Here’s  the  problem.  A  line  moves 
between  two  end  points  in  any  con¬ 
ceivable  direction.  Its  path  varies  con¬ 
tinuously,  passing  through  an  infinite 
number  of  points.  The  number  and  po¬ 
sitions  of  points  on  a  display  screen, 
however,  are  fixed.  Therefore  the  chal¬ 
lenge  in  drawing  a  line  is  to  find,  for 
any  given  point  along  its  path,  the  near¬ 
est  fixed  point  on  the  display.  A  line  is 
thus  represented  by  lighting  the  series 
of  pixels  lying  closest  to  its  path,  as 
Figure  1  illustrates. 

The  simplest  way  to  approximate  a 
line  is  to  calculate  the  series  of  points 
using  the  linear  equation 

y  =  mx  +  b 

where  m  is  the  slope  (the  amount  of 
vertical  change  per  x  increment)  and  b 
is  the  y-  intercept  (the  point  where  the 
line  crosses  the  y  axis).  When  m  and  b 
are  known,  you  plug  in  any  x  and 
round  the  result  to  get  the  nearest  y. 
Unfortunately,  this  method  yields  un¬ 
acceptable  performance  because  m  is  a 
floating-point  value. 

You  have  to  use  integer  arithmetic  if 
you  want  fast  line-drawing.  In  1965, 
IBM  researcher  J.E.  Bresenham  pub- 


Kent  Porter 


lished  an  integer-based  method  that 
has  become  a  stock  item  in  computer 
graphics. 

The  Bresenham  algorithm  represents 
the  slope  with  two  integers,  called  the 
diagonal  and  nondiagonal  increments, 
which  have  opposite  signs.  As  the  line 
progresses,  they  are  applied  to  a  pixel 
selection  variable  generally  represented 


by  the  symbol  d.  The  nondiagonal  in¬ 
crement  is  applied  when  the  nearest 
pixel  is  in  the  current  row,  the  diagonal 
increment  is  applied  when  it’s  in  an 
adjacent  row.  The  sign  of  d  indicates 
when  the  row  changes,  and  thus  selects 
the  closest  pixel.  When  d  is  negative, 
the  pixel  above  is  selected  and  the  row 
doesn’t  change,  and  when  dis  positive, 
diagonal  movement  occurs  to  the  row 
below. 

The  terms  “row,”  “above,”  and  “be¬ 
low”  are  only  conceptual.  The  signs  of 
the  control  variables  allow  the  Bresen¬ 
ham  algorithm  to  draw  right  to  left,  thus 
mathematically  turning  the  display 
upside  down.  And  when  the  major  axis 
of  motion  is  along  the  y  axis,  Bresen¬ 
ham  mathematically  rotates  the  display 
90  degrees,  one  way  or  the  other,  ac¬ 
cording  to  the  drawing  direction. 

That’s  the  purpose  of  the  code  be¬ 
tween  lines  13  and  38  in  Listing  One, 
page  137,  which  implements  the  Bre¬ 
senham  algorithm.  The  result  is  an  un¬ 
broken  line  representation  consisting 
of  linearly-and  diagonally-adjacent  pix¬ 
els,  drawn  using  only  three  integer  ad¬ 


dition  operations  in  the  loop  starting  on 
line  40. 

Add  the  draw_line( )  function  from 
Listing  One  to  your  copy  of  GRAFIX.C 
and  the  prototype  to  GRAFIX.H.  In  or¬ 
der  to  use  the  function,  you  must  re¬ 
compile  GRAFIX.C  and  replace  it  in  the 
GRAFIX.LIB  file.  (Note:  if  you  purchase 
the  DDJ  companion  diskette  or  down¬ 
load  the  code  for  this  article  from  Com¬ 
puServe,  you  will  receive  complete  new 
copies  of  the  source  files  containing 
this  and  other  routines  added  this 
month.) 

Listing  Two  (SPOKES. C),  page  137,  is 
a  sample  program  that  puts  the  Bresen¬ 
ham  routine  to  work.  SPOKES. C  draws 
multicolor  lines  emanating  from  the  cen¬ 
ter  of  the  EGA  display. 

Programming  in  general  develops  func¬ 
tionality  much  as  a  brick  layer  builds  a 
wall:  by  stacking  layers  of  bricks  (lower- 
level  functions)  according  to  a  plan  and 
fastening  them  together  with  the  mortar 
of  program  logic.  Nowhere  is  this  more 
prevalent  than  in  graphics.  So  far,  we’ve 
made  away  to  write  pixels  and  used 
that  routine  to  draw  lines.  Now  we’ll 
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Figure  1:  A  line  is  a  representation  on  the  display  by  lighting  the  pixels  lying 
closest  to  its  actual  path. 
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(continued  from  page  118) 
add  another  level  to  the  hierarchy  with 
a  couple  of  functions  that  draw  multi¬ 
ple  lines. 

The  first  is  the  rectangle,  an  object 
occurring  so  often  that  it  needs  its  own 
function.  We  can  describe  a  rectangle 
in  terms  of  its  width  and  height  relative 
to  the  upper  left  comer.  Thus  the  rec¬ 
tangle  function  in  Listing  Three  page 
137,  is  called  with  draw_rect  (left,  top, 
width,  height).  The  logic  of  the  routine 
combines  the  arguments  in  various  ways 
and  passes  them  along  to  the  four  invo¬ 
cations  of  draw_line(  )  needed  to  draw 
the  edges. 

The  other  high-level  function,  also 
shown  in  Listing  Three,  is  more  com¬ 
plex.  It  draws  a  series  of  joined  line 
segments  and  for  that  reason  has  the 
name  polyline(  ).  You  can  use  it  to  draw 
closed  object  such  as  a  star  or  an  open 
object  such  as  the  zigzag  data  represen¬ 
tation  of  a  line  chart. 

If  a  polyline  has  n  edges,  you  need 
n+1  vertices  to  represent  it.  For  exam¬ 
ple,  a  line  from  A  to  B  to  C  consists  of 
two  segments  or  edges:  A  to  B,  and  B  to 
C.  The  vertices  are  the  end  points  A,  B, 
and  C.  The  polyline( )  function  thus 
requires  two  arguments.  The  first  is  the 
number  of  edges,  and  the  other  is  an 
array  of  vertices.  The  vertex  array  con¬ 
sists  of  coordinate  pairs,  where  v[0]  = 
xA,  v[l]  =  yA,  v[2]  =  xB,  v(3l  =  yB,  and  so 
on.  Consequently,  the  size  of  the  array 
is  (n+l)*2  integers:  in  the  case  of 
polyline  ABC,  six  elements. 

The  internal  flow  of  polyline( )  ad¬ 
vances  along  the  vertices  like  an  inch- 
worm,  drawing  from  the  previous  ver¬ 
tex  to  the  cunent  vertex.  When  the 
current  vertex  exceeds  the  number  of 
edges  plus  one,  the  routine  is  finished. 

Add  the  two  routines  from  Listing 
Three  to  GRAFEX.C  and  their  proto¬ 
types  to  GRAFDC.H,  then  recompile  and 
replace  the  module  in  GRAFIX.LIB.  You 
can  then  run  the  two  small  demo  pro¬ 
grams  from  Listings  Four  (BOXES. C) 
and  Five  (STAR.C),  page  137,  which 
exercise  the  new  functions  by  drawing 
a  series  of  rectangles  (BOXES. C)  and  a 
five-pointed  star. 

The  Bresenham  algorithm  — vener¬ 
ated  though  it  is  for  its  efficiency  — still 
draws  only  one  pixel  at  a  time.  There 
isn’t  an  alternative  when  drawing  lines 
that  move  in  any  direction.  For  strictly 
horizontal  lines,  however,  we  can  use  a 
special  hardware  feature  to  write  up  to 
eight  pixels  at  a  time. 

The  6845  video  controller’s  Write 
Mode  0  enables  you  to  update  an  entire 
byte  on  each  plane  — that  is,  eight 
pixels  — with  one  operation.  The  only 
stipulation  is  that  all  pixels  must  receive 
the  same  index  value  filtered  by  the 


same  bitmask.  In  other  words,  the  eight 
pixels  are  treated  identically  in  a  single 
operation.  Updating  eight  pixels  simul¬ 
taneously  is  actually  more  efficient  than 
updating  one  using  Write  Mode  2,  used 
in  the  draw _point(  )  routine  introduced 
last  month.  This  is  because  it’s  not  nec¬ 
essary  to  shift  the  data  mask  in  order  to 
identify  the  individual  pixel  being  writ¬ 
ten.  In  fact,  Write  Mode  0  incurs  almost 
exactly  the  same  overhead  for  eight 
pixels  that  Write  Mode  2  incurs  for  one. 
The  result  is  blazing  throughput. 

The  hlineO  routine  in  Listing  Six 


A  horizontal  line 
lacks  flexibility, 
of  course, 

but  it’s  very  useful  in 
creating  solids. 


(HLINE.ASM),  page  138,  uses  Write 
Mode  0  to  deliver  over  580,000  pixels 
per  second  on  a  10-MHz  AT  clone  when 
all  lines  completely  fill  each  byte.  The 
routine  is  slowed  slightly  if  there  are 
odd  pixels  on  each  end,  because 
hline( )  must  construct  the  masks  re¬ 
quired  to  update  only  the  affected  pix¬ 
els.  Still,  worst-case  performance  is  in 
the  area  of  450,000  pixels  per  second, 
which  amounts  to  an  18X  to  23X  improve¬ 
ment  over  Bresenham. 

Like  draw _point( ),  hline( )  is  writ¬ 
ten  in  assembly  language  for  maximum 
efficiency.  Its  public  symbol  has  an  un¬ 
derscore  prefix  to  comply  with  C  link¬ 
age  conventions.  Add  the  prototype 

void  far  bline  ( int  x,  inty,  int  length)-, 

to  your  copy  of  GRAFIX.H,  then  assem¬ 
ble  this  routine  and  add  it  to 
GRAFIX.LIB  using  a  librarian. 

Note  that  hline( )  uses  several  auto 
variables  allocated  on  the  stack.  Argu¬ 
ments  are  at  positive  offsets  from  the 
BP  register;  for  local  variables,  subtract 
the  sum  of  their  sizes  from  the  SP  regis¬ 


ter,  then  offset  negatively  from  BP  to 
reach  each  variable,  as  illustrated  by  the 
EQUate  directives.  This  is  precisely  the 
same  method  used  by  most  language 
compilers  for  allocating  variables  local 
to  subroutines.  When  exit  processing 
moves  the  BP  register  contents  back 
into  SP,  the  auto  variables  are  automati¬ 
cally  removed  from  the  stack. 

A  horizontal  line  lacks  flexibility,  of 
course,  but  it’s  very  useful  in  creating 
solids.  A  case  in  point  is  a  filled  rectan¬ 
gle;  simply  loop  through  a  sequence  of 
Y  coordinates,  repeatedly  drawing  a  line 
of  the  same  length.  Listing  Seven  page 
141,  gives  the  GRAFIX  function  fill_rect(  ) 
for  doing  this.  Add  it  to  GRAFIX.C  and 
its  prototype  to  7. 

The  program  COLORS.C  in  Listing 
Eight,  page  141,  uses  Jill_rect( )  to  dis¬ 
play  the  default  16-color  palette  of  the 
EGA  and  VGA.  This  program  fills  90 
percent  of  the  224,000-pixel  screen,  yet 
thanks  to  hline( ),  it  takes  less  than  half 
a  second  on  the  AT.  As  you  see,  draw¬ 
ing  a  line — a  fundamental  object  in 
computer  graphics  — isn’t  quite  as  triv¬ 
ial  as  it  seems  at  first  glance.  Now  that 
we’ve  developed  the  basic  algorithms 
and  the  beginnings  of  a  hierarchy  of 
graphics  primitives,  we  can  start  writing 
serious  graphics  programs,  and  that’s 
what  we’ll  continue  doing  over  the  com¬ 
ing  months. 

Availability 

All  source  code  for  articles  in  this  issue 
is  available  on  a  single  disk.  To  order, 
send  $14.95  (Calif,  residents  add  sales 
tax)  to  Dr.  Dobb’s  Journal,  501 
Galveston  Dr.,  Redwood  City,  CA 94063 
or  call  800-356-2002  (inside  Calif.)  or 
800-533-4372  (outside  Calif.).  Please  spec¬ 
ify  the  issue  and  format  (MS-DOS,  Macin¬ 
tosh,  Kaypro). 


DDJ 
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Text  Screen 
Metrics 


Ahhh,  Comdex.  Recall  the  classic 
Rocky  &  Bullwinkle  episode  in 
which  Bullwinkle  is  interrogated 
by  a  crew  of  trenchcoated  FBI 
types  who  speak  only  in  a  Jack  Webb 
monotone?  After  a  few  questions,  Bullwin¬ 
kle  begins  to  adopt  the  same  mono¬ 
tone,  and  the  spooks  take  umbrage. 

“You’re  trying  to  make  fun  of  the 
way  we  talk?”  one  asks. 

“No,”  replies  Bullwinkle,  “but  it’s  catch¬ 
ing." 

I  thought  of  Bullwinkle  after  trudging 
past  the  eleven-hundredth  booth  full  of 
wool-suited  Asian  gentlemen  selling 
power  supplies  and  clone  cases,  each 
of  whom  greeted  me  by  asking,  “Are 
you  dealer?” 

After  awhile  I  had  to  choke  back  the 
impulse  to  reply,  “No,  I  writer.” 

The  Invasion  of  the  Pie-Expanders 

Comdex  has  always  been  primarily  a 
hardware  show,  and  in  recent  years  has 
become  an  increasingly  Asian  hardware 
show,  hence  my  subliminal  impulse  to 
deal  with  our  Pacific  Rim  partners  in 
their  own  syntax.  Against  constant  pro¬ 
tectionist  pressures  from  both  left  and 
right,  I  have  to  keep  reminding  people 
that  the  Asian  manufacturers  keep  mak¬ 
ing  the  pie  bigger.  The  more  entry-level 
people  who  buy  cheap  Asian  clones  in 
1989,  the  more  experienced  users  will 
buy  higher-cost  American  (and  gener¬ 
ally  more  powerful)  80486  machines  in 
1991-  Growth  in  our  industry  requires 
bringing  ’em  in  at  the  bottom  and  spread¬ 
ing  computing  skills  throughout  soci¬ 
ety.  American  companies  prefer  to  price- 
skim  at  the  top,  and  go  belly-up  when 
the  cream  is  exhausted  — leaving  us  no 
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recourse  but  to  keep  generating  cream. 
By  doing  us  the  favor  of  manufacturing 
our  industry’s  loss-leaders,  our  Asian 
partners  are  keeping  Compaq  and  Ap¬ 
ple  alive. 

At  Comdex,  the  hardware  to  gladden 
a  programmer’s  heart  was  almost  uni¬ 
versally  American  — and  expensive.  ATT 
Bell  Labs  was  showing  a  research  mo¬ 


nitor  — not  even  a  pre-prototype  — with 
a  monochrome  resolution  of  4096  by 
4096  and  a  1 6-Mbyte  refresh  buffer.  300 
DPI  video  to  match  300  DPI  lasers. 
Maybe  1994. 

International  Meta  Systems  showed 
their  Max2  30  MIPS  accelerator  board 
for  Digitalk’s  Smalltalk/V.  The  4-Mbyte 
$8,000  system  makes  the  Xerox  Dorado 
workstation  I  played  with  in  1983  look 
pretty  sick  — and  doesn’t  lock  you  out 
of  mainstream  DOS  and  OS/2  applica¬ 
tions.  (I’ll  have  a  lot  more  to  say  about 
Smalltalk  in  future  columns.) 

I  was  astonished  to  see  a  Xerox- 
blessed  implementation  of  Alan  Kay’s 
Dynabook  product  there,  offered  by 
Scenario  Inc.  of  Somerville  Mass.  The 
Dynabook,  of  course,  was  the  book¬ 
shaped,  100  percent  flat-screen  com¬ 
puter  Xerox  PARC  proposed  in  1976  as 
the  future  of  computing.  You  curl  up  in 
your  cushy  chair  and  read  it  like  a  book, 
thumbing  the  screen  to  flip  pages  and 
touching  hot-link  keywords  to  traverse 
a  hypertext  thread.  No  keyboard,  al¬ 
though  Xerox’s  original  design  included 
one.  Scenario’s  Dynabook  has  a  CD- 
ROM  reader  and  will  be  positioned  as  a 
research  tool,  with  a  giant  effort  to  get 
low-cost  ($40)  reference  works  and  clas¬ 
sics  on  CD-ROM.  An  amazing  thing  — 
and  only  $5,000. 

My  own  personal  Comdex  favorites 
(perhaps  because  they’re  a  realizable 
fantasy)  are  Brier  Technology’s  20- 
Mbyte  and  40-Mbyte  3-5-inch  70ms  disk¬ 
ette  drives.  The  $30  diskettes  are  mechani¬ 
cally  identical  to  PS/2  and  Mac  disk¬ 
ettes,  and  the  drives  are  no  larger.  Fur¬ 
thermore,  the  drives  can  detect  and  read 
both  720K  and  1.4-Mbyte  diskettes.  Two 
of  these  critters,  plus  a  fast  internal  40- 
Mbyte  hard  drive  are  all  a  program¬ 
mer’s  workstation  would  need  for 
backup,  archiving,  and  multiple  media 
compatibility.  Brier  showed  at  the  Da- 
tavue  booth  — which  might  give  you  a 
hint  as  to  where  the  drives  will  first 
appear.  No  price  yet.  Available  ’89- 

Products  like  these  hint  at  what  our 
programmer’s  workstation  will  be  in 
1992. 1  call  it  the  Red  Hot  Shoebox,  and 
the  machine  itself  will  be  a  minimal 
swelling  on  the  cable  between  the  key¬ 


board  and  the  screen.  But  oh,  what  a 
swelling.  .  .  . 

Comdex  Software 

Hiding  behind  a  mountain  of  clone  moth¬ 
erboards  were  a  few  important  pro¬ 
grammer  tools.  The  best  kept  secret 
had  to  be  GoScript,  an  impressive  $195 
PostScript  clone  from  LaserGo  Inc.  Feed 
it  a  megabyte  of  RAM  and  any  sup¬ 
ported  graphics-capable  printer  can 
print  like  a  LaserWriter.  With  every¬ 
body  else  skimming  the  cream,  Go- 
Script  could  become  the  Turbo  Pascal 
of  the  PostScript  world.  Sell  Adobe, 
quick. 

In  the  same  general  category  are 
Maxem’s  Cause  and  Clarion  Software’s 
Clarion,  two  application  generators 
slanted  toward  vertical-market  devel¬ 
opers.  Those  of  you  who  make  your 
living  creating  integrated  dog-kennel  man¬ 
agement  systems  had  better  abandon 
both  C  and  Pascal  — neither  is  necessary 
in  the  transaction-dominated  world  of 
vertical  markets,  where  everything’s  disk- 
bound  to  begin  with  and  performance 
is  not  a  compelling  consideration.  What 
either  product  can  do  in  a  weekend 
could  take  weeks  in  traditional  lan¬ 
guages,  with  results  that  are  solid  and 
attractive  if  not  blazingly  fast.  Cause 
provides  an  intriguing  portability  link 
between  the  PC  and  the  Mac  — prob¬ 
ably  the  best  I’ve  seen. 

The  sharpest  tool  I  encountered  at 
Comdex  was  not  even  “at”  Comdex  — 
the  company  was  not  exhibiting  and 
was  only  giving  private  demos  to  the 
programmer  press.  SoftTools  of  Atlanta 
demonstrated  CASE:W,  and  I  can  only 
characterize  it  as  the  sword  that  will  cut 
the  Gordian  knot  of  Microsoft’s  Win- 
dows/PM  API.  Basically,  CASE:W  is  a 
prototyping  tool  that  does  for  Windows 
and  PM  what  Bricklin’s  Demo  does  for 
DOS  text  screens.  Once  you  have  inter¬ 
actively  created  (via  point-and-drag)  your 
menus  and  menu  trees,  icons,  and  dia¬ 
log  boxes,  CASE:W  compiles  the  proto¬ 
type  to  a  C  source  file  containing  all  the 
hairy  stuff  of  a  Windows  application. 
Windows  is  an  object-friendly  environ¬ 
ment  that  dispatches  event  messages  to 
an  application,  which  must  parse  those 
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events  and  take  action.  Creating  the 
event  handler  is  the  tough  part,  and 
CASE:W  does  all  that.  The  output 
source  file  is  crisply  arranged  and  well- 
commented.  Even  I,  who  laid  C  aside 
years  ago  as  the  sorry  mess  it  is,  could 
pick  up  and  read  the  skeletal  event 
handler. 

CASE:W  is  a  C  tool  for  now,  but  noth¬ 
ing  would  prevent  SoftTools  (or  some 
other  firm)  from  doing  the  same  tool  for 
Modula-2  or  Pascal.  Time  saved:  Awe¬ 
some.  This  is  the  future,  guys.  Bone  up 
on  CASE  techniques  and  keep  your  eyes 
open.  In  the  thick  of  a  recession,  it 
could  save  your  skin. 

The  Text  Mode  Point  Spread 

Last  month  I  explained  how  to  use  BIOS 
calls  to  determine  which  of  the  several 
IBM  video  adapters  was  installed  in  a 
given  machine.  Why  is  this  useful?  The 
obvious  reason  is  to  determine  which 
of  the  numerous  graphics  modes  are 
legal  for  any  given  board.  But  graphics 
entirely  aside,  there  are  numerous  text- 
oriented  reasons  for  knowing  which 
adapter  is  on  the  bus. 

First  and  foremost  is  the  matter  of 
screen  size.  Most  people  who  have  gradu¬ 
ated  to  EGAs  or  VGAs  now  know  that 
PC  screens  are  not  immutably  limited  to 
25  lines.  The  EGA  can  display  25-and 
43-line  screens.  The  VGA  can  display 
25-,  28-,  and  50-line  screens.  Most  good 
programming  environments  (including 
Turbo  Pascal,  TopSpeed  Modula-2,  and 
QuickBasic)  can  make  use  of  the  larger 
screens,  and  with  some  care,  your  ap¬ 
plications  can  too. 

Screen  size  a  la  PC  is  a  peculiar 
concept  in  that  it  is  not  mode -depend¬ 
ent  but  font-dependent.  Understand  PC 
text  fonts,  and  you’ll  get  an  understand¬ 
ing  of  screen  size  along  for  free. 

The  first-generation  video  adapters, 
the  CGA  and  MDA,  have  only  one  font 
in  ROM.  The  CGA  font  is  an  8  x  8  font, 
meaning  that  each  character  in  the  font 
is  created  from  pixels  in  a  matrix  eight 
characters  high  by  eight  characters  wide. 
To  leave  space  between  horizontally 
adjacent  characters,  and  to  allow  for 
lower-case  descenders  on  characters  like 
p  and  q,  the  character  patterns  are  lim¬ 
ited  to  a  7  x  7  pixel  subset  of  the  8x8 
pixel  matrix. 

The  MDA  font  is  an  8  x  14  font  with  a 
twist:  The  rightmost  vertical  column  of 
pixels  within  the  font  is  duplicated  to  its 
own  right,  making  the  font  look  like  a  9 
x  14  font.  Since  in  all  but  the  line-draw 
characters  the  rightmost  column  is 
empty,  the  result  is  that  the  line-draw 
characters  are  “stretched”  so  that  they 
can  touch  one  another  in  the  horizontal 
direction,  while  allowing  a  little  extra 
horizontal  space  between  normal  char¬ 
acters.  This  is  done  with  electrical 


smoke  and  mirrors  within  the  MDA’s 
circuitry,  and  since  the  MDA’s  font  can’t 
be  modified  there  isn’t  much  more  to 
be  said  about  it. 

The  fun  starts  when  you  consider  the 
EGA.  The  EGA’s  default  font  is  also  8  x 
14,  but  without  the  MDA’s  ninth-inning 
stretch.  In  truth,  the  ASCII  characters  in 
the  EGA’s  default  font  are  limited  to  a  7 
x  9  pixel  subset  of  the  8  x  14  matrix. 
There  are  three  dead  pixels  below  the 
font’s  baseline,  and  two  dead  pixels 
above.  This  allows  true  2-pixel  descend¬ 
ers  to  be  used  on  lower-case  charac¬ 
ters,  and  also  provides  comfortable  ver¬ 
tical  spacing  between  character  rows 
on  the  screen.  The  characters  them¬ 
selves,  however,  are  not  much  better 
formed  than  the  CGA’s  crude  7x7 
patterns. 

The  EGA  contains  another  font  in 
ROM.  This  alternate  font  was  included 
to  allow  the  EGA  to  fully  emulate  the 
CGA,  and  is  thus  identical  to  the  CGA’s 
8x8  font.  This  font  can  be  loaded  in 
place  of  the  8  x  14  font,  and  when 
loaded,  whammo!  Your  screen  suddenly 
contains  43  lines  rather  than  25. 

How  so?  It’s  a  question  of  allocating 
scan  lines.  In  text  mode,  the  EGA 
places  350-scan  lines  on  the  screen.  If  it 
allocates  these  scan  lines  to  character 
rows  at  14-scan  lines  per  row,  you  can 
fit  25  lines  on  the  screen.  On  the  other 
hand,  if  you  allocate  the  scan  lines  to 
character  rows  at  8-scan  lines  per  row, 
you  get  43  lines  and  change.  The 
“change”  amounts  to  6-scan  lines  — 
about  all  the  EGA  ever  exhibits  of  “over¬ 
scan,”  what  we  used  to  call  the  “text 
border”  on  the  CGA.  In  the  default  mode, 
there  is  essentially  no  overscan.  (So 
everybody  puh-leez  stop  asking  me  how 
to  set  the  text  border  color  on  the  EGA!) 

Changing  fonts  trips  some  additional 
logic  within  the  EGA  that  tells  the  BIOS 
at  what  line  to  scroll  and  all,  but  in  the 
large  it’s  only  a  question  of  allocating  a 
fixed  number  of  scan  lines  in  two  dif¬ 
ferent  ways.  The  fonts  are  the  same 
width,  so  we  differentiate  them  by  their 
pixel  height.  This  is  sometimes  called 
the  fonts’  point  size,  but  it  has  little  to 
do  with  traditional  print  measurement 
by  points. 

PS/2  Complications 

In  keeping  with  IBM’s  “extend  but  don’t 
replace”  policy,  the  VGA  has  every¬ 
thing  that  the  CGA  and  EGA  have,  and 
then  some.  In  addition  to  both  the  8- 
and  14-pixel  fonts,  the  VGA  has  a  16- 
pixel  font,  which  is  its  default  font.  The 
VGA  puts  400  scan  lines  on  the  screen 
in  text  mode.  Allocate  those  lines  to  a 
16-pixel  font  and  you  get  25  lines.  Allo¬ 
cate  400  lines  to  a  14-pixel  font,  and 
you  get  28  lines.  Finally,  allocate  400 
lines  to  an  8-pixel  font,  and  you  get  50 


lines. 

The  MCGA,  which  is  the  VGA’s  devel- 
opmentally-handicapped  little  brother, 
has  a  stubborn  BIOS  that  understands 
only  the  1 6-pixel  font  and  will  refuse  to 
display  other  than  a  25-line  screen. 
There  are  rumored  methods  to  club  the 
BIOS  from  behind  and  do  the  work 
yourself,  but  having  neither  an  MCGA 
nor  much  respect  for  it,  I  haven’t  ex¬ 
plored  further. 

The  secret  to  determining  the  num¬ 
ber  of  lines  currently  on  the  screen  (and 
hence  the  size  of  the  current  screen 
buffer)  is  to  determine  what  font  is  cur¬ 
rent  loaded.  Once  you’ve  identified  the 
resident  adapter,  that  part  is  a  snap. 

Numerous  Enumerations 

In  my  last  column,  I  defined  an  enu¬ 
merated  type  encompassing  all  the  PC 
display  adapters. 

AdapterType  = 

(None, MDA, CGA, EGAMono, 

EGAColor,VGAMono,  VGAColor, 

MCGAMono,MCGAColor); 

Given  that  there  are  only  three  legal 
font  sizes,  it  makes  sense  to  enumerate 
them  as  well. 

FontSize  =  (Font8,Fontl4,Fontl6); 

Enumerated  types  help  your  code  to 
document  itself,  and  being  8-bit  quan¬ 
tities,  they  are  small  and  fast  compared 
to  hanging  string  tags  on  things  like 
display  adapters.  The  function  we’ll  use 
to  detect  the  current  font,  GetFontSize, 
will  return  a  value  of  type  FontSize. 

Most  display  adapters  only  support 
one  font  size,  which  can  be  reliably 
hard-coded  as  part  of  a  CASE  state¬ 
ment.  For  the  EGA  and  VGA,  font  size  is 
found  through  a  BIOS  call.  Video  inter¬ 
rupt  10H  has  a  service  that  returns  vari¬ 
ous  bits  of  information  about  the  cur¬ 
rent  video  state  in  the  registers.  The 
service  is  selected  with  11H  in  AH  and 
30H  in  AL.  On  return,  the  number  of 
pixels  in  the  current  font  will  be  found 
GetFontSize  is  contained  within  the 
Turbo  Pascal  unit  Textlnfo  in  Listing 
One  (textinfo.pas),  page  142. 

The  number  of  lines  on  a  screen  is  a 
function  of  the  adapter  type  and  the 
font  size.  This  suggests  that  a  two- 
dimensional  array  of  integers  can  be 
defined  such  that  indexing  into  the  ar¬ 
ray  with  the  adapter  type  and  the  font 
size  will  yield  the  number  of  lines  on  a 
screen  for  that  combination  of  adapter 
type  and  font  size.  Both  factors  are  pre¬ 
sent  as  enumerated  types,  and  enu¬ 
merated  types  may  index  arrays  in  both 
Pascal  and  Modula-2. 

This  is  the  algorithm  for  the  proce¬ 
dure  GetTextBufferStats,  also  in  Listing 
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One.  Line  counts  are  arranged  in  a  table 
that  comprises  the  beef  in  an  array  con¬ 
stant.  With  some  comments  to  show 
what  the  table  rows  and  columns  repre¬ 
sent,  it’s  an  example  of  creating  code 
that  is  truly  self-documenting,  in  that 
the  documentation  is  the  code.  The  al¬ 
ternative  is  to  thread  through  a  multiply- 
nested  IF  statement  that  would  admit¬ 
tedly  save  54  bytes  of  data  segment  but 
(in  addition  to  being  slower)  would  be 
a  great  deal  harder  to  read. 

Override! 

There’s  something  else  a  little  different 
about  GetTextBufferStats.  Its  CheckFor- 
Override  parameter  is  a  procedural  type. 
Procedural  types  have  always  existed 
in  Modula-2  and  have  only  recently  been 
added  to  Turbo  Pascal  with  version  5.0. 
What  happens  inside  GetTextBufferStats 
is  this:  The  number  of  characters  in  a 
line  is  returned  by  BIOS  VIDEO  service 
$F.  The  procedure  then  uses  Query- 
AdapterType  and  GetFontSize  to  derive 
a  screen-line  count  through  BIOS- 
based  methods  that  assume  one  of  the 
IBM  display  adapters  or  an  exact  clone. 

The  nature  of  the  PC  text  video  ar¬ 
chitecture,  however,  allows  stretching 
screen  extents  considerably.  Assuming 
that  a  refresh  buffer  begins  at  either 
$B000  (monochrome)  or  $B800 
(color),  it  may  be  mapped  any  conven¬ 
ient  way,  say,  132  x  43  or  80  x  40.  My 
own  display  is  the  absolutely  stunning 
Genius  VHR  401  display,  which  was  a 
desktop  publishing  display  (728  x  1004, 
portrait-style)  long  before  there  was  any 
such  thing  as  desktop  publishing.  It  has 
something  the  other  DTP  displays  don’t 
have:  a  large-format  monochrome  text 
mode  that  may  be  configured  as  80 
columns  by  the  standard  letter-paper- 
sized  66  lines,  or  by  70,  76,  or  83  lines 
as  desired.  Ten  minutes  with  that  tube 
will  make  you  wonder  why  we’ve  set¬ 
tled  for  25-line  brain-damaged  televi¬ 
sion  sets  for  so  long  — but  don’t  get  me 
started  on  that  particular  rant.  (You’ll 
hear  it  in  this  column  often  enough  in 
the  future.) 

The  point  is  that  there  may  be  dis¬ 
plays  that  support  more  than  the  IBM- 
supported  80  columns  and  50  rows  — 
or  some  oddball  values  in  between. 
132-column  text  displays  exist  for  spread¬ 
sheet  jockeys.  And  lord  only  knows 
what  can  be  done  with  a  PCjr  — a  ma¬ 
chine  so  bizarre  that  I  don’t  even  con¬ 
sider  it  IBM-compatible.  The  extended 
text  video  devices  that  I’ve  seen  (in¬ 
cluding  the  Genius)  always  “look  like” 
some  standard  IBM  board  from  a  BIOS 
and  control  level  to  keep  some  meas¬ 
ure  of  compatibility.  Only  the  character- 
to-refresh  buffer  mapping  differs.  To 
support  such  creatures,  you  need  to  be 


able  to  override  the  logic  in  GetTextBuffer¬ 
Stats  with  custom  logic  supplied  by  you 
or  someone  else.  This  can  be  done 
simply  by  executing  an  override  proce¬ 
dure  after  executing  GetTextBufferStats 
but  allowing  GetTextBufferStats  to  call 
the  override  procedure  itself  ensures 
that  the  job  will  be  done. 

The  override  procedure  should  per¬ 
form  its  own  display  detection  specific 
to  the  oddball  target  display,  and  if  the 
oddball  display  is  found,  the  override 
routine  can  replace  the  IBM-supported 
X  and  Y  extents  with  the  oddball  dis¬ 
play’s  X  and  Y  extents.  GetTextBuffer¬ 
Stats  then  calculates  the  screen  size  us¬ 
ing  the  overriding  values.  The  override 
procedure  NullOverride  provided  with 
the  Textlnfo  unit  does  nothing  at  all  — 
it  simply  lets  the  IBM-supported  values 
pass  unchanged.  I'll  provide  an  exam¬ 
ple  of  a  real  override  procedure  next 
month,  specific  to  the  Genius  VHR  dis¬ 
play. 

Note  that  its  use  of  procedural  pa¬ 
rameters  forces  Textlnfo  to  require  com¬ 
pilation  with  Turbo  Pascal  5.0. 

Odds  'n  Ends 

Textlnfo  exists  to  tell  us  important 
things  about  the  machine’s  display  in 
text  mode.  As  I  alluded  to  earlier,  there 
is  the  matter  of  the  starting  address  of 
the  video  refresh  buffer.  A  simple  rule 
applies  here:  Any  video  board  connected 
to  a  monochrome  display  keeps  its 
buffer  at  $B000,  and  any  board  con¬ 
nected  to  a  color  display  keeps  its 
buffer  at  $B800.  The  exceptions  are 
things  like  (blecch!)  black-and-white  TV 
sets,  or  those  awful  $69  composite 
video  monochrome  monitors  from  the 
dawn  of  PC  time.  Both  connect  only  to 
CGAs,  however,  so  the  buffer  remains 
at  $B800,  monochrome  notwithstand¬ 
ing.  Once  your  video  board  has  been 
correctly  detected,  the  GetTextBuffer- 
Origin  function  can  return  the  buffer’s 
address  without  fail. 

Similarly,  GetBIOSTextMode  returns 
the  current  text  mode  with  a  single 
BIOS  call.  This  is  handy  when  you  want 
to  move  into  a  specific  video  mode 
(perhaps  one  of  the  multitude  of  graph¬ 
ics  modes)  and  still  return  to  the  text 
mode  that  was  in  force  when  your  ap¬ 
plication  began  running. 

One  thing  Textlnfo  does  not  address 
is  how  many  pages  of  display  buffer 
memory  are  available  in  the  installed 
video  board.  The  VGA  has  as  many  as 
32,  while  the  poor  MDA  has  only  one. 
Some  clones  have  more  than  IBM 
boards,  some  less.  The  infuriating  thing 
is  that  I  have  yet  to  discover  a  reliable 
means  of  determining  how  many  pages 
are  available  in  the  installed  board  by 
inspection.  You  can  assume  that  a  CGA 


will  have  four  pages  .  .  .  and  you  could 
be  wrong.  The  clone  business  is  like 
that.  Any  clues?  This  boy  would  like  to 
know. 

Listing  Two  (texttest.pas),  page  143, 
is  a  short  program  that  exercises  Text¬ 
lnfo.  Listings  Three  and  Four  (textinfo.def 
and  textinfo.mod),  pages  143  and  144, 
are  the  TopSpeed  Modula-2  implementa¬ 
tion  of  Textlnfo.  (Both  the  definition 
and  implementation  modules,  which 
Turbo  Pascal  combines  in  one  unit  file.) 
Listing  Five  (texttest.mod),  page  146,  is 
the  test  program  in  Modula-2. 

Part  of  the  Plan 

One  of  the  reasons  I  picked  up  this 
column  is  that  my  compatriot  Kent  Por¬ 
ter  has  stepped  aside  to  kick  off  his 
graphics  column.  In  pondering  that,  it 
occurred  to  me  that  while  we  spend  a 
great  deal  of  effort  making  our  graphics 
screens  flashy  and  dynamic,  with  ex¬ 
ploding  icons  and  lord  knows  what 
else,  our  text  screens  are  content  to 
look  like  something  scraped  off  a  3278 
mainframe  terminal.  My  first  big  effort 
here,  consequently,  will  be  to  provide 
you  with  tools  to  allow  you  to  put  some 
flash  in  your  text  displays  as  well.  The 
fun’s  only  beginning.  In  the  coming 
months  I’ll  be  tossing  some  INLINE  di¬ 
rectives,  machine  code  externals,  and 
virtualized  screen  machines  your  way. 

In  the  meantime,  Mr.  Byte  and  I  are 
going  to  set  the  big  scope  out  in  the 
driveway  and  catch  the  opposition  of 
Jupiter,  who  always  looks  better  with  a 
few  belts.  Drink  in  the  night  when  you 
can,  my  friends  — the  stars  are  the  very 
best  antidote  for  a  frantic  life. 

Availability 

All  the  source  code  for  articles  in  this 
issue  is  available  on  a  single  disk.  To 
order,  send  $14.95  (Calif,  residents  add 
sales  tax)  to  Dr.  Dobb’s  Journal ,  501 
Galveston  Dr.,  Redwood  City,  CA  94063, 
or  call  800-356-2002  (inside  Calif.)  or 
800-533-4372  (outside  Calif.).  Please  spec¬ 
ify  the  issue  number  and  format  (MS- 
DOS,  Macintosh,  Kay  pro). 

DDJ 

(Listings  begin  on  page  142.) 

Vote  for  your  favorite  feature/article. 

Circle  Reader  Service  No.  14. 
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Software 
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C  PROGRAMMING 


Listing  One  (Text  begins  on  page  1 13) 


/* - 

♦include 

♦include 

♦include 

♦include 

♦include 

♦include 

♦include 

♦include 

♦include 

♦include 

♦include 

♦include 

♦include 

♦include 


■  smallcom.c 
<conio.h> 
<stdio.h> 
<mem . h> 
<string.h> 
<ctype .h> 
<dos .h> 
<stdlib.h> 
"window. h" 
"editor .h" 
"menu.h" 
"entry. h" 
"serial .h" 
"modem. h" 
"help.h" 


♦define  ANSWERTIMEOUT  60 
♦define  MAXSTRINGS  15 

♦define  carrier ()  (inp (MODEMSTATUS)  &  0x80) 

♦define  LOGFILE  "smallcom.log" 

♦define  HELPFILE  "smallcom.hlp" 

♦define  CFGFILE  "smallcom.cfg" 

♦define  ALT_P  153 
♦define  ALT_C  174 
♦define  CTRL_C  3 
♦define  WILDCARD  '?' 
static  union  REGS  rg; 

static  FILE  ‘logfp,  *uploadfp,  *downloadfp,  *cfg; 
static  int  running=l, connected, answering,  savebaud; 
int  filecount; 

extern  int  direct_connection,  TIMEOUT,  inserting; 
extern  char  spaces []; 
extern  struct  wn  wkw; 
extern  MENU  *mn; 

/* - prototypes - */ 

void  fileedit (char  *) ; 
static  void  displaycount (void) ; 
static  void  smallmenu (int) ; 
static  void  logserial (int) ; 
static  int  upload (int,  int); 
static  int  download(int,  int); 
static  int  call (int,  int); 
static  int  directory (int,  int); 
static  int  comeditor (int,  int); 
static  answer (int,  int); 
static  directcon (int,  int); 
static  int  loginput (int,  int); 
static  int  hangup(int,  int); 
static  int  quit (int,  int); 
static  int  prm(int,  int); 
static  void  loadp(void); 
static  int  savep(int,  int); 
static  void  set_parameters (void) ; 
static  int  get_filename (char  *); 
static  void  notice  (char  *); 
static  void  statusline (void) ; 
static  void  putch_window (int) ; 
void  upload_ASCII (FILE  *) ; 
void  download^ASCI I (FILE  *); 
int  keyhit (void) ; 

char  *prompt_line (char  *,  int,  char  *); 
void  reset_prompt (char  *,  int); 
static  int  testcarrier (void) ; 
static  int  waitforconnect (void) ; 
static  void  initcom(void) ; 
int  waitforresult (void) ; 
int  waitforstring (char  “,  int,  int); 
static  void  waitforcall (void) ; 
static  void  resetline (void) ; 

/* - the  hook  to  the  phone  directory - */ 

static  void  (*phone_directory) (void)  =  NULL; 

/* - the  hook  to  script  processors - */ 

void  (*script_processor) (void) ;  /*  filled  in  by  directory  */ 

/* - hooks  to  file  transfer  protocols - */ 

static  int  (*select_transfer_protocol) (void)  =  NULL; 

/* - up  to  five  upload  function  pointers - */ 

static  void  (*up_protocol [5] ) (FILE  *f ile_pointer)  =  { 
upload_ASCII,  NULL,  NULL,  NULL,  NULL 

}; 

/*  -  up  to  five  download  function  pointers  -  */ 

static  void  (*down_protocol [5] ) (FILE  *f ile_pointer)  =  { 
download_ASCII,  NULL,  NULL,  NULL,  NULL 

); 

/* - Files  menu - */ 

static  char  *fselcs[]  =  { 

"Log  Input  On/Off", 

"Upload  a  File", 

"Download  a  File", 

"Quit", 

NULL 

); 

static  char  *fhelps[]  =  ("log", "upload", "download", "quitcom") ; 

/* - Connect  menu - */ 

static  char  *cselcs[)  =  { 

"Place  Call", 

"Answer  Call", 

"Hang  up", 

"Direct  Connection", 

NULL 

) ; 

static  char  *chelps[]  =  { "call" , "answer", "hangup", "direct" } ; 

/* - Parameters  menu - */ 

static  char  *pselcs[]  =  { 

"Com  Port;  ", 

"Baud  Rate:  ", 

"Data  Bits:  ", 

"Stop  Bit (s)  :  ", 

"Parity:  ", 

"Mode  of  Dialing:  ", 


Listing  One  (Listing  continued,  text  begins  on  page  113  ) 

"Write  Parameters", 

NULL 

) ; 

static  char  *phelps[]  =  ( "port", "baud", "wordlen", "stopbits", 
"parity" , "dialmode" , "writecf g" } ; 

/* - menu  selection  function  tables - */ 

static  int  (*f funcs [ ] ) ()  =  (loginput, upload, download, quit) ; 
static  int  (*cfuncs [] ) ()  =  (call, answer, hangup, directcon } ; 
static  int  (‘pfuncs  [ ) )  ()  =  (prm,prm,prm,prm,prm, prm, savep) ; 
static  int  (‘efuncs [ ] ) ()  =  (comeditor); 
static  int  (‘dfuncs [ j ) ()  =  (directory); 

/*  -  horizontal  prompt  messages  -  */ 

char  fdesc [ ] ="Message  File  Operations"; 

char  cdesc [] “"Connections  to  Remote  Processor"; 

char  pdesc[]="Set  Communications  Parameters  for  Program  Start"; 

char  edesc [ ] “"Edit  a  Text  File"; 

char  ddesc[)="The  SMALLCOM  Telephone  Directory"; 

/* - horizontal  menu  bar - */ 

static  MENU  cmn  []  =  { 

("File",  fdesc,  fselcs,  fhelps,  "ludq",  ffuncs,  0), 

("Connect",  cdesc,  cselcs,  chelps,  "pahd",  cfuncs,  0), 

("Parameters",  pdesc,  pselcs,  phelps,  "cbdspmw",  pfuncs,  0), 

"  edesc,  NULL,  NULL,  "e",  efuncs,  0), 

ddesc,  NULL,  NULL,  "d",  dfuncs,  0), 


( "Editor" 

( "Directory" 
(NULL) 


/*  -  filename  data  entry  template  and  buffer 

static  char  filename [ 65) ,  filemask (65) ; 
static  FIELD  f n_template [ ]  =  { 

(2,14,1, filename, filemask, NULL) , 

(0) 


/* - modem  result  codes - */ 

static  char  ‘results []  =  ( 

"\r\nOK\r\n", 

"\r\nCONNECT\r\n" , 

"\r\nRING\r\n", 

"\r\nNO  CARRIER\r\n", 

"\r\nERROR\r\n", 

"\r\nCONNECT  1200\r\n", 

"\r\nNO  DIALTONE\r\n", 

"\r\nBUSY\r\n", 

"\r\nNO  ANSWER\r\n" , 

"\r\n\r\n", 

"\r\nCONNECT  2400\r\n", 

NULL 

); 

extern  int  COMPORT, PARITY, STOPBITS, WORDLEN, BAUD; 
extern  char  DIAL [ ) ,  PHONENOO; 

/*  ===============  MAIN  ==================  */ 

void  main (void) 

( 

int  c; 
char  ‘re¬ 
inserting  =  FALSE; 
load_help (HELPFILE) ; 
loadp ( ) ; 

savebaud  =  BAUD; 
set_parameters ()  ; 
clear_screen ()  ; 
mb  =  display_menubar (cmn) ; 

establish_window (1, 2, 80, 24, TEXTFG, TEXTBG, TRUE) ; 

statusline () ; 

initcomO  ; 

gotoxy (2,2) ; 

while  (running)  { 

set_help ("smallcom") ; 
testcarrier () ; 
if  (keyhit ())  ( 

switch  (c  =  getkeyO)  ( 


case 

F10 : 

smallmenu (0) ; 

break; 

case 

ALT  F: 

smallmenu (1) ; 

break; 

case 

ALT  C: 

smallmenu (2) ; 

break; 

case 

ALT  P: 

smallmenu (3) ; 

break; 

case 

ALT  E: 

smallmenu (4) ; 

break; 

case 

ALT  D: 

smallmenu (5) ; 

break; 

case 

CTRL  C: 

:clear_window() ; 

wkw.wx  =  wkw.wy  =  0; 

gotoxy  (2,2) ; 

break; 

quit (1,1) ; 

break; 

if  (!(c  &  0x80)  &&  connected) 
if  (answering 

I |  direct_connection) 
logserial (c==' \r' V \n' :c) 
writecomm (c) ; 
if  (c  ==  ' \r' ) 

writecomm (' \n' ) ; 


) 


break; 


} 

if  (input_char_ready () )  ( 

logserial  (c  =  readcommO); 
if  (answering) 

writecomm (c) ; 

} 

) 

if  (connected) 
hangup (1,1); 
release_modem ( ) ; 
restore_menubar (mb) ; 
delete_window ( ) ; 
clear_screen () ; 

) 

/* - - - execute  the  SMALLCOM  menu 

static  void  smallmenu (int  n) 

{ 

window (1,25, 80, 25) ; 
gotoxy (1, 1) ; 
cprintf (spaces) ; 
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putch('  '); 
current_window () ; 
menu_select (cmn,  n) ; 
set_parameters () ; 
statusline () ; 

gotoxy (wkw. wx+2,  wkw.wy+2); 

} 

/* - Call  menu  command - */ 

static  int  call(hs,  vs) 

{ 

if  (! connected)  { 

notice ("Dialing") ; 
placecall {) ; 
sleep (4) ; 
delete_window ( ) ; 

if  ((connected  =  waitforconnect () )  ==  FALSE)  { 
statusline () ; 
initmodemO  ; 

) 

else  if  (script_processor) 

(*script_processor) () ; 

) 

return  TRUE; 

} 

/* - Direct  Connection  menu  command - */ 

static  int  directcon (hs,  vs) 

{ 

direct_connection  A=  1; 
connected  |=  direct_connection; 
return  TRUE; 

) 

/* - Hangup  menu  command - */ 

static  int  hangup (hs,  vs) 

{ 

if  (connected)  ( 

notice ("Hanging  up"); 
reset line () ; 
delete_window ( ) ; 

} 

return  TRUE; 

} 

/*  - Quit  menu  command - */ 

static  int  quit(hs,  vs) 

{ 

int  c  =  0; 

notice ("Exit  to  DOS?  "); 
c  =  getkey () ; 
delete_window() ; 
running  =  (tolower(c)  !  =  '  y' ); 
return  TRUE; 

) 

/* - Log  Input  menu  command - */ 

static  int  loginput(hs,  vs) 

{ 

if  (logfp  ==  NULL) 

logfp  =  fopen (LOGFILE,  "ab"); 
else  { 

fclose (logfp) ; 
logfp  =  NULL; 

) 

return  TRUE; 

} 

/* - Upload  file  menu  command - */ 

static  int  upload(hs,  vs) 

{ 

int  pr  =  0; 
if  ((connected)  { 

error_message ( "Not  connected" ) ; 
return  FALSE; 

} 

if  (uploadfp  ==  NULL)  ( 

setmem(filename,  sizeof  filename  -  1,  '  '); 
setmem(filemask,  sizeof  filemask  -  1,  '_'); 
if  (get_filename ("  Upload  what  file?  ")  !=  ESC)  ( 
if  ((uploadfp  =  fopen (filename,  "rb"))  ==  NULL) 
error_message ("Cannot  open  file"); 
else  { 

statusline () ; 

if  (select_transfer_protocol) 

pr  =  (*select_transfer_protocol) () ; 
(*up__protocol  [pr] )  (uploadfp)  ; 
fclose (uploadfp) ; 
uploadfp  =  NULL; 


/*  -  upload  a  file  with  ASCII  transfer  protocol  -  */ 

void  upload_ASCI I (FILE  *fp) 

{ 

int  c; 

while  ((c  =  fgetc(fp))  !=  EOF)  ( 
writecomm(c) ; 
displaycount () ; 
if  (input_char_ready () ) 
logserial  (readcommO ) ; 
if  (keyhitO) 

if  (getch()  ==  ESC) 
break; 

if  ( Itestcarrier () ) 
break; 

) 

filecount  =  0; 
if  (connected) 

writecomm (EOF) ; 

} 

/* - Download  file  menu  command - */ 

static  int  download (hs,  vs) 

{ 


int  pr  =  0,  save_timeout; 
if  ((connected)  { 

error_message ("Not  connected") ; 
return  FALSE; 

} 

setmem (filename,  sizeof  filename  -  1,  '  '); 
setmem( filemask,  sizeof  filemask  -  1,  '_'); 
if  (get_filename ("  Download  what  file?  ")  !=  ESC)  { 
downloadfp  =  fopen (filename,  "wb") ; 
statusline () ; 

if  (select_transfer_protocol) 

pr  =  (*select_transfer_protocol) () ; 
save_timeout  =  TIMEOUT; 

TIMEOUT  =  60; 

(*down_protocol [pr] ) (downloadfp) ; 

TIMEOUT  =  save_timeout; 
fclose (downloadfp) ; 
downloadfp  =  NULL; 

} 

return  TRUE; 

) 

/*  -  download  a  file  with  ASCII  transfer  protocol  -  */ 

void  download_ASCII (FILE  *fp) 

{ 

int  c  =  0; 
while  (TRUE)  { 

if  (keyhitO)  ( 

if  ( (c  =  getkey () )  ==  ESC) 
break; 

writecomm (c) ; 
if  ((answering) 

logserial  (readcommO  )  ; 

I 

c  =  readcommO  &  127; 
if  (c  ==  0  ||  c  ==  0x7f ) 
break; 

fputc(c,  fp) ; 
displaycount () ; 
if  ( itestcarrier () ) 
break; 

} 

} 

/*  -  echo  modem  input  and  write  to  the  log  if  selected  -  */ 

static  void  logserial (int  c) 

{ 

putch_window(c)  ; 
if  (logfp) 

fputc(c,  logfp); 

} 

/* - read  a  file  name - */ 

static  int  get_f ilename (char  *ttl) 


{ 

int  rtn; 

e  s t  abl i s  h_w i ndow ( 1 , 2  3 , 8  0 , 2  5 , ENTRYFG , ENTRYBG , TRUE ) ; 
window_title (ttl) ; 
gotoxy (3,2) ; 
cputs("File  name:"); 

rtn  =  data_entry (fn_template,  TRUE,  1); 
delete_window () ; 
return  rtn; 

) 

/* - small  message - * / 

static  void  notice (char  *s) 

{ 


int  If  =  (80-strlen (s) ) /2-1; 
int  rt  =  lf+strlen(s)+2; 

establish_window (If, 11, rt, 13, HELPFG, HELPBG,  TRUE) ; 
gotoxy (2,2); 
cputs  (s) ; 

) 

/*  -  comm  and  modem  parameter  menu  commands  -  */ 

static  int  prm(hs,  vs) 

I 


switch  (vs) 
case  1: 

case  2: 

case  3: 
case  4: 
case  5: 

case  6: 


{ 

COMPORT  A=  3; 
break; 

BAUD  *=  2; 
if  (BAUD  ==  220) 
BAUD  =  150; 
if  (BAUD  ==  4800) 
BAUD  =  110; 
break; 

WORDLEN  A=  Oxf; 
break; 

STOPBITS  A=  3; 
break; 

if  (++PARITY  ==  3) 
PARITY  =  0; 
break; 

DIAL [3]  =  DIAL [3] 
break; 


/*  flip  between  1  and  2  */ 

/*  110,150,300,  */ 

/*  600,1200,2400  */ 

/*  flip  between  7  and  8  */ 
/*  flip  between  1  and  2  */ 
/*  0,  1,  2  */ 


==  ' x'  ?  ' P'  :  '  T' ; 


default : 


break; 

) 

setparameters () ; 
return  FALSE; 

} 

/* - post  the  parameters  into  the  menu  display - */ 

static  void  set_parameters (void) 

{ 

static  char  *pars[]  =  ("None",  "  Odd",  "Even"}; 
static  char  *mode[]  =  ("Pulse",  "  Tone"}; 
pselcs [0] [strlen (pselcs [0] ) -1]  =  '0'  +  COMPORT; 
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sprintf (spselcs [1] [strlen (pselcs [1] ) -4] , "%4d", BAUD) ; 

"  %s  Line  %s  %s  %s  %-12.12s  %-14 

14s  F10:Menu", 

pselcs[2] (strlen {pselcs [2] ) -1 ]  =  'O'  +  WORDLEN; 

(connected  ?  "  On" 

"Off"), 

pselcs [3] [strlen (pselcs [3] ) -1]  =  'O'  +  STOPBITS; 

(direct  connection  ?  "Direct" 

"  "), 

sprintf (&pselcs [4 ] [strlen (pselcs [ 4] ) -4 ) , "%s", pars [PARITY] ) ; 

(logfp  ?  "Logging" 

"  "), 

sprintf (&pselcs [5J [strlen (pselcs [5] ) -5] ,  "%s". 

((answering  &  ! connected) 

mode[DIAL[3]=='T'  ] ) ; 

?  "Answering  " 

) 

uploadfp  ?  "Uploading  " 

/* - load  the  configuration  file - */ 

downloadfp  ?  "Downloading" 

"  "), 

static  void  loadp(void) 

(uploadfp | | downloadfp  ?  filename 

"  "), 

{ 

* PHONENO  ?  PHONENO  :  "No  Phone  #"); 

if  ( (cfg  =  fopen (CFGFILE,  "r"))  !=  NULL)  { 

st  =  prompt  line (stat,  25,  st) ; 

fscanf (cfg, "%d  %d  %d  %d  %d  %c  %s". 

1 

& COMPORT, &PARITY, &STOPBITS, & WORDLEN, 4 BAUD, &DIAL[3] , 

/* - write  the  file  count  into  the  status  line - */ 

& PHONENO [0] ) ; 

static  void  displaycount (void) 

f close (cfg) ; 

{ 

1 

f ilecount++; 

} 

if  ((filecount  %  10)  ==  0)  { 

/* - Write  Parameters  menu  command - */ 

window (1,25,80,25); 

static  int  savep(hs,  vs) 

textcolor (MENUFG) ; 

( 

textbackground(MENUBG) ; 

cfg  =  fopen (CFGFILE,  "w"); 

gotoxy (50, 1) ; 

fprintf(cfg,  "%d  %d  %d  %d  %d  %c  %s". 

cprintf ("%5d",  filecount); 

COMPORT, PARITY, STOPBITS, WORDLEN, BAUD, DIAL [ 3 ] , PHONENO) ; 

current  window (); 

fclose (cfg) ; 

gotoxy (wkw.wx+2,  wkw.wy+2); 

initcom ( ) ; 

) 

return  FALSE; 

) 

) 

/*  -  write  a  one-liner  prompt  saving  video 

memory - */ 

/* - Editor  menu  command - */ 

char  ‘prompt  line (char  *s,  int  y,  char  *t) 

static  int  comeditor (hs,  vs) 

< 

{ 

if  (t  =  NULL) 

extern  int  MAXLINES,  inserting; 

if  ((t  =  malloc (160) )  !=  NULL) 

MAXLINES  =  800; 

get text ( 1, y, 80, y, t) ; 

mn  -  NULL; 

window (1, y, 80,  y) ; 

f ileedit ("") ; 

textcolor (MENUFG) ; 

inserting  =  FALSE; 

textbackground (MENUBG) ; 

insert  line(); 

gotoxy (1,1) ; 

return  TRUE; 

cprintf (spaces) ; 

} 

putch ( '  ' ) ; 

/* - Directory  menu  command - */ 

gotoxy (1, 1) ; 

static  int  directory (hs,  vs) 

cprintf (s) ; 

{ 

current  window (); 

if  (phone  directory)  { 

return  t; 

mn  -  NULL; 

} 

(*phone  directory)  () ; 

/*  -  reset  the  one-liner  prompt  line  - 

- */ 

) 

void  reset_prompt (char  *s,  int  y) 

return  TRUE; 

{ 

} 

puttext (1, y, 80,  y,  s) ; 

/* - display  a  status  line - */ 

free (s) ; 

static  void  statusline (void) 

) 

{ 

/* - write  a  character  to  the  user's  window - */ 

char  stat[81]; 

static  void  putch  window (int  c) 

static  char  *st  =  NULL; 
sprintf (stat. 

(continued  on  page  136) 
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C  PROGRAMMING 


listing  One  (Listing  continued,  text  begins  on  page  113  ) 


gotoxy (wkw.wx+2,  wkw.wy+2); 
switch  (c)  { 

case  '\t':  while  (wkw.wx  %  4) 

putch_window ( '  ' ) ; 
break; 

case  '  \b' :  if  (wkw.wx) 

— wkw.wx; 
break; 

default:  putch(c); 

wkw. wx++; 

if  (wkw.wx  <  wkw.wd-2) 
break; 

case  '\n':  if  (wkw.wy  <  wkw.ht-1) 
wkw.wy++; 
else  ( 

scroll_window(l) ; 

writeline (2,  wkw.wy+2,  spaces+1); 

) 

case  '\r':  wkw.wx  =  0; 


gotoxy (wkw.wx+2,  wkw.wy+2); 

} 

/* - wait  for  a  call  -  */ 

static  void  waitforcall (void) 

{ 

answercall () ; 

if  ((connected  =  answering  =  waitforconnect () )  ==  FALSE)  ( 
statusline () ; 
initmodemO ; 

} 

} 

/*  -  wait  for  a  line  connection,  reset  baud  rate  -  */ 

static  int  waitforconnect (void) 

( 

extern  int  BAUD; 
int  baud  =  0; 
while  (baud  ==  0) 

switch  (waitforresult () )  { 


case  1:  baud  =  300;  break;  /*  CONNECT  */ 
case  5:  baud  =  1200;  break;  /*  CONNECT  1200  */ 
case  10:  baud  =  2400;  break;  /*  CONNECT  2400  */ 
case  0:  /*  OK  */ 
case  2:  break;  /*  RING  */ 
case  3:  /*  NO  CARRIER  */ 
case  4:  /*  ERROR  */ 
case  7:  /*  BUSY  */ 
case  8:  /*  NO  ANSWER  */ 
case  -1:  baud  =  -1;  break;  /*  time-out  */ 


default:  break;  /*  anything  else  */ 

) 

if  (baud  ! =  -1  &&  baud  !«  BAUD)  ( 
savebaud  =  BAUD; 

BAUD  =  baud; 
initcomport () ; 

) 

return  (baud  !=  -1); 

} 

/*  -  wait  for  a  modem  result  (0-10) .  -1  if  timed  out  -  */ 

int  waitforresult (void) 

{ 

return  waitforstring (results,  ANSWERTIMEOUT,  0); 

} 

/* - wait  for  a  string  from  the  serial  port - */ 

int  waitforstring (char  *tbl[],  int  wait,  int  wildcard) 

{ 

int  c,  i,  done  =  FALSE; 
char  *sr [MAXSTRINGS] ; 
for  (i  =  0;  tbl[i]  !«  NULL;  i++) 
sr(i]  =  tbl t i ] ; 
while  (!done)  { 
set_timer (wait) ; 
while  (!input_char_ready() )  { 
if  (timed_out () ) 
return  -1; 
if  (keyhitO) 

if  (<c  =  getkeyO)  —  ESC) 
return  -1; 

) 

logserial(c  =  readcommO); 
for  (i  =  0;  tbl [i]  !=  NULL;  i++)  { 

if  (c==* (sr (ij )  || 

(wildcard  &&  * (sr [i] ) ==wildcard) )  { 

if  (*  (++  (sr [i] ) )  ==  '\0')  { 

done  =  TRUE; 
break; 

) 

} 

else 

sr [i]  =  tbl [i] ; 

I 

) 

return  i; 

) 

/*  -  initialize  from  serial  and  modem  parameters  -  */ 

static  void  initcom(void) 

( 

notice ("Initializing  Modem"); 
initmodem () ; 
deletewindow ( ) ; 

} 

/* - test  carrier  detect - * / 

static  int  testcarrier (void) 

{ 

if  ( !direct_connection  &&  connected  &&  carrier ()  ==  FALSE) 
reset line () ; 
return  connected; 

} 

/* - disconnect  and  reestablish  the  serial  port - */ 

static  void  resetline (void) 

{ 


answering  =  connected  =  FALSE; 
statusline () ; 
disconnect () ; 

BAUD  =  savebaud; 
initcomport ()  ; 

} 

/* - answer  a  call - */ 

static  int  answer (hs,  vs) 

( 

answering  =  1; 
statusline () ; 

gotoxy (wkw.wx+2,  wkw.wy+2); 
waitforcall () ; 
return  TRUE; 

) 

#if  COMPILER==TURBOC 

/* - use  bios  to  test  for  a  keystroke 

int  keyhit (void) 

{ 

rg.h.ah  =  1; 

int86(0xl6,  Srg,  &rg) ; 

return  ((rg.x. flags  &  0x40)  ==  0)  ; 

) 

#endif 


End  Listing  One 


Listing  Two 

smallcom  (serial.h, modem. h, editor .h, window. h, menu. h, entry. h, help. h) 

editshel  (editor. h,  menu.h,  entry. h,  help.h,  window. h) 

editor  (editor. h,  window. h) 

help  (help.h,  window. h) 

modem  (serial.h,  modem. h) 

serial  (serial.h) 

entry  (entry. h,  window. h) 

menu  (menu.h,  window. h) 

window  (window. h) 


End  Listing  Two 


Listing  Three 


#  SMALLCOM. MAK:  make  file  for  SMALLCOM . EXE  with  Microsoft  C/MASM 

# 

.c.obj : 

Cl  /DMSOFT=l  /DTURBOC=2  / DCOMP I LER=MSOFT  -c  -W3  -Gs  -AC  $*.C 

smallcom. obj  :  smallcom. c  serial.h  modem. h  menu.h  entry. h  \ 
help.h  window. h 

modem. obj  :  modem. c  serial.h  modem. h 
serial. obj  :  serial. c  serial.h 
entry. obj  :  entry. c  entry. h  window. h 
menu. obj  :  menu.c  menu.h  window. h 
help. obj  :  help.c  help.h  window. h 

editshel. obj  :  editshel. c  editor. h  menu.h  entry. h  help.h  \ 
window. h 

editor. obj  :  editor. c  editor. h  window. h 

window. obj  :  window. c  window. h 

microsft.obj  :  microsft.c 

vpeek.obj  :  vpeek.asm 
masm  /MX  vpeek; 

keyhit. obj  :  keyhit. asm 
masm  /MX  keyhit; 

smallcom.exe  :  smallcom. obj  modem. obj  serial. obj  editor. obj  \ 
editshel. obj  entry. obj  menu. obj  help. obj  \ 
window. obj  keyhit. obj  vpeek.obj  microsft.obj 
link  8 smallcom.  ink  End  Listing  Three 

Listing  Four 

smallcom+ 

modem+ 

serial+ 

entry+ 

menu+ 

editor+ 

editshel+ 

help+ 

window+ 

vpeek+ 

keyhit+ 

microsft 

smallcom 

nul 

\lib\clibce 


End  Listings 
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GRAPHICS  PROGRAMMING 


Listing  One  (Text  begins  on  page  1 18.) 

1|  void  far  draw_line  (int  xl,  int  yl,  int  x2,  int  y2) 

2 |  /*  Bresenham  line  drawing  algorithm  */ 

3 |  /*  xl,  yl  and  x2,  y2  are  end  points  */ 

41  { 

5 |  int  w,  h,  d,  dxd,  dyd,  dxn,  dyn,  dine,  ndinc,  p; 


6 1 

7  1 

register  x,  y; 

8| 

/*  Set  up  */ 

91 

x  =  xl;  y  =  yl; 

/*  start  of  line 

*/ 

101 

w  =  x2  -  xl; 

/*  width  domain  of  line 

*/ 

HI 

h  =  y2  -  yl; 

/*  height  domain  of  line 

*/ 

12 1 

131 

/*  Determine  drawing  direction  */ 

14| 

if  (w  <  0)  { 

/*  drawing  right  to  left 

*/ 

15| 

w  =  -w; 

/*  absolute  width 

*/ 

16| 

dxd  =  -1; 

/*  x  increment  is  negative 

*/ 

17  | 

}  else 

/*  drawing  left  to  right 

*/ 

18| 

dxd  =  1; 

/*  so  x  incr  is  positive 

V 

19| 

if  (h  <  0)  ( 

/*  drawing  bottom  to  top 

*/ 

20  | 

h  =  -h; 

/*  so  get  absolute  height 

*/ 

21 1 

dyd  =  -1; 

/*  y  incr  is  negative 

*/ 

22  | 

)  else 

/*  drawing  top  to  bottom 

*/ 

231 

dyd  =  1; 

/*  so  y  incr  is  positive 

*/ 

24  | 

25| 

/*  Determine  major 

axis  of  motion  */ 

261 

if  (w  <  h)  { 

/*  major  axis  is  Y 

*/ 

27 1 

p  =  h,  h  =  w,  w  = 

p;  /*  exchange  height  and  width 

*/ 

281 

dxn  =  0; 

29| 

dyn  =  dyd; 

301 

)  else  { 

/*  major  axis  is  X 

*/ 

311 

dxn  =  dxd; 

32| 

dyn  =  0; 

33| 

) 

34| 

351 

/*  Set  control  variables  */ 

36| 

ndinc  =  h  *  2; 

/*  Non-diagonal  increment 

*/ 

37| 

d  =  ndinc  -  w; 

/*  pixel  selection  variable 

*/ 

38| 

dine  =  d  -  w; 

/*  Diagonal  increment 

*/ 

39| 

40  | 

/*  Loop  to  draw  the 

line  */ 

41 1 

for  (p  =  0;  p  <=  w; 

P++)  { 

42| 

draw_point  (x,  y) 

431 

if  (d  <  0)  { 

/*  step  non-diagonally 

*/ 

44| 

x  +=  dxn; 

45| 

y  +=  dyn; 

46| 

d  +=  ndinc; 

47  | 

)  else  ( 

/*  step  diagonally 

*/ 

48  | 

x  +=  dxd; 

49| 

y  +=  dyd; 

501 

d  +=  dine; 

511 

) 

521 

) 

531 

) 

End  Listing  One 


Listing  Two 


/*  SPOKES. C:  Bresenham  demo  */ 

/*  Multicolored  spokes  emanate  from  center  of  screen  */ 

♦include  <conio.h> 

♦include  <stdio.h> 

♦include  "grafix.h" 

♦define  CX  320  /*  Center  of  screen  */ 

♦define  CY  175 

void  main() 

{ 

int  x,  y,  color  =  1,  next  (int); 
if  (initvideo  (EGA) )  { 

/*  Spokes  from  center  to  top  and  bottom  */ 

for  (x  =  0;  x  <=  640;  x  +=  80)  { 
color  =  next  (color); 
draw_line  (x,  0,  CX,  CY) ; 
color  =  next  (color); 
drawline  (x,  349,  CX,  CY) ; 

} 

/*  Spokes  from  center  to  sides  */ 

for  (y  =  70;  y  <  350;  y  +=  70)  ( 
color  =  next  (color) ; 
draw  line  (639,  y,  CX,  CY) ; 
color  =  next  (color) ; 
draw_line  (0,  y,  CX,  CY); 

} 

getchO;  /*  Wait  for  a  keystroke  */ 

)  else 

puts  ("EGA  not  present  in  system:  program  ended"); 

)  /* - */ 

int  next  (int  hue)  /*  set/return  next  color  */ 

{ 

set_colorl  (hue++) ; 

return  ( (hue  >  15)  ?  1  :  hue) ;  /*  wrap  around  */ 


End  Listing  Two 


listing  Three 

1|  void  far  draw_rect  (int  xleft,  int  ytop,  int  w,  int  h) 

2 |  /*  Draw  outline  rectangle  in  colorl  from  top  left  corner  */ 


3 |  /*  w  and  h  are  width  and  height  */ 

4 |  /*  xleft  and  ytop  are  top  left  corner  */ 

51  { 

6 |  draw_line  (xleft,  ytop,  xleft+w,  ytop);  /*  top  */ 

7 j  draw_line  (xleft+w,  ytop,  xleft+w,  ytop+h) ;  /*  right  */ 

8 |  draw_line  (xleft+w,  ytop+h,  xleft,  ytop+h);  /*  bottom  */ 

9|  draw_line  (xleft,  ytop+h,  xleft,  ytop);  /*  left  */ 

10|  )  /* - */ 

111 

12 |  void  far  polyline  (int  edges,  int  vertex[]) 

13 |  /*  Draw  multipoint  line  of  n  edges  from  n+1  vertices  where:  */ 

14 |  /*  vertex  [0]  =  xO  vertex  [1]  =  yO  */ 

15|  /*  vertex  [2]  =  xl  vertex  [3]  =  yl  */ 

16|  /*  etc.  */ 


171  { 

18|  int  xl,  yl,  x2,  y2,  v; 

191 

20|  xl  —  vertex [0]; 

21|  yl  =  vertex [1]; 

22 |  for  (v  =  2;  v  <  (edges+l)*2;  v+=  2)  ( 

23|  x2  =  vertex [v] ; 

24 |  y2  =  vertex[v+l]; 

25|  draw_line  (xl,  yl,  x2,  y2); 

26|  xl  =  x2; 

27|  yl  =  y2; 

281  ) 

291  }  /* - */ 

End  Listing  Three 

Listing  Four 


/*  BOXES. C:  Demo  of  draw_rect()  in  GRAFIX.LIB  */ 
/*  Draws  a  big  rectangle  and  four  smaller  ones  */ 
/*  K.  Porter,  DDJ  Graphics  Programming  Column,  March  89  */ 
/* - */ 


♦include  <conio.h> 

♦include  "grafix.h" 

main  () 

( 

if  (init_video  (EGA))  ( 
setcolorl  (15); 
draw_rect  (100,  100,  440,  230); 

set_colorl  (14); 

draw_rect  (110,  110,  420,  30); 

set_colorl  (13); 

draw_rect  (110,  105,  220,  220); 

set_colorl  (12); 

draw_rect  (340,  150,  190,  100); 

set_colorl  (11); 

draw_rect  (340,  260,  190,  60); 

getch();  /*  wait  for  keystroke  */ 

) 

) 


End  listing  Four 


Listing  Five 


/*  STAR.C:  Draws  a  star  using  polyline  */ 

♦include  <conio.h> 

♦include  "grafix.h" 

int  vert  []  =  (  /*  vertices  of  star  */ 

320,  60,  420,280,  150,140, 

490,140,  220,280,  320,  60 

}; 

void  main  () 

( 

if  (init_video  (EGA))  ( 

polyline  (5,  vert);  /*  draw  */ 

getch();  /*  wait  for  key  */ 

) 

) 

End  listing  Five 

Listing  Six  (Listing  continued,  text  begins  on  page  118.) 


;  HLINE.ASM:  Fast  horizontal  line  drawing  routine 
;  Uses  6845  Write  Mode  0  to  update  8  pixels  at  a  time  on  EGA/VGA 
;  C  prototype  is 

;  void  far  hline  (int  x,  int  y,  int  length_in_pixels) ; 

;  Writes  in  current  colorl  from  GRAFIX.LIB 
;  Microsoft  MASM  5.1 

;  K.  Porter,  DDJ  Graphics  Programming  Column,  March  89 

.MODEL  LARGE 
.CODE 

PUBLIC  _hline 

EXTRN  _colorl  :  BYTE  ;  Current  palette  reg  for  pixel 

EXTRN  _draw_point  :  PROC  ;  Pixel  writing  routine 
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;  Declare  arguments  passed  by  caller 


X 

EQU 

[bp+6] 

y 

EQU 

[bp+8] 

len 

EQU 

(bp+10] 

;  Declare  auto 

variables 

last 

EQU 

[bp-  2] 

;  Last  byte  to  write 

solbits 

EQU 

[bp-  4] 

;  Mask  for  start  of  line 

oddsol 

EQU 

[bp-  6) 

;  #  odd  bits  at  start  of  line 

eolbits 

EQU 

[bp-  8] 

;  Mask  for  end  of  line 

.  _ 

oddeol 

EQU 

[bp-10] 

;  ♦  odd  bits  at  end  of  line 

hline 

PROC  FAR 

;  ENTRY  POINT  TO  PROC 

push 

bp 

;  entry  processing 

mov 

bp,  sp 

sub 

sp,  10 

;  make  room  for  auto  variables 

xor 

ax,  ax 

;  initialize  auto  variables 

mov 

last,  ax 

mov 

solbits. 

ax 

mov 

oddsol. 

ax 

mov 

eolbits, 

ax 

mov 

oddeol. 

ax 

;  Do  nothing  if 

line  length  is  zero 

mov 

bx,  len 

;  get  line  length 

cmp 

bx,  0 

;  length  =  0? 

jnz 

chlen 

;  if  not,  go  on 

jmp 

quit 

;  else  nothing  to  draw 

;  Call 

draw  point  ()  with 

a  loop  if  line 

length  <  8 

chlen: 

cmp 

bx,  8 

jnb 

wmO 

;  go  if  len  >=  8 

mov 

ax,  y 

;  get  args 

mov 

cx,  X 

drpt : 

push 

bx 

;  push  remaining  length 

push 

ax 

;  push  args  to  draw_point() 

push 

cx 

call 

draw  point 

;  draw  next  pixel 

pop 

cx 

;  clear  args  from  stack 

pop 

ax 

pop 

bx 

;  fetch  remaining  length 

inc 

cx 

;  next  x 

dec 

bx 

;  count  pixel  drawn 

jnz 

drpt 

;  loop  until  thru 

jmp 

quit 

;  then  exit 

;  Set  6845  for  write  mode  0,  all  planes  enabled,  color  selected 


mO :  mov 

dx,  03CEh 

mov 

ax,  0005h 

;  Set  write  mode 

out 

dx,  ax 

mov 

ax,  OFFOOh 

;  Set/Reset  reg,  enable  all  planes 

out 

dx,  ax 

mov 

ax,  OFFOlh 

;  Enable  set/reset  reg,  all  planes 

out 

dx,  ax 

mov 

dx,  03C4h 

;  6845  address  reg 

mov 

al,  2 

;  Data  reg 

mov 

ah,  _colorl 

;  Palette  reg  planes  enabled 

out 

dx,  ax 

;  Set  color  code 

Compute  x 

coord  for  last  byte 

to  be  written 

mov 

bx,  x 

;  get  start  of  line 

add 

bx,  len 

;  end  =  start  +  length 

mov 

ex',  bx 

and 

cx,  0FFF8h 

;  x  coordinate  where  odd  bits 

mov  last,  cx  ;  at  end  of  line  begin 

;  Compute  number  of  odd  pixels  at  end  of  line 
sub  bx,  cx 

mov  oddeol,  bx  ;  save  it 

;  Construct  pixel  mask  for  last  byte  of  line 


cmp 

bx,  0 

jz 

bsol 

;  go  if  no  odd  pixels 

xor 

ax,  ax 

shr 

ax,  1 

;  shift  right  and 

or 

ax,  80h 

;  set  H/O  bit 

dec 

bl 

;  until  mask  is  built 

jnz 

eolb 

mov 

eolbits,  ax 

;  then  save  mask 

;  Compute  number  of  odd  pixels  at  start  of  line 

bsol:  mov  cx,  x  ;  get  starting  X  again 


and 

cx,  7 

;  #  of  pixels  from  start  of  byte 

jz 

saddr 

;  go  if  none 

mov 

bx,  8 

sub 

bx,  cx 

;  #  of  pixels  to  write 

mov 

oddsol,  bx 

;  save 

;  Construct  pixel  mask  for  first 

byte  of  line 

xor 

ax,  ax 

solb:  shl 

ax,  1 

;  shift  left  and 

or 

ax,  1 

;  set  L/O  bit 

dec 

bl 

;  until  mask  is  built 

jnz 

solb 

mov 

solbits,  ax 

;  then  save  mask 

;  Translate  last  byte  X  into  an 

address 

saddr :  mov 

ax,  OAOOOh 

mov 

es,  ax 

;  ES  ==>  video  buffer 

mov 

bx,  y 

;  get  row 

mov 

ax,  80 

mul 

bx 

mov 

bx,  ax 

;  BX  =  row  offset  =  row  *  80 

push 

bx 

;  save  row  offset 

mov 

ax,  last 

;  get  last  byte  X 

mov 

cl,  3 

shr 

ax,  cl 

;  shift  for  col  offset 

add 

bx,  ax 

;  last  offs  =  row  offs  +  col  offs 

mov 

last,  bx 

;  Compute  address  of  first  byte  (ES:[BX]) 
pop  bx  ; 

mov  ax,  x  ; 


fetch  row  offset 
get  col  offset 


mov 

cl. 

3 

shr 

ax. 

cl 

;  shift  right  3  for  col  offset 

add 

bx. 

ax 

;  offset  =  row  offs  +  col  offs 

cmp 

bx. 

last 

;  is  first  byte  also  last? 

jz 

weol 

;  skip  to  end  mask  if  so 

start 

of  line 

mov 

dx. 

03CEh 

;  6845  port 

mov 

ah. 

solbits 

;  start -of-line  mask 

cmp 

ah. 

0 

jz 

w8 

;  go  if  empty  mask 

mov 

al, 

8 

;  set  bit  mask  reg 

out 

dx, 

ax 

mov 

cl, 

es : [bx] 

;  load  6845  latches 

mov 

ax. 

solbits 

neg 

al 

;  complement 

dec 

al 

;  for  reversed  bit  mask 

and 

al. 

cl 

;  filter  previously  unset  pixels 

mov 

es 

[bx],  al 

;  clear  affected  bits 

mov 

al, 

colorl 

mov 

es: 

[bx],  al 

;  set  affected  bits 

inc 

bx 

;  next  byte 

cmp 

bx, 

last 

;  ready  for  end  of  line  yet? 

jae 

weol 

;  go  if  so 

;  Write  8  pixels  at  a  time  until  last  byte  in  line 


w8 :  mov 

ax. 

0FF08h 

;  update  all  pixels  in  byte 

out 

dx, 

ax 

;  set  bit  mask  reg 

mov 

al, 

es: [bx] 

;  load  6845  latches 

xor 

al, 

al 

mov 

es : 

[bx],  al 

;  clear  all  pixels 

mov 

al, 

_colorl 

mov 

es : 

[bx],  al 

;  set  all  bits 

inc 

bx 

;  next  byte 

cmp 

bx, 

last 

;  thru? 

jnz 

w8 

;  loop  if  not 

;  Write  end  of 

line 

weol:  mov 

dx. 

03CEh 

;  6845  port 

mov 

ah. 

eolbits 

;  end-of-line  mask 

cmp 

ah. 

0 

jz 

rvc 

;  go  if  empty  mask 

mov 

al. 

8 

;  set  bit  mask  reg 

out 

dx. 

ax 

mov 

cl, 

es : [bx] 

;  load  6845  latches 

mov 

ax. 

eolbits 

neg 

al 

;  complement 

dec 

al 

;  for  reversed  bit  mask 

and 

al. 

cl 

;  filter  previously  unset  pixels 

mov 

es : 

[bx],  al 

;  clear  affected  bits 

mov 

al. 

_colorl 

mov 

es: 

[bx],  al 

;  set  affected  bits 

;  Restore  video 

controller  to  default 

state 

rvc :  mov 

dx. 

03CEh 

mov 

ax. 

0005h 

;  write  mode  0,  read  mode  0 

out 

dx, 

ax 

mov 

ax. 

0FF08h 

;  default  bit  mask 

out 

dx. 

ax 

mov 

ax, 

0003h 

;  default  function  select 

out 

dx, 

ax 

xor 

ax. 

ax 

;  zero  Set/Reset 

out 

dx. 

ax 

mov 

ax. 

OOOlh 

;  zero  Enable  Set/Reset 

out 

dx, 

ax 

mov 

dx. 

03C4h 

;  6845  address  reg 

mov 

ax. 

OF02h 

;  Data  reg,  enable  all  planes 

out 

dx. 

ax 

;  End  of  routine 

quit :  mov 

sp, 

bp 

pop 

bp 

retf 
hline  ENDP 

End  listing  Six 

END 

Listing  Seven 

void  far  fill_rect  (int  xleft,  int  ytop,  int  w,  int  h) 

/*  Draw  solid  rectangle  in  colorl  from  top  left  corner  */ 

{ 

register  y; 

for  (y  =  ytop;  y  <  ytop+h;  y++) 
hline  (xleft,  y,  w) ; 

I  /*  - - - */ 


End  Listing  Seven 


Listing  Eight 


/*  COLORS. C:  Shows  all  colors  in  default  palette  */ 

♦include  "grafix.h" 

♦include  <conio.h> 

void  main  () 

{ 

int  r,  c,  color; 

if  (init_video  (EGA))  { 
for  (r  =  0;  r  <  4;  r++) 
for  (c  =  0;  c  <  4;  C++)  { 

color  =  (r  *  4)  +  c;  /*  next  color  */ 

setcolorl  (color); 
f illrect  ( (c*160) ,  (r*80) ,  158,  79); 

) 

getch();  /*  wait  for  keypress  */ 

} 

End  Listings 
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STRUCTURED  PROGRAMMED 


Listing  One  ( Text  begins  on  page  123  ) 


i - 1 

{  Textlnfo  } 
{  } 
{  Text  video  information  library  } 
{  ) 
{  by  Jeff  Duntemann  } 
{  Turbo  Pascal  V5.0  } 
{  Last  update  11/20/88  } 
I - ) 


{All  we're  doing  here  is  converting  r  meric  font  heights} 
{to  their  corresponding  values  of  tyi  FontSize.  } 

FUNCTION  Font Code (Height  :  Byte)  :  vontSize; 

BEGIN 

CASE  Height  OF 

8  :  FontCode  :=  Font 8; 

14  :  FontCode  :=  Font 14; 

16  ;  FontCode  :=  Fontl6; 

END  {CASE} 

END; 


UNIT  Textlnfo; 

INTERFACE 
USES  DOS; 

TYPE 

AdapterType  =  (None, MDA, CGA, EGAMono, EGAColor, VGAMono, 

VGAColor, MCGAMono, MCGAColor) ; 

FontSize  =  (Font8,Fontl4,Fontl6) ; 

{The  following  type  definition  ‘requires*  Turbo  Pascal  5.0!} 
OverrideProc  =  PROCEDURE (VAR  ForceX  :  Byte;  VAR  ForceY  :  Byte); 


VAR 

TextBuf ferOrigin  :  Pointer; 
TextBufferSize  :  Word; 
VisibleX, VisibleY  :  Byte; 


{Likewise,  this  function  converts  values  of  type  FontSize} 
{to  their  corresponding  numeriuc  values.  } 

FUNCTION  FontHeight (Code  :  FontSize)  :  Byte; 

BEGIN 

CASE  Code  OF 

Font8  :  FontHeight  :=  8; 

Fontl4  :  FontHeight  :  =  14; 

Fontl6  :  FontHeight  :=  16; 

END  {CASE} 

END; 


FUNCTION  GetFontSize  :  FontSize; 


FUNCTION  GetBIOSTextMode  :  Byte;  {Ret.  BIOS  text  mode} 

FUNCTION  GetFontSize  :  FontSize;  {Ret.  font  height  code) 

FUNCTION  GetTextBuf ferOrigin  :  Pointer;  {Ret.  pointer  to  text  buffer} 
{Returns  visible  X  and  Y  extent  plus  buffer  size  in  bytes:} 

PROCEDURE  GetTextBuf ferStats (VAR  BX  :  Byte; 

VAR  BY  :  Byte; 

VAR  BuffSize  :  Word; 

CheckForOverride  :  OverrideProc) ; 

PROCEDURE  NullOverride(VAR  ForceX  :  Byte;  VAR  ForceY  :  Byte); 

FUNCTION  QueryAdapterType  :  AdapterType;  {Ret.  installed  display) 
FUNCTION  FontCode (Height  :  Byte)  :  FontSize;  {Ret.  font  height  code} 
FUNCTION  FontHeight (Code  :  FontSize)  :  Byte;  {Ret.  font  height  value} 

IMPLEMENTATION 

FUNCTION  GetBIOSTextMode  :  Byte; 

VAR 

Regs  :  Registers;  {Type  Registers  is  exported  by  the  DOS  unit} 

BEGIN 

Regs. AH  :=  $0F;  (BIOS  VIDEO  Service  $F:  Get  Current  Video  Mode} 

Intr ($10, Regs) ; 

GetBIOSTextMode  :=  Regs . AL;  {Mode  is  returned  in  AL} 

END; 


VAR 

Regs 


Registers;  {Type  Registers  is  exported  by  the  DOS  unit} 


BEGIN 

CASE  QueryAdapterType  OF 


CGA 
MDA 

MCGAMono, 

MCGAColor 

EGAMono, 

EGAColor, 

VGAMono, 

VGAColor 


GetFontSize  :=  Font8; 

GetFontSize  :=  Fontl4; 

GetFontSize  :=  Fontl6;  {Wretched  thing  knows  but  1  font!} 
{These  adapters  may  be  using  any  of  several  different} 
{font  cell  heights,  so  we  need  to  query  the  BIOS  to} 
{find  out  which  is  currently  in  use.) 

BEGIN 

WITH  Regs  DO 
BEGIN 

AH  :=  $11;  {EGA/VGA  Information  Call} 

AL  :=  $30; 

BL  :=  0; 

END; 

Intr ($10, Regs) ;  {On  return,  CX  cont .  the  font  height} 
GetFontSize  :=  FontCode (Regs .CX) ; 

END 


END 

END; 


FUNCTION  QueryAdapterType  :  AdapterType; 

VAR 

Regs  :  Registers;  (Type  Registers  is  exported  by  the  DOS  unit} 

Code  :  Byte; 

BEGIN 

Regs. AH  :=  $1A;  {Attempt  to  call  VGA  Identify  Adapter  Function} 

Regs . AL  :=  $00;  {Must  clear  AL  to  0  ...} 

Intr ($10, Regs) ; 

IF  Regs.AL  =  $1A  THEN  {...so  that  if  $1A  comes  back  in  AL...  } 

BEGIN  {...we  know  a  PS/2  video  BIOS  is  out  there.} 

CASE  Regs . BL  OF  {Code  comes  back  in  BL} 

$00  :  QueryAdapterType  :=  None; 

$01  :  QueryAdapterType  :=  MDA; 

$02  :  QueryAdapterType  :=  CGA; 

$04  :  QueryAdapterType  :=  EGAColor; 

$05  :  QueryAdapterType  :=  EGAMono; 

$07  :  QueryAdapterType  :=  VGAMono; 

$08  :  QueryAdapterType  :=  VGAColor; 

$0A,$0C  :  QueryAdapterType  :=  MCGAColor; 

$0B  :  QueryAdapterType  :=  MCGAMono; 

ELSE  QueryAdapterType  :=  CGA 
END  {CASE} 

END 

ELSE 

{If  it's  not  PS/2  we  have  to  check  for  the  presence  of  an  EGA  BIOS:} 
BEGIN 

Regs. AH  :=  $12;  {Select  Alternate  Function  service} 

Regs.BX  :=  $10;  (BL=$10  means  return  EGA  information} 

Intr ($10, Regs) ;  {Call  BIOS  VIDEO} 

IF  Regs.BX  <>  $10  THEN  {BX  unchanged  means  EGA  is  NOT  there...} 
BEGIN 

Regs. AH  :=  $12;  {Once  we  know  Alt  Function  exists...) 
Regs.BL  :=  $10;  {...we  call  it  again  to  see  if  it's...} 

Intr ($10, Regs) ;  {...EGA  color  or  EGA  monochrome.} 

IF  (Regs . BH  =  0)  THEN  QueryAdapterType  :=  EGAColor 
ELSE  QueryAdapterType  :=  EGAMono 

END 

ELSE  {Now  we  know  we  have  an  CGA  or  MDA;  let's  see  which:} 

BEGIN 

Intr ($11, Regs) ;  {Equipment  determination  service} 

Code  :=  (Regs.AL  AND  $30)  SHR  4; 

CASE  Code  of 

1  :  QueryAdapterType  :=  CGA; 

2  :  QueryAdapterType  :=  CGA; 

3  :  QueryAdapterType  :=  MDA 

ELSE  QueryAdapterType  :=  None 

END  {Case} 

END 

END; 

END; 


FUNCTION  GetTextBuf ferOrigin  :  Pointer; 

{The  rule  is:  For  boards  attached  to  monochrome  monitors,  the  buffer} 
{origin  is  $B000:0;  for  boards  attached  to  color  monitors  (including  } 

{all  composite  monitors  and  TV's)  the  buffer  origin  is  $B800:0.  } 

BEGIN 

CASE  QueryAdapterType  OF 

CGA, MCGAColor, EGAColor, VGAColor  :  GetTextBuf ferOrigin  :=  Ptr ($B800, 0) ; 
MDA, MCGAMono,  EGAMono,  VGAMono  :  GetTextBuf ferOrigin  :=  Ptr ($B000, 0) ; 
END  {CASE} 

END; 


{This  proc  provides  initial  values  for  the  dimensions  of  the  visible} 
{display  and  (hence)  the  size  of  the  visible  refresh  buffer.  It  is  } 
{called  by  the  initialization  section  during  startup  *BUT*  you  must} 
{call  it  again  after  any  mode  change  or  font  change  to  be  sure  of  } 
{having  accurate  values  in  the  three  variables!} 

PROCEDURE  GetTextBuf ferStats (VAR  BX  :  Byte;  (Visible  X  dimension} 

VAR  BY  :  Byte;  {Visible  Y  dimension} 

VAR  BuffSize  :  Word;  (Refresh  buffer  size} 

{This  requires  TP5.0!}  CheckForOverride  :  OverrideProc); 

CONST 

ScreenLinesMatrix  :  ARRAY [AdapterType, FontSize]  OF  Integer  = 


{Font8 : 

Font 14 : 

Font  16: 

None:  } 

(  (25, 

25, 

25), 

MDA:  } 

(-1, 

25, 

-1), 

CGA:  } 

(25, 

-1, 

-1), 

EGAMono:  } 

(43, 

25, 

-1), 

EGAColor:  } 

(43, 

25, 

-1), 

VGAMono:  } 

(50, 

28, 

25)  , 

VGAColor:  } 

(50, 

28, 

25), 

MCGAMono :  } 

(-1, 

-1, 

25), 

MCGAColor:  } 

(-1, 

-1, 

25)) 

VAR 

Regs  :  Registers;  {Type  Registers  is  exported  by  the  DOS  unit} 
BEGIN 

Regs. AH  :=  $0F;  {BIOS  VIDEO  Service  $F:  Get  Current  Video  Mode} 
Intr ($10, Regs) ; 

BX  :=  Regs. AH;  {Number  of  characters  in  a  line  returned  in  AH) 

BY  :=  ScreenLinesMatrix [QueryAdapterType, GetFontSize] ; 

IF  BY  >  0  THEN 
BEGIN 

CheckForOverride (BX, BY) ;  {See  if  something  weird  is  on  bus.} 
BuffSize  :=  (BX  *  2)  *  BY  {Calculate  the  buffer  size  in  bytes} 
END 

ELSE  BuffSize  :=  0; 

END; 
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{This  is  the  default  override  proc,  and  is  called  anytime  you're} 
{not  concerned  about  finding  a  nonstandard  text  adapter  on  the  } 
{bus.  (Funny  graphics  cards  with  normal  text  modes  don't  matter} 
{to  this  library.)  If  you  want  to  capture  any  weird  cards,  you  } 
{must  provide  your  own  override  proc  that  can  detect  the  card  } 
{and  return  correct  values  for  the  visible  X  and  Y  dimensions.  } 

PROCEDURE  NullOverride (VAR  ForceX  :  Byte;  VAR  ForceY  :  Byte) ; 

BEGIN 

{Like  I  said;  Null...} 

END; 


{The  initialization  section  provides  some  initial  values  for  the  } 
{exported  variables  TextBuf ferOrigin,  VisibleX,  VisibleY,  and  } 
{TextBuf ferSize,  so  that  you  can  use  the  variables  without  further} 
(kafeuthering. } 

BEGIN 

TextBufferOrigin  :=  GetTextBuf ferOrigin; 

GetTextBufferStats (VisibleX, VisibleY, TextBuf ferSize, NullOverride) ; 
END. 


End  Listing  One 


listing  Four 


<* - m 

(*  TEXT INFO  *) 
(*  *) 
(*  Text  video  information  library  —  Implementation  module  *) 
(*  *) 
(*  by  Jeff  Duntemann  *) 
(*  TopSpeed  Modula  2  VI. 12  *) 
(*  Last  update  12/7/88  *) 
(* - *) 


IMPLEMENTATION  MODULE  Textlnfo; 

FROM  SYSTEM  IMPORT  Registers; 

FROM  Lib  IMPORT  Intr; 

VAR 

ColorBufOrg  [ 0B8 00H : 0 ]  :  WORD;  (*First  word  in  color  refresh  buffer*) 
MonoBufOrg  [OBOOOH:0]  :  WORD;  (‘First  word  in  mono  refresh  buffer*) 


PROCEDURE  GetBIOSTextMode ( )  :  SHORTCARD; 

VAR 

Regs  :  Registers; 

BEGIN 

Regs. AH  :=  OFH;  (*  VIDEO  service  OFH  *) 

Intr (Regs, 10H) ; 

RETURN  Regs.AL  (*AL  contains  current  text  mode  on  return*) 
END  GetBIOSTextMode; 


Listing  Two 


PROGRAM  TextTest; 

USES  Textlnfo; 

BEGIN 

Write ('The  installed  adapter  is  '); 

CASE  QueryAdapterType  OF 

None  :  Writeln  (' nothing  I"ve  ever  seen.'); 

MDA  :  Writeln ('an  MDA  .'); 

CGA  :  Writeln ('a  CGA . ' ) ; 

EGAMono,EGAColor  :  Writeln ('an  EGA.'); 

VGAMono, VGAColor  :  Writeln ('a  VGA.'); 

MCGAMono,MCGAColor  :  Writeln ('an  MCGA.'); 

END;  {CASE} 

Writeln ('The  current  font  height  is  ', FontHeight (GetFontSize) ,'.') ; 
Writeln ('The  current  BIOS  text  mode  is  ', GetBIOSTextMode, '.') ; 
Writeln ('The  current  screen  is  ', VisibleX, '  character  wide', 

'  and  ', VisibleY,'  characters  wide;'); 

Writeln  ('  and  occupies  ', TextBuf ferSize, '  bytes  in  memory.'); 

END. 


End  Listing  Two 


Listing  Three 


<* - *) 

(*  TEXTINFO  *) 
(*  *) 
{*  Text  video  information  library  —  Definition  module  *) 
(*  *) 
(*  by  Jeff  Duntemann  *) 
(*  TopSpeed  Modula  2  VI. 12  *) 
(*  Last  update  12/7/88  *) 
(*- - - *) 


DEFINITION  MODULE  Textlnfo; 

TYPE 

AdapterType  =  (None, MDA, CGA, EGAMono, EGAColor, VGAMono, 

VGAColor, MCGAMono,MCGAColor) ; 

FontSize  =  (Font8, Fontl4 , Fontl6) ; 

OverrideProc  =  PROCEDURE (VAR  BYTE, VAR  BYTE); 

VAR 

TextBufferOrigin  :  ADDRESS;  (‘Address  of  video  refresh  buffer  *) 
TextBuf ferSize  :  CARDINAL;  (*Bytes  contained  in  refresh  buffer*) 
VisibleX, VisibleY  :  SHORTCARD;  (‘Dimensions  of  the  visible  display*) 


PROCEDURE  GetBIOSTextMode ()  ;  SHORTCARD; 

PROCEDURE  GetTextBufferOriginO  :  ADDRESS; 

PROCEDURE  GetTextBuf ferStats (VAR  BufX  :  BYTE;  (‘Visble  X  dimension*) 

VAR  BufY  :  BYTE;  (‘Visble  Y  dimension*) 

VAR  BuffSize  :  CARDINAL;  (*Refr.  buffer  size*) 
CheckForOverride  :  OverrideProc) ; 


PROCEDURE  QueryAdapterType ()  :  AdapterType; 

PROCEDURE  FontCode (Height  :  SHORTCARD)  :  FontSize; 
PROCEDURE  FontHeight (Code  :  FontSize)  :  SHORTCARD; 
PROCEDURE  GetFontSize ()  :  FontSize; 

PROCEDURE  NullOverride (VAR  ForceX  :  BYTE;  VAR  ForceY 
END  Textlnfo. 


End  Listing  Three 


PROCEDURE  QueryAdapterType ()  :  AdapterType; 
VAR 

Regs  :  Registers; 

Code  :  SHORTCARD; 


BEGIN 

Regs. AH  :=  1AH;  (‘Attempt  to  call  VGA  Identify  Adapter  Function*) 
Regs.AL  :=  0;  (*  Must  clear  AL  to  0  ...  *) 

Intr (Regs, 10H) ; 

IF  Regs.AL  =  1AH  THEN  (*...so  that  if  $1A  comes  back  in  AL...  *) 

(*...we  know  a  PS/2  video  BIOS  is  out  there*) 
CASE  Regs.BL  OF  (‘Code  comes  back  in  BL*) 

0  :  RETURN  None  I 

1  :  RETURN  MDA;  I 

2  :  RETURN  CGA;  | 

4  :  RETURN  EGAColor;  I 

5  :  RETURN  EGAMono;  I 

7  :  RETURN  VGAMono;  I 

8  :  RETURN  VGAColor;  I 

OAH, OCH  :  RETURN  MCGAColor;  | 

OBH  :  RETURN  MCGAMono;  I 

ELSE  RETURN  CGA 

END  (*  CASE  *) 

ELSE 

(*If  it's  not  PS/2  we  have  to  check  for  the  presence  of  an  EGA  BIOS:*) 
Regs. AH  :=  12H;  (‘Select  Alternate  Function  service*) 

Regs.BX  :=  10H;  (*BL=$10  means  return  EGA  information*) 

Intr (Regs, 10H) ;  (‘Call  BIOS  VIDEO*) 

IF  Regs.BX  <>  10H  THEN  (*BX  unchanged  means  EGA  is  NOT  there...*) 
Regs. AH  :=  12H;  (*Once  we  know  Alt  Function  exists...*) 

Regs.BL  :=  10H;  (*...we  call  it  again  to  see  if  it's...*) 

Intr (Regs, 10H) ;  (*...EGA  color  or  EGA  monochrome.*) 

IF  (Regs . BH  =  0)  THEN  RETURN  EGAColor 

ELSE  RETURN  EGAMono 

END 

ELSE  (*  Now  we  know  we  have  an  CGA  or  MDA;  let's  see  which:  *) 

Intr (Regs, 11H) ;  (*  Equipment  determination  service  *) 

Code  :=  SHORTCARD (BITSET (Regs .AL)  *  BITSET{ 4 . . 5} )  »  4; 

CASE  Code  OF 

1  :  RETURN  CGA  | 

2  :  RETURN  CGA  | 

3  :  RETURN  MDA 
ELSE  RETURN  None 

END  (*  Case  *) 

END 

END 

END  QueryAdapterType; 


(*  This  is  a  simple  "clean  conversion"  function  for  relating  the  *) 
(*  enumerated  font  size  constants  to  SHORTCARD  numeric  font  size  *) 
(*  values.  *) 

PROCEDURE  FontCode (Height  :  SHORTCARD)  :  FontSize; 

BEGIN 

CASE  Height  OF 

8  :  RETURN  Font 8  | 

14  :  RETURN  Fontl4  | 

16  :  RETURN  Font 16 
ELSE  RETURN  Font 8 
END  (*  CASE  *) 

END  FontCode; 


(‘This  is  a  simple  "clean  conversion"  function  for  relating  the  *) 
(*SHORTCARD  numeric  font  size  values  to  the  enumerated  font  size*) 
(*  constants  *) 

PROCEDURE  FontHeight (Code  :  FontSize)  :  SHORTCARD; 

BEGIN 

CASE  Code  OF 

Font 8  :  RETURN  8  | 
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Listing  Four  ( Listing  continued ,  text  begins  on  page  123) 


Font 14  :  RETURN  14  | 
Font 16  :  RETURN  16 
END  (*  CASE  *) 

END  FontHeight; 


PROCEDURE  GetFontSize ()  :  FontSize; 

VAR 

Regs  :  Registers; 

BEGIN 

CASE  QueryAdapterTypeO  OF 

RETURN  Font 8  | 

RETURN  Font 14  | 

RETURN  Font 16  | 

(‘These  adapters  may  be  using  any  of  several  *) 
(‘different  font  cell  heights,  so  we  need  to  query*) 
(‘BIOS  to  find  out  which  is  currently  in  use.*) 

WITH  Regs  DO 

AH  :=  11H;  (*  EGA/VGA  Information  Call  *) 

AL  :=  3 OH; 

BL  :=  0; 

END; 

Intr (Regs, 10H) ; 

RETURN  FontCode (SHORTCARD (Regs .CX) ) 

END  (*  CASE  *) 

END  GetFontSize; 


CGA  : 

MDA  ; 

MCGAMono, 
MCGAColor  : 
EGAMono, 
EGAColor, 
VGAMono, 
VGAColor  : 


PROCEDURE  GetTextBufferOriginO  :  ADDRESS; 

(‘The  rule  is:  For  boards  attached  to  monochrome  monitors,  the  buffer*) 
(‘origin  is  $B000:0;  for  boards  attached  to  color  monitors  (including*) 
(‘all  composite  monitors  and  TV's)  the  buffer  origin  is  $B800:0.  *) 


PROCEDURE  GetTextBuf ferStats (VAR  BufX  :  BYTE;  (‘Visble  X  dimension*) 

VAR  BufY  :  BYTE;  (‘Visble  Y  dimension*) 

VAR  Buff Size  :  CARDINAL;  (*Refr.  buffer  size  *) 
CheckForOverride  :  OverrideProc) ; 

TYPE 

FontPoints  =  ARRAY [Font8 .. Font 16]  OF  INTEGER; 

PointsArray  =  ARRAY [None. .MCGAColor]  OF  FontPoints; 

VAR 

Regs  :  Registers;  (*  Type  Registers  is  exported  by  the  DOS  unit  *) 
ScreenLinesMatrix  :  PointsArray; 

Adapter  :  AdapterType; 

Font  :  FontSize; 

(*  TopSpeed  can't  do  two-dimensional  array  aggregates,  Turbo  Pascal  *) 

(*  style  (arrgh)  so  we  have  to  make  it  an  array  of  arrays:  *) 

BEGIN 


ScreenLinesMatrix  :=  PointsArray ( 


* 

None:  *) 

FontPoints (25, 

25, 

25), 

* 

MDA:  *) 

FontPoints (-1, 

25, 

-1), 

* 

CGA:  *) 

FontPoints (25, 

-1, 

-1), 

* 

EGAMono:  *) 

FontPoints (43, 

25, 

-l)r 

* 

EGAColor:  *) 

FontPoints (43, 

25, 

-1), 

* 

VGAMono:  *) 

FontPoints  (50, 

28, 

25), 

VGAColor:  *) 

FontPoints  (50, 

28, 

25), 

* 

MCGAMono:  *) 

FontPoints (-1, 

-1, 

25), 

* 

MCGAColor:  *) 

FontPoints (-1, 

-1, 

25)); 

Regs. AH  :=  OFH;  (*  BIOS  VIDEO  Service  $F:  Get  Current  Video  Mode  *) 
Intr (Regs, 10H) ; 

BufX  :=  Regs. AH;  (*  Number  of  characters  in  a  line  returned  in  AH  *) 

BufY  :-  SHORTCARD (ScreenLinesMatrix [QueryAdapterType () , GetFontSize () ]); 
IF  SHORTCARD (BufY)  >  0  THEN 

CheckForOverride (BufX, BufY) ;  (‘See  if  odd  adapter  is  on  the  bus...*) 
(*  Calculate  the  buffer  size  in  bytes:  *) 

BuffSize  :=  (CARDINAL (BufX)  *  2)  *  CARDINAL (BufY) 

ELSE  BuffSize  :=  0 
END 

END  GetTextBufferStats; 


BEGIN 

CASE  QueryAdapterTypeO  OF 

CGA, MCGAColor, EGAColor, VGAColor  :  RETURN  ADR(ColorBufOrg)  | 

MDA, MCGAMono,  EGAMono,  VGAMono  :  RETURN  ADR (MonoBufOrg) 

END  (*  CASE  *) 

END  GetTextBufferOrigin; 

(‘This  one  function  returns  essential  screen/buffer  size  information.*) 
(‘It  is  called  by  the  initializing  body  of  this  module  but  should  be  *) 
(‘called  again  after  ‘any*  mode  change  or  font  change!  *) 


(*  This  is  the  "default"  override  proc,  called  when  there  is  no  *) 
(*  suspicion  of  anything  nonstandard  on  the  bus.  Replace  with  *) 
(*  a  custom  proc  that  looks  for  any  nonstandard  video  adapter.  *) 

PROCEDURE  Nul lOver ride (VAR  ForceX  :  BYTE;  VAR  ForceY  :  BYTE); 

BEGIN 

(*  Like  I  said;  Null...  *) 

END  NullOverride; 


(*  The  module  body,  like  a  Pascal  unit  initialization  section,  is  *) 
(*  executed  before  the  client  program  that  imports  this  module  or  *) 
(*  any  part  of  it.  *) 

BEGIN 

TextBuf ferOrigin  :=  GetTextBufferOriginO; 

GetTextBufferStats (VisibleX, VisibleY, TextBuf ferSize, NullOverride) ; 
END  Text Info. 


End  Listing  Four 


Listing  Five 

MODULE  Text Test; 

FROM  10  IMPORT  WrStr, WrLn, WrCard, WrShtCard; 

FROM  Textlnfo  IMPORT  AdapterType, QueryAdapterType, GetFontSize, 

FontHeight, GetBIOSTextMode, VisibleX, VisibleY, 
TextBuf ferSize; 


BEGIN 

WrStr ("The  installed  adapter  is  "); 

CASE  QueryAdapterTypeO  OF 

None  :  WrStr ("nothing  I've  ever  seen.")  I 

MDA  :  WrStr ("an  MDA.")  I 

CGA  :  WrStr ("a  CGA.")  I 

EGAMono, EGAColor  :  WrStr ("an  EGA.")  I 

VGAMono, VGAColor  :  WrStr ("a  VGA.")  I 

MCGAMono, MCGAColor  :  WrStr ("an  MCGA . " ) ; 

END;  (*  CASE  *) 

WrLn; 

WrStr('The  current  font  height  is  '); 

WrShtCard (FontHeight (GetFontSize ( ) ) , 2 ) ; 

WrStr (".");  WrLn; 

WrStr ("The  current  BIOS  text  mode  is  "); 

WrShtCard (GetBIOSTextMode () ,2) ; 

WrStr (".");  WrLn; 

(*  VisibleX  and  VisibleY  are  initialized  by  Textlnfo  module  body  *) 
WrStr ("The  current  screen  is  "); 

WrShtCard (VisibleX, 2) ; 

WrStr{"  character  wide  and  "); 

WrShtCard (VisibleY, 2) ; 

WrStr ("  characters  high;"); 

WrLn; 

WrStr ("  and  occupies  "); 

(*  TextBufferSize  is  initialized  by  Textlnfo  module  body  *) 

WrCard (TextBuf ferSize, 6) ; 

WrStr("  bytes  in  memory.");  WrLn; 

END  TextTest . 

End  Listings 
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White  Pine  Software  will  soon  re¬ 
lease  eXodus,  an  X-Windows  system 
display  server  for  the  Macintosh  devel¬ 
oped  in  cooperation  with  Digital  Equip¬ 
ment  Corp.  According  to  White  Pine, 
eXodus  is  the  first  implementation  of 
me  XI 1  standard  under  the  Macintosh 
OS.  XI 1  is  a  network  transparent  win¬ 
dow  system  developed  at  MIT  and  sup¬ 
ported  by  vendors  such  as  Apple  Com¬ 
puter  Inc.  and  Digital  Equipment  Corp. 

eXodus  conforms  to  the  Macintosh 
user  interface  standards  and  is  compat¬ 
ible  with  Apple’s  Multifinder  system. 
Macintosh  Plus,  SE,  and  II  are  sup¬ 
ported,  as  well  as  network  communica¬ 
tion  protocols  such  as  Appletalk, 
DECnet,  and  TCP/IP. 

eXodus  provides  an  X-Windows  sys¬ 
tem  front  end  to  client  applications  run¬ 
ning  on  a  variety  of  host  systems.  By 
handling  requests  for  client  connec¬ 
tions  and  disconnections,  receiving  and 
processing  client  requests,  and  sending 
Macintosh  events  from  user  to  host,  the 
Macintosh  is  integrated  into  the  client 
application. 

Version  1.0  supports  monochrome 
systems;  color  support  will  be  provided 
in  a  later  release.  A  font  compiler  is 
provided  that  converts  X  distribution 
(BDF)  fonts,  as  well  as  Macintosh  fonts, 
to  an  eXodus  compatible  format.  White 
Pine  also  plans  to  upgrade  eXodus  to 
conform  to  DECwindows,  Digital’s  user 
interface. 

Cost  of  eXodus,  Version  1,0,  is  $499 
per  server.  Educational  pricing  and  site 
licenses  are  available.  Reader  Service 
No.  20. 

White  Pine  Software 
94  Route  101A 
P.O.  Box  1108 
Amherst,  NH  03031 
603-886-9050 

Powerline  Software’s  Source  Print 
lists  one  or  more  source  files  with  page 
headings  and  optional  line  numbers 
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and  includes  an  index  (cross-reference 
list),  structure  outlining,  and  automatic 
indentation  of  source  code  and  listings. 
Source  Print  also  generates  a  table  of 
contents  that  lists  functions  and  proce¬ 
dures. 

Tree  Diagrammer,  another  Powerline 
Software  product,  creates  an  organiza¬ 
tion  chart  of  programs  showing  the  hi¬ 
erarchy  of  calls  to  functions,  proce¬ 
dures,  and  subroutines.  Recursive  calls 
are  indicated,  and  designated  com¬ 
ments  in  the  source  code  appear  on  the 
chart. 

Source  Print  sells  for  $97;  Tree  Dia¬ 
grammer  is  $77.  Reader  Service  No.  21. 
Powerline  Software  Inc. 

2531  Baker  St. 

San  Francisco,  CA  94123 
415-346-8325 
800-257-5773  (Dept.  M-4) 

Microtec  Research  has  released 
XRAY86,  the  newest  version  of  its 
XRAY  high-level  debugger  to  support 
the  Intel  8086/186/28 6  microproces¬ 
sors.  The  XRAY  high-level  debugger 
family  supports  emulators  from  applied 
Microsystems  Corp.,  Hewlett-Packard, 
Microcase  Inc.,  Microcosm,  Microtek  In¬ 
ternational,  and  ZAX  Corp. 

XRAY86  provides  a  programmable 
window  interface  called  Viewports, 
which  permits  users  to  scan  source 
code,  monitor  program  variables  and 
expressions,  trace  procedure  calls,  and 
set  simple  and  complex  conditional 
breakpoints. 

With  XRAY  debugger  software,  pro¬ 
grammers  can  use  either  Microtec  Re¬ 
search’s  integrated  C  compiler  and  as¬ 
sembler  tools  or  Intel’s  compilers  and 
assemblers.  In  addition,  Microtec  Re¬ 
search  claims  that  XRAY86  maintains 
the  same  user  interface,  regardless  of 
the  execution  environment  or  the  host 
computer. 

XRAY86  supports  Microtec  Research 
C  and  Pascal  compilers,  as  well  as  C, 
Pascal,  and  PL/M  compilers  from  Intel. 
XRAY86  and  its  language  development 
toolkits  are  available  on  VAX,  IBM  PC, 
and  workstations  such  as  Sun,  HP,  and 
Apollo. 

Prices  for  a  toolkit  that  includes  com¬ 
piler,  assembler  package,  and  XRAY86 
debugger  range  from  $3,500  on  a  PC  to 
$5,000  on  a  workstation  and  $14,000 
on  a  VAX.  Components  of  the  toolkit 
may  be  purchased  separately.  Reader 
Service  No.  22. 

Microtec  Research  Inc. 

P.O.  Box  60337 
Sunnyvale,  CA  94088 
408-733-2919 

Layout,  by  Matrix  Software  Technol¬ 
ogy,  is  a  menu-based  software  devel¬ 
opment  system  that  features  object- 


oriented  programming,  a  graphical  in¬ 
terface,  CASE  tools,  and  hypertext. 

Layout  contains  three  levels  of  soft¬ 
ware  objects:  elements,  procedures, 
and  black  boxes.  Elements  contain  a 
single  preprogrammed  command  (such 
as  “draw  a  window”).  Procedures  are 
more  complex,  consisting  of  two  to  500 
elements.  Black  boxes  are  externally 
developed  software  objects;  rather  than 
containing  elements  built  into  Layout, 
black  boxes  are  units  programmed  in 
code  to  run  with  Layout. 

Layout  is  based  on  an  open  architec¬ 
ture,  which  allows  the  use  of  black  box 
elements  developed  by  third  parties  in 
C  or  assembler,  as  well  as  those  pro¬ 
vided  by  Matrix. 

Layout’s  file  box  opens  a  window  on 
the  screen,  displays  the  current  direc¬ 
tory  in  the  disk,  displays  the  file  names, 
allows  the  user  to  select  and  change 
drives  and  folders,  and  associates 
screen  icons  with  different  file  types. 

Layout  also  contains  underlying  in¬ 
ference  engines,  an  artificial  intelli¬ 
gence  technology  that  enables  informa¬ 
tion  to  be  interpreted  as  a  simulation  or 
compiled  into  a  program.  Layout  cre¬ 
ates  code  in  Turbo  Pascal,  Turbo  C, 
Microsoft  C,  QuickBasic,  or  Lattice  C. 
Layout  also  generates  executable  DOS 
files. 

Priced  at  $149. 95,  Layout  supports  a 
mouse  and  runs  on  the  IBM  PC  and 
compatibles.  Reader  Service  No.  23- 
Matrix  Software  Technology  Corp. 

1  Massachusetts  Technology  Center 
Harborside  Dr. 

Boston,  MA  02128 

617-567-0037 

800-533-5644 

Grammar  Engine  has  introduced  a 
desk  accessory  (DA)  software  tool 
called  LoadROM,  which  is  used  for  mi¬ 
croprocessor  cross  development  on  the 
Macintosh.  The  LoadROM  software  ac¬ 
cepts  binary  and  popular  hex  record 
formats  for  loading  ROM  code  from  the 
Macintosh  to  the  ROMulator,  Grammar 
Engine’s  in-circuit  ROM  emulator.  The 
ROMulator  package  consists  of  hard¬ 
ware,  cables,  LoadROM  host  software, 
and  instruction  manual. 

LoadROM  provides  editing  capabili¬ 
ties  to  allow  ROM  software  patching. 
LoadROM  is  also  a  Macintosh  Program¬ 
mer’s  Workbench  (MPW)  tool.  In  the 
command-line  version  of  the  software, 
it  is  intended  to  be  invoked  by  the 
make  command  of  MPW  to  load  the 
ROMulator  as  part  of  the  build  process. 

After  downloading  from  the  Macin¬ 
tosh,  the  ROMulator  software  is  avail¬ 
able  for  access  from  the  target  com¬ 
puter.  Bi-directional  models  make  it  pos¬ 
sible  to  use  the  target  debugger  to 
(continued  on  page  152) 
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patch  ROM  code.  A  multi-drop  inter¬ 
face  allows  up  to  eight  modules  with 
different  identities  to  be  daisy-chained 
and  loaded  from  a  single  Macintosh 
printer  or  modem  port. 

The  ROMulator  allows  in-circuit  emu¬ 
lation  of  ROMs  in  8-,  16-,  or  32-bit  tar¬ 
get  systems,  such  as  the  Z80,  80386, 
and  68020.  Standard  ROMulator  mod¬ 
els  are  priced  from  $375  to  $1,645,  de¬ 
pending  on  total  RAM  capacity  and 
other  options.  Reader  Service  No.  24. 
Grammar  Engine  Inc. 

3314  Morse  Rd. 

Columbus,  OH  43231 
614-471-1113 

Computer  Control  Systems  has  re¬ 
leased  several  products:  FABS  Plus 
OS/2,  Autosort  OS/2,  and  DB-FABS/ 
DABL,  Version  3. 

Written  in  assembly  language,  FABS 
Plus  is  a  BTree  subroutine  designed  to 
maintain  index  files.  FABS  Plus  sup¬ 
ports  duplicate  and  variable  length 
keys.  Multiple  primary  keys  can  be  main¬ 
tained  in  a  single  tree  providing  access 
to  data  files  on  more  than  one  key.  The 
key  files  are  independent  of  the  data 
files  and  do  not  need  to  be  rese¬ 
quenced.  Generic  searches  and  multi¬ 
level  sequencing  are  supported;  sup¬ 
ported  interfaces  are  Microsoft’s  Basic 
compiler,  Pascal,  Fortran,  and  C. 

Autosort  OS/2  is  a  sort/merge/select 
utility  written  in  assembly  language.  It 
sorts  on  15  sort  keys  (ascending  or  de¬ 
scending)  and  provides  15  select  keys 
so  that  records  may  be  deleted,  re¬ 
tained,  or  retained-if-not  when  the  se¬ 
lect  key  is  less  than,  equal  to,  or  greater 
than  the  select  field  in  the  record. 

Autosort  sorts  and  selects  on  string, 
integer,  single  precision,  and  double 
precision  fields.  It  also  supports  paths 
to  files.  Sort  parameters  can  be  speci¬ 
fied  during  run  time  or  from  parameter 
files  on  the  disk. 

Version  3  of  DB-FABS,  written  in  as¬ 
sembly  language  for  MS-DOS  systems, 
is  a  data,  screen,  and  report  manager 
program  designed  to  help  users  ma¬ 
nipulate  and  control  data  files.  DABL  is 
a  programming  language  designed  to 
be  used  with  DB-FABS.  DB-FABS  con¬ 
sists  of  two  modes  of  operation:  the 
stand-alone  mode  and  the  run-time 
mode,  with  which  users  can  create  data 
files  and  screen  forms  and  handle  the 
file  I/O,  indexing,  sorting,  screen  man¬ 
agement,  and  reports. 

The  single-user  version  of  FABS  Plus 
OS/2  sells  for  $195,  and  the  network 
version  is  $295.  Autosort  OS/2  is  $150, 
and  DB-FABS/DABL,  Version  3,  sells 


for  $195  (single  user)  and  $295  (net¬ 
work  version).  Reader  Service  No.  25. 
Computer  Control  Systems  Inc. 

Rt.  3,  Box  168 
Lake  City,  FL  32055 
904-752-0912 

The  Ohio  Scientific  720,  a  member  of 
the  OSI  series  700  family  of  32-bit  sin¬ 
gle  board  microcomputers  based  on 
Motorola  680x0  processors,  has  been 
released  by  Consolidated  Computer 
Systems  Inc.  (CCSI). 

The  Ohio  Scientific  720  runs  under 
RTTX,  an  operating  system  compatible 
with  Unix’s  System  V  Interface  Defini¬ 
tion  (SVID)  at  both  the  kernel  and  base 
extension  levels.  RTIX  incorporates  real¬ 
time  capability  within  the  kernel.  The 
real-time  features  of  the  RTIX  kernel 
include  NO_WAIT  system  calls  and  re¬ 
quest  and  event  queues. 

In  its  standard  configuration,  the  720 
has  12  RS-232  ports.  Through  intelli¬ 
gent  terminal  concentrators  and  Eth¬ 
ernet,  the  multiuser,  multitasking  sys¬ 
tem  can  accommodate  as  many  as  60 
users.  If  all  users  are  doing  processor 
or  disk-intensive  tasks,  additional  68020 
CPUs  (with  supporting  FPPs  and  static 
RAM  cache)  can  be  added  in  a  parallel 
arrangement  with  dynamic  load  bal¬ 
ancing. 

Standard  RAM  is  4  Mbytes,  expand¬ 
able  to  64  Mbytes.  The  paged  memory 
management  unit  (PMMU)  provides  de¬ 
mand-paged  virtual  memory. 

The  720  offers  multiple  hard  disks 
ranging  in  size  from  91  Mbytes  to  1.2 
gigabytes  for  total  storage  capacity  to 
16  gigabytes.  OSI  720  is  integrated  with 
MIMER,  a  relational  DBMS  that  offers 
4GL  tools  and  Uniplex  II+,  Version 
5.04b,  an  integrated  word  processor, 
spreadsheet,  database,  and  office  auto¬ 
mation  system. 

Prices  for  the  series  700  computers 
begin  at  $6,350.  Reader  Service  No.  26. 
Consolidated  Computer  Systems  Inc. 
2150-D  W  6th  Ave. 

Broomfield,  CO  80020 
303-460-0444 

Hewlett-Packard  has  announced  that 
it  will  use  the  Motorola  68030  (030) 
microprocessor  in  an  engineering  work¬ 
station.  The  HP  9000  Model  340,  which 
also  incorporates  Motorola’s  68882 
(882)  math  coprocessor,  is  priced  at 
$5,495.  It  offers  up  to  4  MIPS  of  proc¬ 
essing  power. 

Motorola’s  68000  microprocessor  line 
currently  has  four  members:  the  68000, 
68101,  68020,  and  68030.  The  68040  is 
being  developed.  New  generations  of 


the  68000  are  compatible  with  earlier 
68000-based  products,  and,  according 
to  the  company,  software  written  for 
one  chip  runs  with  no  modification  on 
the  others.  Reader  Service  No.  27. 
Motorola  Inc. 

Microprocessor  Products  Group 
6501  William  Cannon  Drive  W 
Austin,  TX  78735-8598 
512-440-2000 

AST  Research  is  now  shipping  the 
Mac86,  an  8086-based  coprocessor 
board  that  allows  users  of  the  Macin¬ 
tosh  SE  to  run  MS-DOS  applications. 
The  board  supports  several  drives  for 
loading  and  saving  MS-DOS  applica¬ 
tions,  including  the  Apple  PC  5.25-inch 
drive,  the  DaynaFile,  or  the  IBM  3.5- 
inch  drive.  Users  can  access  MS-DOS 
programs  via  local  area  networks,  such 
as  AppleShare  or  Tops. 

Mac86  provides  multitasking  under 
Apple’s  MultiFinder,  allowing  an  MS- 
DOS  application  to  process  in  the 
Mac86  window  while  a  Macintosh  ap¬ 
plication  is  running  in  another  window. 
It  offers  the  ability  to  copy  and  paste 
text  and  graphics  from  MS-DOS  appli¬ 
cations  to  Macintosh  applications,  or 
text  from  Macintosh  to  MS-DOS  appli¬ 
cations.  Microsoft  mouse  emulation  us¬ 
ing  the  Macintosh  mouse  is  provided 
as  well. 

The  Mac86  was  jointly  developed  by 
AST  Research,  Apple  Computer  Inc., 
and  Phoenix  Technologies.  It  sells 
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for  $599Reader  Service  No.  28. 

AST  Research  Inc. 

2121  Alton  Ave. 

Irvine,  CA  92714 
714-863-1333 

Oasys  has  announced  the  Version  5.1 
release  of  Microsoft  C,  Microsoft  As¬ 
sembler  (MASM),  Microsoft  Linker,  and 
Oasys’  Microsoft  Embedded  Kit 
(MEK86)  hosted  on  VAX,  Sun,  and 
other  Unix  systems.  The  Oasys  port  of 
Microsoft’s  PC-based  C  development 
tools,  known  as  the  Oasys  Microsoft 
Cross  C  Development  System,  allows 
embedded  systems  software  develop¬ 
ers  to  run  executable  output  on  Intel 
8086/286  embedded  microprocessors, 
as  well  as  MS-DOS  or  OS/2  target  sys¬ 
tems. 

Each  version  of  the  Oasys  Microsoft 
Cross  C  Development  System  is  com¬ 
patible  with  Microsoft  C.  This  new  re¬ 
lease  includes  MEK86,  which  contains 
Microsoft  C  run-time  library  source,  as 
well  as  80x86  initialization  code. 

According  to  Oasys,  the  Cross  C  De¬ 
velopment  system  produces  high¬ 
speed  executables  and  optimized  code 
by  elimination  of  common  subexpres¬ 
sions.  The  compiler  also  implements 
register  variables.  The  system  offers  sev¬ 
eral  memory  models  (small,  compact, 
medium,  large,  huge)  and  pointers 
(near,  far,  huge).  Library  routines  im¬ 
plement  most  of  the  Unix  System  V  C 
library.  Users  can  choose  from  three 
math  libraries  and  generate  in-line  8087/ 
80287  instructions  or  floating  point 
calls. 

The  package,  selling  for  $4,250  to 
$15,500  (depending  on  the  host  sys¬ 
tem),  is  available  on  VAX/VMS,  VAX/ 
Unix  V,  Sun-3  and  Sun-386i,  Apollo, 
and  Pyramid  systems.  Reader  Service 
No.  34. 

Oasys  Inc. 

230  Second  Ave. 

Waltham,  MA  02154 
617-890-7889 

C2PS,  a  compiler  that  converts  C 
source  code  into  PostScript  code,  has 
been  released  by  UniPress  Software. 
C2PS  was  developed  for  use  with  Sun 
Microsystems’  NeWS  window  system 
and  other  environments  requiring  the 
production  of  PostScript  code,  such  as 
Adobe  Systems’  Display  PostScript, 
xl  1/NeWs,  and  PostScript  printer  appli¬ 
cations. 

Developers  write  NeWS  programs  in 
two  parts:  The  first  part,  the  applica¬ 
tion,  is  written  in  C,  while  the  graphic 
interface  is  written  in  PostScript.  With 
C2PS,  the  graphic  interface  can  be  writ¬ 
ten  in  C  and  then  translated. 

C2PS  is  part  of  UniPress’  PostScript 
working  environment.  When  it  is  used 


with  the  UniPress  Emacs  editor,  users 
can  edit  and  view  C  code  in  one  win¬ 
dow  while  viewing  the  produced  Post¬ 
Script  in  another.  The  graphic  output 
can  then  be  shown  in  a  NeWS  window 
or  on  a  printer. 

C2PS  is  available  to  commercial  us¬ 
ers  for  $2,995  with  binary  code,  and 
$14,995  with  source  code.  University 
prices  for  C2PS  are  $995  for  binary  code 
and  $4,995  for  source  code.  Reader  Serv¬ 
ice  No.  30. 

UniPress  Software  Inc. 

2025  Lincoln  Hwy. 

Edison,  NJ  08817 
201-985-8000 

TransWare  Enterprises  (TWE),  a  soft¬ 
ware  development  company,  has 
signed  an  agreement  with  Lahey  Com¬ 
puter  Systems  to  implement  the 
Lahey  Fortran  language  system  under 
Digital  Research  Inc.’s  (DRI)  concur¬ 
rent  DOS  and  FlexOS  386  operating 
systems.  The  new  Fortran  language  sys¬ 
tems  are  scheduled  to  be  available  this 
month. 

Lahey’s  Fortran  compilers  conform 
to  the  ANSI  Fortran  77  language  stan¬ 
dard.  DRI’s  operating  systems  are  mul¬ 
titasking  and  multiuser  capable  for  IBM, 
IBM  compatibles,  and  Compaq  micro¬ 
computers. 

Concurrent  DOS  is  a  DOS-compat¬ 
ible  operating  system  that  runs  in  the 
real-mode  state  of  the  Intel  80x86  mi¬ 
croprocessors.  FlexOS  386  is  a  real¬ 
time  operating  system  that  runs  in  the 
protected  mode  state  of  the  80386  mi¬ 
croprocessor.  Reader  Service  No.  31. 
TransWare  Enterprises  Inc. 

5091  Durango  Ct. 

San  Jose,  CA  95118 
408-723-2102 

The  88open  Consortium  Ltd.  has  an¬ 
nounced  that  NCR  Corp.  has  joined 
the  organization  to  establish  market  ac¬ 
ceptance  of  Motorola’s  88000  RISC  mi¬ 
croprocessor  architecture.  NCR  joins  39 
other  software  and  hardware  vendors 
as  a  members  of  88open. 

NCR  is  currently  active  in  two 
88open  software  development  groups: 
the  88open  binary  compatibility  stan¬ 
dards  (BCS)  program  and  the  software 
initiative  committee.  The  BCS  program 
focuses  on  the  development  and  pro¬ 
motion  of  the  88open’s  BCS  interface 
standard,  and  the  software  initiative  com¬ 
mittee  works  with  developing  applica¬ 
tions  for  88000  systems. 

NCR  plans  to  incorporate  the  88000 
chip  set  in  future  computer  systems. 
Other  88open  members  — such  as  Icon 
International  Inc.,  Jet  Propulsion  Labo¬ 
ratories,  Data  General,  and  Convergent 
Technologies  — plan  to  use  the  88000 
in  future  products. 


The  88open  is  a  nonprofit  organiza¬ 
tion  with  more  than  45  worldwide  mem¬ 
bers.  Reader  Service  No  32. 

88open  Consortium  Ltd. 

8560  SW  Salish  Ln.,  Ste.  500 
Wilsonville,  OR  97070 
503-682-5703 

Using  SAS  Institute’s  SAS/CPE  soft¬ 
ware,  systems  analysts  can  collect,  ana¬ 
lyze,  and  report  current  usage  of  their 
VAX  hardware.  SAS/CPE  software  is  a 
component  of  the  SAS  System,  which 
includes  integrated  modules  for  data 
entry,  retrieval,  and  management;  re¬ 
port  writing  and  graphics;  statistical  and 
mathematical  analysis;  business  plan¬ 
ning;  operations  research  and  project 
management;  and  applications  devel¬ 
opment. 

With  SAS/CPE  software,  systems  man¬ 
agers  can  collect  performance  and  us¬ 
age  data  from  data-gathering  facilities 
such  as  the  VMS  Monitor  Utility,  VAX 
System  Performance  Monitor  (SPM),  the 
VMS  Accounting  Utility,  and  SAS/CPE 
software’s  DISKQUOTA  facility,  which 
gathers  disk  usage  data  over  time. 

Users  can  also  convert  the  data  col¬ 
lected  by  these  utilities  to  SAS  data  sets 
where  they  can  be  analyzed  and  pre¬ 
sented  using  SAS/CPE  software’s  built- 
in,  menu-  or  command-driven  report¬ 
ing  programs. 

Another  feature  is  that  users  can  cre¬ 
ate  tabular  reports,  charts,  line  printer 
graphs,  and  high-resolution  graphs  that 
detail  major  areas  of  resource  usage 
and  system  performance. 

The  SAS  System  is  licensed  on  an 
annual  basis  with  fees  based  on  ma¬ 
chine  classification.  The  first-year  li¬ 
cense  fee  for  SAS/CPE  software  ranges 
from  $850  to  $2,900,  with  renewals  avail¬ 
able  at  a  lower  rate.  Degree-granting 
discounts  are  also  available.  To  use  SAS/ 
CPE  software,  sites  need  base  SAS  soft¬ 
ware.  To  modify  the  menu-driven  por¬ 
tion  of  the  system,  sites  need  SAS/AF 
software,  the  SAS  System’s  interactive 
applications  development  tool.  Reader 
Service  No.  33- 
SAS  Institute  Inc. 

Software  Sales  Dept. 

SAS  Circle 
Box  8000 

Cary,  NC  27512-8000 
919-467-8000 

Ashton-Tate  has  released  Step  IVward 
(pronounced  “Step  Forward”),  a  con¬ 
version  program  that  allows  develop¬ 
ers  with  Clipper,  FoxBASE,  and  Quick¬ 
silver  applications  to  convert  them  to 
dBase  IV.  It  translates  most  of  the  func¬ 
tionality  in  these  products  and  includes 
files  tree  processing,  in-code  comment¬ 
ing,  and  printing  capabilities. 

Suggested  retail  price  is  $89-95. 


Dr.  Dobb’s Journal,  March  1989  155 

216 


0  F  INTEREST _  0  F  I  N  T  E  R  E  S  T 


Reader  Service  No.  34. 

Ashton-Tate  Corp. 

20101  Hamilton  Ave. 

Torrance,  CA  90502-1319 
213-329-8000 
800-227-6900 

An  interface  that  serves  as  a  bridge  from 
ProKit*Workbench  to  PRO-IV  has  been 
released  by  McDonnell  Douglas.  The 
interface  provides  a  CASE  environment 
that  supports  applications  developed 
in  IBM,  DEC,  and  Unix  environments. 

According  to  McDonnell  Douglas,  sys¬ 
tem  developers  can  move  from  strate¬ 
gic  planning,  analysis,  and  design  in 
ProKit'Workbench  to  application  de¬ 
velopment,  implementation,  mainte¬ 
nance,  and  documentation  in  PRO-IV 
without  rekeying  design  specifications. 
The  information  developed  and  man¬ 
aged  within  ProKit'Workbench  during 
analysis  and  design  is  electronically 
transfened  through  the  interface. 

ProKit'Workbench  features  include 
support  for  process  and  data  modeling, 
active  prototyping,  and  design  tech¬ 
niques  that  help  software  engineers  pro¬ 
duce  life  cycle  deliverables  for  devel¬ 
opment  and  maintenance  of  applica¬ 
tion  code.  Applications  developed  in 
PRO-IV  are  hardware,  operating  sys¬ 
tem,  and  database  independent. 
Reader  Service  No.  35. 

McDonnell  Douglas 
600  McDonnell  Blvd. 

Hazelwood,  MO  63042 
800-325-1087 

Software  Development  Systems 
Inc.  (SDSI)  has  introduced  cross-devel¬ 
opment  utilities  licensed  for  Unix  sys¬ 
tems  (CLAUS),  which  includes 
CrossCode  C  for  the  68000  microproc¬ 
essor  family,  the  UniWare  Z80  C  com¬ 
piler,  and  a  line  UniWare  cross-assem¬ 
bler  packages. 

For  Unix  systems  that  read  standard 
9-track  reel  tapes  or  standard  cartridge 
tapes  in  the  Unix  tar  format,  SDSI  pro¬ 
vides  the  cross  development  software 
for  computers  running  Berkeley  Unix, 
AT&T  Unix,  Sun’s  SunOS,  Apollo’s  Do- 
main/IX,  DEC’S  Ultrix,  HP’s  HP-UX,  Se¬ 
quent’s  Dynix,  Xenix,  and  others. 

SDSI  has  also  implemented  a  testing 
suite  that  is  run  as  part  of  each  port. 
This  suite  tests  the  cross  development 
package  to  help  ensure  that  it  works 
the  same  way  on  every  machine  and 
adheres  to  the  documentation  pro¬ 
vided.  Reader  Service  No.  36. 

Software  Development  Systems  Inc. 
4248  Belle  Aire  Lane 
Downers  Grove,  IL  60515 
800-448-7733 

Recently  released  by  Micro  Computer 
Control  (MCC)  is  MICRO/SLD-51,  a  PC- 


hosted  source  language  debugger  pro¬ 
gram  that  provides  C  and  assembly  lan¬ 
guage  debugging  capabilities  for  the 
8051  family  of  single-chip  microcon¬ 
trollers. 

This  software  development  tool  exe¬ 
cutes  8051  or  8052  code  on  a  PC.  It 
includes  support  for  on-chip  devices, 
such  as  the  UART,  timers,  and  inter¬ 
rupts.  With  MICRO/SLD-51,  an  8051  pro¬ 
gram  written  in  C,  assembly,  or  a  com¬ 
bination  of  both  can  be  loaded  into  the 
debugger  for  testing  and  evaluation.  An¬ 
other  feature  of  the  debugger  is  that  it 
single-steps  through  an  8051  program 
line  by  line,  displaying  the  original  C  or 
assembly  source  code  as  the  program 
executes  on  the  host  PC. 

Also  included  are  debugging  tools 
such  as  a  single-line  assembler  and  dis¬ 
assembler,  breakpoints  on  code  or 
data,  symbolic  access  to  program  vari¬ 
ables,  and  dynamic  display  of  any  hard¬ 
ware  register  or  data  variable.  The  pro¬ 
gram  also  includes  context  sensitive 
help  windows  that  the  detail  use  pro¬ 
gram  features. 

MICRO/SLD-51  works  with  program 
files  created  with  the  company’s  MS- 
DOS  based  MICRO/C-51  C  cross-com¬ 
piler  and  assembler  development  pack¬ 
age  or  8051  assemblers  that  can  gener¬ 
ate  standard  Intel  Hex  files. 

This  product  is  priced  at  $295  and 
operates  on  an  IBM  PC  or  compatible 
with  256K  memory  and  one  floppy  disk¬ 
ette.  It  supports  monochrome,  CGA, 
VGA,  or  Hercules  video  adapters  and  is 
compatible  with  laptop  computers. 
Reader  Service  No.  37. 

Micro  Computer  Control  Corp. 

P.O.  Box  275 
Hopewell,  NJ  08525 
609-466-1751 

Microcompatibles  has  announced 
completion  of  its  latest  update  to  GRAF- 
MATIC  Fortran-callable  screen  graph¬ 
ics:  GRAPHMATIC  now  supports  the 
VGA  graphics  board.  Also  included  in 
the  latest  release  are  Microsoft  serial 
mouse  support,  animation,  shaded  sur¬ 
face  plots,  solid  model  shaded  images, 
true  clipping,  ability  to  save  and  restore 
a  graphics  screen,  and  more. 

The  $135  price  includes  support  for 
one  Fortran  compiler  and  one  type  of 
graphics  board  (EGA/CGA  or  Hercules 
Mono).  Additional  libraries  for  other  For¬ 
tran  compiler  or  graphics  boards  are 
$35  each.  Reader  Service  No.  38. 
Microcompatibles  Inc. 

301  Prelude  Dr. 

Silver  Spring,  MD  20901 
301-593-0683 
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S  W  A  I  N  E'  S  FLAMES 


Words  &  Figures 


We  verbiage  vendors  get  customer  complaints,  too.  Two  recent  errors  of  mine  prompted 
readers  to  write. 

One  reader  reminded  me  that  misusing  a  word  damages  its  ability  to  communicate  even 
when  the  intent  behind  the  particular  misuse  can  be  discerned.  “Momentarily,”  he  pointed  out, 
means  “for  a  moment,”  not  “in  a  moment.”  Not  all  authorities  agree,  but  unfortunately  for  me,  I  do. 

As  to  the  “wont/won’t”  error,  my  first  reaction  is  to  say  that  of  course  I  know  better.  But  a 
professional  writer  is  no  more  literate  than  his  published  work,  and  I  wasn’t  earning  my  pay  when 
I  let  that  one  get  by. 

Because  we  all  use  language  every  day,  we  tend  to  overlook  misuses  of  language  even  by  those 
who  are  paid  to  use  it  effectively.  We  need  not  be  so  generous:  People  who  make  their  living  by 
putting  words  together  should  be  held  to  high  standards,  just  as  professional  programmers  are 
held  responsible  for  every  little  bug.  Having  delivered  my  mea  culpa,  I  intend  to  point  out  here, 
from  time  to  time,  some  of  the  more  awful  or  hilarious  violations  of  sense  and  logic  in  the 
computer  press. 

I  also  plan  to  look  at  pictures:  Charts,  tables,  and  figures  can  lie.  I’ll  be  doing  this  for  more  than 
entertainment  value.  If  you  read  DDJ ,  you  sometimes  get  treated  as  an  expert  on  things 
quantitative,  and  it  can’t  hurt  to  be  reminded,  from  time  to  time,  of  some  of  the  misleading  ways 
in  which  quantitative  data  can  be  presented. 

Take  Apple’s  latest  annual  report.  The  report  opens  with  a  bank  of  four  bar  charts,  slightly 
three-dimensional  and  tilted,  showing  sales,  earnings  per  share,  and  so  forth,  all  zooming 
skyward.  The  scale  is  fair,  but  the  tilting  has  the  effect  that  increases  are  represented  by  heavy, 
steep  bands  of  color  and  decreases  by  a  lack  of  ink  on  the  page.  The  drops  almost  have  to  be 
deduced  — you  don’t  see  them  at  all  at  first. 

It’s  a  clever  trick. 

Copyright  Protection 

Those  of  us  who  have  hounded  copy-protection  into  its  present  state  of  disrepute  and  declining 
employment  should  now  be  enjoined  to  exert  equal  effort  on  behalf  of  copyright  protection  for 
software  authors. 

Copy  protection  may  have  been  a  bad  attempt  to  solve  the  problem  of  copyright  violation,  but 
the  problem  remains  and  grows  more  severe,  with  no  solution  in  sight. 

I  don’t  think  that  educational  efforts  are  the  solution.  Although  there  are  consumers  selfless 
enough  to  forego  copying  for  the  good  of  the  author  or  of  the  software  industry,  in  general  no 
amount  of  education  is  going  to  make  consumers  act  against  their  apparent  financial  interests.  An 
immediate  saving  of  several  hundred  dollars  is  a  hard  argument  to  refute.  Shareware  works  to  the 
extent  that  the  vendor  can  convince  the  consumer  that  their  relationship  is  something  other  than 
a  vendor-consumer  relationship,  but  when  big-ticket  vendors  try  to  do  the  same  through  guilt  trip 
advertisements  and  shrinkwrap  licenses,  the  consumer  is  justly  skeptical. 

The  analogy  of  book  publishing  doesn’t  point  to  a  solution,  because  the  problem  hasn’t  been 
solved  there,  either.  If  books  were  as  easy  to  copy  as  software,  book  buyers  would  make  copies 
for  their  friends  as  casually  as  they  copy  tapes  and  disks. 

The  October  1988  issue  of  Appledirect,  Apple’s  monthly  magazine  for  developers,  carries  a 
relevant  viewpoint  by  Lionshead  Software  president  Chris  Gillette.  Gillette  challenges  Apple  to 
address  the  problem  by,  for  example,  providing  Macintosh  developers  with  a  ROM  call  to  get  the 
computer’s  serial  number.  This  would  let  vendors  permit  unlimited  copying  of  distribution  disks, 
while  tying  disks  to  one  machine,  and  is  a  scheme  that  has  been  used  by  Sun  and  Hewlett- 
Packard,  as  well  as  by  Apple  itself  in  the  Lisa. 

Strategic  placement  of  the  serial  number  check  could  turn  a  program  into  a  crippled  demo 
version  of  itself  when  run  on  an  unauthorized  computer,  so  that  when  users  created  copies  for 
friends,  they  would  be  promoting  sales.  It’s  possible  to  defeat  such  a  copyright  protection  scheme, 
but  as  Gillette  points  out,  it’s  not  the  professional  who’s  the  problem,  but  the  amateur,  who  copies 
because  it’s  so  easy. 

Whether  or  not  Gillette’s  proposal  is  a  solution  for  copyright  protection,  it’s  deserving  of 
discussion.  Maybe  it  could  serve  as  a  starting  point  for  a  debate  on  ethical  and  effective  means  to 
protect  software  authors’  rights. 

Then  again,  it  is  possible  that  software  copying  is  just  the  consumer’s  way  of  adjusting  the  price 
to  an  acceptable  level.  If  that’s  the  case,  the  consumer  will  eventually  win,  quality  software  will  sell 
for  $19.95,  and  casual  copying  will  not  cease,  but  will  cease  to  be  a  concern. 

Michael  Swaine 
editor-at-large 
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EDITORIAL 


Unlike 
Old  Soldiers, 
Memory 
Problems 
Don’t  Fade 
Away 


I  can  see  it  all  now.  No  longer  will  future  generations  have  to  put  up  with  the  sad  litany,  “When 

I  was  your  age,  I  had  to  walk  two  miles  through  the  snow _ ”  Instead,  kids  will  be  hearing 

something  like,  “Well,  when  I  was  your  age,  I  only  had  64K  of  memory  to  work  with.”  And 
instead  of  “Tell  me,  what  did  you  do  in  the  war,  Dad?”  parents  will  be  asked  “Tell  me  Dad,  what 
was  it  like  to  write  programs  in  256k  of  memory?” 

Yes,  having  only  64 K  (or  even  256K  for  that  matter)  of  memory  is  pretty  much  a  thing  of  the 
past,  although  veterans  of  the  PC  wars  (those  guys  with  the  hint  of  gray  in  their  hair  and  the 
melancholy  smile  on  their  face)  still  reminisce  about  the  good  old  days  of  limited  memory,  slow 
CPUs,  and  8-inch  disk  drives. 

What’s  particularly  interesting  about  the  current  memory  situation  is  that  even  though  the 
problem  of  limited  memory  has  — to  some  degree  — gone  away,  the  problems  of  efficiently  using 
whatever  memory  is  available  remains.  What  with  laiger,  more  complex  programs,  TSRs,  and  a 
host  of  other  constraints  (don’t  forget  that  OS/2  requires  nearly  2  Mbytes  just  to  boot!),  memory 
management  problems  haven’t  even  begun  to  go  away.  And  therein  lies  one  of  the  reasons  we’re 
taking  a  look  at  memory  management  this  month. 

Two  of  our  articles  — “More  Memory  for  DOS  Exec”  and  “SWAP”  — take  different  approaches 
to  a  similar  problem:  how  to  swap  programs  in  and  out  of  expanded  memory  (or  disk)  so  that  you 
can  free  up  main  memory  to  use  more  than  one  program  at  a  time.  In  the  first  of  these  articles,  Kim 
Kokkonen  shares  with  us  some  of  the  actual  techniques  he  uses  in  the  development  of  his 
TurboPower  tools,  proving  that  he’s  a  good  writer,  as  well  as  a  good  programmer. 

Two  other  of  this  month’s  articles  — “Demand  Page  Virtual  Memory”  and  “Advanced  80386 
Memory  Management”  — also  look  at  similar  topics.  In  the  first  instance,  Kent  Dahlgren  examines 
the  general  subject  of  demand  page  memory  and  discusses  how  different  CPUs  handle  paging.  In 
the  second,  Neal  Margulis  looks  in  depth  at  demand  paging  on  the  80386. 

These  won’t  be  the  only  articles  we’ll  be  running  that  discuss  the  problem  of  memory 
management.  The  topic  is  too  important  to  simply  touch  on  and  forget. 


The  last  time  we  asked  for  articles  was  in  October  and  we  heard  from  a  lot  of  you  who  had  all  kinds 
of  good  ideas  for  articles.  You’ve  already  seen  some  of  those  articles  in  print  and  you’ll  see  more 
in  the  next  few  months.  But  don’t  let  up.  If  you  have  an  idea  for  an  article,  get  it  (the  idea  or  the 
article)  to  us. 

What  kind  of  articles  are  we  looking  for?  Well,  how  about  one  that  discusses  your  approach  to 
memory  management.  What  kind  of  articles  would  you  like  to  see  in  the  magazine?  What  kind  of 
articles  would  be  useful  to  you?  If  you  have  a  useful  utility  or  technique,  you  can  bet  that  other 
readers  would  find  it  just  as  useful. 

The  editorial  calendar  for  the  rest  of  the  year  looks  like  this:  May,  Structured  Languages;  June, 
Operating  Systems;  July,  Graphics;  August,  the  Annual  C  Issue;  September,  Modeling  and  Simula¬ 
tion;  October,  Telecommunications;  November,  Parallel  Processing;  and  December,  Object- 
Oriented  Programming.  While  we’re  looking  for  articles  on  these  subjects,  we’ll  consider  just  about 
any  task-specific,  code-intensive  article.  If  you  miss  one  of  our  deadlines  (say  you  have  a  graphics 
article  but  don’t  get  it  done  in  time  for  our  July  issue),  don’t  worry.  If  it’s  good,  we’ll  run  it  at  anytime. 

If  you  have  any  ideas  for  articles  on  any  of  the  above  topics  — or  others  — give  Kent,  Mike,  or 
me  a  call  at  413-366-3600,  or  drop  us  a  note  at  DDJ,  501  Galveston  Drive,  Redwood  City,  CA  94063. 
We  can  also  be  reached  on  CompuServe  (#76704,50),  MCI  Mail  (“DDJ"),  or  BIX  (“jerickson”).  We’ll 
look  forward  to  hearing  from  you  and  publishing  your  articles  over  the  coming  months. 


Jonathan  Erickson 
editor-in-chief 
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Conversion  Confusion 

Dear  DDJ, 

I  enjoyed  Rob  Moore’s  article  on  “Map¬ 
ping  DOS  Memory  Allocation”  (Novem¬ 
ber  1988)  very  much;  it  made  a  lot  of 
sense.  I  did  have  some  problems  con¬ 
verting  it  over  to  Microsoft  C,  though. 
The  one  change  I  discovered  was  that 
<dos.h>  in  Microsoft  C  does  not  con¬ 
tain  a  MKJFP  (segment,  offset)  macro, 
so  I  borrowed  the  macro  from  a 
friend  who  uses  Turbo  C.  The  macro 
left  shifts  the  segment  into  the  next 


word  and  ors  the  offset  in. 

This  one  macro,  however,  was  not 
enough.  I  am  not  convinced  that  my 
program,  called  ptrmcb,  is  accurately 
finding  memory  control  blocks.  The 
first  five  bytes  of  the  first  memory- 
control  block  found  are:  0973:0000  4D 
08  00  08  02.  Referring  to  the  structure 
of  “struct  mcb”:  chain  =  ’M’;  pid  =  2048; 
psize  =  2050. 

I  am  using  QuickC  and  MSC  4.0  with 
MS-DOS  3-3.  Example  1  shows  a  run 
of  both  mcb  and  mapmem.  Any 
thoughts  on  completing  the  conversion 
from  Turbo  C  to  Microsoft  C  would  be 
appreciated. 

Bruce  Koivu 

Orlando,  Fla. 

Robert  responds: 

You  are  correct  that  Microsoft  C  (MSC) 
provides  no  macro  MK_FP  (seg,off)  to 
construct  a  far  pointer  composed  of 
segment  seg  and  offset  off.  Other  DDJ 
readers  have  pointed  this  out  to  me, 
notably  Ron  Sonntag  (of  Analytical  Soft¬ 
ware  Consulting  in  Seattle,  Wash),  who 
found  it  necessary  to  replace  the  macro 


FP_SEG  with  the  Turbo  C  version  and 
make  other  related  macro  definition 
adjustments  when  converting  MCB.C 
to  run  under  MSC  5.1.  (I  won’t  give 
any  further  details  because  I  currently 
do  not  have  access  to  a  copy  of  MSC 
and  cannot  personally  vouch  for  the 
results.) 

Mr.  Koivu’s  erroneous  output  from 
my  MCB  program  is  almost  certainly 
due  to  compilation  of  the  program  with 
a  compiler  option  set  to  word  align¬ 
ment.  My program  will  not  execute propb 
erly  under  any  C  compiler  unless  byte 
alignment  is  used.  I  worked  out  the 
examples  after  reader  Edward  Rippy 
of  Oakland,  Calif,  informed  me  of  simi¬ 
lar  problems  he  encountered  when  he 
tried  word  alignment  under  Turbo  C. 

When  compiled  under  byte  align¬ 
ment  (this  is  the  default  in  Turbo  C), 
MCB. EXE  reports  the  results,  shown  in 
Example  2,  when  invoked  on  my  cur¬ 
rent  system  ( true  blue  IBM  PC  running 
under  PC-DOS  3.2). 

When  I  compile  under  word  align¬ 
ment  (Options/Compiler/Code  Genera¬ 
tion/Alignment  Word  in  the  Turbo  C 
integrated  environment  or  the  com¬ 
mand  line -a  option)  and  run  the  new 
MCB. EXE  I  get  the  results  that  are  shown 
in  Example  3- 

Note:  All  characters  marked  *  (aster¬ 
isk)  are  various  nonprintable  charac¬ 
ters,  which  confirms  all  the  more  that 
there  is  a  problem. 

This  latter  mess  is  similar  to  that 
reported  by  reader  Koivu.  Let  me  ex¬ 
plain  what  has  gone  wrong.  The  rele¬ 
vant  contents  of  the  first  MCB  located 
at  0974:0000  (hex)  in  my  case  are  4D 
08  00  E7  20  00  determined  by  using 
DOS  DEBUG.  A  pointer  to  struct  MCB 
is  used  as  a  template  to  overlay  and 
retrieve  the  contents  of  the  MCBs  as 
they  already  exist  in  memory.  From 
my  MCB.C  listing,  struct  MCB  is  de¬ 
fined  as: 

struct  MCB 

1 

char  chain; 

unsigned  pid; 

unsigned  psize; 

char  unusedlll]’ 


With  byte  alignment,  the  compiler  does 
not  adjust  user-defined  structures,  so, 
if  a  structure  of  this  type  overlays  the 
first  MCB  in  memory  we  get: 

chain  =  4D  (’M’interpreted  as  char) 
pid  =  08  00  (0x0008  interpreted 
as  unsigned) 

psize  =  E7  20  (0x20EF  interpreted 
as  unsigned) 


PSP 

bytes 

owner 

command  line  hooked  vectors 

0008 

8320 

N/A 

0B7D 

4176 

N/A 

22  24  2E 

0C99 

603760 

free 

MCB 

MCB  ID 

PID 

MB 

PAR- 

ENV  OWNER 

NO. 

SEG 

SIZE 

ENT 

BLK? 

01 

0973  M 

0800 

28704 

068C 

N 

02 

0973  0007 

7808 

022B 

N  UNKNOWN  OWNER 

Example  1:  Allocated  Memory  Map  by  TurboPower  Software  Version  1.8 


MCB 

NO. 

MCB  ID 
SEG 

PID 

MB 

SIZE 

PAR¬ 

ENT 

ENV 

BLK? 

OWNER 

01 

0974  M 

0008 

134768 

0291 

N 

IBMDOS . COM/MSDOS . SYS 

02 

2A5C  M 

2A5D 

3120 

2A5D 

N 

COMMAND.COM  COPY  #1 

03 

2B20  M 

2A5D 

160 

2A5D 

Y 

COMMAND.COM  COPY  #1 

(22  MCBs  not 

relevant  to 

discussion  omitted) 

25 

331B  M 

3327 

160 

2A5D 

Y 

C:\UTIL\MCB.EXE 

26 

3326  M 

3327 

71264 

2A5D 

N 

C:\UTIL\MCB.EXE 

27 

448D  Z 

0000 

374560 

F000 

N 

FREE  MEMORY  CONTROL  BLOCK 

Example  2:  MCB.C  compiled  with  byte  alignment  (the  default) 


MCB 

NO. 

MCB 

SEG 

ID 

PID 

MB 

SIZE 

PAR¬ 

ENT 

ENV 

BLK? 

OWNER 

01 

02 

0974 

0999 

M 

* 

E700 

BCD0 

512 

11568 

FF7E 

0720 

N 

N 

************* 

UNKNOWN  OWNER 

Example  3:  MCB.C  compiled  with  word  alignment 
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This  occurs  because  the  contents  of  off¬ 
set  0  are  assigned  to  chain,  offsets  1 
and  2  to  pid,  and  offsets  3  and  4  to 
psize,  which  you  would  expect  upon 
examination  of  the  definition  of  struct 
MCB.  (When  interpreting  the  results 
remember  that  Intel processors  use  “back- 
words ’’storage.) 

Furthermore,  the  size  of  struct  MCB 
is  0x10  (16  decimal),  so  each  unit 
increment  of  a  pointer  to  such  a  struc¬ 
ture  (ptrmcb  in  my  published  MCB.C 
listing)  increases  the  address  of  the 
pointer  by  0x10  bytes.  The  next  MCB 
is  thus  located  at  0x974:0  +  0x20EF  " 
0x10  +  1  =  0x2A5C:0  and  agrees  with 
MCB  NO.  02  in  Example  2. 

With  word  alignment,  the  compiler 
generates  code  to  start  each  field  of  a 
structure  on  an  even  address  bound¬ 
ary,  which  provides  for  quicker  execu¬ 
tion  on  the  80286  and  80386 proces¬ 
sors.  Usually  such  adjustments  by  the 
compiler  make  no  difference.  However, 
in  a  case  where  a  structure  is  used  as 
a  template  (i.e.,  used  to  overlay  and 
retrieve  existing  data  in  memory  writ¬ 
ten  by  some  other  process),  such  com¬ 
piler  adjustments  are  generally  un¬ 
wanted.  Let’s  see  what  goes  wrong  in 
the  case  at  hand. 

With  word  alignment  we  get 

chain  =  4D  CM’  interpreted  as  char) 

pid  =  00  E7  (0xE700  interpreted 
as  unsigned) 

psize  =  20  00  (0x20  interpreted  as 
unsigned) 

This  is  because  the  compiler  has  pad¬ 
ded  the  byte  after  the  chain  field  with 
an  extra  byte  so  that  the  remaining 
structure  fields  pid,  psize,  and  un- 
usedfllj  all  start  on  word  boundaries. 
The  unusedfllj field  is  also  padded  on 
the  end  with  an  extra  byte  so  that  the 
structure  holds  an  even  number  of  bytes 
(0x12  =  18  in  this  case).  The  vales  of 
pid  and  psize  are  then  read  from  the 
contents  of  offsets  2-3  and  4-5,  respec¬ 
tively.  You  can  imagine  the  problems 
this  creates  since  the  proper  values  are 
contained  in  offsets  1-2  and  3-4  in¬ 
stead.  Furthermore,  each  increment  of 
a  pointer  to  this  word  aligned  structure 
increases  the  pointer’s  address  by  0x12 
bytes,  not  by  OxlO.  It  is  no  wonder  the 
main  logic  of  the  MCB  program  (chain 
successively  from  the  first  to  the  last 
MCB)  is  immediately  derailed  leading 
to  the  print  out  of  garbage. 

Reader  Sonntag  informs  me  that  the 
statement  *pragma  pac(l)  (an  MSC 
compiler  directive)  placed  at  the  top 
of  the  MCB.C  source  file  will  cause 
MSC  5.1  to  compile  with  byte  align¬ 
ment.  I  would  imagine  that  an  equiva¬ 


lent  command  line  switch  (for  MSC) 
or  a  menu  selection  (for  Quick  C)  ex¬ 
ists  to  accomplish  the  same  thing.  In 
any  case,  I  strongly  recommend  that 
CodeView  be  used  to  step  through 
MCB.EXE  to  drive  home  the  ideas  I 
have  presented. 


Answers  Anyone ? 

Dear  DDJ, 

Tandy  Corp.  offers  a  20-Mbyte  hard 
disk  for  its  mode  1400  LT  portable  com¬ 
puter,  which  I  eagerly  purchased  hop¬ 
ing  to  finally  have  a  gem  of  a  machine. 
But  alas  .  .  .  problems  with  the  power 
supply  destroyed  my  aspirations. 

It  seems  to  me  that  the  AC  power 
adapter  supplied  with  the  1400  LT  does 
not  produce  enough  current  to  sustain 
the  1400  LT  and  cannot  operate  the 
computer  (and  hard  disk)  on  AC  only. 
My  question  is  as  follows:  Is  it  possible 
to  substitute  the  AC  power  adapters 
supplied  with  the  unit  with  a  more 
powerful  one?  If  so,  how  can  I  obtain 
or  build  one? 

The  following  information  could  pos¬ 
sibly  be  of  help  in  solving  my  problem: 
Tandy  AC  adapter  (supplied  with  unit); 
class  2  transformer;  input  120V  AC, 
60Hz,  20W;  and  output  15V  DC,  700mA. 
Also,  I  have  a  LiteDrive-II  hard  disk 
subsystem  by  CMS  Enhancements. 

A  solution  to  this  problem  would 
greatly  benefit  me  and  my  fellow  1400 
LT  users. 

Wilberto  Garcia 

456  Beach  63rd  St. 

Arveme,  NY  11692 


Ecstatic  About  Al 

Dear  DDJ, 

I  am  writing  the  first  letter  to  a  maga¬ 
zine  that  I  have  ever  written  in  my  (47 
years)  life,  in  response  to  the  recent 
series  by  Al  Stevens.  In  a  nutshell,  1 
think  the  series  has  been  fantastic! 

I  started  programming  25  years  ago 
in  Cobol;  I  have  written  in  Assembler, 
Fortran,  Basic,  Easycoder,  and  Auto¬ 
coder,  and  I  have  thoroughly  enjoyed 
the  “C  Column.”  As  a  youngster  I  used 
to  enjoy  saving  my  nickels  and  buying 
Popular  Mechanics  magazine  (for  25 
cents),  taking  it  home,  building  some¬ 
thing  based  on  an  article,  and  then 
showing  it  off  to  my  family  and  friends. 
Thanks  to  Al  Stevens’  column,  I  can 
enjoy  the  same  pleasure  and  satisfac¬ 
tion  that  I  did  so  many  years  ago. 

I  am  a  programmer:  I  write  computer 
software  (for  a  firm  in  Silicon  Valley), 
and  I  still  enjoy  tinkering.  Thanks  to 


Al’s  great  column,  I  look  forward  to  Dr. 
Dobb’s  Journal  every  month  like  I  used 
to  look  forward  to  the  latest  Popular 
Mechanics. 

Don’t  let  the  flak  from  the  Microsoft 
C  folks  derail  a  great  project.  The  seri¬ 
ous  programmer  doesn’t  want  to  hear 
the  politics  about  which  C  compiler  is 
better  or  why.  Let  the  Dvoraks  handle 
that,  and  keep  Al  Stevens  busy  with  the 
projects  that  are  so  much  fun  and  so 
rewarding.  Thanks  a  million! 

Richard  M.  Linder 

Los  Gatos,  Calif. 


Mad  About  Modula-2 

Dear  DDJ, 

I  take  umbrage  with  your  (Kent  Por¬ 
ter’s)  complaints  on  the  wordiness 
of  Modula-2  library  procedures.  Even 
the  most  primitive  of  text  editors 
(and  the  JPI  environment)  will  perform 
global  substitutions;  thus,  one  need 
only  type  some  small  acronym  until 
one  is  finished  and  replace  them  later. 
Actually,  I  tend  to  place  reassignments 
such  as 

CONST  WRiteChar  =  IO.WrChar; 

in  my  modules  because  I  personally 
find  the  abbreviation  “Wr”  somewhat 
damaging  to  the  eye. 

The  aspect  of  Modula-2  that  I  take 
dearest  to  heart  is  the  necessity  of  ex¬ 
plicitly  stating  the  location  of  the  pro¬ 
cedures  used.  In  contrast,  C  will  freely 
accept  IOUs  in  lieu  of  code,  and  it’s 
not  until  the  linker  hauls  you  up 
before  the  bench  that  you  know  some¬ 
thing  is  missing.  Modula-2  demands 
cash  on  the  barrelhead  (or  at  least  in 
the  definition  modules),  or  one  goes 
nowhere. 

The  notion  of  type  transfer  allows 
you  to  do  as  much  damage  in  this 
language  as  in  C.  Simply  assign  an  arbi¬ 
trary  code  location  to  a  PROC-type  vari¬ 
able  and  then  call  it  to  see  this.  Perhaps 
one  could  convert  this  into  some  sort 
of  inline  code  for  JPI  (by  assigning  the 
location  of  a  constant  aggregate),  but 
it  doesn’t  seem  worth  it,  for  their  as¬ 
sembler  meshes  so  nicely  with  their 
compiler. 

I  hope  your  successor  (Jeff  Dun- 
temann)  will  not  forgo  Modula-2  for 
Turbo  Pascal. 

John  O.  Goyo 


DDJ 
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More  Memory  for 

DOS  Exec 


Swapping  calling  programs  in  and  out  of  expanded  memory 1 
is  useful  when  programs  invoke  each  other 


(im  Kokkonen 


A  s  many  have  lamented,  the  6-tOK  of  memory  avail¬ 
able  to  DOS  programs  is  looking  smaller  every 
year  With  TSRs  gobbling  up  memory  on  one  end, 
and  applications  growing  larger  on  the  other,  it  is 
easy  to  use  up  all  the  space.  Of  course,  necessity 
is  the  mother  of  invention,  so  desperate  DOS  programmers 
have  devised  a  number  of  ad  h<x"  methtxis  —using  ex¬ 
panded  and  extended  memory,  overlays,  and  so  on  —to 
cram  more  functions  into  the  same  space 
This  article  describes  another  such  method.  I've  enhanced 
the  DOS  Exec  function  by  swapping  most  of  the  calling 
program  into  expanded  memory  or  to  disk,  and  giving  all 
that  free  memory  to  the  child  process.  When  the  subprtxess 
is  complete,  the  calling  program  is  sw  apped  back  into  place 
and  continues  normally.  This  technique  is  especially  valu¬ 
able  for  menuing  environments  that  must  Execute  other 
large  programs,  or  modem  programming  editors  that  are 
expected  to  spawn  huge  compilations  at  the  touch  of  a  key 
In  fact,  it's  useful  for  any  program  that  must  invoke  another 
The  swapping  Exec  function  is  implemented  in  a  Turbo 
Pascal  5,0  unit  called  ExecSwap.  The  meat  of  the  code  is 
written  in  assembly  language,  however,  and  with  some 
changes  could  be  linked  into  other  languages 

Turbo  Postal  Program  Organization 

In  order  for  me  to  explain  how  /iretSwap  works,  we  ll  need 
to  delve  into  the  organization  of  a  Turbo  Pascal  program. 
Let's  examine  this  program  called  A",  show  n  in  Example  1. 

What  this  program  does  isn't  important.  I'll  use  it  just  to 
show  the  arrangement  of  memory'.  A'  uses  two  of  Turbo's 
standard  units,  Crt  and  Dos .  It  also  implicitly  uses  the  System 
unit,  as  does  every  Turbo  Pascal  program.  Table  1  maps  out 
the  various  segments.  (You  can  see  a  similar  map  of  a  real 
program  by  having  the  compiler  create  a  MAP  file  and 
inspecting  the  segment  map  at  the  beginning  of  that  file.) 
It's  important  to  note  that  each  Pascal  unit  has  its  own  code 

Kirn  Kokkonen  is  the  president  of  TurhoPawer  Software  and 
the  author  of  many  public  domain  I'urho  Pascal  tools.  He 
can  be  reached  at  PO.  Box  66747.  Scotts  Valley.  C'A  95066 
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segment  (denoted  by  <  -  <  AT  etc.  in  Table  1 ),  ami  that  (lie 
code  segments  are  arranged  in  what  might  seem  like  reverse 
order.  That  is,  the  unit  appearing  first  in  the  i  SES  statement 
is  linked  at  the  highest  memory  address,  and  the  main 
program  has  the  lowest  code  segment.  Also,  it  the  program 
doesn't  need  to  use  the  heap,  the  memory  above  the  heap 
base  may  not  be  allocated. 

ExecStcaps  goal  is  to  copy  most  of  the  memory  used  by 
the  program  to  secondary  storage  and  then  to  deallocate 
that  memory.  ExecSwap  needs  to  leave  only  enough  of  itself 
behind  to  call  DOS  Exec  and  restore  the  image  when  the 
child  process  returns. 

By  this  criterion  the  best  place  for  ExecSuafi s  r  ode  would 
be  in  the  main  body  of  the  program.  This  way  it  could  Mart 
swapping  memory  at  the  lowest  possible  code  segment  and 
free  the  most  memory  for  the  child  process  In  fable  I  s 
terms  it  would  start  swapping  at  axle  segment  CS_X  and 
continue  to  the  top  of  the  program.  After  deallocating  mem¬ 
ory,  the  only  overhead  would  be  the  program  segment 
prefix  (2s()  bytes >  plus  the  portion  of  segment  (.'.STY  re¬ 
quired  to  undo  the  swap.  Example  2  shows  what  memory 
might  look  like  while  the  child  process  was  active  The  rest 
of  program  A' would  have  been  stored  tn  IMS  memory  il 
available,  or  in  a  disk  file  if  not. 

There’s  another  factor  to  consider,  though  ExecSwap 
should  be  convenient  to  use  in  more  than  just  one  program. 
Hence,  I've  made  it  a  self-contained  unit  which  is  available 


lust  by  adding  it  to  the  main  program's  USES  statement. 
Considering  Table  1  again,  it  s  clear  that  when  you  I  iSE 
ExecSwap  you  want  to  add  it  at  the  end  of  the  list.  In  that 
case,  the  memory  map  wit!  look  like  Example  -i  The  mem¬ 
ory  that  remains  allocated  during  the  Exec  is  the  PSP.  the 
code  in  the  main  program  A",  and  whatever  pan  of  ExecSwap 
must  remain  resident 

The  main  program's  code  segment  need  not  be  large,  of 
course  In  the  extreme  case,  the  main  program  would  con¬ 
sist  of  nothing  but  a  I  'SES  statement  anti  a  single  procedure 
call  to  another  unit.  Hus  reduces  the  overhead  of  the  Exe c 
call  to  essentially  just  the  PSP  plus  ExecSwap  itself  And 
that’s  not  much  ExecSwap’ s  resident  portion  consumes  less 
than  2,000  bytes 

Using  ExecSwap 

Before  we  plunge  into  the  mechanics  of  ExecSwap,  El! 
descrilx*  how  h  is  used  bv  an  apple,  ation  The  unit  interfaces 
three  routines,  shown  in  Example  c  Before  performing  an 
Exec  call,  the  program  must  call  ImiExecSuap  This  routine 
computes  how  many  bytes  to  swap  and  allocates  space  to 
store  the  swapped  region. 

The  swapped  region  of  memory  starts  just  beyond  the 
resident  portion  of  ExecSwap.  The  programmer  must  spec 
ify  the  end  of  the  region  with  the  parameter  IxistlnSarc 
because  the  choice  depends  on  how  the  program  uses  the 
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(continued  from  page  15) 

heap.  What  you  choose  for  LastToSave  affects  only  the  size 
of  the  swap  file  or  the  amount  of  EMS  memory  needed;  it 
has  no  effect  on  resident  overhead  during  the  Exec  call. 

There  are  three  reasonable  values  for  LastToSave.  Passing 
the  System  variable  HeapOrg  tells  ExecSwap  not  to  save  any 
part  of  the  heap;  this  is  the  correct  option  for  programs  that 
make  no  use  of  the  heap.  Passing  the  system  variable 
HeapPtr  causes  ExecSwap  to  save  all  allocated  portions  of 
the  heap.  Only  the  free  list  is  ignored,  so  this  is  a  good 
choice  for  programs  that  don’t  fragment  the  heap.  Passing 
the  expression  PtrfSeg  (FreePtrA)  +$  1 000,  0)  tells  ExecSwap 
to  save  the  entire  heap,  including  the  free  list.  This  is  the 
most  conservative  option,  but  it  may  lead  to  swap  files 
approaching  640K  bytes  in  size. 

InitExecSwap’s  second  parameter,  SwapFileName,  speci¬ 
fies  the  name  and  location  of  the  swap  file.  If  EMS  memory 
is  available,  this  name  won’t  be  used;  otherwise  InitExecSwap 
will  create  a  new  file.  InitExecSwap  assures  that  sufficient 
EMS  or  disk  space  exists  for  the  swap;  if  not,  it  returns 
FALSE.  To  minimize  swap  times,  it’s  a  good  idea  to  put  the 
swap  file  on  the  fastest  drive  that  will  hold  it.  It’s  also 
prudent  to  avoid  a  floppy  drive  because  the  user  may 
change  disks  while  the  child  process  is  active.  The  swap  file 
remains  open,  using  a  file  handle,  until  ShutdownExecSwap 
is  called  or  the  program  ends.  InitExecSwap  marks  the  file 
with  the  Hidden  and  System  attributes  so  that  the  user  of  the 
child  process  won’t  be  tempted  to  delete  it. 

ExecWithSwap  is  analogous  to  the  standard  Exec  proce¬ 
dure  in  Turbo’s  Dos  unit.  Its  first  parameter  is  the  path  name 
of  the  program  to  Execute,  and  its  second  is  the  command 
line  to  pass  to  it.  The  only  difference  from  Exec  is  that 
ExecWithSwap  is  a  function,  returning  the  status  of  the  call 
in  a  Word.  The  function  returns  DOS  error  codes,  with  one 
exception.  The  most  common  error  codes  are: 

0  success 

1  swap  error  (no  swap  storage,  disk  error,  EMS  error) 

2  file  not  found 

3  path  not  found 

8  insufficient  memory 

You  may  never  need  to  call  ShutdownExecSwap ,  since 
ExecSwap  sets  up  an  exit  handler  that  automatically  calls  it 


program  X; 

uses  {System, )  Dos,  Crt; 
begin 

ClrScr; 

Exec{'  C :  (COMMAND .  COM' ,  "); 
end. 

Example  1:  An  examination  of  program  X 

PSP: 

program  segment  prefix 

lower  addresses 

CS  X: 

Xcode 

( 

CS  Crt: 

Crt  code 

| 

CS  Dos: 

Dos  code 

V 

CS  System: 

System  code 

higher  addresses 

DS: 

initialized  data 
uninitialized  data 

| 

SS: 

stack 

V 

HeapOrg: 

heap  base 

HeapPtr: 

heap  high  water  mark 

available  heap  space 

FreePtr: 

free  list 

FreePtr+IOOOh 

top  of  program 

available  DOS  memory 

xxxx: 

top  of  memory 

Table  1:  Memory  map  of  example  program 


when  the  program  ends.  In  some  cases,  however,  you  may 
want  to  close  and  erase  the  swap  file  or  regain  EMS  space 
before  continuing. 

There’s  a  conundrum  here.  ExecSwap  should  be  last  in 
the  USES  list,  but  the  main  program  should  do  as  little  as 
possible.  So  where  do  you  place  calls  to  the  ExecSwap 
routines?  It’s  easiest  to  call  them  from  the  main  program  and 
take  the  hit  in  overhead.  Turbo  Pascal  provides  a  better  key 
to  the  puzzle,  though.  Version  5  supports  procedure  vari¬ 
ables,  and  Version  4  makes  it  easy  to  fake  them.  So  do  this: 
In  the  main  program,  assign  the  address  of  each  ExecSwap 
procedure  to  a  procedure  variable  declared  in  a  unit  used 
early  in  the  USES  list.  Then  call  ExecSwap s  routines  in  any 
later  unit  by  referring  to  the  procedure  variables. 

One  caution  about  using  ExecSwap.  Because  most  of 
your  program’s  code  isn’t  in  memory  while  the  child  process 
runs,  it’s  essential  that  the  program’s  interrupt  handlers  be 
deactivated  first.  Turbo  Pascal  5  provides  a  handy  proce¬ 
dure  called  SwapVectors  that  does  this  for  all  the  System 
interrupt  handlers.  Call  SwapVectors  just  before  and  after 
ExecWithSwap,  and  treat  any  of  your  own  handlers  in  a 
similar  fashion. 

Listing  One,  page  66,  offers  a  simple  example  of  using 
ExecSwap.  You  can  assemble  ExecSwap. ASM  (Listing  Three, 
page  66)  using  MASM  4.0  or  later,  or  any  compatible  assem¬ 
bler.  Then  compile  the  test  program  to  an  EXE  file  and  run 
it,  and  you’ll  enter  a  DOS  shell.  If  you  have  a  DOS  memory 
mapping  utility,  you’ll  see  that  the  TEST  program  is  using 
less  than  3K  of  memory.  The  swap  file  uses  about  20K, 
most  of  that  for  the  16K  stack,  which  is  Turbo’s  default.  If 
the  swap  goes  to  EMS,  the  EMS  block  will  be  32K  bytes, 
because  EMS  is  allocated  in  16K  chunks.  Type  Exit  to  leave 
the  shell,  and  the  test  program  will  regain  control. 

A  real  program  provides  more  impressive  results.  We 
developed  ExecSwap  for  use  in  our  Turbo  Analyst  product, 
which  offers  an  integrated  environment  where  the  program¬ 
mer  can  edit  source  files,  then  Exec  the  compiler,  debugger, 
or  any  of  many  other  programming  utilities.  Without  benefit 
of  ExecSwap,  the  environment  keeps  about  250K  of  memory 
during  the  Exec.  With  ExecSwap,  the  overhead  is  only  about 
4K.  That  246K  makes  a  difference! 

How  It's  Done 

ExecSwap s  Pascal  source  file,  ExecSwap. PAS,  is  given  in 
Listing  Two,  page  66.  It’s  little  more  than  a  shell  for  the 
assembly  language  routines  in  ExecSwap. ASM,  Listing  Three. 

Looking  at  InitExecSwap  in  Listing  Two,  you’ll  see  that  it 
checks  first  for  EMS  memory  (any  version  of  EMS  will  do). 
If  that  is  available,  it  is  used  in  preference  to  disk  storage.  If 
not,  InitExecSwap  goes  on  to  assure  that  there’s  enough 
space  on  the  specified  drive  to  hold  the  swap  area.  The 
production  version  of  ExecSwap  (trimmed  here  for  the  sake 
of  brevity),  checks  that  the  drive  doesn’t  hold  removable 
media.  InitExecSwap  also  stores  several  items  in  global 
variables,  where  they’re  easily  accessible  by  the  assembly 
language  routines,  and  installs  an  exit  handler  to  clean  up 
after  itself  in  case  the  program  halts  unexpectedly. 

The  tricky  stuff  is  in  ExecSwap. ASM.  The  file  starts  with 
the  standard  boilerplate  needed  for  linking  to  Turbo  Pascal. 
A  number  of  temporary  variables  in  the  code  segment  are 
declared;  these  are  essential  because  the  entire  data  seg¬ 
ment  is  gone  during  critical  portions  of  ExecWithSwap.  One 
of  these  variables  is  a  temporary  stack.  It’s  a  small  one,  only 
128  bytes,  but  it  is  required  because  the  normal  Turbo  Pascal 
stack  is  also  swapped  out.  Macro  definitions  follow;  more 
than  the  usual  number  of  macros  are  used  to  keep  the 
Listing  to  a  reasonable  length. 

(continued  on  page  22) 
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(continued  from  page  18) 

Exec  With  Swap  starts  by  copying  a  number  of  variables 
into  the  code  segment.  Then  it  checks  to  see  whether 
swapping  will  go  to  EMS  or  disk.  If  neither  has  been  acti¬ 
vated,  ExecWithSwap  exits  immediately,  returning  error  code 
1.  Otherwise,  ExecWithSwap  processes  one  of  four  similar 
loops:  one  each  to  swap  to  or  from  disk  or  EMS  storage. 
Let’s  trace  the  “swap  to  EMS”  loop  in  detail,  at  label  WriteE. 
The  sequence  for  swapping  to  disk  is  so  similar  that  I  won’t 
need  to  describe  it  here. 

First  map  EMS  memory,  making  the  first  16K  page  of  the 
EMS  swap  area  accessible  through  the  page  window  at 
FrameSeg:0.  (Note  that  ExecSwap  doesn’t  save  the  EMS 
context;  if  your  application  uses  EMS  for  other  storage,  be 
sure  to  remap  EMS  after  returning  from  ExecWithSwap .)  The 
macro  SetSwapCount  then  computes  how  many  bytes  to 
copy  into  the  first  page,  returning  a  full  16K  bytes  unless  it’s 
also  the  last  page.  The  first  location  to  save  is  at  label 
FirstToSave,  which  immediately  follows  the  ExecWithSwap 
routine.  The  MoveFast  macro  copies  the  first  swap  block 
into  the  EMS  window.  BX  is  then  incremented  to  select  the 
next  logical  EMS  page,  and  the  DS  register  is  adjusted  to 
point  to  the  next  swap  block,  16K  bytes  higher  in  memory. 
The  loop  continues  until  all  the  bytes  have  been  copied. 

Next,  modify  the  DOS  memory  allocation,  so  that  the 
space  just  swapped  out  is  available  to  the  child  process. 
First,  save  the  current  allocated  size  so  you  can  restore  it 
later.  Then  switch  to  the  small  temporary  stack,  which  is 
safely  nestled  in  the  code  segment.  Finally,  call  the  DOS 
SetBlock  function  to  shrink  the  memory  to  just  beyond  the 
end  of  the  ExecWithSwap  routine. 

The  actual  DOS  Exec  call  follows.  The  implementation 
here  is  similar  to  the  one  in  Borland’s  Dos  unit.  It  validates 
and  formats  the  program  path  and  command  line,  parses  file 
control  blocks  (FCBs)  from  the  command  line  in  case  the 
child  expects  them,  and  calls  the  DOS  Exec  function.  The 
error  code  returned  by  Exec  is  stored  until  the  reverse  swap 
is  complete. 


PSP:  program  segment  prefix  I  ExecSwap 

CS_X:  X  code  (partial)  i  overhead 

child  program  program  segment  prefix 

xxxx:  top  of  memory 


Example  2:  Memory  map  while  child  process  is  active 


PSP: 

program  segment  prefix 

CS  X: 

X  code 

CS  ExecSwap: 

ExecSwap  code  ^ 

CS  Crt: 

Crt  code 

CS  Dos: 

Dos  code 

CS_System: 

System  code 

xxxx: 

top  of  memory 

Example  3:  Memory  map  after  using  ExecSwap 


function  InitExecSwap (LastToSave  :  Pointer;  SwapFileName  : 
String)  :  Boolean; 

(-Initialize  for  swapping,  returning  TRUE  if  successful) 

function  ExecWithSwap (Path,  CmdLine  :  String)  :  Word; 
{-DOS  Exec  supporting  swap  to  EMS  or  disk) 

procedure  ShutdownExecSwap; 

(-Deallocate  swap  area) 


Example  4:  ExecSwap  routines 


The  reverse  swap  is  just  that:  It  reallocates  memory  from 
DOS  and  copies  the  parent  program  back  into  place.  There 
is,  however,  one  critical  difference  from  the  first  swap. 
Errors  that  occur  during  the  reverse  swap  are  fatal.  Because 
the  program  to  return  to  no  longer  exists,  the  only  recourse 
is  to  halt.  The  most  likely  reason  for  such  an  error  is  the 
inability  to  reallocate  the  initial  memory  block.  This  occurs 
whenever  the  Exec  call  (or  the  user)  has  installed  a  memory 
resident  program  while  in  the  shell.  Be  sure  to  warn  your 
users  not  to  do  this!  ExecSwap  could  write  an  error  message 
before  halting;  to  save  space  here,  it  just  sets  the  ErrorLevel, 
which  can  be  checked  within  a  batch  file: 

OFFh  can’t  reallocate  memory 
OFEh  disk  error 
OFDh  EMS  error 

ExecWithSwap  is  done  after  it  switches  back  to  the  original 
stack,  restores  the  DS  register,  and  returns  the  status  code. 

The  remainder  of  ExecSwap.ASM  is  a  collection  of  small 
utility  routines,  some  of  which  may  find  for  general  use. 

In  Summary 

ExecSwap  seems  quite  reliable.  It  doesn’t  depend  on  any 
newly  discovered  undocumented  features  of  DOS,  and  has 
been  tested  by  thousands  of  users. 

There  are  a  few  additional  features  it  might  have.  The 
production  version  writes  status  messages  while  swapping, 
so  nervous  users  don’t  think  their  hard  disks  are  being 
formatted.  It  might  also  support  direct  swapping  to  ex¬ 
tended  memory;  this  hasn’t  been  attempted  because  experi¬ 
ence  indicates  that  using  extended  memory  in  a  DOS  appli¬ 
cation  is  a  compatibility  nightmare,  and  RAM  disks  seem 
quite  adequate  for  swapping.  If  the  remainder  of  ExecSwap 
were  converted  to  assembly  language,  Turbo  Pascal’s  link 
order  conventions  (within  a  unit)  could  be  circumvented, 
and  another  500  bytes  or  so  of  Exec  overhead  would  be 
saved.  With  a  few  more  DOS  memory  management  calls,  it 
would  be  possible  for  the  parent  and  child  processes  to 
share  a  common  data  area.  An  extension  of  the  ExecSwap 
concept  allows  TSR  programs  to  leave  just  a  core  of  interrupt 
handlers  in  memory,  and  swap  the  application  code  in 
when  they  pop  up  (SideKick  Plus  apparently  does  this). 

The  ExecSwap  unit  has  become  a  very  useful  item  in  my 
bag  of  tricks.  With  an  ExecSwap- based  DOS  shell  in  the 
programming  editor  I  use,  I  can  achieve  the  kind  of  multi¬ 
tasking  I  need  (“interruption-based”  multitasking).  ExecSwap 
should  make  it  easier  for  you  to  squeeze  more  functionality 
into  that  640K  box  as  well. 
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80386 

Memory  Management 


Paging  is  the  80386’s  answer  to  the  memory 
management  challenges  for  today’s  multitasking 
operating  systems 


emory  management  is  a  chal¬ 
lenge  for  multitasking  oper¬ 
ating  systems.  To  combat 
this  difficulty,  the  Intel  80386 
architecture  has  a  method 


for  managing  memory  called  “paging,” 
which  is  in  addition  to  the  segmenta¬ 
tion  features  of  the  80286.  Paging  can 
increase  efficiency  of  virtual  memory 
multitasking  operating  systems  that  run 
8086,  80286,  and  80386  microproces¬ 
sor  software.  This  article  explains  how 
paging  increases  the  performance  for 
multitasking  operating  systems  and  why 
paging  is  a  requirement  for  multitasking 
8086  and  32-bit  80386  microprocessor 
applications.  In  order  to  make  use  of 
the  information  in  this  article,  you 
should  have  basic  knowledge  of  pro¬ 
tected  mode  andl  segmentation  on  the 
80286  or  80386  microprocessor. 

Both  the  8086  and  the  80286  address 


memory  with  a  linear  address.  For  sys¬ 
tems  that  use  these  processors,  or  the 
386  CPU  without  paging,  the  linear  ad¬ 
dress  is  equivalent  to  the  physical  ad¬ 
dress.  Address  translation  on  the  386 


CPU  is  shown  in  Figure  1.  Notice  that 
the  paging  unit  comes  after  the  linear 
address  calculation.  The  paging  unit 
translates  the  logical  address  seen  by 
the  programs  into  the  physical  address 
that  goes  out  on  the  bus,  which  allows 
paging  to  be  performed  by  the  operat¬ 
ing  system  but  does  not  impact  appli¬ 
cations  in  any  manner. 


Neal  is  an  applications  engineer  for 
Intel  Corp.  and  can  be  reached  at 2625 
Walsh  Ave.,  SC4-40,  Santa  Clara,  CA 
95051. 


Neal  Margulis 

The  Logical  Basis  Segmentation-based  memory  man- 

A  segment  is  used  to  define  the  task’s  agement  has  additional  shortcomings, 
logical  address  space,  which  consists  When  variable  sized  segments  are  used 
of  one  or  more  segments.  The  80286  for  physical  memory  allocation,  for  ex- 
allows  segments  of  up  to  64K,  and  the  ample,  memory  fragmentation  often  oc- 
386  microprocessors  allow  segments  curs.  Fragmentation  occurs  when  the 
up  to  4  gigabytes  long.  As  any  experi-  free  memory  in  a  system  consists  of 
enced  programmer  knows,  segments  discontinuous  small  sections.  Then 
are  visible  to  the  application  program-  when  the  operating  system  needs  to 
mer,  although  less  so  on  the  386  due  load  a  large  segment,  it  must  perform 
to  its  larger  size.  a  costly  rearranging  of  memory.  To 

Microsoft’s  OS/2  currently  uses  seg-  overcome  fragmentation,  some  segmen- 
ments  as  the  basis  for  its  virtual  mem-  tation-based  schemes  allocate  the  maxi- 
ory  management.  The  80286’s  maxi-  mum  segment  size  when  any  size  seg- 
mum  segment  size  of  64K  makes  seg-  ment  is  loaded.  Although  this  over- 
ment-based  physical  memory  alloca-  comes  the  fragmentation  problem,  it 
tion  possible.  With  the  386  microproc-  wastes  memory.  Clearly  a  new  method 
essor,  in  which  segments  can  be  up  to  that  overcomes  these  inefficiencies  and 
4  gigabytes,  allocating  memory  on  such  works  with  32-bit  code  is  needed  The 
a  large  basis  is  not  practical.  (continued  on  page  28) 


Figure  1:  Address  translation  on  the  80386 
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(continued  from  page  24) 
new  method  for  virtual  memory  man¬ 
agement  is  paging. 


Paging 

While  paging  is  enabled,  the  processor 
translates  a  linear  address  to  a  physical 


Figure  3-'  The  80386 processor  performs  a  page  table  lookup from  information 
stored  in  memory  when  it  cannot  find  the  mapping  information  fora  page 
in  the  TLB. 


31 _ 

Page 


12  11  0 


Table  Address  31. ..12 

Available 

0  0 

D 

A 

0  0 

U 

R 

P 

S 

W 

P 

Present 

R/W 

Read/Write 

U/S 

User/  Supervisor 

A 

Accessed 

D 

Dirty 

AVAIL. 

Available  for  Systems  Programmer  Use 

address  with  the  aid  of  page  tables. 
Like  mainframe  computers,  the  page 
tables  are  arranged  in  a  two-level  hier¬ 
archy,  as  shown  in  Figure  2.  The  page 
table  directory  base,  which  is  the  con¬ 
trol  register  CR3,  points  to  the  page 
table  directory.  The  directory  is  one 
page  long  and  contains  entries  for  1,024 
page  tables.  Page  tables  are  also  one 
page  long,  and  the  entries  in  a  page 
table  describe  1,024  pages;  each  page 
is  4K  in  size.  As  an  option,  tasks  can 
have  their  own  page  table  directory, 
for  there  is  a  page  table  directory  base 
associated  with  each  task. 

The  processor  uses  the  upper  10  bits 
of  the  linear  address  as  an  index  into 
the  directory.  Each  directory  entry  holds 
20  bits  of  addressing  information,  which 
contain  the  address  of  a  page  table. 
The  processor  uses  these  20  bits  and 
the  middle  10  bits  of  the  linear  address 
to  form  the  page  table  address.  The 
address  contents  of  the  page  table  en¬ 
try  and  the  lower  12  bits  of  the  linear 
address  form  the  32-bit  physical 
address. 

The  Translation  Lookaside  Buffer  (TLB) 

Paging  information  is  stored  in  the  on- 
chip  TLB  and  in  memory.  If  the  proces¬ 
sor  had  to  access  these  page  tables  in 
memory  each  time  a  reference  was 
made,  performance  would  suffer.  To 
save  the  overhead  of  the  page  table 
lookups,  the  processor  automatically 
caches  mapping  information  for  32  re¬ 
cently  used  pages  in  an  on-chip  trans¬ 
lation  lookaside  buffer.  The  TLB’s  32 
entries  cover  4K,  each  providing  a  total 
cover  of  128K  of  memory  addresses. 
The  TLB  is  flushed  by  changing  the 
value  of  CR3,  which  is  commonly  ac¬ 
complished  by  a  privileged  MOV  in¬ 
struction  or  a  task  switch. 

As  shown  in  Figure  3,  only  when  the 
processor  does  not  find  the  mapping 
information  for  a  page  in  the  TLB  does 
it  perform  a  page  table  lookup  from 
information  stored  in  memory.  To  im¬ 
prove  hit  rates,  the  TLB  is  four-way  set 
associative,  meaning  each  translation 
can  be  stored  in  one  of  four  locations 
in  the  TLB.  The  result  is  that  for  typical 
systems,  97  -  99  percent  of  the  address 
references  are  TLB  hits,  requiring  no 
memory  references  to  translate.  When 
a  TLB  miss  occurs,  the  processor  re¬ 
places  an  older  TLB  entry  with  the  new 
entry  that  is  likely  to  be  used  again. 
This  replacement,  called  TLB  miss  proc¬ 
essing,  is  performed  entirely  in  hard¬ 
ware. 


Note:  0  indicates  Intel  Reserved.  DO  NOT  Define. 


Figure  4:  The  lower  12  bits  of  the  page  directory  entries  and  page  table  entries 
contain  several  control  bits. 


Using  Paging  for 

Virtual  Memory  Management 

Virtual  memory  allows  large  or  multi¬ 
ple  programs  to  be  executed  as  if  the 
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entire  program  were  in  memory,  even  system  that  must  read  the  needed  page 
though  portions  are  still  on  disk.  In  the  into  memory  and  return  execution  to 
case  of  a  large  program  that  has  20  the  program.  The  handler  reads  the 
Mbytes  of  data,  for  example,  and  a  contents  of  CR2  to  decide  which  page 
computer  that  has  only  2  Mbytes  of  is  required.  If  there  is  no  more  room 
memory,  the  operating  system  can  load  in  physical  memory  to  load  in  another 
and  run  the  program.  An  operating  sys-  page,  the  handler  must  decide  which 
tern  that  uses  demand  paging  can  mul-  presently  loaded  page  should  be  dis- 
titask  more  applications  in  less  physi-  carded.  Although  the  operating  system 
cal  memory  than  an  operating  system  cannot  be  sure  which  pages  will  not 
that  uses  segmentation  for  memory  al-  be  needed  in  the  future,  it  can  make  a 
location.  The  information  for  efficiently  very  good  guess  based  on  the  least 
accomplishing  memory  management  recently  used  pages.  The  A  (accessed) 
lies  within  the  page  directory  entries  bit  and  the  bits  reserved  for  operating- 
and  page  table  entries.  In  Figure  4,  in  system  use  determine  which  pages  have 
the  lower  12  bits  of  each  of  these  en-  not  been  used  recently.  The  proces- 
tries  there  are  several  control  bits  used  sor’s  hardware  automatically  sets  the 
by  the  operating  system  for  keeping  A  bit  to  1  whenever  the  processor  ac- 
track  of  which  pages  are  in  memory,  cesses  the  page;  the  bit  can  only  be 
which  pages  are  on  disk,  information  cleared  by  software.  By  periodically 
for  deciding  which  page  should  be  clearing  the  A  bits,  the  operating  sys- 
swapped  out  in  favor  of  a  new  page,  tern  can  keep  track  of  pages  not  re- 
and  if  the  swapped  page  needs  to  be  cently  used.  The  A  bit,  combined  with 
written  back  to  disk  or  merely  discarded.  managing  the  operating  system  reserved 

If  set  to  1,  the  P  (present)  bit  indi-  bits,  allows  an  accurate  “least  recently 
cates  that  the  entry  is  present  in  mem-  used”  algorithm  to  be  implemented  for 
ory.  If  the  P  bit  is  0,  any  attempt  to  page  management, 
access  this  page  will  cause  a  page  fault  Once  the  operating  system  deter- 
(exception  14)  prior  to  the  memory  mines  the  page  that  will  be  discarded 
access.  When  a  page  fault  occurs,  the  from  RAM,  it  must  then  decide  if  the 
processor  passes  control  to  the  inter-  page  needs  to  be  written  back  to  disk, 

rupt  14  handler,  part  of  the  operating 

Enabling  and  Disabling  Paging  on  the  80386 

When  the  80386  microprocessor  is  Once  paging  is  turned  on,  all  linear 
brought  out  of  reset,  it  first  executes  in  addresses  are  paged  to  the  correct  physi- 
real  mode.  To  use  paging,  the  proces-  cal  address.  The  address  translation  in- 
sor  must  be  executing  in  protected  formation  is  then  automatically  cached 
mode.  The  steps  for  entering  and  exit-  into  the  TLB  each  time  the  hardware 
ing  protected  mode  are  described  in  performs  a  page  translation  from  the 
the  DDJ  article  “80386  Protected  Mode  tables  in  memory.  Should  you  change 
Initialization”  by  Neal  Margulis  (Octo-  any  of  the  page  table  information  in 
ber  1988).  To  enable  paging,  follow  memory,  or  decide  to  use  a  different 
these  steps:  set  of  page  tables,  you  must  perform  a 

MOV  CR3,xxxxxxxx  to  invalidate  the 

1.  Set  up  the  page  directory  and  the  current  TLB  entries  so  that  the  new 

page  tables  in  memory  with  the  de-  paging  information  will  be  used, 
sired  values.  When  disabling  paging  you  must  do 

2.  Load  CR3,  the  page  directory  base,  the  following: 
with  the  base  address  of  the  page  di¬ 
rectory.  Loading  CR3  also  invalidates  1.  Locate  the  instruction  that  performs 
any  information  stored  in  the  TLB.  the  transition  on  a  page  whose  linear 

3.  Execute  a  MOVCRO,  EAX instruction  address  is  the  same  as  the  physical 
where  bit  31  is  set  to  1,  and  the  other  address.  This  prevents  an  unpredict- 
bits  are  unchanged.  This  can  be  ac-  able  instruction  prefetch  from  occur- 
complished  with  the  sequence  MOV  ring  between  changing  the  paging  status 
EAX,  CRO;  OR  EAX,  80000000H.  It  is  and  the  next  instruction. 

possible  to  enable  paging  at  the  same  2.  A  MOV  CRO,  EAX  where  bit  31  is 
time  protected  mode  is  entered.  The  forced  to  0  is  executed.  This  can  be 
instruction  sequence  in  which  the  tran-  accomplished  with  the  sequence  MOV 
sition  to  paging  will  occur  must  have  EAX,  CRO:  AND  EAX,  7FFFFFFFH. 
its  linear  address  mapped  to  its  physi-  3.  MOV  CR3,  EAX  to  invalidate  the  TLB 
cal  address.  entries. 

4.  The  instruction  prefetch  queue  should 

be  flushed  by  performing  a  JMP  $2  After  paging  is  disabled,  the  linear 
instruction.  address  and  physical  address  are  the 

same.  — N.  M. 
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386  MEMORY  MANAGEMENT 


The  D  (dirty)  bit  indicates  if  the  page 
has  been  written  to.  If  the  D  bit  is  set, 
then  the  operating  system  knows  that 
it  must  be  written  back  to  disk.  If  the 
D  bit  is  not  set,  then  the  copy  of  the 
page  that  is  currently  on  the  disk  is  the 
most  recent  version.  The  U/S  (user/ 
supervisor)  and  R/W  (read/write)  bits 
are  described  in  the  page-based  protec¬ 
tion  section  later  on  in  this  article. 

The  method  of  swapping  pages  in 
and  out  of  memory  when  needed  is 
called  demand  paging.  Unix  System  V 
for  the  386  microprocessor  has  always 
offered  this  feature,  and  in  September 
1988,  PharLap  Software  announced  that 
386 1  VMM,  which  runs  on  top  of 
386 1  DOS-Extender,  will  also  support 
demand  paging.  With  PharLap’s  devel¬ 
opment  tools  and  a  compiler,  such  as 
80386  High  C  Compiler  from  Meta¬ 
ware,  users  can  develop  large  appli¬ 
cations  that  can  take  advantage  of  de¬ 
mand  paging. 

In  addition  to  virtual  memory  man¬ 
agement,  paging  has  another  useful  fea¬ 
ture:  It  can  be  used  to  do  a  simple 
remapping  of  memory,  a  feature  used 
in  some  DOS  control  programs.  Pro¬ 
grams  such  as  Compaq’s  CEMM,  Quar¬ 
terdeck’s  QEMM-386,  and  Qualitas’s  386- 
to-the-MAX  use  remapping  ability  to 
implement  various  features.  Applica¬ 
tion  programs  addresses  that  use  the 
LIM  (Lotus,  Intel,  Microsoft)  specifica¬ 
tion  for  accessing  expanded  memory, 
for  instance,  are  remapped  in  software 
to  use  fast  extended  memory,  thus  elimi¬ 
nating  the  need  for  special  memory 
board’s  external  mapping  hardware. 
This  type  of  program  also  allows  ex¬ 
tended  memory  to  be  mapped  into  the 
DOS-accessible  512K-640K  range  on 
386  microprocessor-based  PCs  that  have 
512K  of  memory  on  the  motherboard. 
In  addition,  it  allows  relocation  of  ter- 
minate-and-stay-resident  utilities  out¬ 
side  of  DOS’s  640K. 

Protection 

The  80386  provides  many  protection 
mechanisms  that  operating  systems  can 
selectively  employ  to  fit  their  needs. 
Segmentation  provides  the  basis  for 
much  of  the  task-based  protection  and 
multilevel  protection  schemes.  Level  3 
of  segmentation-based  protection  cor¬ 
responds  to  user  level  for  paging,  and 
levels  0,  1,  and  2  correspond  to  super¬ 
visor  level. 

Paging  has  a  separate  protection 
mechanism  that  is  sufficient  for  most 
operating  systems.  Paging  protects  su¬ 
pervisor  memory  and  allows  for  write 
protecting  of  user  pages.  The  U/S  and 
R/W  bits  are  found  in  each  page  direc¬ 
tory  entry  and  page  table  entry.  Their 
presence  in  both  levels  allows  more 


selective  control  over  the  access  to  page 
groups  and  individual  pages.  The  op¬ 
erating  system  can  allow  user  programs 
to  have  read  only,  read  and  write,  or 
no  access  to  a  given  page  or  page 
group.  If  a  memory  access  violates  the 
page  protection  attributes,  such  as  user 
level  code  writing  a  read  only  page, 
an  exception  14  will  be  generated. 

Exception  14  is  used  for  reporting 
page  access  violations  and  page  faults. 

An  operating  system 
that  uses  demand 
paging  can  multitask 
more  applications  in 
less  physical  memory 
than  an  operating 
system  that  uses 
segmentation  for 
memory  allocation 


To  distinguish  the  cause  of  an  excep¬ 
tion  14,  the  operating  system  examines 
a  16-bit  error  code  that  is  pushed  as 
part  of  the  page  fault  handler.  From  the 
error  code  and  the  faulting  linear  ad¬ 
dress,  stored  in  CR2,  the  operating  sys¬ 
tem  can  correctly  handle  the  fault  and 
resume  execution. 

Virtual  8086  Environment 

For  running  existing  code,  one  of  the 
biggest  advantages  of  the  386  micro¬ 
processor  is  in  the  support  for  multi¬ 
tasking  DOS  applications.  Microsoft’s 
current  80286-based  OS/2  does  not  al¬ 
low  multitasking  of  DOS  applications, 
but  the  386  can  multitask  DOS  applica¬ 
tions  with  virtual  86  mode.  IGC’s  VM/ 
386,  Microsoft’s  Windows/386,  Quar¬ 
terdeck’s  DESQview,  and  several  soft¬ 
ware  vendors  offer  multitasking  of  DOS 
applications  as  a  major  feature  of  their 
software.  Other  products,  like  MERGE 
and  VPIX,  use  virtual  86  mode  for  run¬ 
ning  DOS  applications  under  Unix. 

The  386  can  execute  8086  applica¬ 
tions  in  both  real  mode  and  virtual  86 
mode.  Virtual  86  mode  allows  the  exe¬ 
cution  of  8086  applications  while  still 
allowing  use  of  paging.  The  main  dif¬ 
ference  between  real  and  protected 
mode,  however,  is  how  the  segment 


selectors  are  interpreted.  When  the  proc¬ 
essor  is  executing  in  virtual  mode,  the 
segment  registers  are  used  as  in  real 
mode.  The  contents  of  the  segment 
register  are  shifted  left  4  bits  and  added 
to  the  offset  to  form  the  segment  linear 
address.  When  running  in  protected 
mode,  the  processor  determines  which 
applications  are  protected  mode  and 
which  are  8086  applications.  The  8086 
applications  require  their  segments  to 
be  interpreted  as  in  real  mode. 

Paging  is  crucial  to  multitasking  8086 
applications.  With  paging,  the  applica¬ 
tions  can  be  executed  anywhere  in  mem¬ 
ory,  not  just  the  lower  1  Mbyte.  With¬ 
out  this  ability,  only  640K  of  applica¬ 
tions  would  be  multitaskable.  The  pag¬ 
ing  hardware  allows  the  20-bit  linear 
address  produced  by  a  virtual  mode 
program  to  be  divided  into  up  to  256 
pages.  Each  one  of  the  pages  can  be 
relocated  anywhere  in  physical  mem¬ 
ory.  The  operating  system  is  able  to 
treat  memory  for  virtual  86  appli¬ 
cations  as  it  does  memory  for  32-bit 
applications. 

Because  CR3,  the  page  directory  base 
register,  is  different  for  each  task,  each 
task  can  use  a  different  mapping  scheme 
to  map  pages  to  different  physical  loca¬ 
tions.  Of  course  entries  can  appear  in 
both  tables  to  allow  sharing  of  operat¬ 
ing  system  code  between  applications. 

Summary 

Paging  is  the  80386’s  answer  to  the 
challenges  of  memory  management  for 
today’s  multitasking  operating  systems. 
Whether  a  task’s  logical  address  space 
consists  of  one  segment  or  many,  an 
operating  system  can  subdivide  the  lin¬ 
ear  address  space  into  pages.  To  an 
operating  system,  pages  are  more  con¬ 
venient  units  than  are  segments  for  al¬ 
location  because  pages  are  all  the  same 
size,  which  prevents  common  problems 
that  occur  while  using  segments  for 
memory  allocation.  Additionally,  page- 
based  swapping  is  better  tuned  to  disk 
drives  than  segment-based  swapping. 

Paging  is  the  only  mechanism  for 
virtual  memory  management  of  32-bit 
applications  (in  which  segments  can 
be  up  to  4  gigabytes  in  length)  and  for 
virtual  8086  applications,  which  all  ex¬ 
ist  in  the  lowest  Mbyte  of  the  linear 
address  space.  The  fast  on-chip  TLB 
and  hardware  TLB  miss  processing  al¬ 
low  the  386  microprocessor  to  perform 
these  advanced  memory  management 
techniques  without  reducing  the  applica¬ 
tion’s  processing  power. 
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Demand  Paged 
Virtual  Memory 

Putting  a  mainframe  environment 
on  a  micro 


Kent  Dahlgren 


Once  an  exotic  large-system 
technology,  Demand  Paged 
Virtual  Memory  has  come 
to  the  world  of  small  com¬ 
puters.  The  new  generation 
of  32-bit  microprocessors,  with  blazing 
instruction  throughput  and  advanced 
on-chip  memory  management,  brings 
mainframe  performance  to  the  desk¬ 
top.  With  it  comes  the  ability  to  run 
several  programs  at  the  same  time,  each 
requiring  more  memory  than  the  com¬ 
puter  physically  possesses.  How?  That’s 
what  this  article  is  about. 

So  what  is  Demand  Paged  Virtual 
Memory,  or  DPVM?  In  a  nutshell,  it’s 
the  partitioning  of  a  program’s  linear- 
address  space  into  smaller  units  called 
“pages”.  Even  very  large  programs  con¬ 
fine  their  activities  at  any  given  instant 
to  small  regions  of  memory:  a  loop  in 
executable  code,  a  table  in  data  space, 
some  variables  here  and  there.  Thus, 
there  is  never  a  need  for  all  the  code 
and  data  to  be  in  memory  at  once. 

This  observation,  often  referred  to 
as  locality  of  reference,  is  the  basis  for 
DPVM.  As  programs  run,  the  pages 
they  need  are  moved  into  memory, 
replacing  pages  no  longer  required.  If 
a  page  containing  changes  is  to  be 
replaced,  it’s  saved  on  disk  to  prevent 
data  loss  and  for  access  later.  Other 
jobs  can  run  while  this  process,  called 


Kent  Dahlgren  is  the  strategic  planner 
for  graphics  products  at  Paradise  Sys¬ 
tems,  a  manufacturer  of  graphics  de¬ 
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Middlefield  Rd.,  Mountain  View,  CA 
94043. 


swapping,  is  going  on.  In  this  way, 
DPVM  supports  concurrent  execution 
of  several  programs,  any  one  (or  all) 
of  which  “thinks”  its  linear  memory 
space  is  unlimited. 

Naturally  all  this  doesn’t  occur  by 
magic.  It  takes  a  combination  of  hard¬ 
ware  and  software  called  a  Virtual  Mem¬ 
ory  Manager,  or  VMM.  The  CPU  must 
provide  memory  management  and  the 
high-instruction  rate  required  to  run 
the  sophisticated  operating  system  that 
makes  it  happen.  The  system  must  also 
have  a  high-performance  disk  to  han¬ 
dle  swapping  efficiently.  And  of  course 
there  have  to  be  enough  cycles  left 
after  the  overhead  to  do  productive 
work. 

The  key  element  in  DPVM,  then,  is 
the  CPU.  Heretofore,  microprocessors 
simply  didn’t  have  enough  horsepower 
or  features.  Now  they  do. 

So  let’s  look  at  the  workings  and 
issues  of  DPVM,  and  how  three  current- 
generation  microprocessors  handle 
them. 

How  Does  It  Work? 

Paged  memory  management  uses  a  dy¬ 
namic,  relocatable  partitioning  scheme 
to  manage  main  memory.  The  parti¬ 
tions,  referred  to  as  pages,  are  of  uni¬ 
form  size,  typically  4K.  Unlike  the  seg¬ 
mented  memory  familiar  to  users  of 
Intel  processors,  the  existence  and  ma¬ 
nipulation  of  pages  are  transparent  to 
processes  running  on  the  system.  This 
is  a  result  of  taking  the  addresses  gen¬ 
erated  by  the  CPU  (referred  to  as  logi¬ 
cal  or  virtual  addresses),  and  translat¬ 
ing  them  into  a  real  memory  address. 


Consequently  a  process  always  sees 
an  uninterrupted  linear  address  space, 
even  though  the  pages  allocated  to  it 
are  probably  not  contiguous  in  main 
memory. 

The  logical  to  physical  translation  is 
accomplished  by  breaking  addresses 
into  two  components.  The  high-order 
bits  represent  the  page  number,  with 
the  low-order  bits  giving  the  offset 
within  the  page.  Logical  addresses  are 
mapped  onto  the  physical  addresses 
of  page  frames  located  in  main  mem¬ 
ory  using  a  data  structure  known  as  the 
page  map  table,  which  contains  the 
current  logical  to  physical  mapping. 
The  page  offset  bits  are  unmapped  and 
therefore  simply  passed  through  as  the 
physical  page  offset.  The  page  map 
table  also  stores  bit  fields  describing 
protection  and  cachability.  Having  such 
information  for  each  page  is  another 
benefit  of  paged  memory  management. 
Figure  1  illustrates  the  mapping  proce¬ 
dure. 

The  power  of  this  mapping  method¬ 
ology  makes  the  most  compelling  bene¬ 
fit  of  paged  memory  management  pos¬ 
sible.  Because  a  complete  memory  im¬ 
age  of  the  process  is  kept  in  secondary 
storage  and  only  the  portion  that  is 
currently  being  executed  in  main  mem¬ 
ory,  the  process  can  run  in  an  address 
space  much  smaller  than  its  total  im¬ 
age.  As  the  program  refers  to  new  sec¬ 
tions  (for  example  pages)  of  the  image, 
they’re  brought  into  main  storage. 
Hence  the  term  “demand  paged  virtual 
memory”.  Newly  arriving  pages  replace 
pages  that  are  not  currently  being  ref¬ 
erenced.  To  support  this  scheme  an 
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additional  data  structure  is  required  in 
order  to  find  logical  pages  in  secon¬ 
dary  storage.  This  structure,  the  file 
map  table,  parallels  the  page  map 
table. 

Often,  of  course,  a  process  refers  to 
a  page  that  is  not  physically  present  in 
main  memory.  This  situation  is  called 
a  page  fault,  and  is  treated  as  an  excep¬ 
tion.  It  requires  that  the  CPU  abort  the 
memory  cycle  (data  or  instruction  fetch) 
and  save  its  state.  The  system  must 
then  find  the  required  page  and  bring 
it  into  memory,  after  which  the  CPU 
can  restart  the  aborted  access. 

Support  for  DPVM  address  transla¬ 
tion  and  access  validation  are  the  core 
requirements  for  the  Memory  Manage¬ 
ment  Unit  (MMU).  The  scheme  depends 
on  its  ability  to  translate  each  memory 
access  transparently  to  the  executing 
process.  This  is  not  a  trivial  task;  map¬ 
ping  a  logical  address  space  of  4  giga¬ 
bytes  requires  over  a  million  4K  pages. 
Even  when  a  process  requires  only  4 
Mbytes,  the  MMU  must  translate  a  thou¬ 
sand  pages  to  support  it.  This  leads  to 
extremely  large  map  tables:  so  large 
that  many  systems  swap  portions  of 
the  map  tables  themselves  in  and  out 
of  main  memory. 

As  a  result  of  this  swapping  require¬ 
ment,  most  systems  don’t  use  simple 
linear  translation  tables  as  shown  in 
Figure  2.  Instead  the  tables  are  arranged 
in  a  tree  structure,  in  which  the  leaves 
contain  page  tables  — arrays  of  logical 
to  physical  translation  data — and  in¬ 
termediate  nodes  are  hierarchical  ta¬ 
bles  of  pointers  — or  page  directories  — 
to  the  next  lower  level.  The  number  of 


levels  is  a  function  of  system  require¬ 
ments.  More  levels  allow  the  memory 
manager  to  add  new  address  translation 
information  in  smaller  increments,  but 
costs  more  memory  cycles  during  a 
page  map  table  search. 

Even  very  large  program 
confine  their  activities 
at  any  given  instant  to 
small  regions  of  memory 


The  arrangement  used  in  the  80386 
represents  a  compromise  between  pay¬ 
off  and  penalty.  The  page  size  is  fixed 
at  4K  with  the  remaining  20  bits  of  the 
logical  page  address  split  into  two  10- 
bit  indexes.  This  results  in  a  1,024- 
entry  page  directory  consisting  of  32- 
bit  pointers  to  page  tables,  each  of 
which  contains  1,024  32-bit  address  trans¬ 
lation  entries.  The  beauty  of  this  scheme 
is  that  both  the  page  tables  and  page 
directory  are  4K  in  size,  simplifying  the 
paging  of  these  entries  themselves. 

But  What  About  Performance? 

The  elegance  of  DPVM  extracts  a  price: 
Managing  the  memory  can  consume  a 
significant  portion  of  CPU  time.  This  is 
reflected  in  the  fact  that  the  bulk  of  the 
papers  written  about  this  topic  deal 
with  various  performance  optimization 
issues.  The  key  areas  are  address  trans¬ 


lation  and  page  replacement. 

Two  strategies  can  enhance  address 
translation  performance.  The  first  is  to 
include  registers  in  the  MMU  for  cach¬ 
ing  recent  address  translations.  These 
caches  are  referred  to  as  translation 
lookaside  buffers  (TLBs)  or  address  trans¬ 
lation  caches  (ATCs).  A  well-designed 
TLB  can  eliminate  table  searches  for 
well  over  90  percent  of  memory  refer¬ 
ences,  and  for  this  reason  all  the  avail¬ 
able  MMUs  include  them.  The  architec¬ 
ture  of  TLBs  falls  into  two  broad  cate¬ 
gories,  fully  associative  and  set  asso¬ 
ciative. 

Fully  associative  TLBs  offer  the  most 
flexibility.  Here,  any  of  the  entries  can 
hold  a  given  address  translation,  since 
logical  addresses  are  compared  with 
all  of  the  logical  address  tags  in  the 
TLB.  The  drawback  is  that  this  requires 
address  comparators  for  each  entry  and 
uses  up  area  on  the  chip.  In  addition, 
the  hardware  required  for  keeping  track 
of  replacement  information  is  signifi¬ 
cantly  complex. 

The  goal  of  a  set  associative  TLB 
design  is  to  simplify  the  hardware.  This 
is  done  by  using  a  portion  of  the  logi¬ 
cal  page  address  to  select  what  is  re¬ 
ferred  to  as  a  line  in  the  cache.  Each 
line  consists  of  one  TLB  entry  for  each 
set.  The  problem  with  this  approach  is 
that  it  effectively  reduces  the  number 
of  available  TLB  entries  for  mapping 
specific  sets  of  address  ranges. 

Another  strategy  to  improve  transla¬ 
tion  performance  is  providing  hardware 
or  microcode  in  the  CPU  to  search  the 
page  map  table  for  a  new  translation 
when  it  cannot  be  found  in  the  cache. 
This  situation  is  called  a  TLB  miss.  This 
hardware  also  takes  care  of  determin¬ 
ing  which  entry  to  replace  when  a  new 
entry  is  to  be  loaded.  Not  only  does  it 
improve  performance,  but  it  also  means 
the  programmer  doesn’t  have  to  write 
code  to  handle  this  critical  function. 

Improvements  in  page  handling  per¬ 
formance  are  similar  to  those  for  ad¬ 
dress  translation.  The  key  issue  here 
involves  swapping:  deciding  which 
page  to  remove  from  main  memory 
when  a  new  one  must  be  loaded.  The 
goal  is  to  remove  pages  that  will  not 
be  needed  again  soon.  Because  it  is 
not  possible  to  predict  future  program 
behavior,  past  referencing  patterns  are 
used  to  guess  which  page  is  least  likely 
to  be  needed.  The  two  most  popular 
techniques  are  FIFO  and  LRU.  These 
algorithms  have  been  the  focus  of  much 
research  over  the  past  20  years.  The 
most  preferable  (in  terms  of  perform¬ 
ance)  is  LRU,  which  is  achieved  at  the 
cost  of  algorithmic  complexity  (see  side- 
bar).  Hardware  support  for  paging 
comes  in  the  form  of  intelligent  I/O 
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Figure  1:  Mapping  procedure 
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Figure  2:  Linear  translation  tables 


CPU 

TLB  Size /Type 

TLB  Reload 

Page  Sizes 
Supported 

Translation  Tree 
Levels  Supported 

Real-Time  Support 

68030 

22  Entry,  Fully 
Associative 

Microcode 

256,512,  IK,  2K, 
4K,  8K,  16K,  32K 

1  to  5 

Transparent  Mapping 

80386 

32  Entiy,  4  Way 
Set  Associative 

Microcode 

4K 

1 

None 

29000 

64  Entry,  2  Way 
Set  Associative 

Software 

IK,  2K,  4K,  8K 

any  number 

None 

Table  1 :  MMU  architectures  compared 


controllers  that  relieve  the  CPU  of  some 
of  the  work  involved  in  swapping  pages 
in  and  out  of  memory.  No  doubt  this 
approach,  common  in  mainframes,  will 
eventually  migrate  to  small  systems  as 
multitasking  operating  systems  become 
more  prevalent. 

Thrashing  is  a  term  describing  situ¬ 
ations  in  which  the  CPU  spends  more 
time  managing  memory  (paging,  search¬ 
ing  tables,  and  so  on)  than  executing 
process  code.  In  some  cases  the  situ¬ 
ation  can  get  so  bad  that  only  one 
percent  of  instructions  executed  are 
those  of  processes.  The  simplest  way 
to  reduce  the  problem  is  to  add  more 
real  memory.  Unfortunately,  that  costs 
real  money.  The  alternative  is  to  add 
sophisticated  performance  analysis  and 
tuning  software  to  the  VMM.  For  exam¬ 
ple,  the  VMM  in  a  multitasking  envi¬ 
ronment  can  continually  monitor  the 
page  faulting  behavior  of  executing 
tasks  and  dynamically  adjust  their  page 
allotments  to  optimize  performance. 
Tasks  creating  large  numbers  of  page 
faults  have  their  allocation  of  available 
pages  increased. 

And  Then  There's  Real  Time 

The  key  problem  with  DPVM  in  real¬ 
time  systems  is  the  performance  degra¬ 
dation  and  indeterminacy  resulting  from 


Implementing  the  LRU  Algorithm 
Tom  Gettys 


The  design  of  a  Demand  Paged  Virtual 
Memory  system  revolves  around  two 
key  decisions:  the  buffer  write  policy 
and  the  page  replacement  algorithm. 

The  two  main  write  policies  are  write- 
through  and  copy-back.  Both  involve 
keeping  two  copies  of  each  page  im¬ 
age,  one  in  main  memory,  the  other  in 
secondary  storage  such  as  a  disk.  The 
write-through  policy  updates  the  copy 
in  secondary  storage  every  time  its  im¬ 
age  in  main  memory  is  altered.  This  is 
the  safest,  since  both  always  contain 
the  same  data.  Its  effectiveness  is  sig¬ 
nificantly  degraded,  however,  if  the  num¬ 
ber  of  read  operations  does  not  greatly 
exceed  the  number  of  writes. 

The  copy-back  strategy  updates  sec¬ 
ondary  storage  only  when  a  buffer  in 
main  memory  is  to  be  overwritten.  The 
algorithm  knows  whether  to  do  this  by 
maintaining  a  TRUE/FALSE  value  known 
as  a  “dirty  bit”  for  each  page  buffer. 


Tom  Gettys  is  a  principle  software  engi¬ 
neer for  GDP  Technologies  and  can 
be  reached  at  700  Snowberry ,  Lafay¬ 
ette,  CO  80026. 


The  dirty  bit  is  set  to  FALSE  (0)  when 
the  page  is  first  loaded  into  memory.  The 
bit  is  then  changed  to  TRUE  whenever 
a  write  occurs  in  the  page’s  address 
space.  If  this  bit  is  still  FALSE  when  it’s 
time  to  overwrite  the  page  buffer,  the 
image  is  unchanged  so  there’s  no  need 
to  copy  it  back  to  secondary  storage. 

A  page  fault  occurs  when  a  process 
refers  to  a  page  that  is  not  currently  in 
memory.  If  there  are  no  free  page  buff¬ 
ers  in  main  memory,  a  page  replace¬ 
ment  algorithm  must  determine  which 
buffer  to  overwrite.  Clearly,  it’s  most 
efficient  to  use  a  method  requiring  the 
fewest  accesses  to  secondary  storage. 
The  optimum  strategy  is  to  overlay  the 
page  that  will  not  be  used  again  for  the 
longest  time.  Because  this  requires  pre¬ 
dicting  the  future,  though,  it’s  hard  to 
implement,  so  we  must  find  another 
algorithm  that  yields  something  close 
to  the  optimum.  The  most  popular  of 
such  methods  is  called  “least  recently 
used,”  or  LRU. 

LRU  replaces  the  page  that  has  not 
been  accessed  for  the  longest  period 
of  time.  It  performs  remarkably  well 


due  to  the  principle  of  locality:  Proc¬ 
esses  tend  to  access  storage  in  nonuni¬ 
form,  highly-localized  patterns  clustered 
together  both  in  time  and  space.  Con¬ 
sequently,  a  page  that  has  not  been 
referenced  recently  is  unlikely  to  be 
referenced  again  in  the  near  future. 

With  the  proper  choice  of  a  data 
structure,  the  LRU  algorithm  is  straight¬ 
forward  and  efficient.  It  requires  that 
the  buffers  be  ordered  according  to 
their  most  recent  access  in  time.  This 
leads  us  directly  to  the  ubiquitous  FIFO 
(first-in,  first-out)  queue.  When  a  page 
is  referenced  it  is  placed  at  the  back  of 
the  queue.  The  page  at  the  head  of  the 
queue  is  thus  the  least  recently  used, 
and  its  buffer  is  the  one  the  algorithm 
can  overlay.  The  size  of  this  queue 
corresponds  to  the  fixed  number  of 
existing  page  buffers,  so  — because  the 
queue  doesn’t  shrink  and  grow — it’s 
not  necessary  to  incur  the  overhead  of 
dynamic  allocation  to  manage  it.  In¬ 
stead  we  can  use  an  array. 

When  an  existing  page  is  accessed, 
its  dirty  bit  is  set  and  the  node  moves 
to  the  back  of  the  queue.  Similarly,  a 
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page  faulting  and,  to  a  lesser  extent, 
TLB  misses.  There  are  two  approaches 
to  this  problem. 

One  is  to  lock  pages  containing  mem¬ 
ory  and  translation  table  entries  into 
the  TLB  for  time-critical  routines.  The 
only  performance  penalty  is  the  ad¬ 
dress  translation  overhead,  which  is 
usually  small  in  single  chip  CPU/MMU 
implementations.  It’s  not  difficult  to  lock 
pages  in  memory  because  page  swap¬ 
ping  is  handled  by  system  software.  All 
that  is  required  is  an  additional  bit  in 
the  page  map  tables’  address  transla¬ 
tion  entries  to  indicate  whether  the  page 
is  swappable.  In  addition,  the  page 
replacement  algorithm  must  eliminate 
such  pages  from  the  pool  of  available 
swapping  candidates. 

Locking  TLB  entries  is  another  mat¬ 
ter,  because  TLB  reloading  is  usually 
handled  by  the  CPU’s  microcode.  In 
such  cases,  the  CPU  must  directly  fur¬ 
nish  the  ability  to  lock  TLB  entries.  The 
Motorola  68851,  the  companion  MMU 
for  the  68020,  includes  such  support. 

Perhaps  the  best  approach  for  en¬ 
hancing  real-time  performance  is  to  set 
aside  regions  of  the  virtual  address  space 
that  are  not  mapped  by  the  MMU  at  all. 
This  completely  eliminates  address  trans¬ 
lation  overhead  and  results  in  portions 
of  the  memory  map  where  virtual  and 


real  addresses  are  the  same.  This  is  the 
approach  taken  by  the  designers  of  the 
68030’s  MMU. 

Virtual  Address  Spaces 

An  important  decision  in  the  design  of 
a  virtual  memory  manager  is  how  many 
address  spaces  to  support  and  how  to 
arrange  processes  within  them.  This 


can  go  as  far  as  running  multiple  oper¬ 
ating  systems  concurrently,  each  in  its 
own  virtual  machine.  The  most  visible 
example  of  this  type  of  implementa¬ 
tion  is  Microsoft  Windows/386,  which 
uses  the  paging  and  protection  capa¬ 
bilities  of  the  80386  to  create  multiple 
640K  DOS  environments. 

(continued  on  page  3  7 ) 
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Real  Address 


Figure  3:  Structure  of  the  29000’s  MMU 


page  fault  grabs  the  head  of  the  queue, 
sets  its  dirty  bit,  and  moves  the  node 
to  the  back.  From  the  standpoint  of 
queue  management,  then,  these  opera¬ 
tions  are  identical.  A  doubly  linked  list 
provides  the  necessary  flexibility  and, 
by  designating  one  of  the  nodes  as  the 


Listing  One 

struct  queue  node  { 

WORD  succ; 

/* 

index  of  next  younger 
node  */ 

WORD  pred; 

/* 

index  of  next  older 
node  */ 

WORD  page_id; 

/* 

ID  of  page  associated 
w/this  node  */ 

BYTE  dirty_bit; 

}  lru_fifo[BFRS  +  1]; 

/* 

TRUE  if  page  has  been 
written  to  */ 

list  head,  there  is  no  distinction  be¬ 
tween  the  two  cases. 

Listing  One  shows  the  structure  of  a 
queue  node  and  the  declaration  of  the 
queue  as  an  array  of  these  nodes.  The 
elements  pred  and  succ  are  the  back¬ 
ward  and  forward  pointers,  respectively. 
Note  that  they  are  just  array  indices  and 
not  pointer  types.  This  is  due  to  the 
non-dynamic  nature  of  the  queue.  The 
succ  of  the  list  head  is  the  oldest  (LRU) 
page,  and  the  pred  of  the  list  head  is 
the  youngest  (MRU)  page.  The  other 
two  elements  are  the  dirty  bit  (actually 
a  byte  here,  because  there  are  no  other 
bit  fields  with  which  it  can  share  mem¬ 


ory)  and  the  identifier  of  the  page  asso¬ 
ciated  with  the  node.  In  this  example 
the  buffer  number  associated  with  each 
queue  node  is  equal  to  its  array  index, 


Listing  Two 

void  init_fifo(void) 

{ 

WORD  i; 

for  (i  «*  0;  i  <«  BFRS;  i++)  { 
lru_fifo[i] .succ  =  i  +  1; 
lru_fifo[ij .pred  =  i  -  1; 
lru_fifo[ij .page_id  =  BAD_PAGE; 
lru_fifo[ij .dirty_bit  =  FALSE; 

} 

lru_fifo[0] .pred  ■  BFRS; 
lru  fifo(BFRS) .succ  =  0; 

} 


so  no  additional  data  is  required  to 
provide  page-to-buffer  mapping. 

Listing  Two  is  the  queue  initializa¬ 
tion  routine,  which  executes  once  to 
set  up  the  forward  and  backward  links 
and  clear  the  dirty  bit.  It  also  sets  the 
page  ID  to  an  invalid  value,  thus  pre- 
loading  the  queue  with  phantom  pages. 
As  a  new  page  request  is  received  it 
will  not  match  any  of  the  current  en¬ 
tries,  and  because  the  dirty  bit  is  not 
set,  the  memory  manager  bypasses  the 
copy-back  step.  The  buffer  associated 
with  the  head  of  the  queue  will  hold 
the  new  page,  and  its  node  moves  to 
the  back  of  the  queue.  This  small  bit  of 


software  sleight  of  hand  avoids  special 
case  checking  that  would  otherwise 
be  necessary  with  every  page  request. 

Listing  Three  manipulates  the  point¬ 
ers  to  delete  the  specified  node  and 
relink  it  to  the  back  of  the  queue.  The 
existence  of  the  list  head  node  allows 
this  to  work  without  case  checking. 
This  is  not  obvious,  it  is  a  valuable 
exercise  to  prove  this  by  assuming  in¬ 
stead  a  separate  variable  which  points 
to  the  head  of  the  queue  and  develop¬ 
ing  the  equivalent  function.  You  will 

Listing  Three 

void  requeue (WORD  node) 

{ 

lru  fifo[lru  fifo [node] .pred] .succ  =  lru  fifo 
[node] .succ; 

lru_fifo[lru_fifo [node] .succ] .pred  -  lru_fifo 
[node] .pred; 

lru_fifo[lru_fifo[LIST_HEAD] .pred] .succ  =  node; 

lru_fifo [node] .pred  =  lru_fifo[LIST_HEAD] .pred; 

lru_fifo [LIST_HEAD] .pred  =  node; 

lru_fifo [node] .succ  =  LIST_HEAD; 

) _ 

find  that  it  becomes  more  complex. 

The  rest  of  the  code  shows  what  else 
is  needed  to  put  a  complete  Memory 
Management  System  in  place.  The  de¬ 
tails  of  the  MMS  front  end  will  vary 
since  the  definition  of  a  page  depends 
on  the  application,  and  the  exact  na¬ 
ture  of  the  interface  between  the  MMS 
and  the  application  will,  of  course,  vary 
also.  — T.G. 
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(continued  from  page  35) 

Other  applications  include  high-reli¬ 
ability,  fault-tolerant  systems  where  it 
is  essential  that  failing  tasks  not  destroy 
data  belonging  to  others.  Putting  each 
task  in  its  own  address  space  guaran¬ 
tees  this. 

Multiple  address  spaces  can  be  cre¬ 
ated  entirely  via  software  in  the  virtual 
memory  manager  and/or  with  aid  of 

Microprocessors  didn’t 
have  the  horsepower. 
Now  they  do 


hardware  support  in  the  MMU.  The 
software  approach  involves  setting  up 
separate  mapping  tables  for  each  ad¬ 
dress  space  and  changing  the  pointer 
to  the  table  area  when  activating  a  proc¬ 
ess  that  resides  in  a  different  address 
space. 

Most  MMUs  support  multiple  address 
spaces  in  hardware  with  pseudo  ad¬ 
dress  bits:  Status  codes  that  may  be 
combined  with  the  regular  address  bits 
during  address  translation.  Unfortu¬ 
nately,  the  pseudoaddress  bits  can  con¬ 
fuse  the  VMM  if  it  wants  to  move  data 
between  spaces.  This  can  be  handled 
by  mapping  addresses  in  both  spaces 
to  a  common  page  in  memory,  but  this 
circumvents  the  protection  that  was  the 
goal  of  separate  spaces  in  the  first  place. 
Consequently,  most  CPUs  that  use 
pseudo  address  bits  also  provide  spe¬ 
cial  privileged  instructions  that  allow 
the  VMM  to  read  and  write  physical 
addresses. 

Sizing  Up  The  Players 

There  are  currently  three  widely  avail¬ 
able  32-bit  CPUs  with  on  chip  MMUs: 
The  Motorola  68030,  the  Intel  80386, 
and  the  AMD  Am29000.  The  latter  is 
one  of  the  new  RISC  processors.  The 
MMU  architecture  of  each  reflects  its 
target  market  and  historical  background. 
Table  1  gives  a  comparison  of  their 
features. 

The  68030  has  the  most  sophisticated 
MMU  of  the  three.  Based  on  the  68851 
MMU  used  with  the  68020,  it  empha¬ 
sizes  flexibility  and  maximum  hardware 
support.  The  reason  for  this  approach 
can  be  traced  to  the  68000’s  success  in 
the  technical  workstation  market.  Each 
of  Motorola’s  customers  had  different 
system  requirements;  Silicon  Graphics 
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with  a  high-performance  graphics  en¬ 
vironment;  MassComp’s  real-time  Unix 
implementation;  Sun  and  Apollo  with 
general-purpose  workstations. 

Flexibility  is  apparent  in  the  wide 
range  of  page  sizes  as  well  as  the  abil¬ 
ity  to  select  from  1-  to  5-level  transla¬ 
tion  trees.  The  three-bit  function  code 
generated  by  the  68020  and  68030  sup¬ 
ports  up  to  eight  separate  32-bit  logical 
address  spaces.  The  TLB  is  a  fully  asso¬ 
ciative  22  entry  design  with  control  fields 
for  protection  and  memory  caching  sup¬ 
pression. 


Multiple  operating 
systems  run 
concurrently,  each  in 
its  own  virtual  machine 


Real-time  support  is  provided  in  the 
form  of  transparent  translation  (that  is, 
no  translation)  for  up  to  two  regions. 
The  regions  can  be  as  small  as  16 
Mbytes,  with  each  allocated  to  a  spe¬ 
cific  address  space.  The  main  draw¬ 
back  to  this  scheme  is  that  it  bypasses 
normal  page  protection  methods,  which 
are  applied  to  the  region  as  a  whole. 

Compared  to  the  68030,  the  80386’s 
paged  memory  management  capabili¬ 
ties  are  minimal.  This  is  the  first  mem¬ 
ber  of  the  80X86  family  with  any  sup¬ 
port.  Intel  also  retained  the  segmented 
memory  architecture  of  the  earlier  chips 
in  the  design,  and  made  it  possible  to 
use  both  schemes  simultaneously.  These 
backward  compatibility  requirements, 
combined  with  the  need  to  keep  the 
chip  size  within  producible  limits,  dic¬ 
tated  the  simplicity  of  the  80386’s  page 
management  support.  Page  size  is  fixed 
at  4K  and  only  two-level  translation 
tables  are  supported.  Despite  these  limi¬ 
tations,  the  80386’s  ability  to  support  a 
virtual  machine  environment  for  DOS 
applications  makes  it  a  strong  contender 
for  the  high-end  personal  computer 
market. 

The  AMD  29000  is  the  first  commer¬ 
cial  32-bit  RISC  microprocessor  with 
an  on-chip  MMU.  In  keeping  with  the 
bare-bones,  high-performance  goals  of 
RISC,  the  29000’s  MMU  provides  the 
minimum  hardware  needed  to  support 
DPVM.  Systems  software  for  the  29000 
must  therefore  perform  some  functions 
that  are  done  by  hardware  in  other 


VM 


architectures:  TLB  reloads  are  an  ex¬ 
ample.  While  this  adds  complexity  to 
the  job  of  writing  a  VMM,  it  does  yield 
the  ultimate  in  system  flexibility.  That’s 
a  major  benefit  in  the  embedded  real¬ 
time  controller  market  for  which  the 
chip  is  targeted. 

The  29000  MMU  supports  up  to  256 
32-bit  address  spaces  through  an  8-bit 
process  identifier  (PID).  Unlike  the 
68000  family’s  function  codes,  which 
the  processor  automatically  generates, 
the  PID  is  loaded  into  a  register  in  the 
MMU  by  system  software.  This  gives 
the  system  designer  more  control  over 
the  allocation  of  address  spaces.  In  a 
multi-OS  virtual  machine,  the  PIDs  sepa¬ 
rate  the  address  spaces  of  each  guest 
OS.  In  high-reliability,  multitasking  en¬ 
vironments,  each  task  can  be  allocated 
its  own  address  space  using  the  PIDs. 
Figure  3  shows  the  structure  of  the 
29000’s  MMU. 

The  trend  is  clearly  toward  CPUs, 
such  as  the  68030  and  80386  for  both 
mid-range  and  high-end  desktop  sys¬ 
tems.  The  incorporation  of  the  MMU 
means  support  for  DPVM,  is  a  given  in 
systems  using  these  CPUs  [HELP],  The 
major  remaining  requirement  for  DPVM 
is  a  reasonably  fast  fixed  disk,  and  these 
are  already  widely  available  at  low  cost. 
As  a  result  you  will  begin  to  see  more 
and  more  systems  featuring  the  multi¬ 
tasking  and  unlimited  address  spaces 
that  DPVM  makes  possible  on  small 
computers. 
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SWAP 

An  application-independent  method  for  one 
MS-DOS  application  to  run  another 


Nico  Mak 


Many  application  programs 
have  “shell-to-DOS”  capa¬ 
bilities  that  let  you  run  ap¬ 
plications  or  execute  DOS 
commands  from  within  your 
resident  (current)  program.  The  prob¬ 
lem  with  many  of  these  programs,  how¬ 
ever,  is  that  once  you’ve  enabled  the 
shell-to-DOS  capabilities,  you  often 
don’t  have  enough  memory  left  to  run 
the  additional  programs  you  need.  In 
this  article  I’ll  present  a  program  that 
provides  an  application-independent 
method  for  one  MS-DOS  application 
to  run  another,  even  if  both  programs 
would  normally  not  fit  in  memory  at 
the  same  time.  The  program,  which 
I’ve  named  SWAP  (see  Listing  One, 
page  72),  eliminates  the  need  for  an 
application  to  have  its  own  memory 
management  routines.  A  typical  use  is 
to  temporarily  swap  out  a  text  editor 
so  that  you  can  run  memory-hungry 
compilers,  linkers,  or  even  debuggers 
without  losing  your  place  in  an  editing 
session.  The  box  on  page  46  discusses 
some  typical  uses  of  SWAP.  The  amount 
of  extra  memory  you  gain  by  using 
SWAP  can  be  significant,  but  it  de¬ 
pends  on  the  size  of  the  application 
that  is  swapped  out.  When  run  from 
dBase  III  Plus,  for  example,  SWAP  frees 
approximately  220K  of  memory. 

SWAP  works  by  copying  conven¬ 
tional  memory  used  by  the  currently 
running  application  to  expanded  mem¬ 
ory  or  to  a  disk  file,  thereby  freeing 
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conventional  memory  used  by  the  ap¬ 
plication.  SWAP  then  runs  the  desired 
program  before  restoring  the  original 
environment. 

For  convenience  sake,  I  refer  to  the 
program  that  shells  to  DOS  and  gets 
swapped  out  as  the  swappee.  Expanded 
memory  and  EMS  refer  to  memory  that 
conforms  to  Version  3-2  or  later  of  the 
Lotus/Intel/Microsoft  Expanded  Mem¬ 
ory  Specification.  Numbers  suffixed  by 
an  //are  in  hexadecimal  notation  (for 
example,  21H). 

SWAP  is  compatible  with  most  MS- 
DOS  programs.  I’ve  tested  it  with  many 
popular  programs,  including  dBase  III 
Plus,  Lotus  1-2-3,  and  Mansfield  Soft¬ 
ware  Group’s  KEDIT.  Before  relying 
on  it,  however,  you  should  test  SWAP 
with  your  own  configuration  in  case 
of  conflicts  with  terminate-and-stay- 
resident  (TSR)  software  and  other  pro¬ 
grams. 

The  program  is  most  likely  to  fail 
when  used  with  multitasking  software 
such  as  DESQview  and  Windows.  This 
is  because  these  programs,  like  SWAP, 


modify  DOS  memory  control  blocks. 
However,  because  they  have  their  own 
facilities  for  overcoming  memory  con¬ 
straints,  you  generally  would  not  use 
SWAP  with  these  products. 

Though  SWAP  is  coded  in  8088  as¬ 
sembly  language,  you  don’t  need  to 
know  assembly  language  to  understand 
how  it  works.  The  description  provided 
here  will  make  more  sense,  however, 
if  you  have  had  some  experience  with 
the  IBM  PC  interrupt  system  and  some 
of  the  more  common  DOS  (interrupt 
21H)  functions. 

Using  the  SWAP  Program 

The  SWAP  command  (see  Figure  1  for 
the  command  syntax)  can  be  entered 
at  the  DOS  prompt,  or  it  can  be  part  of 
the  command  string  that  your  applica¬ 
tion  sends  to  DOS  to  run  another  pro¬ 
gram.  When  the  -Coption  is  used,  SWAP 
copies  everything  written  to  the  stan¬ 
dard  output  device  (stdout)  to  the  con¬ 
sole  before  it  is  written  to  stdout.  This 
option  is  useful  when  standard  output 
is  redirected.  It  can  save  considerable 


SWAP  [options]  command  [command-parameters]  [  >  fileid] 
Brackets  indicate  optional  parameters. 

Valid  SWAP  options  are: 

-C  Copy  redirected  output  to  the  console 
-D  Disk  file  C:\SWAP.DAT  is  used  instead  of  expanded  memory. 
-F  Forces  SWAP  to  continue  even  if  an  interrupt  vector  points  to 
the  Swappee. 

-Q  Quiet  operation.  Informational  messages  are  not  displayed. 

Command  is  any  command  that  can  be  issued  at  the  DOS  prompt. 
command-parameters  are  parameters  or  options  for  the  command. 
fileid  is  a  DOS  file  or  device  to  which  output  from  the  command  can 
be  directed. 
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Figure  1:  SWAP’s  command  syntax 
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time  in  certain  situations  — for  exam¬ 
ple,  when  a  long-running  program  goes 
astray,  you  normally  don’t  find  out  about 
the  problem  until  the  program  com¬ 
pletes  and  you  view  the  file  containing 
the  redirected  output.  The  -C  option 
gives  you  an  opportunity  to  abort  the 
program  immediately  by  pressing  Ctrl- 
Break  because  output  is  displayed  on 
the  console  at  the  same  time  as  it  is 
written  to  stdout. 

The  -C  option  is  particularly  useful 
when  compiling  programs  from  inside 
an  editor.  I  use  an  editor  macro  that 
redirects  compiler  output  to  a  disk  file, 
examines  the  output  for  error  messages, 
and  automatically  locates  any  source 
lines  that  generated  compiler  errors  (simi¬ 
lar  macros  are  available  for  most  edi¬ 
tors).  Occasionally,  a  simple  mistake 
confuses  a  compiler  enough  so  that 
every  source  line  generates  an  error.  If 
the  program  is  large,  it  can  be  a  while 
before  the  compiler  and  editor  macro 
run  to  completion.  Because  SWAP  cop¬ 
ies  each  error  message  to  the  console 
as  it  is  generated,  I  can  terminate  a  long 
compile  immediately  rather  than  wait¬ 
ing  for  unnecessary  and  lengthy  proc¬ 
essing  by  the  compiler  and  editor  macro. 

Normally,  SWAP  will  not  operate  on 
a  program  that  it  thinks  has  taken  con¬ 
trol  of  any  of  the  machine’s  interrupt 
vectors.  Because  removing  interrupt¬ 
handling  code  would  probably  result 
in  a  crashed  machine.  Examples  of  pro¬ 
grams  that  take  control  of  interrupt  vec¬ 
tors  are  SideKick,  The  Norton  Guides, 
and  many  communications  products. 

To  determine  whether  the  swappee 
has  hooked  an  interrupt  vector,  SWAP 
issues  the  Get  Vector  function  (inter¬ 
rupt  21H ,  function  35H)  to  obtain  the 
addresses  of  the  interrupt  handlers  for 
interrupts  0  through  80H.  If  one  of  the 
addresses  points  to  memory  owned  by 
the  swappee,  SWAP  assumes  that  the 
program  deliberately  took  control  of 
the  interrupt  vector. 

Because  stray  unused  vectors  might, 
by  chance,  point  at  the  program  you 
want  to  swap  out,  the  -F  option  is 
provided  to  override  this  default  be¬ 
havior.  This  option  should  be  used  only 
if  you  are  sure  that  the  Swappee  does 
not  hook  interrupt  vectors. 

MCBs,  PSPs,  and  PIDs 

Before  going  into  a  step-by-step  de¬ 
scription  of  SWAP’s  operation,  I  should 
discuss  three  aspects  of  DOS  internals 
that  are  not  covered  by  the  IBM  and 
Microsoftdocumentation  — memorycon- 
trol  blocks  (MCBs),  the  program  seg¬ 
ment  prefix  (PSP),  and  process  identifi¬ 
ers  (PIDs). 

SWAP’s  operation  depends  on  modi¬ 
fying  DOS  MCBs.  Although  the  follow¬ 


ing  information  is  not  documented  by 
Microsoft  or  IBM,  it  is  consistent  in 
DOS  Versions  2.0  through  4.0.  Two 
references  for  information  on  MCBs  are 
the  “16-Bit  Software  Toolbox”  columns 
in  the  October  1986  and  February  1987 
issues  of  DDJ. 

SWAP  works  by  copying 
conventional  memory 
used  by  the  currently 
running  application  to 
expanded  memory  or 
to  a  disk  file,  thereby 
freeing  conventional 
memory  used  by  the 
application 

An  MCB  immediately  precedes  each 
block  of  memory  allocated  by  DOS  or 
by  a  user  program.  MCBs  are  one  para¬ 
graph  (16  bytes)  long,  but  only  the  first 
5  bytes  are  used.  (See  Figure  2  for  the 
format  of  an  MCB.)  The  id  field  con¬ 
tains  a  hex  5A  for  the  MCB  describing 
the  last  block  of  memory  in  the  system 
and  hex  4D  for  all  other  MCBs.  The 
owner  field  contains  the  address  of  the 
program  segment  prefix  (PSP)  of  the 


program  that  allocated  the  memory  or 
for  which  DOS  allocated  the  memory. 
A  0  in  this  field  indicates  that  the  mem¬ 
ory  is  free,  and  an  8  in  this  field  marks 
memory  allocated  before  the  first  user 
program  is  loaded.  The  length  field 
contains  the  number  of  paragraphs  in 
the  block  of  memory  (note  that  this 
field  does  not  include  the  length  of  the 
MCB  itself). 

DOS  allocates  two  MCBs  when  it 
runs  a  program:  one  for  the  program’s 
environment  and  one  for  the  program 
itself.  Additional  MCBs  are  built  when¬ 
ever  a  program  allocates  memory  with 
interrupt  21H function  48H. 

In  the  simplest  case,  when  SWAP  is 
started,  the  system  will  contain  MCBs 
for  the  following  blocks  of  memory: 
DOS  system  memory  (owner  address 
8),  the  copy  ofCOMlVlAND.COM  loaded 
during  DOS  initialization  (three  MCBs), 
the  swappee  environment,  the  swap- 
pee’s  PSP  and  code,  the  copy  of  COM¬ 
MAND. COM  loaded  by  the  swappee 
(three  MCBs),  SWAP’s  environment, 
SWAP’s  PSP  and  code,  and  unallocated 
memory  (owner  address  0). 

Note  that  this  list  includes  three  MCBs 
for  each  copy  of  COMMAND.COM. 
DOS  builds  two  MCBs  when  it  loads 
COMMAND.COM,  just  as  when  any 
other  program  is  loaded.  The  third  MCB 
is  for  memory  allocated  by  COM¬ 
MAND. COM  for  an  additional  (larger) 
copy  of  the  environment.  There  may 
be  additional  MCBs  for  any  TSR  pro¬ 
grams.  MCBs  may  not  be  in  this  order 
if  memory  is  fragmented. 

Most  of  the  PSP  is  well  documented 
in  the  DOS  Technical  Reference ,  but 
several  useful  fields  are  described  as 
“reserved”  in  IBM  and  Microsoft  manu¬ 
als.  See  Figure  3  for  the  location  and 
lengths  of  these  fields. 


Figure  2:  Memory  control  block  (MCB)  format 


Figure  3:  Some  useful  but  undocumented  fields  in  the  program  segment 
prefix  (PSP) 
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In  DOS  Versions  2.0  through  4.0,  the 
parent  pointer  contains  the  segment 
address  of  the  program’s  parent.  COM¬ 
MAND. COM  is  always  its  own  parent, 
so  this  field  is  also  useful  in  determin¬ 
ing  whether  a  PSP  belongs  to  COM- 
MAND.COM. 

The  fields  related  to  the  file  handle 
array  are  valid  only  in  DOS  Versions 
3.0  through  4.0.  The  file  handle  array 
contains  20  1-byte  entries,  one  for  each 
possible  file  handle.  For  example,  the 
entry  at  offset  0  into  the  file  handle 
array  corresponds  to  file  handle  0.  En¬ 
tries  are  indexes  into  another  table  DOS 
uses  internally  to  keep  track  of  file 
handles.  An  entry  of  hex  FF  indicates 
that  the  corresponding  file  handle  is 
not  open.  The  file-handle-array  pointer 
holds  the  address  of  the  file  handle 
array.  The  handle  array  size  field  con¬ 
tains  the  number  of  entries  in  the  file 
handle  array. 

A  program  can  enlarge  the  file  han¬ 
dle  array  by  changing  the  pointer  and 
handle  array  size  fields  and  by  copying 
the  original  file  handle  array.  In  this 
case  the  default  file  handle  array  is  no 
longer  used.  Under  DOS  Versions  3-3 
and  4.0,  applications  can  use  interrupt 
21H function  67Hlo  perform  this  func¬ 
tion.  You  can  read  more  about  the 
file-handle-array-related  fields  in  the  “16- 
Bit  Software  Toolbox”  columns  in  the 
May  1986,  September  1986,  and  De¬ 
cember  1986  issues  of  DDJ. 

The  process  ID  (PID)  for  a  program 
running  under  DOS  Versions  3  0 
through  4.0  is  the  address  of  its  PSP. 
When  a  program  asks  DOS  to  perform 
functions  that  use  fields  in  the  PSP, 
DOS  uses  the  PID  to  locate  the  current 
PSP.  The  undocumented  interrupt  21H 
functions  51H  and  52H  respectively 
get  and  set  the  current  PID.  See  the 
“16-Bit  Software  Toolbox”  column  in 
the  May  1986  issue  of  DDJ  for  more 
on  these  functions. 

SWAP  uses  the  Get/Set  PID  func¬ 
tions  in  two  places:  the  interrupt  21H 
handling  routine  and  the  subroutines 
that  are  copied  on  top  of  the  Swappee. 
These  routines  are  described  in  detail 
in  the  following  sections. 

How  SWAP  Works 

SWAP  performs  miscellaneous  initiali¬ 
zation,  including  displaying  the  copy¬ 
right  notice  and  checking  the  command¬ 
line  options.  It  checks  the  parent  pointer 
field  in  its  PSP  to  verify  that  its  parent 
is  COMMAND.COM.  It  then  builds  a 
table  containing  the  relevant  informa¬ 
tion  from  all  MCBs,  identifies  the  MCB 
for  its  own  PSP,  and  works  backward 
through  the  table  of  MCBs  to  deter¬ 
mine  how  much  memory  can  be 
swapped  out.  This  memory  consists  of 


its  own  environment,  memory  belong¬ 
ing  to  the  parent  COMMAND.COM,  and 
memory  allocated  in  all  MCBs  belong¬ 
ing  to  the  swappee  (except  the  MCB 
for  the  swappee’s  environment). 

SWAP  verifies  that  no  interrupt  vec¬ 
tors  point  to  memory  allocated  to  the 
Swappee.  It  copies  memory  used  by 
itself,  COMMAND.COM,  and  the  swap¬ 
pee  to  expanded  memory  or  to  a  disk 
file.  The  program  copies  the  necessary 
subroutines  to  the  first  few  kilobytes 
of  memory  allocated  to  the  swappee, 
thereby  overlaying  the  swappee.  It  also 
overlays  the  swappee’s  file  handle  ar¬ 
ray  with  its  own  file  handle  array  and 
ensures  that  the  file-handle-array  pointer 
in  the  swappee’s  PSP  points  to  this 
new  file  handle  array. 

SWAP  reduces  the  amount  of  mem- 


Typical  Uses  of  SWAP 

To  understand  how  SWAP  can  be  used, 
assume  for  the  moment  that  you  have 
entered  DOS  from  within  your  editor 
in  order  to  assemble  a  program.  If  the 
command  you  normally  use  to  assem¬ 
ble  your  program  is: 

MASM  filename; 

then  the  command  to  run  your  assem¬ 
bler  with  SWAP  becomes: 

SWAP  MASM  filename; 

If  you  typically  redirect  the  assembler 
output  to  a  disk  file,  you  can  still  see  a 
copy  of  the  assembler  output  on  the 
screen  using: 

SWAP  -C  MASM  filename;  >  out- 

put.fil 

Of  course,  you  would  do  this  in  your 
editor’s  macro  language  or  from  a  .BAT 
file. 

To  use  SWAP  to  swap  out  dBase  and 
load  your  favorite  editor,  you  could 
enter  the  dBase  command: 

RUN  SWAP  KEDIT  filename 

Alternatively,  you  could  add  the  fol¬ 
lowing  line  to  your  CONFIG. DB  file: 

TEDIT  =  SWAP.COM  -F  KEDIT.EXE 

and  subsequently  enter  the  following 
dBase  command  to  edit  a  file: 

MODIFY  COMMAND  filename 

— NM 


ory  allocated  to  the  Swappee  by  alter¬ 
ing  the  length  field  in  the  MCB  for  the 
swappee’s  PSP,  building  an  MCB  for 
the  remainder  of  the  storage  it  swapped 
out,  and  marking  this  new  MCB  as 
unallocated.  SWAP  then  transfers  con¬ 
trol  to  the  code  that  overlaid  the  swap¬ 
pee.  This  subroutine  uses  the  Set  PID 
function  to  set  the  current  PID  to  the 
swappee’s  PSP.  Then  it  runs  COM¬ 
MAND.  COM  to  execute  the  user’s  com¬ 
mand.  When  the  user’s  command  com¬ 
pletes,  all  but  the  first  16K  that  was 
swapped  out  is  swapped  back  in  (the 
first  16K  can’t  be  swapped  in  at  this 
point  because  it  would  overlay  the  code 
for  this  step).  SWAP  then  transfers  con¬ 
trol  back  to  the  area  of  memory  in 
which  it  was  first  run. 

SWAP  issues  the  Set  PID  function  to 
reset  the  process  ID.  The  first  16K  of 
the  Swappee  are  swapped  in,  thus  re¬ 
storing  the  machine  to  the  previous 
state.  SWAP  then  releases  its  EMS  han¬ 
dle,  or  if  the  -D  option  was  used,  erases 
the  work  file. 

Interrupt  21 H  Handler 

When  the  -C  option  is  used,  SWAP 
installs  an  interrupt  21H handler  to  copy 
everything  written  to  the  standard  out¬ 
put  device  to  the  console.  Standard 
output  is  presumably  redirected  away 
from  the  console,  so  SWAP  also  opens 
another  file  handle  for  the  console  de¬ 
vice.  Every  time  an  interrupt  21H  oc¬ 
curs,  the  interrupt  handler  checks  for 
functions  that  write  to  standard  output. 
When  one  of  these  functions  is  used, 
SWAP  copies  the  data  headed  for  stan¬ 
dard  output  to  the  console.  These  func¬ 
tions  are: 

•  02H — Display  Output  (outputs  the 
character  in  DL) 

•  06H — Direct  Console  I/O  (unless  DL 
=  hex  FF,  same  as  function  02H) 

•  09H — Print  String  (outputs  a  dollar- 
sign-delimited  string) 

•  40H — Write  to  a  File  or  Handle  (if 
writing  to  stdout) 

Output  written  to  any  file  handle  is 
copied  if  the  file-handle-array  entry  for 
that  handle  is  the  same  as  the  entry  for 
standard  output. 

When  the  interrupt  21H  handler  de¬ 
termines  it  should  copy  data  to  the 
console,  it  issues  the  Get  PID  function 
to  save  the  caller’s  PID,  then  issues  the 
Set  PID  function  specifying  the  inter¬ 
rupt  21H  handler’s  PSP.  This  is  done 
so  that  DOS  uses  the  appropriate  file 
handle  array  to  write  a  copy  of  the  data 
to  the  handle  opened  for  the  console 
device.  SWAP  then  issues  the  Set  PID 
function  to  restore  the  caller’s  PID  and 
jumps  to  the  original  interrupt  21H han- 
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(continued  from  page  46) 
dler.  Note  that  the  original  interrupt 
21H  handler  does  not  know  that  SWAP 
has  “front-ended”  the  interrupt. 

Conclusion 

You’ll  like  SWAP  if  you’ve  ever  tried 
to  run  one  application  from  within  an¬ 
other  and  got  the  message  “Program 
too  big  to  fit  in  memory.”  SWAP  is 


You’ll  like  SWAP 
if  you’ve  ever  tried 
to  run  one 

application  from  within 
another  and  got 
the  message  “Program 
too  big  to  fit  in 
memory” 


particularly  useful  to  programmers  be¬ 
cause  it  can  be  used  as  the  basis  for  an 
integrated  environment  that  makes  it 
easy  to  compile,  link,  correct  errors, 
and  even  debug  without  leaving  your 
editor. 

If  you  make  enhancements  to  SWAP, 
I  encourage  you  to  upload  the  modi¬ 
fied  code  to  the  DDJ  Forum  on  Com¬ 
puServe.  I  have  already  posted  a  ver¬ 
sion  that  makes  it  easier  to  use  SWAP 
from  Mansfield  Software  Group’s  Per¬ 
sonal  REXX  interpreter.  Comments  and 
suggestions  are  welcome.  I  can  be 
reached  at  70056,241  on  CompuServe, 
or  as  Nico_Mak  on  Bix. 

Availability 

All  source  code  for  articles  in  this  issue 
is  available  on  a  single  disk.  To  order, 
send  $14.95  (Calif,  residents  add  sales 
tax)  to  Dr.  Dobb’s  Journal,  501 
Galveston  Dr.,  Redwood  City,  CA  94063, 
or  call  800-356-2002  (inside  Calif.)  or 
800-533-4372 (outside  Calif.).  Please  spec¬ 
ify  the  issue  number  and  format  (MS- 
DOS,  Macintosh,  Kaypro). 

DDJ 

(Listing  begins  on  page  72.) 

Vote  for  your  favorite  feature/article. 

Circle  Reader  Service  No.  4. 
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A  Memory  Allocation 
Compaction  System 

Here’s  a  compaction  technique  to  solve  your 
fragmented  memory  problems 


Steve  Peterson 


With  the  popularity  of  the  C 
programming  language, 
the  use  of  dynamic  mem¬ 
ory  allocation  in  PC  soft¬ 
ware  has  become  com¬ 
mon.  Graphical  interfaces  and  object- 
oriented  programming  techniques  both 
rely  heavily  upon  the  ability  to  dyna¬ 
mically  create  and  delete  blocks  of 
memory. 

A  natural  by-product  of  the  memory 
allocation  tools  provided  by  the  stan¬ 
dard  C  library  is  heap  fragmentation. 
In  an  operating  environment  with  vir¬ 
tual  memory,  fragmentation  is  a  con¬ 
cern  only  to  the  extent  that  it  degrades 
performance.  Unfortunately,  under  MS- 
DOS,  memory  can  become  so  frag¬ 
mented  that  the  program  fails  for  lack 
of  contiguous  free  memory.  Microcom¬ 
puter  operating  systems  developed  af¬ 
ter  MS-DOS  provide  solutions  to  this 
problem.  Both  Microsoft  Windows  and 
the  Macintosh  Toolbox  provide  sup¬ 
port  for  compaction  of  memory.  In  ad¬ 
dition,  Microsoft  OS/2  provides  sup¬ 
port  for  virtual  memory. 

This  article  describes  a  compacting 
memory  management  scheme  that  is 
implemented  in  C.  The  scheme’s  fea¬ 
tures  include  the  allocation  of  memory 
blocks  that  can  move  in  memory  to 
minimize  fragmentation,  the  ability  to 
mark  individual  memory  blocks  as  de- 
leteable  or  nondeleteable  and  as  fixed 


Steve  Peterson  is  a  consultant  with 
FOURTH  SHIFT  Corp.  in  Minneapolis. 
He  can  be  reached  at  3100  Boone  Ave., 
North,  Minneapolis,  MN 55427. 


or  moveable,  and  the  availability  of  a 
function  that  can  be  associated  with  a 
block  that  is  called  whenever  the  block 
is  moved  or  deleted.  Furthermore,  this 
scheme  can  easily  be  ported  to  other 
environments  where  an  ANSI-standard 
C  compiler  is  available. 

Memory  Compaction  Strategies 

For  a  memory  compaction  system  to 
be  useful,  it  must  compress  memory 
without  disturbing  pointers  in  the  user 
program.  Two  approaches  to  this  proc¬ 
ess  are  in  general  use.  Both  approaches 
maintain  a  master  pointer  table,  which 
contains  the  master  pointers  to  every 
allocated  block.  These  approaches  dif¬ 
fer  in  the  way  that  the  user  accesses  the 
master  pointer. 

Under  Microsoft  Windows,  the  user 
program  is  given  a  handle  to  an  allo¬ 
cated  block  of  memory.  To  use  the 
handle,  a  function  must  be  called  to 
lock  the  block  in  place  and  to  retrieve 
a  pointer  to  the  block.  The  lock  should 
be  released  when  the  program  no  longer 
needs  to  reference  that  block  of  mem¬ 
ory.  The  advantage  of  this  method  is 
that  a  block  will  not  move  in  memory 
while  the  block  is  being  used.  The 
disadvantage  of  this  method  is  that  you 
must  call  a  function  in  order  to  get  a 
pointer  to  a  block. 

The  method  implemented  in  this  ar¬ 
ticle  is  similar  to  that  used  on  the  Apple 
Macintosh.  When  a  block  of  memory 
is  allocated,  the  user  program  is  given 
a  pointer  to  the  master  pointer  table 
entry  that  corresponds  to  the  block. 
The  user  program  can  either  reference 


the  block  by  dereferencing  the  pointer 
twice,  or  it  can  copy  the  address  from 
the  master  pointer  table  to  a  local 
pointer.  This  implementation  requires 
careful  programming.  Consider  the  fol¬ 
lowing  example  of  a  function  that  reads 
a  record  from  a  database  where  Rec  is 
a  double-indirect  pointer  to  a  block. 

GetDbRecfBlockNum,  *Rec) 

If  GetDbRec  causes  memory  to  be  com¬ 
pacted,  and  Rec  is  moved  to  a  different 
location,  *Rec  is  no  longer  a  valid 
pointer,  and  anything  that  GetDbRec 
writes  to  *Rec  will  overwrite  other  data. 
To  overcome  this  problem,  do  one  of 
the  following: 

•  Ensure  that  any  function  passed  a 
dereferenced  pointer  cannot  cause 
memory  to  be  compacted. 

•  Write  your  code  so  that  the  double- 
indirect  pointer,  rather  than  a  derefer¬ 
enced  pointer,  is  passed. 

•  Lock  the  block  in  memory  if  a  dere¬ 
ferenced  pointer  is  passed  to  a  rou¬ 
tine  that  can  cause  memory  to  be 
compacted. 

By  adhering  to  these  rules,  you  can 
avoid  memory  corruption. 

Data  Structures 

When  the  system  is  initialized,  it  cre¬ 
ates  one  or  more  segments,  a  master 
segment  table  (MST),  and  a  master 
pointer  table  (MPT).  (See  Figure  1.) 
Each  segment  has  an  entry  in  the  MST. 
An  MST  entry  contains  the  physical 
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address  of  the  segment,  the  number  of 
blocks  allocated,  the  amount  of  free 
space  in  the  segment,  and  pointers  to 
the  first  free  block  and  to  the  most 
recent  free  block  accessed.  The  pointer 
to  the  most  recent  free  block  is  used 
to  allocate  blocks  evenly  throughout 
the  segment. 

Each  segment  contains  one  or  more 
blocks,  as  shown  in  Figure  2.  When  the 
segment  is  created,  it  contains  one  block 
that  is  marked  as  free  and  encompasses 
the  entire  segment.  As  the  user  pro¬ 
gram  requests  memory,  this  free  block 
is  broken  into  smaller  blocks  that  are 
marked  as  they  are  allocated.  Each  block 
has  a  header  that  is  stored  immediately 
prior  to  the  block  in  memory.  This 
header  contains  the  length  of  the  block, 
a  pointer  to  the  previous  block  in  the 
segment,  flags,  the  segment  in  which 
this  block  is  located,  the  master  pointer 
associated  with  this  block,  and  the  ad¬ 
dress  of  the  block  function.  The  mean¬ 
ing  of  the  bits  in  the  flag  byte  are  shown 
in  Table  1. 


When  a  block  is  allocated,  the  sys¬ 
tem  places  a  pointer  to  the  block  into 
a  free  entry  in  the  MPT.  The  user  pro¬ 
gram  receives  a  pointer  to  this  table 
entry.  The  use  of  double  pointer  refer¬ 
ences  lets  the  block  move  in  memory 
without  the  user  program’s  knowledge. 
Unused  MPT  entries  point  to  NULL. 
The  MPT  is  created  when  the  system 
is  initialized,  and  is  not  stored  in  a 
segment. 

The  compaction  algorithm  coalesces 
free  space  in  the  segment  until  a  re¬ 
quest  for  space  is  satisfied.  If  the  amount 
of  freed  space  is  not  sufficient,  this 
algorithm  begins  removing  deletable 
blocks  until  the  request  is  satisfied. 

When  a  block  is  deleted,  the  header 
portion  of  the  block  remains  in  mem¬ 
ory.  This  allows  the  application  to 
determine  that  the  block  has  been 
deleted. 

The  Memory  Compaction  Code 

Listing  One,  page  82,  contains  the  mem¬ 


ory  manager  header  file.  Listing  Two, 
page  82,  contains  the  code  that  imple¬ 
ments  the  module,  including  functions 
to  initialize  the  module,  allocate  and 
deallocate  memory,  manually  compact 
memory,  and  test  the  state  of  the 
module. 

int  Memlnitflong  Size,  int  Num 
MPTEntries)  — This  function  initializes 
the  module.  Size  specifies  the  number 

For  a  memory 
compaction  system  to  be 
useful,  it  must  compress 
memory  without 
disturbing  pointers  in 
the  user  program 


of  bytes  to  be  allocated  to  segments. 
NumMPTEntries  is  the  number  of  en¬ 
tries  to  be  allocated  in  the  master  pointer 
table.  The  function  returns  TRUE  after 
successful  initialization,  and  FALSE  if 
not  enough  memory  was  available.  For 
example,  Memlnit(262144l,  512);  allo¬ 
cates  256K  under  the  system  and  al¬ 
lows  512  master  pointers. 

The  function  first  allocates  an  array 
large  enough  to  hold  the  entire  master 
pointer  list,  and  it  then  allocates  seg- 
(continued  on  page  55) 


Block  Structure 


Figure  2:  Each  segment  contains  one 
or  more  blocks. 


Master  Segment  Table 


Segment  0 


Master  Pointer 
Table 


Segment  0 


Segment  1 


Segment  N 


Figure  1:  One  or  more  segments,  a  master  segment  table,  and  a  master 
pointer  table  are  created. 


FLAG 

BLKJNUSE 

BLK_DELETED 

BLKDELETABLE 

BLK_LOCKED 

BLK_FUNCDELETE 

BLKFUNCMOVE 

BLK_LAST 


FUNCTION 

Block  is  allocated 
Block  contents  have  been  deleted 
Contents  of  block  can  be  deleted  if  necessary 
Block  cannot  be  moved  in  memory 
Call  block  function  before  deleting  block 
Call  block  function  before  moving  block 
Block  is  last  one  in  the  segment 


Table  1:  Flags  contained  in  the  header  block 
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(continued  from  page  53) 
merits.  The  code  tries  to  allocate  seg¬ 
ments  of  64K  -  1  bytes  long.  If  the  last 
segment  is  less  than  16K  bytes,  its  size 
is  increased  by  16K,  and  the  size  of  the 
next-to-last  segment  is  decreased  cor¬ 
respondingly.  This  step  helps  avoid  the 
allocation  of  segments  that  are  too  small 
to  be  useful. 

Once  the  segments  are  created,  a 
single  free  block  is  allocated  inside  of 
each  one. 

void  **P  =  MemAlloc(unsigned  int 
Size)  — This  function  allocates  a  block 
of  memory  in  the  system.  Size  is  the 
number  of  bytes  to  be  allocated  in  the 
block.  P  points  to  the  master  pointer 
for  the  block,  or  to  NULL  if  the  block 
could  not  be  allocated. 

The  memory  allocator  first  searches 
the  free  list,  starting  at  the  last  free 
block  referenced,  in  order  to  find  a  free 
block  that  is  large  enough  to  hold  the 
block  to  be  allocated.  If  no  free  block 
is  sufficiently  large,  the  function  com¬ 
pacts  the  segment  that  contains  the 
most  remaining  free  space,  until  that 
segment  has  a  free  block  that  can  hold 
the  block  to  be  allocated.  When  a  block 
is  created,  it  is  marked  non-deletable 
and  moveable. 

void  **P  =  MemAllocFunc  (unsigned 
int  Size,  void  (*FuncXvoid  *b,  un¬ 
signed  int  f,  unsigned  int  Size,  void 
*c),  unsigned  int  Flags)  — This  func¬ 
tion  is  similar  to  MemAlloc,  except  that 
you  can  specify  a  function  (the  “block 
function”)  to  be  called  when  the  block 
is  moved  or  deleted.  Passing  the  flag 
BLK_FUNCMOVE  causes  the  function 
to  be  called  when  the  block  is  moved. 
Similarly,  passing  the  flag 
BLK_FUNCDELETE  causes  the  function 
to  be  called  when  the  block  is  deleted. 
These  flags  can  be  ORe d  together  to 
indicate  both  options. 

The  block  function  takes  as  parame¬ 
ters  the  block  to  be  deleted,  a  flag  that 
indicates  if  the  block  is  being  moved 
or  deleted,  and  the  length  of  the  block. 
If  BLK_FUNCMOVE  is  set,  C  points  to 
the  new  location  of  the  block.This  func¬ 
tion  returns  VOID. 

void  MemFree(void  **P)  — This  func¬ 
tion  deallocates  a  block  of  memory.  P 
points  to  the  MPT  entry  for  the  block, 
and  the  deallocation  routine  combines 
the  block  with  adjacent  free  blocks. 
The  block  function  is  not  called  when 
a  block  is  deallocated. 
MemCompact(void)  — This  function 
lets  you  manually  compact  memory. 
By  calling  CompactSeg( )  for  each  seg¬ 
ment,  memory  is  compacted  completely. 
CompactSeg(byte  Segment,  un¬ 
signed  int  Size,  int  Deletable)  — The 
CompactSeg  function  performs  the  ac¬ 
tual  compaction  of  memory.  Segment 
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indicates  the  segment  to  be  compacted. 
Size  indicates  how  many  bytes  of  con¬ 
tiguous  space  are  required.  Deleteable 
is  TRUE  if  deletable  blocks  are  to  be 
deleted. 

The  function  proceeds  through  mem¬ 
ory,  examining  each  block  in  turn,  and 
looks  for  a  free  block  where  coalescing 
can  begin.  Once  the  first  free  block  is 
found,  the  function  begins  the  com¬ 
paction  of  subsequent  blocks.  If  a  block 
is  deletable,  it  is  marked  as  deleted, 
and  the  function  moves  the  block 
header  to  its  new  location.  If  a  block 
is  in  use  and  moveable,  that  block  is 
moved  to  its  new  location. 

In  MemAllocf ),  the  function  is  called 
twice.  It  is  called  with  Deletable  FALSE, 
then  called  again  with  Deletable  TRUE 
if  there  is  still  not  enough  free  space. 
MemLocked(void  **P) — The  Mem- 
Locked  function  returns  TRUE  if  a  block 
is  locked;  otherwise  it  returns  FALSE. 
MemLock(void  **P)  — locks  a  block 
into  a  location  in  memory. 
MemUnlock(void  **P)  — The  function 
MemUnlock  releases  a  lock  on  a  block. 
MemDeleted(void  **P) — This  func¬ 
tion  returns  TRUE  if  a  block  is  de¬ 
leteable,  or  FALSE  if  the  block  is  not 
deletable. 

MemDeletable(void  **P)  — This  func¬ 
tion  makes  a  block  deletable. 
MemUndeletable(void  **P)  — This 
function  makes  a  block  undeletable. 
MemGetLargest(void)  — This  function 
returns  the  size  of  the  largest  block  that 
could  be  allocated. 

MemGetCurrentLargestfvoid)  — The 

function  MemGetCurrentLargest  returns 
the  size  of  the  largest  block  that  could 
be  allocated  without  compaction. 

Using  the  Memory  Compaction  System 

Listing  Three,  page  89,  shows  a  simple 
program  designed  to  demonstrate  the 
features  of  the  module. 

As  in  any  module,  many  enhance¬ 
ments  and  improvements  can  be  made, 
depending  upon  your  needs.  For  ex¬ 
ample,  if  space  is  a  critical  considera¬ 
tion,  you  can  decrease  the  block  over¬ 
head.  One  way  to  do  so  is  by  replacing 
the  pointer  to  the  previous  block  with 
an  offset,  saving  two  bytes  in  the  large 
memory  model.  Another  way  is  to  elimi¬ 
nate  the  block  function,  thus  saving 
four  bytes.  Yet  another  tactic  is  to  store 
the  segment  number  in  the  unused  bits 
of  the  flags  field,  or  to  compute  the 
segment  number  from  the  master  seg¬ 
ment  table  entries.  Finally,  the  master 
pointer  number  can  be  determined  by 
searching  the  master  pointer  table. 


If  time  is  more  important,  you  can 
copy  contiguous  allocated  blocks  in 
one  operation  during  the  compaction 
process,  rather  than  copying  them  sepa¬ 
rately.  Since  the  current  compaction 
algorithm  eliminates  deletable  blocks 
in  a  first-come,  first-served  order,  an¬ 
other  optimization  is  to  add  a  mecha¬ 
nism  for  assigning  priority  to  deleteable 
blocks  in  order  to  allow  the  application 
to  control  the  order  of  deletion.  You 

Graphical  interfaces 
and  object-oriented 
programming 
techniques  both  rely 
heavily  upon  the  ability 
to  dynamically  create 
and  delete  blocks  of 
memory 


can  also  write  the  block  configuration 
functions  ( MemLocked ,  MemLock,  Mem 
Unlock,  MemDeleted,  MemDeletable, 
and  MemUndeletable')  as  macros.  Fi¬ 
nally,  under  Microsoft  C  5.1,  in  certain 
situations  you  can  use  the  memcpy( ) 
function,  which  is  more  efficient. 

Additional  functions  that  you  can  im¬ 
plement  are  MemDelete( ),  which  al¬ 
lows  a  block  to  be  deleted  under  pro¬ 
gram  control,  and  MemReallocate( ), 
which  reallocates  a  block  that  has  been 
deleted. 

Availability 

All  source  code  in  this  issue  is  available 
on  a  single  disk.  To  order,  send  $14.95 
(Calif,  residents  add  sales  tax)  to  Dr. 
Dobb’s  Journal,  501  Galveston  Dr.,  Red¬ 
wood  City,  CA  94063,  or  call  800-356- 
2002  (inside  Calif.)  or  800-533-4372  (out¬ 
side  Calif.).  Please  specify  the  issue 
number  and  format  (MS-DOS,  Macin¬ 
tosh,  Kaypro). 

DDJ 
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Object-oriented  programming  makes  a  case  for 
software  recycling 


Michael  Floyd 


An  object  in  the  real  world  is 
something  with  mass,  an  as¬ 
sociated  weight,  and  volume; 
it  has  other  attributes  that  fur¬ 
ther  refine  its  description  and, 
in  some  cases,  there  may  be  some  pro¬ 
cedure  or  action  that  describes  its  func¬ 
tion.  Our  world  is  filled  with  objects, 
so  it  seems  only  natural  to  describe  and 
solve  problems  in  terms  of  objects  as 
well. 

This  idea  is  the  basis  for  object- 
oriented  programming  (OOP).  As  you’ll 
soon  see,  however,  a  programming  lan¬ 
guage  requires  more  than  just  objects 
to  be  called  object-oriented. 

This  article  begins  with  a  tour  of  the 
concepts  in  object-oriented  program¬ 
ming.  I’ll  cover  the  basic  concepts  in¬ 
cluding  objects,  classes,  inheritance,  and 
polymorphism.  Next,  I’ll  discuss  how 
these  concepts  are  brought  together  to 
do  what  is  called  “object-oriented  pro¬ 
gramming.”  In  addition,  I’ll  examine 
some  of  the  reasons  you  might  con¬ 
sider  OOP.  Finally,  I’ll  cover  some  of 
the  popular  object-oriented  languages 
such  as  SmallTalk  and  Actor,  as  well 
as  some  of  the  traditional  languages, 
like  C  (C++),  that  have  object-oriented 
extensions. 

Objects 

As  in  the  real  world,  an  object  is  some¬ 
thing  with  a  set  of  attributes  and  fea- 
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tures  that  describe  its  nature  and  func¬ 
tionality.  Objects  are  represented  in  most 
OOP  languages  as  data  structures.  The 
degree  of  success  that  an  object  can 
be  described  depends,  in  part,  on  how 
well  those  data  structures  can  be  im¬ 
plemented.  This  is  a  key  point  when 
considering  the  various  OOP  languages. 

At  the  program  level,  objects  can  be 
thought  of  as  Pascal  records  or  C  struc¬ 
tures.  Just  as  a  record  can  contain  other 
records,  an  object  can  contain  other 
objects.  Messages  are  used  to  commu¬ 
nicate  with  objects.  When  a  message 
is  sent  to  an  object,  the  object  uses  a 
set  of  procedures  (called  methods)  to 
respond  to  that  message.  Messages  are 
analogous  to  function  calls  in  other 
languages.  As  an  example,  consider 
the  following  statement: 

3  factorial 

In  this  example,  3  is  an  object  to  which 
the  message  factorial  is  sent.  The  ex¬ 
tent  to  which  messages  are  supported 
depends  on  the  implementation,  as 
you’ll  soon  see. 

Classes 

In  concept,  objects  belong  to  catego¬ 
ries  or  classes  of  objects.  These  classes 
can  in  turn  be  subclasses  of  broader 
classes.  Looking  at  it  another  way,  an 
object  is  an  instance  of  a  particular 
class.  Classes,  then,  provide  a  way  to 
categorize  a  given  set  of  objects. 

As  an  example,  consider  Figure  1, 
which  describes  a  class  of  objects 
known  as  “aircraft.”  Within  the  aircraft 


class  are  subclasses  of  objects  corre¬ 
sponding  to  particular  types  of  aircraft. 
For  instance,  “private  plane”  is  a  sub¬ 
class  of  the  “aircraft”  class.  Continuing 
down  the  graph  you’ll  note  that  '"'Cessna 
182”  is  a  subclass  of  “private  plane” 
and  that  “Flying  Lady”  is  an  object  that 
describes  a  particular  Cessna  182. 

Note  that  each  subclass  is  connected 
to  its  “parent”  class  by  a  link.  Since  a 
private  plane  is  an  aircraft,  the  link 
between  these  two  is  called  an  IS-A 
link.  It  is  this  network  of  links  (called 
a  semantic  network)  that  allows  us  to 
deduce  that  the  Flying  Lady  is  also  an 
aircraft. 

A  class  definition  is  used  to  describe 
a  new  class  of  objects.  This  is  analo¬ 
gous  to  type  definitions  in  other  lan¬ 
guages.  Defining  a  new  class  of  objects 
is  referred  to  as  data  abstraction.  Ob¬ 
jects  are  therefore  described  as  imple¬ 
mentations  of  abstract  data  types. 

As  I  mentioned  earlier,  OOP  treats 
data  structures  as  primary.  At  this  level, 
we  are  talking  about  classes  of  objects. 
Indeed,  OOP  may  well  have  been  called 
COP  (class  oriented  programming)  since 
it  is  better  to  think  in  terms  of  classes 
of  objects  rather  than  individual  ob¬ 
jects  (instances). 

Just  as  messages  are  specific  to  ob¬ 
jects,  methods  are  specific  to  classes. 
A  method  describes  how  a  particular 
class  of  objects  will  behave.  Methods 
are  analogous  to  program  code  in  other 
languages. 

The  difference  between  objects  and 
classes  is  often  confused.  Keep  in  mind 
that  objects  are  created  at  run  time  and 
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(continued  from  page  58) 
are  the  instances  of  a  class,  while  classes 
are  a  static  description  of  an  object  set 
that  exists  in  the  program. 

Another  concept  that  confuses  tradi¬ 
tional  programmers  is  the  notion  that, 
at  least  in  “pure”  OOP,  a  module  and 
a  type  are  the  same.  We  can  therefore 
state  the  following  identity: 

module  =  type 

What  this  implies  is  that  the  class  descrip¬ 
tion  includes  both  the  defining  attrib¬ 
utes  of  an  object  and  the  services  it 
provides.  Indeed,  this  identity  implies 
the  dual  nature  of  classes. 

Inheritance  and  Polymorphism 

Inheritance  is  a  mechanism  that  allows 
an  object  to  inherit  properties  from  a 
class  of  objects.  For  instance,  consider 
Figure  2,  which  adds  some  descrip¬ 
tions  to  the  various  classes  from  Figure 
1.  The  description  for  aircraft,  for  in¬ 
stance,  states  that  all  aircraft  have  land¬ 


ing  gear.  From  this,  you  can  deduce 
that  the  Flying  Lady  must  have  landing 
gear  since  it  is  a  Cessna  182  and  a 
Cessna  182  is  an  aircraft.  In  fact,  the 
description  of  “Flying  Lady”  refines  the 
notion  by  stating  that  this  particular  air¬ 
craft  has  fixed  landing  gear.  As  presen¬ 
ted,  this  is  known  as  single  inheritance 
since  an  object  inherits  its  attributes 
from  a  single  parentclass  (or  ancestor). 

There  are,  of  course,  extensions  to 
the  basic  inheritance  concept.  Multiple 
inheritance,  for  instance,  allows  you 
to  declare  a  class  as  heir  to  more  than 
one  parent  class.  Repeated  inheritance, 
on  the  other  hand,  allows  you  to  de¬ 
clare  a  class  as  heir  to  more  than  once 
to  the  same  class. 

Polymorphism  allows  program  enti¬ 
ties  to  refer  to  objects  in  more  than  one 
class,  and  through  dynamic  binding 
the  ability  for  those  objects  to  respond 
uniquely  to  the  same  message.  This  is 
an  important  feature  since  it  allows  us 
to  group  dissimilar  classes  (analogous 
to  an  array  of  mixed  types). 


Object-Oriented  Programming 

So,  what  is  OOP  and  what  makes  a 
language  object-oriented?  You  might 
say  that  object-oriented  programming 
is  the  combination  of  data  abstraction, 
inheritance,  and  polymorphism.  OOP 
treats  data  as  primary,  therefore,  object- 
oriented  programming  is  a  style  that 
modularizes  a  program  on  the  basis  of 
its  data  structures. 

An  object-oriented  language,  then, 
must  support  abstract  data  typing  for 
the  creation  of  new  classes,  some  de¬ 
gree  of  inheritance  so  that  new  objects 
created  at  run  time  can  take  on  the 
properties  of  predefined  classes,  and 
polymorphism  so  that  a  single  message 
can  elicit  different  responses  from  dif¬ 
ferent  object  classes. 

A  true  OOP  language  should  also 
support  garbage  collection.  The  devel¬ 
opment  system  should  automatically 
deallocate  memory  for  objects  that  will 
no  longer  be  used  in  the  system.  This 
feature  exists  in  most  object  oriented 
languages,  but  not  in  many  of  the  ex¬ 
tended  languages  such  as  C++. 

Why  OOP? 

A  colleague  of  mine  once  noted  that, 
“if  an  object  is  comparable  to  a  C  struc¬ 
ture,  why  do  I  need  another  paradigm?” 
Supporters  of  object-oriented  program¬ 
ming  point  out  that  typical  top-down 
approaches  to  software  development 
lead  to  narrowly  defined  procedures 
that  are  specific  to  a  given  problem. 
Such  procedures  must  be  changed  as 
the  problem  at  hand  changes.  OOP 
on  the  other  hand,  promotes  a  modular 
approach  to  programming.  Because  ob¬ 
jects  stand  on  their  own  as  individual 
components,  they  can  be  readily  ex¬ 
tended  to  handle  new  features.  In  ad¬ 
dition,  objects  can  be  reused,  either 
by  other  parts  of  the  system,  or  in  other 
applications. 

Inheritance  in  particular  promotes  re¬ 
usability  because  modules  (classes)  are 
extensions  of  existing  modules  (parent 
classes).  Polymorphism,  on  the  other 
hand,  promotes  extendibility  and  flexi¬ 
bility  of  the  system. 

Besides  reusability  and  extendibil¬ 
ity,  there  are  other  programming  issues 
that  are  solved  by  object-oriented 
programming.  For  instance,  earlier  I 
mentioned  that  objects,  just  as  a  Pascal 
records  or  C  structures,  can  contain 
other  objects.  But  there  are  some  char¬ 
acteristics  of  objects  that  are  beyond 
the  scope  of  procedural  languages.  For 
instance,  objects  must  be  able  to  “share” 
objects  with  other  objects  (comparable 
to  sharing  a  field  of  a  record  with  an¬ 
other  record).  This  is  not  possible  with 
Pascal. 

Another  problem  difficult  to  solve 
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Figure  1:  Semantic  network  describing  the  “aircraft”  class 


Figure  2:  Semantic  network  detailing  bow  objects  inherit  attributes  from 
parent  classes 
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in  procedural  languages  is  the  ability 
to  create  new  objects  on  the  fly  (com¬ 
parable  to  creating  structures  dynami¬ 
cally  at  run  time).  Indeed,  this  is  one 
of  the  features  that  allows  the  creation 
of  more  “intelligent”  applications.  This 
allows  the  system  to  change  its  behav¬ 
ior  without  programmer  intervention, 
and  has  important  consequences  in  data 
base  and  knowledge-base  applications. 

Object-Oriented  Languages 

As  you  might  guess,  there  are  a  num¬ 
ber  of  object-oriented  programming  lan¬ 
guages  with  disparate  philosophies  on 
how  these  features  should  be  handled. 
Just  as  a  hammer  is  better  than  a  screw¬ 
driver  at  pounding  a  nail,  each  of  the 
object-oriented  languages  caters  to  par¬ 
ticular  needs.  By  surveying  some  of  the 
popular  object-oriented  languages,  you 
may  be  able  to  come  to  grips  with 
which  language  is  most  suitable  for 
your  purposes: 

SmallTalk  — Implemented  as  an  in¬ 
terpreted  environment,  SmallTalk  is  a 
typeless  language  that  favors  dynamic 
binding;  because  no  type  checking  is 
performed,  binding  of  structures  takes 
place  at  run  time.  SmallTalk  was  devel¬ 
oped  at  Xerox  by  Alan  Kay  and  his 
associates  in  the  mid  1970s.  SmallTalk 
has  since  then  been  implemented  for 
a  number  of  platforms  and  Xerox  has 
formed  a  subsidiary  called  ParcPlace 
Systems  to  fully  support  the  SmallTalk 
environment. 

Everything  in  SmallTalk  is  an  object 
including  the  environment  that  Small¬ 
Talk  runs  in.  Therefore,  SmallTalk  does 
not  distinguish  between  objects  and 
classes.  SmallTalk  can  be  described  as 
a  tree  of  classes  where  object  is  the 
root  class,  and  the  leaves  of  the  tree  are 
considered  subclasses.  In  this  scenario, 
a  subclass  is  an  instance  of  a  higher- 
level  class  called  a  metaclass. 

SmallTalk  supports  most  of  the  con¬ 
cepts  developed  in  this  article  includ¬ 
ing  data  abstraction,  inheritance,  poly¬ 
morphism,  and  garbage  collection. 
Actor — Actor,  which  is  implemented 
as  an  interpreter,  still  uses  a  more  pro¬ 
cedural  approach  with  control  and  block 
structures.  The  Actor  language  set  sup¬ 
ports  messages  and  methods,  is  strongly 
typed,  and  includes  a  built-in  library 
of  classes  similar  to  SmallTalk. 

Actor,  like  SmallTalk,  does  not  dis¬ 
tinguish  between  objects  and  classes 
in  the  sense  that  object  is  the  “ultimate” 
class  that  all  other  class  will  be  built 
from.  Actor  supports  all  the  “pure”  ob¬ 
ject-oriented  concepts  described  in  this 
article  including  data  abstraction,  mes¬ 
sage  sending,  single  inheritance,  and 
polymorphism. 

Eiffel — Eiffel  is  a  compiler  that  pro¬ 


vides  a  complete  object  oriented  pro¬ 
gramming  environment.  Eiffel  supports 
most  of  the  concepts  described  in  this 
article  including  multiple  inheritance, 
dynamic  binding,  and  garbage  collec¬ 
tion.  Eiffel  provides  a  complete  library 
of  traditional  tools  as  classes.  These 
classes  include  windowing  and  graph¬ 
ics  based  on  X  Windows,  lists,  hash 
tables,  binary  trees,  and  more. 

An  interesting  feature  of  Eiffel  is  that 
it  generates  C  as  intermediate  code. 
This  allows  for  portability  as  well  as 
opening  the  door  to  cross-development 
in  the  C  environment. 

Extended  Languages 

C++  — -C++,  developed  by  Bjame  Strous- 
trup  at  AT&T,  offers  a  number  of  exten¬ 
sions  to  the  C  language.  C++  by  nature 
distinguishes  objects  from  classes.  As 
with  C  structures,  classes  are  declared 
and  defined  separately.  C++  supports 
the  notion  of  “friend”  routines  that  make 
it  possible  to  call  C++  routines  from  C. 
C++  also  supports  operator  overloading, 
which  allows  you  to  use  the  same  name 
for  different  operations. 

C++  handles  the  issue  of  dynamic 
binding  by  forcing  the  programmer  to 
declare  classes  as  virtual.  Defaulting  to 
static  binding  means  that  the  compiler 
can  implement  calls  efficiently.  This, 
of  course,  has  an  effect  on  the  poly¬ 
morphic  nature  of  the  declared  class. 

Current  implementations  of  C++  only 
support  single  inheritance.  A  C++  stan¬ 
dard  is  expected  from  AT&T  sometime 
this  year.  Some  of  the  issues  still  to  be 
addressed  include  multiple  inheritance. 

Of  course,  all  memory  management 
and  garbage  collection  is  left  to  the 
programmer.  In  keeping  with  traditional 
C,  the  C++  programmer  merely  defines 
Create  and  Destroy  procedures. 
Objective-C  — Objective-C  departs 
from  C++  in  the  sense  that  the  object- 
oriented  portion  of  the  language  is  un¬ 
typed.  Objective-C  provides  a  library 
of  classes  that  roughly  parallel  the 
classes  built  into  SmallTalk.  Providing 
untyped  classes  allows  Objective-C  to 
emphasize  dynamic  binding  and  poly¬ 
morphism,  although  it  only  supports 
single  inheritance.  Again,  allocation  and 
deallocation  of  memory  is  in  the  hands 
of  the  programmer. 

Lisp  — Because  of  the  interest  in  the 
artificial  intelligence  community,  sev¬ 
eral  object-oriented  extensions  to  Lisp 
exist.  Probably  the  most  prominent  in 


this  category  is  Loops  (developed  at 
Xerox).  Most  Lisp  implementations  have 
well  supported  environments  that  pro¬ 
vide  for  multiple  and  repeated  inheri¬ 
tance,  polymorphism  and  dynamic  bind¬ 
ing,  and  garbage  collection.  As  with 
Lisp  proper,  types  are  not  specified  in 
the  language. 

Simula  — Simula,  an  object-oriented  ex¬ 
tension  of  Algol  60,  was  developed  in 
1967  by  Ole-Johan  Dahl  and  Krysten 
Nygaard.  Simula  is  a  strongly  typed 
language  that  supports  program  con¬ 
trol  blocks,  coroutines,  and  the  notion 
of  a  main  program. 

The  major  benefit  brought  to  OOP 
by  Simula  is  its  set  of  built-in  primitives 
for  simulation  modeling.  In  particular, 
Simula  focuses  on  discrete  event  simu¬ 
lation  where  the  model  can  be  thought 
of  as  a  state  machine  and  the  system 
consists  of  individual  events.  Each  event 
is  in  a  given  state  and  the  system  evolves 
in  response  to  these  changing  states. 

Most  implementations  of  Simula  in¬ 
clude  a  well-supported  development 
environment  and  source-level  debug¬ 
ging  facilities.  In  addition,  Simula  sup¬ 
ports  the  necessary  garbage  collection. 
In  contrast  with  languages  such  as  Small¬ 
Talk,  however,  Simula  does  not  include 
a  standard  class  library. 

The  Carpenter's  Wrench 

Although  not  a  new  idea,  OOP  has 
gained  a  great  deal  of  popularity 
in  recent  years.  One  reason  is  that  as 
hardware  technology  improves,  systems 
can  better  handle  the  heavy  demand 
on  resources.  The  down  side  is  that 
features  such  as  multiple  inheritance 
and  dynamic  binding  can  still  slow 
down  an  application  to  a  crawl.  Wait¬ 
ing  for  improved  hardware  technol¬ 
ogy,  then,  is  not  the  answer  as  we 
must  look  for  new  ways  to  optimize 
search  strategies. 

Remember  too  that  every  tool  serves 
a  specific  purpose.  Just  as  the  carpen¬ 
ter  has  no  use  for  a  mechanic’s  wrench, 
you  may  find  little  use  for  object-ori¬ 
ented  programming.  But  if  you’re  in¬ 
volved  in  the  development  of  large  scale 
systems  that  must  evolve  over  time, 
you'll  want  to  take  a  look  at  the  various 
object-oriented  languages.  In  the  proc¬ 
ess,  however,  keep  in  mind  OOP’s 
prime  directive;  reusability. 
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Listing  One  (Text  begins  on  page  14.) 


program  TestExecSwap; 
uses 

Dos, ExecSwap;  {Keep  ExecSwap  last) 
const 

SwapLoc  :  array [Boolean]  of  String[7]  =  ('on  disk',  'in  EMS'); 
var 

Status  :  Word; 
begin 

if  not  InitExecSwap (HeapPtr,  'SWAP.$$$')  then 

WriteLn ('Unable  to  allocate  swap  space') 

else  begin 

WriteLn ('Allocated  ',  BytesSwapped,  '  bytes  ',  SwapLoc [EmsAllocated] ) ; 

SwapVectors; 

Status  :=  ExecWithSwap(GetEnv('COMSPEC' ) ,  ''); 

SwapVectors; 

WriteLn ('Exeec  status;  ',  Status); 

end; 

end. 


End  Listing  One 


Listing  Two 


(Copyright  (c)  1988  TurboPower  Software) 

(May  be  used  freely  as  long  as  due  credit  is  given) 

($R-,S-> 
unit  ExecSwap; 

(-Memory-efficient  DOS  EXEC  call) 
interface 

const 

BytesSwapped  :  Longlnt  =  0;  (Bytes  to  swap  to  EMS/disk) 

EmsAllocated  :  Boolean  -  False;  (True  when  EMS  allocated  for  swap) 

FileAllocated  ;  Boolean  -  False;  (True  when  file  allocated  for  swap) 

function  ExecWithSwap (Path,  CmdLine  :  String)  :  Word; 

(-DOS  EXEC  supporting  swap  to  EMS  or  disk) 

function  InitExecSwap (LastToSave  :  Pointer;  SwapFileName  :  String)  :  Boolean; 
(-Initialize  for  swapping,  returning  TRUE  if  successful) 

procedure  ShutdownExecSwap; 

(-Deallocate  swap  area) 

implementation 

var 

EmsHandle  :  Word; 

FrameSeg  :  Word; 

FileHandle  :  Word; 

SwapName  :  String [80]; 

SaveExit  :  Pointer; 

( $L  EXECSWAP) 

function  ExecWithSwap (Path,  CmdLine  :  String)  :  Word;  external; 
procedure  FirstToSave;  external; 
function  AllocateSwapFile  :  Boolean;  external; 
procedure  DeallocateSwapFile;  external; 

{ $F+ )  (These  routines  could  be  interfaced  for  general  use) 
function  Emslnstalled  :  Boolean;  external; 
function  EmsPageFrame  :  Word;  external; 

function  AllocateEmsPages (NumPages  :  Word)  :  Word;  external; 
procedure  DeallocateEmsHandle (Handle  :  Word);  external; 
function  DefaultDrive  :  Char;  external; 
function  DiskFree (Drive  :  Byte)  :  Longlnt;  external; 

procedure  ExecSwapExit; 
begin 

ExitProc  :=  SaveExit; 

ShutdownExecSwap; 
end; 

($F-) 

procedure  ShutdownExecSwap; 
begin 

if  EmsAllocated  then  begin 

DeallocateEmsHandle (EmsHandle) ; 

EmsAllocated  :=  False; 
end  else  if  FileAllocated  then  begin 
DeallocateSwapFile; 

FileAllocated  :=  False; 
end; 
end; 

function  PtrDiff(H,  L  :  Pointer)  :  Longlnt; 
type 

OS  =  record  0,  S  :  Word;  end;  (Convenient  typecast) 
begin 

PtrDiff  :=  (Longlnt (OS (H) .S)  shl  4+0S(H).0)- 
( Longlnt (OS (L) . S)  shl  4+0S(L).0); 

end; 

function  InitExecSwap (LastToSave  :  Pointer; 

SwapFileName  :  String)  :  Boolean; 

const 

EmsPageSize  =  16384;  (Bytes  in  a  standard  EMS  page) 


var 

Pages InEms  ;  Word;  (Pages  needed  in  EMS) 

BytesFree  :  Longlnt;  (Bytes  free  on  swap  file  drive) 

DriveChar  :  Char;  (Drive  letter  for  swap  file) 

begin 

InitExecSwap  :=  False; 

if  EmsAllocated  or  FileAllocated  then 
Exit; 

BytesSwapped  :=  PtrDiff (LastToSave,  GFirstToSave) ; 
if  BytesSwapped  <=  0  then 
Exit ; 

SaveExit  :=  ExitProc; 

ExitProc  :=  @ExecSwapExit; 

if  Emslnstalled  then  begin 

PagesInEms  :=  (BytesSwapped+EmsPageSize-1)  div  EmsPageSize; 
EmsHandle  :=  AllocateEmsPages (PagesInEms) ; 
if  EmsHandle  <>  $FFFF  then  begin 
EmsAllocated  :=  True; 

FrameSeg  :=  EmsPageFrame; 
if  FrameSeg  <>  0  then  begin 
InitExecSwap  :=  True; 

Exit  ; 
end; 
end; 
end; 

if  Length (SwapFileName)  <>  0  then  begin 
SwapName  :=  SwapFileName+#0; 
if  Pos(':',  SwapFileName)  =  2  then 
DriveChar  ;=  Upcase (SwapFileName [1] ) 
else 

DriveChar  :=  DefaultDrive; 

BytesFree  :»  DiskFree (Byte (DriveChar) — $4 0 ) ; 

FileAllocated  :=  (BytesFree  >  BytesSwapped)  and  AllocateSwapFile; 
if  FileAllocated  then 
InitExecSwap  :=  True; 

end; 

end; 

end. 


End  Listing  Two 


Listing  Three 

; EXECSWAP. ASM 

;  Swap  memory  and  exec  another  program 
;  Copyright  (c)  1988  TurboPower  Software 
;  May  be  used  freely  as  long  as  due  credit  is  given 


DATA  SEGMENT 

EXTRN 
EXTRN 
EXTRN 
EXTRN 
EXTRN 
EXTRN 
EXTRN 
EXTRN 

DATA  ENDS 

BYTE  PUBLIC 

BytesSwapped : DWORD 
EmsAllocated: BYTE 
FileAllocated: BYTE 
EmsHandle: WORD 

FrameSeg: WORD 

FileHandle: WORD 

SwapName: BYTE 
PrefixSeg:WORD 

; Bytes  to  swap  to  EMS/disk 
;True  when  EMS  allocated  for  swap 
;True  when  file  allocated  for  swap 
; Handle  of  EMS  allocation  block 
.•Segment  of  EMS  page  frame 
; Handle  of  DOS  swap  file 
; ASCIIZ  name  of  swap  file 
;Base  segment  of  program 

CODE  SEGMENT 

ASSUME 
PUBLIC 
PUBLIC 
PUBLIC 
PUBLIC 
PUBLIC 

WORD  PUBLIC 

CS : CODE, DS: DATA 

ExecWithSwap, FirstToSave 

AllocateSwapFile, DeallocateSwapFile 

DefaultDrive, DiskFree 

Emslnstalled, EmsPageFrame 

AllocateEmsPages, DeallocateEmsHandle 

FileAttr 

EQU 

6 

;Swap  file  attribute  (hidden+system) 

EmsPageSize 

EQU 

16384 

;Size  of  EMS  page 

FileBlockSize 

EQU 

32768 

,-Size  of  a  file  block 

StkSize 

EQU 

128 

; Bytes  in  temporary  stack 

lo 

EQU 

(WORD  PTR  0) 

; Convenient  typecasts 

hi 

EQU 

(WORD  PTR  2) 

ofst 

EQU 

(WORD  PTR  0) 

segm 

EQU 

(WORD  PTR  2) 

.•Variables  in  CS 

EmsDevice 

DB 

' EMMXXXX0' , 0 

;Name  of  EMS  device  driver 

UsedEms 

DB 

0 

; 1  if  swapping  to  EMS,  0  if  to  file 

BytesSwappedCS 

DD 

0 

; Bytes  to  move  during  a  swap 

EmsHandleCS 

DW 

0 

;EMS  handle 

FrameSegCS 

DW 

0 

; Segment  of  EMS  page  window 

FileHandleCS 

DW 

0 

;DOS  file  handle 

PrefixSegCS 

DW 

0 

; Segment  of  base  of  program 

Status 

DW 

0 

; ExecSwap  status  code 

LeftToSwap 

DD 

0 

; Bytes  left  to  move 

SaveSP 

DW 

0 

.•Original  stack  pointer 

SaveSS 

DW 

0 

.•Original  stack  segment 

PathPtr 

DD 

0 

.•Pointer  to  program  to  execute 

CmdPtr 

DD 

0 

.•Pointer  to  command  line  to  execute 

ParasWeHave 

DW 

0 

.■Paragraphs  allocated  to  process 

CmdLine 

DB 

128  DUP(0) 

.■Terminated  command  line  passed  to  DOS 

Path 

DB 

64  DUP(O) 

.•Terminated  path  name  passed  to  DOS 

FileBlockl 

DB 

16  DUP(0) 

;FCB  passed  to  DOS 

FileBlock2 

DB 

16  DUP(O) 

;FCB  passed  to  DOS 

EnvironSeg 

DW 

0 

; Segment  of  environment  for  child 

CmdLinePtr 

DD 

0 

.•Pointer  to  terminated  command  line 

FilePtrl 

DD 

0 

.•Pointer  to  FCB  file 

FilePtr2 

DD 

0 

; Pointer  to  FCB  file 

TempStack 

DB 

StkSize  DUP(0) 

; Temporary  stack 

StackTop 

LABEL  WORD 

; Initial  top  of  stack 

(continued  on  page  68) 


(Handle  of  EMS  allocation  block) 
(Segment  of  EMS  page  frame) 

(DOS  handle  of  swap  file) 

{ASCIIZ  name  of  swap  file) 

(Exit  chain  pointer) 
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Listing  Three  (Listing  continued,  text  begins  on  page  14.) 

Z Macros 

MovSeg 

MACRO  Dest,Src 

/Set  one  segment  register  to  another 

MOV 

SaveSP 

SP  z  Save 

stack  position 

MOV 

SaveSS 

ss 

Src 

MovMem 

BytesSwappedCS . lo, Bytes Swapped. lo 

MovMem 

BytesSwappedCS . hi , Bytes Swapped . hi 

MovMem 

EmsHandleCS, EmsHandle 

MovMem 

FrameSegCS , FrameSeg 

MovMem 

MACRO  Dest,Src 

/Move  from  memory  to  memory  via  AX 

MovMem 

FileHandleCS, FileHandle 

AX, Src 

MovMem 

Pref ixSegCS, PrefixSeg 

MOV 

ENDM 

InitSwapCount 

;  Init 

lalize  bytes  LeftToSwap 

MACRO 

/Initialize  counter  for  bytes  to  swap 

/ Check 

for  swapping  to  EMS  or  file 

MovMem 

LeftToSwap . lo, BytesSwappedCS . lo 

CMP 

EmsAllocated,  0 

/Check  flag  for  EMS  method 

MovMem 

Lef tToSwap . hi , BytesSwappedCS .hi 

JZ 

NotEms 

/Jump  if  EMS  not  used 

/Swap  to  EMS 

NotEms 

CMP 

FileAllocated, 0 

/Check  flag  for  swap  file  method 

SetSwapCount 

MACRO  BlkSize 

/Return  CX  =  bytes  to  move  this  block 

JNZ 

WriteF 

/Swap  to  file 

LOCAL 

FullBlk 

/...and  reduce  total  bytes  left  to  move 

JMP 

ESDone 

/Exit  if  no  swapping  method  set 

MOV 

CX, BlkSize 

/Assume  we'll  write  a  full  block 

CMP 

LeftToSwap. hi, 0 

/Is  high  word  still  non-zero? 

/Write 

to  swap 

file 

JNZ 

FullBlk 

/Jump  if  so 

WriteF: 

MovSeg 

DS,  CS 

/DS  =  CS 

CMP 

LeftToSwap. lo, BlkSize 

/Low  word  still  a  block  or  more? 

InitSwapFile 

/Seek  to  start  of  swap  file 

JAE 

FullBlk 

/Jump  if  so 

JNC 

EFO 

/Jump  if  success 

MOV 

CX, LeftToSwap. lo 

/Otherwise,  move  what's  left 

JMP 

ESDone 

/Exit  if  error 

FullBlk:SUB 

LeftToSwap. lo,CX 

/Reduce  number  left  to  move 

EFO: 

SetSwapCount  FileBlockSize 

/CX  »  bytes  to  write 

SBB 

LeftToSwap. hi,  0 

MOV 

DX, OFFSET  FirstToSave 

/ DS : DX  ->  start  of  region  to  save 

DosCallAH  40h 

/File  write 

JC 

EF1 

/Jump  if  write  error 

NextBlock 

MACRO  SegReg,  BlkSize 

/Point  SegReg  to  next  block  to  move 

CMP 

AX,  CX 

/All  bytes  written? 

MOV 

AX, SegReg 

JZ 

EF2 

/Jump  if  so 

ADD 

AX, BlkSize/16 

/Add  paragraphs  to  next  segment 

EF1: 

JMP 

ESDone 

/Exit  if  error 

MOV 

SegReg, AX 

/Next  block  to  move 

EF2 : 

NextBlock  DS, FileBlockSize 

/Point  DS  to  next  block  to  write 

MOV 

AX, LeftToSwap. lo 

JNZ 

EFO 

/Loop  if  bytes  left  to  write 

OR 

AX, LeftToSwap. hi 

/Bytes  left  to  move? 

MOV 

UsedEms, 0 

/Flag  we  used  swap  file  for  swapping 

ENDM 

JMP 

SwapDone 

/Done  swapping  out 

EmsCall 

MACRO  FuncAH 

/Call  EMM  and  prepare  to  check  result 

/Write 

to  EMS 

MOV 

AH, FuncAH 

/Set  up  function 

WriteE: 

MOV 

ES, FrameSeg 

/ES  ->  page  window 

67h 

MOV 

DX, EmsHandle 

/DX  =  handle  of  our  EMS  block 

OR 

AH, AH 

/Error  code  in  AH 

XOR 

BX,  BX 

/BX  =  initial  logical  page 

ENDM 

MovSeg 

DS,CS 

/DS  =  CS 

EEO: 

XOR 

AL,  AL 

/Physical  page  0 

DosCallAH 

MACRO  FuncAH 

/Call  DOS  subfunction  AH 

EmsCall 

44h 

/Map  physical  page 

MOV 

AH, FuncAH 

JZ 

EE1 

/Jump  if  success 

21h 

JMP 

ESDone 

/Exit  if  error 

ENDM 

EE1: 

SetSwapCount  EmsPageSize 

/CX  =  Bytes  to  move 

XOR 

DI ,  DI 

/ES:DI  ->  base  of  EMS  page 

MOV 

SI, OFFSET  FirstToSave 

; DS : SI  ->  region  to  save 

DosCallAX 

MACRO  FuncAX 

/Call  DOS  subfunction  AX 

MoveFast 

/Move  CX  bytes  from  DS:SI  to  ES:DI 

MOV 

AX, FuncAX 

INC 

BX 

/Next  logical  page 

21h 

NextBlock  DS, EmsPageSize 

/Point  DS  to  next  page  to  move 

JNZ 

EEO 

/Loop  if  bytes  left  to  move 

MOV 

UsedEms, 1 

/Flag  we  used  EMS  for  swapping 

InitSwapFile 

MACRO 

MOV 

BX, FileHandleCS 

/BX  =  handle  of  swap  file 

/Shrink 

memory 

allocated  to  this  process 

XOR 

CX,CX 

SwapDone:MOV 

AX, Pref ixSegCS 

XOR 

DX,DX 

/Start  of  file 

MOV 

ES,  AX 

/ES  =  segment  of  our  memory  block 

DosCallAX  4200h 

/DOS  file  seek 

DEC 

AX 

ENDM 

MOV 

DS,  AX 

/DS  =  segment  of  memory  control  block 

MOV 

CX, DS : [0003h] 

/CX  =  current  paragraphs  owned 

HaltWithError 

MACRO  Level 

/Halt  if  non-recoverable  error  occurs 

MOV 

ParasWeHave, CX 

/Save  current  paragraphs  owned 

MOV 

AL, Level 

/Set  errorlevel 

SetTempStack 

/Switch  to  temporary  stack 

DosCallAH  4Ch 

MOV 

AX, OFFSET  FirstToSave+15 

ENDM 

MOV 

CL,  4 

SHR 

AX,  CL 

/Convert  offset  to  paragraphs 

MoveFast 

MACRO 

/Move  CX  bytes  from  DS:SI  to  ES:DI 

ADD 

BX,  AX 

CLD 

/Forward 

SUB 

BX, Pref ixSegCS 

/BX  =  new  paragraphs  to  keep 

CX,1 

/Convert  to  words 

DosCallAH  4 Ah 

/SetBlock 

REP 

MOVSW 

/Move  the  words 

JNC 

EXO 

/Jump  if  successful 

RCL 

CX,1 

/Get  the  odd  byte,  if  any 

JMP 

EX  5 

/Swap  back  and  exit 

REP 

MOVSB 

/Move  it 

ENDM 

/Set  up  parameters  and  call  DOS  Exec 

EXO: 

MOV 

AX, ES : [002Ch] 

/Get  environment  segment 

SetTempStack 

MACRO 

/Switch  to  temporary  stack 

MOV 

EnvironSeg, AX 

MOV 

AX, OFFSET  StackTop 

/Point  to  top  of  stack 

MovSeg 

ES,  CS 

/ES  =  CS 

MOV 

BX,  CS 

/Temporary  stack  in  this  code  segment 

LDS 

SI, PathPtr 

/ DS : SI  ->  path  to  execute 

CLI 

/Interrupts  off 

MOV 

DI, OFFSET  Path 

;ES:DI  ->  local  ASCIIZ  copy 

MOV 

SS,BX 

/Change  stack 

CLD 

MOV 

SP,  AX 

LODSB 

/Read  current  length 

STI 

/Interrupts  on 

CMP 

AL,  63 

/Truncate  if  exceeds  space  set  aside 

ENDM 

JB 

EX1 

. - 

MOV 

AL,  63 

/function  ExecWithSwap (Path,  CmdLine  : 

string)  :  Word/ 

EX1 : 

MOV 

CL,  AL 

ExecWithSwap 

PROC  FAR 

XOR 

CH,  CH 

/CX  -  bytes  to  copy 

PUSH 

BP 

REP 

MOVSB 

MOV 

BP,  SP 

/Set  up  stack  frame 

XOR 

AL,  AL 

STOSB 

/ASCIIZ  terminate 

/Move  variables 

to  CS  where  we  can  easily  access  them  later 

LDS 

SI,  CmdPtr 

/ DS : S I  ->  Command  line  to  pass 

MOV 

Status,  1 

/Assume  failure 

MOV 

DI, OFFSET  CmdLine 

/ ES : DI  ->  Local  terminated  copy 

LES 

DI, [BP+6] 

/ES:DI  ->  CmdLine 

LODSB 

MOV 

CmdPtr. of st,DI 

CMP 

AL,  126 

/Truncate  command  if  exceeds  space 

MOV 

CmdPtr.segm,ES 

/CmdPtr  ->  command  line  string 

JB 

EX2 

LES 

DI, [BP+10] 

/ES:DI  ->  Path 

MOV 

AL, 126 

MOV 

PathPtr .ofst,DI 

EX2: 

STOSB 

MOV 

PathPtr . segm,  ES 

/PathPtr  ->  path  to  execute 

MOV 

CL,  AL 

XOR 

CH,  CH 

/CX  -  bytes  to  copy 

REP 

MOVSB 

MOV 

AL, ODH 

/Terminate  with  AM 

STOSB 

MovSeg 

DS,  CS 

/DS  -  CS 

MOV 

SI, OFFSET  CmdLine 

MOV 

CmdLinePtr .ofst, SI 

MOV 

CmdLinePtr . segm,  DS 

/Store  pointer  to  command  line 

INC 

SI 

(continued  on  page  70) 
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Listing  Three  (Listing  continued,  text  begins  on  page  14.) 


MOV  DI, OFFSET  FileBlockl 

MOV  FilePtrl.ofst,DI 

MOV  FilePtrl . segm, ES 

DosCallAX  2901h 

MOV  DI, OFFSET  FileBlock2 

MOV  FilePtr2.ofst,DI 

MOV  FilePtr2.segm,ES 

DosCallAX  2901h 

MOV  DX, OFFSET  Path 

MOV  BX, OFFSET  EnvironSeg 

DosCallAX  4 BO Oh 

JC  EX3 

XOR  AX, AX 

MOV  Status, AX 


; Store  pointer  to  filename  1,  if  any 
; Parse  FCB 


/Store  pointer  to  filename  2,  if  any 
/Parse  FCB 


z  Exec 

/Jump  if  error  in  DOS  call 
/Return  zero  for  success 
/Save  DOS  error  code 


DosCallAX  3D02h 
POP  DS 

MOV  BX, AX 

MOV  AL,  0 

JC  EIDone 

DosCallAH  3Eh 


/Open  for  read/ write 

/Save  handle  in  case  one  returned 
/Assume  FALSE 


/Set  up  temporary  stack  and  reallocate  original  memory  block 


SetTempStack 
MOV  ES, PrefixSegCS 

MOV  BX, ParasWeHave 

DosCallAH  4 Ah 
JNC  EX 4 

HaltWithError  OFFh 
EX4:  InitSwapCount 

/Check  which  swap  method  is  in  use 
EX5:  CMP  UsedEms, 0 

JZ  ReadF 

JMP  ReadE 

/Read  back  from  swap  file 
ReadF:  MovSeg  DS,CS 

InitSwapFile 
JNC  EF3 

HaltWithError  OFEh 
EF3:  SetSwapCount  FileBlockSize 

MOV  DX, OFFSET  FirstToSave 

DosCallAH  3Fh 
JNC  EF4 

HaltWithError  OFEh 
EF4 :  CMP  AX,CX 

JZ  EF5 

HaltWithError  OFEh 
EF5:  NextBlock  DS, FileBlockSize 

JNZ  EF3 

JMP  ESDone 


/Copy  back  from 

EMS 

ReadE: 

MOV 

DS, FrameSegCS 

/DS 

MOV 

DX, EmsHandleCS 

/DX 

XOR 

BX,  BX 

/BX 

MovSeg 

ES,  CS 

/ES 

EE3: 

XOR 

AL,  AL 

/Phy 

EmsCall 

44h 

/Map 

JZ  EE4 

HaltWithError  OFDh 
SetSwapCount  EmsPageSize 
XOR  SI, SI 

MOV  DI, OFFSET  FirstToSave 

MoveFast 

INC  BX 

NextBlock  ES, EmsPageSize 


ESDone:  CLI 

MOV  SS,S 

MOV  SP,S 

STI 

MOV  AX, S 

MOV  DS, A 

MOV  AX, S 

POP  BP 

RET  8 

ExecWithSwap  ENDP 


SS,SaveSS 
SP, SaveSP 

AX, SEG  DATA 
DS,  AX 
AX, Status 
BP 


/Set  up  temporary  stack 


/SetBlock 

/Jump  if  no  error 

/Must  halt  if  failure  here 

/Initialize  LeftToSwap 


/Jump  to  read  back  from  file 
/Read  back  from  EMS 


/Seek  to  start  of  swap  file 

/Jump  if  we  succeeded 

/Must  halt  if  failure  here 

/CX  =  bytes  to  read 

/ DS : DX  ->  start  of  region  to  restore 

/Read  file 

/Jump  if  no  error 

/Must  halt  if  failure  here 

/Jump  if  full  block  read 
/Must  halt  if  failure  here 
/Point  DS  to  next  page  to  read 
/Jump  if  bytes  left  to  read 
/  We '  re  done 


/Jump  if  success 

/Must  halt  if  failure  here 

/CX  =  Bytes  to  move 

;DS:SI  ->  base  of  EMS  page 

;ES:DI  ->  region  to  restore 

/Move  CX  bytes  from  DS:SI  to  ES:DI 

/Next  logical  page 

/Point  ES  to  next  page  to  move 

/Jump  if  so 

/Switch  back  to  original  stack 


/Restore  DS 
/Return  status 


/Remove  parameters  and  return 


MOV 

AL,  1 

/Return  TRUE 

EIDone:  RET 

Emslnstalled 

ENDP 

/function  EmsPageFrame  :  Word/ 

EmsPageFrame 

PROC  FAR 

EmsCall 

41h 

/Get  page  frame 

MOV 

AX,  BX 

/AX  =  segment 

JZ 

EPDone 

/Done  if  Error  =  0 

XOR 

AX,  AX 

/Else  segment  =  0 

EPDone :  RET 

EmsPageFrame 

ENDP 

/function  AllocateEmsPages (NumPages  : 

Word)  :  Word/ 

AllocateEmsPages  PROC  FAR 

MOV 

BX,  SP 

/Set  up  stack  frame 

MOV 

BX,  SS : [BX+4 ] 

/BX  =  NumPages 

EmsCall 

43h 

/Allocate  EMS 

MOV 

AX,  DX 

/Assume  success 

JZ 

APDone 

/Done  if  not  0 

MOV 

AX, OFFFFh 

z$FFFF  for  failure 

APDone:  RET 

2 

/Remove  parameter  and  return 

AllocateEmsPages  ENDP 

/procedure  DeallocateEmsHandle (Handle 

:  Word) z 

DeallocateEmsHandle  PROC  FAR 

MOV 

BX,  SP 

/Set  up  stack  frame 

MOV 

DX,  SS : [BX+4] 

/DX  =  Handle 

EmsCall 

45h 

/Deallocate  EMS 

RET 

2 

/Remove  parameter  and  return 

DeallocateEmsHandle  ENDP 

/function  DefaultDrive  :  Char/ 

DefaultDrive 

PROC  FAR 

DosCallAH  19h 

/Get  default  drive 

ADD 

AL,  'A' 

/Convert  to  character 

RET 

DefaultDrive 

ENDP 

/function  DiskFree (Drive  :  Byte)  :  Longlntz 

DiskFree 

PROC  FAR 

MOV 

BX,  SP 

/Set  up  stack  frame 

MOV 

DL, SS : [BX+4] 

/DL  =  Drive  to  check 

DosCallAH  36h 

/Get  disk  space 

MOV 

DX,  AX 

/Return  OFFFFFFFFh  for  failure 

CMP 

AX, OFFFFh 

/Bad  drive  number? 

JZ 

DFDone 

/Jump  if  so 

MUL 

CX 

/AX  -  bytes/cluster 

MUL 

BX 

/ DX : AX  =  bytes  free 

DFDone :  RET 

2 

/Remove  parameter  and  return 

DiskFree 

ENDP 

End  Listings 


/Label  EVEN  marks  first  location  to  swap 
FirstToSave: 


/function  AllocateSwapFile  :  Boolean/ 
AllocateSwapFile  PROC  NEAR 
MOV  CX, FileAttr 

MOV  DX, OFFSET  SwapName+1 
DosCallAH  3Ch 
MOV  FileHandle,  AX 

MOV  AL,  0 

JC  ASDone 

INC  AL 

ASDone:  RET 
AllocateSwapFile  ENDP 


/Attribute  for  swap  file 
/DS:DX  ->  ASCI I Z  swap  name 
/Create  file 

/Save  handle  assuming  success 
/Assume  failure 
/Failed  if  carry  set 
/Return  true  for  success 


/procedure  DeallocateSwapFile; 
DeallocateSwapFile  PROC  NEAR 
MOV  BX, FileHandle 

DosCallAH  3Eh 
XOR  CX,CX 

MOV  DX, OFFSET  SwapName+1 

DosCallAX  4301h 
DosCallAH  41h 
RET 

DeallocateSwapFile  ENDP 


/Handle  of  swap  file 
/Close  file 
/Normal  attribute 
/DS:DX  ->  ASCIIZ  swap  name 
/Set  file  attribute 
/Delete  file 


/function  Emslnstalled  :  Boolean/ 
Emslnstalled  PROC  FAR 
PUSH  DS 

MovSeg  DS, CS 

MOV  DX, OFFSET  EmsDevice 


/DS  =  CS 

/DS:DX  ->  EMS  driver  name 
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SWAP 


Listing  One  (Text  begins  on  page  44.) 

SWAP  -  (c)  Copyright  1988  Nico  Mak  and  Mansfield  Software  Group 
All  rights  reserved 

To  rebuild  SWAP.COM  u3e  the  following  instructions: 
masm  swap; 
link  swap; 

exe2bin  swap  swap.com 


macro  to  display  an  error  message 
and  to  jump  to  error_exit  routine 


cr 

equ  13 

If 

equ  10 

error 

macro 

message 

local 

around,  msg,  msglen 

jmp 

around 

msg 

db 

^message,  cr.  If 

msglen 

equ 

$-msg 

around: 

mov 

dx, offset  msg 

mov 

cx, msglen 

jmp 

error_exit 

endm 

define  error  message 


get  address  of  error  message 
get  length 

jump  to  error  exit  routine 


the  following  is  copied  over  the  swappee 


segment 

assume 

org 

proc 

jmp 


stack 


'code' 

cs : code, ds: code 
lOOh 
near 
begin 
db 
equ 


org  past  psp 


20  dup(' STACK') 
$ 


db 

equ 

equ 

equ 

equ 

db 

db 

db 

equ 

dw 

dw 


0 

80h 

40h 

20h 

lOh 


option  flag 

copy  stdout  to  'con' 

swap  even  if  vector  points  to  swappee 

don't  print  hello  message 

swap  to  disk 


"SWAP  EMS  Error 
'xx  function  ' 
'xx',cr,lf 
$-emsg_ems 


segment  of  SWAP's  original  psp 
segment  of  swappee' s  psp 


flag 

f lag_copy 
flag_force 
flag_quiet 
flag_disk 

emsg_ems 
ems_rc 
ems_func 
emsg_ems_len 

my_psp 
swappee_psp 

;  variables  used  when  swapping  to  expanded  memory 
ems_handle  dw  ?  ;  emm  handle 

swap_pages  dw  ?  ;  number  of  pages  for  ems_handle 

ems_frame  dw  ?  ;  ems  page  frame 

last_ems_func  db  ?  ;  last  emm  function  issued  by  swap 

;  variables  used  when  swapping  to  disk 

swap_fid  db  "c: \swap.dat", 0  ;  asciiz  string  to  open  swap  file 

swap_handle  dw  ?  ;  handle  while  swap  file  is  open 

;  fields  for  int  21  function  4b  (exec) 
commandcom_ad< 
exec_sp 
command_line 
command_text 
blank_fcb 
exec_parm_blo( 
exec_env 
cmdline_addr 
cmdline_seg 

fcbl_seg 

fcb2_seg 

;  fields  used  by  int  21  handler 
save_pid  dw  ? 

int21_vector  dd  ? 

con  db  "con",0 

handle  dw  ? 

char_buf  db  ? 

save_ax  dw  ? 

save_bx  dw  ? 

save_cx  dw  ? 

save_dx  dw  ? 

save  ds  dw  ? 


dd 

7 

;  address 

of  program  to  exec  (command.com) 

;  swap_in  -  swap 

dw 

? 

;  save  area  for  reg  clobbered  by  exec  function 

- 

db 

?,"/c" 

; 

command  line  for  command.com 

swap_in : 

db 

130  dup  (0) 

command  line  continued 

mov 

db 

36  dup 

(0) 

dummy  fcb  for  exec  function 

add 

equ 

$ 

exec  parameter  block 

mov 

dw 

7 

segment  addr  of  environment 

test 

dw 

offset 

command  line  ;  address  of  command  line 

jnz 

dw 

7 

; - swap  in 

dw 

offset 

blank  fcb 

;  address  of  fcb 

mov 

dw 

? 

cld 

dw 

offset 

blank  fcb 

;  address  of  fcb 

swap  in  page: 

dw 

7 

mov 

pid  at  time  int  21  handler  received  control 

original  int  21  vector  owner 

asciiz  string  to  open  console 

handle  while  "con"  is  open 

buffer  for  int  21  function  2  and  6  handlers 

register  save  areas  for  int  21  handler 


run  command  ■ 


the  following  code  is  copied  over  the  swappee 


run_command: 

call 

call 

call 

call 

retf 


copy_start 

exec_user_cmd 

copy_stop 

swap_in 


;  start  copying  stdout  to  the  console 
;  execute  the  user's  command 
;  stop  copying  stdout  to  the  console 
;  swap  in  all  but  first  16k 


subroutines  for  run  command  follow 


copy_start  -  if  -c  option  specified,  open  handle  for  console  and  hook  int  21 


copy_start : 

test 


flag, f lag_copy 


will  we  copy  stdout  to  display? 


jz 

copy_start_ret 

;  no 

open  a 

handle  that  points  to 

"con" 

mov 

dx, offset  con 

;  address  of  asciiz  file  name 

mov 

ax, 3d01h 

;  code  to  open  handle  for  writing 

int 

21h 

;  open  the  file 

mov 

handle, ax 

;  remember  handle 

jnc 

open_worked 

;  did  open  succeed? 

flag, 255-f lag_copy 
short  copy_start_ret 


no,  then  we  won't  copy  stdout 
...  and  won't  hook  int  21 


and 
jmp 

open_worked: 

; - hook  int  21  vector 

mov  ax,3521h  ;  code  to  get  interrupt  21  vector 

int  21h  ;  ask  dos  for  address  in  vector 

mov  word  ptr  int21_vector,bx;  save  offset 

mov  word  ptr  int21_vector (2] ,es  ;  save  segment 

mov  dx, offset  int21_handler  ;  address  of  our  int  21  handler 

mov  ax,2521h  ;  code  to  set  interrupt  21  address 

int  21h  ;  tell  dos  to  set  int  21  vector 

;  -  ensure  that  standard  error  is  redirected  and  copied 

mov  al,cs:[19h]  ;  get  stdout  file  handle  array  entry 

mov  cs:[lah],al  ;  use  stdout  entry  for  stderr  entry 

copy_start_ret : 
ret 


exec  user  < 


-  set  up  and  issue  the  int  21  function  4b  (exec) 


exec_user_cmd : 
mov 
mov 
mov 
mov 
mov 
mov 
push 
pop 
mov 
Ids 
mov 
int 
mov 
cli 
mov 
mov 
sti 
ret 


cs:exec_sp, sp 
ax,cs: [2ch] 
exec_env,  ax 

word  ptr  cmdline_seg,  ds 
word  ptr  fcbl_seg,ds 
word  ptr  fcb2_seg,ds 


save  register 

pass  address  of  our  environment 
to  exec  function 
address  of  command  line 
fill  in  segments  for  fcbs 


bx, offset  exec_parm_block 
dx, commandcom_addr  ; 
ax,4b00h  ; 
21h 

ds , cs : swappee_psp  ; 


ss, swappee_psp 
sp, exec_sp 


;  bx  =  exec  parameter  block 
es:bx  =  asciiz  string  of  command.com 
code  to  load  and  execute  a  program 
tell  dos  to  execute  the  user's  program 
restore  ds  addressability 
turn  off  interrupts 
restore  stack 


;  allow  interrupts 


copy_stop 

copy_stop: 


close  handle  and  restore  original  int  21  vector 


test 

cs: flag, flag  copy 

;  did  we  copy  stdout  to  display? 

jz 

copy  stop  ret 

;  no 

; - close 

handle  for  console 

mov 

bx, handle 

;  close  handle  for  'con' 

mov 

ah, 3eh 

;  dos  function  *  close  handle 

int 

21h 

;  tell  dos  to  close  'con' 

;  -  restore  original  int  21  vector 

push 

ds 

;  ds  gets  clobbered,  so  save  it 

Ids 

dx,int21  vector 

;  get  address  of  old  int  21  vector 

mov 

ax, 2521h 

;  code  to  set  interrupt  21  address 

int 

21h 

;  tell  dos  to  change  it 

pop 

copy  stop  ret: 
ret 

ds 

;  restore  ds  addressability 

swap  in  all  but  the  first  page  of  swappee 


bx,cs 
bx, 3ffh 
es,bx 

flag, f lag_disk 
swap_in_disk 
from  expanded  mi 
cx,  1 


bx  »  swappee' s  psp 
first  page  to  swap  in  over 


start  with  second  logical  page 


bx,cx 

map_page 

ds 

ds, ems_frame 
si,  0 
di,  0 


call 
push 
mov 
mov 
mov 
push 
mov 
rep 
pop 
pop 
mov 
add 
mov 
inc 
cmp 

jl 

ret 

; - swap  in  from  disk 

swap_in_disk: 
call 


loop  to  swap  16K 
logical  page 


save  ds 

ds  =  where  to  swap  from 


cx, 4000h 
movsb 
cx 
ds 

bx,es 
bx, 400h 
es,bx 
cx 

cx, swap_pages 
swap_in_page 


copy  16K 


mov 
mov 
mov 
mov 
int 
jnc 
error 

lseek_done : 

mov 

swap_in_disk_page : 


open_swap_file 
cx,  0 

dx, 4000h 
bx, swap_handle 
ax, 4201h 
21h 

lseek_done 
"LSEEK  on  swap  file  failed1 

cx,  1 


!  next  place  to  swap  to 


es  =  first  page  to  swap  over 

open  the  swap  file 

high  order  part  of  offset 

file  pointer  to  start  +  16k 

get  swap  file  handle 

code  to  lseek  from  current  location 

tell  dos  to  lseek  to  2nd  page 


call 

mov 

add 

mov 

inc 

cmp 

jl 

call 

ret 


read_swap_file 

bx,es 

bx, 400h 

es,bx 

cx 

cx, swap_pages 
s wap_i n_di s  k_page 
close_swap_file 


start  with  second  logical  page 

loop  to  swap  16K 

read  16k  from  swap  file 


es  =  next  place  to  swap  to 
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int  21  handler  and  its  subroutines  follow 


I  Listing  One  (Listing  continued,  text  begins  on  page  44.) 


assume  ds: nothing 
int21  handler: 


-  decide 

whether  we  will  front-end 

this  int  21  function 

cmp 

ah, 02h 

je 

func02 

cmp 

ah, 06h 

je 

func06 

cmp 

ah, 09h 

je 

func09 

cmp 

ah, 40h 

je 

func40 

-  call  the  original  int  21  vector  owner 

L  thing: 

jmp 

cs:int21  vector 

Le  int  21 

function  9  (print  dollar- 

-sign  delimited  string) 

call 

front_start 

push 

di 

push 

es 

mov 

di,dx 

mov 

es,save  ds 

address  of  string  at  es:di 

mov 

al, ' $' 

scan  for  $ 

mov 

cx,  -1 

max  bytes  to  scan 

cld 

scan  in  forward  direction 

repne 

scasb 

find  the  $ 

sub 

di,dx 

mov 

cx,di  ; 

length  to  write 

dec 

cx  ; 

don't  write  the  $ 

pop 

es 

pop 

di 

mov 

ds, save_ds 

ds  addressability  is  blown 

call 

write_to  con 

write  buffer  to  display 

mov 

ds , cs : swappee_psp 

restore  ds  addressability 

jmp 

front_done 

write_to_con  -  call  original  int  21H  handler  to  write  buffer  to  display 


write_to_con : 

assume  ds: nothing 

mov  bx,cs:handle  ; 

mov  ah, 40h  ; 

pushf 

call  dword  ptr  cs: int21_vector 

ret 


;  handle  opened  for  'con' 

;  dos  function  -  write  to  handle 


front_done  -  almost  done  front-ending  int  21 


front_done: 

assume  ds:code 
;  -  restore  caller's  pid 

mov  bx, save_pid  ;  get  pid  of  process  that  issued  int  21 

mov  ah,50h  ;  dos  function  -  set  pid 

int  21h  ;  set  pid 

.  -  restore  registers  fi  go  jump  to  previous  int  21  handler 

mov  ax, save_ax 

mov  bx,save_bx 

mov  cx, save_cx 

mov  dx,  save_dx 

mov  ds,save_ds  ;  ds  addressability  blown 

jmp  do_real_thing 


the  following  routines  are  used  by  both  parts  of  the  program 


emm  -  remember  emm  function  in  case  of  error  and  issue  int  67 


;  handle  int  21  function  6  (direct  console  i/o) 
func06: 


mov  last_ems_func,ah 

int  67h 

or  ah, ah 

ret 


;  call  expanded  memory  manager 


dl, Offh 
do_real_thing 


get  input  characters? 

yes,  then  there  is  no  output  to  copy 


ems  error  -  handle  ems  errors 


;  handle  int  21  function  2  (display  character  in  dl  register) 
func02: 


char_buf,dl 

dx, offset  char  buf 

cx,  1 

write_to_con 
front  done 


;  put  character  to  write  in  buffer 
;  get  address  of  buffer 
;  get  length 

;  write  buffer  to  display 


mov 

di, offset  ems_rc 

call 

hex_to_ascii 

;  make  ems  error  code  printable 

mov 

ah, Tast_ems_f unc 

mov 

di, offset  ems_func 

call 

hex_to_ascii 

;  make  last  em3  function  printable 

mov 

cx, emsg_ems_len 

mov 

dx, offset  emsg_ems 

jmp 

error_exit 

;  go  display  error  message  and  exit 

handle  int  21  function  40  (write  to  file  handle) 


mov 

func40_done 

jmp 


call  front_start 

verify  that  file  handle  array 


mov  bx, save_bx 

mov  es,save_pid 

les  di,es:34h 

mov  ah,es:[di+l] 

cmp  ah,es: [di+bx] 

pop  es 

pop  di 

jne  func40_done 

call  real  int  21  handler  with 

mov  ds,save_ds 

call  write_to_con 

mov  ds , cs : swappee_psp 


entry  for  this  handle  ! 


;  get  caller's  handle 
;  psp  for  process  issuing  int  21 
;  address  of  caller's  file  handle  array 
;  file  handle  array  entry  for  stdout 
;  does  handle  entry  —  stdout  entry? 


;  no,  don't  copy  to  console 
handle  opened  for  'con' 

;  ds  addressability  blown 
;  write  buffer  to  display 
;  restore  ds  addressability 


;  hex_to_ascii  -  convert  ah  register  contents  to  ascii  hexadecimal  at  ds:di 

hex_to_ascii : 

~  mov  dl,ah 

mov  cx, 2 

hex_char : 

push  cx 

mov  cl, 4 

rol  dl,cl 

mov  al,dl 

and  al,00fh 

daa 

add  al,0f0h 

adc  al,040h 

mov  [di],al 

inc  di 

pop  cx 

loop  hex_char 
ret 


error_exit  -  display  error  message  and  exit 
ds:dx  point  to  error  message,  cx  has  the  length 


front_start  -  start  front-ending  int  21 


f ront_start : 

assume  ds: nothing 

?  -  establish  ds  addressability  and  ; 

mov  save_ds,ds 

mov  ds, cs : swappee_psp 

assume  ds:code 

mov  save_ax, ax 

mov  save_bx,bx 

mov  save_cx, cx 

mov  save_dx, dx 

;  -  remember  caller's  pid 

mov  ah, 51h 

int  21h 

mov  save_pid,bx 

;  -  set  pid  so  our  file  handle  array 

mov  bx, cs 

mov  ah, 50h 

int  21h 

ret 


save  registers 

;  establish  ds  addressability 
;  tell  assembler 
;  save  registers 


;  dos  function  *  get  pid 
;  tell  dos  to  get  pid 
;  remember  pid 
is  used 

;  pid  =  my  cs  register 
;  dos  function  =  set  pid 
;  tell  dos  to  set  pid 


error_exit : 

push 

push 

mov 

mov 

mov 

mov 

int 

pop 

pop 

mov 

mov 

int 

jmp 


dx, offset  emsg_start 

cx, emsg_start_len 

bx,  2 

ah, 40h 

21h 

dx 


handle  for  stderr 

dos  function  -  handle  write 

output  error  message  to  stderr 

handle  for  stderr 

dos  function  -  handle  write 

output  error  message  to  stderr 


routines  to  open,  read  from,  and  close  the  swap  file 


open_s wap_f i le : 
mov 
mov 
int 
jnc 
error 
open_exit : 

mov 

ret 


dx, offset  swap_fid  ; 

ax, 3d00h  ; 

21h 

open_exit 

"Could  not  open  swap  file1 
swap_handle, ax 


;  address  of  fileid  to  open 
;  open  file  in  read-only  mode 


;  read_swap_file  -  read  16K  from  swap  file  to  address  in  es:0 
;  saves  cx 
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read_swap_file 

push 

Listing  One  ( Listing  continued,  text  begins  on  page  44.) 

mov 

bx, swap  handle 

get  swap  file  handle 

;  process  cmdline  -  process  options,  set  up  command  line  for  exec  function 

mov 

cx, 4000h 

read  16k 

- - 

mov 

dx,  0 

buffer  offset 

process  cmdline 

push 

ds 

mov 

bx, 80h 

push 

es 

option  check: 

pop 

ds 

buffer  segment 

inc 

bx 

mov 

ah, 3fh 

dos  function  -  handle  read 

cmp 

byte  ptr  [bx],cr 

;  carriage  return? 

int 

21h 

jne 

option  check2 

;  no 

pop 

ds 

error 

"No  command  to  execute 

* 

pop 

cx 

option  check2: 

jnc 

read  exit 

cmp 

byte  ptr  [bx] , '  ' 

;  blank? 

error 

"Error  reading  swap  file" 

je 

option  check 

read_exit : 

cmp 

byte  ptr  [bx] , '  /  ' 

;  option  signal? 

ret 

je 

got  option 

cmp 

byte  ptr  [bx],'-' 

;  option  signal? 

close  swap  file: 

jne 

copy  command  line 

mov 

bx, swap  handle 

get  swap  file  handle 

got  option: 

mov 

ah, 3eh 

dos  function  =  close  file 

mov 

byte  ptr  [bx],'  ' 

;  blank  out  character  on  command  line 

int 

21h 

inc 

bx 

;  point  at  option 

ret 

mov 

al,byte  ptr  [bx] 

;  get  option 

mov 

byte  ptr  [bx] , '  ' 

;  blank  out  character  on  command  line 

;  - 

or 

al, '  ' 

;  convert  option  to  lower  case 

;  return  -  return  to  DOS 

cmp 

al, ' c' 

;  option  'c'? 

• 

jne 

check  option  q 

return: 

or 

flag, flag  copy 

mov 

ax,4c00h  ; 

dos  function  to  terminate 

option  check 

int 

21h 

back  to  dos 

check  option  q: 

cmp 

al,  'q' 

;  option  'q'? 

• 

jne 

check  option  f 

;  map _page  -  map  EMS  logical  page  in  bx  into  physical  page  0 

or 

flag, flag  quiet 

i 

jmp 

option  check 

map_page : 

check  option  f: 

mov 

al,  0 

physical  page 

cmp 

al, ' f ' 

;  option  'f'? 

mov 

dx,ems  handle  ; 

ems  handle 

jne 

check  option  d 

mov 

ah, 44h 

map  handle  page 

or 

flag, flag  force 

call 

emm 

jmp 

option  check 

jz 

map  page  exit 

check  option  d: 

jmp 

ems  error 

cmp 

al,  'd' 

;  option  'd'? 

map_page_exit : 

jne 

bad  option 

ret 

or 

flag, flag  disk 

jmp 

option  check 

lowend  equ 

$ 

end  of  code  copied  to  lower  memory 

bad  option: 

error 

"Invalid  option" 

line  to  command  line  for  command.com 

;  the  following  is  *not*  copied  on  top  of 

the  swappee 

copy  command  line: 

1  - 

mov 

cl,  ds : [80h] 

;  length  of  my  command  line 

inc 

cl 

;  add  one  for  cr 

hello 

db  "SWAP  Version  1.0 

(c)  Copyright  1988  Nico  Mak" 

mov 

si, 81h 

;  address  of  my  command  line 

db  "  and  Mansfield  Software  Group",  cr,  If 

mov 

di, offset  command  text 

;  address  of  where  to  put  it 

hello  len 

equ  $-hello 

xor 

ch,ch 

;  zero  uninitialized  part  of  count 

emsg  start 

db  "SWAP  Error:  " 

cld 

;  scan  in  forward  direction 

emsg  start  len 

equ  $-emsg  start 

rep 

movsb 

;  copy  command  line 

run_addr 

dw  offset  run  command  ;  offset  of  run  command 

;  set  length  of 

new  command  line 

run_seg 

dw  ? 

;  segment  of  run  command 

mov 

cl,ds: [80h] 

;  length  of  my  command  line 

swappee_mcb 

dw  ?  ; 

segment  of  mcb  for  swappee  psp 

add 

cl,  2 

;  add  2  for  "/c" 

swappee  end 

dw  ?  ; 

segment  of  mcb  after  swappee 

mov 

command  line, cl 

;  save  new  length 

my  mcb  size 

dw  ? 

ret 

next  mcb 

dw  ?  ; 

address  of  next  mcb 

next  code 

db  ? 

M/Z  code  in  next  MCB 

; - 

next  owner 

dw  ?  ; 

etc 

;  say  hello  -  print  hello  message 

next  size 

dw  ?  ; 

. - 

ems  device  name 

db  "EMMXXXXO", 0 

expanded  memory  manager  signature 

say  hello: 

comspec 

db  '  COMSPEC*' 

environment  variable  name 

test 

flag, flag  quiet 

;  was  -q  option  used? 

comspec  len 

equ  $ -comspec 

jnz 

say  hello  exit 

;  yes,  skip  this 

mov 

dx, offset  hello 

;  get  address  of  message 

mcb  info 

struc  ; 

important  memory  control  block 

info 

mov 

cx, hello  len 

;  get  length  of  message 

addr 

dw  ?  ; 

address  of  mcb 

mov 

bx,  2 

;  handle  for  stderr 

owner 

dw  ?  ; 

psp  of  owner 

mov 

ah, 40h 

;  dos  function  -  write  to  handle 

len 

dw  ?  ; 

length  of  mcb 

int 

21h 

;  write  copyright  message 

mcb  info 

ends 

say  hello  exit: 

ret 

max  mcbs 

equ  100 

mcbs 

mcb  info  <> 

; - 

mcb  length 

equ  $-mcbs 

;  check  dos  version  -  be  sure  this  is 

dos  3.0  or  higher 

db  (max  racbs-l)*mcb  length  dup  (?) 

check  dos  version: 

mov 

ah, 30h 

;  dos  function  -  get  version 

;  mainline  code 

run  from  system  prompt 

int 

21h 

;  get  dos  version 

cmp 

al,  3 

;  ok? 

begin: 

jae 

dos  version  ret 

assume 

ds : code , es : code 

error 

"DOS  version  must  be 

.0  or  higher" 

mov 

sp, offset  stack  ; 

set  up  new  stack  pointer 

dos  version  ret 

call 

process  cmdline  ; 

check  options,  set  up  'exec'  cmdline 

ret 

call 

say  hello  ; 

print  copyright  message 

call 

check  dos  version  ; 

ensure  we  have  dos  3.0  or  later 

call 

find  comspec  ; 

find  comspec=  in  environment 

;  find  comspec 

find  fileid  for  exec 

function 

call 

shrink  ourself  ; 

free  unneeded  memory 

call 

get  mcb  info  ; 

get  relevant  info  about  mcbs 

find  comspec: 

call 

check  mcbs  ; 

ensure  mcbs  are  in  expected  order 

mov 

es,es:2ch 

;  es  -  environment  segment 

call 

vector  check  ; 

ensure  swappee  has  not  hooked  vectors 

xor 

di,di 

;  point  to  start  of  env  in  es:di 

call 

figure  pages  ; 

determine  how  many  ems  pages  we 

need 

cld 

;  scan  in  forward  direction 

call 

init  ems  ; 

ems  initialization,  allocation. 

etc 

;  -  loop  thru  environment  strings 

one  by  one,  beginning  here 

call 

swap  out  ; 

swap  out  swappee,  command.com, 

and  us 

find  string: 

call 

muck  with  memory  ; 

copy  swap  over  swappee  &  set  up 

mcbs 

test 

byte  ptr  es: [di] ,  -1 

;  end  of  environment? 

mov 

ss, swappee  psp  ; 

switch  to  stack  in  low  memory 

jnz 

check  string 

;  nope,  continue 

call 

run  user  command  ; 

go  call  run  command  rtn  in  low 

memory 

error 

"Could  not  find  COMSPEC-  in  environment"  ;  very  unlikely 

mov 

ss,my_psp  ; 

switch  back  to  original  stack 

;  -  compare 

current  env  string  to 

' COMSPEC-' 

call 

swap  first  ; 

swap  in  first  16K 

check  string: 

call 

clean  up  ; 

restore  original  environment 

mov 

si, offset  comspec 

;  point  to  'COMSPEC-'  string 

exit : 

mov 

bx,di 

;  save  ptr  to  start  of  env  string 

jmp 

return  ; 

leave  SWAP 

mov 

cx, comspec  len 

;  length  of  'COMSPEC-' 

repe 

cmpsb 

;  compare 

;  - 

je 

found  comspec 

;  found  it 

;  subroutines  for  code  that  is  not  copied  to  low  memory  follow 

mov 

di,bx 

;  restore  ptr  to  start  of  env  string 

;  - 

xor 

al,al 

;  scan  for  end  of  string 

mov 

cx,  -1 

repne 

scasb 

jmp 

find  string 

;  go  back  for  next  string 

;  -  found  COMSPEC- 

f ound_comspec : 
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Listing  One  (Listing  continued,  text  begins  on  page  44.) 

mov  word  ptr  commandcom_addr [0] , di  ;  remember  address  of  . . . 

mov  word  ptr  commandcom  addr [2 j ,  es  ;  ...  asciiz  "conanand.com" 


je  find_swappee_psp  ;  yes  continue 

error  "Unexpected  MCB  while  looking  for  PSP  of  swappee" 

;  -  we've  found  swappee' s  psp  -  bx  points  at  mcb  entry  for  swappee 

f ound_swappee_psp : 


;  shrink_ourself  -  release  unneeded  memory 
shrink  ourself: 


push 

cs 

pop 

es 

;  address  of  start  of  SWAP  memory 

mov 

bx, offset  endcode+15 

;  address  of  end  of  SWAP  code 

mov 

cl, 4 

shr 

bx,cl 

;  convert  to  paragraphs 

mov 

ah, 4ah 

;  dos  function  *  SETBLOCK 

int 

21h 

;  shrink  ourselves 

jne 

error 

check_mcbs_ret : 
ret 


es, [bx] .owner  ;  es  -  swappee 
swappee_psp,es  ;  remember  swa] 
word  ptr  es:2ch,0  ;  swappee  must 
check_mcbs_ret 

"Swappee  does  not  have  an  environment" 


es  -  swappee  s  psp 

remember  swappee' s  psp 

swappee  must  have  an  environment 


unless  the  -f  option  was  specified,  check  whether  vectors  point  at  swappee 
note:  only  interrupts  l-79h  (inclusive)  are  checked 


get_mcb_info  -  get  relevant  info  from  mcb  chain 


get_mcb_inf o : 
mov 
mov 
int 
mov 
mov 
mov 

mem_loop: 

mov 

mov 

mov 

mov 

mov 

inc 

cmp 

jle 

error 

mem_loopl : 

cmp 

jne 

error 

mem_next : 

mov 

inc 

cmp 

je 

add 

mov 

add 

jmp 

found_our_psp 

mov 

mov 

add 

mov 


my_psp, cs 
ah, 52h 
21h 

es,es: [bx]-2 
bx, offset  mcbs 
dx,  0 


remember  address  of  our  PSP 
undocumented  function 
get  base  of  memory  chain 
this  is  it 

count  of  MCBs 


[bx] .addr,es 

cx,word  ptr  es:l  ;  owner  of  mcb 

[bx] . owner, cx 
cx,word  ptr  es:3  ;  length  of  mcb 

[bx] .len,cx 

dx  ;  increment  count  of  MCBs 

dx,max_mcbs 
mem_loopl 

"Over  100  Memory  Control  Blocks  in  system" 


byte  ptr  es:0,'Z'  ;  . 

mem_next 

"Could  not  find  SWAP's  PSP' 


;  last  memory  block? 


vector_check : 

~  test  f 

jnz  v 

mov  c 

next_vector: 

inc  c 

cmp  c 

jae  v 

mov  a 

mov  a 

int  2 

mov  d 

push  c 

mov  c 

add  b 

shr  b 

pop  c 

add  d 

cmp  s 

jae  n 

jae  n 

error  " 

vector_check_ret : 
”  ret 


flag, flag_force 
vector_check_ret 
cx,  0 


cx,80h 

vector_check_ret 

ah, 35h 

al,cl 

21h 

dx,es 


dx,bx 

swappee_psp, dx 

next_vector 

dx, swappee_end 

next_vector 

"Swappee  has  hooked  an 


;  start  at  the  beginning 

;  next  vector 
;  all  done? 

;  yes,  no  vectors  hooked 
;  get  vector  function 
;  vector  number 

;  call  dos  to  get  vector  address 
;  get  segment  addr 

;  shift  count 
;  round  up 

;  divide  offset  by  16 

;  compute  segment 
;  compare  to  start  of  swappee 
;  no  problem,  keep  looking 
;  compare  to  end  of  swappee 
;  no  problem  either 
interrupt  vector" 


cx,my_psp 
found_our_psp 
cx, [bx] .len 
es,cx 

bx,mcb_length 

mem_loop 


mov  dx, [bx] .len 

mov  my_mcb_size,dx  ;  remem) 

add  cx, [bx].len  ;  add  1< 

mov  next_mcb,cx  ;  this  : 

remember  information  about  the  next  mcb 

mov  es,cx 

mov  dl,es:0 

mov  next_code,dl 

mov  dx,es:l 

mov  next_owner,dx 

mov  dx,es:3 

mov  next_size,dx 


;  copy  seg  addr  of  mcb 
;  next  paragraph 
;  is  this  our  psp? 

;  yes 

;  add  length  of  this  mcb 
;  this  is  next  memory  block 
;  where  next  mcb  goes 
;  proceed 

;  have  found  our  psp 


figure_pages  -  figure  how  many  16K  pages  of  EMS  we  need 


f igure_pages : 
mov 
dec 
mov 
mov 
sub 
mov 
shr 


remember  length  of  our  mcb 
add  length  of  memory 
this  is  next  memory  block 


cx, swappee_psp 
cx 

swappeejncb, cx 

dx, next_mcb 

dx,cx 

cx,  10 

dx,cl 

dx,  dx 

figure2 

"Less  than  16K  to  swap" 
dx 

swap_pages , dx 


cx  -  swappee' s  mcb 
remember  address  of  mcb 
dx  -  mcb  after  swap.com 
dx  -  difference  in  paragraphs 

convert  paragraphs  to  16k  pages 


init_ems  -  ensure  ems  is  up  to  par,  allocate  pages,  and  save  page  map 


check_mcbs  -  ensure  mcbs  are  in  expected  order 

verify  that  our  parent  is  command.com,  find  swappee  psp,  etc. 


init_ems : 

test  flag, flag_disk 

jz  find_emm 

jmp  init_ems_exit 

.  -  determine  whether  ems  is  installed 

find  emra: 


mov 

cx,cs:16h 

;  our  parent's  address 

mov 

es,  cx 

mov 

ax,es:16h 

;  and  our  grandparent's  address 

cmp 

ax,  cx 

;  better  be  equal 

jne 

unknown_parent 

mov 

ax,cs:10h 

;  our  ctrl-break  handler 

cmp 

ax,  cx 

;  better  equal  our  parent's  address 

je 

skip  our  env 

unknown _parent : 

error 

"SWAP  not  directly  run 

:rom  COMMAND.COM" 

. - back  up 

to  find  swappee' s  mcb. 

bx  still  points  at  entry  for  our  mcb  i 

skip  our  env: 

mov 

cx,cs 

call 

prev  mcb 

cmp 

[bx] .owner, cx 

;  is  this  mcb  for  our  environment? 

jne 

skip  command 

call 

prev  mcb 

; - back  up 

over  all  mcb's  owned  by 

command.com  (es  ==  command.com  psp) 

skip  command: 

mov 

cx,  es 

;  address  of  command.com  psp 

cmp 

[bx] .owner, cx 

;  is  this  mcb  owned  by  command.com? 

je 

command  loop 

;  yes 

error 

"COMMAND. COM  must  immediately  precede  SWAP  in  memory" 

command  loop: 

mov 

dx, [bx] .addr 

;  remember  address  of  mcb  in  case 

mov 

swappee  end,dx 

;  it  is  the  one  above  swappee 

call 

prev  mcb 

;  back  up  one  mcb 

cmp 

[bx] . owner,  cx 

;  is  this  mcb  owned  by  command.com? 

je 

command  loop 

;  yes,  skip  it 

; - assume  we  have  one  of  swappee' s 

mcbs 

;  back  up 

over  all  it's  mcb's  till  we  reach  psp 

mov 

cx, [bx] .owner 

;  cx  -  swappee' s  psp 

find  swappee_psp: 

mov 

dx, [bx] .addr 

;  address  of  this  mcb 

inc 

dx 

;  address  of  memory 

cmp 

dx,  cx 

;  is  this  swappee' s  psp? 

je 

found  swappee_psp 

;  yes 

call 

prev  mcb 

;  check  previous  psp 

cmp 

[bx] . owner, cx 

;  still  owned  by  swappee? 

mov 

ax, 3567h 

code  to  get  int  67  handler 

int 

21h 

get  interrupt  vector 

mov 

di,Oah  ; 

offset  to  name  string 

mov 

si, offset  ems  device  name 

;  correct  ems  name 

mov 

cx,  8 

length  of  name 

cld 

; 

scan  in  forward  direction 

repe 

cmpsb  s 

do  the  compare 

jz 

test_status  ; 

ems  not  loaded 

error  "Could  not  find  Expanded  Memory  Manager" 

. - test  ems  status 

test_status : 

mov  ah, 40h  ;  code  to  test  status 

call  emm 

jz  check_ems_version 

jmp  ems_error 

.  -  ensure  that  we  have  ems  version  3.2  or  later 

check_ems_version : 

mov  ah,46h  ;  get  version 

call  emm 

jz  got_ems_version 

jmp  ems_error 

got_ems_version : 

cmp  al,32h 

jnb  get_page_frame 

error  "Expanded  Memory  Manager  version  must  be  3.2  or  higher" 

; - get  page  frame  address 

get_page_f  rame : 


mov  ems_frame,bx 

jz  alloc_pages 

jmp  ems_error 

? - allocate  ems  pages 

alloc_pages: 

mov  ah,43h 

mov  bx, swap_pages 

call  emm 


;  code  to  get  page  frame  addr 
;  where  ems  memory  starts 


(continued  on  page  80) 
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SWAP 


Listing  One  (Listing  continued,  text  begins  on  page  44.) 

mov  ems_handl e , dx 

jz  save_page_map 

error  "Not  enough  free  expanded  memory" 

; - save  ems  page  map 

save_page_map : 

mov  ah, 47h  ;  save  page  map 

mov  dx, ems  handle 

call  emm 

jz  init_ems_exit 

jmp  ems_error 

init_ems_exit : 
ret 


mov  bx, swappee_psp 

add  bx,dx 

mov  es,bx 

fill  in  new  mcb 
mov  dx, next_mcb 

sub  dx, bx 

add  dx,next_size 

mov  word  ptr  es:3,dx 

mov  dl,next_code 

mov  byte  ptr  es:0,dl 

mov  word  ptr  es:l,0 


address  of  swappee's  psp 

add  paragraphs  in  swappee's  mcb 

this  is  where  mcb  for  free  mem  goes 

address  of  mcb  after  original  swap 

compute  paragraphs  of  free  space 

add  paragraphs  for  next  mcb 

fill  in  size 

get  id  from  next  mcb 

copy  id  (M  or  Z) 

mark  block  as  free 


swap_out  -  swap  out  swappee,  command.com,  and  curself 


mov 

es, swappee_mcb 

test 

flag,  f .Lag_disk 

;  swap  to  disk? 

jnz 

swap  out  disk 

;  yes 

-  swap  out  to  expanded  memory 

mov 

cx,  0 

cld 

out_page : 

;  loop  to  swap  16K 

mov 

bx,  cx 

;  logical  page  *  loop  count 

call 

map_page 

mov 

bx, ems_frame 

assume 

ds: nothing 

push 

es 

pop 

ds 

;  ds  -  where  to  swap  from 

mov 

es,bx 

;  es  -  ems_frame 

mov 

si,  0 

mov 

di,  0 

push 

cx 

mov 

cx, 4000h 

;  copy  16K 

rep 

movsb 

pop 

cx 

mov 

bx,ds 

;  where  to  swap  from 

add 

bx, 400h 

;  add  16K 

mov 

es,bx 

;  es  -  next  place  to  swap  from 

push 

cs 

pop 

ds 

assume 

ds : code 

inc 

cx 

cmp 

cx, swap_pages 

;  done  swapping? 

jl 

swap_out_page 

;  no,  swap  the  next  page 

ret 

—  swap  out  to  disk 

_out_disk: 

;  es  -  swappee' s  mcb 

mov 

cx,0 

;  attribute 

mov 

dx, offset  swap_fid 

mov 

ah, 3ch 

;  dos  function  -  create  a  file 

int 

21h 

jnc 

c reate _done 

error 

"Could  not  create  swap 

file" 

e_done : 

mov 

swap  handle, ax 

mov 

cx,  0 

;  number  of  pages  swapped 

_out_disk_page : 

;  loop  to  swap  16K 

push 

cx 

;  remember  number  pages  swapped 

mov 

bx,  swap_handle 

;  handle  to  write  to 

mov 

cx, 04000h 

;  write  16k 

xor 

dx,  dx 

;  offset  to  write  from 

push 

ds 

push 

es 

pop 

ds 

;  segment  to  write  from 

mov 

ah, 40h 

;  dos  function  -  write  to  handle 

int 

21h 

pop 

ds 

jnc 

write_workedl 

error 

"Error  writing  to  swap 

file" 

_workedl : 

mov 

bx,es 

;  where  to  swap  from 

add 

bx, 400h 

;  add  16K 

mov 

es,bx 

;  es  =  next  place  to  swap  from 

pop 

cx 

;  remember  number  of  pages  swapped 

inc 

cx 

;  now  we've  swapped  one  more  page 

cmp 

cx, swap_pages 

;  done  swapping? 

jl 

swap_out  disk_page 

;  no,  swap  the  next  page 

call 

close  swap  file 

ret 

;  run_user_command  -  call  run_command  routine  in  low  memory 
run_user_command : 

>  -  put  swappee  segment  address  into  pointer  to  run_command 

mov  bx, swappee_psp 

mov  word  ptr  run_seg,bx  ;  segment  of  swappee  psp 

?  -  set  pid  to  address  of  swappee  psp 

mov  ah,  5 Oh  ;  dos  function  =»  set  pic 

int  21h  ;  set  process  id 

;  -  call  run_command  in  low  memory 

mov  ds,bx 

assume  ds: nothing 

call  dword  ptr  cs:run_addr  ;  call  run_command 

mov  ds,cs:my_psp 

assume  ds:code 

;  -  restore  pid  to  SWAP's  psp 

mov  bx, cs  ;  pid  =  my  cs  register 

mov  ah,50h  ;  code  to  set  pid 

int  21h 

ret 


dos  function  -  set  pid 
set  process  id 


call  run  command 


pid  =  my  cs  register 
code  to  set  pid 


swap_first  -  swap  in  first  page  that  was  swapped  out 


swap_first: 

mov 

test 

jnz 


es,  swappee_mcb 
flag, flag_disk 
swap_first_disk 
from  expanded  memory 


;  swapping  in  from  disk? 
;  yes 


mov 

bx,  0 

;  logical  page  -  0 

call 

map_page 

push 

ds 

;  save  ds 

mov 

ds,ems_frame 

;  ds  =  where  to  swap 

mov 

si,0 

mov 

di,  0 

mov 

cld 

cx, 4000h 

;  copy  16K 

rep 

movsb 

pop 

ret 

ds 

;  restore  ds 

swap  in 

from  disk 

rst_disk 

call 

open_swap_file 

call 

read_swap_file 

call 

close_swap_file 

clean_up  -  restore  ems  or  delete  swap  file 


clean_up: 

test 


test  flag,  flag_disk 

jnz  clean_up_disk 

restore  ems  page  map 


mov  ah, 48h 

mov  dx, ems 

call  emm 

jz  deallo< 

jmp  ems_er: 

; - deallocate  the 

deallocate: 

mov  ah,45h 


ah, 48h 

dx, ems_handle 
emm 

deallocate 

ems_error 

ite  the  ems  pages 


ah, 45h 

mov  dx,ems_handle 

call  emm 

jz  clean_up_exit 

jmp  ems_error 

;  -  delete  swap  disk  file 

clean_up_disk : 

mov  dx, offset  swap_fid 

mov  ah,41h 

int  21h 

clean_up_exit : 
ret 


;  muck_with_memory  -  copy  part  of  SWAP  over  swappee's  psp,  set  up  mcbs,  etc 

muck_with_memory : 

mov  es, swappee_psp 

;  -  copy  code  over  swappee's  psp 

cld  ;  copy  in  forward  direction 

mov  cx, offset  lowend  ;  length  of  code  to  copy 

mov  si,100h  ;  start  copying  after  psp 

mov  di,100h  ;  where  to  copy 

rep  movsb  ;  copy  code  over  swappee' s  psp 


restore  page  map 


deallocate  pages 


file  handle  for  swap  file 
code  to  delete  a  file 


cld  ;  copy  in  forward  direction 

mov  cx, offset  lowend  ;  length  of  code  to  copy 

mov  si,100h  ;  start  copying  after  psp 

mov  di,100h  ;  where  to  copy 

rep  movsb  ;  copy  code  over  swappee' s  psp 

copy  our  file  handle  array  down  to  swappee' s  psp 

mov  cx,20  ;  length  of  file  handle  table 

mov  si,18h  ;  address  of  our  file  handle  table 

mov  di,18h  ;  where  to  put  file  handle  table 

rep  movsb  ;  copy  file  handle  table  to  swappee  psp 

set  the  file  handle  array  size  and  offset  in  swappee's  psp 

mov  word  ptr  es:32h, 20  ;  length  of  file  handle  table 

mov  word  ptr  es:34h,18h  ;  offset  of  file  handle  table 

mov  word  ptr  es:36h,es  ;  segment  of  file  handle  table 

now  fix  up  the  swappee's  mcb  (still  has  an  M) 

mov  es, swappee_mcb  ;  address  of  swappee's  mcb 

mov  dx, offset  lowend+15  ;  offset  to  end  of  SWAP  code 

mov  cx, 4 

shr  dx, cl  ;  convert  to  paragraphs 

mov  word  ptr  es:3,dx  ;  put  result  in  swappee's  mcb 

find  address  of  mcb  for  memory  that  was  freed  up 


prev_mcb  -  back  up  one  entry  in  table  of  MCBs 


prev_mcb: 

sub  bx,mcb_length 

cmp  bx, offset  mcbs 

jae  prev_mcb_ret 

error  "Memory  Control  Blocks  not  in  expected  order" 

prev_mcb_ret : 
ret 


endcode  equ  $ 

align  16 
db  16  dup(O) 

swap  endp 

code  ends 

end  swap 


;  so  that  at  least  on  mcb  follows  swap 


End  listings 
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MEMORY  COMPACTION 


Listing  One  (Text  begins  on  page  50.) 


Listing  Two 


/ *  *  *  *  mem . h 

S.  Peterson 

*/ 

typedef  unsigned  char 
typedef  unsigned  int 


data  structures  for  memory  manager 
programmer  12/88 

byte; 

uint; 


/*  This  structure  is  the  header  of  a  memory  block.  It  lies  before 
the  actual  memory  block.  */ 
struct  memBlkHdr  ( 

char 
byte 
byte 

struct  memBlkHdr 
uint 
int 
void 

}  ; 

typedef  struct  memBlkHdr  MEMBLK; 

/*  These  are  the  definitions  of  each  of  the  flags  in  the  flags  byte 
of  memBlkHdr.  */ 


♦define 

BLK 

INUSE 

0x01 

/* 

Block 

is  allocated  */ 

♦define 

BLK' 

'DELETABLE 

0x02 

/* 

Block 

can  be  deleted  *, 

♦define 

blk' 

"locked 

0x04 

/* 

Block 

is  locked  */ 

♦define 

BLK' 

'funcdelete 

0x08 

/* 

Call 

block  function  on 

delete  */ 

♦define 

blk" 

"funcmove 

0x10 

/* 

Call 

block  function  on 

move  */ 

♦define 

blk' 

'deleted 

0x20 

/* 

Block 

has  been  deleted 

*/ 

♦define 

blk' 

'last 

0x40 

/* 

Last 

block  in  segment  1 

7 

/*  freePtr  is  stored  at  the  beginning  of  the  user  part  of  a 

free  block.  It  contains  the  links  to  next  and  previous  free  blocks 
in  the  segment,  prev  is  NULL  if  this  is  the  first  free  block,  and 
next  is  NULL  if  this  is  the  last  block  */ 


checkByte;  /*  Header  validation  */ 
flags;  /*  Flags  (see  below)  */ 
segment;/*  Segment  of  this  block  */ 
*prev;  /*  Pointer-previous  block  */ 
size;  /*  size  of  block  */ 
pointerNum;  /*  Block  master  pointer  */ 
(*func) (void  *,  byte,  uint,  void  *); 


struct  freePtr  ( 

MEMBLK  *prev;  /*  Pointer  to  previous  free  block  */ 
MEMBLK  *next;  /*  Pointer  to  next  free  block  */ 


typedef  struct  freePtr  FREEBLK; 

/*  Macro  to  return  address  of  data  area  give  block  header  address  */ 

♦define  DATALOC(xx)  ((byte  *)  (xx)  +  sizeof (MEMBLK) ) 

/*  Macro  to  return  address  of  header  given  data  area  address  */ 
♦define  HEADERLOC (xx)  ((byte  *)  (xx)  -  sizeof (MEMBLK) ) 

/*  This  is  an  entry  in  the  master  block  table.  */ 


struct 


masterSegmentEntry  ( 
void 
uint 
uint 

struct  memBlkHdr 
struct  memBlkHdr 


♦block;  /*  Address,  associated  block  */ 
size;  /*  Size  of  block  */ 
freeSpace;  /*  Amount  of  free  space  */ 
♦free;  /*  First  free  block  */ 

♦last;  /*  Last  reference  free  block  */ 


♦define  DEFSEGSIZE  4096  /*  Default  segment  size  */ 

♦define  CB  'S' 

/*  MINREMAINDER  is  the  smallest  free  block  that  can  remain  after 

allocation.  Making  this  larger  reduces  fragmentation  but  wastes 
more  space.  */ 

♦define  MINREMAINDER  20 

/*  MINBLOCKDATA  is  the  smallest  block  data  area  that  can  be  created.  This 

must  be  at  least  sizeof (FREEBLK)  bytes  so  there  is  space  for  the 
next  and  prev  pointers  stored  in  a  free  block.  ♦/ 

♦define  MINBLOCKDATA  (sizeof (FREEBLK) ) 

/*  Function  prototypes  */ 

♦ifndef  NOPROTO 

int  MemInit(long  int,  int); 

int  MemLocked(void  **); 

void  MemLock(void  **); 

void  MemUnlock (void  **); 

void  MemDeletable (void  **); 

void  MemUndeletable (void  **); 
int  MemDeleted(void  **); 

void  **MemAlloc (uint) ; 

void  **MemAllocFunc (uint, void  (*) (void  *,byte,  uint,  void  *),  uint); 

void  MemFree(void  **); 

uint  MemGetLargest (void) ; 

uint  MemGetCurrentLargest (void) ; 

void  MemCompact (void) ; 

♦endif 


End  Listing  One 


/*♦*♦♦  mem.c  Compact ible  memory  manager 

S.  Peterson  programmer  12/88,  1/89 

This  module  provides  a  memory  management  system  with  the  following 
features : 

Relocatable  memory  blocks 
.  Able  to  collapse  fragemented  free  space 

Disposable  blocks 
.  Lockable  blocks 


♦include 

♦include 

♦include 

♦include 

♦include 

♦include 

♦include 

♦include 


<stdio.h> 

<stddef .h> 

<malloc.h> 

<string.h> 

<process.h> 

<stdlib.h> 

<conio.h> 

"mem.h" 


/*  Static  module  data  */ 


struct  masterSegmentEntry  *mst  =  NULL;  /*  Master  segment  table  */ 


byte 

numSegs 

=  -1; 

/*  Number  of  whole  &  partial  segments  */ 

byte 

lastSeg 

-  -1; 

/*  Index  of  last  segment  used  */ 

void 

**mpt 

-  NULL; 

/*  Master  pointer  table  */ 

int 

numMP 

-  -1; 

/*  Number  of  master  pointers  allocated  */ 

int 

mpFree 

=  -1; 

/*  Number  of  master  pointers  free  */ 

int 

lastMP 

=  -1; 

/*  Last  master  pointer  used  */ 

/*  Local  function  declarations  */ 


♦ifndef  NOPROTO 


static  int 
static  int 
static  int 
static  void 
static  void 

♦endif 


FindFreeBlock (int,  uint,  void  **); 
AllocBlock (uint,  void  **,  byte); 
GetFreeMP (void) ; 

ReleaseMP (int) ; 

CompactSeg(byte,  uint,  int); 


/** 


Memlnit 

Entry 

Exit 

Returns 


—  initalize  memory  manager 

ISize  size  of  requested  memory  in  bytes 

nHandles  number  of  block  handles  to  allocate 

none 


TRUE  worked 

FALSE  failed 


**/ 

int 

Memlnit (ISize,  nHandles) 
long  int  ISize; 

int  nHandles; 


( 


byte 

numWhole; 

/* 

Number  of  whole  segments  to  create  */ 

uint 

numBytes; 

/* 

Size  of  partial  segment  */ 

uint 

createSize; 

/* 

Size  to  create  */ 

MEMBLK 

♦mbh; 

/* 

Work  block  header  */ 

int 

i; 

/* 

Work  */ 

FREEBLK 

*f; 

/* 

Free  links  */ 

/*  Allocate  handle  list  */ 


if  ( (mpt  =  (void  **)  malloc (sizeof (void  *) *nHandles) )  ==  NULL) 
return  FALSE; 

numMP  =  nHandles; 

for  (i  =  0;  i  <  numMP;  mpt(i]  =  NULL,  i++)  ; 
mpFree  =  numMP; 
lastMP  =  0; 

/*  Determine  size  of  segments  to  create  */ 

numWhole  =  (byte)  (ISize  /  (long)  DEFSEGSIZE); 
numBytes  =  (uint)  (ISize  %  (long)  DEFSEGSIZE); 
numSegs  =  numWhole  +  1; 
lastSeg  =  0; 

if  ( (mst  =  (struct  masterSegmentEntry  *)  malloc (sizeof 

(struct  masterSegmentEntry) * (numSegs) ) )  ==  NULL) 
return  FALSE; 

/*  Allocate  segments  */ 

for(i  =  0;  i  <  numSegs;  i++)  { 

if  (i  ==  numSegs  -  2)  (  /*  Second  to  last  */ 

if  (numBytes  <  DEFSEGSIZE  /  4)  (  /*  Last  is  small  */ 

numBytes  +=  DEFSEGSIZE  /  4; 
createSize  =  DEFSEGSIZE  -  (DEFSEGSIZE  /  4) ; 

}  else  ( 

createSize  =  DEFSEGSIZE; 

) 

)  else  if  (i  ==  numSegs  -  1)  (  /*  Last  */ 

createSize  =  numBytes; 

)  else  (  /*  Whole  segment  */ 

createSize  =  DEFSEGSIZE; 

) 

if  (createSize  <  sizeof (MEMBLK)  +  10) 
return  FALSE; 

if  ( (mst [i] .block  =  (void  *)  malloc (createSize) )  ==  NULL) 
return  FALSE; 
mstfij.size  =  createSize; 
mst [i] . freeSpace  =  createSize; 


/*  Allocate  one  block  in  segment  */ 
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mbh 

mst [i] . free 
mst  [i] .last 


=  (MEMBLK  *)  mst [i] .block; 
=  mbh; 

=  mbh; 


mbh->checkByte 

mbh->prev 

mbh->flags 

mbh->size 

mbh->segment 


=  CB; 

=  NULL; 

=  BLK_LAST; 

=  mst[i] .size, 
=  (byte)  i; 


/*  Clear  next  and  prev  pointer  area  */ 


f  =  (FREEBLK  *)  DATALOC (mbh) ; 
f->prev  =  NULL; 
f->next  =  NULL; 


return  TRUE; 


/“  MemLocked  —  test  whether  a  block  is  locked 

Entry  block  address  of  a  block 

Exit  none 

Returns  TRUE  block  is  locked 

FALSE  not  locked 

“/ 

int 

MemLocked (block) 
void  “block; 

( 

return  !(( (MEMBLK  *)  HEADERLOC (‘block) ) ->f lags  4  BLK  LOCKED); 

) 


Listing  Two  ( Listing  continued,  text  begins  on  page  50.) 

Possible  enhancement:  if  no  segment  has  enough  room,  shuffle 
blocks  between  segments. 

If  there  is  not  enough  room  in  any  segment,  the  function 
fails. 

“/ 


void 

** 

MemAlloc (size) 

uint 

size; 

( 

byte 

curSeg; 

/*  Current  segment  */ 

byte 

seglndex; 

/*  Index  of  segment  in  list  */ 

long 

ItotalFree 

=01;  /*  Total  free  space  */ 

byte 

maxFreeSeg 

=  255;  /*  Segment,  most  free  space  */ 

uint 

maxFreeSize 

=  0;  /*  Segment  space,  most  space  */ 

MEMBLK 

*b; 

/*  Block  address  to  allocate  */ 

int 

created 

=  FALSE;  /*  Block  created  */ 

int 

mp; 

/*  Master  pointer  */ 

if  ( (mp  ■ 

GetFreeMPO)  <  0) 

return  NULL; 


if  (size  >  DEFSEGSIZE  -  sizeof (MEMBLK) ) 
return  NULL; 

if  (size  <  MINBLOCKDATA)  /*  Smallest  allocatable  block  */ 

size  =  MINBLOCKDATA; 

size  +=  sizeof (MEMBLK) ;  /*  Add  header  to  block  */ 

/*  First  pass  —  try  to  allocate  from  current  block  structure  */ 


/** 

MemLock 

—  locks  a  block  into  a  particular  location  in 

Entry  block 
Exit  none 

address  of  block  to  lock 

“/ 

void 

Returns  void 

MemLock (block) 

void 

( 

“block; 

i 

) 

((MEMBLK  *)  HEADERLOC ( ‘block ))->f lags  1=  BLK_LOCKED; 

/“ 

MemUnlock 

—  unlocks  a  block 

Entry  block 
Exit  none 

address  of  block  to  unlock 

Returns  void 

“/ 

void 

MemUnlock (block) 

void 

“block; 

) 

((MEMBLK  *)  HEADERLOC ( ‘block) )->f lags  4=  BLK_LOCKED; 

/** 

MemDeletable 

—  make  a  block  deletable 

Entry  block 
Exit  none 
Returns  void 

address  of  block  to  mark  as  deletable 

“/ 

void 

MemDeletable (block) 

void 

“block; 

) 

((MEMBLK  *)  HEADERLOC ( ‘block) )->f lags  |=  BLK_DELETABLE ; 

/“ 

MemUndeletable 

—  mark  a  block  as  undeletable 

Entry  block 
Exit  none 

address  of  block  to  mark 

Returns  void 

*  t  j 

void 

MemUndeletable (block) 

void 

“block; 

} 

((MEMBLK  *)  HEADERLOC ( ‘block ))-> flags  4=  BLK_LOCKED; 

y** 

MemlsDeleted 

—  test  whether  a  block  has  been  deleted 

Entry  block 
Exit  none 

address  of  a  block 

Returns  TRUE 

block  is  available 

**  / 

FALSE 

has  been  deleted 

int 

MemDeleted (block) 

void 

“block; 

{ 

return  ({(MEMBLK  *)  HEADERLOC (‘block) ) ->f lags  4  BLK_DELETED)  !=  0; 


/“  MemAlloc  —  allocate  memory  block 

Entry  size  size  of  block  to  allocate 

Exit  none 

Returns  pointer  to  created  block,  or  NULL  if  not  enough  room  to  create 
Notes  The  function  operates  by  first  examining  the  current  segment 
for  a  first  fit  to  the  requested  size.  It  then  proceeds  to 
the  remaining  blocks  looking  for  a  free  block  of  adequate 
size. 

If  no  block  exists  that  is  large  enough,  it  examines  the 
segment  list  looking  for  a  segment  that  can  be  compacted 
to  produce  enough  room.  The  segment  with  the  fewest 
allocated  blocks  is  favored  for  compaction. 


for  (seglndex  =  0;  (seglndex  <  numSegs)  44  (lereated);  seglndex++)  ( 
curSeg  =  (lastSeg  +  seglndex)  %  numSegs; 

/*  Get  stats  */ 

ItotalFree  +=  (long)  mst [curSeg] . freeSpace; 

/*  Is  there  enough  space  in  the  current  segment  to  allocate?  */ 

if  (mst [curSeg] .freeSpace  >=  size)  ( 

if  (maxFreeSize  <  mst [curSeg] . freeSpace)  { 

maxFreeSize  -  mst [curSeg] . freeSpace; 

maxFreeSeg  =  curSeg; 

} 


/* 

if 


} 


Search  free  list  for  first  fit  */ 
(FindFreeBlock (curSeg,  size,  4b))  { 

/*  Allocate  */ 

if  (! (created  ■  AllocBlock (size, 
return  FALSE; 


4b,  curSeg))) 


/*  Which  segment  could  be  compacted  to  create  a  block  large  enough? 

We  kept  track  of  the  segment  with  the  most  free  space.  This  should 
compact  easily.  */ 

if  (lereated  44  (maxFreeSeg  !-  255))  { 

/*  Compact  to  produce  needed  free  space  */ 


curSeg  =  maxFreeSeg; 

CompactSeg (curSeg,  size,  FALSE); 


if  (! FindFreeBlock (curSeg,  size,  4b))  [ 
CompactSeg (curSeg,  size,  TRUE); 


) 


if 


(! FindFreeBlock (curSeg, 
return  NULL; 


size, 


&b)) 


I 


if  (! (created  =  AllocBlock (size,  4b,  curSeg))) 
return  FALSE; 


if  (created)  ( 

mst [curSeg] . freeSpace  -=  b->size; 
mpt [mp]  =  DATALOC (b); 

b->pointerNum  =  mp; 

b->func  =  NULL; 

lastSeg  =  curSeg; 

return  (void  *)  4{mpt[mp]); 

}  else  ( 

ReleaseMP (mp) ; 
return  NULL; 


/“ 


MemAllocFunc 
Entry  size 
func 
flags 


—  allocate  a  memory  block  with  an  associated  function 
size  of  block  to  allocate 
function  to  call 
following  constants: 

BLK_FUNCDELETE  call  function  when  block  deleted 
BLK  FUNMOVE  call  function  when  block  moved 


Exit  none 

Returns  pointer  to  allocated  block,  or  NULL  if  no  space  available 
Notes  Calls  memAlloc  to  allocate  memory 


“/ 

void  “ 

MemAllocFunc (size,  func,  flags) 
uint  size; 

void  (*func) (void  *,  byte,  uint,  void  *); 

uint  flags; 
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/*  Allocated  block  */ 

/*  Dereferenced  block  header  */ 


if  ( (aBlock  *  MemAlloc (size) )  !=  NULL)  { 
b  =  (MEMBLK  *)  HEADERLOC (*aBlock) ; 
b->flags  |-  flags  &  (BLK_FUNCMOVE  | 
b->func  -  func; 
return  aBlock; 

)  else  { 

return  NULL; 


BLK  FUNCDELETE) ; 


Listing  Two  (Listing  continued,  text  begins  on  page  50.) 

mst (segment] . last  =  curFree->next; 

)  else  if  (curFree->prev  !=  NULL)  ( 

t  =  (FREEBLK  *)  DATALOC (curFree->prev) ; 

t->next  =  curFree->next; 

mst (segment] . last  =  curFree->prev; 

)  else  (  /*  No  free  block  */ 

mst (segment] .last  =  NULL; 
mst [segment] . free  =  NULL; 


/**  FindFreeBlock  —  locate  a  free  block  in  a  segment 
Entry  seg  segment  to  search 

size  bytes  required  for  block  including  header 

Exit  b  address  of  block  header  (if  found) 

Returns  TRUE  block  found 

FALSE  no  space 

Notes  Finds  a  free  block  in  the  current  segment.  Starts 

with  the  last-referenced  free  block  in  the  segment.  This 
spreads  the  allocations  through  the  segment  and  combats 
fragmentation. 

The  caller  can  save  some  time  by  first  checking  to  see  if 
the  segment  has  enough  free  space  to  allocate  the  block. 
This  algorithm  uses  the  first-fit  method,  which  is  fast  but 
promotes  fragmentation. 

“/ 

static  int 

FindFreeBlock (seg,  size,  b) 
int  seg; 

uint  size; 

void  **b; 


Current  memory  block  */ 


!  mst [seg] .last; 


=  NULL)  { 

while  (m->size  <  size)  { 

if  ((m  =  ((FREEBLK  *)  DATALOC (m) ) ->next) 
/*  End  of  free  list  */ 
m  -  mst (seg) .free; 


=  mst [seg] .last) 
break; 


if  (m->size  <  size)  { 
*b  -  NULL; 
return  FALSE; 

)  else  ( 

*b  ■  m; 
return  TRUE; 


*b  =  NULL; 
return  FALSE; 


/*  No  block  large  enough  */ 


/*  Block  found  */ 


/*  No  block  */ 


{  /*  Block  will  be  split  */ 

aBlock  =  (MEMBLK  *)  ((byte  *)  freeBlock  + 

(freeBlock->size  -  size)); 

aBlock->checkByte  =  CB; 

aBlock->prev  =  freeBlock; 

aBlock->flags  =  BLK_ INUSE; 

aBlock->size  =  size; 

aBlock->segment  =  segment; 

freeBlock->size  -=  size; 

/*  Is  block  last  in  segment?  */ 

if  ( (freeBlock->f lags  &  BLK_LAST)  !=  0)  ( 

freeBlock->flags  &=  BLK_LAST; 

aBlock->flags  |=  BLK_LAST; 

)  else  ( 

nextBlock  =  (MEMBLK  *)  ((byte  *)  aBlock  +  (aBlock->size) ) ; 
nextBlock->prev  =  aBlock; 


*b  =  aBlock; 
return  TRUE; 


GetFreeMP  —  return  next  free  master  pointer 

Entry  none 
Exit  none 

Returns  index  of  next  free  master  pointer 


static  int 
GetFreeMP () 


if  (mpFree  ==  0) 

return  -1; 

for  (i  =0;  i  <  numMP;  i++,  lastMP++)  ( 
if  (lastMP  >*  numMP) 
lastMP  =  0; 

if  (mpt [lastMP]  ==  0)  ( 
mpFree — ; 
return  lastMP; 


AllocBlock  —  allocate  a  block 

Entry  size  size  of  block  (including  header)  to  allocate 

b  address  of  block  where  it  will  be  allocated 

Exit  b  Address  of  allocated  block  header  (this  is 

different  that  the  b  input  parameter) 

Returns  TRUE  allocated 

FALSE  memory  structure  corrupt 

Notes  This  function  takes  a  block  and  splits  it  in  two.  If  the 

remaining  free  block  is  small,  the  entire  block  is  allocated 
and  no  free  portion  is  created.  This  can  waste  some  memory, 
but  avoids  extreme  fragmentation. 


ReleaseMP 
Entry  mp 
Exit  none 
Returns  void 


static  void 
ReleaseMP (mp) 
int  mp; 

( 


—  release  a  master  pointer  to  free  pool 
master  pointer  to  release 


mpFree++; 
mpt[mp]  =  NULL; 


static  int 
AllocBlock (size, 
uint  size; 

void  “b; 

byte  segment; 


MEMBLK  ‘freeBlock; 
MEMBLK  ‘nextBlock; 
MEMBLK  ‘aBlock; 
FREEBLK  ‘curFree; 
FREEBLK  *t; 


/*  Free  block  */ 

/*  Next  block  */ 

/*  Allocated  block  */ 

/*  Free  pointers  in  block  we  are  allocating  */ 
/*  Pointer  to  free  block  we  are  adjusting  */ 


freeBlock  =  (MEMBLK  *)  *b; 

if  ( (freeBlock->size  -  MINREMAINDER  <  size))  ( 


/*  Whole  block  will  be  allocated  */ 


aBlock->flags 


=  freeBlock; 

=  aBlock->size; 
|=  BLK  INUSE; 


curFree  =  (FREEBLK  *)  DATALOC (aBlock) ; 

if  (mst [segment] .free  ==  aBlock)  [ 

/*  Implicit:  aBlock  is  first  in  list  */ 
mst [segment] . free  =  curFree->next; 


if  (curFree->next  !=  NULL)  { 

L  =  (FREEBLK  *)  DATALOC (curFree->next) ; 
t->prev  =  curFree->prev; 


/“  MemFree  —  free  a  block  of  memory 

Entry  blockPtr  pointer  to  mpt  entry  for  block 

Exit  none 
Returns  none 

“/ 

void 

MemFree (blockPtr) 
void  “blockPtr; 

( 

MEMBLK  *cur;  /*  Actual  block  */ 

FREEBLK  ‘curFree;  /*  Free  block  in  current  block  */ 

MEMBLK  ‘workMem;  /*  Work  block  in  memory  */ 

FREEBLK  ‘workFree;  /*  Work  block  in  next  block  */ 


combined  =  FALSE;  /*  Has  been  combined  */ 

=  (MEMBLK  *)  HEADERLOC (‘blockPtr) ; 


if  (cur->checkByte  !=  CB) 
return; 


ReleaseMP (cur->pointerNum) ; 


/*  blockPtr  no  longer  valid  */ 


curFree  =  (FREEBLK  *)  DATALOC (cur) ; 

/*  Mark  block  as  unallocated  */ 

cur->f lags  &=  BLK_INUSE; 

mst [cur->segment] . freeSpace  +=  cur->size; 

/*  Combine  with  subsequent  block?  */ 

if  ( (cur->flags  &  BLK_LAST)  ==  0)  [ 

workMem  =  (MEMBLK  *)  ((byte  *)  cur  +  cur->size) ; 
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if  ( (workMem->flags  &  BLK_INUSE)  ==  0)  {  /*  unallocated  */ 

combined  =  TRUE; 

if  ( (workMem->flags  &  BLK_LAST)  !=  0) 
cur-> flags  |=  BLK_LAST; 

workFree  =  (FREEBLK  *)  DATALOC (workMem) ; 
curFree->next  =  workFree->next; 
curFree->prev  =  workFree->prev; 
cur->size  +=  workMem->size; 

/*  New  top  of  free  list?  */ 

if  (workMem  ==  mst [cur->segment] . f ree) 
mst[cur->segment J .free  =  cur; 


curFree->next  =  mst [cur->segment] . free; 

if  (mst [cur->segment] .free  !=  NULL)  ( 
workFree= (FREEBLK  *)  DATALOC (mst [cur->segment] . free) ; 
workFree->prev  =  cur; 

) 

mst [cur->segment] . free  =  cur; 

) 

} 

if  (mst [cur->segment] .last  ==  NULL)  ( 
mst [cur->segment] .last  =  cur; 
mst [cur->segmentj .free  =  cur; 

} 


if  (workMem  ==  mst [cur->segment] . last) 
mst [cur->segment] . last  =  cur; 

/*  Adjust  pointers  in  free  chain.  Point  to  new  block  */ 


if  (curFree-:>next  !-  NULL)  ( 

workFree  =  (FREEBLK  *)  DATALOC (curFree->next) ; 
workFree->prev  =  cur; 

I 

if  (curFree->prev  !=  NULL)  ( 

workFree  =  (FREEBLK  *)  DATALOC (curFree->prev) ; 
workFree->next  =  cur; 

) 


/*  Adjust  previous  block  chain  */ 

if  ( (cur->flags  &  BLK_LAST)  ==  0)  ( 

workMem  =  (MEMBLK  *)  ((byte  *)  workMem  + 

workMem->size) ; 

workMem->prev  =  cur; 


/**  MemGetLargest  —  returns  size  of  largest  block  available  after 
compaction 

Entry  none 
Exit  none 

Returns  Free  space  in  segment  with  most  free  space,  less  the  size  of 
one  block  header. 


uint 

MemGetLargest () 
( 


byte  seg;  /*  Current  segment  */ 

uint  largest  =  0;  /*  Free  space  */ 


for  (seg  =  0;  seg  <  numSegs;  seg++) 

if  (largest  <  mst [seg] . f reeSpace) 

largest  =  mst [seg] . f reeSpace; 
if  (largest  <  sizeof (MEMBLK) ) 
return  0; 

else 

return  largest  -  sizeof (MEMBLK) ; 


) 


/*  Combine  with  previous  block?  */ 

if  (cur->prev  !=  NULL)  ( 

workMem  =  cur->prev; 

if  ( (workMem->flags  &  BLK_INUSE)  ==  0)  (  /*  unallocated  */ 
workMem->size  +=  cur->size; 

if  ( (cur->flags  &  BLK_LAST)  !«  0) 

workMem->f lags  |*  BLK_LAST; 
cur->checkByte  -  ' \0' ; 

if  (combined)  ( 

/*  Eliminate  free  block  from  links  */ 


/**  MemGetCur rent Largest  —  returns  size  of  largest  available  block 

Entry  none 
Exit  none 

Returns  size  of  largest  available  block 


**/ 

uint 

MemGetCurrentLargest () 

( 

byte  seg; 

MEMBLK  *curBlock; 
FREEBLK  *curFree; 
uint  largest  =  0; 


/*  Current  segment  */ 

/*  Current  block  */ 

/*  Current  free  block  */ 
/*  Largest  block  found  */ 


for  (seg  =  0;  seg  <  numSegs;  seg++)  { 
curBlock  =  mst [seg] . free; 
while  (curBlock  !=  NULL)  [ 

if  (curBlock->size  >  largest)  ( 

largest  =  curBlock->size; 

} 


workFree  =  (FREEBLK  *)  DATALOC (workMem) ; 
workFree->next  =  curFree->next; 

if  (workFree->next  !=  NULL)  [ 
workFree  =  (FREEBLK  *) 

DATALOC (workFree->next) ; 
workFree->prev  =  workMem; 


}  else  { 


curFree  =  (FREEBLK  *)  DATALOC (curBlock) ; 
curBlock  =  curFree->next; 

I 

) 

if  (largest  <  sizeof (MEMBLK) ) 
return  0; 

else 

return  largest  -  sizeof (MEMBLK); 


/*  Free  block  already  linked  */ 
combined  -  TRUE; 


/*  Connect  block  chain  */ 

if  ( (cur->flags  &  BLK_LAST )  ==  0)  ( 

workMem  =  (MEMBLK  *)  ((byte  *)  cur  +  cur->size) ; 
workMem->prev  =  cur->prev; 


/**  MemCompact  —  invoke  compaction  routine 

Entry  none 
Exit  none 
Returns  none 

**/ 

void 

MemCompact () 

{ 

byte  seg; 

for  (seg  -  0;  seg  <  numSegs;  seg++)  [ 

CompactSeg (seg,  DEFSEGSIZE,  FALSE); 


if  (cur  ==  mst [cur->segment] . free) 

mst [cur->segment] . free  =  workMem; 


if  (cur  ==  mst [cur->segment] .last) 

mst [cur->segment] .last  =  workMem; 

) 

} 

/*  If  not  combined,  link  into  free  chain  */ 
if  (! combined)  { 

/*  We  scan  backwards  looking  for  the  last  block  that 
is  free  */ 

workMem  =  cur->prev; 

while  ((workMem  !=  NULL)  &&  ( (workMem->flags  S 

BLK_INUSE)  !=  0))  { 

workMem  =  workMem->prev; 

) 

/*  A  block  is  prior  to  the  free  block  in  memory  */ 

if  (workMem  !=  NULL)  [ 

workFree  =  (FREEBLK  *)  DATALOC (workMem) ; 
curFree->prev  =  workMem; 
curFree->next  =  workFree->next; 
workFree->next  =  cur; 

if  (curFree->next  !=  NULL)  { 

workFree  =  (FREEBLK  *)  DATALOC (curFree->next) ; 
workFree->prev  =  cur; 

] 

)  else  [  /*  Place  at  beginning  of  list  */ 

curFree->prev  =  NULL; 


/**  CompactSeg  —  compact  a  segment 

Entry  seg  segment  to  compact 

size  desired  free  block  size 

deletable  TRUE  if  deletable  segments  should  be  deleted 

FALSE  otherwise 

Exit  none 
Returns  none 

**/ 

static  void 

CompactSeg (seg,  size,  deletable) 
byte  seg; 

uint  size; 

int  deletable; 

{ 

MEMBLK  ‘copyLoc  =  NULL; 

FREEBLK  *copyFree; 

MEMBLK  ‘curBlk; 

MEMBLK  ‘saveBlk; 

MEMBLK  ‘prevBlk  =  NULL; 

MEMBLK  *nextFree  =  NULL; 

MEMBLK  ‘prevFree  =  NULL; 

FREEBLK  *tmpFree; 
uint  spaceRecovered  =  0; 

int  last  =  FALSE; 

curBlk  =  mst [seg] .block; 

while  ((spaceRecovered  <  size)  &&  (Hast))  { 

last  =  (curBlk->flags  &  BLK_LAST )  !=  0; 

if  ( { (curBlk->flags  &  BLK_DELE TABLE )  !=  0)  &&  (deletable)  && 
(curBlk->size  >  sizeof (MEMBLK)  +  MINBLOCKDATA) )  { 


/*  Next  place  to  copy  */ 

/*  Free  pointers  */ 

/*  First  block  */ 

/*  Saved  block  location  */ 

/*  Previous  block  */ 

/*  Saved  next  free  block  */ 
/*  Saved  prev.  free  block  */ 
/*  Temporary  free  pointer  */ 
/*  Amount  space  recovered  */ 
/*  Last  record  found  */ 
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spaceRecovered  +=  curBlk->size  -  sizeof (MEMBLK)  - 

MINBLOCKDATA; 

if  (copyLoc  !=  NULL)  [ 

if  ( (curBlk->f lags  *  BLK_FUNCDELETE)  !=  0) 

(*  (curBlk->func) ) (curBlk,  BLK_FUNCDELETE 
I  BLK_FUNCMOVE,  curBlk->size,  copyLoc); 


spaceRecovered  +=  curBlk->size; 

nextFree  =  {MEMBLK  *)  ( ( (FREEBLK  *) 

DATALOC (curBlk) ) ->next) 
curBlk  =  (MEMBLK  *)  ((byte  *)  curBlk  +  curBlk->size) ; 

) 


/*  Save  location  of  block  */ 
saveBlk  =  curBlk; 


/*  At  this  point  copyLoc  points  to  the  beginning  of  the  free  area, 
spaceRecovered  is  the  size  of  the  new  free  block,  and  saveBlk 
points  to  the  next  free  block  in  the  segment  */ 


/*  Move  block  header  to  new  location  */ 
memmove (copyLoc,  curBlk,  sizeof (MEMBLK) ) ; 

/*  Set  up  new  pointer  to  previous  block  */ 


)  else  { 

if 


copyLoc->prev  =  prevBlk; 
copy Loc->f lags  &=  BLK_LAST; 
copy Loc->f lags  |=  BLK_DELETED; 

COpyLoc->size  =  sizeof (MEMBLK)  +  MINBLOCKDATA; 
mpt [copyLoc->pointerNum]  =  DATALOC (copyLoc) ; 
prevBlk  =  copyLoc; 

curBlk  =  (MEMBLK  *)  ((byte  *)  saveBlk  + 

copyLoc->size) ; 

copyLoc  =  (MEMBLK  *)  ((byte  *)  copyLoc  + 

copyLoc->size) ; 

( (curBlk->flags  &  BLK_FUNCDELETE)  !=  0) 

(* (curBlk->func) ) (curBlk, 

BLK_FUNCDELETE,  curBlk->size,  NULL) ; 


/*  Initialize  free  area  after  block  */ 


curBlk->flags  &=  BLK_LAST; 
curBlk->f lags  |=  BLK_DELETED ; 
saveBlk  =  curBlk; 
prevBlk  =  curBlk; 

curBlk  =  (MEMBLK  *)  ((byte  *)  curBlk  + 

curBlk->size) ; 

saveBlk->size  =  sizeof (MEMBLK)  +  MINBLOCKDATA; 
copyLoc  =  (MEMBLK  *)  DATALOC (saveBlk) ; 


if  (copyLoc  !=  NULL)  ( 

copyLoc->checkByte 

copyLoc->prev 

copyLoc->size 

copyLoc->pointerNum 

copyLoc->segment 


=  CB; 

=  prevBlk; 

=  spaceRecovered; 
=  0; 

=  seg; 


if  (last)  ( 

copy Loc->f lags  =  BLK_LAST; 

)  else  ( 

copyLoc->flags  =  0; 

saveBlk  =  (MEMBLK  *) ( (byte  *)  copyLoc  +  copyLoc->size) ; 
saveBlk->prev  =  copyLoc; 

) 


copyFree  =  (FREEBLK  *)  DATALOC (copyLoc) ; 
copyFree->prev  =  prevFree; 
if  (prevFree  !=  NULL)  ( 

tmpFree  =  (FREEBLK  *)  DATALOC (prevFree) ; 
tmpFree->next  =  copyLoc; 

) 

copyFree->next  =  nextFree; 
if  (nextFree  !=  NULL)  { 

tmpFree  -  (FREEBLK  *)  DATALOC (nextFree) ; 
tmpFree->prev  =  copyLoc; 

) 

mst [seg] . free  =  copyLoc; 
mst  [seg] .last  =  copyLoc; 

End  Listing  Two 


)  else  if  ( (curBlk->f lags  &  BLK_INUSE)  !=  0)  ( 
if  (copyLoc  ==  NULL)  [ 

prevBlk  =  curBlk; 

curBlk  -  (MEMBLK  *)  ((byte  *)  curBlk  + 

curBlk->size) ; 

)  else  ( 

if  ( (curBlk->f lags  &  BLK_LOCKED)  ==  0)  [ 

if  ( (curBlk->f lags  &  BLK_FUNCMOVE )  !=  0) 
(* (curBlk->func) ) (curBlk, 

BLK_FUNCMOVE ,  curBlk->size, 
copyLoc) ; 

/*  Move  block  to  new  location  *7 
saveBlk  =  curBlk; 

memmove (copyLoc,  curBlk,  curBlk->size) ; 

copyLoc->prev  =  prevBlk; 

copyLoc->flags  &=  BLK_LAST; 

prevBlk  =  copyLoc; 


listing  Three 


demo.c  Demonstration 

S.  Peterson  programmer 

This  program  demonstrates  the 


byte,  uint, 


♦include 

<stdio.h> 

♦include 

<stddef .h> 

♦include 

<process.h> 

♦include 

cmemory .h> 

♦include 

"mem.h" 

void  blockFunc (void  *,  b; 

int  main (void) ; 

int 
main  () 

void  **p; 

void  *q; 


program  for  memory  manager 
1/89 

features  of  the  memory  manager. 


void  *);  /*  Prototype,  block  function  */ 


/*  Double  pointer  to  block  */ 
/*  Single  pointer  to  block  */ 


mpt [copy Loc->pointerNum]  = 

DATALOC (copyLoc) ; 


/*  Allocate  a  30K  buffer  and  100  master  pointers  */ 


/*  Move  pointer  to  next  block  */ 

curBlk  =  (MEMBLK  *)  ((byte  *) saveBlk  + 
copyLoc->size) ; 
copyLoc  =  (MEMBLK  *)  ((byte  *) copyLoc  + 
copyLoc->size) ; 


if  (Memlnit (300001,  100)  !=  TRUE) 
exit  (1) ; 

/*  Allocate  a  buffer  of  1024  bytes.  It  is  created  as  moveable  and 
undeletable  */ 

if  ((p  =  MemAlloc (1024) )  ==  NULL) 

printf ("Error  allocating  1024  bytes. \n"); 


)  else  (  /*  Close  up  current  free  block  */ 

curBlk  =  (MEMBLK  *)  ((byte  *)  curBlk  + 
curBlk->size) ; 


MemLock (p) ; 
q  =  *p; 

memset(q,  0,  1024); 


/*  Make  the  block  unmoveable  */ 

/*  Get  pointer  to  memory  block  */ 
/*  Initialize  block  to  0  */ 


copyLoc->flags  -  0; 

copyLoc->checkByte  =  CB; 

copyLoc->prev  =  prevBlk; 

copyLoc->size  =  spaceRecovered; 

copyLoc->pointerNum  =0; 
copyLoc->segment  =  seg; 
saveBlk  = (MEMBLK  *)  ((byte  *) copyLoc  + 
copyLoc->size) ; 
saveBlk->prev  =  copyLoc; 
spaceRecovered  =  0; 

copyFree  = (FREEBLK  *) DATALOC (copyLoc) ; 
copyFree->prev  =  prevFree; 
if  (prevFree  !=  NULL)  { 

tmpFree  =  (FREEBLK  *) 

DATALOC (prevFree) ; 
tmpFree ->next  =  copyLoc; 

} 


copyFree->next  =  nextFree; 
if  (nextFree  !=  NULL)  [ 

tmpFree  =  (FREEBLK  *) 

DATALOC (nextFree) ; 
tmpFree->prev  =  copyLoc; 

) 


prevBlk 

prevFree 

copyLoc 


=  copyLoc; 
=  copyLoc; 
=  NULL; 


/*  Make  the  block  moveable  */ 
/*  Note:  q  no  longer  valid  */ 


MemUnlock (p) ; 

MemCompact ( ) ; 

MemFree (p) ; 

/*  Allocate  a  block  with  an  associated  function.  */ 

if  ((p  =  MemAllocFunc (1024,  blockFunc,  BLK_FUNCDELETE  | 

BLK_FUNCMOVE ) ) 

exit  (2) ; 


/*  Cause  memory  to  be  compacted  */ 
/*  Deallocate  p  */ 


MemFree (p);  /*  Deallocate  p  */ 

return  0; 

) 

void 

blockFunc (blockPtr,  flags,  length,  newLoc) 

void  *blockPtr; 

byte  flags; 

uint  length; 

void  * newLoc; 

( 

if  ((flags  6  BLK_FUNCMOVE)  !=  0)  { 

/*  Perform  some  action  when  block  moves  */ 

} 

if  ((flags  &  BLK_FUNCDELETE )  !=  0)  { 

/*  Perform  some  action  when  block  is  deleted  */ 


)  else  {  /*  Free  */ 

if  (copyLoc  ==  NULL) 

copyLoc  =  curBlk; 


End  Listings 
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EXAMINING  ROOM 


This  month  the  Doctor  examines 
Edward K.  Ream’s  “Sherlock” 
debugger,  TSR System’s  “C”eri- 
ous  Toolkit,  ”  Crescent  Software’s 
“Basic  QuickPak  Professional,  ” 
and  a  book  called  “The  Puz¬ 
zling  Adventures  of  Dr.  Ecco.  ” 

Sherlock 

Homes 

In 

Alex  Lane 


Product  Information 

Sherlock;  Edward  K.  Ream,  1617 
Monroe  St.,  Madison,  WI  53711.  IBM 
PC/XT/AT  or  compatible  with  2  floppy 
disks  or  hard-disk  MS-DOS.  Microsoft 
C  or  Turbo  C  compiler.  (Note:  Micro¬ 
soft  MASM  macro  assembler  required 
to  change  interrupt  handler.)  Price:  $195. 

It’s  funny  how  C  programmers  get 
caught  in  the  rut  of  debugging 
programs  by  peppering  them  with 
printf( )  statements.  Sure,  some 
master  the  intricacies  of  source- 
level  debuggers  like  CodeView,  which 
offers  both  slick  features  and  a  formi¬ 
dable  learning  curve;  others,  influenced 
by  books  like  Debugging  C  (Robert 
Ward,  Que,  1986),  try  various  ad  hoc 
combinations  of  compile-time  variables 
and  macros.  The  rest,  however,  lacking 
time  or  budget,  uneasily  curse  the  dark¬ 
ness  and  continue  to  rely  on  printf( ) 
statements  to  flush  bugs  out  into  the 
open. 

Rejoice,  programmers!  That  darkness 
may  be  short-lived.  Sherlock  is  a  rea¬ 
sonably  priced,  well  thought-out  tool 
for  debugging,  tracing,  and  profiling 
programs  written  in  C.  The  package 
was  written  by  Edward  K.  Ream,  who’s 
developed  a  reputation  for  putting  out 
quality  software  and  whose  name  is 
no  stranger  to  these  pages.  Sherlock 
runs  on  IBM  PC/XT/AT  machines  un¬ 
der  MS-DOS  with  either  Microsoft  C  or 
Turbo  C.  (Because  source  code  is  pro¬ 
vided  for  the  macros  and  support  rou- 


Alex  Lane  is  a  knowledge  engineer  for 
Technology  Applications  Inc.  of  Jackson¬ 
ville,  Fla.  He  can  be  reached  as  a. lane 
on  BIX  and  as  ALANE  on  MCI  Mail. 
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tines,  minor  modifications  should  al¬ 
low  Sherlock  to  be  used  with  other 
compilers  as  well.)  The  software  comes 
on  two  5Vt-inch  low-density  floppies, 
and  is  accompanied  by  a  66- page  spiral- 
bound  manual. 

Features 

I  can  appreciate  the  work  that  Ed  Ream 
did  on  Sherlock  because  I  did  some¬ 
thing  similar  (but  nowhere  near  as  pol¬ 
ished)  for  a  C  project  a  while  back.  By 
enabling  and  disabling  various  trace- 
points,  you  can  quickly  see  what’s  hap¬ 
pening  in  the  program  without  either 
being  overrun  with  spurious  debug¬ 
ging  information  or  having  to  continu¬ 
ally  stop,  edit,  recompile,  and  relink 
the  code.  This  is  particularly  important 
when  trying  to  track  down  pointer  bugs, 
which  tend  to  behave  differently  as 
printfC )  statements  are  added  to  and 
removed  from  the  code.  Ream  discusses 
such  problems  in  the  manual,  and  re¬ 
fers  readers  to  Ward’s  Debugging  C, 
mentioned  earlier. 

The  typical  statement  executed  from 
a  Sherlock  macro  is  a  printf( )  state¬ 
ment,  although  any  executable  C  state¬ 
ment  (including  blocks  of  statements) 
may  be  used  in  a  macro.  This  lets  you 
create  really  complicated  debugging  func¬ 
tions  (display  of  data  structures,  for 
example)  that  are  only  called  when 
you  need  them.  I  found  Sherlock’s  trac¬ 
ing  ability  useful  in  selectively  viewing 
the  input  from  a  serial  port  during  pro¬ 
gram  execution.  This  allowed  me  to 
quickly  tell  whether  my  program  was 
misbehaving,  or  whether  the  serial  in¬ 
put  was  corrupt. 

Leaving  the  Sherlock  object  code  in 
the  application  effectively  embeds  an 
extensive  diagnostic  capability  that’s 
easy  to  use  and  simple  to  document. 

Sherlock  is  also  a  profiling  tool,  which 
means  it  can  gather  frequency  and  tim¬ 
ing  statistics  and  report  them  at  any 
time.  This  feature  can  be  of  particular 
value  when  trying  to  track  down  the 
20  percent  of  the  code  that  uses  80 
percent  of  the  CPU’s  time,  or  when 
trying  to  track  down  a  boundary-value 
bug.  While  I  normally  don’t  need  this 
capability,  I  was  pleasantly  surprised 
to  see  how  ea'sy  it  was  to  implement. 

Typically,  Sherlock  macros  are  en¬ 
abled  or  disabled  from  the  command 
line  by  including  the  macro  name  with 
a  special  prefix  (like  ‘+  +’  or  respec¬ 
tively).  These  command-line  arguments 
are  removed  by  the  SL_PARSE( )  macro, 
which  passes  the  remaining  arguments 
to  the  subsequent  code.  The  scope  of 
Sherlock  tracepoints  can  also  be  con¬ 
trolled  from  other  macros,  particularly 
the  SL_ON( )  and  SL_OFF( )  macros. 

Defining  or  not  defining  the  compile¬ 


time  variable  SHERLOCK  determines 
whether  the  macros  in  the  code  are 
expanded  or  whether  they  disappear 
without  a  trace.  Because  Sherlock  mac¬ 
ros  are  unobtrusive  in  source  code, 
there’s  really  no  need  to  remove  them 
before  generating  production  versions 
of  executable  code.  This  capability  is 
valuable  for  code  that  undergoes  peri¬ 
odic  revision  or  enhancement. 

Utilities 

You  can  get  a  head  start  on  mastering 
Sherlock  by  using  the  Sherlock  pre¬ 
processor  (SPP).  This  program  automati¬ 
cally  inserts  macros  to  trace  the  entry 
and  exit  of  all  functions  in  a  file  and 
inserts  initialization  macros  in  the 
main( )  function.  Studying  such  a 
“Sherlocked”  file  with  the  manual  at 
hand  speeds  the  learning  process.  An¬ 
other  Sherlock  utility,  SDEL  reverses 
the  process  should  you  decide  to  re¬ 
move  macros. 

A  third  utility,  SDIF,  is  a  file  compari¬ 
son  program  that  is  designed  to  com¬ 
pare  an  “un-Sherlocked”  file  with  its 
“Sherlocked”  cousin.  The  output  of  SDIF 
lets  you  immediately  see  which  macros 
are  in  the  file. 

The  C  source  code  for  SDEL  and 
SDIF  is  included  with  the  package.  In 
addition,  the  source  to  CPP,  a  C  pre¬ 
processor  compatible  with  the  draft 
ANSI  standard  of  1-11-88,  is  included 
as  an  extensive  example  of  how  Sher¬ 
lock  macros  are  used. 

No  Nonsense 

Despite  the  sophistication  of  the  Sher¬ 
lock  package  as  a  whole,  there  are 
some  things  to  watch  out  for.  Sherlock 
is  intended  for  intermediate-to-advanced 
C  programmers,  and  thus,  doesn’t  go 
into  the  level  of  startup  detail  one  might 
expect  in  a  general-purpose  package. 
For  example,  some  things  are  dropped 
in  the  user’s  lap  with  no-nonsense  ex¬ 
planations,  such  as  the  existence  of 
two  sets  of  macros  (the  second,  in  case 
your  compiler  does  not  allow  multiple 
static  variables  to  have  the  same  name 
even  if  declared  in  separate  blocks). 
Another  such  example  is  a  warning  to 
the  effect  that  the  timing  interrupt  han¬ 
dler  (supplied  in  assembler  source  and 
in  small-  and  large-model  object  file 
formats)  may  have  to  be  twiddled  for 
non-100  percent  IBM  compatibles. 

Sherlock  is  not  copy-protected  and 
Ed  Ream’s  no-nonsense  license  agree¬ 
ment  asks  the  user  to  treat  the  software 
just  like  a  book.  Just  as  no-nonsense  is 
the  author’s  offer  of  a  satisfaction-or- 
money-back  guarantee. 

Sherlock  offers  excellent  value  and 
utility  for  the  price,  and  belongs  in  the 
toolkit  of  every  serious  C  programmer. 
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. . .  But 

Ceriously 

Folks 

Keith  Weiskamp 


Product  Information 

“C’erious  Toolkit;  TSR  Systems  Ltd., 
1600  B  Main  Street,  Port  Jefferson,  N.Y. 
11777;  516-331-6336.  IBM  PC  or  PS/2 
and  compatibles.  Requires:  DOS  2.0 
or  later;  Turbo  C  2.0,  Microsoft  5.0,  or 
Watcom  C  6.5.  Price:  libraries  and  docu¬ 
mentation  $99;  libraries,  documenta¬ 
tion,  and  source  code  $199- 

If  you  take  your  C  programming 
seriously,  you’re  going  to  need  a 
set  of  serious  tools.  Let’s  face  it, 
writing  the  same  pop-up  window 
interface  or  string-handling  rou¬ 
tine  over  and  over  is  a  complete  waste 
of  time.  To  help  you  write  more  pow¬ 
erful  C  programs,  TSR  Systems  has  de¬ 
veloped  a  toolkit  of  useful  functions 
for  the  major  PC-based  C  compilers  — 
Microsoft  C,  Turbo  C,  and  Watcom  C. 

TSR’s  offering  reduces  the  difficulty 
of  adding  pop-up  windows  and  menus 
to  your  programs.  In  addition,  you’ll 


Keith  Weiskamp  is  the  author  of  nu¬ 
merous  computer  books  including  Ad¬ 
vanced  Turbo  C  Programming. 


find  the  tools  for  accessing  your  PC’s 
hardware  including  the  screen,  disk 
drive,  keyboard,  speaker,  and  printer 
a  real  productivity  booster.  For  a  slight 
additional  expense  ($50),  you  can  ob¬ 
tain  the  “C’erious  Toolkit  Plus,  which 
includes  a  set  of  terminate  and  stay 
resident  (TSR),  and  hot-key  routines. 

What  You  Get 

The  standard  “C”erious  Toolkit  comes 
complete  with  a  library  of  over  100 
functions  and  a  111-page  manual.  The 
first  part  of  the  manual  is  devoted  to 
background  information,  such  as  how 
the  tools  are  linked  with  different  com¬ 
pilers  and  a  brief  presentation  of  the 
data  structures  required  to  support  the 
tools.  For  some  strange  reason  the  Turbo 
C  compiler  is  not  covered.  The  second 
part  of  the  manual  provides  a  quick 
reference  for  each  of  the  functions.  Here, 
you’ll  find  short  examples  that  demon¬ 
strate  how  parameters  and  return  val¬ 
ues  are  used.  Overall,  I  was  disap¬ 
pointed  with  the  manual,  especially  the 
reference  section,  because  the  exam¬ 
ples  were  incomplete  and  hard  to  read. 
The  best  way  to  learn  how  to  use  the 
functions  is  by  trial-and-error  or  by  study¬ 
ing  the  sample  programs  that  are  in¬ 
cluded  with  the  toolkit. 

The  functions  are  grouped  into  11 
categories  as  shown  in  Table  1. 

The  tools  are  packed  into  a  library 
that  fits  on  one  disk.  I  didn’t  review  the 
source  code  version  of  the  product, 
but  I  assume  that  the  source  files  are 
provided  on  a  second  disk.  The  tools 
are  coded  in  assembler  and  C.  In  gen¬ 
eral,  you’ll  find  that  they’re  optimized 
for  size  and  speed.  In  fact,  TSR  pro¬ 
vides  a  menu  program  that  was  con¬ 
structed  with  their  tools  and  weighs  in 


at  only  7,116  bytes.  A  similar  version  of 
the  program  constructed  with  the  popu¬ 
lar  Blaise  C  tools  required  over  35K. 

With  the  standard  version,  TSR  in¬ 
cludes  a  demo  disk  that  provides  a  set 
of  sample  programs.  By  working  with 
the  sample  programs,  I  discovered  some 
powerful  applications  of  the  tools  that 
were  not  apparent  from  reading  the 
manual.  For  example,  at  first  glance  I 
didn’t  think  that  features,  such  as  pop¬ 
up  menu  interfaces,  could  be  gener¬ 
ated  without  a  lot  of  work.  After  ex¬ 
ploring  the  sample  programs,  however, 
I  realized  that  with  a  little  creativity  and 
a  few  switch  statements  it  could  be 
done.  You’ll  also  find  sample  programs 
for  displaying  the  status  of  disk  drives, 
formatting  strings,  displaying  windows, 
and  many  other  goodies. 

In  most  cases,  the  functions  are  rela¬ 
tively  easy  to  use.  Four  header  files  are 
provided,  although,  most  of  the  func¬ 
tions  only  require  tproto.h. 

Some  Improvements 

The  greatest  defect  is  the  manual.  Al¬ 
though  the  text  seems  accurate  and 
examples  are  provided  for  each  func¬ 
tion,  the  type  is  hard  to  read  because 
it’s  so  small.  I’d  suggest  that  TSR  either 
provide  a  magnifying  glass  with  the 
product  or  reprint  the  manual.  Also, 
you  won’t  find  a  table  of  contents  or 
an  index.  If  you  spend  half  of  your 
programming  time  looking  things  up 
in  the  manual,  like  I  do,  you’ll  really 
miss  the  index. 

The  design  emphasis  of  the  tools  is 
on  speed  and  size.  In  some  cases,  how¬ 
ever,  the  tools  are  too  low  level  for  my 
preference.  That  is,  you  need  too  many 
separate  tools  to  construct  something 
useful.  For  example,  if  you  want  to 
display  a  window  with  a  border  and  a 
title,  you’ll  have  to  call  at  least  five 
different  functions: 

setWind(  .  .  .  ); 
setAttr(  .  .  .  ); 
setBordf  .  .  .  ); 
setTitle(  .  . .  ); 
strtWind(  .  .  .  ); 

If  you’re  displaying  a  lot  of  different 
windows  in  a  program,  you  might  want 
to  combine  some  of  these  functions  so 
that  you  can  actually  display  a  window 
with  one  or  two  calls. 

All  in  all,  you’ll  really  appreciate  the 
efficiency  of  these  routines.  I’d  suggest 
that  you  pick  up  the  source  code  ver¬ 
sion  so  that  you  can  customize  the 
tools  for  your  needs.  In  addition,  if  you 
need  to  create  TSR  programs,  you  might 
want  to  pick  up  a  copy  of  the  “C’erious 
Toolkit  Plus. 

(continued  on  page  96) 
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Cursor 

Routines  for  reading,  moving,  and  displaying 
cursors 

Disk 

Reading  the  status  of  disk  drives 

Keyboard 

Low-level  keyboard  access 

Printing 

Initialize  the  printer,  print  characters  and 
screen  images 

Rectangle 

Fills,  moves,  copies,  erases,  and  saves  rec¬ 
tangular  screen  regions 

Screen  I/O 

Set  attributes,  restore  and  save  screen  im¬ 
ages,  read  and  write  characters,  strings,  and 
tokens 

Sound 

Control  the  PC’s  speaker 

String  processing 

Insert,  delete,  and  search  for  characters;  jus¬ 
tify  strings 

Window 

Everything  you  need  to  create  dynamic  pop¬ 
up  windows 

Video 

Control  video  modes 

Miscellaneous 

Internal  functions,  determine  RAM  size,  read 
the  light  pen,  and  other  goodies 

Table  1:  Categories  of  functions  included  with  the  toolkit 
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EXAMINING  ROOM 


Quick  Look 
at 

QuickPak 

Bruce  Tonkin 


Product  Information 

QuickPak  Professional;  Crescent  Soft¬ 
ware,  11  Grandview  Ave.,  Stamford, 
CT  06905;  203-846-2500.  IBM  PC  and 
compatibles.  DOS  2.0  or  later;  Micro¬ 
soft  Basic  and  Quick  Basic  compilers, 
Versions  1.0  or  higher,  or  Turbo  Basic. 
Price:  $149. 

SuickPak  Professional  is  a  set 
of  routines  (many  in  assem¬ 
bler)  intended  for  use  with 
the  Microsoft  Basic  and 
Quick  Basic  compilers,  ver¬ 
sions  1.0  or  later,  and  with 
i  Turbo  Basic. 

I  counted  276  routines  (there  are  a 
few  more  on  disk,  documented  in  a 
text  file)  and  saw  just  a  handful  I  couldn’t 
use;  if  only  a  dozen  were  worthwhile, 
QuickPak  would  still  be  worth  the 
money.  I  give  this  package  an  unquali¬ 
fied  recommendation  on  the  basis  of 
its  value  and  utility. 

Documentation 

Before  talking  about  the  routines,  you 
should  know  the  downside:  There  is 
no  quick  reference,  summary,  or  in¬ 
dex.  The  manual  is  not  numbered  by 
page  but  by  section  and  page  within 
section;  I’d  prefer  the  former.  There  is 
a  decent  table  of  contents,  though,  and 
the  routines  are  usually  named  clearly; 
that  makes  finding  references  easier 
than  you  might  think.  Still,  an  index 
would  be  worthwhile. 

It  would  be  even  nicer  to  have  a 
reference  card  or  section  that  listed  rou¬ 
tines  by  function  (for  example  direc¬ 
tory  routines  or  file  routines).  The  pre¬ 
sent  manual  does  provide  section  head¬ 
ings  in  the  table  of  contents,  but  those 
headings  are  a  bit  too  general.  Further, 
there  is  no  explanation  of  the  routines 
except  those  given  in  the  body  of  the 
manual  itself.  The  table  of  contents  lists 
a  routine  named  “DOSVer.”  It’s  easy 
to  guess  what  that  one  does,  but  what 
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ware  for  TRS-80  and  MS-DOS/PC-DOS 
computers.  You  may  reach  him  at  T.N.  T. 
Software  Inc.,  34069  Hainesville  Rd., 
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about  “FGetRT?”  From  the  table  of  con¬ 
tents,  we  know  only  that  it’s  a  DOS 
service  routine.  (It’s  similar  to  a  ran¬ 
dom  file  GET,  but  avoids  ON  ERROR 
handling.)  Memory  joggers  are  always 
useful,  particularly  when  there  are  more 
routines  in  QuickPak  than  keywords 
in  Quick  Basic  or  Turbo  Basic. 

I  was  told  that  a  new  version  of  the 
manual  is  in  preparation.  I  hope  these 
shortcomings  are  addressed,  because 
the  explanations  and  examples  in  the 
manual  are  very  good  — both  clear  and 
detailed.  The  hints  and  discussions  of 
various  programming  techniques  are 
valuable,  too. 

Down  to  Business 

I  could  probably  make  a  career  out  of 
writing  my  own  versions  of  each  of  the 
routines  in  QuickPak  and  writing  a  short 
article  about  each  for  publication.  I 
haven’t  done  that,  and  won’t,  of  course. 
There  are  routines  to  insert  and  delete 
elements  from  string  and  numeric  ar¬ 
rays,  sort  arrays,  create  and  manipulate 
bit  arrays,  parse  strings  in  downright 
useful  ways,  check  for  file  existence, 
find  space  available  on  a  disk  (and 
determine  disk  parameters),  determine 
or  set  the  current  drive,  run  a  batch  file 
from  Basic,  read  or  write  absolute  disk 
sectors,  manipulate  moving  bar  menus, 
use  a  mouse,  check  or  set  keyboard 
status,  find  the  day  of  the  week  for  any 
date,  determine  whether  a  printer  is 
ready,  encrypt  or  decrypt  a  file,  create, 
clear,  or  print  to  a  window  (even  draw 
a  box  around  it),  save  and  restore 
screens  (even  for  EGA),  scan  files,  use 
8-byte  integers,  speed  up  “slow”  native 
functions,  and  hundreds  more  at  least 
as  useful. 

If  that’s  not  enough,  Crescent  also 
includes  a  workable  full-screen  editor 
with  word  wrap,  block  and  column 
moves,  and  the  usual  editing  functions, 
together  with  a  sample  spreadsheet  pro¬ 
gram.  Of  course,  functions  or  routines 
to  do  the  usual  financial  or  statistical 
calculations  (present  value,  annuity,  in¬ 
ternal  rate  of  return,  depreciation,  stan¬ 
dard  deviation,  maximum,  minimum, 
and  so  forth)  are  included  in  the  Quick¬ 
Pak  package.  Either  the  editor  or  spread¬ 
sheet  programs  (all  or  part)  can  be 
included  in  code  you  write  for  your 
own  applications.  How  many  times 
have  you  wanted  to  include  a  small 
editor  or  spreadsheet  in  one  of  your 
programs? 

Finally,  complete  source  code  is  avail¬ 
able  for  everything.  Be  warned:  There’s 
more  than  one  megabyte,  so  it’s  hardly 
an  afternoon’s  browse.  It’s  well  com¬ 
mented  and  worth  getting. 

Buy  QuickPak  and  enjoy!  You  won’t 
go  wrong.  It’s  just  not  possible. 


Puzzling 

Adventures 


Jonathan  Amsterdam 


Product  Information 

The  Puzzling  Adventures  of  Dr.  Ecco 
by  Dennis  Shasha.  W.H.  Freeman 
and  Company,  New  York,  1988.  Price: 
$9-95  (paperback). 

The  best  puzzles  have  always 
been  showcases  for  beautiful 
mathematics.  Until  recently, 
however,  one  field  of  mathe¬ 
matics  — computer  science  — 
has  been  conspicuous  by  its  absence 
from  puzzledom.  You  might  think  that 
nothing  could  be  farther  from  math’s 
abstract  sparklings  than  the  inexorable 
bit-by-bit  crunching  of  our  favorite  ma¬ 
chines,  but  a  short  course  in  the  theory 
of  computation  would  change  that  mis¬ 
guided  opinion.  Some  of  the  most  ele¬ 
gant  mathematics  of  our  century  has 
been  inspired  by  computers,  and  it 
would  come  as  no  surprise  to  any  stu¬ 
dent  of  computer  science  that  the  field 
would  provide  material  for  some  new 
and  wonderful  puzzles. 

But  NYU  computer  scientist  Dennis 
Shasha  is  the  first  to  actually  write  such 
puzzles  — or  at  least,  the  first  to  write 
a  book  of  them.  The  book,  called  The 
Puzzling  Adventures  of  Dr.  Ecco,  con¬ 
tains  some  40  problems,  nearly  all  of 
them  drawn  from  the  mathematics  of 
computers,  and  nearly  all  of  them  fresh 
and  exciting.  You  won’t  find  any  of  the 
tired  old  standbys  that  ask  you  to  move 
matchsticks  or  pennies  around;  instead, 
you’ll  construct  digital  circuits,  design 
a  communication  network  that  still 
works  in  the  presence  of  failures,  and 
invent  cryptographic  protocols  for  the 
secure  transmission  of  data.  Along  the 
way,  Shasha  covers  many  of  the  key 
ideas  of  modem  computer  science  in 
an  elegant,  Gardneresque  prose.  Some¬ 
times  the  text  contains  the  explanation; 
but  often,  the  puzzles  themselves  lead 
you  to  discovery.  For  instance,  solving 
a  seemingly  innocuous  puzzle  about 
ranking  tennis  players  can  lead  you  to 
a  beautiful  sorting  algorithm.  In  the 
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solutions  at  the  end  of  the  book,  Shasha 
often  reveals  the  inspiration  for  the  puz¬ 
zle  and  refers  the  interested  reader  to 
a  paper  or  textbook.  Occasionally,  how¬ 
ever,  no  good  explanation  is  provided 
— the  beautiful  sorting  algorithm  is 
named  but  never  described  explicitly, 
for  example  — and  this  is  a  weakness 
of  the  book.  On  the  other  hand,  it  is  a 
book  of  puzzles,  not  a  teaching  text, 
and  judged  by  those  standards  pro¬ 
vides  a  fine  layman’s  introduction  to 
the  field. 

The  book  relates  the  adventures  of 
one  Dr.  Jacob  Ecco,  omniheurist.  An 
omniheurist,  as  the  book’s  narrator,  Pro¬ 
fessor  Scarlet,  explains,  is  a  person  who 
solves  all  problems.  Scarlet  first  meets 
Ecco  in  a  bakery  when  they  are  both 
children,  where  he  watches  Ecco  win 
a  cake  from  the  baker  by  solving  a 
clever  puzzle.  The  episode  sticks  in 
Scarlet’s  mind,  and  many  years  later, 
upon  discovering  that  Ecco  lives  not 
far  from  his  own  home,  Scarlet  seeks 
him  out,  befriends  him,  and  learns  his 
story. 

After  his  brilliant  doctoral  work,  Ecco 
tired  of  academia  moved  to  MacDou- 
gal  Street  in  Greenwich  Village,  where 
he  earns  a  living  by  solving  interesting 
puzzles  brought  to  him  by  tycoons, 
generals,  engineers,  and  presidents  in 
various  states  of  desperation.  Ecco  lis¬ 
tens  to  their  problems,  presses  them 
for  more  details,  and  invariably  asks 
Scarlet,  “What  do  you  make  of  it,  Pro¬ 
fessor?”  Scarlet,  who  plays  Watson  to 
Ecco’s  Holmes,  will  sometimes  offer  a 
suggestion  or  present  a  way  of  under¬ 
standing  a  problem,  sometimes  just  com¬ 
ment  on  the  problem’s  difficulty.  Ecco 
then  thinks  for  a  few  minutes,  scribbles 
a  solution,  and  hands  it  to  his  client. 
While  he  is  occupied,  we,  the  readers, 
have  the  opportunity  to  solve  the  puz¬ 
zle.  Ecco’s  clients  are  almost  always 
pleased  by  his  solution  and  usually  ask 
a  couple  of  follow-up  questions,  which 
amount  to  variations  on  the  original 
puzzle.  In  solving  successively  more 
difficult  versions  of  the  puzzle,  we  are 
often  led  to  more  general  ways  of  look¬ 
ing  at  the  problem. 

In  between  puzzle-solving  sessions, 
there  is  plenty  of  time  for  Ecco  and 
Scarlet  to  play  innumerable  games  of 
chess  and  to  discuss  topics  such  as  the 
aesthetics  of  mathematics,  the  neural 
basis  of  our  passion  for  design,  and  the 
foibles  of  human  nature.  There’s  also 
a  bit  of  jetsetting:  Ecco  and  Scarlet  travel 
to  India,  and,  accompanied  by  non¬ 
monotonic  logician  Evangeline  Goode, 
they  go  windsurfing  at  the  Columbia 
Goige  in  Oregon.  Shasha’s  Ecco  is  a 
three-dimensional  man,  not  a  mere  place¬ 
holder  for  genius  — we  leam  about  his 


past,  his  need  for  privacy,  his  love  for 
chess,  knowledge  and,  of  course,  puz¬ 
zles,  his  well-justified  fear  that  he  is 
under  surveillance,  and  his  constant 
striving  for  elegance  and  simplicity. 

The  book  even  has  something  of  a 
plot:  it  gradually  becomes  apparent  that 
someone  or  some  organization  is  out 
to  get  Ecco.  They  break  into  his  apart¬ 
ment,  leave  coded  messages  that  are 
cryptic,  even  when  decoded,  and,  in 
the  end,  perhaps  do  something  more. 
Just  what  has  happened  at  the  story’s 
conclusion  and  who  is  responsible  are 
the  final,  unresolved  mysteries  of  the 
book. 


Oh  yes,  there’s  also  a  contest  (which 
runs  to  the  middle  of  this  month):  de¬ 
code  10  messages  sprinkled  through¬ 
out  the  book  and  solve  the  puzzles 
they  describe  and  you’ll  be  entered  in 
a  drawing  for  a  hand-carved  chess  set. 
You’ll  also  get  a  free  T-shirt  proclaim¬ 
ing  you  to  have  joined  the  great  Dr. 
Ecco  in  the  ranks  of  that  most  distin¬ 
guished  and  unusual  of  professions, 
the  omniheurists. 
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PROGRAMMING  PARADIGMS 


Apple  Acquires 
Lisp  Company 


This  first  item  is  for  those  of  you 
who  lust  after  a  Lisp  worksta¬ 
tion.  You  know  who  you  are. 
Others  can  skip  ahead  to  this 
month’s  excursion  into  superlinear 
speedup  in  parallel  algorithms  or  my 
radical  proposal  regarding  the  teach¬ 
ing  of  programming. 

Early  this  year,  Apple  acquired  the 
assets  of  Coral  Software,  a  Cambridge, 
Mass.,  software  company  specializing 
in  programming  languages  and  artifi¬ 
cial  intelligence  tools.  Five  Coral  engi¬ 
neers  have  been  installed  as  the  core 
of  a  Cambridge-based  research  lab  for 
Larry  Tesler’s  Advanced  Technology 
Group. 

Apart  from  the  questions  that  this 
acquisition  raises  or  puts  to  rest  regard¬ 
ing  the  kinds  of  software  that  Apple 
finds  it  appropriate  to  sell,  it  focuses 
attention  on  the  Coral’s  product  line, 
and  particularly  on  its  Allegro  Com¬ 
mon  Lisp.  Coral  has  been  selling  a  Lisp 
for  the  Macintosh  since  early  on,  and 
currently  has  three  language  products: 
Allegro  Common  Lisp,  the  entry-level 
Pearl  Lisp,  and  Object  Logo.  Although 
Logo  is  often  regarded  as  a  language 
for  children,  Object  Logo  reputedly  of¬ 
fers  nearly  complete  access  to  the  tool¬ 
box  and  is  surprisingly  powerful.  But 
it  is  Allegro  Common  Lisp  that  Apple 
is  initially  distributing  through  the  re¬ 
cently-ingested  APDA. 

Franz  Inc.  contributed  to  the  original 


Michael  Swaine 


development  of  Allegro  Common  Lisp, 
and  will  continue  to  offer  a  version  of 
the  product  for  the  Mac  running  under 
A/UX.  Because  Franz  is  the  company 
supplying  the  Lisp  implementation  be¬ 
ing  bundled  with  the  NeXT  computer, 
one  expects  smooth  portage  of  Lisp 
between  these  environments.  Because 
Mathematica  is  also  available  on  both 
machines,  it  looks  as  though  certain 


kinds  of  scientific  programming  could 
live  comfortably  on  either  machine.  Com¬ 
mon  Lisp  itself  was  designed  for  port¬ 
ability,  as  Guy  Steele  points  out  in  The 
Book,  Common  Lisp:  The  Language. 

Superlinearity  Revisited 

I  have  discussed  superlinearity  in  this 
column  before  (August  1988).  A  recent 
paper  by  V.  Nageshwara  Rao  and  Vipin 
Kumar  casts  more  light  on  the  phe¬ 
nomenon. 

In  a  parallel  architecture,  you  hope 
to  get  greater  processing  speed  from 
adding  more  processors,  distributing  a 
problem  across  them  so  that  they  can 
attack  it  in  parallel.  The  more  proces¬ 
sors,  the  greater  the  speed,  it  is  fair  to 
expect.  If  you  can  reduce  sequential 
running  time  by  a  factor  of  n  through 
using  n  processors,  you  are  getting  a 
linear  speedup,  and  that’s  very  good. 

Linearity  is,  in  fact,  a  kind  of  logical 
limit  on  the  speedup  you  can  expect 
from  parallelizing  a  problem.  It’s  clear 
why  this  should  be  so:  If  a  parallel 
algorithm  can  solve  a  problem  in  n 
seconds  using  m  processors,  there  is  a 
sequential  algorithm  that  can  solve  the 
problem  in  m*n  seconds,  namely,  the 
algorithm  that  consists  of  the  m  com¬ 
ponents  of  the  parallel  algorithm,  exe¬ 
cuted  sequentially  by  the  single  proc¬ 
essor.  In  practice,  full  linearity  is  rarely 
achieved,  because  there  is  always  some 
overhead  involved  in  distributing  the 
problem  to  the  processors  and  com¬ 
bining  their  outputs. 

According  to  this  logic,  superlinearity 
ought  not  to  be  possible.  If  you  can 
speed  up  an  algorithm  by  a  factor  greater 
than  m  by  parallelizing  it  across  m  proc¬ 
essors,  it  would  seem  that  you  just  didn’t 
have  the  fastest  sequential  algorithm 
to  begin  with.  And  it  would  seem  that 
it  would  be  trivial  to  construct  a  better 
sequential  algorithm  from  the  parallel 
one,  as  described  in  the  preceding  para¬ 
graph. 

That’s  why  the  existence  of  super- 


linear  speedup  in  a  number  of  parallel 
algorithms  is  surprising. 

Typically,  when  apparent  super¬ 
linearity  is  encountered  in  the  paralleli¬ 
zation  of  an  algorithm,  one  of  two  situ¬ 
ations  exists.  In  one  situation,  the  origi¬ 
nal  sequential  algorithm  can  be  shown 
to  have  been  improved  in  parallelizing 
it,  so  that  resequentializing  it  yields  a 
better  sequential  algorithm  and  elimi¬ 
nates  the  superlinearity.  In  the  other 
situation,  the  speedup  is  superlinear 
in  isolated  cases,  but  still  linear  or 
sublinear  on  the  average.  The  former 
is  useful  if  it  really  leads  to  improving 
the  sequential  algorithm,  and  this  has 
occurred. 

The  latter  is  not  uncommon,  and  is 
real  superlinearity,  in  a  sense.  This  kind 
of  superlinearity  is  not  so  surprising 
once  you  examine  it.  After  all,  it’s  like 
a  local  decrease  in  entropy:  it’s  more 
than  offset  by  increases  elsewhere  in 
the  system.  And  while  this  isolated- 
case  superlinearity  may  be  useful  (es¬ 
pecially  if  you  have  some  knowledge 
of  the  kinds  of  cases  you  are  likely  to 
encounter  in  practice),  it  is  more  than 
offset  in  the  long  run  by  the  sublinear 
cases,  resulting  in  a  sublinear  average 
speedup,  which  is  what  we  are  led  to 
expect  by  the  logical  argument  against 
superlinearity. 

Unfortunately  for  the  argument,  there 
are  cases  in  which  it  is  possible  to 
achieve  an  average  speedup  that  is  su¬ 
perlinear. 

Rao  and  Kumar  have  found,  for  state- 
space  search  problems,  superlinearity 
on  the  order  of  a  17-fold  speedup  with 
nine  processors,  on  the  average. 

The  kind  of  problem  to  which  Rao 
and  Kumar  address  themselves  fits  a 
simple  model  of  depth-first  search  of  a 
complete  binary  tree  of  m  leaf  nodes, 
with  an  equal  static  partitioning  of  the 
tree  among  n  processors. 

Depth-first  search  is  a  fundamental 
AI  algorithm,  used  when  the  problem 
can  be  cast  as  “the  search  for  a  path  in 
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a  directed  graph  from  an  initial  node 
to  a  goal  node. .  .  .  [It]  is  used  quite 
frequently  if  good  problem-specific  evalu¬ 
ation  functions  are  not  available.”  (I’m 
quoting  Stuart  Shapiro  from  page  1004 
of  his  Encyclopedia  of  Artificial  Intelli¬ 
gence,  Volume  2,  John  Wiley  &  Sons, 
1987.)  The  goal  is  to  find  a  solution 
node  in  a  tree,  and  the  basic  algorithm, 
adapted  from  Shapiro,  looks  like  this: 

Put  the  initial  node  on  a  list  called 

OPEN. 

While  OPEN  is  nonempty: 

Remove  the  first  node  from  OPEN 
and  call  it  n. 

If  n  is  a  solution,  return  n  and 

quit. 

Generate  the  immediate  succes¬ 
sors  of  n. 

Put  them  at  the  beginning  of 
OPEN. 

End  while. 

That  is,  the  algorithm  searches  all  the 
way  down  the  leftmost  branch,  then 
backs  up  to  the  first  unsearched  branch 
and  searches  it,  until  it  finds  a  solution 
node  or  runs  out  of  tree. 

Solution  nodes,  in  Rao  and  Kumar’s 
model,  are  uniformly  distributed  in  a 
randomly  located  region,  possibly  over 
the  whole  tree  (solutions  live  at  the 
leaf  nodes).  The  assumption  regarding 
the  distribution  of  solutions  is  a  good 
one  for  problems  for  which  no  good 
heuristic  exists.  (If  there  is  a  good  heu¬ 
ristic,  you  won’t  even  be  able  to  get 
linearity,  because  the  heuristic  will  re¬ 
order  the  branches,  driving  solutions 
to  the  left  part  of  the  tree,  where  a 


When  we  learned  to 
program  in  Fortran  or 
Basic,  we  were  also 
learning  that  what  we 
were  doing  was 
programming 


sequential  depth-first  algorithm  will  find 
them  quickly.)  The  algorithm  (sequen¬ 
tial  or  parallel)  stops  when  it  finds  the 
first  solution. 

The  parallel  algorithm  Rao  and  Kumar 
use  slices  the  tree  vertically  into  n  sub¬ 


trees,  and  runs  the  sequential  algorithm 
on  each,  in  parallel  on  n  processors. 

In  this  model,  parallel  depth-first 
search  is  essentially  linear  if  there  is 
only  one  solution  to  find,  and  also 
linear  if  there  are  many  solutions  dis¬ 
tributed  uniformly  over  the  entire  tree 
(more  precisely,  over  the  entire  set  of 
leaf  nodes). 

Superlinearity  enters  the  picture  when 
there  are  several  solutions  and  the  (un¬ 
known)  region  in  which  they  lie  is 
smaller  than  the  entire  tree.  Maximal 
superlinearity  occurs  when  the  region 
in  which  solutions  lie  is  equal  to  the 
size  of  the  partition  of  the  search  space 
allocated  to  a  processor;  i.e.,  m/n  leaf 
nodes.  If  s  represents  the  number  of 
solutions,  the  maximum  efficiency,  or 
degree  of  superlinearity,  is  given  by: 

(s+l)/2-(s-l)/(2*n), 

or  for  a  large  number  of  processors, 
essentially 

(s+l)/2. 

Theoretically,  that  can  be  a  very  large 
number,  but  even  the  more  modest 
17/9  speedup  the  authors  actually  found 
is  impressive. 

This  superlinearity  seems  to  be  the 
result  of  the  imbalance  in  the  solution 
density  over  the  entire  solution  space, 
which  lets  one  of  the  processors  get  a 
sizable  chunk  of  the  region  in  which 
the  solutions  lie.  This  gives  that  proces¬ 
sor  an  excellent  chance  to  find  a  solu¬ 
tion,  and,  because  the  first  solution 
found  ends  the  search,  this  gives  the 
parallel  algorithm  a  superlinear  edge 
over  the  identical  sequential  algorithm. 

Rao  and  Kumar  think  that  there  ought 
to  be  many  real-world  cases  in  which 
this  kind  of  superlinearity  can  be  ex¬ 
pected.  There  are  many  problems  in 
which  a  “good”  non-goal  node  often 
leads  to  many  solutions,  while  “bad” 
non-goal  nodes  lead  to  no  solutions. 
The  solutions  headed  by  a  “good”  node 
will  lie  close  together,  leading  to  the 
kind  of  restricted  solution  region  the 
authors  have  modelled.  They  cite  the 
Eight  Queens  problem  as  an  example, 
and  their  experiments  focused  on  the 
15  Puzzle  and  the  Hacker’s  problem. 

Personally,  I  still  think  superlinearity 
looks  like  magic.  I  can’t  help  a  touch 
of  skepticism  about  these  results.  The 
superlinearity  effect  Rao  and  Kumar 
describe  rests  on  certain  information 
about  the  distribution  of  solutions, 
namely  that  the  solutions  are  clustered 
in  a  region  smaller  than  the  entire  search 
space.  Because  I  don’t  see  that  infor¬ 
mation  being  used  by  the  sequential 
depth-first  algorithm,  I  can’t  help  won¬ 
dering  if  the  deck  isn’t  stacked  against 


it,  and  if  there  isn’t  some  sequential 
algorithm  that  incorporates  this  infor¬ 
mation  and  brings  depth-first  search 
back  to  linear  reality.  I  dunno. 

Paradigms  for  Beginners 

I’d  like  to  advance  a  radical  proposal: 
That  programming  paradigms  be  used 
as  an  entry  into  the  study  of  computer 
science  and  programming.  I’d  like  to 
see  programming  paradigms  studied 
in  interdisciplinary  courses  that  serve 
as  the  student’s  first  and  only  course 
in  computer  science.  I’d  also  like  to  see 
the  study  of  paradigms  introduced  into 
the  core  computer  science  curriculum 
at  the  very  beginning  of  the  computer 
science  student’s  coursework. 

I’m  not  saying  that  I  don’t  believe 
there  are  any  prerequisites  for  the  study 
of  computer  science.  The  student  needs 
some  elementary  mathematical  knowl¬ 
edge  that  any  eighth  grader  ought  to 
have,  but  that  colleges  often  have  to 
provide.  And  a  computer  science  pro¬ 
gram  within  an  EE  department  will  natu¬ 
rally  have  elementary  electronics  and 
computer  hardware  prerequisites.  For 
such  a  program,  that’s  certainly  the  right 
way  to  begin.  But  there  is  always  a  first 
course  in  programming,  and  that’s  the 
course  I  have  in  mind.  That  course 
marks  the  student’s  first  practical  expe¬ 
rience  with  controlling  the  machine. 

A  Bad  Introduction  May  Mark 
the  Student  For  Life 

I  don’t  want  to  overstate  the  case.  Those 
of  us  who  learned  Fortran  or  Basic 
during  that  impressionable  phase  were 
probably  not  ruined  forever  by  the  ex¬ 
perience.  But  when  we  learned  to  pro¬ 
gram  in  Fortran  or  Basic,  we  were  also 
learning  that  what  we  were  doing  was 
programming.  Our  later  experiences 
with  such  alternative  paradigms  as  func¬ 
tional  programming,  object-oriented  pro¬ 
gramming,  or  logic  programming  were 
confusing  and  frustrating,  and  at  first 
we  found  ourselves  resisting  the  expe¬ 
rience.  We  were  unlearning  what  pro¬ 
gramming  is,  and  learning  a  new, 
broader  idea  of  programming  that  en¬ 
compassed  the  new  paradigm.  We 
thought  that  programming  involved  im¬ 
plementing  good  algorithms  to  solve 
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problems,  but  discovered  that  some¬ 
times  it’s  selecting  representative  classes 
to  model  the  system.  We  thought  that 
programming  was  all  about  writing  code 
to  manipulate  data,  but  we  had  to  ac¬ 
cept  that  sometimes  the  distinction  be¬ 
tween  code  and  data  just  got  in  the 
way.  Well,  I  don’t  want  ever  to  find 
myself  resisting  learning  something  new; 

I  want  to  be  open  to  new  ideas.  I 
believe  that  learning  about  program¬ 
ming  in  the  usual  way  leads  to  such 
resistance,  by  implanting  fixed  notions 
about  what  programming  is,  notions 
that  are  just  plain  wrong. 

What  would  I  cover  in  this  imaginary 
Computer  Science  101?  I  can  only  list 
some  elements  that  seem  appropriate; 
I  don’t  have  a  syllabus.  I’d  present  many 
example  programs  for  the  students  to 
read  and  study;  I’d  ask  the  students  to 
interpret  the  code,  explaining  what  they 
think  it  does.  There  would  be  no  key¬ 
ing  and  running  of  programs.  I’d  pre¬ 
sent  alternative  paradigms,  identified 
as  such,  and  get  the  students  to  see  the 
differences  in  approach  of  the  different 
paradigms.  Ideally,  by  the  end  of  the 
course,  the  students  would  have  some 
ability  to  criticize  code  in  several  lan¬ 
guages  from  the  point  of  view  of  clarity 
and  readability  (though  not  efficiency). 

I  could  see  the  course  being  titled  Com¬ 
puter  Programming  for  Reading  Knowl¬ 
edge. 

There  are  several  obvious  arguments 
against  using  such  a  course  in  pro¬ 
gramming  paradigms  as  the  introduc¬ 
tion  to  programming. 

One  runs  like  this:  1.  The  differences 
among  programming  paradigms  only 
make  sense  after  you’ve  acquired  one 
paradigm.  Students  needs  at  least  one 
concrete  example  of  what  program¬ 
ming  is  before  they  can  deal  with  ab¬ 
stractions  about  what  programming  can 
be.  Programming  is  an  abstract  activity 
anyway,  and  it  will  confuse  students 
to  introduce  it  at  an  abstract  level,  of¬ 
fering  alternative  visions  of  the  activity 
from  the  start. 

Or  there’s  this  argument:  2.  A  course 
such  as  I  describe  will  leave  the  stu¬ 
dent  still  unable  to  write  a  computer 
program.  What  I  propose  is  tantamount 
to  requiring  a  course  in  linguistics 
as  prerequisite  to  learning  a  foreign 
language.  Learning  a  new  language  — 
natural  or  computer  — is  difficult,  and 
the  student  ought  to  have  a  chance  to 
come  out  of  the  first  encounter  with  a 
feeling  of  success. 

Or  this:  3.  Students  of  programming 
may  need  help  learning  the  first  lan¬ 
guage,  but  after  that,  they  can  teach 
themselves.  We  need  programmers. 
Many  students  will  take  no  course  after 
the  first.  In  the  traditional  scheme,  these 


people  will  be  equipped  to  go  forth 
and  program,  despite  the  fact  that  they’ll 
have  much  to  leam  on  the  job.  Stu¬ 
dents  who  have  been  subjected  to  my 
proposed  Computer  Science  101  will 
not  be  so  equipped. 

I  have  an  answer  for  each. 

1.  I  don’t  buy  this.  I’ve  never  had  a 
college  physics  course,  yet  I  have  read 
and  understood,  for  recreation,  dozens 
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of  books  on  relativity,  cosmology,  and 
quantum  physics.  I  think  I  have  a  sense 
of  the  issues,  a  feeling  for  what  it  is  like 
to  work  in  the  fields,  and  if  I  were  to 
go  back  to  school  to  study  physics,  I 
think  I  could  choose  a  field  of  study 
more  wisely  for  having  read  these 
books.  While  there  are  difficult  abstrac¬ 
tions  in  programming,  the  basic  con¬ 
cepts  of  computer  programming  itself 
are  nowhere  near  as  ethereal  as  those 
of  quantum  physics.  People  who  know 
nothing  about  programming  think  that 
it  means  writing  instructions  to  make 
the  computer  do  what  they  want  it  to 
do,  and  that’s  a  workable  first  approxi¬ 
mation. 

2.  I  guess  I  don’t  hold  the  ability  to 
write  syntactically-correct  Basic  code 
to  be  at  college-level  skill.  I  also  don’t 
think  that  it  is  a  particularly  important 
skill  for  the  great  majority  of  people 
who  have  some  interest  in  computer 
science,  but  who  will  never  become 
professional  software  developers.  The 
ability  to  read  a  block  of  code  is  a  very 
different  skill,  is  useful  to  more  people, 
and  is  a  skill  that  professional  pro¬ 
grammers  need  but  are  never  explicitly 
taught.  I  do  believe  that  it  is  possible 
to  teach  a  basic  reading  knowledge  of 
several  programming  languages,  exem¬ 
plifying  radically  different  paradigms 


within  the  course  of  a  college  term.  I 
don’t  mean  proofreading  or  finding  er¬ 
rors  in  code;  I  mean  discerning  what  a 
correct  and  well-written  page  of  code 
does.  My  CS  101  would  not  be  like  a 
linguistics  course;  it  would  be  a  course 
in  what  computer  programming  is. 
There’s  no  analog  in  natural  languages 
because  we  don’t  need  a  course  telling 
us  what  a  natural  language  is. 

Weeks  of  student  time  in  introduc¬ 
tory  programming  courses  is  taken  up 
in  identifying  and  correcting  syntax  er¬ 
rors,  honing  typing  skills,  letting  the 
problems  that  happen  to  arise  dictate 
what  the  student  happens  to  learn. 
These  things  have  to  be  dealt  with  even¬ 
tually  if  the  student  is  to  learn  to  write 
correct  programs,  but  they  are  getting 
in  the  way  of  getting  the  idea.  Those 
who  remember  that  far  back  should 
know  that  first  programming  courses 
don’t  give  a  sense  of  success;  they  give 
a  sense  of  accomplishment,  acquired 
from  finally  breaking  through  the  brick 
wall  you’d  been  beating  your  head 
against.  I  propose  sending  the  student 
to  the  wall  equipped  with  an  intellec¬ 
tual  hammer. 

3.  Students  who  are  introduced  to  pro¬ 
gramming  in  the  way  I  propose  will 
have  to  take  programming  courses  or 
deal  with  some  frustration  in  learning 
the  mechanics  of  programming  by  them¬ 
selves.  I  think  that  a  basic  reading  knowl¬ 
edge  of  several  programming  languages 
will  seriously  reduce  the  frustration  of 
learning  where  to  put  the  semicolons, 
but  in  any  case,  the  students  will  be 
coming  to  the  process  of  writing  code 
with  a  broader  understanding.  It’s  pos¬ 
sible  that  the  approach  I  propose  would 
reduce  the  number  of  poorly-educated 
people  passing  themselves  off  as  pro¬ 
grammers.  I  guess  that’s  a  drawback  if 
you  think  that  bad  software  is  better 
than  no  software  at  all. 
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A  Phone 
Directory  and 
XMODEM  for 
SMALLCOM 


This  month  adds  two  features  to 
the  SMALLCOM  communications 
program  introduced  in  this  col¬ 
umn  last  month.  The  features  are 
a  telephone  directory  and  the  XModem 
file  transfer  protocols.  Most  communi¬ 
cations  programs  include  support  for 
both  capabilities.  As  this  project  pro¬ 
ceeds  from  month  to  month,  I  add  fea¬ 
tures  to  the  program  by  initializing  hook¬ 
ing  function  pointers.  Whenever  add¬ 
ing  features  this  way,  I  will  provide  the 
lines  of  code  that  you  must  change  in 
order  to  turn  on  the  hooks. 

Those  of  you  who  download  the 
code  from  the  CompuServe  online  serv¬ 
ice  should  be  alerted  to  my  methods. 
Each  source  code  file  that  you  down¬ 
load  is  written  just  as  it  appears  in  the 
issue  where  the  code  is  originally  pub¬ 
lished.  I  use  the  column  to  document 
minor  program  changes  required  for 
subsequent  months  and  do  not  change 
the  uploaded  code.  Why  do  it  this  way? 
There  are  two  reasons:  First,  the  man¬ 
agement  of  those  files  is  a  significant 
administrative  burden  borne  by  the  al¬ 
ready  overworked  and  loyal  staff  at 
DDJ.  Second,  I  planned  this  project  so 
that  anyone  could  bail  out  at  any  time 
and  still  have  usable  software.  Each 
month  presents  a  finished  tool  or  a 
complete  program.  The  tools  and  pro¬ 
grams  are  built  upon  those  of  the  pre¬ 
vious  months. 

You  might  not  need  all  the  enhance¬ 
ments  of  the  programs  as  they  pro¬ 
gress,  and  I  might  get  run  over  by  a  pie 
wagon.  The  code  you  download  should 
therefore  not  be  dependent  on  the  re¬ 
quirements  of  later  months.  It  follows 
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then  that  the  programs  and  the  col¬ 
umns  that  describe  them  are  a  matched 
set.  You  need  both. 

The  Hooks 

Listing  One,  page  132,  hooks. c,  is  a 
replacement  for  a  small  block  of  code 
near  the  beginning  of  smallcom.c.  Its 
location  and  what  it  replaces  should 
be  obvious  from  the  comments.  I  do 


not  give  line  number  references  be¬ 
cause  you  might  have  typed  the  code 
in,  and  your  numbers  and  mine  would 
probably  not  agree.  Hooks.c  provides 
the  function  prototypes  for  the  new 
features  and  initializes  the  hooking  func¬ 
tion  pointers.  You  will  see  hooks  to 
Kermit  protocols  in  the  upload  and 
download  function  pointers.  These  are 
stubbed  functions.  Kermit  is  not  in  this 
issue. 

The  Phone  Directory 

Listing  Two,  page  132,  is  phonedir.c. 
This  source  file  adds  the  phone  direc¬ 
tory  to  SMALLCOM.  A  phone  directory 
is  just  what  you  might  expect:  a  direc¬ 
tory  of  numbers  that  you  call  frequently. 
Because  different  online  services  and 
electronic  bulletin  boards  use  different 
connection  protocols  (baud  rate,  stop 
bits,  and  so  on),  the  phone  directory 
allows  you  to  specify  those  parameters 
for  each  entry. 

The  phone  directory  is  called  by 
the  Directory  selection  on  the  SMALL¬ 
COM  menu.  By  initializing  the  phone_ 
directory  function  pointer  in  smallcom.c 
to  the  phdirectory  function  in  phone¬ 
dir.c,  we  enable  the  feature.  The  phdi¬ 
rectory  function  opens  a  full-screen  win¬ 
dow,  reads  the  directory  from  the  file 
named  phone. dir,  and  fills  the  window 
with  text  from  the  directory  records  by 
calling  the  text_window  function.  The 
phone. dir  file  does  not  exist  until  you 
build  a  directory  with  at  least  one  en¬ 
try.  Each  record  in  the  file  is  a  null- 
terminated  string  with  fixed  position 
fields.  The  fields  are  separated  by 
spaces.  This  way  the  strings  are  given 
to  the  text_window  function  in  the  file 
format.  The  get_directory  function  allo¬ 
cates  a  block  of  memory  for  each  string 
and  builds  the  array  of  string  pointers 
expected  by  the  text_window  function. 

Once  the  phone  directory  is  dis¬ 
played,  the  program  calls  the  select_ 
window  function  to  allow  a  menu-like 
cursor  to  select  an  entry  from  the  direc¬ 
tory.  You  move  the  cursor  up  and  down 
with  the  arrow  keys  and  use  other  keys 
to  select  what  you  want  to  do  with  the 
entry  pointed  to  by  the  cursor. 

select_window  returns  with  the  num¬ 


ber  of  the  entry  selected  or  zero  if  you 
press  the  Esc  key.  The  call  to  select_ 
window  includes  the  address  of  the 
dirproc  function.  select_window  will, 
therefore,  call  the  dirproc  function  when 
you  press  a  key  other  than  the  Help 
key  (FI),  the  Enter  key,  an  arrow  key, 
or  the  Esc  key.  The  dirproc  function 
processes  the  Del  key,  which  deletes 
an  entry;  the  Ins  key,  which  inserts  a 
new  entry;  the  F2  key,  which  writes  the 
modified  directory  to  the  phone. dir  file; 
and  the  F3  key,  which  modifies  the 
directory  entry  where  the  cursor  points. 

Inserting  or  modifying  a  directory 
entry  uses  the  data  entry  window  tem¬ 
plate  functions  from  the  window  li¬ 
brary.  A  window  is  popped  up  over  the 
directory,  and  you  modify  its  contents 
by  using  the  data  entry  features. 

When  you  press  the  Enter  key,  the 
selected  directory  record  updates  the 
current  phone  number  and  line  proto¬ 
cols,  and  the  program  returns  to  the 
SMALLCOM  screen  where  you  will  see 
the  newly  selected  phone  number  at 
the  bottom  of  the  screen.  If  you  pop 
down  the  Parameters  menu,  you  will 
see  that  the  parameters  associated  with 
the  selection  are  now  selected.  You 
can  make  these  values  the  startup  de¬ 
fault  by  choosing  the  Write  Parameters 
selection  from  the  Parameters  menu. 

The  SMALLCOM  phone  directory  fea¬ 
ture  is  an  example  of  a  simple  applica¬ 
tion  of  the  data  entry  library  where  the 
values  in  a  flat  file  database  are  main¬ 
tained  with  a  data  entry  template.  No¬ 
tice  that  there  are  help  window  mne¬ 
monics  in  the  directory_template  FIELD 
array.  As  with  last  month’s  code,  I  am 
not  republishing  the  smallcom.hlp  text 
file  to  add  help  text  for  the  phone 
directory  (or  for  the  file  transfer  proto¬ 
col  data  entry  template  explained  later). 
You  may  compose  help  windows  that 
please  you  for  these  templates.  The 
directory  and  its  data  fields  should  be 
obvious  to  you  without  help  windows, 
but  you  might  want  to  add  help  text  if 
you  give  the  executable  SMALLCOM 
program  to  less  sophisticated  users  than 
yourself. 

Each  directory  record  includes  a  name 
for  a  script  file.  Scripts  are  sequences 
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of  interpreted  commands  that  a  com¬ 
munications  program  uses  to  automate 
routine  dialogues  with  online  services. 
Each  script  would  be  specific  to  the 
service  it  supports  because  the  services 
use  different  command  languages.  The 
directory  process  posts  the  script’s  name 
into  a  global  string  variable  named 
scriptfile.  Later,  when  we  add  the  script 
processor,  we  will  use  that  variable  to 
retrieve  the  script  file. 

File  Transfer  Protocols 

Here’s  the  problem.  When  you  send 
data  across  phone  lines,  errors  called 
“line  hits”  sometimes  occur.  A  line  hit 
might  add  a  bogus  character,  skip  a 
good  character,  or  change  the  binary 
configuration  of  a  character.  Line  hits 
can  occur  as  a  natural  byproduct  of 
noisy,  voice-grade  circuits.  These  er¬ 
rors  cannot  always  be  detected  by  the 
serial  hardware  in  the  computers.  So, 
if  your  data  cannot  endure  errors,  you 
must  put  error-detecting  and  error- 
correcting  logic  into  the  file  transfer 
software.  The  handshaking  and  data 
formats  that  manage  error  detection  and 
correction  in  serial  communications  are 
called  “file  transfer  protocols.” 

What  kind  of  data  cannot  endure 
errors?  Three  examples  are  executable 
computer  programs,  compressed  files, 
and  some  encrypted  files.  These  are 
binary  files  that  must  be  received  intact 
in  order  for  them  to  be  properly  used 
at  their  destinations.  Binary  files  must 
be  transmitted  with  a  protocol  that  either 
supports  an  8-bit  word  length  as  the 
XModem  protocol  does  or  translates 
byte  values  greater  than  127  into  a  pair 
of  7-bit  bytes  as  the  Kermit  protocol 
can  do.  ASCII  text  files  that  contain  the 
source  code  for  sizable  programs  should 
always  be  transmitted  with  an  error- 
correcting  protocol.  A  garbled  charac¬ 
ter  in  a  program’s  source  code  can  be 
difficult  to  spot,  can  go  undetected  by 
the  compiler,  and  can  wreak  havoc 
when  the  program  is  run. 

What  kind  of  data  can  endure  some 
margin  of  error?  Text  messages  can  usu¬ 
ally  be  sent  without  error  correction 
because  their  readers  are  humans  who 
can  perform  their  own  visual  error  cor¬ 
rection.  You  can  read  the  garbled  mes¬ 
sage  “Climatv  is  what  wi  expect,  weath$r 
is  whit  we  gt”  and  know  what  was 
sent.  That  example  is  extreme.  Most 
transmissions  get  off  without  a  hitch. 
The  ASCII  protocol  is  usually  accept¬ 
able  for  text  that  is  meant  for  people 
to  read.  When  the  hits  get  too  severe 
for  you  to  read  the  message,  hang  up 
the  phone  and  try  another  time.  Don’t 
bother  switching  to  an  error-correcting 
protocol.  If  the  line  hits  are  so  bad  that 
you  can’t  read  the  message,  no  error- 


correcting  protocol  would  work  either. 

Most  communications  programs  al¬ 
low  you  to  select  from  a  set  of  file- 
transfer  protocols  so  that  they  are  com¬ 
patible  with  the  various  online  services 
throughout  the  world.  We  will  add  that 
capability  to  SMALLCOM  with  a  menu 
that  selects  from  the  ASCII,  XModem, 
and  Kermit  protocols. 

Listing  Three,  page  133,  is  proto¬ 
col. c.  It  lets  you  select  a  specific  file- 
transfer  protocol  when  you  are  about 
to  upload  or  download  a  file.  It  opens 
a  small  window  and  writes  the  selec¬ 
tions  for  three  protocols:  ASCII, 
XModem,  and  Kermit.  ASCII  is  the  only 
protocol  that  was  included  in  the 
SMALLCOM  program  last  month. 
XModem  is  added  this  month.  I  might 
address  Kermit  in  a  later  month. 

If  you  want  to  add  still  another  pro¬ 
tocol,  you  would  add  an  entry  to  the 
window  menu’s  display,  code  corre¬ 
sponding  function  addresses  to  the 
up -protocol  and  down -protocol  func¬ 
tion  pointer  arrays  in  hooks. c,  and  write 
the  functions  to  implement  the  new 
protocol.  The  protocol  name  should 
start  with  a  unique  letter.  I’ve  built  the 
protocol  selection  menu  to  respond  to 
the  usual  menu  cursor  selection  and 
also  to  select  a  protocol  from  the  menu 
when  you  press  the  first  letter  of  the 
protocol’s  name.  If  you  add  a  protocol, 
you  must  insert  a  keystroke  test  for 
the  correct  first  letter  into  the  prot_ 
key  function  toward  the  beginning  of 
protocol,  c. 

Suppose,  for  example,  that  you 
wanted  to  add  the  CompuServe  B  pro¬ 
tocol  to  SMALLCOM.  Users  of  Compu¬ 
Serve  might  want  to  do  that,  and  the 
way  to  do  it  is  paved  by  an  article  in 
the  June  1986  issue  of  DDJ.  The  article, 
“The  CompuServe  B  Protocol:  A  Better 
Way  to  Send  Files”  by  Levi  Thomas  and 
Nick  Turner,  briefly  describes  the  pro¬ 
tocol.  Their  description  is  supported 
by  a  C  program  written  by  Steve  Wilhite. 
I  have  not  used  this  code,  but  it  imple¬ 
ments  the  CompuServe  B  protocol  in 
a  way  that  looks  as  if  it  would  be  read¬ 
ily  adaptable  to  the  SMALLCOM  archi¬ 
tecture.  The  authors  of  the  article  say 
the  code  is  in  the  public  domain,  but 
Wilhite  put  a  copyright  notice  in  the 
source  file.  Rather  than  mess  with  that 
contradiction  and  attempt  to  incorpo¬ 
rate  the  code  into  SMALLCOM,  I  will 
retreat  in  temerity  to  the  usual  refer¬ 
ence  book  position  and  leave  the  more 
difficult  task  as  an  exercise  for  the 
reader. 

XModem 

Almost  anyone  who  uses  modems  and 
online  services  knows  about  XModem. 
It  is  a  file-transfer  protocol  designed  in 


the  early  eighties  by  Ward  Christensen, 
who  placed  it — and  CP/M  programs 
that  implemented  it — into  the  public 
domain.  It  is  a  simple  and  effective 
protocol  that  provides  a  measure  of 
error  correction  during  the  transmission 
of  critical  files  between  computers.  For 
comprehensive  discussions  of  the 
XModem  protocol,  see  the  books  on 
serial  communications  I  cited  in  the 
last  two  months  or  get  a  copy  of  the 
June  1985  DDJ  and  read  “Christensen 
Protocols  in  C”  by  Donald  Krantz.  (The 
editorial  and  article  content  of  all  past 
issues  are  available  in  bound  volumes, 
by  year,  from  M&T  Publishing.) 

Writers  who  tackle  XModem  are 
quick  to  criticize  it  and  then  hasten  to 
congratulate  Christensen  who  gener¬ 
ously  gave  it  to  the  world.  Discussions 
of  its  deficiencies  are  a  favorite  pastime 
with  some  writers  who  do  not  ade¬ 
quately  acknowledge  XModem’s  origi¬ 
nal  purpose,  which  was  to  get  around 
the  line  hit  problems  people  were  hav¬ 
ing  trying  to  push  binary  data  around 
between  CP/M  microcomputers.  There 
was  nothing  about  XModem  that 
pushed  the  technology  when  it  was 
published.  It  is  a  simple  protocol  simi¬ 
lar  to  ones  that  were  being  used  in 
asynchronous  and  bisynchronous  com¬ 
munications  applications  in  the  mini¬ 
computers  of  the  middle  seventies.  It 
was  destined  to  become  a  standard, 
not  because  it  revolutionized  anything 
or  was  the  absolutely  best  way  to  solve 
the  problem  but  because  it  was  there  — 
working,  reliable,  and  available  to  any¬ 
one  who  needed  and  wanted  it.  If  Chris¬ 
tensen  had  not  put  it  into  the  public 
domain,  we  might  never  have  heard 
of  it.  Because  he  did,  it  became  a  roar¬ 
ing  success  and  remains  in  use  every¬ 
where. 

In  a  nutshell  (a  big  nutshell),  here  is 
how  the  XModem  protocol  works.  The 
sending  XModem  program  transmits  a 
file  to  a  receiving  XModem  program. 
To  manage  error  detection,  the  send¬ 
ing  program  adds  something  to  the 
data  that  relates  to  the  data  records 
themselves.  The  original  XModem  com¬ 
putes  and  transmits  a  simple  8-bit  check¬ 
sum  of  the  data  characters.  The  receiv¬ 
ing  program  calculates  the  checksum 
too,  and  if  the  calculated  checksum  is 
not  the  same  as  the  one  transmitted  by 
the  sender,  an  error  exists  in  either  the 
data  characters  or  the  checksum  itself. 
A  later  improvement  to  XModem  sub¬ 
stitutes  a  Cyclic  (or  Cyclical  — the 
authors  disagree.  One  author,  Campbell, 
disagrees  with  himself)  Redundancy 
Check  (CRC)  value  for  the  checksum, 
thus  tightening  up  the  error  detection. 

To  manage  error  correction,  the  re¬ 
ceiving  program  tells  the  sending  pro- 
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gram  whether  or  not  the  data  were 
received  correctly.  The  sending  pro¬ 
gram  then  either  sends  more  data  or 
resends  the  data  record  that  was  in 
error.  This  handshake  would  not  be 
efficient  if  it  were  used  on  the  entire 
file  at  one  clip.  So,  the  XModem  proto¬ 
col  breaks  the  file  into  fixed  length, 
128-byte  blocks  and  sends  them  one 
at  a  time. 

The  sending  program  cannot  begin 
sending  until  it  knows  that  the  receiver 
is  ready  to  receive.  The  sender  waits 
for  the  receiver  to  send  a  special  char¬ 
acter  that  gives  the  go-ahead.  The  sender 
and  receiver  might  be  two  different 
implementations  of  XModem.  Older  ver¬ 
sions  did  not  support  the  CRC,  so  newer 
ones  must  be  able  to  support  either  the 
CRC  or  the  checksum.  If  the  sender  is 
an  older  version,  it  simply  waits  for  a 
NAK  (an  international  transmission  con¬ 
trol  protocol)  (0x15)  from  the  receiver. 
If  the  sender  is  a  newer  version  it  waits 
for  either  the  NAK  or  a  ‘C.’  If  it  gets  a 
NAK,  it  uses  the  checksum.  If  it  gets  the 
‘C,’  it  uses  the  CRC.  If  the  receiver  is 
an  older  version,  it  sends  the  NAK  when 
it  is  ready  to  receive.  If  it  is  a  newer 
version,  it  does  not  know  yet  whether 
the  sender  can  support  the  CRC  or  not. 


So  it  sends  the  ‘C’  hoping  for  the  best. 
If  it  does  not  receive  the  SOH  (0x01) 
character,  which  identifies  the  start  of 
a  block,  it  tries  a  few  more  times  and 
then  sends  the  NAK. 

When  the  sender  knows  that  the  re¬ 
ceiver  is  ready,  the  sender  sends  a  block. 
Each  block  contains  the  SOH,  the  1- 
byte  block  number  (a  serial  number 
relative  to  one),  the  ones-complement 
of  the  block  number,  128  bytes  of  data, 
and  either  the  1-byte  checksum  or  the 
2-byte  CRC.  Then  it  waits  for  a  re¬ 
sponse  from  the  receiver.  After  the  last 
block,  the  sender  sends  the  single  EOT 
(0x04)  character  to  the  receiver. 

The  receiver  reads  all  this  stuff  and 
looks  at  it.  The  first  byte  must  be  the 
SOH  or  EOT  character.  If  the  EOT  char¬ 
acter  is  received,  the  receiver  sends  the 
ACK  (0x06)  character,  closes  the  file  it 
is  building,  and  assumes  the  transmis¬ 
sion  is  complete.  Otherwise  the  receiver 
looks  at  the  rest  of  the  packet.  The 
block  number  must  be  either  the  previ¬ 
ous  block  number  plus  one  or,  in  the 
case  of  a  retransmission,  the  previous 
block  number.  The  next  byte  must  be 
the  ones-complement  of  the  block  num¬ 
ber.  The  128-data  bytes  can  be  any¬ 
thing  at  all.  If  the  checksum  mode  is 
being  used,  the  checksum  must  be  the 


8-bit  sum  of  the  bytes  in  the  128-data 
field.  If  the  CRC  mode  is  being  used, 
the  two  CRC  bytes  must  be  the  CRC 
that  is  computed  from  the  128-data  bytes 
plus  two  more  bytes  of  a  zero  value.  If 
all  this  is  true,  the  receiver  writes  the 
data  block  to  the  file  it  is  building  and 
sends  the  ACK  character  to  the  sender. 
If  any  of  this  is  not  true,  or  if  the  re¬ 
ceiver  times  out  while  waiting  for  any 
of  the  above  from  the  sender,  the  re¬ 
ceiver  sends  the  NAK  (0x15)  character 
to  the  sender. 

If  the  sender  sees  the  ACK  character, 
it  proceeds  with  the  next  block.  Other¬ 
wise,  it  resends  the  block  that  was  just 
NAK’d. 

The  receiver  works  with  timeouts. 
While  it  is  waiting  for  the  SOH,  it  sets 
a  ten  second  timeout.  While  waiting 
for  each  of  the  other  bytes  of  the  packet, 
it  sets  a  one  second  timeout.  Timeouts 
and  error  detections  are  all  handled 
with  NAKs.  After  so  many  consecutive 
NAKs,  both  the  sender  and  receiver 
give  up  and  declare  the  transmission  a 
bust.  The  one-second  timeout  can  be 
too  short  for  use  with  services  that  go 
through  a  network.  The  network’s 
packet  overhead  on  a  busy  day  can 
exceed  one  second,  causing  the  re¬ 
ceiver  to  time  out.  If  this  gets  to  be  a 
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problem,  increase  the  timeout  to  some 
larger  value,  perhaps  five  seconds. 

Listing  Four,  page  134,  is  xmodem.c, 
the  functions  that  implement  the 
XModem  upload  and  download  file- 
transfer  protocols.  Notice  the  handling 
of  the  external  xonxoff_enabled  vari¬ 
able.  While  XModem  is  sending  and 
receiving  data,  the  XON  and  XOFF  pro¬ 
tocols  must  be  disabled.  The  data  be¬ 
ing  transmitted  can  consist  of  any  bytes 
of  any  value,  any  of  which  could  look 
like  the  XOFF  code.  If  XON/XOFF  pro¬ 
tocols  were  in  force  and  a  block  num¬ 
ber  or  checksum  looked  like  the  XOFF, 
the  serial  transmission  function  would 
think  it  was  being  told  by  the  other  side 
to  quit  transmitting.  It  would  then  wait, 
perhaps  forever,  for  the  XON  signal. 

Notice  also  the  test_u>ordlen  func¬ 
tion.  For  XModem  to  operate  properly, 
the  serial  port  must  be  programmed  for 
a  word  length  of  eight  data  bits.  This 
function  prevents  the  upload  or  down¬ 
load  from  starting  if  eight  data  bits  are 
not  programmed.  Christensen  specifies 
that  the  protocol  can  use  seven  bits  by 
clearing  the  most  significant  bit  of  the 
block  numbers  and  checksum  at  both 
ends  of  the  line,  but  this  would  work 
only  with  ASCII  files.  Other  files  need 
the  full  eight  bits  to  be  transmitted. 

I  am  not  going  to  attempt  to  explain 
why  the  CRC  algorithm  works  because 
I  do  not  know,  but  here  is  the  proce¬ 
dure  it  uses.  The  algorithm  builds  a 
16-bit  CRC  from  a  string  of  8-bit  bytes. 
The  CRC  starts  with  a  zero  value.  The 
following  steps  occur  for  each  byte  in 
the  string.  The  byte  is  concatenated  to 
the  right  of  the  CRC  to  form  a  24-bit 
value.  This  value  is  shifted  left  one  bit 
eight  times.  For  each  one-bit  shift,  if 
the  most  significant  bit  of  the  24-bit 
value  before  the  shift  is  a  one,  the 
value  0x1021  is  XORed  with  the  left¬ 
most  16  bits  (the  CRC  part)  of  the  new 
24-bit  value.  When  all  bytes  have  been 
processed  this  way,  the  leftmost  16  bits 
are  the  CRC.  This  algorithm  works  with 
XModem  and  should  work  with  Kermit 
as  well. 

The  CRC  is  built  by  the  compute_crc 
function.  You  pass  the  function  — a 
string  pointer  — and  the  number  of  bytes 
in  the  string.  A  better  and  more  mathe¬ 
matical  explanation  of  the  CRC  can  be 
found  in  most  of  the  references  already 
cited.  Perhaps  you  will  understand  it, 
although  that  is  not  necessary.  The  al¬ 
gorithm  works  and  we  know  how  to 
build  it.  I  looked  at  how  others  coded 
the  algorithm  and  wrote  the  one  you 
see  here.  Then  I  tested  it  by  transmit¬ 
ting  files  back  and  forth  between 
SMALLCOM  and  another  computer  that 
was  running  ProComm. 
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The  XModem  protocol  was  originally 
described  in  a  paper  published  by  Chris¬ 
tensen  in  the  fall  of  1982.  In  January  of 
1985  John  Byms  published  a  descrip¬ 
tion  of  the  logic  that  replaced  the  check¬ 
sum  with  a  CRC.  That  paper  included 
a  C  language  CRC  algorithm  that  does 
not  work  with  today’s  compilers.  From 
the  looks  of  it  the  code  would  not 
work  with  many  older  compilers  either. 
Both  papers  can  be  found  on  BBSs  and 
online  services  around  the  country.  Other 
descriptions  are  found  in  the  books 
and  articles  I’ve  already  mentioned. 

To  compile  and  build  the  phone  di¬ 
rectory  and  XModem  into  SMALLCOM, 
add  phonedir,  prototype,  and  XModem 
entries  to  the  smallcom.prj  file  for  Turbo 
C,  and  smallcom.mak  and  smallcom.lnk 
for  Microsoft  C.  These  files  were  in  last 
month’s  column. 

Not  Just  Another  Turbo  C  Book 

Most  of  the  C  books  in  the  bookstore 
have  “Turbo  C”  in  their  titles.  Many  of 
these  books  are  about  the  C  language 
itself  with  little  information  specific  to 
Turbo  C.  (Modesty  prevents  me  from 
pointing  out  the  one  outstanding  ex¬ 
ception.)  Now  my  “boss”  at  DDJ,  Kent 
Porter,  has  written  a  book  that  has  Turbo 
C  in  its  title,  and  is  about  C,  Turbo  C, 
the  PC,  and  good  programming  in  gen¬ 
eral.  There  are  chapters  on  how  DOS 
disks  and  files  work,  BIOS,  the  TC  video 
library,  popup  windows,  menus,  mice, 
graphics,  expanded  memory  manage¬ 
ment,  data  structures,  interrupt  func¬ 
tions,  and  plenty  more.  There  is  lots  of 
C  code  to  explain  the  lessons,  and  it  all 
works  by  using  the  unique  features  of 
Turbo  C. 

I  saw  the  manuscript  before  publi¬ 
cation.  I  really  like  the  book,  and  I  am 
not  saying  that  just  because  Kent  is  my 
editor.  As  I  write  this  column,  the  book 
is  not  yet  available  but  by  the  time  you 
read  the  column,  the  book  should  be 
available.  Its  title  is  Stretching  Turbo  C 
2.0  and  it  is  published  by  Brady  Books. 

Availability 

All  source  code  in  this  issue  is  available 
on  a  single  disk.  To  order,  send  $14.95 
(Calif,  resident  add  sales  tax)  to  Dr. 
Dobb’s Journal,  501  Galveston  Dr.,  Red¬ 
wood  City,  CA  94063,  or  call  800-356- 
2002  (inside  Calif.)  or  800-533-  4372 
(outside  Calif.).  Please  specify  the  is¬ 
sue  number  and  format  (MS-DOS,  Macin¬ 
tosh,  Kaypro). 

DDJ 
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Matching  My 
Wife’s  Wet 
Washcloth 


My  wife  and  I  have  an  arrange¬ 
ment  regarding  home  decor. 
We  didn’t  plan  it  this  way,  it’s 
just  how  it  happens.  She  de¬ 
cides  when  a  room  needs  redecorating 
and  what  needs  to  be  done.  Then  I  do 
all  the  work.  Afterwards  she  shows  it 
to  friends  and  says,  “Look  what  we 
did.”  That  plural  pronoun  always  both¬ 
ers  me  because,  after  all,  she  was  prob¬ 
ably  out  shopping  most  of  the  time  I 
was  toiling.  On  the  other  hand,  the 
“we”  might  be  fair  inasmuch  as,  if  left 
solely  up  to  me,  nothing  would  get 
done  around  the  house  beyond  replac¬ 
ing  dead  light  bulbs. 

Anyway  (and  there  is  a  point  to  this), 
some  years  ago  as  she  was  preparing 
to  put  me  to  work,  my  wife  took  a 
washcloth  to  the  paint  store  and  told 
the  guy,  “Wet  this  and  mix  a  paint 
that’s  the  same  color.”  Amazingly,  he 
was  able  to  do  it.  Starting  with  white, 
he  added  two  squirts  of  this  pigment, 
three  of  that,  one  of  another,  then  stirred 
it  up.  And  there  it  was,  a  perfect  match. 

We  might  not  be  able  to  exactly  du¬ 
plicate  the  color  of  my  wife’s  wet  wash¬ 
cloth  on  the  EGA  screen,  but  we  can 
probably  come  pretty  close.  And  the 
process  is  almost  the  same  as  the  sales¬ 
man  used  to  blend  the  paint.  We  prob- 
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ably  can  match  it  exactly  in  VGA  256 
color  mode;  however,  that’s  significantly 
more  complicated  than  EGA  colors,  so 
we’ll  put  it  off  until  later.  As  pointed 
out  in  earlier  columns,  the  VGA  be¬ 
haves  just  like  the  EGA  when  in  an 
EGA  graphics  mode  or  640x480  16- 
color  mode,  so  this  discussion  applies 
to  both. 

Graphics  images  are  made  from  pix¬ 


els,  which  in  turn  are  represented  by 
bit  patterns  in  programs.  The  color  that 
a  pixel  assumes  on  the  screen  is  a 
function  of  the  bit  pattern  placed  in  the 
video  buffer’s  corresponding  location. 
Therefore  a  pixel’s  data  representation 
value  determines  its  color,  right? 

Well,  not  really.  There’s  a  data  struc¬ 
ture  between  the  video  buffer  and  the 
screen  itself,  the  contents  of  which  gov¬ 
erns  the  mapping  of  pixel  values  to 
actual  colors.  This  data  structure  is  called 
the  color  palette. 

The  name  no  doubt  derives  from  an 
analogy  to  the  artist’s  palette,  a  board 
containing  an  array  of  colors  from  which 
the  artist  selects  as  he  or  she  paints. 
That’s  apt,  because  the  EGA  palette  is 
an  electronic  equivalent.  It  holds  an 
array  of  16  colors  in  elements  called 
registers.  A  pixel  value  is  simply  an 
index  into  this  array.  When  you  stuff 
pixel  value  2  into  the  video  buffer,  in 
effect  you  say,  “I  want  this  pixel  to 
have  the  color  contained  in  palette 
register  2.” 

As  it  refreshes  the  screen,  the  video 
controller  grabs  a  pixel  value  from  the 
video  buffer,  then  uses  that  value  to 
locate  the  actual  color  in  the  palette. 
That’s  how  color  mapping  occurs,  and 
why  EGA  pixel  values  must  be  in  the 
range  0  - 15. 

So  how  does  a  palette  register  con¬ 
trol  the  actual  color?  Through  a  rather 
oddly  arranged  6-bit  number  that  gov¬ 
erns  the  intensities  of  the  three  basic 
colors  — red,  green,  and  blue  — from 
which  all  displayable  hues  are  derived. 

Because  a  6-bit  number  can  repre¬ 
sent  64  different  values,  the  EGA  is 
capable  of  displaying  64  colors.  How¬ 
ever,  there  can  be  a  maximum  of  only 
16  at  a  time  due  to  the  size  of  the 
palette.  You  can  instantly  change  the 
color  of  all  instances  of  a  given  pixel 


value  by  changing  the  contents  of  its 
corresponding  palette  register,  but  you 
can’t  do  anything  on  an  EGA  to  get 
more  than  16  out  of  64  colors  at  one 
time;  it’s  a  hardware  limitation.  If  you 
gotta  have  more,  get  a  VGA,  which 
does  256  colors  at  a  time  from  a  total 
selection  of  262,144.  Still,  16  out  of  64 
colors  at  a  resolution  of  640x350  is 
enough  to  do  some  pretty  respectable 
graphics. 

The  EGA  initializes  its  palette  to  the 
same  color  sequence  as  the  CGA’s  fixed 
text  colors.  This  provides  the  default 
pixel  value-to-color  mapping  shown 
in  Table  1.  The  program  COLORS. C  in 
Listing  One,  page  138,  displays  the  de¬ 
fault  EGA  palette.  The  program  must 
be  linked  with  GRAFIX.LIB  developed 
in  earlier  installments  of  this  column. 


Value 

Color 

0 

Black 

1 

Blue 

2 

Green 

3 

Cyan 

4 

Red 

5 

Magenta 

6 

Brown 

7 

Light  gray 

8 

Dark  gray 

9 

Light  blue 

10 

Light  green 

11 

Light  cyan 

12 

Light  red 

13 

Light  magenta 

14 

Yellow 

15 

White 

Table  1:  Default  color  palette  for  the 
EGA  and  VGA 
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If  you’ve  done  much  color  program¬ 
ming  in  text,  you’ve  probably  got  the 
default  values  so  engraved  in  your  mind 
that  14  and  yellow  have  become  syn¬ 
onymous.  The  ability  to  change  palette 
registers  to  any  color  you  want  means 
you’ll  have  to  break  an  old  habit.  From 
now  on,  pixel  value  14  refers  to  what¬ 
ever  is  in  palette  register  14  at  the  time. 

Squirts  of  Pigment 

The  guy  that  matched  my  wife’s  wash¬ 
cloth  made  the  color  by  squirting  vari¬ 
ous  quantities  of  one  pigment  and  an¬ 
other  into  a  white  base.  The  process 
of  creating  EGA  colors  is  similar,  ex¬ 
cept  that  we  start  from  a  base  of  black. 

Display  colors  are  hues  blended  by 
combining  various  measures  of  three 
primary  colors:  red,  green,  and  blue. 
These  measures  are  actually  intensities 
ranging  from  none  (black)  through 
bright.  There  are  four  intensities  of  each 
primary  color,  which  is  how  we  get  64 
possible  colors  on  the  EGA  (43).  Here’s 
how  it  works. 

A  byte  contains  eight  bits,  but  a  pal¬ 
ette  register  is  a  6-bit  value.  Conse¬ 
quently  the  two  high-order  bits  are 
“don’t  care”  and  the  remaining  low  six 
bits  convey  color  information.  It  doesn’t 
take  a  degree  in  math  to  figure  out  that, 
with  three  colors  and  six  bits,  there  are 
two  bits  per  primary  color,  and  that 
each  set  of  two  bits  can  represent  any 
of  four  intensities. 

What  is  not  so  obvious  is  how  those 
bits  are  arranged.  The  designers  of  the 
EGA  no  doubt  had  their  reasons  for 
doing  it  as  they  did,  but  I  don’t  know 
what  those  reasons  were.  And  whether 
it  makes  sense  or  not,  it’s  how  it  is. 

The  palette  bits  are  arranged  in  the 
order  rgbRGB,  where  lower  case  indi¬ 
cates  lower  intensity.  Thus  the  palette 
value  xxlOOOOO  (binary)  is  a  very  dark 


Name 

Binary 

Hex 

REDO 

000000 

0x00 

RED1 

100000 

0x20 

RED2 

000100 

0x04 

RED3 

100100 

0x24 

GRN0 

000000 

0x00 

GRN1 

010000 

0x10 

GRN2 

000010 

0x02 

GRN3 

010010 

0x12 

BLU0 

000000 

0x00 

BLU1 

001000 

0x08 

BLU2 

000001 

0x01 

BLU3 

001001 

0x09 

Table  2:  Symbolic  names  for  the  pri¬ 
mary  color  intensities 


shade  of  red,  and  palette  value  xxOOOOl  1 
is  light  cyan  (a  combination  of  bright 
blue  and  bright  green).  Turning  all  bits 
on  yields  pure  white,  while  resetting 
all  bits  produces  black,  or  the  absence 
of  any  color  component. 

The  default  palette  colors  are  grouped 
according  to  “normal”  and  “intense” 
hues.  Thus  registers  0-7  hold  a  se- 

The  designers  of  the 
EGA  no  doubt  had 
their  reasons  for  doing 
it  as  they  did,  but  I 
don’t  know  what  those 
reasons  were 


quence  of  colors  with  normal  intensity, 
and  8-15  contain  their  brighter  coun¬ 
terparts  in  the  same  sequence.  The  pri¬ 
mary  colors  (red,  green,  and  blue)  in 
the  lower  range  are  actually  of  intensity 
level  2,  or  one  level  away  from  bright¬ 
est.  The  default  palette  doesn’t  display 
any  low-intensity  primary  colors,  which 
tend  to  be  quite  dim  on  the  display  and 
are  thus  mostly  useful  for  mixing  to 
create  composite  colors. 

An  example  is  brown.  It’s  composed 
of  red  level  2  and  green  level  1 .  To  get 
this  mixture,  set  the  bits  as  follows: 

rgbRGB 


010100 

This  yields  the  value  I4h.  Notice  that 
brown  contains  no  blue  component, 
so  bits  b  and  B  are  both  0.  This  corre¬ 
sponds  to  blue  level  0,  or  in  other 
words  the  absence  of  blue. 

Adding  blue  level  1  to  the  mix 
(011100b)  is  the  same  as  squirting  a 
little  blue  pigment  into  tan  paint.  The 
outcome  is  mauve,  which  is  a  sort  of 
washed-out  purple.  If  instead  we  take 
brown  and  “promote”  both  its  colors 
upward  one  level  (to  green  2  and  red 
3,  represented  as  1001 10b)  we  get  bright 
brown,  or  in  other  words  yellow. 

Because  each  of  the  primary  color 
levels  is  represented  by  a  fixed  bit  pat¬ 
tern,  we  can  give  them  symbolic  names 
to  improve  program  readability.  Table 


2  shows  the  mapping  of  names  to  bit 
patterns.  Using  them,  we  can  construct 
color  palette  values  with  expressions 
such  as 

brown  =  GRN1  I  RED2; 

My  colleagues  in  the  publishing  busi¬ 
ness  have  a  name  for  this  technique  of 
forming  hues  by  mixing  measures  of 
three  primary  colors:  They  call  it  color 
separation.  To  me  that’s  backwards. 
It’s  really  color  combination.  Whatever 
you  call  it,  it  works  for  the  painter,  the 
printer,  and  the  programmer.  Later  in 
this  article  we’ll  look  at  a  program  that 
you  can  use  to  experiment  with  color 
mixing  on  the  EGA. 

Adding  EGA  Colors 
to  ihe  GRAFIX  Library 

In  order  to  support  EGA  colors,  we 
need  to  modify  the  GRAFIX.H  header 
file  that  we’re  building  and  add  some 
functions  to  the  library. 

Each  month  we’ll  be  adding  some¬ 
thing  to  the  header  file,  so  I’ll  list  that 
entire  file  with  the  additions  set  apart 
and  labeled  by  a  heading  indicating 
the  month  they  appeared.  As  you  can 
see  from  Listing  Two,  page  138,  this 
month  we’re  adding  color  constants 
and  the  definition  of  a  byte  type  to  the 
top  of  GRAFIX.H,  and  four  functions 
to  the  bottom. 

The  functions  themselves  are  defined 
in  EGAPALET.C  (Listing  Three,  page 
138).  You  should  compile  this  file  to 
an  .OBJ,  then  add  it  to  the  GRAFIX 
library  with  the  DOS  command 

LIB  GRAFIX  +EGAPALET; 

Let’s  look  at  what  this  program  module 
does. 

Because  it’s  declared  outside  the 
scope  of  any  function,  the  ega_  palette 
array  is  a  static  visible  to  the  four  func¬ 
tions  in  this  compile  unit.  Furthermore, 
it’s  initialized  to  the  default  colors  of 
the  real  palette.  Note  that  this  is  our 
copy  of  what’s  in  the  palette  known  to 
the  video  controller;  it’s  not  the  palette. 
Because  it  carries  the  same  values  at 
initialization  as  the  video  controller’s, 
and  because  the  palette-setting  func¬ 
tion  maintains  it,  we  can  safely  assume 
that  the  local  copy  always  accurately 
reflects  the  colors  appearing  on  the 
display. 

The  ega _palreg( )  function  returns 
the  color  value  in  a  given  palette  regis¬ 
ter.  Pass  it  the  register  number  (that  is, 
pixel  value)  and  the  function  returns 
the  6-bit  composite  color  pattern  from 
that  register. 

Note  that  the  ROM  BIOS  video  serv¬ 
ices  furnish  function  lOh,  subfunction 
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7,  to  read  a  hardware  palette  register 
directly.  If  you  put  lOh  in  register  AH, 
7  in  register  AL,  and  the  register  num¬ 
ber  in  BL,  then  execute  interrupt  lOh , 
you  get  the  color  pattern  back  in  regis¬ 
ter  BH.  This  is  an  alternative  that  is 
slightly  safer  than  returning  a  value 
from  the  phantom  software  palette,  but 
it  incurs  the  heavy  overhead  of  calling 

Because  each  of  the 
primary  color  levels 
is  represented  by  a  fixed 
bit  pattern,  we  can 
give  them  symbolic 
names  to  improve 
program  readability 

the  ROM  BIOS.  Consequently  we  use 
the  method  given  here  in  the  interest 
of  performance. 

The  next  function,  ega_blend( ),  is 
a  color  pattern  constructor.  It  combines 
the  primary  components  into  a  byte 
that  you  can  then  load  into  a  palette 
register  or  use  for  other  purposes.  For 
example,  to  make  brown,  write 

brown  =  ega_blend  (RED2,  GRN1, 

BLUO); 

Note  that  the  order  of  arguments  with 
respect  to  color  sequence  doesn’t  mat¬ 
ter.  The  function  simply  combines  bits. 
Thus, 

brown  =  egajblend  (BLUO,  GRN1, 

RED2); 

produces  exactly  the  same  result. 

The  get_ega_colormix( )  function  is 
the  opposite  of  ega_blend( ).  It  explodes 
the  content  of  a  given  palette  register 
into  its  three  primary  color  intensities. 
Here  the  sequence  of  color  arguments 
is  significant,  and  additionally  the  ar¬ 
guments  must  be  addresses  of  receiv¬ 
ing  variables  (since  a  function  can  re¬ 
turn  only  one  value  directly).  The  func¬ 
tion  derives  the  bit  patterns  by  ANDing 
the  register  contents  with  each  of  the 
most  intense  primary  values,  thus,  iso¬ 
lating  the  appropriate  bits. 

The  final  function  is  set_ega _palreg( ), 


which  places  a  new  color  pattern  into 
the  given  palette  register.  The  function 
updates  the  local  copy  of  the  palette, 
then  uses  the  ROM  BIOS  video  serv¬ 
ices  — unavoidable  in  this  case  — to 
change  the  hardware  setting.  The  ef¬ 
fect  of  this  function  is  to  instantly  change 
all  instances  of  the  corresponding  pixel 
to  the  new  color  on  the  display. 

Listing  Four,  page  138,  is  a  utility 
program  that  you  can  use  to  experi¬ 
ment  with  EGA  color  combinations. 
To  get  it  up  and  running,  compile  MIX.C, 
then  link  with  GRAFEX.LIB. 

This  program  displays  a  4x3  array 
of  filled  rectangles  showing  the  four 
intensities  each  of  red,  green,  and  blue 
(the  leftmost  is  black,  the  lowest  possi¬ 
ble  intensity  corresponding  to  REDO, 
GRNO,  and  BLUO).  A  large  filled  rectan¬ 
gle  at  the  bottom  of  the  screen  contains 
the  current  color  mixture;  it  starts  out 
bright  white,  because  the  most  intense 
of  all  three  primary  shades  is  selected. 

A  white  rectangle  surrounds  one  box 
in  each  color  row.  This  is  an  indicator 
showing  which  intensity  is  currently  a 
component  of  the  color  at  the  bottom. 
To  move  the  indicator  for  red  to  a 
lower  intensity,  type  r.  The  indicator 
shifts  left  and  the  color  bar  at  the  bot¬ 
tom  immediately  changes  to  pale  cyan. 
To  move  the  red  indicator  to  its  brighter 
neighbor,  type  uppercase  R.  You  can 
similarly  control  green  with  g  and  G, 
and  blue  with  b  and  B.  Quit  by  press¬ 
ing  Esc;  the  program  then  shows  the 
breakdown  of  the  color  most  recently 
constructed. 

The  local  functions  in  MIX.C  reveal 
how  it  works.  The  setup _palette(  )  func¬ 
tion  loads  reds  into  palette  registers 
1-4,  greens  into  5-8,  and  blues  into 
9-12.  Palette  register  13  drives  the 
color  sample  at  the  bottom  of  the  screen. 
setup, _screen( )  constructs  the  work 
display. 

Most  of  the  program’s  work  is  done 
by  mix_colors( ),  a  loop  that  repeats 
until  you  press  Esc.  The  loop  gets  a 
keystroke,  then  acts  on  it  via  a  switch( ) 
whose  cases  vary  depending  on  the 
keystroke.  The  RAISE  and  LOWER  mac¬ 
ros  ensure  that  the  indicator  box  re¬ 
mains  within  the  four  possible  inten¬ 
sity  selections.  After  the  switch( )  com¬ 
pletes,  the  new  color  mixture  is  com¬ 
puted  and  this  value  updates  palette 
register  13,  instantly  changing  the  color 
sample  box. 


The  main( )  function  itself  does  little 
besides  reporting  the  results  after 
mix_colors( )  completes.  The  results 
make  MIX  more  than  just  a  toy  or  an 
example  of  how  to  use  the  graphics 
library  we’re  constructing.  Use  it  as  a 
utility  for  designing  the  colors  you  want 
to  use  elsewhere,  and  the  results  report 
to  code  your  program. 

Who  knows?  One  of  the  colors  you 
mix  might  match  my  wife’s  wet  wash¬ 
cloth. 

Availability 

All  source  code  for  articles  in  this  issue 
is  available  on  a  single  disk.  To  order, 
send  $14.95  (Calif,  residents  add  sales 
tax)  to  Dr.  Dobb’s Journal,  501  Galves¬ 
ton  Dr.,  Redwood  City,  CA  94063,  or 
call  800-356-2002  (inside  Calif.)  or  800- 
533-4372  (outside  Calif  ).  Please  spec¬ 
ify  the  issue  number  and  format  (MS- 
DOS,  Macintosh,  Kaypro). 

DDJ 

(Listings  begin  on  page  138.) 

Vote  for  your  favorite  feature/article. 
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STRUCTURED  PROGRAMMING 


Three 

Little  Words 


The  publisher  of  the  London  Star 
(a  sort  of  National  Enquirer  for 
scone-eaters)  has  taken  a  survey 
indicating  that  the  three  most  at¬ 
tention-getting  words  for  the  British  audi¬ 
ence  are  (in  order)  “sex,”  “win,”  and 
“free."  The  chap  said  that  if  he  could 
run  a  contest  with  a  banner  reading, 
“Win  free  sex!”  he’d  be  the  only  news¬ 
paper  left  in  London.  After  twenty  years 
of  trying  to  avoid  seeing  the  tabloids 
down  at  the  Piggly  Wiggly  checkout 
counter,  I’d  have  to  say  the  three  equiva¬ 
lent  words  to  American  eyes  are  “mur¬ 
der,”  “UFOs,”  and  “Elvis.”  (Which  makes 
one  long  to  run  a  story  with  the  head¬ 
line,  “UFOs  murder  Elvis!”  but  alas,  it 
didn’t  happen  that  way.) 

Given  that  real  programmers  keep 
their  pants  on  and  listen  to  Boz  Scaggs, 
what  would  you  imagine  are  the  three 
most  attention-getting  words  on  the  cov¬ 
ers  of  computer  magazines?  My  bet 
would  fall  to  “windows,”  “speed,”  and 
“graphics.”  (“Speed  windows  graph¬ 
ics!”  is  a  cry  Microsoft  has  been  ignor¬ 
ing  for  years.  .  .  .) 

These  three  words  make  for  strange 
bedfellows,  given  that: 

•  Our  machines  are  not  fast  enough  to 
do  graphics  at  a  speed  I  find  accept¬ 
able.  My  benchmark  is  this:  Slow 
enough  to  watch  is  way  too  slow.  Last 
weekend  I  was  down  at  Fry’s,  shaking 
my  head  behind  the  yokels  who  were 
marveling  at  Macintosh  II  graphics.  The 
II  was  taking  seconds  to  redraw  a  win¬ 
dow.  Landfill.  Ajnd  that’s  supposedly 
the  fastest  machine  you  can  buy  south 
of  ten  grand.  .  .  . 

Jeff  Duntemann,  K16RA 

•  Our  screens  are  not  big  enough  to 
divide  even  once,  much  less  several 
times.  The  smallest  screen  I  would  con¬ 
sider  dividable  is  19-inch  diagonal,  with 
1024  x  1200  graphics  and/or  132  x  66 
text.  A  century  of  work  with  the  66-line 
typewritten  page  has  trained  us  to  see 
such  a  page  as  a  “glanceable  unit,”  and 
we  are  usually  capable  of  spotting  key¬ 
words  on  such  a  page  without  close 

120 


reading.  Most  of  us  think  in  terms  of  will  have  to  do  us  until  the  rest  of  you 
8'/2-inch  by  1 1-inch  pages.  A  25-line  guys  catch  on,  and  all  buy  66-line  text 
screen  is  an  infuriating  straitjacket.  screens.  (The  Micro  Display  Systems’ 

I  have  often  grimaced,  seeing  maga-  Genius  VHR  has  been  out  there  for 
zines  present  code  for  windowing  sys-  four  years,  and  you  can  buy  one  from 
terns  targeted  at  a  25-line  or  350-pixel  47th  Street  Computer  in  Nuh  Yawk  for 
screen.  This  is  the  wrong  way  to  be  $999  ) 
moving,  folks.  We  should  be  modeling 

full  typewritten  pages  on  our  screens,  Anatomy  of  a  V  Screen 
not  postage  stamps.  A  virtual  screen  is  virtual  for  the  same 

So,  if  you’ve  been  wondering  what  reason  that  virtual  memory  is  virtual: 
I’ve  been  leading  up  to  in  the  last  two  The  hardware  display  doesn’t  have 
columns,  it’s  this:  I’m  building  a  sort  enough  screen  to  show  a  full  page,  so 
of  anti-windowing  system.  Rather  than  you  have  to  put  part  of  the  page  else- 
specifying  a  rectangular  subset  of  the  where  and  bring  pieces  of  the  full  page 
screen  as  a  window,  I’ll  be  specifying  onto  the  display  as  needed, 
the  hardware  display  as  a  window  into  Our  “elsewhere”  is  the  heap,  and  the 
a  he-man’s  66-line  virtual  screen.  This  (continued  on  page  122) 


Firgure  1:  The  architecture  of  a  virtual  screen 
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(continued  from  page  120) 
whole  thing  is  held  together  with  point¬ 
ers  in  a  highly  memory-efficient  fash¬ 
ion.  (Turbo  Pascal  is  every  bit  as  clever 
with  pointers  as  C  is.  Maybe  more.) 
Figure  1  is  a  schematic  of  the  memory 
architecture  of  a  virtual  screen.  Follow 
along  on  the  figure  during  the  follow¬ 
ing  discussion. 

What  should  a  virtual  screen  allow 
us  to  do?  The  key  is  this:  We  are  model¬ 
ing  a  piece  of  paper.  Ideally,  we  should 
be  able  to  write  text  to  any  location  on 
the  virtual  screen  without  worrying 
about  whether  any  given  portion  of  the 
screen  is  currently  displayed  or  not. 
Independently,  we  should  be  able  to 
pan  the  visible  window  into  the  virtual 
screen  at  will,  by  one  line  or  any  other 
number  of  lines  at  a  time. 

The  important  thing  is  that  we  aban¬ 
don  the  visible  display  as  a  reference 
frame.  Line  1  is  the  first  line  of  the 
virtual  screen,  whether  visible  or  not. 
The  visible  display  becomes  a  window 
that  we  slide  up  and  down  the  virtual 
screen,  inspecting  it  at  will. 

Right  off,  this  forces  us  to  abandon 
the  PC’s  hardware  cursor,  which  is  a 
prisoner  of  the  current  visible  display. 
Abandoning  the  hardware  cursor  is  prob¬ 
ably  a  good  idea.  The  PC’s  cursor  man¬ 
agement  firmware  is  bug  ridden  and 
quirky,  and  I’d  just  as  soon  turn  the 
sorry  thing  off  and  leave  it  off.  (Turn¬ 
ing  it  off  is  easy.  Turning  it  back  on 
again  is  not  — but  those  are  tales  for 
another  time.) 

Physically,  the  virtual  screen  is  a  col¬ 
lection  of  blocks  of  memory  on  the 
heap,  with  one  block  allocated  for  each 
line  on  the  virtual  screen.  The  virtual 
screen  is  held  together  with  a  descrip¬ 
tor  record  having  the  structure  shown 
in  Listing  One,  page  142. 

Here,  HEIGHTis  a  constant  that  speci¬ 
fies  the  number  of  lines  (counting  from 
1)  in  the  virtual  screen.  I  use  66,  model¬ 
ing  our  typical  letter-size  paper  sheet 
at  the  traditional  six  lines  of  type  per 
inch.  You  can,  however,  change  HEIGHT 
to  some  other  value  to  model  legal-size 
paper  (84  lines)  or  one  of  the  Euro¬ 
pean  paper  sizes.  For  now,  don’t  probe 
the  internal  structure  of  individual  lines 
(I’ll  get  to  that  later),  but  simply  think 
of  them  as  storage  arrays  for  text. 

For  simplicity’s  sake,  I  have  designed 
the  virtual  screen  system  so  that  the 
size  of  the  screens  is  fixed  at  compile 
time,  and  only  one  size  of  screen  (that 
specified  by  the  constants  HEIGHT  and 
WIDTH)  is  supported  at  once.  If  fields 
were  added  to  the  record  screen  to 
describe  the  screen’s  dimensions,  the 
size  of  a  screen  could  be  specified  at 
screen  initialization  time;  that  is,  the 


time  when  a  screen  is  created  on  the 
heap  with  the  InitScreen  procedure. 
Some  complication  would  have  to  be 
added  to  the  supporting  procedures 
and  functions,  but  it’s  not  impossible 
or  even  especially  difficult,  and  might 
be  worth  it  to  be  able  to  support  the 
modeling  of  both  letter  and  legal  paper 
in  the  same  application  at  the  same 
time. 

The  heart  of  the  virtual  screen  record 
is  a  pair  of  arrays  of  pointers,  ShowPtrs 
and  StorePtrs.  The  differences  between 
their  purposes  are  subtle  but  impor¬ 
tant:  StorePtrs  points  to  where  the  vir¬ 
tual  screen  information  is  stored.  The 
pointers  in  StorePtrs  are  initialized  at 
screen  initialization  time  and  never 
change  until  the  screen  is  disposed  of. 
ShowPtrs,  by  contrast,  contains  point¬ 
ers  that  are  used  to  direct  display  out¬ 
put;  that  is,  where  the  information  is 
to  be  shown,  hence  the  name.  Some 
of  ShowPtrs?  pointers  point  into  the 
display  adapter’s  visible  refresh  buffer. 
The  rest  point  to  lines  in  the  virtual 
screen  on  the  heap.  Which  pointers 
point  where  is  the  key  to  this  whole 
virtual  business. 

When  the  virtual  screen  is  initialized 
with  InitScreen,  the  first  VisibleY point¬ 
ers  are  set  to  point  into  successive  160- 
byte  regions  in  the  display  adapter  re¬ 
fresh  buffer,  starting  at  the  address  given 
in  TextBufferOrigin.  (Both  VisibleY  and 
TextBufferOrigin  are  initialized  and  ex¬ 
ported  by  the  Textlnfo  unit  I  described 
last  month.  VisibleY  contains  the  num¬ 
ber  of  lines  currently  displayed  on  the 
screen,  and  TextBufferOrigin  is  a  pointer 
pointing  to  the  first  byte  of  the  display 
adapter  refresh  buffer.) 

The  field  TopLine  in  the  descriptor 
record  stores  the  number  of  the  virtual 
screen  line  shown  at  the  top  of  the 
visible  display.  In  Figure  1,  this  is  line 
7;  note  that  ShowPtrs[7]'\s  the  first  pointer 
in  the  array  that  points  into  the  physi¬ 
cal  display  refresh  buffer,  rather  than 
into  the  virtual  screen  itself.  Starting 
with  the  index  stored  in  TopLine,  a 
number  of  pointers  corresponding  to 
the  number  of  visible  lines  (  VisibleY) 
point  into  the  visible  refresh  buffer. 

Writing  to  the  screen  is  easy.  We 
don’t  have  to  know  whether  the  line 
to  which  we  wish  to  write  is  currently 
visible.  If  we  want  to  write  to  line  8, 
we  specify  line  8  with  a  custom  GotoXY 
procedure,  and  then  the  WriteTo  pro¬ 
cedure  will  send  the  output  to  what¬ 
ever  line  is  pointed  to  by  ShowPtrs[8], 
If  ShowPtrs[8]  points  to  a  line  on  the 
visible  display,  we  see  the  output  im¬ 
mediately;  if  ShowPtrs[8]  instead  points 
to  a  line  in  the  virtual  screen,  we  won’t 
see  the  output  and  will  have  to  pan  the 


visible  display  until  the  newly  written 
line  comes  into  view. 

Panning  Hie  Screen 

Sliding  the  visible  display  up  and  down 
as  a  “window”  into  the  virtual  screen 
is  by  far  the  trickiest  part  of  SCREENS 
.PAS  (Listing  Two,  page  142).  Regard¬ 
less  of  which  direction  the  pan  opera¬ 
tion  takes,  the  work  is  all  done  within 
procedure  pan.  Understanding  pan  is 
best  done  by  looking  to  Figure  1  dur¬ 
ing  the  following  discussion. 

Accomplishing  a  pan  involves  a  num¬ 
ber  of  separate  tasks,  each  of  which 
must  be  accomplished  in  a  specific  or¬ 
der.  It’s  possible  to  perform  both  an 
upward  and  a  downward  pan  using 
the  same  run  of  code,  but  the  algorithm 
is  more  straightforward  by  testing  for 
the  direction  of  the  pan  and  using  a 
separate  sequence  of  statements  for 
each  of  the  two  directions.  The  follow¬ 
ing  sequence  is  for  a  downward  pan; 
that  is,  sliding  the  visible  window  such 
that  first  line  1  is  at  the  top,  then  line 
2,  then  line  3,  and  so  on. 

By  Hie  Numbers 

1 .  Make  sure  that  the  pan  will  not  take 
the  visible  display  beyond  the  array 
bounds  of  the  virtual  screen.  To  do  so 
would  trigger  a  runtime  range  error  if 
range  error  trapping  is  enabled.  If  range 
error  trapping  is  not  enabled,  the  pro¬ 
gram  will  behave  erratically  and  prob¬ 
ably  abort  to  DOS.  If  a  multiple-line 
pan  would  take  the  visible  display  out 
of  range,  but  some  number  of  lines 
remain  between  the  limit  of  the  visible 
display  and  the  end  of  the  virtual  screen, 
the  number  of  lines  in  the  pan  {By 
Lines)  is  adjusted  so  that  the  pan  “just 
makes  it.” 

2.  Copy  the  newly  hidden  line  or 
lines  from  the  visible  display  to  the 
virtual  screen.  Remember  that  I/O  to  a 
virtual  screen  may  be  sent  to  either  the 
refresh  buffer  or  to  the  virtual  screen 
lines  allocated  on  the  heap.  A  visible 
line  may  contain  data  that  does  not 
exist  in  the  visible  line’s  virtual  coun¬ 
terpart  on  the  heap.  Therefore,  each 
time  a  visible  line  or  lines  “roll  off’  the 
top  or  bottom  of  the  visible  screen, 
those  lines  must  be  copied  into  their 
corresponding  virtual  lines. 

3.  Glitch  the  portion  of  ShowPtrs  that 
points  into  the  visible  refresh  buffer 
down  by  the  number  of  lines  in  the 
pan.  If  the  top  line  being  displayed  is 
7  (as  shown  in  Figure  1)  the  series  of 
pointers  beginning  at  ShowPtrs[7]  must 
be  moved  down  the  array  by  4  bytes 
(the  size  of  a  Turbo  Pascal  pointer)  so 
that  what  was  ShowPtrs! 7]  becomes 
ShowPtrs[8]  and  so  on.  The  number  of 
pointers  involved  depends  on  the  num- 
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ber  of  lines  in  the  visible  display,  which 
is  given  by  global  variable  VisibleY. 
The  glitch  is  done  with  a  simple  call  to 
Turbo  Pascal’s  Move  statement. 

4.  Repoint  ShowPtrd  pointers  to  the 
newly-hidden  lines  back  into  the  vir¬ 
tual  screen.  Step  3  copied  the  data  in 
those  lines  from  the  visible  refresh  buffer 
into  their  corresponding  lines  on  the 
heap.  Here  we  must  now  repoint  the 
pointers  that  used  to  point  into  the 
visible  refresh  buffer  back  into  the  heap. 
This  is  done  simply  by  assigning  the 
corresponding  pointers  from  StorePtrs 
(which  always  point  onto  the  heap) 
into  their  twins  in  ShowPtrs. 

5.  Glitch  the  visible  display  upward 
by  the  number  of  lines  in  the  pan.  It 
may  seem  counterintuitive  at  first,  but 
to  slide  the  window  downward  you 
must  glitch  the  display  upward.  Think 
of  it  this  way:  When  you  pass  a  cow 
on  the  Interstate,  you're  moving  for¬ 
ward,  but  the  cow  appears  to  move 
backward.  As  Einstein  would  say,  Eve¬ 
rything’s  relative.  The  glitch  itself  is  done 
by  a  call  to  the  firmware  scrolling  rou¬ 
tines  in  ROM  BIOS  video  interrupt  10H. 

6.  Copy  the  newly- visible  line  or  lines 
from  the  virtual  screen  on  the  heap  into 
the  visible  refresh  buffer.  Glitching  the 
display  leaves  a  blank  line  or  lines, 
which  must  be  filled  with  lines  from 
the  virtual  screen.  This  is  the  mirror- 
image  to  step  2,  and  is  done  quickly 
with  Turbo  Pascal’s  Move  procedure. 

7.  Finally,  update  the  TopLine  counter 
in  the  virtual  screen’s  descriptor  re¬ 
cord.  The  top  line  shown  in  the  visible 
display  has  changed,  and  TopLine  must 
always  reflect  the  number  of  that 
top  line. 

To  Virtualize  or  Not  to  Virtualize 

I  can  hear  the  screams  already:  That 
sliding  a  window  up  and  down  all  the 
time  is  a  monstrous  violation  of  good 
ergonomic  software  design.  And  that’s 
true  .  .  .  but  the  key  is  the  phrase  “all 
the  time.”  Simply  having  virtual  screens 
does  not  require  that  you  use  them  in 
all  cases.  I  might  also  add  that  you  can 
use  them  well  or  you  can  use  them 
badly,  just  as  with  a  paring  knife  or 
false  eyelashes. 

A  little  cleverness  can  help  a  lot.  A 
66-line  form  might  be  designed  in  three 
major  portions:  The  top  25  lines  as  one 
portion,  the  next  18  lines  as  the  second 
section,  and  the  remaining  23  lines  as 
the  third  section.  Why?  A  person  with  a 
25-line  screen  gets  the  top  section  at  a 
glance,  pans  down  to  pick  up  the  mid¬ 
dle  18  lines,  and  then  pans  again  to  get 
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the  final  23  lines.  A  person  with  an  EGA 
or  VGA  can  read  the  top  two  sections 
(totalling  43  lines)  at  a  glance,  with  one 
pan  down  to  see  the  last  23  lines. 

A  person  with  a  Genius  tube,  of 
course,  gets  the  whole  meatball  in  one 
glance  and  doesn’t  need  to  pan  at  all. 
If  you  have  enough  fields  on  a  form  to 
fill  66  lines,  you’re  going  to  have  to 
manage  multiple  forms  for  25,  43,  and 
50  line  screens  anyway.  Designing  a 
form  in  this  fashion  manages  multiple 
forms  for  you  without  any  change  in 
the  software. 

And  then,  once  the  form  is  com¬ 
pleted  in  the  virtual  screen,  you  can 
print  the  virtual  screen  to  paper  as  a 
unit  — again,  without  any  additional  fuss¬ 
ing  to  combine  multiple  forms  onto 
one  sheet  for  printing. 

Virtual  screens  also  make  report  pre¬ 
viewing  easy  and  convenient.  Reports 
must  be  formatted  for  paper,  not  for 
the  screen,  so  if  the  user  wants  to  pre¬ 
view  a  printed  report  on  the  screen, 
he  or  she  must  be  able  to  pan  around 
the  sheet  in  order  to  inspect  the  whole 
sheet  on  a  sub-66-line  screen.  My  infa¬ 
mous  Little  Black  Book  program 
JBOOK.PAS  (which  I  will  someday  re¬ 
lease  as  shareware)  prints  address  in¬ 
formation  on  Day  Runner-style  memo 
book  sheets,  many  of  which  accept 
over  50  lines  in  the  Laserjet  II’s  16.66 
pitch  Line  Printer  font.  Using  SCREENS 
.PAS,  JBOOK  builds  each  sheet  of  the 
paper  report  in  a  virtual  screen,  and 
then  prints  directly  from  the  virtual  screen. 

Listing  Two  is  the  Turbo  Pascal  code 
for  the  virtual  display  management  unit. 
Listing  Three,  page  144,  is  a  short  demo 
program,  SCRNTEST.PAS.  SCRNTEST  al¬ 
lows  you  to  load  the  first  66  lines  of 
any  text  file  into  a  virtual  screen  and 
then  pan  through  it.  Pressing  Del  will 
clear  the  center  line  of  the  visible  dis¬ 
play,  which  can  then  be  scrolled  onto 
and  off  of  the  screen  as  proof  that  the 
screen  really  is  virtual.  (SCRNTEST  can¬ 
not  write  to  disk,  so  your  text  file  will 
not  be  corrupted.) 

SCREENS. PAS  is  complete  and  us¬ 
able  as  it  stands,  but  much  could  be 
added  to  it.  I’ll  be  presenting  additional 
procedures  for  the  unit  in  future  col¬ 
umns.  These  will  include  a  box-draw¬ 
ing  procedure,  as  well  as  code  to  allow 
the  creation  of  “ghost”  screens  stored 
entirely  on  the  heap,  and  flashed  in 
and  out  of  view  with  a  little  external 
assembly  language  magic.  Also,  from 
time  to  time  I’ll  present  screen-oriented 
procedures  showing  how  different  user 
interface  concepts  are  implemented,  and 
they’ll  be  built  on  the  virtual  screens 
platform  shown  here. 

And  if  I  can  score  the  loan  of  a  video 
board  that  displays  more  than  80  col¬ 


umns  horizontally,  I’ll  take  a  crack  at 
adding  horizontal  panning  to  the  sys¬ 
tem.  People  who  have  display  boards 
that  support  132  column  text,  write  to 
me.  Let  me  know  what’s  good. 

Off  the  Shelf  Video  Information 

I’ve  learned  most  of  the  information 
on  text  displays  presented  in  these  last 
few  columns  the  hard  way,  but  more 
and  more  of  it  is  being  gathered  up  into 
reference  books  specifically  devoted 
to  video  topics. 

Let  me  call  attention  to  two  recent 
titles  that  I’ve  found  very  useful.  Pro¬ 
grammer’s  Guide  to  PC  and  PS/2  Video 
Systems  by  Richard  Wilton  is  the  most 
broad  ranging,  in  that  it  covers  the  full 
spectrum  of  PC  video,  including  the 
CGA,  MDA,  Hercules,  and  something 
called  the  InColor  card  that  I’ve  never 
heard  of.  Programmer’s  Guide  to  the 
EGA  and  VGA  Cards  by  Richard  F. 
Ferraro  is  more  focused,  but  covers  its 
territory  in  greater  depth.  The  books 
distinguish  themselves  quite  clearly  in 
several  ways.  The  Wilton  book  is  a 
software  book,  that  contains  tremen¬ 
dous  quantities  of  C  and  assembler 
code,  including  what  looks  like  a  fast 
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graphics  BITBLT  in  assembler.  Sadly, 
the  source  is  printed  in  an  eye-crossing 
pale  green  that  suggests  an  intention 
to  present  source  code  in  3-D,  only 
they  forgot  to  bind  the  little  glasses  into 
the  book.  (Microsoft  Press  recognizes 
the  error  and  will  print  it  more  clearly 
in  future  press  runs.)  The  Ferraro  book 
is  a  hardware  book,  and  tells  you  much 
more  about  what  goes  on  at  a  register 
level.  Wilton  presents  his  great  quanti¬ 
ties  of  data  in  reference  manual  fash¬ 
ion,  and  doesn’t  provide  as  much  in 
the  line  of  example  code. 

The  two  dovetail  nicely  with  one  an¬ 
other,  and  I  consider  both  of  them  es¬ 
sential.  I’ll  let  Kent  pass  on  how  useful 
they  are  to  the  graphics  programmer,  but 
they  have  not  failed  so  far  to  answer 
any  questions  I’ve  had  on  text  video. 

Carol  of  the  BELs 

I  seem  to  be  making  a  habit  of  finishing 
up  these  columns  on  major  holidays. 
(In  the  Santa  Cruz  area,  Halloween  is 
major.)  A  little  later  on  this  drippy  Christ¬ 
mas  Eve,  Carol  and  I  will  be  packing 
off  in  the  Magic  Van  to  have  a  quiet 
dinner  with  friends  on  the  slopes  of 
Loma  Prieta. 

A  good  night,  I  think,  to  shut  the 
machines  down  and  look  for  the  best 
that  is  human  somewhere  else.  Give 
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somebody  who  counts  a  hug,  and  it’ll 
be  right  there. 

Promise. 

Errata 

A  bug  has  been  discoverd  in  the  list¬ 
ings  for  the  March  1989  “Structured 


Programming”  column.  On  line  175  of 
TEXTINFO.PAS,  (within  procedure 
GetFont  Size)  replace  the  line 

BL  :=  0; 

with  the  line 

BH  :=  0; 

The  bug  apparently  affects  VGA  dis¬ 
play  boards  only,  and  then  only  under 
certain  circumstances.  Please  update 
your  copy  of  TEXTINFO.PAS  accord¬ 
ingly. 

Availability 

All  source  code  for  articles  in  this  issue 
is  available  on  a  single  disk.  To  order, 
send  $14.95  (Calif,  residents  add  sales 
tax)  to  Dr.  Dobb’s Journal ,  501  Galves¬ 
ton  Dr.,  Redwood  City,  CA  94063,  or 
call  800-356-2002  (inside  Calif.)  or  800- 
533-4372  (outside  Calif.).  Please  spec¬ 
ify  the  issue  number  and  format  (MS- 
DOS,  Macintosh,  Kaypro). 

DDJ 

(Listings  begin  on  page  142.) 

Vote  for  your  favorite  feature/article. 

Circle  Reader  Service  No.  11. 
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Listing  One  ( Text  begins  on  page  109  ) 


/* - 

#include 

#include 

♦include 

♦include 

♦include 

♦include 

♦include 

♦include 

♦include 

♦include 

♦include 

♦include 

♦include 

♦include 


smallcom.c 
<conio.h> 
<stdio.h> 
<mem.h> 
<string.h> 
<ctype .h> 
<dos .h> 
<stdlib.h> 
"window. h" 
"editor .h" 
"menu.h" 
"entry .h" 
"serial . h" 

" modem. h" 
"help. h" 


♦define  ANSWERTIMEOUT  60 
♦define  MAXSTRINGS  15 

♦define  carrier  ()  (inp (MODEMS TATUS)  &  0x80) 

♦define  LOGFILE  "smallcom.log" 

♦define  HELPFILE  "smallcom.hlp" 

♦define  CFGFILE  "smallcom.cfg" 

♦define  ALT_P  153 
♦define  ALT_C  174 
♦define  CTRL_C  3 
♦define  WILDCARD  '?' 
static  union  REGS  rg; 

static  FILE  *logfp,  *uploadfp,  *downloadfp,  *cfg; 
static  int  running=l, connected, answering, savebaud; 
int  filecount; 

extern  int  direct_connection,  TIMEOUT,  inserting; 
extern  char  spaces []; 
extern  struct  wn  wkw; 
extern  MENU  *mn; 

/* - prototypes - */ 

void  fileedit (char  *) ; 
static  void  displaycount (void) ; 
static  void  smallmenu (int) ; 
static  void  logser ial  (int) ; 
static  int  uploadfint,  int); 
static  int  download (int,  int); 
static  int  call (int,  int); 
static  int  directory (int,  int); 
static  int  comeditor (int,  int); 
static  answer (int,  int); 
static  directcon  (int,  int); 
static  int  loginput (int,  int); 
static  int  hangup(int,  int); 
static  int  quit (int,  int); 
static  int  prm(int,  int); 
static  void  loadp(void); 
static  int  savep(int,  int); 
static  void  set_parameters (void) ; 
static  int  get_f ilename (char  *); 
static  void  notice (char  *); 
static  void  statusline (void) ; 
static  void  putch  window(int); 
void  upload_ASCIl7FILE  *) ; 
void  download_ASCII (FILE  *); 
int  keyhit (void) ; 

char  *prompt_line (char  *,  int,  char  *); 
void  reset_prompt (char  *,  int); 
static  int  testcarrier (void) ; 
static  int  waitforconnect (void) ; 
static  void  initcom (void) ; 
int  waitforresult (void) ; 
int  waitforstring (char  **,  int,  int); 
static  void  waitforcall (void) ; 
static  void  resetline (void) ; 

/* - the  hook  to  the  phone  directory - * / 

static  void  (*phone_directory) (void)  =  NULL; 

/* - the  hook  to  script  processors - * / 

void  (*script_processor) (void) ;  /*  filled  in  by  directory  */ 

/* - hooks  to  file  transfer  protocols - */ 

static  int  (*select_transfer_protocol) (void)  =  NULL; 

/* - up  to  five  upload  function  pointers - */ 

static  void  (*up_protocol [5] ) (FILE  *f ile_pointer)  =  { 
upload_ASCII ,  NULL,  NULL,  NULL,  NULL 

); 

/*  -  up  to  five  download  function  pointers  -  */ 

static  void  ( *down_protocol [5] ) (FILE  *f ile_pointer)  =  { 
download_ASCII,  NULL,  NULL,  NULL,  NULL 

) ; 

/* - Files  menu - */ 

static  char  *fselcs[]  =  { 

"Log  Input  On/Off", 

"Upload  a  File", 

"Download  a  File", 

"Quit", 

NULL 

}; 

static  char  *fhelps[]  =  ( "log", "upload", "download", "quitcom" ) ; 

/* - Connect  menu - *  / 

static  char  *cselcs[]  =  ( 

"Place  Call", 

"Answer  Call", 

"Hang  up", 

"Direct  Connection", 

NULL 

)  ; 

static  char  *chelps[]  =  { "call", "answer", "hangup", "direct" ) ; 

/* - Parameters  menu - */ 

static  char  *pselcs[]  =  { 

"Com  Port:  ", 

"Baud  Rate:  ", 

"Data  Bits:  ", 

"Stop  Bit (s)  :  ", 

"Parity:  ", 

"Mode  of  Dialing:  ", 


Listing  One  (Text  begins  on  page  109.) 

/* - hooks. c - */ 

/* - the  hook  to  the  phone  directory - */ 

extern  void  phdirectory (void) ; 

static  void  (*phone_directory) (void)  *  phdirectory; 

/* - the  hook  to  script  processors - */ 

void  (*script_processor) (void) ; 

/* - hooks  to  file  transfer  protocols - */ 

extern  int  select_protocol (void) ; 

static  int  (*select_transfer_protocol) (void)  =  select_protocol; 

/* - up  to  five  upload  function  pointers - */ 

void  upload_xmodem(FILE  *) ; 
void  upload_kermit (FILE  *) ; 

static  void  (*up_protocol [5] ) (FILE  *file_pointer)  -  { 
upload_ASCII,  upload_xmodem,  upload_kermit, NULL, NULL 

}; 

/*  -  up  to  five  download  function  pointers  -  */ 

void  download_xmodem(FILE  *); 
void  download_kermit (FILE  *); 

static  void  (*down_protocol [5] ) (FILE  *file_pointer)  -  ( 

download_ASCII,  download_xmodem,  download_kermit, NULL, NULL 

}; 

End  Listing  One 


Listing  Two 

/* - phonedir.c - */ 

♦include  <stdio.h> 

♦include  <stdlib.h> 

♦include  <conio.h> 

♦include  <string.h> 

♦include  <mem.h> 

♦include  <ctype.h> 

♦include  "window. h" 

♦include  "entry. h" 

♦include  "help.h" 

♦include  "modem. h" 


♦define  DIRECTORY  "phone. dir" 
♦define  MAX_ENTRIES  50 
♦define  WRITEDIR  F2 
♦define  MODIFYDIR  F3 


void  phdirectory (void) ; 
char  scriptfile[13) ; 
static  void  get_directory (void) ; 
static  void  put_directory (void) ; 
static  int  dirproc(int,  int); 
static  void  bld_default (int) ; 
static  void  build_dir (int) ; 
static  int  enter_di rectory (int) ; 
static  void  select_directory (int) ; 
char  *prompt_line(char  *,  int,  char  *); 
void  reset_prompt (char  *,  int); 
static  int  edit_directory (void) ; 
static  int  direrror (int) ; 

static  void  field_terminate (FIELD  *fld,  int  termchar) ; 


extern  int  PARITY, STOPBITS, WORDLEN,  BAUD; 
extern  char  PHONENOU; 
extern  char  spaces!); 

extern  struct  wn  wkw;  /*  the  directory  window  structure  */ 
extern  void  (*phone_directory) ()  -  phdirectory; 

/* - phone  directory  file  record - */ 

struct  { 

callee's  name  */ 

phone  number  */ 

none/odd/even  */ 

1  or  2  */ 

7  or  8  */ 

110,150,300,600,1200,2400  */ 
name  of  script  file  */ 


char  ol_name[21);  /* 
char  ol_phone [24] ;  /* 
char  ol_parity [8] ;  /* 
char  ol_stopbits [4] ;  /* 


char  ol_wordlen[3] ; 
char  ol_baud[6); 
char  ol_script [9)  ; 

)  pd; 

static  char  hdr[]  = 

"  Name  " 

"Phone  Number  " 

"Parity  Stop  Len  Baud  Script"; 
static  char  select_prompt [ ]  = 

"\030\031\021\304\331 : Select  Esc:Return  " 
"F2: Write  Directory  F3:Modify  " 

"Ins: Insert  Del:Delete"; 
static  char  enterjorompt [ ]  = 

"  F2:Write  Changes  to  Directory  " 

"  Esc: Ignore  Entry  FI: Help"; 
static  char  *pds [MAX_ENTRIES+1 ] ; 
static  int  pet; 
static  FILE  *fp; 

static  char  nmmask[]  =  " _  "; 

static  char  phmask()  =  " _ "; 

static  char  prmask[]  •  " _ "  ; 

static  char  sbmask[j  = 

static  char  wlmask[j  = 

static  char  bdmask[]  =  " _ "; 

static  char  scmask[]  “  " _ "; 

/*  -  data  entry  template  for  the  directory 

FIELD  directory_template [ ]  =  { 


(3, 

16, 

1,  pd.ol  name, 

nmmask, 

"name" } , 

(4, 

16, 

1,  pd.ol_phone, 

phmask, 

"phone" ) , 

(5, 

16, 

1,  pd.ol_parity, 

prmask, 

"parity") , 

(6, 

16, 

1,  pd.ol_stopbits, 

sbmask, 

"stopbits" ) 

(7, 

16, 

1,  pd.ol  wordlen, 

wlmask, 

"wordlen" ) , 

(8, 

16, 

1,  pd.ol  baud, 

bdmask, 

"baud" ) , 

(9, 

(0) 

16, 

1,  pd.ol_script, 

semask, 

"script" ) , 

data  entry  error  messages  ■ 
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static  char  *ermsgs[]  -  ( 

"Parity  must  be  None,  Odd,  or  Even", 

"Stop  Bits  must  1  or  2", 

"Word  Length  must  be  7  or  8", 

"Baud  Rate  must  be  110,150,300,600,1200,2400" 

}; 

/* - manage  the  telephone  directory - */ 

void  phdirectory {void) 

{ 

int  s  -  1; 

char  *ttl,  *sel; 

set_help("directry") ; 

ttl  -  prompt_line (hdr,  1,  NULL); 

sel  -  prompt_line (select_prompt,  25,  NULL); 

establish_window (1, 2, 80, 24, TEXTFG, TEXTBG, TRUE) ; 

get_directory ( ) ; 

text_window(pds,  1); 

while  (pet  ss 

(s=select_window(s,SELECTFG,SELECTBG,dirproc) ) !*0) 
if  (pet  &&  pds(s-l]  !-  spaces+1)  ( 
select_directory (s-1) ; 
break;- 

} 

delete_window() ; 
reset_prompt (sel,  25) ; 
reset_prompt (ttl,  1); 

} 

/* - select  the  directory  entry  for  the  dialer - */ 

static  void  select_directory (int  n) 

{ 

char  *cp  ■  scriptfile; 
movmem(pds [n] ,  spd,  sizeof  pd) ; 
strnepy (PHONENO,  pd.ol_phone,  20); 

BAUD  «  atoi (pd.ol_baud) ; 

STOPBITS  -  *pd.ol  stopbits  -  'O'; 

WORDLEN  =  *pd.ol“wordlen  -  'O'; 

PARITY  -  (*pd.oT_wordlen  --  'N'  ?  0  : 

*pd.ol~wordlen  —  'O'  ?  1  :  2); 

establish  window (35, 11, 50, 13, HELPFG,HELPBG, TRUE) ; 
gotoxy (2,5) ; 

eputs ("Initializing  Modem"); 
initmodem() ; 
delete_window() ; 

setmem (scriptfile,  sizeof  scriptfile,  '\0'); 
strnepy (scriptfile,  pd.ol_script,  8); 
while  (*cp  SS  *cp  !-  '  ')” 
cp++; 

strcpy(cp,  ".scr"); 

) 

/* - read  the  phone  directory - */ 

static  void  get_directory (void) 

( 

if  (pet  «  0  SS  (fp  -  f open (DIRECTORY,  "r"))  !-  NULL)  ( 
while  (fread(Spd,  sizeof  pd,  1,  fp)  !-  0)  ( 

build  dir(pct++); 
if  (pet  —  MAX_ENTRIES) 
break; 

) 

pds[pct++]  *  spaces+1; 
pds (pet]  -  NULL; 
f close (fp) ; 

) 

if  (pet  «  0) 

dirproc(INS,  1); 

) 

/*  -  build  a  default  phone  directory  entry  -  */ 

static  void  bld_de fault (int  n) 

( 

static  char  *prs[]  -  ("None",  "Odd  ",  "Even"); 
setmem(Spd,  sizeof  pd-1,  '  '); 
strnepy (pd.ol_parity,  prs (PARITY],  4); 

*pd.ol_stopbits  *  STOPBITS  +  'O'; 

*pd.ol_wordlen  *  WORDLEN  +  'O'; 
sprintf (pd.ol_baud,  "%4d",  BAUD); 
pd.ol_baud(4)  —  '  ' ; 
build_dir (n) ; 

) 

/* - build  a  directory  entry  for  display -  */ 

static  void  build_dir (int  n) 

{ 

if  ((pds[nj  -  malloc (sizeof  pd) )  !-  NULL) 
movmemfspd,  pds[n],  sizeof  pd) ; 

) 

/* - write  the  phone  directory - */ 

static  void  put_directory (void) 

{ 

int  i; 

fp  =  fopen (DIRECTORY,  "w"); 
for  (i  =  0;  i  <  pet;  i++) 
if  (pds(i)  !=  spaces+1) 

fwrite (pds [i] ,  sizeof  pd,  1,  fp) ; 
f close (fp) ; 

} 

/* - process  a  directory  entry - */ 

static  int  dirproc(int  c,  int  lineno) 

( 

int  i,  j; 
switch  (c)  ( 

case  DEL: 

if  (pds [lineno-1]  !«  spaces+1)  ( 
free (pds [lineno-1] ) ; 
for  (j  -  lineno-1;  j  <  pet;  j++) 
pds[j]  -  pds [ j+1 ] ; 
if  (—pet)  ( 

text_window (pds ,  wkw . wtop) ; 
for  (i  =  pct+2;  i  <=  wkw. wtop+wkw.ht;  i++) 
writeline(2,  i,  spaces+1); 
if  (lineno-1  ==  pet) 

— lineno; 

) 


else 

clear_window ( ) ; 

) 

break; 
case  INS: 

if  (pet  ==  MAX_ENTRIES) 
break; 
i  -  pet; 
if  (i) 

while  (i  >■  lineno)  ( 
pds [i]  *  pds [i-1] ; 

— i; 

> 

bld_default (i) ; 
pct++; 

case  MODIFYDIR: 

if  (pds (lineno-1]  !*  spaces+1)  ( 

movmem (pds [lineno-1] ,  &pd,  sizeof  pd) ; 
enter_directory (lineno-1) ; 

) 

break; 

case  WRITEDIR: 

put_directory () ; 
break; 

) 

wkw.wy  -  lineno  -  wkw. wtop  +  1; 
return  (pet  ■■  0); 

) 

/* - data  entry  for  a  directory  record - */ 

static  int  enter_directory (int  lineno) 

< 

int  s  -  1; 

char  *p  -  prompt_line (enter_prompt,  25,  NULL); 
establish_window (20, 5, 56, 15, ENTRYFG, ENTRYBG, TRUE) ; 
window_title ("  Telephone  Directory  Entry  "); 
gotoxy(3,3),  eputs ("Name: ") ; 
gotoxy(3,4),  eputs ("Phone: ") ; 
gotoxy(3, 5) ,  eputs ("Parity:") ; 
gotoxy(3,6),  eputs ("Stop  Bits:"); 
gotoxy(3,7),  eputs ("Word  Length:"); 
gotoxy(3,8),  eputs ("Baud  Rate:"); 
gotoxy(3,9),  eputs ("Script :") ; 
field_terminate (directory_template,  ' \0' ) ; 
while  (s  !-  WRITEDIR  &&  s  !-  ESC)  ( 

s  »  data_entry (directory_template,  FALSE,  s); 
if  (s  —  WRITEDIR) 

s  -  edit  directory (); 

) 

field_terminate (directory  template,  '  '); 

*( ( (char  *)(&pd))  +  sizeof  pd-1)  -  '\0'; 
delete_window () ; 
reset_prompt (p,  25) ; 
if  (s  —  WRITEDIR)  ( 

movmem(&pd,  pds (lineno],  sizeof  pd) ; 
put_directory () ; 

) 

text_window (pds, wkw. wtop  ?  wkw. wtop  :  1); 
return  (s  !-  ESC); 

) 

I* - validate  the  directory  entry - */ 

static  int  edit_directory (void) 

! 

int  i; 

static  int  bds[]  -  (110,150,300,600,1200,2400); 
*pd.ol_parity  -  toupper (*pd.ol_parity) ; 
if  (*pd.ol_parity  !=  'N'  && 

*pd.ol_parity  !-  'O'  Si 
*pd.ol_parity  !-  'E' ) 
return  direrror(3); 

if  (*pd.ol_stopbits  !-  '1'  Si  *pd.ol_stopbits  !-  '2') 
return  direrror{4); 

if  (*pd.ol_wordlen  !-  '7'  ss  *pd.ol_wordlen  !=  '8') 
return~direrror (5) ; 
for  (i  -  0;  i  <  6;  i++) 

if  (atoi  (pd.ol_baud)  *==bds[i]) 
break; 
if  (i  ==  6) 

return  direrror(6); 
return  WRITEDIR; 

} 

/* - post  a  directory  entry  error -  */ 

static  int  direrror(int  n) 

( 

errorjnessage (ermsgs [n-3] ) ; 
return  n; 

) 

/* - set  field  terminators  to  null  or  space - */ 

static  void  field_terminate (FIELD  *fld,  int  termchar) 

{ 

for  (; fld->frow; f ld++) 

* (fld->fbuf f+strlen (fld->fmask) )  ■  termchar; 

) 


End  Listing  Two 


Listing  Three 

/* - protocol,  c 


♦include 

♦include 

♦include 

♦include 

♦include 

♦include 


<stdio.h> 

<conio.h> 

<ctype.h> 

"window. h1 

"help.h" 

"menu.h" 
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Listing  Three  (Listing  continued,  text  begins  on  page  109  ) 

static  char  *prots[]  =  ( 

"  ASCII", 

"  Xmodem", 

"  Kermit", 

NULL 

}; 


/*  -  translate  A, X,K  keystrokes  for  protocol  menu  -  */ 

static  int  protkey(int  ky,  int  lnno) 

( 

ky  =  tolower(ky); 

return  ky=*'a'  ?  1  :  ky=='x'  ?  2  :  ky=='k'  ?  3  :  ERROR; 

} 

/*  —  file  transfer  protocol  for  uploads  and  downloads  —  */ 
int  select_protocol (void) 

1 

extern  MENU  *mn; 

MENU  *holdmn; 
static  int  rtn  -  0; 
holdmn  «  mn; 
mn  *  NULL; 

set_help ( "protocol " ) ; 

establish_window (25, 7,55,11, MENUFG , MENUBG , TRUE) ; 
window_title ("  Select  Transfer  Protocol  "); 
text_window(prots,  1); 

rtn  «  select_window(rtn?rtn:l,SELECTFG,SELECTBG,protkey) ; 
delete_window ( ) ; 
mn  *  holdmn; 
return  rtn  ?  rtn-1  :  0; 

) 

/*  -  These  are  stubs,  to  be  replaced  later  -  */ 

void  upload_kermit (FILE  *fd) 

{ 

errorjnessage ("Upload  KERMIT  not  implemented") ; 

} 

void  download_kermit (FILE  *fd) 

{ 

error_message ("Download  KERMIT  not  implemented"); 

) 


End  Listing  Three 


Listing  Four 

/* - xmodem. c - */ 

♦include  <stdio.h> 

♦include  <conio.h> 

♦include  <stdlib.h> 

♦include  <mem.h> 

♦include  "window. h" 

♦include  "serial. h" 

♦define  RETRIES  12 
♦define  CRCTRIES  2 
♦define  PADCHAR  Oxla 
♦define  SOH  1 

♦define  EOT  4 

♦define  ACK  6 
♦define  NAK  0x15 
♦define  CAN  0x18 

♦define  CRC  'C' 

/* - external  data - */ 

extern  int  TIMEOUT; 
extern  int  WORDLEN; 
extern  int  xonxof f_enabled; 

/* - local  data - */ 

static  int  tries;  /*  retry  counter  */ 

static  char  bf  [130];  /*  i/o  buffer  */ 

/* - prototypes - */ 

extern  int  keyhit (void) ; 
static  void  receive_error (int,  int); 
static  void  xmodem_msg (char  *); 
static  void  test_wordlen (void) ; 
unsigned  compute_crc (char  *,  int); 

/* - error  messages - */ 

static  char  *errs[]  =  ( 

"Timed  Out  ", 

"Invalid  SOH 
"Invalid  block  ♦  ", 

"Invalid  chksum/crc" 

}»* 

/* - upload  with  xmodem  protocol - */ 

void  upload_xmodem(FILE  *fd) 

( 

int  i,  chksum,  eof  *  FALSE,  ans  =  0,  In,  crcout  =  0; 
unsigned  crc; 
char  bno  =  1; 
xonxoff_enabled  =  FALSE; 

establish_window (20,10,52,14, MENUFG, MENUBG, TRUE) ; 
window_title( "XMODEM  Upload  (CHKSUM)"); 
tries  ■*  0; 
test_wordlen () ; 

/* - wait  for  the  go-ahead  from  the  receiver - */ 

TIMEOUT  =  6; 

while  (tries++  <  RETRIES  £&  crcout  !=  NAK  &&  crcout  !=  CRC) 
crcout  =  readcommO; 
if  (crcout  ==  CRC) 

window  title  ("  XMODEM  Upload  (CRC)  "); 

TIMEOUT  -  TO; 

/* - send  the  file  to  the  receiver - */ 

while  (tries  <  RETRIES  s& 


!eof  &&  ans  !=  CAN  &&  !timed_out () )  ( 

/* - read  the  next  data  block - */ 

setmem(bf ,  128,  PADCHAR); 
if  ((In  =  fread(bf ,  1,  128,  fd) )  <  128) 
eof  =  TRUE; 
if  (In  ==  0) 
break ; 

gotoxy(2,  2); 

cprintf ("Block  %d  ",bno); 
chksum  =  0; 
if  (keyhit ()) 

if  (getch()  ==  ESC)  ( 
writecomm (CAN) ; 
break; 

1 

writecomm (SOH) ;  /*  SOH  */ 

writecomm (bno) ;  /*  block  number  */ 

writecomm (bno) ;  /*  Is  complement  */ 

/* - send  the  data  block - */ 

for  (i  =  0;  i  <  128;  i++)  f 
writecomm (bf [ i ] ) ; 

chksum  +=  bf ( i ] ;  /*  checksum  calculation  */ 

) 

/*  —  send  error-correcting  value  (chksum  or  crc)  —  */ 
if  (crcout  ==  NAK) 

writecomm (chksum  &  255); 
else  ( 

crc  =  compute_crc (bf ,  130); 
writecomm ( (crc  »  8)  &  255); 
writecomm (crc  &  255); 


/* - read  ACK,  NAK,  or  CAN  from  receiver - */ 

ans  =  readcommO; 
if  (ans  ==  ACK)  ( 
bno++; 
tries  =  0; 
gotoxy(2,  4); 
cprintf ("  "); 


if  (ans  ==  NAK)  ( 
eof  =  FALSE; 
gotoxy(2,  4); 

cprintf ("%2d  tries",  ++tries) ; 

/* - position  to  previous  block - */ 

if  (fseek (fd,  -128L,  1)  ==  -1) 
fseek(fd,  0L,  0); 

) 

) 

if  (eof)  { 

writecomm (EOT) ;  /*  send  the  EOT  */ 

readcommO;  /*  wait  for  an  ACK  */ 


xmodem_msg( "Transfer  Completed") ; 

) 

else 

xmodem_msg ("Transfer  Aborted"); 
xonxof f_enabled  =  TRUE; 

} 

/* - download  with  xmodem  protocol - */ 

void  download_xmodem(FILE  *fd) 

( 

int  blk=0,  soh=  0,  bn,  nbn,  i,  crcin  =  TRUE,  fst  =  TRUE; 
unsigned  chksum,  cs,  csl; 
xonxof f_enabled  =  FALSE; 

es  t  abl ish_window (20,10,52,14, MENUFG , MENUBG , TRUE ) ; 
window_title( "XMODEM  Download  (CHKSUM)"); 

/*  -  send  Cs  then  NAKs  until  the  sender  starts  sending  - 
tries  =  0; 
test_wordlen ()  ; 

TIMEOUT  =  6; 

while  (soh  !=  SOH  &&  tries  <  RETRIES)  ( 
crcin  =  (tries++  <  CRCTRIES); 
writecomm (crcin  ?  CRC  :  NAK) ; 
soh  =  readcomm ( ) ; 
if  ( !timed_out ()  &&  soh  !=  SOH) 
sleep (6) ; 

) 

if  (crcin) 

window_title ("  XMODEM  Download  (CRC)  "); 
while  (tries  <  RETRIES)  ( 
if  (timed_out () ) 

recei ve  er ror ( 0 ,  NAK)  ; 

/*  —  Receive  the  data  and  build  the  file  —  */ 
gotoxy (2, 2) ; 

cprintf ("Block  %d  ",  blk  +  1); 
if  ( ! fst)  { 

TIMEOUT  =10; 
soh  =  readcomm ( ) ; 
if  (timed_out () ) 
continue; 
if  (soh  ==  CAN) 
break; 

if  (soh  ==  EOT)  ( 
writecomm (ACK) ; 
break; 

) 

) 

fst  =  FALSE; 

TIMEOUT  =  1; 

bn  =  readcommO;  /*  block  number  */ 

nbn  =  readcommO;  /*  l's  complement  */ 

chksum  =  0; 

/* - data  block - */ 


*/ 
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Listing  Four  (Listing  continued,  text  begins  on  page  109.) 

for  (i  =  0;  i  <  128;  i++)  { 

*  (bf  +  i)  =  readcommO; 
if  (timed_out () ) 
break; 

chksum  =  (chksum  +  (*(bf  +  i) )  &  255)  &  255; 

) 

if  (timed_out () ) 
continue; 

/* - checksum  or  crc  from  sender - *1 

cs  =  readcommO  &  255; 
if  (crcin)  { 

csl  =  readcommO  &  255; 
cs  =  (cs  «  8)  +  csl; 

} 

if  (timed_out{)) 
continue; 

if  (soh  !»  SOH)  {  /*  check  the  SOH  */ 

receive_er ror ( 1 ,  NAK) ; 
continue; 

} 

/*  —  same  as  previous  block  number?  -  */ 

if  (bn  ==  blk) 

fseek (fd,  -128L,  1) ; 

/*  —  no,  next  sequential  block  number?  —  */ 
else  if  (bn  ! -  blk  +  1)  { 
receive_error (2,  CAN); 
break; 

) 

blk  =  bn; 

/*  —  test  the  block  I  Is  complement  —  */ 
if  ( (nbn  &  255)  !«=  (blk  &  255))  ( 

receive_error (2,  NAK); 
continue; 

) 

if  (crcin) 

chksum  *  compute_crc(bf,  130); 

/*  —  test  chksum  or  crc  vs  one  sent  —  */ 
if  (cs  !=  chksum)  { 

receive_error (6,  NAK); 
continue; 

) 

soh  -  bn  -  nbn  =  cs  =  0; 
tries  -  0; 

/*  —  write  the  block  to  disk  —  */ 
fwrite(bf,  128,  1,  fd) ; 
if  (keyhitO) 

if  (getchO  -=  ESC)  { 
writecomm(CAN) ; 
break; 

) 

writecomm(ACK) ; 

) 

if  (soh  ==  EOT) 

xmodem_msg( "Transfer  Complete"); 

else 

xmodemjnsg ("Transfer  Aborted"); 

TIMEOUT  -10; 
xonxoff_enabled  =  TRUE; 

) 

/* - send  a  nak - */ 

static  void  receive_error (erno,  rtn) 

{ 

++tries; 

if  (TIMEOUT  ==  1)  { 

gotoxy (2, 4) ; 

cprintf("%s  (%d  tries)",  errs[erno],  tries); 

) 

writecomm(rtn) ; 

) 

/* - test  for  valid  word  length - * / 

static  void  test_wordlen(void) 

( 

if  (WORDLEN  !=  8)  ( 

gotoxy (2, 4) ; 

cprintf ("Must  be  8  Data  Bits"); 
tries  =  RETRIES; 

} 

I 

/*  -  final  message  about  xmodem  transfer  -  */ 

static  void  xmodemjnsg (char  *s) 

( 

gotoxy (2, 3) ; 
cprintf (s) ; 
put ch (BELL) ; 
sleep (3) ; 
delete_window() ; 

) 

/* - compute  the  crc - */ 

unsigned  compute_crc (char  *bf,  int  len) 

I 

int  i; 

long  crc  =  0; 
while  (len — )  { 

crc  |=  (*bf++)  &  255; 
for  (i  =  0;  i  <  8;  i++)  { 
crc  «=  1; 

if  (crc  &  OxlOOOOOOL) 
crc  A=  0xl02100L; 

) 

) 

return  (unsigned)  (crc  »  8); 

) 

End  Listings 


Listing  One  (Text  begins  on  page  1 16.) 

/*  COLORS. C:  Shows  all  colors  in  default  palette  */ 

♦include  "grafix.h" 

♦include  <conio.h> 

void  main  () 

{ 

int  r,  c,  color; 

if  (init_video  (EGA))  ( 
for  (r  =  0;  r  <  4;  r++) 
for  (c  =  0;  c  <  4;  C++)  { 
color  =  (r  *  4)  +  c;  /*  next  color  */ 

set_colorl  (color) ; 
fill_rect  ( (c*160) ,  (r*80) ,  158,  79); 

) 

getchO;  /*  wait  for  keypress  */ 

I 

} 

End  Listing  One 


Listing  Two 


/*  Include  file  for  GRAFIX.LIB  */ 

/*  EGA/ VGA  graphics  subsystem  */ 

/*  K.  Porter,  DDJ  Graphics  Programming  Column  */ 

/* - */ 

/*  Color  constants  from  April,  89  */ 

standard  colors  */ 


♦define 

Black 

0 

/*  sta 

♦define 

Blue 

1 

♦define 

Green 

2 

♦define 

Cyan 

3 

♦define 

Red 

4 

♦define 

Magenta 

5 

♦define 

Brown 

0x14 

♦define 

LtGray 

7 

♦define 

DkGray 

0x38 

♦define 

LtBlue 

0x39 

♦define 

LtGreen 

0x3A 

♦define 

LtCyan 

0x3B 

♦define 

LtRed 

0x3C 

♦define 

LtMagenta 

0x3D 

♦define 

Yellow 

0x3E 

♦define 

White 

0x3F 

♦define 

REDO 

0x00 

/*  basic 

♦define 

RED1 

0x20 

♦define 

RED2 

0x04 

♦define 

RED  3 

0x24 

♦define 

GRN0 

0x00 

♦define 

GRN1 

0x10 

♦define 

GRN2 

0x02 

♦define 

GRN3 

0x12 

♦define 

BLU0 

0x00 

♦define 

BLU1 

0x08 

♦define 

BLU2 

0x01 

♦define 

BLU3 

0x09 

/*  EGA  640  x  350,  16/64  colors 
/*  VGA  640  x  480,  16/64  colors 


♦if  ! defined  byte 
♦define  byte  unsigned  char 
♦endif 

/*  Supported  video  modes  */ 

♦define  EGA  0x10 

♦define  VGA 16  0x11 

/*  Function  prototypes  */ 

/*  From  February,  '89  */ 

/* - */ 

int  far  init_video  (int  mode) ;  /*  init  display  in  video  mode 

void  far  pc_textmode  (void);  /*  PC  text  mode 

void  far  draw_point  (int  x,  int  y) ;  /*  write  pixel  in  colorl 

void  far  set_colorl  (int  palette_reg) ;  /*  set  foreground  color 

/*  From  March,  '89  */ 

I* - */ 

void  far  draw_line  (int  xl,  int  yl,  int  x2,  int  y2); 

/*  Bresenham  line  drawing  algorithm 

void  far  draw_rect  (int  left,  int  top,  int  width,  int  height); 

,  •  /*  draw  rectangle  from  top  left  corner 

void  far  polyline  (int  edges,* int  vertices [));  /*  draw  polyline 

void  far  hline  (int  x,  int  y,  int  len);  /*  horizontal  line 

void  far  fill_rect  (int  left,  int  top,  int  width,  int  height) ; 

/*  draw  solid  rectangle  in  colorl  starting  at  top  left  corner 

/*  From  April,  '89  */ 

/* - */ 

byte  far  ega_palreg  (int  preg);  /*  color  in  EGA  palette  reg 

void  far  set_ega_palreg  (int  reg,  int  color);  /*  set  palette  reg 

byte  far  ega_blend  (byte  cl,  byte  c2,  byte  c3) ;  /*  blend  primaries 

void  far  get_ega_colormix  (int  preg,  int  *r,  int  *g,  int  *b) ; 

/*  get  mix  of  red,  green,  and  blue  in  EGA  pal  register  preg 


*/ 

*/ 

*/ 

V 

V 

V 

*/ 

*/ 

*/ 

*/ 

*/ 

*/ 

*/ 

V 


End  Listing  Two 
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/*  EGAPALET.C:  Palette  control  for  EGA/VGA  16-color  modes  */ 
/*  Compile  separately,  then  add  to  GRAFIX.LIB  */ 
/*  K.  Porter,  DDJ  Graphics  Programming  Column,  April  '89  */ 
/*  - */ 


♦include  "grafix.h" 
♦include  <dos.h> 


Listing  Four  (Listing  continued,  text  begins  on  page  116.) 

switch  (b)  { 

case  BLUO:  puts  ("(BLUO)");  break; 
case  BLU1:  puts  ("(BLU1)");  break; 
case  BLU2:  puts  (" (BLU2) ") ;  break; 
case  BLU3:  puts  ("(BLU3)");  break; 


byte  egajpalette  [16]  -  {  /*  current  palette  contents  */ 

Black,  Blue,  Green,  Cyan,  Red,  Magenta,  Brown,  LtGray, 

DkGray,  LtBlue,  LtGreen,  LtCyan,  LtRed,  LtMagenta,  Yellow, 
White 

); 

extern  int  grafixmode;  /*  from  GRAFIX.C  */ 

/*  - */ 

byte  far  ega_palreg  (int  preg) 

/*  return  contents  of  palette  register  preg  */ 

{ 

return  ega_palette  [preg] ; 

1  /*  - V 

byte  far  ega_blend  (byte  cl,  byte  c2,  byte  c3) 

/*  blend  three  primary  colors,  return  color  pattern  */ 

{ 

return  cl  |  c2  |  c3; 

I  /*  - */ 

void  far  get_ega_colormix  (int  preg,  int  *r,  int  *g,  int  *b) 

/*  break  color  in  palette  reg  preg  into  its  components  */ 

{ 

*r  =  egajpalette  [preg]  &  RED 3; 

*g  =  ega_palette  [preg]  &  GRN3; 

*b  =  ega_palette  [pregj  fi  BLU3; 

,  /*  - */ 

void  far  set_ega_palreg  (int  preg,  int  color) 

/*  change  palette  register  preg  to  new  color  */ 

/*  use  only  for  EGA  16-color  mode  */ 

{ 

union  REGS  r; 


]  /* 


*/ 


void  setup  jpalette  (void)  /*  put  basic  colors  in  palette  */ 
{ 

set_ega_palreg  (  1,  REDO);  set_ega_palreg  (  2,  RED1); 
set_egaj3alreg  (  3,  RED2);  set_ega  jialreg  (  4,  RED3) ; 


set_ega_palreg  (  5, 
set_ega_palreg  (  7, 


GRNO);  set_ega_palreg  (  6,  GRN1) ; 
GRN2);  set_ega_palreg  (  8,  GRN3) ; 


set_egaj>alreg  (  9, 
set_ega_palreg  (11, 


BLUO);  set_ega_palreg  (10,  BLU1); 
BLU2);  set_ega_palreg  (12,  BLU3) ; 


set  ega  palreg  (13,  White);  /*  used  for  mixed  colors  */ 

, - v 


void  draw_box  (int  reg,  int  c,  int  r)  /*  box  around  color  */ 
( 

set_colorl  (reg) ; 

draw  rect  (col[c]-5,  row[r]-5,  110,  70); 

1  /*  - - */ 


void  setup_screen  (void)  /*  construct  work  screen  */ 

( 

int  r,  c,  reg  =  1; 

for  (r  -  0;  r  <  3;  r++) 
for  (c  =  0;  c  <  4;  C++)  { 

set_colorl  (reg++);  /*  select  color  reg  */ 

fill_rect  (col[c],  row[r],  100,  60);  /*  fill  */ 

) 

set_colorl  (13); 

fill_rect  (col[0],  280,  580,  60);  /*  mixed  color  area  */ 


if  (grafixmode  ==  EGA)  ( 
egajpalette  [preg]  -  color; 
r.h.ah  -  0x10; 


r.h.bh  ■  color; 
r.h.bl  =  preg; 
int86  (0x10,  Sr,  fir); 

) 

,  /*  - 


/*  update  our  copy  of  palette  */ 
/*  use  ROM  BIOS  video  services  */ 
/*  to  update  the  real  palette  */ 


End  Listing  Three 


Listing  Four 

/*  MIX.C:  Utility  for  mixing  colors  with  EGA  */ 

♦include  "grafix.h" 

♦include  <conio.h> 

♦include  <stdio.h> 


♦define  ESC  27  /*  Esc  char  */ 

♦define  ERASE  0 
♦define  SHOW  15 


int  col[]  -  (30, 
int  row[j  -  (30, 
int  rr  -  1,  gr  = 
int  base_red[]  = 
int  base_grn[j  = 
int  base_blu[j  = 


190,  350,  510);  /*  box  horiz  locations 

110,  190);  /*  box  vert  locations 


5,  br  -  9; 
(REDO,  RED1, 
(GRNO,  GRN1, 
(BLUO,  BLU1, 


/*  reg  index  for  color  set 
RED2,  RED3 ) ; 

GRN2,  GRN3 ) ; 

BLU2,  BLU3); 


*/ 

V 

*/ 


void  main  () 

( 

int  r,  g,  b; 


void  setup j>alette  (void) ,  setup_screen  (void) , 
mix_colors  (void) ; 


if  (init_video  (EGA) )  ( 
setupj>alette()  ; 
setup_screen() ; 
mix_colors () ; 
pc_textmode ( ) ; 

) 


/*  Report  results  */ 
get_ega_colormix  (13,  fir,  fig,  fib) ; 

printf  ("\nMixed  color  has  value  0x%02X",  egaj>alreg  (13)); 
printf  ("\nComponent  breakdown:"); 


printf 

switch 

("\n 
(r)  ( 

Red 

0x%02X 

",  r); 

case 

REDO: 

puts 

"(REDO)") 

break; 

case 

RED1 : 

puts 

" (RED1)") 

break, 

case 

RED2 : 

puts 

" (RED2) ") 

break, 

case 

i 

RED3: 

puts 

" (RED3) ") 

break, 

/ 

printf 

switch 

C 

(g)  1 

Green 

0x%02X  " 

,  g); 

case 

GRNO 

puts 

"(GRNO)") 

break, 

case 

GRN1 

puts 

" (GRN1) " ) 

break, 

case 

GRN2 

puts 

" (GRN2) ") 

break, 

case 

GRN3 

puts 

" (GRN3) ") 

break, 

printf 

(" 

Blue: 

0x%02X  " 

,  b); 

for  (r  =0;  r  <  3;  r++) 
draw_box  (SHOW,  3,  r) ; 

,  /*  - 


void  mix_colors  (void) 

{ 

♦define  RAISE (col)  col  =  (col  <  3)  ?  ++col  :  3 
♦define  LOWER  (col)  col  =  (col  >  0)  ?  —col  :  0 

char  reply; 
int  r,  rc  -  3,  gc  1 


/*  rubberband  most  intense  */ 

- */ 

/*  interactive  portion  */ 


3,  be  *  3,  mixture; 


do  ( 

reply  *  getch(); 
switch  (reply)  ( 
case  ESC  :  break; 
case  'r'  :  r  *  0; 


/*  quit  program 
/*  lower  red 


draw_box  (ERASE,  rc,  r) ; 

LOWER  (rc); 

draw_box  (SHOW,  rc,  r) ; 
break; 
case  'R'  :  r  -  0; 

draw_box  (ERASE,  rc,  r); 

RAISE  (rc); 

draw_box  (SHOW,  rc,  r) ; 
break; 
case  ' q'  :  r  *  1; 

draw_box  (ERASE,  gc,  r) ; 

LOWER  (gc); 

draw_box  (SHOW,  gc,  r) ; 
break; 
case  'G'  :  r  -  1; 

draw_box  (ERASE,  gc,  r) ; 

RAISE  (gc) ; 

draw_box  (SHOW,  gc,  r) ; 
break; 
case  'b'  :  r  -  2; 

draw_box  (ERASE,  be,  r) ; 

LOWER  (be); 

draw_box  (SHOW,  be,  r) ; 
break; 
case  'B'  :  r  -  2; 

draw_box  (ERASE,  be,  r) ; 

RAISE  (be); 

draw_box  (SHOW,  be,  r) ; 
break; 

} 

mixture  =  ega_blend  (base_red[rc] ,  base_grn [gc] , 
base_blu[bc] )  ; 

set_egaj>alreg  (13,  mixture);  /*  update  color  mix  ' 

)  while  (reply  !-  ESC) ; 


/*  raise  red  */ 


/*  lower  green  */ 


/*  raise  green  */ 


/*  lower  blue  */ 


/*  raise  blue  */ 


End  Listings 
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Listing  One  (Text  begins  on  page  120.) 


Screen  =  RECORD 

ShowPtrs 
StorePtrs 
X,  Y 

TopLine 

FollowCursor 


Listing  Two 


ARRAY [1. .HEIGHT]  OF  LinePtr; 
ARRAY [1. .HEIGHT]  OF  LinePtr; 
Byte; 

1. .HEIGHT; 

Boolean 


End  Listing  One 


SCREENS 

Virtual  screen  management  unit 


by  Jeff  Duntemann  KI6RA 
Turbo  Pascal  5.0 
Last  modified  12/24/88 


UNIT  Screens; 


USES  DOS, 

Text Info; 


(  Standard  Borland  unit  } 

{  Given  last  issue;  DDJ  3/89  ) 


BEGIN 

IF  Up  THEN  Service  :*  $06  ELSE  Service  $07; 

WITH  Regs  DO 
BEGIN 

AH  Service; 

AL  ByLines; 

BH  CurrentAttr;  {  Attribute  for  blanked  line(s)  ) 

CH  0;  {  CX  &  DX:  Glitch  the  full  display  ) 

CL  0; 

DH  VisibleY-1; 

DL  VisibleX-1; 

END; 

Intr($10,Regs) ; 

END; 

{  Returns  string  equivalent  of  RealValue:  ) 

FUNCTION  RealStr (RealValue  :  Real;  Exponential  :  Boolean; 

FieldWidth, DecimalWidth  :  Integer)  :  String80; 

VAR 

Dummy  :  String80; 

BEGIN 

IF  Exponential  THEN 

Str (RealValue  :  FieldWidth, Dummy) 

ELSE 

Str (RealValue  :  FieldWidth  :  DecimalWidth, Dummy) ; 

RealStr  :*  Dummy 
END; 


80;  {  These  are  the  character  sizes  of  the  virtual  screens  ) 

66;  (  KEEP  IN  MIND  THAT  THIS  IS  A  1-ORIGIN  SYSTEM!!!!!!!!!  ) 

{  I.e.,  we  count  rows  and  columns  from  *1*,  not  0.  ) 

True;  {  Constants  for  glitching  and  panning  ) 


TYPE 

Strings  =  STRING [5]; 

StringlO  *=  STRING [10]; 

String80  =  STRING [80]; 

{  Lines  are  made  of  these;  helps  us  mix  characters  and  attributes:  ) 
ScreenAtom  ■  RECORD 

CASE  Boolean  OF 

True  :  (Ch  :  Char; 

Attr  :  Byte) ; 

False  :  (Atom  :  Word) ; 

END; 

LinePtr  *  ALine; 

Line  =  ARRAY [1. .WIDTH]  OF  ScreenAtom; 


ScreenPtr 

Screen 


'  AScreen; 

'  RECORD 

ShowPtrs 
StorePtrs  : 
X,  Y 

TopLine 

FollowCursor 

END; 


:  ARRAY [1. .HEIGHT]  OF  LinePtr; 
ARRAY [1. .HEIGHT]  OF  LinePtr; 

:  Byte; 

:  1.. HEIGHT; 

:  Boolean 


CONST 

ClearAtom  :  ScreenAtom  -  (Ch  :  '  ';  {  ASCII  space  char  ) 

Attr  :  $07);  {  "Normal"  screen  attribute  } 


CurrentAttr  :  Byte;  {  Exported  global,  *not*  a  function!  ] 


PROCEDURE  ClearLine(LineTarget  :  LinePtr; 

VisibleX  :  Byte; 
ClearAtom  :  ScreenAtom) ; 


(  Returns  string  equivalent  of  BooleanValue:  ) 
FUNCTION  BooStr (BooleanValue  :  Boolean)  :  String5; 
BEGIN 

IF  BooleanValue  THEN  BooStr  'TRUE' 

ELSE  BooStr  :«  'FALSE' 

END; 


(  Returns  string  equivalent  of  IntegerValue:  ) 

FUNCTION  IntStr (IntegerValue, FieldWidth  :  Integer)  :  StringlO; 
VAR 

Dummy  :  StringlO; 

BEGIN 

Str (IntegerValue  :  FieldWidth, Dummy) ; 

IntStr  Dummy 
END; 


{  Clears  Target  to  the  atom  passed  in  ClearAtom:  ) 

PROCEDURE  ClrScreen (Target  :  ScreenPtr;  ClearAtom  :  ScreenAtom); 

VAR 

I  :  Integer; 

BEGIN 

WITH  TargetA  DO 
BEGIN 

(  Brute  force:  Clear  all  lines  at  the  ends  of  pointer  } 

(  referents,  even  though  non-visible  lines  are  cleared  twice  ) 
FOR  I  :«  1  TO  HEIGHT  DO 

ClearLine (ShowPtrs [ I ] ,  VisibleX, ClearAtom) ; 

FOR  I  :■  1  TO  HEIGHT  DO 

ClearLine (StorePtrs [ I ] , VisibleX, ClearAtom) ; 

X  1;  Y  :»  1; 

END 


INLINE 

($58/ 

$59/ 

$5F/ 

$07/ 

$8C/$C2/ 
$81/$FA/0/0/ 
$7  4/ $02/ 
$F3/$AB) ; 


(  POP  AX  )  {  Pop  filler  char/attribute  into  AX  ) 

(  POP  CX  ]  (  Pop  line  length  (repeat  count)  into  CX  } 

{  POP  ES  ]  (  Pop  line  address  segment  into  ES  ) 

(  POP  DI  )  (  Pop  line  address  offset  into  DI  ) 

(  MOV  DX, ES  )  (  Move  ES  into  DX  for  test  against  0  ) 

(  CMP  DX, 0000  )  (  Compare  ES  value  (in  DX)  against  0  ) 

(  JE  2  }  {If  Equal,  jump  ahead  2  bytes  } 

{  REP  STOSW  )  (  Otherwise,  blast  that  line  to  atoms!  } 


FUNCTION  BooStr (BooleanValue  :  Boolean)  :  String5; 

PROCEDURE  ClrScreen (Target  :  ScreenPtr;  ClearAtom  :  ScreenAtom); 
PROCEDURE  DisposeOf Screen (VAR  Target  :  ScreenPtr); 

PROCEDURE  GotoXY (Target  :  ScreenPtr;  NewX, NewY  :  Byte); 

PROCEDURE  InitScreen (Target  :  ScreenPtr;  Visible  :  Boolean); 

FUNCTION  IntStr (IntegerValue, FieldWidth  :  Integer)  :  StringlO; 
PROCEDURE  Pan (Target  :  ScreenPtr;  PanUp  :  Boolean;  ByLines  :  Integer); 
FUNCTION  RealStr (RealValue  :  Real;  Exponential  :  Boolean; 

FieldWidth, DecimalWidth  :  Integer)  :  String80; 
PROCEDURE  WriteTo (Target  :  ScreenPtr;  S  :  String); 

PROCEDURE  WritelnTo (Target  :  ScreenPtr;  S  :  String); 


IMPLEMENTATION 

{  Private  to  SCREENS— make  it  public  if  you  need  it.  } 
PROCEDURE  GlitchDisplay (Up  :  Boolean;  ByLines  :  Integer); 
VAR 

Service  :  Byte; 

Regs  :  Registers; 


(  Moves  logical  (*not*  hardware!)  cursor  to  NewX, NewY:  ) 

PROCEDURE  GotoXY (Target  :  ScreenPtr;  NewX, NewY  :  Byte); 

(  Simply  places  new  values  in  descriptor  record's  X  6  Y  fields  ) 
BEGIN 

WITH  Target A  DO 
BEGIN 

X  :=  NewX; 

Y  :=  NewY 
END 


(  V-Screen  equivalent  of  Write:  } 

PROCEDURE  WriteTo (Target  :  ScreenPtr;  S  :  String); 
VAR 

I,K  :  Integer; 

TX  :  Byte; 

ShiftedAttr  :  Word; 

BEGIN 

{  Put  attribute  in  the  high  byte  of  a  word:  } 
ShiftedAttr  CurrentAttr  SHL  8; 

WITH  Target A  DO 
BEGIN 
TX  :-  X; 
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K  :=  0; 

FOR  I  :=  0  TO  Length (S)-l  DO 
BEGIN 

IF  X+I  >  VisibleX  THEN  {  If  string  goes  past  end  of  line:  ) 
BEGIN 

Inc (Y) ;  {  Increment  Y  value  } 

X  1;  TX  :=  1;  {  Reset  X  and  temp  X  value  to  1  } 

K  :=  0;  {  K  is  the  line-offset  counter  } 

END; 

{  Here  we  combine  the  character  from  the  string  and  the  } 
j  current  attribute  via  OR,  and  assign  it  to  its  location  } 

{  on  the  screen:  } 

Word (ShowPtrs [Y] A [X+K] )  :=  Word(S[I+l])  OR  ShiftedAttr; 

Inc (TX) ;  Inc(K); 

END; 

X  :-  TX;  {  Update  X  value  in  descriptor  record  } 

END 

END; 


{  V-Screen  equivalent  of  Writeln:  ) 

PROCEDURE  WritelnTo (Target  :  ScreenPtr;  S  :  String); 

BEGIN 

WriteTo (Target, S) ; 

Inc (Target A. Y) ;  (  These  2  lines  are  the  equivalent  of  CR/LF  ) 

Target A.X  :=  1 
END; 


{  Moves  the  visible  display  as  a  window  onto  a  full-page  virtual  screen:  } 
PROCEDURE  Pan (Target  :  ScreenPtr;  PanUp  :  Boolean;  ByLines  :  Integer); 


BEGIN 

FOR  I  :=  1  TO  HEIGHT  DO 
BEGIN 

New (ShowPtrs [I] ) ;  {  Allocate  a  line  on  the  heap  ) 

StorePtrs[I]  :=  ShowPtrs [I]  {  Duplicate  pointer  ) 

END; 

X  :=  1; 

Y  :-  1; 

TopLine  :=  1; 

FollowCursor  :=  True; 

IF  Visible  THEN  1  As  opposed  to  a  "ghost"  screen  on  the  heap  ) 
FOR  I  :  =  0  TO  VisibleY-1  DO 

ShowPtrs [1+1]  {  Repoint  pointers  into  refresh  buffer  ) 

Ptr (Seg (TextBuf ferOriginA) , 

Ofs (TextBufferOriginA)  +  (I  *  (VisibleX  *  2))) 

END 

END; 


(  Frees  up  heapspace  occupied  by  Target.  DON'T  use  if  Target  is  the  } 
(  address  of  a  statically  declared-record  obtained  with  0  or  Addr()!!  ) 

PROCEDURE  DisposeOfScreen (VAR  Target  :  ScreenPtr); 

VAR 

I  :  Integer; 

BEGIN 

FOR  I  :=  1  TO  Height  DO  Dispose (Target A .ShowPtrs [I] ) ; 

Dispose (Target) ; 

Target  NIL 
END; 


I  :  Integer; 

YOffset  :  byte; 

BEGIN 

YOffset  :  =  VisibleY-1;  (  Compensates  for  1-based  line  numbering  ) 

WITH  TargetA  DO 

IF  PanUp  THEN  (  If  we  want  to  pan  the  display  up  the  screen  ) 

BEGIN 

(  Don't  do  anything  if  we're  at  the  top  of  the  V-screen:  } 

IF  TopLine  >  1  THEN 
BEGIN 

{  If  we're  not  at  the  top  but  ByLines  would  take  us  out  of  ) 

(  legal  range,  adjust  ByLines  to  scroll  the  rest  of  the  way:  ) 

IF  TopLine  -  ByLines  <  1  THEN  ByLines  :=  TopLine  -  1; 

{  Move  newly-hidden  lines  into  virtual  screen  buffer:  ) 

FOR  I  :=  TopLine  +  YOffset  DOWNTO 

TopLine  +  YOffset  -  (ByLines-1)  DO 
Move(ShowPtrs[I]A,StorePtrs[I]A, VisibleX  *  2); 

(  Glitch  the  display  pointer  array  up:  ) 

Move (ShowPtrs [TopLine] , ShowPtrs [TopLine-ByLines] ,VisibleY  *  4); 

{  Repoint  affected  line  pointers  into  virtual  screen:  ) 

FOR  I  :  =  TopLine  +  YOffset  DOWNTO 

TopLine  +  YOffset  -  (ByLines-1)  DO 
ShowPtrs [I]  :=  StorePtrs [I] ; 

{  Glitch  the  display  buffer  down:  } 

GlitchDisplay (False, ByLines) ; 

{  Update  virtual  screen's  TopLine  counter:  ) 

TopLine  :=  TopLine  -  ByLines; 

{  Move  newly-visible  lines  to  display  from  virtual  screen:  ) 

FOR  I  :=  TopLine  TO  TopLine  +  (ByLines-1)  DO 
Move (StorePtrs [I] A, ShowPtrs [I] A, VisibleX  *  2); 

END 

END 

ELSE  (  If  we  want  to  pan  the  display  down  the  screen  ) 

BEGIN 

(  First  check  if  the  pan  would  take  us  out  of  legal  line  range:  ) 

IF  TopLine  +  YOffset  <  Height  THEN 
BEGIN 

(  If  we're  not  at  bottom  but  ByLines  would  take  us  out  of  ) 

(  legal  range,  adjust  ByLines  to  scroll  the  rest  of  the  way:  ) 

IF  TopLine  +  YOffset  +  ByLines  >  HEIGHT  THEN 
ByLines  :=  HEIGHT  -  (TopLine  +  YOffset); 

{  Move  newly-hidden  lines  into  virtual  screen  buffer:  ) 

FOR  I  :=  TopLine  TO  TopLine  +  (ByLines-1)  DO 
Move (ShowPtrs [I]  \  StorePtrs [I]  \ VisibleX  *  2) ; 

{  Glitch  the  display  pointer  array  down:  ) 

Move(ShowPtrs [TopLine] , ShowPtrs [TopLine+ByLines] ,VisibleY  *  4) ; 

{  Repoint  affected  line  pointers  into  virtual  screen:  ) 

FOR  I  :=  TopLine  TO  TopLine  +  (ByLines-1)  DO 
ShowPtrs [I]  :=  StorePtrs [I] ; 

{  Glitch  the  display  buffer  up  ) 

GlitchDisplay (True, ByLines) ; 

{  Move  newly-visible  lines  to  display  from  virtual  screen:  ) 

FOR  I  :=  TopLine  +  VisibleY  TO  TopLine  +  VisibleY  +  (ByLines-1)  DO 
Move (StorePtrs [I] A, ShowPtrs [I] A, VisibleX  *  2); 

(  And  finally,  update  virtual  screen's  TopLine  counter:  ) 

TopLine  :=  TopLine  +  ByLines 
END 

END 

END; 


{  You  *must*  init  a  V-Screen  through  this  proc  before  using  it:  ) 
PROCEDURE  InitScreen (Target  :  ScreenPtr;  Visible  :  Boolean); 

VAR 

I  :  Integer; 

BEGIN 

WITH  Target A  DO 


(  SCREENS  Initialization  Section:  } 

BEGIN 

CurrentAttr  :-  $07;  {  $07  is  the  "normal"  video  attribute  ) 

END. 

End  Listing  Two 


Listing  Three 


, - 1 

(  SCREENTEST  ) 

(  Virtual  screen  demo  program  ) 

(  ) 

{  by  Jeff  Duntemann  KI6RA  } 

{  Turbo  Pascal  5.0  ) 

{  Last  modified  12/24/88  } 

I - ) 


PROGRAM  ScreenTest; 


USES  DOS, 

Textlnfo, 

Screens; 


[  Standard  Borland  unit  } 

{  Given  last  issue;  DDJ  3/89  ) 
(  Given  this  issue;  DDJ  4/89  } 


CONST 

PanBy 


[  Specifies  #  of  lines 


to  pan  at  once  ) 


VAR 

I 

Check 

Ch 

Extended 

Scancode 

Shifts 

TestScreen 

My  Screen 

FileName 

TestFile 

HalftoneAtom 

InString 


:  Integer; 

:  Integer; 

:  Char; 

:  Boolean; 

:  Byte; 

:  Byte; 

:  Screen; 

:  ScreenPtr; 

:  String80; 

:  Text; 

:  ScreenAtom; 
:  String80; 


( -»»GetKey«« - ) 

<  } 

(  Filename:  GETKEY . SRC  —  Last  modified  7/23/88  ) 

(  } 


{  This  routine  uses  ROM  BIOS  services  to  test  for  the  presence  ) 
{  of  a  character  waiting  in  the  keyboard  buffer  and,  if  one  is  } 
(  waiting,  return  it.  The  function  itself  returns  a  TRUE  } 
(  if  a  character  has  been  read.  The  character  is  returned  in  ) 
{  Ch.  If  the  key  pressed  was  a  "special"  (non-ASCII)  key,  the  ) 
(  Boolean  variable  Extended  will  be  set  to  TRUE  and  the  scan  ) 
(  code  of  the  special  key  will  be  returned  in  Scan.  In  ) 
(  addition,  GETKEY  returns  shift  status  each  time  it  is  called  } 
{  regardless  of  whether  or  not  a  character  was  read.  Shift  } 
(  status  is  returned  as  eight  flag  bits  in  byte  Shifts,  } 
(  according  to  the  bitmap  below:  } 


(  BITS  } 

I  7  6  5  4  3  2  1  0  ) 

(  1  .  INSERT  (l=Active)  ) 

{  .1 . CAPS  LOCK  (1-Active)  ) 

{  .  .  1 . NUM  LOCK  (l=Active)  ) 

{  ...  1  ...  .  SCROLL  LOCK  (1-Active)  ) 

{  1  ALT  (1-Depressed)  ) 

(  . 1  .  .  CTRL  (l=Depressed)  } 

I  . 1  .  LEFT  SHIFT  (1 -Depressed)  } 

{  .  1  RIGHT  SHIFT  (1-Depressed)  } 

<  } 

{  Test  for  individual  bits  using  masks  and  the  AND  operator:  ) 

<  ) 

{  IF  (Shifts  AND  $0A)  =  $0A  THEN  CtrlAndAltArePressed;  ) 

I  ) 

{  From:  COMPLETE  TURBO  PASCAL  5.0  by  Jeff  Duntemann  ) 

{  Scott,  Foresman  &  Co.,  Inc.  1988  ISBN  0-673-38355-5  } 

I - } 
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FUNCTION  GetKey (VAR  Ch  :  Char; 

VAR  Extended  :  Boolean; 

VAR  Scan  :  Byte; 

Var  Shifts  :  Byte)  :  Boolean; 

VAR  Regs  :  Registers; 

Ready  :  Boolean; 

BEGIN 

Extended  :=  False;  Scan  :*■  0; 

Regs. AH  : *  $01;  {  AH=1:  Check  for  keystroke  } 

Intr ($16, Regs) ;  j  Interrupt  $16:  Keyboard  services) 

Ready  (Regs. Flags  AND  $40)  =  0; 

IF  Ready  THEN 
BEGIN 

Regs. AH  :«  0;  (  Char  is  ready;  go  read  it...  } 

Intr ($16,Regs) ;  j  ...using  AH  *  0:  Read  Char  } 

Ch  :=  Chr (Regs.AL) ;  {  The  char  is  returned  in  AL  ) 

Scan  :=  Regs. AH;  {  ...and  scan  code  in  AH.  ) 

IF  Ch  *  Chr(0)  THEN  Extended  :=  True  ELSE  Extended  :=  False; 
END; 

Regs. AH  $02;  {  AH=2:  Get  shift/alt/ctrl  status  ) 

Intr ($16, Regs) ; 

Shifts  :=  Regs.AL; 

GetKey  :=  Ready 
END; 


BEGIN 

IF  ParamCount  <  1  THEN  (  No  file-ee,  no  work-ee  ) 

BEGIN 

Writeln ( ' »>SCRNTEST  by  Jeff  Duntemann  '); 

Writeln('  Virtual  screen  demo  program'); 

Writeln ('  Version  of  12/24/88  —  Turbo  Pascal  5.0'); 

Writeln('  Invoke:  SCRNTEST  <textfile>  <CR>' ) ; 

Writeln ('  Use  up/down  arrows  to  pan  window;'); 

Writeln ('  the  DEL  key  to  blank  out  a  line.'); 

Writeln ('  Press  "Q"  or  "q"  to  quit...'); 

END 

ELSE 

BEGIN 

FileName  :=  ParamStr(l);  {  See  if  named  file  can  be  opened  } 
Assign (TestFile, FileName) ; 

($1-)  Reset (TestFile) ;  ($1+) 

Check  IOResult; 

IF  Check  <>  0  THEN  {  If  not,  complain:  ) 

BEGIN 

Writeln ('»Test  file  '.FileName,'  Cannot  be  opened.'); 
Writeln  ('  Please  invoke  again  with  a  valid  file  name.'); 

END 

ELSE 

BEGIN  {  File  can  be  opened;  let's  read  it  into  a  V-screen  ) 
HalftoneAtom.Ch  :=*  Chr(177);  HalftoneAtom.Attr  $07; 
MyScreen  :«  8TestScreen; 

InitScreen (MyScreen,True) ;  (  Allocate  &  init  the  screen  ) 

ClrScreen (MyScreen, ClearAtom) ;  {  Clear  the  screen  ) 

IF  NOT  EOF (TestFile)  THEN  {  If  the  file  isn't  empty...  ) 
BEGIN 

I  :■  1;  {  Start  from  line  1  ) 

WHILE  (NOT  EOF (TestFile) )  AND  (I  <-  HEIGHT)  DO 
BEGIN 

Readln (TestFile, InString) ; 

{  Truncate  each  line  at  70  columns:  ) 

InString  Copy (InString, 1, 70) ; 

{  Write  line  number  to  the  V-Screen:  ) 

WriteTo (MyScreen, IntStr (I, 5) ) ; 

{  Write  the  data  line  to  the  V-Screen:  } 

WritelnTo (MyScreen, ' :  ' +InString) ; 

Inc (I)  {  Increment  the  line  counter  } 

END; 

{  Up  to  66  lines  of  the  file  are  on  the  screen.  } 

(  Here  we  pan  up  on  the  up  arrow,  and  down  on  ) 

{  the  down  arrow.  'Q'  quits  the  program.  } 

Extended  False; 

REPEAT 

IF  Extended  THEN 
CASE  Scancode  OF 

(  DEL  }  83  :  WITH  MyScreen*  DO 

ClearLine(ShowPtrs[TopLine  +  (VisibleY  DIV  2)], 
VisibleX, Half toneAtom) ; 

{  Up  Arrow  }  72  :  Pan (MyScreen, Up, PanBy) ; 

{  Down  arrow  )  80  :  Pan (MyScreen, Down, PanBy) ; 

END;  {  CASE  } 

REPEAT  UNTIL  GetKey (Ch, Extended, Scancode, Shifts) ; 

UNTIL  Ch  IN  [ ' Q' , ' q' ] ; 

END 

END 

END 

END. 


End  Listings 
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Database  Applications  has  announced 
a  business  and  scientific  graphics  prod¬ 
uct  called  dR&G,  which  is  driven  by 
4GL  statements.  This  software  package 
combines  graphics  with  tabular  report¬ 
ing,  mail  merge,  and  SQL-like  queries 
of  relational  databases. 

Chart  styles  include  bar,  pie,  line, 
area  filled,  histogram  and  scatter,  as 
well  as  fitted  curves  with  forward  or 
backward  moving  averages,  regression 
lines,  and  exponential/logarithmic 
curves  with  prediction  and  confidence 
limits  displayed.  Up  to  six  data  sets 
may  be  plotted  at  once,  with  automatic 
scaling  to  fit  the  chart  in  vertical  and 
horizontal  formats. 

Charts  and  tabular  reports  are  speci¬ 
fied  as  4GL  statements,  as  in  “Graph 
as  Bars,  Sales  by  Day  Across  Region,” 
which  yields  multilevel  bars  summariz¬ 
ing  daily  transaction  data  from  a  dBase 
file  or  16  related  dBase  files.  4GL  state¬ 
ments  are  stored  in  one  or  many  pro¬ 
gram  files  and  may  be  called  by  name 
or  from  a  menu,  or  they  can  be  entered 
as  ad  hoc  queries. 

dR&G  produces  charts,  linear  regres¬ 
sion  statistics  for  up  to  six  dependent 
variables,  new  template  files,  tabular 
data  reports,  cross-table  matrix  reports, 
custom  format  reports,  letter  reports, 
mail-merge,  and  mailing  labels,  as  well 
as  program  files  to  reproduce  all  of  the 
above.  The  user  has  control  over  chart 
labelling,  the  treatment  of  missing  data 
values,  the  color  palette,  the  page  size 
and  position,  and  the  use  of  various 
type  fonts.  33  hatch  and  line  patterns, 
up  to  128  colors,  and  over  30  type 
styles  are  supported. 

dR&G  integrates  G-RUN  software  of 
Mightysoft  Corp.  of  Seattle,  Wash., 
with  nonprocedural  language  (NPL)  of 
the  dNPL/Reporter  report  writer  to  pro¬ 
vide  access  of  16  related  databases, 
sorting,  summarizing,  computation,  and 
chart  plotting. 

dR&G  is  priced  at  $179;  the  upgrade 


prepaid  price  for  registered  dNPL/Re¬ 
porter  users  is  $89.  The  company  will 
also  upgrade  NPL/R  database  applica¬ 
tion  systems  with  dR&G  capability  at 
the  same  upgrade  price.  Reader  Serv¬ 
ice  No.  26. 

Database  Applications  Inc. 

400  Wall  St. 

Princeton,  NJ  08540 
609-924-2900 

Glockenspiel’s  C+  +  1.2,  the  AT&T  de¬ 
signed  superset  of  ANSI  C,  will  be  re¬ 
leased  by  Imagesoft.  Encapsulation, 
one  of  the  product’s  features,  helps 
users  develop  pretested  invulnerable 
classes.  C+  +  1.2  also  features  reusing 
stable  code  — inheritance  helps  users 
reuse  their  pretested  classes  in  new 
circumstances. 

Also  included  is  type  checking,  an 
optimized  code  generator  in  Microsoft 
C  5.x  that  supports  mixed  model  key¬ 
words,  a  CL-compatible  seamless  com¬ 
pilation  command,  and  support  for  both 
real  and  protected  mode  development 
and  delivery  environments  on  OS/2. 

Glockenspiel  C+  +  is  grammar  com¬ 
patible  with  designer  C+  +  on  Unix  and 
VMS,  as  well  as  Domain  C+  +  on  Apollo; 
it  also  implements  the  standard  AT&T 
1.2  grammar  for  C+  +. 

Containing  over  600  pages  of  docu¬ 
mentation  that  covers  topics  such  as 
mixed  language  programming,  imple¬ 
menting  dynalink  libraries  in  C+  +,  de¬ 
bugging  with  CodeView,  and  mixed 
model  development,  Glockenspiel  C+  + 
sells  for  $3,995.  Reader  Service  No.  27. 
Imagesoft 
6-57  158th  St. 

Beechhurst,  NY  11357 
718-746-9069 

Lattice  has  released  Version  3  4  of  the 
Lattice  C  compiler  for  DOS  and  OS/2. 
This  latest  upgrade  includes  CodeProbe, 
a  full-screen,  source-level  debugger  and 
also  features  an  integrated  editor,  linker, 
and  librarian. 

Lattice’s  debugger  can  be  used  with 
a  mouse  and  offers  three  ways  to  dis¬ 
play  source  code.  A  high-level  view 
shows  only  the  C  source  lines,  a  low- 
level  view  shows  only  the  assembler 
code,  and  the  mixed  view  shows  both. 
Depending  on  which  view  is  used,  break¬ 
points  and  other  program  references 
can  be  made  by  way  of  source  line 
numbers  and  either  absolute  or  relative 
addresses. 

In  Version  3-4,  CodeProbe  operates 
under  DOS  or  OS/2  real  mode.  Sup¬ 
port  is  provided  for  debugging  family¬ 
mode  programs  that  use  the  OS/2  EXE 
format  but  run  under  DOS.  Registered 
users  receive  a  free  upgrade,  which 
extends  CodeProbe  to  OS/2  protected 


mode.  The  upgraded  version  supports 
multithread  and  multiprocess  debug¬ 
ging  and  includes  features  for  testing 
Presentation  Manager  programs. 

Lattice  C  for  DOS  and  OS/2,  Version 
3.4,  sells  for  $450.  The  package  in¬ 
cludes  the  compiler,  linker,  CodeProbe 
and  C-SPRITE  debuggers,  integrated  LSE 
editor,  bind  utility,  object  module  li¬ 
brarian,  disassembler,  API,  graphics,  stan¬ 
dard  Lattice  C  libraries,  and  documen¬ 
tation.  Registered  users  of  Version  3-3 
receive  Version  3.4  at  no  charge;  users 
of  earlier  versions  may  upgrade  for  $75. 
Reader  Service  No.  28. 

Lattice  Inc. 

2500  S  Highland  Ave. 

Lombard,  IL  60148 
312-916-1600 

Softaid  has  introduced  a  version  of 
MTBASIC  Multitasking  Basic  Compiler 
targeted  to  Intel’s  Wildcard  88.  MTBA¬ 
SIC  is  an  interactive  compiler  designed 
to  be  included  in  ROM  on  systems  de¬ 
signed  around  the  Wildcard. 

MTBASIC  includes  built-in  multi¬ 
tasking  that  supports  up  to  ten  concur¬ 
rent  tasks;  a  windowing  environment 
is  also  supplied.  MTBASIC  for  the  Wild¬ 
card  is  provided  as  a  set  of  source 
codes  so  that  it  can  be  customized  to 
suit  the  OEM’s  requirements.  The  com¬ 
piler  is  burned  into  a  ROM  that  resides 
on  the  Wildcard. 

MTBASIC  is  designed  for  the  diskless, 
ROM-based  equipment  typically  de¬ 
signed  with  the  Wildcard.  Selling  for 
$6,500,  this  product  includes  source 
code.  Reader  Service  No.  29. 

Softaid  Inc. 

8930  Rte.  108 
Columbia,  MD  21045 
800-433-8812 

The  DOS  version  (2.1)  of  the  True 
Basic  Language  System  includes  VGA 
graphics  support,  new  manuals,  trace 
utility,  and  compatibility  between  ma¬ 
chine  types  supported  by  True  Basic 
(IBM,  Macintosh,  Amiga,  and  Atari). 
Current  users  can  upgrade  for  $29-95. 

A  Unix  version,  taigeted  to  the  higher- 
education  and  government  markets,  will 
be  released  during  the  fourth  quarter 
of  this  year.  Reader  Service  No.  30. 

True  Basic  Inc. 

45  Theodore  Fremd  Ave. 

Rye,  NY  10580 

914-921-1630 

800-TRBASIC 

Version  3-0  of  the  PC-MOS  multiuser 
DOS-compatible  operating  system  from 
The  Software  link  (TSL)  has  been 
announced.  The  new  release  supports 
Windows/286,  bringing  multiuser  ca- 
(continued  on  page  150) 
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(continued  from  page  146) 
pabilities  to  the  windows  environment 
through  devices  that  support  high¬ 
speed,  bit-mapped  graphics,  such  as 
TSL’s  VNA  and  SunRiver’s  Cygna/386 
workstation. 

Release  3-0  hardware  support  addi¬ 
tions  include  DCA’s  Irma2  and  the  Intel 
Inboard  386  and  386/PC.  Also  added 
are  support  of  Compaq’s  386/20e,  the 
IBM  PS/2  mouse,  and  Everex’s  Quick 
02  controller  card.  Support  for  several 
tape  backup  systems  — such  as  Priam, 
Everex’s  Excell  Streaming  60  Tape  Drive, 
the  Wangtek  tape  backup  system,  and 
the  Techmar  60E  for  the  IBM  PS/2  — 
has  also  been  added. 

Software  compatibility  includes  Da- 
taFlex  2.3,  Clarion  Professional  Devel¬ 
oper,  Wordperfect  5.0,  dBaselV  1.0,  Ex¬ 
cel  2.0,  Sidekick  Plus  1.0,  ACCPAC  Plus 
Accounting  5.0,  Q&A  2.0,  and  Advanced 
Revelation  1.0. 

PC-MOS  includes  an  option  for  de¬ 
layed  write  caching;  users  also  can  de¬ 
fine  cache  sizes  and  determine  how 
often  read  requests  are  written  to  the 
disk.  Also,  PC-MOS  allows  the  PC-MOS 
kernel  to  be  relocated  to  noncontigu¬ 
ous  areas  of  upper  memory. 

This  product  includes  support  for 
TSR  programs  such  as  Sidekick  and 
SideKick  Plus.  Spanish  and  German  key¬ 
board  drivers  and  language  translations 
are  supported.  PC-MOS,  Version  3  0, 
sells  for  $195  (single  user),  $595  (five 
user),  and  $995  (25  user).  Reader  Serv¬ 
ice  No.  31. 

The  Software  Link 
3577  Parkway  Lane 
Norcross,  GA  30092 
404-448-5465 

Howard  W.  Sams  &  Co.  has  released 
three  new  books:  The  Waite  Group’s 
OS/2  Programmer’s  Reference  by  Asael 
Dror,  The  Waite  Group’s  Turbo  C Bible 
by  Naba  Barkakati,  and  Turbo  C  Pro¬ 
gramming  for  the  PC,  Revised  Edition 
by  Robert  Lafore. 

The  Waite  Group’s  OS/2  Program¬ 
mer’s  Reference  is  a  debugged  refer¬ 
ence  to  the  set  of  over  200  OS/2  API 
function  calls.  This  distillation  of  the 
OS/2  Software  Developer’s  Kit  is  di¬ 
vided  into  categories,  each  with  its  own 
tutorial.  Within  each  category,  func¬ 
tions  are  presented  alphabetically,  each 
with  its  purpose,  syntax,  and  example, 
including  explanations  of  error  codes, 
uses,  cautions,  and  references  to  re¬ 
lated  APIs.  Book  no.  22645,  it  is  848 
pages  and  sells  for  $24.95. 

For  programmers  using  Borland’s 
Turbo  C  compiler,  The  Waite  Group’s 
Turbo  C  Bible  includes  tutorials  and 
explanations  to  point  out  the  different 
purposes  and  uses  of  each  function. 


Compatibility  check  boxes  show  port¬ 
ability  with  Microsoft  C,  Versions  3.0, 
4.0,  and  5.0;  Microsoft  QuickC;  and  the 
Unix  System  V  compilers.  This  book, 
no.  22631,  sells  for  $24.95. 

Turbo  C  Programming  for  the  PC, 
Revised  Edition  includes  graphics  and 
debugger  features.  This  book  moves 
through  the  fundamentals  of  the  lan¬ 
guage  with  a  structured  step-by-step 
approach.  Expanded  to  include  Ver¬ 
sion  2.0  (but  still  compatible  with  Turbo 
C  1.0  and  1.5),  it  covers  the  graphics 
library,  graphics  modes,  the  Debug¬ 
ging  Tracer,  and  it  highlights  ANSI  C 
features.  This  book  sells  for  $22.95  and 
is  no.  22660.  Reader  Service  No.  32. 
Howard  W.  Sams  &  Co. 

4300  W  62nd  St. 

Indianapolis,  IN  46268 
800-428-7267 

Oregon  Software  has  released  Ver¬ 
sion  1.2a  of  Oregon  C+  +  for  the  Sun-3. 
This  update  is  highlighted  by  the  intro¬ 
duction  of  a  mouse-driven,  window 
interface  to  the  C+  +  source-level  de¬ 
bugger. 

The  window  interface  consists  of  five 
windows:  a  status  window  that  dis¬ 
plays  file  name,  line  number,  function 
name,  and  scope  information;  a  source 
window  that  displays  the  source  text; 
a  button-panel  window  that  allows 
mouse-click  access  to  the  debugger’s 
commands;  a  dialog  window  for  the 
debugger’s  I/O;  and  an  application  win¬ 
dow  for  the  application’s  I/O.  The  sepa¬ 
rate  windows  for  application  and  de¬ 
bugger  I/O  mean  that  the  graphical 
layout  of  an  application’s  I/O  is  not 
scrambled  by  the  debugger’s  I/O.  The 
source,  dialog,  and  application  win¬ 
dows  are  scrolling. 

Oregon  C+  +,  Version  1.2a,  sells  for 
$1,900  for  a  single-user  license,  $4,750 
for  1  -  6  node  network  on  a  single  file 
server,  and  $12,000  for  an  unlimited 
node  network  on  a  one  file  server. 
Reader  Service  No.  36. 

Oregon  Software 
6915  SW  Macadam  Ave. 

Portland,  OR  97219-2397 
503-245-2202 
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$  W  A  I  N  E'  S  FLAMES 


Words  &  Figures,  and  a  Programmer’s  Word  Processor 


Puzzle:  Who  said  the  following,  when,  and  where?  Hint:  It  was  not  Ted  Nelson  in  “Those 
Unforgettable  Next  Two  Years”  at  the  Second  West  Coast  Computer  Faire  in  San  Jose  in  1977. 
The  answer  will  be  revealed  at  the  bottom  of  the  page.  Don’t  peek. 

“Information  technology  represents  a  radical  discontinuity  in  industrial  history. ...  It  means 
changing  your  basic  assumptions  about  what  business  organizations  are  supposed  to  look  like. 

“For  instance,  you  have  to  abandon  the  assumption  that  managers  are  different  from  the  people 
they  manage.  One  of  the  things  that  made  them  appear  different  in  the  past  was  that  they  had 
information  that  the  people  they  managed  didn’t  have.  Managers,  we  said,  were  the  people 
uniquely  equipped  to  deal  with  information,  and  for  that  reason  we  granted  them  authority.  ...  If 
you  used  to  think  that  what  separated  managers  from  workers  was  information,  you  have  to 
abandon  that  assumption.  Workers  will  have  information  too.” 


Shortly  after  I  transmitted  last  month’s  column  in  which  I  waxed  wroth  over  misuses  of  words  and 
figures  in  the  computer  press,  Jon  Erickson  showed  me  the  cover  of  the  January  17, 1989  issue  of 
PC  Magazine,  with  its  award  for  technichal  (sic)  excellence.  Then  MacUser  features  editor,  John 
Anderson,  passed  me  a  copy  of  the  January  1  New  York  Times  Book  Review  section,  with  a 
delightfully  relevant  article  by  John  Allen  Paulos. 

Paulos  decries,  as  I  did,  American  innumeracy,  the  analog  to  illiteracy  in  the  realm  of  numbers. 
He  points  out  that  most  people  have  no  real  feeling  for  the  difference  between  a  million  and  a 
trillion,  and  lack  the  simple  skills  necessary  to  assess  risks  to  life,  limb,  and  freedom.  (Canceling  a 
European  trip  for  fear  of  terrorists  is  silly;  the  expected  value  of  the  payoff  in  a  lottery  is  always  less 
than  the  cost  of  a  ticket;  even  for  very  accurate  tests,  mandatory  AIDS  testing  would  probably 
produce  vastly  more  false  positives  than  correct  identifications.) 

It  matters  that  the  public  not  be  quite  such  numerically  numbskulls,  Paulos  claims,  because 
innumeracy  makes  people  suckers  for  simple  scams  and  makes  them  poor  citizens  in  a  world 
where  numbers  count.  I  decided  to  discuss  the  subject  on  this  page  from  time  to  time  because  Dr. 
Dobb ’s  readers  are  as  good  a  group  as  I  can  imagine  to  take  the  message  forth,  and  even  they  (you, 
[we])  need  an  occasional  reminder.  Even  a  generally  numerate  book  such  as  Alexander  Hellemans 
and  Bryan  H.  Bunch’s  The  Timetables  of  Science  (Simon  and  Schuster,  1988)  can  slip  up:  “correct  to  n 
decimal  places”  means  rounded  to  n  places,  not  truncated  at  the  nth  place.  The  expression  “n  times 
more”  has  been  so  thoroughly  corrupted  to  mean  “n  times  as”  that  it’s  probably  unsalvageable. 

Paulos’s  forthcoming  book,  Innumeracy:  Mathematical  Illiteracy  and  Its  Consequences ,  should 
be  one  such  reminder.  So  are  Darrell  Huffs  classic  little  How  to  Lie  with  Statistics  (W.W.  Norton  & 
Co.,  1954)  and  The  Mismeasure  of  Man  by  Stephen  Jay  Gould,  an  impressive  debunking  of  one  of 
the  hoariest  and  most  malignant  of  statistical  fictions,  IQ. 


Paragon’s  QUED/M,  a  text  editor  for  the  Macintosh,  is  highly  regarded  by  Mac  programmers.  Now 
Paragon  has  introduced  a  full  word  processor  based  on  QUED/M,  and  as  soon  as  I  saw  the  feature 
list,  1  requested  the  product.  Still  a  sucker  for  a  well-written  press  release,  I  guess. 

1116  features  of  Nisus,  though,  look  like  Paragon  has  been  peeking  at  my  word  processor  feature 
wish  list.  The  search-and-replace  feature  is  a  GREP  that  knows  about  fonts  and  styles  and  even 
graphics.  You  can  draw  directly  into  the  text,  overlap  text  and  pictures,  and  wrap  text  around  art, 
and  can  place  pictures  in  headers  or  footers  (of  which  you  can  have  any  number).  Like  QUED/M, 
Nisus  lets  you  record,  write,  and  edit  macros;  and  gives  you  essentially  unlimited  undoing  of  almost 
any  changes. 

Nisus  has  a  modeless  catalog  function  for  opening  files,  searching  through  unopened  files,  and 
other  file  operations.  Paragon  claims  that  Nisus  can  locate  a  word  or  phrase  in  unopened  files  faster 
than  other  word  processors  can  search  one  open  document.  It’ll  balance  quotation  marks  and 
parentheses  and  add  line  numbers  on  screen,  and  will  compare  files. 

It  seems  to  me  that  anybody  who  writes  code  and  English  on  a  Macintosh  would  be  intrigued 
by  what  Paragon  claims  for  Nisus,  and  as  soon  as  I’ve  worked  with  the  product,  I’ll  give  you  my 
report  on  how  well  Paragon  delivered. 

Answer  to  puzzle:  Harvard  Business  School  Associate  Professor  Shoshana  Zuboff,  in  Inc. 
magazine  January,  1989.  Computer  Lib  comes  to  HBS.  What  on  earth  does  Zuboff  think  could  drive 
managers  to  lose  their  grip  on  the  manager’s  edge  —  information? 

Competition.  Companies  that  fail  to  put  the  information  in  the  hands  of  those  who  carry  out 
policy  will  not  be  able  to  compete  with  those  that  do. 

Michael  Swaine 
editor-at-large 
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QUICK  C  VERSUS  TURBO  C  68 

by  Scott  Robert  Ladd 

At  first  glance,  Borland’s  Turbo  C  and  Microsoft  C  might  appear  to  be  similar  feathers  from 
the  same  bird  but,  as  Scott  discovers,  that  isn’t  necessarily  the  case.  Join  him  as  he  discusses 
the  strengths  and  weaknesses  of  these  two  popular  C  compilers. 


PROGRAMMING  PARADIGMS  107 

by  Michael  Swaine 

It  was  Robert  Floyd's  1978  Turing  Award  lecture  on  programming  paradigms  that  inspired 
Michael’s  column  in  the  first  place.  Now,  more  than  10  years  later,  Michael  interviews 
Professor  Floyd  to  see  how  he  and  the  world  of  programming  have  changed. 

C  PROGRAMMING  115 

by  Al  Stevens 

This  month,  Al  builds  the  engine  of  a  C-like  interpreter,  which  can  be  added  as  a  script 
interpreter  to  his  SMALLCOM  communications  project.  Al  then  follows  up  earlier  columns 
by  adding  his  two  cents  about  QuickC  2.0,  as  well  as  the  goings  on  of  ANSI  C. 

GRAPHICS  PROGRAMMING  124 

by  Kent  Porter 

Viewports  not  only  provide  you  with  a  window  to  the  world,  they  let  you  define  the 
boundaries  of  that  world.  At  least  that’s  what  Kent  and  his  dog  found  out. 

STRUCTURED  PROGRAMMING  132 

by  Jeff  Duntemann 

Typecasting  is  a  problem  that  has  traditionally  plagued  Hollywood  actors,  but  as  Jeff  points 
out,  it  can  be  a  problem  for  programmers  as  well. 


CREATING  TSRs  WITH  TURBO  PASCAL,  PART  I 

by  Ken  L.  Pottebaum 

In  this  first  installment  of  a  two-part  series,  Ken  discusses  TSR  basics  and  presents  the  tools 
necessary  to  write  memory-resident  programs.  Next  month  he  will  put  this  theory  to  work. 

KERMIT  MEETS  MODULA-2 

by  Brian  R.  Anderson 

Modula-2  enabled  Brian  to  implement  each  layer  of  the  Kermit  communications  protocol 
as  separate  modules  and  in  this  article  he  shows  you  how  he  did  it. 

LANGUAGE-INDEPENDENT  DYNAMIC  PSEUDOSTRUCTURES 

by  Bruce  W.  Tonkin 

Whenever  data  must  be  compared  in  a  variety  of  different  formats,  data  conversion 
sometimes  pays  off.  Bruce  discusses  how  you  perform  conversion  and  what  kind  of  results 
you  can  expect. 

TAWK,  A  SIMPLE  INTERPRETER  IN  C++ 

by  Bruce  Eckel 

The  data-encapsulation  features  of  C++  let  you  create  more  sophisticated  programs  without 
adding  complexity.  Bruce’s  “tiny”  AWK  implementation  illustrates  this  and  more. 

QUICKDRAWING  WITH  XCMDs 

by  Jay  Martin  Anderson 

Speed  up  your  HyperCard  applications  by  accessing  QuickDraw  directly.  Jay  shows  you 
how  — and  how  to  avoid  pitfalls  when  doing  so. 

RLE  REVISITED 

by  Phil  Daley 

The  run-length  encoding  technique  we  presented  in  February  generated  a  flurry  of  response, 
and  so  here’s  another  approach  to  the  problem. 
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The  Open 
Editorial 


A  L 


A  few  weeks  back,  Mike,  Kent,  and  I  spent  a  couple  of  days  at  Microsoft’s  annual  systems 

seminar  hearing  about  the  future  as  Microsoft  sees  it.  It  should  come  as  little  surprise  that  MS 
sees  OS/2  as  part  of  everyone’s  future.  Actually,  1  feel  better  about  OS/2  and  its  chances  of 
survivability  after  hearing  some  of  MS’s  strategies.  Nevertheless,  as  I’ve  said  before,  if  OS/2  is  to 
be  accepted,  then  MS  needs  to  get  out  the  80386  version  that  will  provide  access  to  the  32-bit  linear 
address  space,  allow  multiple  DOS  sessions,  include  the  high-performance  file  system,  and  more. 
But  it  isn’t  a  trivial  task  to  rewrite  the  several  hundred  thousand  lines  of  assembly  code  that  make 
up  OS/2.  Even  though  MS  says  this  is  one  of  their  top  priorities,  it  bothered  me  that  we  didn’t  see 
a  technology  demonstration  of  OS/2-386  at  the  seminar  (MS  is  generally  open  about  technology 
demos  when  they  are  making  progress)  and  it  makes  me  nervous  about  MS  hitting  their  mid  1990 
target  for  getting  the  386  version  out  to  market. 

I  was  also  interested  in  hearing  more  about  what  Microsoft  intends  on  doing  with  object-oriented 
technology.  When  the  words  “C++  compiler”  flashed  on  the  overhead  screen,  I  thought  that  we 
might  be  onto  something.  However,  it  turned  out  they  weren’t  too  specific  on  their  plans  because, 
it  seemed,  they  hadn’t  really  made  up  their  mind  yet.  The  internal  debate  seems  to  concern  whether 
or  not  they  should  put  out  a  stand-alone  C++  compiler  or  add  C++  extensions  to  existing  C 
compilers.  As  best  as  I  could  tell,  the  current  preference  is  to  add  extensions  to  the  Microsoft  C 
compiler  sometime  before  the  end  of  this  year.  But  C++  isn’t  the  only  object-oriented  path  MS  will 
be  pursuing.  They  also  talked  about  a  “Visual”  Basic  which,  among  other  things,  will  let  people 
write  graphic  user-interface  applications  without  having  to  do  a  lot  of  coding. 

One  thing  that  I  found  particularly  interesting  is  that  long-time  language  guru  Greg  Whitten,  who 
has  worked  with  all  language  implementations  in  the  MS  systems  group  over  the  past  10  years, 
recently  moved  over  to  the  application  development  side  of  the  company.  His  mission  there  seems 
to  be  two-fold:  to  direct  the  development  of  new  object-oriented  applications  and  to  apply 
object-oriented  technology  to  the  applications  development.  According  to  Whitten,  Microsoft’s 
various  applications  make  up  several  million  lines  of  code  and  the  object-oriented  paradigm  is  one 
way  for  MS  to  keep  things  under  control  and  on  schedule.  It’s  worth  noting  that  the  recent  dramatic 
drop  in  MS  earnings  was  attributed  to  the  inability  to  get  application  products  out  in  time,  and  they 
apparently  believe  OOPs  can  prevent  this  in  the  future. 


As  if  two  days  of  OS/2  wasn’t  enough,  the  UniForum  conference,  which  followed  close  on  the 
heels  of  the  MS  seminar,  left  me  with  several  impressions:  1.  The  Unix  market  is  as  fragmented  as 
ever.  2.  The  widespread  acceptance  of  the  X  Window  protocol  is  one  of  the  few  consistent  things 
that  ran  throughout  the  show;  and  3.  I'm  tired  of  consortiums  and  “open”  anything.  Let’s 
see  .  .  .  there’s  the  88open  consortium,  the  SPARC  International  consortium,  the  OSF  consortium, 
and  the  Unix  International  consortium.  Then  there’s  Open  Look,  Open  Systems,  Open  Desktop, 
Open  Font,  and  X  Open. 

Here’s  an  idea.  Someone  should  go  out  and  get  the  rights  to  the  name  Open  Window  because, 
considering  the  proliferation  of  windowing  systems,  some  outfit  is  bound  to  come  out  with  a 
product  by  this  name  and  if  you  have  the  rights  to  the  name,  you  might  be  able  to  make  a  couple 
of  bucks.  But  then,  somebody  has  probably  already  tied  it  up  anyway. 

Actually,  the  real  future  of  the  prefix  “open”  may  be  in  vertical  market  applications.  How  about 
a  package  for  dentists  called  Open  Mouth,  or  a  program  for  duck  hunters  called  Open  Season.  Or 
maybe  even  a  product  for  trouser  manufacturers  called  Open  Fly.  Hey,  will  someone  please  open 
the  door  so  I  can  get  out  of  here. 


editor-in-chief 
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LETTER  S 


SEI  Reactions 

Dear  DDJ, 

I  read  with  interest  your  editorial 
“Swaine’s  Flames”  in  the  November  1988 
issue  of  Dr.  Dobb’s  Journal.  I  regret 
that  your  experience  has  given  you  a 
negative  impression  of  the  Software 
Engineering  Institute  (SEI)  and  would 
like  to  explain  that  situation  from  my 
perspective. 

According  to  your  account,  the  SEI 
did  not  meet  a  commitment  to  produce 
an  article  for  your  September  issue.  As 
best  as  I  can  trace  your  telephone  od¬ 
yssey  through  the  SEI,  your  request  for 
an  article  was  initially  turned  down 
because  of  the  prior  commitments  of 
those  staff  members  who  could  have 
either  written  the  article  or  committed 
resources  to  having  it  written. 

Unfortunately,  the  person  who  fi¬ 
nally  accepted  your  request  thought 
he  was  making  a  personal  commitment, 
but  you  thought  you  were  getting  an 
SEI  commitment.  We  did  not  perceive 
that  problem  until  a  draft  of  the  article 
went  to  review.  This  is  where  SEI  com¬ 
munication  failed,  and  we  apologize. 
Reviewers  found  the  draft  incomplete  — 
not  ready  for  publication  without  sig¬ 
nificant  effort.  Meanwhile,  your  dead¬ 
line  was  rapidly  approaching. 

At  this  point,  one  of  our  program 
directors  called  to  let  you  know  that 
the  draft  did  not  meet  our  standards 
and  that  we  could  not  revise  it  in  time 
to  meet  your  deadline.  In  later  conver¬ 
sations  with  you,  SEI  staff  agreed  to 
produce  an  article  sometime  in  the  fu¬ 
ture  but  made  no  specific  commitment, 
or  so  they  thought.  Obviously,  you  felt 
otherwise. 

I  am  surprised  by  the  inference  you 
draw  from  this  experience  about  soft¬ 
ware  engineering  and  bureaucratic  de¬ 
lay.  I  see  the  situation  quite  differently. 
An  important  characteristic  of  a  suc¬ 
cessful  software  engineering  organiza¬ 
tion  is  that  it  meets  commitments  with 
quality  results  on  time  and  within 
budget.  At  the  SEI,  we  take  commit¬ 
ments  seriously:  We  don’t  make  one 
unless  we  intend  to  honor  it.  Ironically, 
this  caution  in  making  commitments  is 


what  prompted  staff  members  to  turn 
down  your  request  in  the  first  place. 

We  undoubtedly  have  made  and  will 
in  the  future  make  mistakes  at  the  SEI. 
I  regret  that  this  instance  of  miscom- 
muncation  left  you  with  a  poor  opin¬ 
ion  of  us.  If  you  are  still  interested  in 
publishing  an  article  from  the  SEI,  please 
call. 

Larry  E.  Druffel 

SEI  Director 

Pittsburgh,  Penn. 

Jon  responds:  Thanks  for  the  offer  Larry 
and,  yes,  I’d  still  like  to  see  the  article. 
Believe  it  or  not,  I  do  think  the  SEI 
serves  a  useful function  and  that  many 
fine  people  are  associated  with  it.  I 
wish  the  organization  well.  However,  I 
stand  by  my  description  of  my  experi¬ 
ences  with  the  SEI,  experiences  that 
were  substantiated  by  readers  who  have 
also  had  to  deal  with  the  organiza¬ 
tion’s  bureaucracy. 

Dear  DDJ , 

I  was  entertained  by  your  page  in  the 
November  1988  Dr.  Dobb’s  (“Swaine’s 
Flames"  by  Jon  Erickson)  about  your 
difficulties  with  the  Software  Engineer¬ 
ing  Institute  (SEI).  I  don’t  know  much 
about  the  SEI  but,  yes,  the  government 
software  world  is  that  bad.  I’ve  been 
dealing  with  it  for  25  years.  It’s  always 
bad,  and  it’s  been  getting  worse  lately. 
The  last  project  I  worked  on  had  maybe 
five  technical  people  trying  to  modify 
code,  10  or  15  people  trying  to  test  it, 
and  maybe  30  people  running  around 
to  meetings  and  stumbling  over  each 
other  making  decisions  whose  quality 
is  best  left  to  the  imagination.  Aside 
from  an  abnormally  large  number  of 
test  people  — which  for  reasons  too 
complicated  to  go  into  here  made  some 
sense  — this  show  is  not  atypical. 

If  you’d  like  some  real  entertainment, 
obtain  a  copy  of  DOD  standard  2167A, 
which  describes  how  software  is  to  be 
developed  for  mission  critical  software. 
This  gem  and  the  descriptions  of  the 
associated  documentation  include  vir¬ 
tually  every  idea  (good  or  bad)  ever 
espoused  about  the  software  produc¬ 
tion  process.  Now  try  to  imagine  what 
will  happen  when  a  bureaucracy  gets 
a  hold  of  it. 

As  for  software  engineering:  Are  you 
sure  it  exists?  I’d  submit  that  the  differ¬ 
ence  between  engineers  and  tinkers 
(used  in  the  original  non-pejorative 
sense)  is  that  engineers  know  pretty 
much  what  should  happen  when  they 
fire  things  up,  whereas  tinkers  know 
what  they  hope  will  happen.  Engineers 
understand  why  what  they  are  building/ 
fixing  works,  whereas  tinkers  under¬ 
stand  what  to  do  to  make  things  work 


a  lot  of  the  time.  From  what  I’ve  seen, 
most  “software  engineering”  is  really 
software  tinkering.  To  pick  just  one 
example,  the  people  I’ve  seen  “engi¬ 
neering”  real-time  software  rarely  seem 
to  understand  the  difference  between 
synchronous  and  asynchronous  sys¬ 
tems,  and  do  not  understand  enough 
about  queuing  systems  to  predict  the 
performance  of  asynchronous  systems. 
Not  surprisingly,  the  performance  char¬ 
acteristics  of  the  systems  they  build 
often  comes  as  an  unpleasant  surprise 
to  them. 

It  seems  to  me  that  a  process  that 
can’t  predict  size,  performance,  or  cost 
with  any  precision  isn’t  engineering. 
Don’t  get  me  wrong:  Tinkering  is  an 
honorable  art  and  a  necessary  one.  But 
there  are  a  lot  of  situations  where  I’d 
prefer  a  little  more  determinism  in  the 
results. 

It  particularly  disturbs  me  that  I  don’t 
know  where  to  send  someone  who 
honestly  wants  to  learn  about  software 
engineering.  For  algorithms,  I  can  send 
them  to  Rnuth’s  books.  For  informa¬ 
tion  on  testing,  I  can  send  them  to 
Boris  Beizer’s  excellent  books.  But 
where  can  I  send  someone  for  infor¬ 
mation  on  how  to  design  a  system  that 
will  work  and  how  to  predict  how  well 
it  will  work?  I  missed  your  SE  issue.  I’ll 
dig  up  a  copy  and  read  it,  and  I’m 
ordering  a  copy  of  your  SE  Source- 
book.  Perhaps  it  will  help,  but  I’m  not 
optimistic. 

Donald  Kenney 

San  Diego,  Calif. 

XREF  Examination 

Dear  DDJ, 

Kent  Porter’s  December  1988  “Struc¬ 
tured  Programming”  column,  with  the 
XREF  program,  was  entertaining  and 
instructive,  as  his  articles  usually  are. 
Some  of  the  material  calls  for  a  little 
further  discussion. 

All  line  number  references  are  to 
Kent’s  Listing  Three. 

1.  In  describing  the  “binary  B+  tree” 
as  a  combination  of  a  binary  tree  and 
a  B+  tree,  the  article  may  have  con¬ 
fused  data  with  links.  The  structure 
appears  to  me  to  be  a  simple  binary 
tree  with  nodes  containing,  among  other 
data,  pointers  to  singly  linked  lists  of 
line  numbers.  The  fact  that  data  points 
to  a  linked  list  in  no  way  affects  the 
nature  of  the  tree. 

2.  XREF’s  opening  comments  declare 
that  the  program  “uses  binary  trees  and 
doubly-linked  lists  to  effect  B-Tree.” 
Neither  the  article  nor  the  program  deals 
with  doubly-linked  lists  or  B-Trees.  I 
often  use  such  comments  to  describe 
what  I’m  going  to  do,  then  do  some- 
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thing  different.  One  of  A1  Stevens’  re¬ 
cent  crotchets  addresses  that  type  of 
program  comment. 

3.  Because  XREF  operates  on  Modula-2 
as  well  as  Pascal  files,  line  137  should 
test  for  DQuote  as  well  as  Quote ,  and 
line  139  should  set  ScanChar  .  =  ch. 
The  program  logic  appears  to  success¬ 
fully  prevent  ch  from  containing  DQuote 
when  processing  a  syntactically  correct 
Pascal  file,  so  Kent  would  be  justified 
in  leaving  PComment  as  declared  in 
line  35,  rather  than  manipulating  it  in 
response  to  a  command  line  switch  for 
file  type. 

4.  If  Token  (line  119)  finds  an  opening 
comment  or  quotation  marker,  it  calls 
procedure  FindEndOfComment  (line 
48).  FindEndOfComment  then  searches 
for  a  matching  closing  comment  or 
quotation  marker.  If  it  fails  to  find  the 
matching  marker,  it  will  read  beyond 
the  end  of  the  file. 

5.  If  the  tests  in  lines  268  through  282 
are  to  “weed  out  nuisances”  reliably, 
they  should  be  made  against  Up- 
Shift(Symbol)  rather  than  just  Symbol. 
As  written,  they  fail  to  weed  out'  While, 
at  line  323  when  making  a  case-sensi¬ 
tive  listing. 

6.  When  making  a  case-sensitive  list¬ 
ing,  XREF  avoids  placing  the  nodes  in 
their  final  order  until  just  before  mak¬ 
ing  the  report.  A  call  to  the  Alphabetize 
procedure  (line  342)  then  builds  a  new 
tree,  disposing  of  the  old  one  as  it 
goes.  Kent  is  to  be  commended  for 
making  his  case  sensitive  ordering  fol¬ 
low  a  human  collating  sequence,  but 
this  approach  seems  redundant.  I  am 
tempted  to  build  the  tree  in  its  final 
order  on  the  first  pass. 

The  tree  only  needs  be  built  once  if  the 
symbols  are  compared  according  to  the 
case  sensitivity  flag  rather  just  testing 
“if  si  >  s2,”  and  so  forth.  Comp,  shown 
in  my  Listing  will  do  the  job.  My  Listing 
also  contains  BNode,  modified  to  use 
Comp. 

Building  the  tree  in  a  single  pass,  the 
Alphabetize  procedure  (line  342)  can 
be  eliminated,  and  a  few  other  places 
can  be  simplified.  But  does  this  ap¬ 
proach  really  accomplish  anything  use¬ 
ful?  Maybe,  maybe  not. 

Results  from  sample  runs  of  the  origi¬ 
nal  and  modified  XREF  programs,  us¬ 
ing  the  original  XREF.PAS  as  an  input 
file,  are  in  Table  1.  The  modified  ver¬ 
sion  performs  fewer  string  compari¬ 
sons  than  the  original  version  does:  52 
percent  fewer  without  case  sensitivity, 
and  70  percent  fewer  with  case  sensi¬ 
tivity.  The  modified  version  performs 
as  expected  regarding  node  creation. 
The  original  version,  however,  makes 
47  percent  fewer  calls  to  the  Upshift 


function  in  the  case-sensitive  trial. 

Clearly,  getting  reliable  benefit  from 
the  modifications  would  require  fine- 
tuning  Upshift.  Then  I  would  fine-tune 
Comp.  Then  I  would  .  .  .  well,  instead 
of  considering  changes  to  dealing  with 
case  sensitivity,  I  am  considering  de¬ 
tails  of  optimization  — not  the  present 
point.  The  most  I  can  say  about  the 


benefits  of  the  modifications  is  that  they 
justify  further  study. 

As  usual,  Kent  has  provided  material 
to  stimulate  his  readers’  thinking.  My 
thanks  to  him  and  to  DDJ  for  that. 
Please  keep  it  up! 

Karl  Brendel 
Hutchinson,  Kansas 

(continued  on  page  1 58) 


listing  One 

TYPE  CompType  =  (LessThan, Equal, GreaterThan) ; 

FUNCTION  Comp (VAR  si,  s2,  shl,  sh2  :  SymString; 

CaseSen  :  BOOLEAN)  :  CompType; 

(  shl/sh2  are  Upshift <sl/s2)  } 

BEGIN 

IF  CaseSen  THEN  BEGIN 
IF  shl  <  sh2  THEN 
Comp  :■  LessThan 
ELSE  IF  shl  >  sh2  THEN 
Comp  :=  GreaterThan 
ELSE  IF  si  <  s2  THEN 
Comp  :=  LessThan 
ELSE  IF  si  >  s2  THEN 
Comp  :=  GreaterThan 
ELSE 

Comp  :=  Equal 

END 

ELSE  BEGIN  (not  CaseSen} 

IF  shl  <  sh2  THEN 
Comp  :=  LessThan 
ELSE  IF  shl  >  sh2  THEN 
Comp  :=  GreaterThan 
ELSE 

Comp  :=  Equal 

END 

END; 

The  BNode  function  (line  186)  can  then  be  rewritten  as 

FUNCTION  BNode (VAR  sym  :  SymString)  :  SymTreePtr; 

{  Find  sym' s  node  in  binary  tree,  or  add  it  if  it  doesn't  exist  } 

VAR  Node,  Parent  :  SymTreePtr; 

UCsym  ;  SymString; 
co,  parentco  :  CompType; 

BEGIN 

Node  :=  Head; 

IF  Case_Sensitive  THEN 
UCsym  :=  Upshift (sym) 

ELSE 

UCsym  :=  sym; 

{  Note  that  calls  to  NewNode  have  initialized  all  Node.UCSymbol  } 
co  :=  Compfsym, NodeA. Symbol, UCsym, NodeA. UCsymbol, Case_Sensitive) ; 
WHILE  (Node  <  >  NIL)  AND  (co  <  >  Equal)  DO  BEGIN 
Parent  :=  Node; 

IF  co  =  LessThan  THEN 
Node  NodeA.LLink 
ELSE 

Node  :=  NodeA.RLink; 
parentco  :=  co; 

co  :=  Comp(sym, NodeA. Symbol, UCsym, NodeA. UCsymbol, Case_Sensitive) ; 
END; 

IF  Node  <  >  NIL  THEN  (  Node  exists  for  this  symbol  } 

INC  (Node A. Count) 

ELSE  BEGIN  {  Else  add  new  node  to  binary  tree  } 

Node  :=  NewNode  (sym); 

IF  parentco  =  LessThan  THEN  (  Update  parent's  pointer  } 

Parent A .LLink  :=  Node 
ELSE 

Parent A .RLink  :=  Node 

END; 

BNode  :=  Node; 

END; 


XREF 

Version 

Case 

Sensitivity 

String1 

Compares 

Calls  to 
NewNode 

Calls  to2 
UpShift 

Original 

insensitive 

11,660 

143 

1,462 

Modified 

insensitive 

5,560 

143 

1,462 

Original 

sensitive 

18,921 

296 

443 

Modified 

sensitive 

5,638 

148 

831 

1  "String  Compares  "  is  a  count  of  the  number  of  times  that  symbols  are  compared 
for  for  equality  or  inequality. 

2  The  modifications  made  some  of  the  original  calls  to  Upshift  pointless.  They 
were  removed  from  the  modified  version  and  are  not  included  in  this  table. 


Table  1:  Sample  runs  of  the  original  and  modified  XREF  programs 
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Can  you  write  TSR  t  terminate  and  stay  resident)  pro¬ 
grams  in  Turbo  Pascal'  The  answer  is  yes.  and  this 
two-part  series  shows  how  This  month  1  II  talk 
about  the  basic  requirements  for  TSR  programs  and 
present  the  tools  (see  TSRI  N1T PAS  in  Listing  One. 
page  74 )  to  create  them.  Next  month  I  II  deceit >p  an  example 
program  that  illustrates  installing  the  TSR  program  and  (.hang¬ 
ing  its  hot  keys,  using  files,  and  doing  other  things  that 
real-world  TSR  programs  need  to  do 
||  The  primary  requirement  tor  a  TSR  program  is  for  it  to  be 
‘  invisible'  to  the  operating  system  and  other  software  The 
,  operation  of  such  a  program  can  lx-  separated  into  two 
parts  its  background  mode,  in  which  it  w  aits  to  be  popped 
up  and  its  actu  ated  mode  In  their  background  mode.  TsR 
programs  intercept  one  or  more  interrupt  vectors  and  1110m 
c  tor  their  calls  to  determine  w  hen  to  pop  up  These  intercept 
routines  are  normally  w  ritten  in  assembly  language  in  order 
H  to  be  efficient  and  to  preserve  the  contents  of  the  registers 
11  Being  invisible  in  the  popped-up  mode  means  preserving 
||  the  computer  s  state  when  the*  TSR  program  pops  up.  and 
.  restoring  its  state  when  the  program  pops  hack  down.  The 
1  main  problem  encountered  when  popping  up  a  TSR  pro- 
jj  gram  is  dealing  w  ith  nonreentrant  routines 
8  Because  nonreentrant  routines  cannot  lx*  reentered  safely . 
■  two  general  approaches  are  used  to  eliminate  the  problem 
.  The  simplest  method  is  to  avoid  using  any  of  the  nonreen¬ 
trant  routines  As  many  DOS  !  C)  and  file  functions  are 
f  nonreentrant,  this  approach  would  severely  restrict  the  tasks 
I  that  the  TSR  program  could  perform,  however,  it  does  lend 

jj  Ken  Pottebaum  is  a  professional  mechanical  engineer  for 
■  the  Small  Disk  Division  of  Imprimis,  a  subsidiary  qf  Control 
■  Data  Corporation .  He  can  he  reached  at  121  Redhud. 
jj  Yukon,  OK  7J099. 


itself  to  the  creation  of  small,  spec  tal-purpo.se  TSR  pro¬ 
grams  An  approach  that  allows  more  versatile  TSR  pro¬ 
grams  is  to  avoid  popping  up  the  program  while  a  nonreen¬ 
trant  routine  is  being  executed  — this  is  the  tnethc id  TSR!  'nit 
uses. 

While  waiting  for  their  cue  to  pop  up,  TSR  programs 
normally  monitor  the  keyboard  input  and  then  pop  up 
when  their  hot  keys  are  detected  Either  the  BIOS  hardware 
keyboard  interrupt  09b  or  the-  BIOS  software  keyboard 
interrupt  1 6b  can  lx-  intercepted  and  used  to  monitor  the 
keyboard  input  l  ’sing  interrupt  OOh  provides  the  advantages 
of  quickly  detec  ting  the  hot  keys  and  of  using  key  combina¬ 
tions  that  are  not  normally  recognized  its  quick  response 
to  the  hot  keys  is  because  this  is  the  hardware  interrupt  that 
is  executed  whenever  a  key  is  pressed  or  released,  its 
immediate  response  is  also  a  drawbac  k  because  the  com¬ 
puter  could  be  executing  a  nonreentrant  routine  when  the 
TSR  program's  activ  ation  key  s  are  pressed.  I ’sing  interrupt 
I (>h  reduces  the-  likelihood  of  the  hot  keys  being  detected 
while  an  unsafe  routine  is  being  executed  because  this 
software  interrupt  must  be  called  by  another  routine:  there¬ 
fore  it  cannot  lx-  executed  at  any  time,  as  can  a  hardware 
interrupt  I’nfortunatelv,  it  does  not  completely  prevent  the 
TsR  program  from  being  popped  up  during  unsafe  or  non- 
reentrant  routines  The  disadvantages  of  using  interrupt  16b 
are  that  the  Shift-key  combinations  used  to  make  up  the*  hot 
keys  arc-  reduced  (they  must  lx-  a  combination  that  is  nor¬ 
mally  interpreted  by  the  keyboard  input  routines)  and  that 
the  TSR  program  cannot  be  popped  up  until  the  software 
interrupt  is  c  alled 

Recent  versions  of  BIOS  firmware  contain  a  service  func¬ 
tion.  4Fh.  of  interrupt  15b  that  is  intended  to  be  intercepted 
by  softw  are  programs  This  service  provides  a  clean  way  of 
monitoring  the*  keyboard  inpul  and  modifying  the  input. 


Milking  use  ul  this  feature  would  restrict  the  'I  NK  program 
treated  using  TSRVnit  to  computers  with  the  new  BIOS 
turn  lion,  how  ev  er,  si  i  TSKl  n it  does  n<  it  use  interrupt  /  5 b 

In  order  it >  have  flexibility  in  hot-kev  vombinutu  ins,  quit  k 
detection  of  the  hot  keys,  and  the  safety  provided  by  the 
software  interrupt,  the  method  used  in  TSUI  nit  involves 
both  keyboard  interrupt  vectors. 

Although  tire  specific  maintenance  tasks  required  tor  a 
general-purpose  TSK  program  can  best  be  seen  by  ex¬ 
amining  the  tasks  performed  inside  TSRUnil  the  guidelines 
for  intercepting  interrupt  vectors  are  explained  in  the  tol- 
ii  ivv  ing  sect  it  m 

Intercepting  Interrupt  Vectors 

Routines  to  intercept  interrupt  calls  are  a  vital  part  of  a  TSR 
program.  As  with  TSK  programs,  intercept  routines  must 
preserve  the  contents  ol  the  st.uk  and  the  registers  — 
including  the  Hag  register  Interrupt  routines  are  normally 
called  by  executing  an  hit  instruction,  which  pushes  the 
flags  and  then  a  two-word  return  address  onto  the  stack 
The  instruction  also  clears  the  interrupt  bit  of  the  flags, 
w  hich  disables  further  interrupts 

Although  several  methods  of  emulating  an  interrupt  call 
exist,  the  simple  and  efficient  method  used  in  TSKl  nit  is  to 
push  the  f  lags  i  into  the  stack  and  then  perform  a  far  indirect 
i  all.  t.’.smg  the  indirect  call  allows  the  register  contents  to 
be  intact  when  the  far  call  is  executed  -—the  call  destination 
address  is  contained  at  the  memorv  loc  ation  .specified  in  the 
call  instruction 

With  tire  exception  of  interrupts  25h  and  26b.  all  interrupt 
n  mimes  fcav c  (he  stac  k  clean:  that  is.  they  exit  by  removing 
the  return  address  and  flags  front  the  stack  as  thev  return  to 
(he  c  alling  routine.  The  return  can  be  performed  Ity  execut¬ 
ion  either  an  inter ruivt  return,  /AY  /  01  a  far  return.  Hi'TH  2. 


that  disc  ards  2  bvtes  from  the  stack 


As  prev  iously  mentioned  interrupts  25/?  and  26b 


ibs<  Jute  physical  sector  read  and  write  n  mimes  — are  atypi 


a!.  Thev  leav e  the  old  flags  i  >n  the  stac  k.  and  so  all  routines 


that  call  them  must  dean  up  the  stack  by  discarding  the  old 


flags  after  calling  either  interrupt.  Furthermore,  intercept 


routines  t<  >r  them  must  leav  e  the  <  del  flags  i  >n  the  stack  vv  hen 
they  exit 

Inside  TSRUnif 

TSR l "nit  performs  three  types  of  tasks.  One  routine.  TSkln- 
stall,  installs  the  TSK  program  Once  installed,  the  mainte¬ 
nance  of  the  program  is  performed  b\  I.X1  / A/  code  routines 
in  AXM  and  the  Rascal  routine  Pojil pOtdc  The  remaining 
four  routines  provide  auxiliary  services  for  checking  the 
printer  status  and  tor  ac  c  essing  lines  of  the  saved  text  image 
For  additional  information  on  these  auxiliary  serv  ice  rou¬ 
tines  see  Listing  One 

TSKlustaU  is  a  straightforward  routine  that  provides  the 
TSR  intercept  routines  with  the  information  they  will  re¬ 
quire  Rather  than  storing  all  the  data  in  the  data  segment, 
the  TSR  program  stores  the  information  required  by  the 
I.XIJ.XI Vi  icle  routines  m  the  code  segment  i  lav  ing  their  data 
in  the  c  ode  segment  simplifies  the  I.Xl.l.Xl:  routines  by  allow¬ 
ing  them  to  access  the  data  without  using  an  additional 
segment  register  The  following  items  are  saved  by  the 
installation  routine 

1.  The  complete  pointer  to  the  top  of  the  TSR  program 
stack  (obtained  from  the  current  stack  pointer  and  then 
adjusted  to  its  \  aide  prior  to  the  call  to  1  SRlnstall  ) 

2  The  address  of  thc>  routine  to  lx*  called  from  Pop!  p(.mhj 
3.  Tire  original  interrupt  vectors  for  interrupts  09h,  K>b. 
21b.  25b.  and  26b 
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4.  The  current  video  mode  and  the  size  of  the  cursor 

5.  Whether  or  not  a  math  coprocessor  is  present 

6.  The  size  and  address  of  the  buffer  for  saving  the  screen 
image 

7.  The  Shift-key  combination  code  and  the  scan  code  of 
the  activation  key.  Although  the  command-line  parame¬ 
ters  are  accessed  and  evaluated  to  determine  the  hot 
keys  to  be  used,  this  is  not  critical  to  the  TSR  program. 
The  conversion  of  the  activation  character  to  a  key¬ 
board  scan  is  performed  by  searching  for  the  character 
in  an  array  of  allowed  characters  — the  index  of  the 
array  is  the  scan  code. 

After  saving  the  required  items 
and  displaying  an  installation  mes¬ 
sage,  the  interrupt  vectors  for  the 
five  routines  being  intercepted  are 
replaced.  The  Swap  Vectors  command 
is  used  to  save  Turbo  Pascal’s  inter¬ 
rupt  vectors  and  to  restore  previous 
vectors.  Before  issuing  the  Keep  com¬ 
mand  to  exit  and  stay  resident,  the 
adjacent  flag  bytes,  UnSafe  and  Fig, 
are  cleared  to  enable  the  TSR  pro¬ 
gram  to  be  popped  up.  Because 
their  memory  location  is  coincident 
with  the  first  2  bytes  of  the  ASM 
procedure,  their  default  values  are 
nonzero  and  therefore  prevent  the 
TSR  program  from  popping  up  while 
it  is  being  installed. 

The  critical  part  of  TSRUnit  is  con¬ 
tained  in  the  INLINE  code  of  proce¬ 
dure  ASM.  Although  the  Turbo  Pas¬ 
cal  compiler  sees  ASM  as  one  INTERRUPT  procedure,  it 
actually  contains  five  intercept  routines  and  some  data¬ 
storage  space.  The  standard  entry  and  exit  codes  to  ASM  are 
used  only  as  locations  for  storing  data  — an  additional  block 
of  space  is  also  reserved  for  data  storage  at  the  beginning 
of  the  routine.  For  programming  convenience,  ASM  must 
be  located  at  offset  0  in  TSRUnit.  The  untyped  constants 
preceding  the  procedure  then  provide  the  offsets  to  data 
locations  and  INLINE  code  routines  in  TSRUnit. 

OurIntr21,  the  first  routine  in  ASM,  is  an  intercept  routine 
for  the  DOS  function  interrupt  (interrupt  21h).  The  routine 
checks  whether  the  function  is  to  be  treated  as  nonreentrant 
by  using  the  function  number  as  the  index  to  the  array 
DosTab  — array  values  of  1  indicate  nonreentrant  routines. 
If  it  is  considered  unsafe  to  pop  up  the  TSR  program  while 
the  function  is  being  executed,  the  UnSafe  flag  is  set  and 
then  cleared  upon  returning  from  a  far  call  to  the  intercepted 
routine.  Rather  than  toggling  a  single  bit  to  indicate  safe  and 
unsafe  conditions,  a  byte  value  is  incremented  and  decre¬ 
mented;  this  allows  the  intercept  routine  to  be  reentrant.  If 
the  function  is  considered  safe,  the  registers  are  restored  and 
a  far  jump  to  the  intercepted  routine  is  used  to  exit  from 
OurIntr21. 

The  next  two  routines,  OurIntr25  and  OurIntr26,  inter¬ 
cept  the  DOS  absolute  physical  sector  read  and  write  inter¬ 
rupts  in  order  to  set  the  UnSafe  flag  while  they  are  executed. 
Notice  that  the  two  interrupts  leave  the  old  flags  on  the  stack 
so  the  intercept  routines  discard  the  old  flags  from  the  stack 
after  their  call  to  the  original  interrupts  by  adding  2  to  the 
stack  pointer.  Also,  they  end  with  a  RETF  instruction  that 
leaves  the  old  flags  on  the  stack. 

Although  the  concept  behind  the  intercept  routine  for 
BIOS  09h,  OurIntr9,  is  simple,  its  implementation  is  not  as 
simple  as  that  of  the  previous  intercept  routines.  In  effect, 
the  intercept  routine  checks  for  the  activation  key  combina¬ 


tion  and  sets  the  pop-up  bit  in  the  flag  Fig  when  it  is 
detected  — provided  that  it  or  the  in-use  bits  are  not  already 
set.  All  repeated  hot-key  scan  codes  — obtained  by  holding 
the  hot  key  down  — are  discarded,  as  well  as  the  initial  one 
that  causes  the  pop-up  bit  to  be  set.  The  scan  codes  for 
repeated  presses  of  the  hot  key  while  Fig  is  set  are  not 
discarded. 

The  actual  implementation  of  OurIntr9  involves  checking 
for  multibyte  and  buffer-full  scan  codes,  as  well  as  keeping 
track  of  the  previous  scan  code  in  order  to  discard  repeated 
hot  keys.  All  the  scan  codes,  except  the  hot-key  code  that 
set  the  pop-up  flag  and  all  repeated 
hot-key  codes,  are  passed  on  to  the 
normal  interrupt  09h  routine.  The 
multibyte  scan  codes  are  detected 
by  checking  for  the  scan  codes  OEOh 
and  OFOh\  whenever  one  of  them  is 
detected,  the  flag  Flg9  is  set  and 
then  cleared  after  the  next  byte  is 
obtained.  Because  buffer-full  scan 
codes  can  separate  repeated  hot¬ 
key  codes,  the  buffer-full  scan  codes 
00b  and  OFFh  do  not  cause  Prev  — 
containing  the  previous  scan  code  — 
to  be  updated. 

OurIntrl6,  the  intercept  routine 
for  the  software  keyboard  interrupt, 
essentially  checks  Fig  to  determine 
whether  the  TSR  program  is  to  be 
popped  up  and  whether  any  char¬ 
acters  are  to  be  inserted  into  the 
keyboard  input  steam.  It  then  exe¬ 
cutes  the  appropriate  block  of  code. 
As  with  the  OurIntr9  routine,  its  implementation  is  not 
simple.  The  main  services  provided  by  interrupt  I6h  are  to 
read  a  character  (services  00b  and  10b )  and  to  report 
whether  a  character  is  ready  (services  01b  and  lib).  The 
read-character  services  do  not  return  until  a  character  is 
available.  Because  OurIntr9 discards  the  hot-key  scan  code, 
it  does  not  provide  the  read-character  service  with  a  charac¬ 
ter  to  return.  If  a  read-character  request  is  being  executed 
and  the  hot  key  is  pressed,  OurIntr9  will  set  the  pop-up  flag, 
but  OurIntrl6  will  not  be  able  to  respond  to  it  until  another 
key  is  pressed  — one  that  can  be  returned  by  the  read- 
character  service.  The  solution  to  this  problem  is  to  emulate 
the  read-character  service  with  a  loop  of  report-character- 
ready  requests  and  allow  a  read  request  to  be  performed 
only  when  the  report  function  indicates  that  a  character  is 
ready.  The  loop  contains  separate  checks  for  the  pop-up 
flag  and  the  insert-character  flag.  When  the  pop-up  signal 
is  detected  inside  the  loop,  the  interface  routine  ToPopUp  is 
called  to  allow  the  TSR  program  to  pop  up.  Because  pro¬ 
gram  execution  returns  to  the  read-character  emulation  loop 
when  the  TSR  program  is  popped  back  down,  the  only  two 
ways  out  of  the  loop  are  for  the  insert-character  flag  to  be 
set  or  for  a  character  to  be  reported  ready. 

Inserting  characters  into  the  input  stream  involves  moving 
them  into  the  AL  register,  setting  the  AH  register  to  0  (for  a 
zero  scan  code),  and  exiting  from  the  intercept  routine. 
Naturally,  the  “characters  to  insert”  counter  is  decremented 
and  the  character  pointer  incremented  unless  the  service 
request  is  report  character  ready  instead  of  read  character. 
The  report  service  still  returns  the  character  and  scan  code 
in  AX,  but  the  character  should  not  be  “removed”  from  the 
buffer  and  the  zero  flag  must  be  cleared  to  indicate  that  a 
character  is  ready.  In  order  to  return  the  modified  flags,  the 
old  flags  must  be  discarded  instead  of  restored  from  the 

(continued  on  page  20) 


The  primary 
requirement  for  a  TSR 
program  is  for  it  to  be 
“invisible”  to  the 
operating  system  and 
other  software 
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(continued  from  page  16) 
stack  when  the  routine  is  exited. 

In  order  to  pop  up  the  TSR  program,  OurIntrl6  calls 
ToPopUp,  which  serves  as  an  interface  to  PopUpCode.  If  the 
UnSafe  flag  is  set,  ToPopUp  immediately  returns  to  Our- 
Intrl6.  If  it  is  safe  to  pop  up  the  TSR  program,  it  adjusts  the 
in-use  flag  and  pop-up  flags,  changes  to  the  TSR  program 
stack,  and  emulates  an  interrupt  call  to  PopUpCode.  Upon 
returning  from  PopUpCode ,  it  restores  the  stack  pointers  and 
clears  the  in-use  flag.  Simple  disable-  and  enable-interrupt 
commands  before  and  after  the  stack-changing  commands 
are  required  to  prevent  interrupts  from  occurring  while  the 
stack  pointer  is  being  changed. 

PopUpCode  was  written  as  an  INTERRUPT  routine  so  that 
the  compiler  would  automatically  insert  the  code  to  save  all 
the  registers  and  to  load  the  DS  register  with  the  TSR 
program’s  data  segment.  The  code  generated  also  restores 
the  registers  when  PopUpCode  is  exited.  The  first  and  last 
tasks  performed  in  PopUpCode  are  calls  to  SwapVectors.  The 
first  call  to  SwapVectors  restores  all  of  Turbo  Pascal’s  inter¬ 
rupt  vectors  — these  were  saved  when  the  TSR  program  was 
installed.  The  second  call  restores  the  interrupt  vectors  to 
the  settings  they  had  when  PopUpCode  was  called. 

The  code  between  the  beginning  and  ending  SwapVec¬ 
tors  statements  is  divided  into  three  sections.  The  first  sec¬ 
tion  saves  various  information  about  the  computer’s  current 
state  and,  if  necessary,  changes  the  video  mode  to  the  one 
in  use  when  the  TSR  program  was  installed.  If  the  program 
is  unable  to  save  the  screen  image,  PopUpCode  will  be 
exited  without  popping  up  the  TSR  program.  In  order  to 
keep  the  memory  requirements  down,  PopUpCode  was  writ¬ 
ten  to  handle  only  text  and  CGA  video  modes.  The  code  in 
the  second  section  performs  a  far  call  to  the  function  ad¬ 
dress  obtained  when  the  TSR  program  was  installed  — the 
popping  up  of  the  program  is  completed.  This  section  also 
handles  the  number  of  characters  to  insert  value,  which  is 
returned  from  the  function  call.  The  final  section  restores 
everything  that  may  have  been  changed.  Although  a  Copy 
command  was  used  to  obtain  some  of  the  video  informa¬ 
tion,  all  the  video  information  is  restored  using  BIOS  inter¬ 
rupt  calls. 

For  a  demonstration  program  illustrating  how  to  use 
TSRUnit,  check  the  next  issue  of  DDJ. 

References  Used 

Naturally,  I  used  Borland’s  Turbo  Pascal  Reference  Guide 
for  information  on  Turbo  Pascal.  For  information  on  DOS 
and  BIOS  interrupt  routines,  I  used  The  New  Peter  Norton 
Programmer’s  Guide  to  the  IBM  PC  &  PS/2 ,  published  by 
Microsoft  Press,  1988.  For  additional  information  on  key¬ 
board  modes  and  their  scan  codes,  I  consulted  a  copy  of 
Compaq  DeskPro  386/20  Technical  Reference  Guide. 
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Kermit  Meets 
Modula-2 

The  modularity  of  Modula-2  makes  it  well-suited  for 
communications  projects 


Brian  R.  Anderson 


Kermit  (named  after  the  famous 
frog)  is  a  general-purpose  file 
transfer  protocol  that  was  de¬ 
veloped  at  Columbia  Univer¬ 
sity  in  1981.  What  is  innova¬ 
tive  about  Kermit  is  that  it  makes  mini¬ 
mal  assumptions  about  the  hardware 
upon  which  it  operates.  While  this  in¬ 
novation  allows  Kermit  to  be  used  on 
virtually  any  computer,  Kermit  is  typi¬ 
cally  used  for  communications  between 
microcomputers  and  larger  computers 
(minicomputers  or  mainframes). 

This  article  describes  a  minimal  im¬ 
plementation  of  Kermit  that  uses  Lo¬ 
gitech  Modula-2.  In  order  to  provide  a 
framework  for  my  discussion  of  the 
design  and  implementation  of  the  pro¬ 
gram,  I  will  first  discuss  the  Kermit 
protocol  in  some  detail.  I  will  use  the 
layered  protocol  approach  to  describe 
how  I  employed  a  Yourdon-style  Data 
Flow  Diagram  (DFD)  for  the  overall 
design  of  the  program.  Finally,  I  will 
discuss  how  the  use  of  Modula-2  al¬ 
lowed  me  to  implement  each  layer  of 
the  protocol  as  a  separately  compiled 
module. 

The  Need  For  Data 
Communications  Protocols 

On  the  surface,  the  process  of  data 
communications  appears  to  be  very  sim¬ 
ple:  Data  is  converted  into  a  form  that 
matches  the  transmission  medium  (the 
MODulator  part  of  the  Modem  handles 
this  step);  the  data  is  sent  on  its  way; 


Brian  is  an  instructor  in  the  computer 
systems  technology  department  of  the 
British  Columbia  Institute  of  Technol¬ 
ogy.  He  can  be  reached  at  BCIT, 
Burnaby  Campus,  3700  Willingdon 
Ave.,  Burnaby,  BC  V5G  3H2  Canada. 


and  then  the  data  is  converted  back  to 
the  original  data  at  the  other  end  (this 
step  is  the  task  of  the  DEModulator 
part  of  the  Modem).  Unfortunately,  the 
actual  process  is  seldom  that  easy. 

If  the  transmission  path  used  to  move 
data  were  perfect,  no  communication 
protocol  would  be  necessary  (or  at  least, 
the  protocol  could  be  very  simple), 
and  the  data  could  merely  be  sent  as 
electrical  impulses  from  one  system  to 
another.  All  real  transmissions  paths 
suffer  from  problems  such  as  noise, 
dropout,  and  distortion  (including  phase 
distortion,  frequency  distortion,  and  am¬ 
plitude  distortion).  Despite  the  use  of 
the  best  possible  hardware,  any  of  these 
impairments  can  cause  data  errors  — 
such  that  the  received  message  does 
not  match  the  transmitted  message.  To 
be  effective,  a  file  transfer  protocol  must 
detect  such  errors  and  take  corrective 
action. 

The  receiver  and  the  transmitter  may 


not  have  the  same  timing  requirements. 
If  the  receiver  is  not  ready  for  data 
when  the  transmitter  starts  sending,  in¬ 
formation  will  be  lost.  A  file  transfer 
protocol  must  also  allow  the  receiver 
and  the  transmitter  to  synchronize  so 
that  such  data  loss  does  not  happen. 

The  Kermit  Protocol 

Kermit  is  a  point-to-point  (as  opposed 
to  multipoint)  communications  proto¬ 
col  that  uses  stop-and-wait  Automatic 
Retransmission  reQuest  (ARQ)  for  er¬ 
ror  control.  (XModem,  which  is  widely 
used  for  communications  between  mi¬ 
crocomputers,  is  also  a  point-to-point, 
stop-and-wait  protocol.)  After  sending 
some  data,  Kermit  stops  and  waits  for 
an  acknowledgement  of  the  data  that 
it  just  sent.  If  no  acknowledgement  (or 
a  negative  acknowledgement)  occurs, 
Kermit  resends  any  data  that  had  been 
sent  since  the  last  acknowledgement. 

Kermit  handles  all  communications 
via  packets  (unlike  XModem,  which 
uses  single  characters  for  acknowledge¬ 
ment).  A  packet  is  a  stream  of  bytes 
that  fits  a  particular  pattern.  Figure  1 
shows  a  block  diagram  of  the  Kermit 
packet. 

The  Mark  field  uniquely  identifies 
the  beginning  of  the  Kermit  packet. 
This  field  contains  an  ASCII  start-of- 
header  character,  which  is  the  only  non- 
printable  character  anywhere  in  the 
packet.  (If  nonprintable  characters  are 
encountered  elsewhere,  they  are  con¬ 
verted  into  printable  characters.  This 
process  is  explained  shortly.) 

The  Length  field  contains  a  count  of 
the  number  of  characters  in  the  rest  of 
the  packet;  this  count  ranges  from  3  (to 
indicate  an  empty  data  field)  to  94  (the 
maximum  size  of  a  data  field).  The 
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Sequence  field  indicates  the  packet  se¬ 
quence  number.  The  range  of  sequence 
numbers  is  from  zero  to  63.  (After  63, 
the  sequence  repeats.)  The  Type  field 
identifies  the  type  of  packet.  Packet 
types  include  D(data),  T(yes,  acknowl¬ 
edge),  N  (negative  acknowledge),  S 
(send  initiate),  F  (filename),  Z  (end  of 
file),  E  (error),  and  B  (break  transmis¬ 
sion,  end  of  transmit).  (There  are  other 
packet  types  that  are  not  used  in  this 
implementation;  see  the  references 
given  at  the  end  of  this  article  for  fur¬ 
ther  details.) 

The  Data  field  in  the  Kermit  packet 
contains  just  what  its  name  implies  — 
data.  (Due  to  the  constraint  that  the 
packet  contain  only  printable  charac¬ 
ters,  some  data  must  be  converted  to 
printable  form  and/or  encoded.)  Fi¬ 
nally,  the  Check  field  (which  is  usually 
an  arithmetic  Checksum)  allows  error 
control. 

The  features  of  Kermit  that  allow  this 
protocol  to  be  used  on  nearly  any  com¬ 
puter  system  are  the  small  packet  size 
(96  characters  maximum)  and  Kermit’s 
reliance  upon  printable  characters.  The 
latter  is  necessary  because  many  sys¬ 
tems  interpret  nonprintable  characters 
in  special  ways.  (In  Unix,  for  example, 
Control-D  means  end-of-file;  in  CP/M 
and  MS-DOS,  Control-Z  may  be  used 
for  the  same  function.)  In  addition,  many 
mainframes  can  deal  with  only  7-bit 
characters  — these  mainframes  cannot 
use  the  parity  bit  for  data.  In  order  to 
avoid  the  problems  caused  by  control 
and  binary  characters,  the  designers  of 
Kermit  choose  to  convert  any  suspect 
characters  into  normal  printable  char¬ 
acters.  In  this  context,  suspect  charac¬ 
ters  include  any  control  characters  that 
have  a  binary  1  in  the  eighth  bit. 

Initialization 

Before  transmission  can  begin,  the  re¬ 
ceiver  and  the  transmitter  must  agree 
upon  certain  parameters.  Some  of  these 
parameters  (transmission  rate,  parity, 
and  the  number  of  stop  bits)  must  be 
set  up  in  hardware  before  Kermit  can 
begin.  Other  parameters  are  handled 
via  a  limited  negotiation  that  occurs 
during  transmission  of  the  first  packet. 
The  data  field  of  the  first  packet  con¬ 
tains  several  fields  for  this  purpose. 
This  negotiation  process  is  very  sim¬ 
ple:  If  there  is  no  agreement  about  a 
feature  where  agreement  is  necessary, 
an  automatic  fallback  to  defaults  oc¬ 
curs.  When  agreement  about  a  feature 
is  not  necessary,  each  end  complies 
with  the  other  end’s  wishes. 

Some  of  the  fields  within  the  initiali¬ 
zation  field  may  contain  values  that  do 
not  result  in  printable  ASCII  characters. 
Each  of  these  values  must  be  converted 


by  adding  20H  to  the  value.  This  proc¬ 
ess,  called  “character-izing,”  is  per¬ 
formed  on  the  MAXL,  TIME ,  NPAD, 
and  EOL  fields.  The  TM DC field  is  treated 
differently.  This  field  is  “control-ified,” 
which  means  that  bit  6  is  inverted,  by 
XORing  it  with  01000000B.  Other  fields 
are  sent  as  literal  characters. 

Figure  2  shows  the  contents  of  the 
initialization  packets.  (One  packet  is 
sent  from  each  end.)  During  initializa¬ 
tion,  each  end  initializes  the  other.  (The 
pronouns  “I”  and  “you”  are  often  used 
to  describe  each  end  of  the  communi¬ 
cations  link.)  Table  1  describes  each 
of  the  fields  in  the  initialization  packet. 

File  Transfer 

After  initialization,  the  process  of  file 
transfer  consists  of  sending  or  receiv¬ 
ing  any  number  of  files.  Each  of  these 
files  is  prefixed  with  a  packet  that  con¬ 
tains  the  filename  and  terminates  with 


an  end-of-file  packet.  After  all  files  have 
been  transferred,  an  end-of-transmit 
packet  is  sent. 

While  this  implementation  cannot 
transmit  multiple  files  (each  file  must 
be  transmitted  with  a  separate  Send 
command),  it  can  receive  multiple  files. 

Figures  3  and  4  show  state  diagrams 
for  the  processes  of  receiving  and  send¬ 
ing,  respectively  (adapted  from  refer¬ 
ence  1  in  the  bibliography  following 
this  article).  These  simplified  diagrams 
are  meant  only  to  present  an  overview 
of  the  sequence  of  events  that  occur 
during  file  transfer. 

As  mentioned  earlier,  Kermit  requires 
that  all  data  be  sent  as  printable  charac¬ 
ters.  To  accomplish  this,  and  at  the 
same  time  to  allow  any  type  of  data  to 
be  transmitted,  control  codes  (ASCII 
00H  -  19H  and  7FH  plus  binary  codes 
outside  of  the  range  of  ASCII  80H  - 
(continued  on  page  26) 


Mark  Length  Sequence  Type 


The  Kermit  Packet 


The  first  character  of  the  packet  is  an  ASCII  SOH  (start  of  header);  the  rest  of 
the  packet  must  be  printable  ASCII  characters.  Each  field  of  the  packet 
(except  for  the  data  field)  normally  consists  of  a  single  character;  the  data 
field  may  consist  of  up  to  91  characters  (total  packet  length  is  96).  To  ensure 
the  packet  contains  only  printable  characters,  special  encoding  is  used. 


Figure  1:  A  block  diagram  of  the  Kermit  packet 


MAXL  TIME  NPAD  PADC 


QCTL  QBIN  CHKT  REPT  CAPA  Reserved 


need  not  be  used  in  all  implementations:  REPT 
and  CAPA  are  not  used  in  this  version  of  Kermit; 
the  Reserved  field(s)  are  for  future  expansion  and 
are  not  yet  defined.  See  the  text  for  and 
explanation  of  each  field. 

Figure  2:  Data  portion  of  the  initialization  packet 


FIELD  FUNCTION 


The  maximum  packet  size  that  I  can  accept;  you  will  also  indicate  your 
maximum  packet  length. 

The  maximum  time  (in  seconds)  that  you  should  wait  before  timing  me  out. 
The  number  of  padding  characters  that  you  should  send  ahead  of  each 
packet.  (Default  is  zero.) 

The  padding  character  that  you  should  use. 

The  character  that  you  should  send  to  terminate  each  packet  (usually  none 
or  ASCII  <cr>). 

The  character  that  I  will  use  to  control  the  process  of  character  quoting 
(usually  #)■ 

The  character  that  I  will  use  for  quoting  binary  bytes  (usually  &. 

The  type  of  check  character  used:  1  means  a  one-byte  Checksum,  2  means 
a  two-byte  Checksum ;  and  3  means  a  three-byte  CRC.  This  version  uses 
only  the  one-byte  Checksum. 

The  character  that  I  will  use  for  repeat-count  encoding.  A  blank  (ASCII  <sp>) 
means  that  this  feature  is  not  used  (as  is  the  case  with  this  implementation). 
Advanced  capabilities.  Each  bit  has  a  separate  function,  and  several  bytes 
may  be  linked  together  (bit  zero  is  a  linkage  bit).  These  features  are  not 
used  in  this  implementation. 


Table  1:  Fields  in  the  initialization  packet 
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(continued  from  page  23) 

FFH)  must  be  handled  in  a  special  way. 
To  do  so,  the  data  is  modified  so  that 
it  is  a  printable  character,  and  a  “pre¬ 
fix”  (so-called  “quote”)  character  is  used 
to  advise  the  other  side  that  this  modifi¬ 
cation  has  been  performed. 

Control  characters  are  XORed  with 
01000000B  (which  inverts  bit  6),  and 
then  prefixed  with  #.  For  example,  a 
<cr>  <lf>  sequence  (which  is  Control- 
M  and  Control-J)  becomes  #M#J. 

When  a  character  has  a  binary  1  in 
the  most  significant  bit  position,  this 
bit  is  inverted  and  the  resulting  charac¬ 
ter  is  prefixed  with  &.  For  example, 
1 1 000001 B  is  converted  to  & A. 

In  some  cases,  both  of  these  quoting 
schemes  must  be  used:  1000000 IB  be¬ 
comes  &#A.  The  two  prefix  (quoting) 
characters  can  be  sent  by  prefixing  them 
with  #■.  #  becomes  *#,  while  &  be¬ 
comes  #&.  The  use  of  quoting  schemes 
can  add  considerable  overhead.  The 
control  characters  make  up  26.6  per¬ 
cent  of  the  ASCII  character  set,  while 
bytes  with  the  most  significant  bit  high 
make  up  50  percent  of  random  binary 
files.  In  contrast,  text  files  can  be  trans¬ 
mitted  quite  efficiently  because  they 
contain  few  control  characters  and  no 
nonASCII  characters. 

Layered  Communications  Protocols 

Communications  protocols  are  often 
described  as  having  several  layers  (or 
levels).  Each  of  the  layers  is  responsi¬ 
ble  for  certain  aspects  of  the  steps  in¬ 
volved  in  establishing  and  maintaining 
a  connection,  moving  the  data,  or  en¬ 
suring  data  integrity.  Layered  protocols 
allow  a  standard  to  be  flexible  enough 
to  be  widely  adopted.  The  inherent 


Figure  3:  Kermit  state  transition  dia¬ 
gram  for  receiving 
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modularity  of  layered  protocols  also 
makes  the  process  of  implementing  stan¬ 
dards  easier. 

The  ISO-OSI  Seven-Level  Model 

The  most  notable  layered  protocol  is 
the  International  Standards  Organiza¬ 
tion’s  Open  Systems  Interconnect  Seven- 
Level  Reference  Model,  usually  called 
the  OSI  model.  This  was  meant  to  be  a 
universal  model  for  large-scale  interna¬ 
tional  networks,  although  many  of  the 
principles  also  apply  to  more  limited 
applications  (such  as  Kermit). 

The  diagram  in  Figure  5  compares 
the  OSI  model  with  Kermit.  Because 
Kermit  is  a  simple  point-to-point  proto¬ 
col  where  the  connection  process  is 
under  the  manual  control  of  the  user, 
not  all  of  the  OSI  layers  are  required. 

Software  Design 

By  following  the  data  flow  through  the 
protocol  layers,  design  of  the  program 
becomes  straightforward.  As  mentioned 
at  the  beginning  of  this  article,  I  used 
a  data  flow  diagram  (DFD)  as  an  initial 
design  tool.  The  DFD,  which  is  shown 
as  Figure  6,  provides  a  clear  picture  of 
the  overall  design  of  this  Kermit  im¬ 
plementation. 

When  designing  a  program  in  Modu¬ 
la-2,  an  early  step  (and  the  next  step 
here)  is  to  design  the  main  module  and 
the  definition  modules.  The  main  mod¬ 
ule,  called  the  PCKermit,  calls  the  other 


gram  for  sending 


modules.  Definition  modules  contain 
no  code,  and  describe  the  actions  the 
implementation  modules  will  perform. 
Four  definition  modules  were  designed 
from  the  DFD:  Shell ,  PAD ,  Files,  and 
DataLink.  The  physical  layer  module 
is  provided  by  the  Modula-2  compiler 
that  I  used  (Logitech),  so  some  effort 
was  saved  here.  The  compiler-supplied 
module  that  implements  the  physical 
layer  is  named  RS232Int( for  “interrupt- 
driven  access  to  the  RS-232  serial  port”). 
The  main  module  and  the  definition 
modules  are  shown  as  Listings  One 
through  Five  respectively,  starting  on 
page  83- 

The  definition  modules  closely  match 
the  DFD,  with  the  exception  that  the 
packet  assembler  and  the  packet  disas¬ 
sembler  are  combined  into  a  single 
module,  called  PAD  (for  Packet  Assem¬ 
bler/Disassembler).  Although  many  pro¬ 
cedures  are  hidden  within  the  implemen¬ 
tation  of  PAD,  only  two  are  imported 
and  used  by  the  main  module:  Send 
and  Receive.  The  main  module  imports 
several  procedures  from  Shell,  includ¬ 
ing  dispOpts,  Options,  Dir,  Connect, 
eXit,  and  MainHelp.  The  purpose  of 
many  of  these  procedures  is  obvious 
from  their  names:  dispOpts  and  Op¬ 
tions  refer  to  the  communications  op¬ 
tions  (Baud  rate,  parity,  and  so  forth). 
Connect  provides  terminal  emulation. 

The  Files,  DataLink,  and  RS232Int 
modules  follow  the  layering  concept 
and  are  not  accessed  from  the  main 
module.  These  lower-level  modules  are 
accessed  only  from  within  PAD. 

Although  examination  of  the  main 
module  and  the  definition  modules  re¬ 
veals  few  (if  any)  details  of  the  under¬ 
lying  implementation,  it  does  provide 
a  good  picture  of  the  overall  design  of 
the  program. 

Implementation  Details 

Each  of  the  modules  mentioned  above 
is  divided  into  several  procedures,  and 
each  of  these  procedures  has  one  well- 
defined  purpose  or  task.  Here  are  de¬ 
scriptions  of  a  few  of  the  key  parts  of 
the  code: 

The  Shell  Module 

In  Modula-2,  each  implementation  mod¬ 
ule  can  have  an  initialization  section, 
which  is  also  called  the  “module  body.” 
The  module  body  looks  like  a  main 
part  of  a  program  module.  It  is  exe¬ 
cuted  once,  when  the  program  first 
starts  up,  in  order  to  initialize  the  mod¬ 
ule.  In  the  case  of  the  Shell  module,  the 
module  body  sets  the  initial  conditions 
of  the  communications  hardware  (that 
is,  the  Baud  rate,  parity,  and  so  on). 

The  Shell  implementation  module  (List¬ 
ing  Six,  page  83)  contains  several  local 
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(continued  from  page  26) 
procedures  for  setting  the  Baud  rate, 
parity,  word  length,  and  number  of 
stop  bits  used  by  the  communications 
hardware.  In  Modula-2,  local  proce¬ 
dures  that  are  not  mentioned  in  the 
EXPORT  list  of  the  definition  module 
are  available  only  within  the  module 
in  which  these  procedures  are  defined. 
In  this  case,  these  procedures  are  ac¬ 
cessed  by  the  Options  procedure,  which 
is  exported  and  used  by  the  main  mod¬ 
ule,  PCKermit. 

I  had  a  bit  of  fun  with  the  Dir  proce¬ 
dure  — I  wanted  a  single  command  that 
could  either  display  the  current  direc¬ 
tory,  or  else  change  to  another  subdi¬ 
rectory  and  then  display  the  contents 
of  that  subdirectory.  This  required  some 
minor  parsing  of  user  input  in  order  to 
separate  the  directory  name  from  the 
file  name.  For  example,  if  you  entered 
FOO\*.EXE,  the  Dir  procedure  would 


try  to  switch  to  a  subdirectory  named 
FOO,  and  then  display  all  of  the  .EXE 
files.  Dir  is  smart  enough  to  know  the 
difference  between  FOOV.EXE  and 
\FOOWEXE.  A  useful  enhancement 
would  be  the  ability  to  log  onto  a  dif¬ 
ferent  disk  drive;  this  enhancement 
would  just  require  a  bit  more  parsing. 

The  Connect  command  emulates  a 
glass  teletype  by  scanning  the  keyboard 
for  input  and  the  sending  any  input 
that  it  receives  it  out  to  the  RS-232  serial 
port.  Connect  also  scans  the  RS-232 


serial  input  port,  and  then  sends  any¬ 
thing  that  it  receives  to  the  screen.  Some 
interpretation  is  necessary  in  order  to 
prevent  control  characters  from  print¬ 
ing,  to  allow  for  backspaces,  and  to 
switch  echo  modes  on  and  off.  The 
most  useful  addition  that  could  be  made 
here  would  be  full  terminal  emulation 
(to  make  the  screen  and  keyboard  act 
like  a  common  video  terminal,  such  as 
the  Televideo  950  or  the  DEC  VT100). 

(continued  on  page  32) 


WHILE  <"end  of  transmit"  packet  not  received>  DO 
(*  receive  a  file  *) 

WHILE  <"end  of  file"  packet  not  received>  DO 
(*  receive  a  packet  *) 

END; 

END; 


Example  1:  Pseudocode  for  the  Receive  procedure 
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(continued  from  page  28) 

The  Packet  Assembler/Disassembler 
{PAD)  Module 

Although  the  PAD  module  (Listing 
Seven,  page  86)  contains  over  20  pro¬ 
cedures,  only  two  procedures  ( Send 
and  Receive)  are  exported  for  the  use 
of  other  modules.  The  balance  of  the 
procedures  (some  of  which  are  only  a 
few  line  of  code)  help  the  exported 
procedures  get  the  job  done. 

Several  of  the  procedures  construct 
or  decipher  the  various  control  pack¬ 
ets,  such  as  the  initialization,  response 
(ACK/NAK),  and  error  packets. 

The  Send  procedure  reads  data  from 
a  file  and  uses  that  data  to  construct  a 
packet.  Before  a  character  is  added  to 
a  packet,  the  character  must  be  checked 
to  see  if  it  is  a  control  character  or  if  it 
has  the  most  significant  bit  set.  If  either 
condition  exists,  the  character  is  al¬ 
tered,  and  a  quote  character  (#or  G)  is 
added.  When  the  packet  is  nearly  full, 
the  count,  sequence,  and  type  bytes 
are  added  before  the  packet  is  passed 
on  to  the  DataLink  module. 

The  Receive  procedure  contains  a 
nested  loop.  (Example  1  shows  the 
pseudocode  for  this  loop.)  As  required 
by  the  protocol,  each  successfully  re¬ 
ceived  packet  is  acknowledged  by  a  Y 
packet.  If  no  packet  is  received,  or  if 
the  received  packet  contains  errors,  then 
an  N  packet  is  sent  instead.  After  sev¬ 
eral  errors  in  a  row  ( errors  =  MAXtrys ), 
file  transfer  is  abandoned  and  an  error 
message  is  issued  to  the  user.  If  all 
goes  as  it  should,  each  good  packet  is 
processed  to  remove  both  control-quot¬ 
ing  and  binary-quoting  (e.g.,  #M*J  is 
changed  to  <cr>  <lf>  again,  and  so  on) 
before  the  data  is  stored  to  the  output 
file. 

Two  small  procedures,  Char  and 
UnChar,  are  used  throughout  this  mod¬ 
ule  to  convert  packet  service  bytes  to/ 
from  their  “character-ized”  format.  (This 
is  necessary  to  ensure  that  the  sequence 
and  length  fields  contain  only  print¬ 
able  characters,  and  that  these  charac¬ 
ters  are  later  correctly  interpreted  as 
numbers.) 

The  Files  Module 

The  purpose  of  the  Files  module  (List¬ 
ing  Eight,  page  91)  is  two-fold:  to  pro¬ 
vide  a  “nicer”  interface  to  the  underly¬ 
ing  file  system,  and  to  gain  full  control 
of  disk  buffering. 

Wirth’s  FileSystem  module  uses  a  sin¬ 
gle  procedure,  called  Lookup ,  to  open 
existing  files  or  to  create  new  files.  (A 
Boolean  parameter  determines  which 
action  Lookup  performs.)  I  have  used 
Lookup  to  constru  ct  separate  Open  and 
Create  procedures.  The  Open  proce¬ 
dure  returns  a  Status  Error  if  the  file 
does  not  exist.  If  the  Create  procedure 


determines  that  the  requested  file  al¬ 
ready  exists,  this  procedure  advises  the 
user  and  asks  if  the  file  should  be  over¬ 
written  before  it  continues. 

One  of  the  major  problems  encoun¬ 
tered  when  developing  communications 
programs  is  timing  — specifically,  it  is 
possible  to  miss  incoming  data  if  the 
program  is  doing  something  that  is  time- 


consuming  (such  as  disk  I/O)  at  the 
“wrong”  time.  The  “right”  time  to  out¬ 
put  to  the  disk  is  after  a  packet  has 
been  received,  but  before  the  packet 
has  been  acknowledged.  The  stop-and- 
wait  protocol  then  ensures  that  no  more 
data  is  received  until  after  the  disk  write 


is  complete. 

The  Files  module  writes  to  the  disk 
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A  comparison  of  the  ISO — OSI  Model  and  Kermit.  The  layers  are  each  taken 
care  of  by  a  part  of  the  Kermit  packet  (and  the  associated  software  and/or 
hardware),  the  Application  and  Presentation  layers  are  handled  by  the  TYPE 
and  DATA  fields  (Control  character  quoting  is  and  example  of  a  Presentation 
layer  function);  the  Session  layer  by  the  SEQ  field;  and  the  Datalink  layer  by 
MARK,  LEN,  and  CHECK  fields  (refer  to  figure  1  for  the  Kermit  Packet  layout). 
The  Physical  layer  is  handled  by  the  Serial  Device  Drivers  and  the  RS232 
Hardware.  Since  Kermit  is  a  point-to-point  system,  the  transport  and  Network 
layers  are  not  required;  the  application,  of  course,  is  communications. 


Figure  5:  A  comparison  of  the  LSO-OSL  model  and  Kermit 
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Shell:  User  Interlace,  Help  Menus,  (Dumb)  Terminal  Emulation,  Set  Communications  Parameters 

Files:  Interface  to  OS  mass  storage. 


Packet 

Assembler: 


Takes  stream  of  bytes,  and  converts  to  packet  —  adds  binary  and  control  quoting,  Type  field, 
Sequence  field,  and  Length  field  (although  this  properly  belongs  in  datalink  layer). 


Packet  Takes  packet  and  checks  for  appropriate  Type  and  Sequence,  removes  quoting  to  convert 

Disassembler:  information  to  its  original  form.  Performs  error  control  involving  packet  Type  or  Sequence. 

NOTE:  The  Packet  Assembler  and  Disassembler  are  in  a  single  module  called  PAD. 


Datalink: 


Port: 


Outgoing:  Adds  SOH  and  Checksum  (and  optional  padding  and  end-of-line  characters).  Although 
Length  should  be  added  here,  it  is  more  easily  done  by  Packet  Assembler. 

Incoming:  Strips  SOH,  and  uses  Length  to  find  and  compare  Checksum.  Performs  error  control 
involving  missing  packets,  missing  SOH,  or  garbled  data  (i.e.,  bad  checksum). 

Interface  to  Hardware  (Serial  Port)  —  Provided  by  Standard  Library  Functions.  Allows  fro  status 
checking  on  input,  so  that  system  does  not  wait  indefinitely  if  no  data  coming  in. 


Figure  6:  Kermit  file  transfer  protocol  data  flow 
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in  two  stages.  The  Put  procedure  puts  PAD.  As  always,  it  is  vital  that  the  Re- 


the  character  into  a  buffer.  The  Do- 
Write  procedure  outputs  the  buffer  to 
the  disk  only  if  the  buffer  is  nearly  full 
(that  is,  if  it  is  too  full  to  fit  into  another 
packet).  The  Receive  procedure  in  PAD 
calls  Put  for  each  character  in  the  packet, 
and  then  calls  Do  Write  ax  the  end  of  the 
packet.  (At  first  glance,  you  might  be 
tempted  to  use  a  block  write  command 
to  store  the  entire  packet  that  is  re¬ 
ceived.  This  is  not  possible,  however, 
because  the  packet  contains  a  great 
deal  of  information  that  should  not  be 
stored  to  the  file  — the  service  fields 
[Mark,  Length ,  Sequence ,  Type ,  and 
Check ]  and  the  control/binary  quoting 
characters  must  be  stripped  from  the 
packet  before  it  is  saved.)  Finally,  the 
CloseFile  procedure  must  ensure  that 
the  buffer  is  flushed  to  disk  before 
actually  closing  an  output  file. 

The  DataLink  Module 

The  DataLink  module  (Listing  Nine, 
page  92)  receives  and  transmits  pack¬ 
ets.  The  SendPacket  procedure  accepts 
a  packet  from  PAD  and  writes  the  packet 
to  the  serial  port,  one  character  at  a 
time  (via  the  RS232Int  module).  The 
ReceivePacket  procedure  reads  charac¬ 
ters  from  the  serial  port  (via  RS232Int) 
and  assembles  them  into  packets,  which 
are  then  passed  on  to  PAD.  SendPacket 
is  by  far  the  simpler  of  these  two  proce¬ 
dures  — it  outputs  the  characters  in  a 
loop,  calculates  the  Checksum  as  it 
goes,  and  then  outputs  the  Checksum 
at  the  end.  Very  little  can  go  wrong 
with  SendPacket. 

By  contrast,  the  ReceivePacket  pro¬ 
cedure  has  to  be  able  to  handle  several 
potential  problems:  timeouts  (no  data 
received),  packet  format,  and  Check- 
Sum  errors.  First  of  all,  ReceivePacket 
looks  for  the  Mark  character  (ASCII 
SOH)  until  one  of  the  following  three 
events  occurs:  ReceivePacket  reads  100 
characters  without  finding  SOH,  about 
10  seconds  elapses;  or  SOH  is  read.  If 
SOH  is  not  encountered,  an  error  mes¬ 
sage  is  output  to  the  screen  and  error 
status  is  returned  to  PAD,  which  de¬ 
cides  whether  or  not  to  try  again.  If 
SOH  is  encountered,  ReceivePacket  then 
receives  the  rest  of  the  packet.  Re¬ 
ceivePacket  also  assumes  that  the  next 
byte  is  the  Length  field,  which  is  used 
to  determine  how  many  characters 
should  be  read  before  expecting  the 
Checksum  field.  If  that  byte  is  not  the 
Length  field,  the  Checksum  field  will 
be  wrong,  and  the  error  will  be  recog¬ 
nized.  As  the  characters  are  being  re¬ 
ceived,  a  local  Checksum  is  calculated 
for  comparison  to  the  Checksum  field 
that  is  received  from  the  remote  end. 
If  the  Checksums  do  not  match,  an 
error  is  reported  to  the  screen  and  to 
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ceive  routines  time  out  if  no  data  is 
received. 

Notice  that  although  the  Checksum 
is  a  simple  arithmetic  sum  of  the 
ordinal  value  of  the  characters,  some 
rather  bizarre  calculations  are  performed 
upon  the  sum  before  it  is  used.  These 
calculations  ensure  that  the  resulting 
Checksum  is  a  printable  ASCII  charac¬ 
ter,  and  make  all  of  the  bits  of  the 
original  sum  significant  (so  that  all  of 
the  bits  have  some  effect  upon  the 
Checksum  field). 

Performance 

Kermit  is  most  useful  if  no  other  file 
transfer  method  is  available,  as  is  often 
the  case  when  dissimilar  computers  are 
involved.  Kermit  is  relatively  efficient 
when  transferring  text  files.  When  Ker¬ 
mit  is  used  to  transfer  binary  files,  its 
quoting  schemes  can  add  more  than 
70  percent  redundancy. 

I  have  used  this  implementation  of 
Kermit  to  upload  and  download  files 
to  the  IBM  3083  mainframe  at  the  Brit¬ 
ish  Columbia  Institute  of  Technology. 
This  implementation  has  also  been 
tested  successfully  with  the  Kermit  sec¬ 
tion  of  Procomm,  using  a  direct  link 
(NULL  MODEM)  at  up  to  9600  Baud. 

Portability 

I  have  ported  this  implementation  to 
the  Atari  ST,  and  now  frequently  use 
the  two  Kermits  to  transfer  files  be¬ 
tween  the  ST  and  the  PC.  The  only 
significant  change  in  porting  over  to 
the  ST  involved  writing  an  RS232- 
Int  module  for  the  ST  in  order  to  han¬ 
dle  differences  in  the  interface  to  the 
serial  communications  hardware  on 
the  ST. 

The  process  of  moving  Kermit  to 
other  platforms  should  involve  mini¬ 
mal  effort  if  a  reasonably  complete 
Modula-2  compiler  is  available.  Of 
course,  conversion  to  a  different  lan¬ 
guage  is  also  possible,  although  that 
approach  would  involve  considerably 
more  effort.  Several  C  implementations 
of  Kermit  are  available  on  various  bul¬ 
letin  boards  and  directly  from  Colum¬ 
bia  University. 

Limitations  and  Problems 

This  was  meant  to  be  a  minimal  im¬ 
plementation  of  the  Kermit  protocol, 
so  none  of  the  advanced  features  were 
incorporated.  Anyone  interested  in  add¬ 
ing  these  features  is  referred  to  the 
bibliography  at  the  end  of  this  article. 
(The  Joe  Campbell  book  includes  some 
recent  enhancements  to  the  protocol 
that  are  not  mentioned  in  the  earlier 
Byte  article,  but  the  article  is  more  de¬ 
tailed  and  complete.) 


Conclusion 

When  implementing  a  communications 
protocol,  it  is  vital  to  understand  and 
to  apply  the  concept  of  layering.  Each 
layer  has  in  the  protocol  a  small  num¬ 
ber  of  well-defined  tasks.  If  each  layer 
is  handled  by  an  independent  module, 
the  protocol’s  overall  complexity  is  bro¬ 
ken  down  to  a  manageable  level.  The 
ISO-OSI  Seven-Level  Reference  Model 
provides  a  useful  model,  even  for  sim¬ 
pler  protocols  such  as  Kermit. 

The  most  subtle  problems  that  can 
arise  with  a  communications  protocol 
are  due  to  timing  constraints  — one  end 
will  not  quit  sending  just  because  the 
other  end  is  busy  doing  something  other 
than  receiving.  It  is  important  to  prop¬ 
erly  handle  such  potential  problems  in 
order  to  prevent  data  loss. 

The  Modula-2  programming  language 
proved  to  be  well  able  to  handle  this 
communications  project.  The  design  and 
implementation  were  completed  in 
about  a  week.  Due  to  the  modular  na¬ 
ture  of  the  program,  alterations  and 
enhancements  will  not  be  difficult. 
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Language-Independent 

Dynamic 

Pseudostructures 


Simple  data  conversions  can 
pay  big  dividends 


Bruce  W.  Tonkin 


A  structure  may  be  defined  as  a 
grouping  of  data  items  (char¬ 
acters,  numbers,  pointers,  or 
other  types)  that  can  be  treated 
as  an  entity  by  the  program¬ 
mer.  Structures  (or  the  largely  equiva¬ 
lent  Pascal  records  and  Basic  user- 
defined  types)  are  enormously  useful 
because  they  simplify  and  generalize 
the  underlying  program  logic.  Without 
structures,  programs  that  could  have 
been  written  cleanly  and  elegantly  must 
be  written  with  more  of  a  “brute  force” 
approach. 

Still,  a  structure  is  commonly  limited 
in  one  important  way:  The  structure’s 
components  (and  even  the  order  of 
those  components)  must  be  defined  at 
compile  time,  not  at  run  time.  This 
shortcoming  often  causes  problems. 

Consider,  for  example,  a  general  sort 
program.  The  program  should  be  able 
to  handle  an  arbitrary  number  of  keys, 
to  work  with  all  reasonable  data  types 
of  whatever  lengths,  and  to  sort  files 
far  larger  than  available  memory.  Be¬ 
cause  the  amount  of  available  memory 
is  not  known  in  advance  and  will  vary, 
the  sort  should  use  the  fastest  compari¬ 
son  algorithm(s)  possible  for  the  sake 
of  efficiency. 

If  the  programmer  knew  in  advance 
about  the  order  and  the  types  of  the 
keys  in  the  file  to  be  sorted,  a  structure 
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that  contains  all  of  the  keys  would  be 
easy  to  define.  A  comparison  algorithm 
could  then  be  written  to  take  full  ad¬ 
vantage  of  the  structure,  and  space  could 
be  allocated  for  as  large  an  array  as 
necessary.  When  no  formal  structure 
can  be  defined  in  advance,  that  ap¬ 
proach  is  not  possible. 

In  practice,  most  programmers  allo¬ 
cate  a  block  of  memory  at  run  time 
instead.  That  block  of  memory  will  be 
filled  with  the  data  to  be  sorted  (all  or 
part  of  each  record).  Another  block  of 
memory  may  hold  pointers  to  the  col¬ 
lection  of  keys  for  each  of  the  records. 
Individual  key  values  that  belong  to 
each  record  can  be  accessed  by  a  fixed 
offset  from  that  value. 

In  effect,  the  programmer  gets  the 
effect  of  a  structure,  without  many  of 
its  benefits.  To  see  how  severe  this 
disadvantage  can  become,  consider  the 
pseudocode  for  a  sort  on  K  keys  in 


Example  1.  The  actual  sorting  algo¬ 
rithm  is  not  important,  so  I’ve  kept 
things  as  general  as  possible.  I’ve  as¬ 
sumed  that  two  records  are  compared 
at  some  point,  but  that  the  action  taken 
(swapping  pointers,  moving  memory, 
and  so  on)  does  not  matter. 

For  each  key  that  is  compared,  the 
program  looks  up  the  data  type  and 
then  calls  the  correct  comparison.  The 
comparison  is  passed  either  the  two 
values  or  else  the  pointers  to  those 
values,  and  will  probably  return  an  in¬ 
teger  value  that  will  be  examined  in 
order  to  determine  what  action  should 
be  subsequently  taken.  If  necessary, 
the  process  is  repeated  for  each  key. 

If  the  structure  is  known  in  advance, 
only  a  pointer  to  the  structure  needs 
to  be  passed  to  the  comparison  algo¬ 
rithm  (or  the  comparison  can  be  done 
inline).  The  comparison  does  not  need 
to  look  up  the  type  of  each  key.  Sub¬ 
stantially  fewer  parameters  need  to  be 
passed. 

Suppose  that  there  are  ten  1-byte 
keys  for  two  records,  and  that  all  but 
the  last  key  are  identical.  In  this  case, 
the  general  method  will  require  ten 
type  comparisons,  ten  calls  with  two 
passed  parameters  and  a  return  value, 
and  nine  incremented  key  pointers  to 
compare  each  of  two  records. 

In  this  scenario,  a  specific  solution 
will  pass  two  pointers,  with  one  pointer 
passed  to  each  of  the  two  key  structure 
members.  Assuming  that  each  key  is 
of  a  different  type,  the  ten  type  com¬ 
parisons  can  be  omitted.  If  all  keys  are 
of  the  same  type,  then  nine  calls  (with 
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two  passed  parameters  and  a  return 
value)  can  also  be  omitted.  Further¬ 
more,  if  all  keys  are  either  a  character 
byte  or  an  unsigned  byte,  there  is  no 
need  to  explicitly  increment  any  key 
pointers. 

Although  it  is  not  likely  that  all  keys 
will  be  either  a  character  byte  or  an 
unsigned  byte,  it  is  common  for  two 
or  more  adjacent  keys  to  be  one  of 
these  bytes.  The  resulting  smaller  over¬ 
head  can  offer  a  substantial  advantage, 
since  many  sorts  require  a  large  num- 

Nearly  every  modern 
processor  contains  a  string 
comparison  instruction,  or 
a  small  set  of  instructions 
that  can  perform  a  string 
comparison  at  high  speed 


ber  of  comparisons — and,  therefore, 
a  large  number  of  passed  parameters. 
If  one  or  more  merge  passes  are  re¬ 
quired,  any  advantage  is  further  magni¬ 
fied  because  even  more  comparisons 
will  occur. 

Converting  to  a  Common  Format 

Nearly  every  modern  processor  con¬ 
tains  a  string  comparison  instruction, 
or  at  least  a  small  set  of  instructions 
that  can  perform  a  string  comparison 
at  high  speed.  This  capability  is  an 
obvious  optimization,  and  all  common 
compilers  take  advantage  of  it. 

No  common  CPU-level  instruction 
for  the  comparison  of  floating-point 
numbers,  long  integers,  or  other  spe¬ 
cial  data  types  exists.  Such  comparison 
routines  are  supplied  by  the  compiler 
vendor.  For  some  types  of  data,  the 
routines  can  be  quite  slow. 

To  take  advantage  of  efficient  string 
comparisons,  an  ideal  general-purpose 
sort  might  convert  all  data  into  ASCII 
string  format.  If  that  conversion  can 
be  made  faster  than  the  sum  of  1)  the 
type  comparisons,  2)  the  additional  calls 
to  the  comparison  algorithms  (and  the 
corresponding  stack  usage),  and  3)  the 
time  required  to  increment  the  key  point¬ 
ers  (in  this  example,  x=K+l),  then  the 
sort  will  run  faster. 

Let  me  emphasize  that  I’m  not  talk¬ 
ing  about  converting  floating-point  num¬ 
bers  into  strings  of  digits.  That  would 
waste  memory  and  be  time-consum¬ 
ing.  By  “converting  to  string  format,”  I 


mean  something  much  simpler  — con¬ 
verting  the  various  data  types  into  a 
string  of  characters,  so  that  when  the 
characters  are  sorted  in  ASCII  order, 
the  data  from  which  the  string  was 
derived  is  also  sorted. 

As  an  example  of  the  technique,  con¬ 
sider  a  1 6-bit  signed  integer  stored  on 
an  IBM  PC-type  machine.  In  that  for¬ 
mat,  the  most  significant  byte  is  on  the 
right,  and  the  sign  is  stored  in  the  high- 
order  bit  (on  =  negative  number)  of  that 
byte. 

If  integers  were  stored  with  the  bytes 
reversed  and  with  the  sign  bit  comple¬ 
mented,  then  a  string  comparison  would 
work.  An  ASCII-order  sort  of  the  con¬ 
verted  data  would  create  the  same  rela¬ 
tive  order  as  an  integer  sort. 

There  wouldn’t  be  any  merit  to  the 
conversion  if  the  sort  key  were  a  single 
integer  field,  because  integer  compari¬ 
sons  are  fast.  If  the  sort  were  required 
to  process  several  integer  keys  per  re¬ 
cord,  however,  there  might  well  be  an 
advantage.  The  conversion  would  take 
time,  but  afterwards,  any  comparisons 
would  require  only  two  parameters. 
The  more  comparisons,  keys,  and  dif¬ 
ferent  data  types,  the  stronger  the  in¬ 
centive  to  convert. 

If  the  data  is  converted,  then  the 
original  data  (or  some  kind  of  pointer 
to  the  original  data)  needs  to  be  re¬ 
tained  in  order  to  output  a  sorted  file 
at  the  end.  In  most  cases,  that  step  is 
not  necessary — only  the  original  re¬ 
cord  number  is  needed  in  order  to 
output  an  index  to  the  sorted  records. 
Note,  too,  that  if  the  record  number  is 
converted  and  included  as  the  last  sort 
key,  and  then  unconverted  at  the  end 


of  the  sort,  the  sort  preserves  the  order 
of  the  original  data  where  possible. 
This  can  be  important  when  a  file  is 
read  through  an  index,  because  disk 
head  movement  and  drive  wear  are 
minimized,  and  throughput  is  improved. 
Whether  or  not  this  conversion  is  per¬ 
formed,  the  step  of  appending  the  re¬ 
cord  number  to  each  collection  of  keys 
makes  it  impossible  for  any  records  to 
be  “equal,”  and  makes  the  sort  logic 
even  faster. 

The  Number  of  Comparisons 

In  most  sorts,  all  but  a  few  records  are 
compared  to  another  record  at  least 
twice  (more  if  a  merge  pass  occurs). 
Computational  and  hash-based  sorts 
can  beat  this  process,  but  only  at  the 
price  of  added  complexity  and  addi¬ 
tional  assumptions  about  the  data. 
Often,  there  are  far  more  comparisons: 
A  bubble  sort  of  N  records  makes  N-l 
comparisons  on  the  first  pass  alone, 
and  can  (in  the  worst  case)  make 
N(N-l)/2  comparisons  before  it  fin¬ 
ishes.  That  is  an  average  of  (N-l)/2 
comparisons  per  record! 

A  sort  that  uses  a  binary  search  tech¬ 
nique  makes  approximately  log(N)  com¬ 
parisons  to  insert  the  Nth  record,  log(N- 
1)  comparisons  to  insert  the  N-lst  re¬ 
cord,  and  log(l)  comparisons  to  insert 
the  first  record.  (All  logarithms  in  this 
article  are  to  the  base  2.)  For  files  of 
more  than  eight  records,  sorts  based 
on  a  binary  search  average  more  than 
two  comparisons  per  record.  As  a  rough 
approximation,  a  sort  of  N  records  based 
on  a  binary  search  requires  an  average 
of  log(N)-l  comparisons  per  record. 
For  a  larger  number  of  records  (from 


loop  while  still  records  to  sort 
get  new  record 
set  x=l 

loop  while  x  <=  K 

determine  the  data  type  of  key  x 
call  the  appropriate  comparison 

compare  record  a  to  record  b  on  key  x 
if  record  a  is  less  than  record  b 
return  result  'less  than' 
else  if  record  a  is  greater  than  record  b 
return  result  'greater  than' 
else  return  result  'equal' 
end  if 

if  result  is  'less  than' 

take  action  and  set  x=K+l 
else  if  result  is  'greater  than' 
take  action  and  set  x=K+l 
else  increment  x 
end  if 

end  loop  (compare  keys) 
end  loop  (sort  records) 


Example  1:  Pseudocode  for  a  sort  on  K  keys 


40 


Dr.  Dobb’s Journal,  May  1989 

305 


PSEUDOSTRUCTURES 


about  20  to  at  least  100,000),  a  better 
approximation  is  log(.737N)-l.  Table 
1  lists  an  approximate  number  of  com¬ 
parisons  (computed  by  summing  the 
logs  of  all  values  of  N  to  16  significant 
digits)  and  the  improved  estimate.  List¬ 
ing  One,  page  94,  shows  the  program 
that  was  used  to  generate  the  table. 

If  there  are  N  records,  K  keys  per 
record,  and  all  keys  need  to  be  com¬ 
pared  in  order  to  resolve  matters,  then 
a  very  good  sort  needs  to  make  about 
2KN  individual  key  comparisons.  A  bub¬ 
ble  sort  could  require  about  (N/2)KN 
comparisons.  A  sort  based  on  a  binary 
search  needs  roughly  [log(.737N)-l]KN 
comparisons.  Table  2  may  make  the 


results  easier  to  comprehend. 

An  attempt  to  sort  a  million  records 
with  a  bubble  sort  would  be  a  ridicu¬ 
lous  exercise.  If  each  comparison  took 
100  nanoseconds,  the  sort  would  take 
nearly  two  days,  even  with  no  other 
overhead.  The  binary  search  method 
would  finish  in  about  six  seconds! 

Sort  Overhead 

In  practice  there  is  a  lot  of  overhead. 
The  actual  comparison  involves  mem¬ 
ory  accesses,  register  increment  and 
decrement  operations,  stack  usage,  and 
various  other  instruction  processing. 
The  relative  time  required  to  per¬ 


form  comparisons  of  different  kinds 
varies  by  compiler,  processor,  data  type, 
and  possibly  the  memory  locations  in¬ 
volved  and  the  memory  model  used. 
String  comparisons  are  usually  among 
the  fastest  available  comparisons.  (In- 
teger-to-integer  or  byte-to-byte  com¬ 
parisons  are  normally  the  fastest.)  That 

Without  structures, 
programs  that  could 
have  been  written 
cleanly  and  elegantly 
must  be  written  with 
more  of  a  “brute  force” 
approach 


being  the  case,  it  is  difficult  to  state 
precisely  what  advantage  will  be  gained 
by  converting  raw  data  into  strings. 
The  only  possible  answer  is,  “it  de¬ 
pends.” 

Generally  speaking,  though,  if  a  string 
comparison  is  even  slightly  faster  than 
an  explicit  comparison,  then  there  is  a 
point  after  which  it  becomes  more  effi¬ 
cient  to  convert.  This  point  is  reached 
when  the  number  of  comparisons  vastly 
outweighs  the  number  of  conversions 
necessary  for  any  reasonably  large  file. 

Remember  that  conversion  saves 
some  time  when  comparisons  are  done. 
If  nothing  else,  the  fact  that  fewer  sepa¬ 
rate  calls  are  made,  and  fewer  parame¬ 
ters  are  passed,  makes  the  string  com¬ 
parison  more  efficient.  This  efficiency 
increases  as  more  keys  are  added  — 
this  factor  is  quite  important  for  a  general- 
purpose  sort.  Table  3  shows  a  sort  of 
10,000  records  on  two  keys,  where  the 
key-by-key  sort  calls  a  comparison  pro¬ 
cedure. 

From  this,  it’s  clear  that  a  key-by-key 
sort  suffers  in  performance  unless  a 
relatively  long  time  is  needed  in  order 
to  perform  a  conversion,  few  keys  and 
few  records  exist,  and  the  time  required 
to  do  type  checks  and  procedure  calls 
is  negligible.  As  we  shall  see,  none  of 
these  conditions  are  likely  to  hold. 

Regardless  of  the  amount  of  time 
saved,  the  savings  in  code  complexity 
are  very  real  and  obvious.  Once  the 
data  is  converted  to  string  format,  all 
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Number  of 
Records 

Comparisons 

Per  Record 

Log(.737N)-1 

1 

0 

-1 .4402630 

2 

0.5 

-0.4402636 

3 

0.861654 

0.1446990 

4 

1.146241 

0.5597370 

5 

1.381378 

0.8816650 

6 

1.581976 

1.1446996 

7 

1 .757030 

1.3670914 

8 

1.912401 

1 .5597370 

9 

2.052126 

1.7296623 

10 

2.179106 

1.8816653 

100 

5.247650 

5.2035935 

1000 

8.529398 

8.5255217 

2000 

9.526494 

9.5255217 

3000 

10.110419 

10.110483 

4000 

10.524916 

10.525521 

5000 

10.846511 

10.847449 

6000 

11.109319 

11.110483 

7000 

11.331546 

11.332876 

8000 

11.524065 

11.525521 

9000 

11.693891 

11.695446 

10000 

11.845814 

11.847449 

20000 

12.845441 

12.847449 

30000 

13.430272 

13.432411 

40000 

13.845242 

13.847449 

50000 

14.167128 

14.169377 

6000 

14.430134 

14.432411 

70000 

14.652506 

14.654804 

80000 

14.845136 

14.847449 

90000 

15.015049 

15.017374 

Table  1:  Approximate  number  of  comparisons  per  record  for  a  sort  using  a 
binary  search 


#  Records 

Very  Good  Sort 

Bubble  Sort 

Binary  Sort 

16 

48 

360 

123 

128 

768 

24,384 

2,135 

1,024 

6,144 

1,571,328 

26,296 

16,384 

98,304 

402,628,608 

617,336 

131,072 

786,432 

25,769,607,168 

6,118,339 

1 ,048,576 

6,291,456 

1,649,265,868,800 

58,383,894 

Table  2:  Number  of  comparisons  for  a  complete  sort  (based  on  three  keys  per 
record) 
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Conversions 

20,000 

0 

Comparisons 

118,458 

118,458  to  236,916 

Type  checks 

20,000 

one  per  comparison 

Procedure  calls 

0 

one  per  comparison 

Table  3-  Operations  required  for  a  two-key  sort  of 10, 000  records 


loop  while  still  records  to  sort 
get  new  record 

convert  keys  for  new  record  and  append  record  number 
compare  record  a  to  record  b 
if  record  a  is  less  than  record  b 
do  appropriate  action 
else  do  something  else 
end  if 

end  loop  (sort  records) 


Example  2:  Pseudocode  for  a  sort  that  uses  conversion 


subsequent  comparisons  are  string-to- 
string,  and  are  fast  and  easy  to  opti¬ 
mize.  The  savings  in  complexity  can 
be  even  easier  to  appreciate  if  one  or 
more  of  the  keys  must  be  sorted  in 
descending  order. 

When  a  full  “brute  force”  method  is 
used  to  compare  each  key  individually, 
a  general  sort  must  accommodate  an 
extra  flag  for  each  key.  The  sort  must 
also  invert  the  result  returned  by  the 
affected  comparison  algorithm,  or  else 
supply  a  different  comparison  (dou¬ 
bling  the  number  of  algorithms  and 
lengthening  the  sort  time)  in  order  to 
return  a  correct  result. 

If  the  data  is  converted  to  strings, 
then  a  simple  and  fast  XOR  (with  deci¬ 
mal  255)  can  be  performed  to  invert 
the  bits  in  each  affected  key.  This  step 
allows  the  use  of  a  straight  string  com¬ 
parison  thereafter.  Example  2  illustrates 
some  pseudocode  for  a  sort  that  uses 
conversion. 

The  bare  logic  is  certainly  simpler 
than  the  previous  example,  but  the  sort 
depends  heavily  upon  the  step  of  data 
conversion.  In  order  to  obtain  the  best 
performance,  the  conversion  routines 
should  be  written  in  assembler. 

I’ve  written  a  set  of  such  assembler 
routines  for  Microsoft  data  types.  The 
routines  are  in  Listing  Two,  page  94, 
( CONVINT,  to  convert  integers),  Listing 
Three,  page  94,  ( CONVLONG ,  to  con¬ 
vert  long  integers),  Listing  Four,  page 
94,  ICONVOF,  to  convert  old  floating¬ 
points),  Listing  Five,  page  94,  ( CONVNF. ', 
to  convert  IEEE  floating-points),  and 
Listing  Six,  page  95,  ( INVERT,  to  XOR 
all  bytes  in  a  key  with  ASCII  255  for 


reverse-order  sorts).  Each  of  these  con¬ 
version  routines  alters  the  actual  data 
in  memory.  The  size  of  the  key  data 
does  not  change. 

Though  the  routines  were  written 
for  use  with  Quick  Basic  4.0,  there 
should  be  little  problem  in  altering  them 
for  use  with  other  languages.  A  word 
of  warning:  the  converted  data  may 
contain  ASCII  null  characters,  which 
will  cause  problems  in  the  standard  C 
strcmp  library  routine.  C  programmers 


should  use  a  different  (perhaps  assem¬ 
bler-based)  string  comparison. 

Test  Data  in  Support  of  Conversion 

To  test  the  worth  of  the  conversion 
approach,  I  wrote  a  simple  series  of 
benchmarks  in  Quick  Basic  4.5  and  ran 
the  resulting  stand-alone  .EXE  file  on 
my  Tandy  4000  (80386,  16  MHz,  no 
math  co-processor).  The  benchmark  pro¬ 
gram  (shown  in  Listing  Seven,  page  95) 
is  tedious  but  straightforward:  It  con¬ 
sists  of  a  series  of  timing  loops  for  each 
of  a  number  of  elementary  operations. 
The  time  required  to  perform  a  bare 
loop  was  subtracted  from  each  test. 
The  times  are  presented  in  seconds  per 
100,000  operations,  and  averaged  over 
five  runs.  The  results  are  shown  in 
Table  4. 

From  this  table,  there  seems  to  be 
only  one  case  where  data  should  not 
be  converted:  when  the  key  or  keys  are 
integers  or  long  integers.  As  we  shall 
see,  that’s  not  necessarily  true. 

If  the  sort  ever  includes  any  floating¬ 
point  keys,  then  a  conversion  is  nearly 
mandatory — the  time  required  for  a 
conversion  and  a  string  comparison 
ranges  from  5.11  to  7.06  seconds  per 
100,000  operations,  while  the  time  re¬ 
quired  for  a  floating-point  comparison 
alone  (even  coded  in-line)  can  be  nearly 
eight  times  as  large. 

Some  Examples 

Other  combinations  are  not  so  clear- 
cut,  but  are  more  instructive.  If  an  inte¬ 
ger  comparison  is  not  coded  in-line 


TEST 

RESULTS 

. 

Operation  Test 

Time  (sec.) 

Raw  integer  loop 

0.11 

Integer  conversion 

0.88 

Long  integer  conversion 

1.05 

Old  single  float  conversion 

2.33 

Old  double  float  conversion 

3.01 

IEEE  single  float  conversion 

1.98 

IEEE  double  float  conversion 

3.66 

Invert  8  bytes 

2.27 

Compare  two-byte  strings 

3.00 

Compare  two  integers 

0.34 

Compare  two  four-byte  strings 

3.13 

Compare  two  single  floats 

39.73 

Compare  two  double  floats 

40.78 

Compare  two  8-byte  strings 

3.40 

Compare  two  long  integers 

1.33 

Compare  two  20-byte  strings 

4.22 

Compare  two  20-byte  strings  (best?) 

2.91 

Three-integer-parameter  call* 

2.26 

'Dummy  call  with  three  parameters  passed  and  one 
integer  (constant)  assignment  in  the  subprogram. 

All  string  comparisons  were  for  strings  that  differed 
in  only  the  final  byte,  except  for  the  “20-byte  (best?)’’ 
operation,  where  the  strings  differed  in  the  first  byte. 

Table  4:  Benchmark  results 
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(meaning  that  the  comparison  is  a  pro¬ 
cedure  call),  then  it  takes  at  least  2.60 
seconds  per  100,000  operations  (2.26 
seconds  for  the  procedure  calls).  100,000 
conversions  and  100,000  comparisons 
take  3-88  seconds.  As  a  result,  if  the  key 
is  a  single  integer,  you  might  think  it 
better  not  to  convert.  Again,  though, 
the  sheer  number  of  comparisons  may 
dominate. 

Suppose  that  you  need  to  sort  100,000 
records,  and  you  intend  to  use  a  method 
that  relies  upon  a  binary  search.  If  there 
are  two  integer  keys,  then  you  will 
need  to  perform  200,000  conversions 
and  about  1,516,704  comparisons, 
which  together  will  take  47.26  seconds. 
A  simple  integer  comparison  on  the 
first  key  (not  coded  in-line)  will  take 
at  least  39.43  seconds.  If  the  first  keys 
are  always  identical,  then  a  second  in¬ 
teger  comparison  will  take  another  39.43 
seconds.  If  the  second  comparison  is 
required  only  19.9  percent  of  the  time, 
then  the  two  methods  will  be  equally 
fast.  If  the  second  comparison  is  needed 
more  often,  then  the  conversion  method 
will  save  time. 

These  times  are  quite  conservative. 
For  unconverted  integer  variables,  the 
actual  comparison  operation  would 
never  be  as  simple  as  shown  in  the 
benchmarks  — rather  than  only  one  logi¬ 
cal  operation,  there  could  be  two  (com¬ 
pare  for  less  than,  compare  for  greater 
than,  and  drop  through  for  equality). 
The  number  of  necessary  operations 
depends  upon  the  data.  If  two  logical 
comparisons  are  necessary  for  each  in¬ 
teger  key  (all  data  is  in  exactly  the 
wrong  order  for  the  first  logical  test), 
then  the  simple  comparisons  will  take 
an  additional  5.16  seconds.  This  addi¬ 
tional  time  makes  the  process  of  con¬ 
version  and  string  comparisons  nearly 
equivalent  to  an  integer  comparison, 
even  for  a  single  key.  In  addition,  each 
unconverted  comparison  requires  a  type 
check,  which  is  not  necessary  for  con¬ 
verted  data.  The  type  check  will  take 
at  least  another  5. 16  seconds  (one  logi¬ 
cal  operation  per  comparison),  and  pos¬ 
sibly  make  a  sort  on  a  single  integer 
key  faster  if  the  data  is  converted  into 
string  format  first. 

From  the  results  determined  in  the 
previous  table,  it  seems  that  a  string 
comparison  takes  about  2.9  seconds, 
plus  approximately  .066  seconds  per 
byte  (per  100,000  comparisons).  No  sin¬ 
gle  data  comparison  takes  less  time 
than  the  time  required  per  byte,  whether 
or  not  the  comparison  is  coded  in-line. 
The  greater  the  number  of  bytes  of 
keys,  and  the  more  comparisons  per- 
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formed,  the  more  efficient  a  conver¬ 
sion  to  ASCII  strings  will  be. 

To  see  how  beneficial  conversion 
could  be,  consider  the  case  of  ten  inte¬ 
ger  keys.  Assume  that  the  tenth  key  is 
always  necessary,  and  that  there  are 
100,000  records  to  sort.  I’ll  compare  a 
sort  that  uses  data  conversion  against 
a  sort  that  is  coded  to  use  in-line  com¬ 
parisons,  no  type  checks,  and  two  logi¬ 
cal  integer  comparisons  per  key  (no 
fair  testing  for  key  equality  first).  In 


Regardless  of  the 
amount  of  time 
conversion  saves,  the 
savings  in  code 
complexity  are  very  real 
and  obvious 


other  words,  I’ll  test  a  hard-coded  spe¬ 
cial  sort  written  specifically  for  the  inte¬ 
ger  data  against  a  general  sort  that  uses 
data  conversion. 

The  conversion  sort  requires 
1,000,000  conversions  (time:  8.8  sec¬ 
onds),  1,000,000  type  checks  (time:  3-40 
seconds,  if  the  integer  test  is  first),  and 
about  1,516,704  20-byte  string  compari¬ 
sons  (64.0  seconds)  for  a  total  of  76.20 
seconds.  The  hard-coded  integer  sort 
requires  no  conversions  or  type  checks, 
but  performs  30,334,084  logical  com¬ 
parisons  (two  comparisons  per  key  for 
each  of  the  ten  keys  for  each  record 
comparison)  for  a  total  of  103.1  sec¬ 
onds  — about  62  percent  more  time.  If 
the  integer  sort  had  used  procedure 
calls,  the  sort  time  would  have  been 
increased  by  the  performance  of  an 
additional  15,167,040  procedure  calls 
(one  call  per  key  per  comparison)  to  a 
total  of  445.9  seconds  — nearly  seven 
times  as  long  as  the  time  required  with 
conversion! 

These  results  are  interesting  because 
they  show  that: 

1 .  Sort  times  are  greatly  dominated  by 
the  time  required  to  perform  a  com¬ 
parison; 

2.  Sorts  that  use  data  conversion  can 
be  more  efficient  at  comparison  be¬ 
cause  string  comparisons  are  faster,  byte 
for  byte; 

3.  Sorts  that  do  not  use  conversion 


must  avoid  procedure  calls;  but  if  pro¬ 
cedure  calls  are  avoided,  all  compari¬ 
sons  (at  each  key  level)  must  be  coded 
in-line,  which  greatly  increases  code 
size  and  complexity; 

4.  General-purpose  sorts  that  don’t  use 
conversion  must  determine  the  type  of 
each  key  each  time  that  a  comparison  is 
invoked.  Sorts  that  do  use  conversion 
must  determine  the  type  of  each  key 
only  once,  when  the  data  is  converted. 

Conclusions 

Data  conversion  can  pay  rather  large 
dividends,  especially  for  a  general- 
purpose  sort,  but  also  for  any  other 
program  that  must  compare  data  in  a 
variety  of  formats.  If  procedure  calls 
are  used  to  perform  a  comparison,  any 
algorithm  that  does  not  use  conversion 
might  be  (at  best)  only  slightly  faster 
than  an  algorithm  that  does  use  con¬ 
version.  If  there  are  multiple  compari¬ 
sons  per  record,  as  well  as  procedure 
calls  for  each  comparison,  it  is  virtually 
certain  that  conversion  will  be  faster. 
In  any  case  that  involves  the  compari¬ 
son  of  floating-point  formats,  the  proc¬ 
ess  of  conversion  plus  a  string  com¬ 
parison  will  be  far  faster  than  a  straight 
floating-point  comparison. 

Apparently,  compiler  writers  have 
missed  a  chance  to  optimize  floating¬ 
point  comparisons.  (Borland’s  Turbo 
Basic  floating-point  and  string  compari¬ 
son  times  are  not  especially  different 
from  those  of  Microsoft’s  QuickBasic, 
and  the  long-integer  comparison  times 
are  much  longer).  I  hope  that  future 
Basic  compilers  offer  more  optimiza¬ 
tion,  but  that  won’t  change  the  overall 
value  of  conversions  when  multiple 
keys  are  used  — string  comparison  op¬ 
erations  are  just  too  fast  per  byte. 

Try  extending  these  results  and  con¬ 
version  routines  to  other  languages, 
non-Intel-based  machines,  and  to  other 
data  types.  I’d  be  interested  to  hear 
about  any  cases  where  data  conversion 
does  not  prove  effective  in  a  general  sort. 
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All  source  code  for  articles  in  this  issue 
is  available  on  a  single  disk.  To  order, 
send  $14.95  (Calif,  residents  add  sales 
tax)  to  Dr.  Dobb's  Journal,  501  Gal¬ 
veston  Dr.,  Redwood  City,  CA  94063, 
or  call  800-356-2002  (from  inside  Calif.) 
or  800-533-4372  (from  outside  Calif.). 
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TAWK 

A  Simple  Interpreter 

in  C++ 


The  data-encapsulation  features  of  C++ prove  useful  when 
reading  and  writing  records 


Bruce  Eckel 


Most  microcomputer  data¬ 
base  management  systems 
(DBMSs)  read  and  write  re¬ 
cords  in  a  “comma-separated 
ASCII”  format.  This  is  prob¬ 
ably  an  artifact  from  the  days  when 
Basic  (which  uses  that  format)  was  the 
only  common  tongue  on  microcom¬ 
puters.  Comma-separated  ASCII  files 
are  useful  not  only  because  they  allow 
the  records  from  one  DBMS  to  be 
moved  to  another,  but  also  because 
they  can  be  manipulated  by  using  pro¬ 
gramming  languages. 

While  Basic  automatically  reads  and 
writes  these  records,  other  languages 
must  be  programmed  to  do  so.  In  C++, 
this  tedious  task  can  be  encapsulated 
into  several  classes;  the  user  of  the 
class  doesn’t  need  to  worry  about  the 
details.  In  the  first  part  of  this  article, 
two  classes  are  created.  The  first,  class 
field ,  reads  a  single  quoted  and  comma- 
separated  field  and  makes  an  object 
from  that  field.  The  second,  class  csas- 
cii,  opens  a  comma-separated  ASCII 
file  and  reads  records  (as  arrays  of  field 
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objects)  one  at  a  time,  until  the  file 
ends.  A  simple  application  that  uses 
the  classes  to  search  through  a  data¬ 
base  file  for  a  last  name  is  presented. 

Database  files  must  often  be  manipu¬ 
lated  or  output  in  an  organized  way  as 
a  “report.”  It  becomes  tedious  and 
problematic  to  write  and  compile  code 
for  each  different  report  since  nonpro¬ 
grammers  must  often  design  reports. 
A  common  solution  to  a  problem  such 
as  this  is  the  creation  of  a  “scripting 
language”  specifically  tailored  to  the 
task  at  hand.  The  second  part  of  this 
article  is  the  creation  of  a  simple  lan¬ 
guage  that  outputs  the  records  (to  stan¬ 
dard  output)  in  a  comma-separated  AS¬ 
CII  file  according  to  a  script  in  a  sepa¬ 
rate  file. 

The  program  is  called  TAWK  for  “tiny 
awk,”  since  the  problem  it  solves  is 
vaguely  reminiscent  of  the  “awk”  pattern- 
matching  language  found  on  Unix  (ver¬ 
sions  have  also  been  created  for  DOS). 
It  demonstrates  one  of  the  thornier  prob¬ 
lems  in  computer  science:  parsing  and 
executing  a  programming  language.  The 
data-encapsulation  features  of  C++ 
prove  most  useful  here,  and  a  recursive- 
descent  technique  is  used  to  read  arbi¬ 
trarily  long  fields  and  records. 

The  code  was  developed  and  tested 
on  a  DOS  system.  It  compiles  with 
Zortech  C++  or  the  Glockenspiel/ Ad¬ 
vantage  translator  used  with  Microsoft 
C.  The  programs  should  also  work  on 


Unix,  because  all  library  calls  are  ANSI 
C  and  the  only  class  used  that  is  not 
defined  here  is  the  streams  class  (which 
is  included  with  every  C++  package). 
The  simple  screen-manipulation  com¬ 
mands  (clear  screen,  reverse  video)  as¬ 
sume  an  ANSI  terminal  or  a  PC  with 
ANSI. SYS  loaded. 

Object-Oriented  Terminology 

When  discussing  object-oriented  pro¬ 
gramming,  it  is  helpful  to  review  some 
of  the  terminology.  Object-oriented pro¬ 
gramming  means  “sending  messages 
to  objects.”  In  traditional  languages, 
data  is  declared  and  functions  act  di¬ 
rectly  on  the  data.  In  object-oriented 
programing,  objects  are  created,  mes¬ 
sages  are  sent  to  the  objects,  and  the 
objects  decide  what  to  do  with  the 
message  (in  other  words,  how  to  act 
on  their  internal  data). 

An  object  is  an  entity  with  internal 
state  (data)  and  external  operations, 
called  member  functions  in  C++.  “Send¬ 
ing  a  message”  means  calling  one  of 
these  member  functions. 

An  important  reason  for  organizing 
a  program  into  distinct  objects  is  the 
concept  of  encapsulation.  When  data 
is  encapsulated  in  an  object,  it  is  hid¬ 
den  away  (private)  and  can  only  be 
accessed  by  way  of  a  clearly  defined 
interface.  Only  class  member  functions 
and  friend  functions  may  modify  pri¬ 
vate  data.  Data  encapsulation  can  clar- 
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ify  code  by  combining  data  in  a  single 
package  with  specific  legal  operations 
(member  functions).  Data  encapsula¬ 
tion  is  also  useful  in  preventing  bugs  — 
a  working  class  doesn’t  break  simply 
because  it  is  used  in  a  new  program. 

Virtual  Functions 

Object-oriented  purists  will  notice  this 
program  does  not  use  late  binding  (by 
way  of  C++  virtual  functions)  and  thus 
is  not  object-oriented  in  the  Smalltalk 
sense.  When  a  message  is  sent  to  an 

Database  files  must 
often  be  manipulated 
or  output  in  an 
organized  way  as  a 
“report” 


object  in  Smalltalk,  the  object  always 
decides  what  to  do  with  the  message 
(that  is,  the  specific  function  to  call)  at 
run  time,  so  the  function  address  isn’t 
bound  to  the  function  call  until  the  call 
is  actually  made.  Because  most  compil¬ 
ers  bind  function  calls  during  compila¬ 
tion,  run-time  binding  is  often  called 
late  binding. 

C++  always  performs  binding  at  com¬ 
pile  time,  unless  the  programmer  spe¬ 
cifically  instructs  the  compiler  to  wait 
until  run  time  by  using  the  virtual  key¬ 
word.  This  feature  allows  subclasses 
(all  inherited  from  the  same  base  class) 
to  have  identical  function  calls  that  are 
executed  differently.  A  collection  of  ge¬ 
neric  objects  (all  of  the  same  base  class) 
can  be  maintained  and  all  the  “legal” 
messages  for  the  base  class  may  be 
sent  to  any  of  the  objects  in  that  collec¬ 
tion.  The  object  figures  out  what  to  do 
with  the  message  according  to  what 
specific  subclass  it  is.  This  is  object- 
oriented  programming  in  its  true  sense. 

Most  problems  can  benefit  from  the 
data-encapsulation  features  of  C++.  It 
seems,  however,  that  not  every  prob¬ 
lem  demands  virtual  functions.  The  pro¬ 
ject  presented  here  is  one  of  those  cases. 
For  an  example  of  the  use  of  virtual 
functions,  see  my  article  “Building  Mi- 
croCAD”  in  the  November/December 
1988  issue  of  Micro  Cornucopia  (also 
available  as  part  of  C++  source  code 
library  disk  #1,  available  from  Eisys 
Consulting  for  $15). 


Reading  C++  Code 

If  you  are  a  C  programmer,  here’s  a 
simple  way  to  think  about  C++  while 
you  are  reading  the  code  for  this  arti¬ 
cle:  Objects  look  like  structures,  with 
a  few  bells  and  whistles.  One  bell  is 
that  you  can  hide  some  of  the  structure 
members  — members  are  automatically 
hidden  (private )  unless  you  explicitly 
state  they  are  public.  A  whistle  is  the 
ability  to  include  functions  as  members 
of  the  struct.  Members  of  a  class  (a 
user-defined  type)  are  accessed  just  as 
you  would  access  members  of  a  struct — 
with  a  dot  (or  an  arrow,  if  you  have  a 
pointer  to  an  object).  One  more  whis¬ 
tle  is  that  the  programmer  can  define 
the  way  the  objects  are  initialized  (by 
using  the  constructor)  when  they  come 
into  scope,  and  cleaned  up  (by  using 
the  destructor)  when  they  go  out  of 
scope. 

Example  1  shows  a  tiny  class  to  in¬ 
troduce  you  to  the  basics  of  C++  pro¬ 
gramming.  class  declarations  are  gen¬ 
erally  contained  in  header  files  with 
the  extension  hxx.  Definitions  are  gen¬ 
erally  contained  in  files  with  the  exten¬ 
sion  .cxx.  The  AT&T  Unix  C++  chose 
the  unfortunate  extension  of  .Cfor  defi¬ 
nitions,  and  .h  for  declarations.  This  is 
fine  on  Unix,  which  is  case-sensitive, 
but  causes  problems  while  in  DOS. 
Walter  Bright’s  Zortech  C++  compiler 
originally  used  .cpp.  He  later  modified 
it  to  allow  .cxx,  which  is  the  style  the 


Glockenspiel  translator  (previously  mar¬ 
keted  by  Lifeboat  as  Advantage  C++) 
uses.  I  use  the  .cxx  format  because  it 
works  with  both  products. 

The  Streams  Class 

The  streams  class  used  here  is  an  ex¬ 
tremely  useful  class  developed  by  Bjame 
Stroustrup  (the  inventor  of  the  language) 
to  handle  input/output.  It  defaults  to 
standard  input  and  standard  output  (the 
cin  and  cout  objects,  automatically  de¬ 
fined  when  you  include  the  stream. hxx 
header  file),  but  can  also  be  used  to 
read  and  write  files.  A  buffer  can  even 
be  made  into  a  stream  object,  and  the 
same  operations  can  be  performed  on 
that  object. 

The  most  complete  written  reference 
available  for  the  streams  class  is  chap¬ 
ter  8  of  Stroustrup’s  The  C++  Program¬ 
ming  Language  (Addison-Wesley, 
1986).  This  chapter  is  not  exactly  an 
exhaustive  example  of  streams.  One 
of  the  beauties  of  C++  is  that  you  al¬ 
ways  have  access  to  a  description  (often 
admittedly  terse)  of  the  operations  avail¬ 
able  for  that  particular  class  — the 
header  file.  By  studying  the  header  file, 
you  can  often  get  ideas  for  new  ways 
to  use  an  object.  Zortech  C++  also  has 
library  source  code  available,  which 
includes  valuable  comments  on  the  use 
of  certain  functions  (that’s  how  I  fig¬ 
ured  out  many  features). 

(continued  on  page  55) 


class  tiny  ( 

//  private  stuff  here  (this  is  a  comment) 
int  i; 

public:  //  public  stuff  here: 
print!)  (  //  an  "in-line"  function 
printf("i  =  %d\n",i); 

} 

tiny  (int  j) ;  //  constructors  have  the  class  name 
tinyO  (}  //  destructors  use  a  tilde 
);  //  classes  end  with  a  brace  and  a  semicolon 

tiny: :tiny (int  j)  (  //  non  inline  definition 

i  =  j; 

1 

main()  { 

tiny  A(2);  //  implicit  constructor  call 

//  A.i  =  30;  //  error!  private  member 
A.printO;  //  calling  a  member  function 
//  implicit  destructor  call  at  end  of  scope 


Example  1:  A  C++ class 


#include  <stream.hxx>  //  cout  automatically  defined 
main()  { 

cout  «  "Hello,  world! \n"  <<  "I  am  " 

«  6  <<  "today !\n"; 

} 


Example  2:  The  use  of  streams 
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(continued  from  page  52) 

Output  in  streams  is  accomplished 
with  the  operator  you  know  from  C  as 
left  shift.  C++  allows  you  to  overload 
functions  and  operators  to  give  them 
different  meanings  depending  on  their 
arguments.  When  left  shift  is  used  with 
a  stream  object,  it  means  “put  this  stuff 
out  to  the  stream.”  Example  2  lists  a 
short  program  to  show  the  use  of 
streams.  Notice  how  streams  allow  you 
to  string  together  a  series  of  output 
statements. 

Recursive  Descent 

A  recursive  descent  algorithm  is  useful 
if  you  don’t  know  how  long  or  compli¬ 
cated  a  statement  will  be  when  you 
start  looking  at  it.  In  programming  lan¬ 
guages,  for  example,  recursive  descent 
parsers  are  often  used  in  expression 
evaluation,  because  expressions  can  con¬ 
tain  other  expressions.  In  this  project, 
the  expressions  aren’t  particularly  com¬ 
plicated,  but  we  don’t  know  how  long 
a  string  of  text  is  going  to  be. 

A  central  function  is  used  when  scan¬ 
ning  an  expression  using  recursive  de¬ 
scent.  This  function  munches  along  and 
absorbs  input  until  it  runs  into  a  delim¬ 
iter  that  indicates  a  change  in  the  type 
of  input  (white  space,  for  example,  or 
a  number).  At  this  point,  it  might  call 
another  function  to  eat  the  white  space 
or  to  get  a  string  of  digits  and  turn  it 
into  a  number.  Then,  if  the  expression 
is  finished,  it  will  just  return.  If  the 
expression  isn’t  finished  (and  here’s 
the  tricky  part),  it  calls  itself  (that  is,  it 
recurses).  Every  time  it  encounters  a 
new  expression  within  the  one  it’s  evalu¬ 
ating,  it  recurses  to  evaluate  the  ex¬ 
pression. 

When  solving  more  complex  prob¬ 
lems  (such  as  a  programming  language), 
a  set  of  functions  is  used.  Each  func¬ 
tion  may  call  any  of  the  others  during 
expression  evaluation. 

At  some  point,  the  evaluation  must 
bottom  out.  When  this  happens,  the 
function  performs  some  termination  ac¬ 
tivities  and  then  returns.  As  the  stack 
unwinds  from  all  the  recursive  calls, 
the  tail  end  of  each  function  call  per¬ 
forms  some  operation  to  store  the  in¬ 
formation  it  was  able  to  glean,  and 
then  it  returns.  When  the  function  fi¬ 
nally  completes,  the  expression  has 
been  evaluated. 

Recursive  descent  is  used  in  three 
places  in  this  project.  The  field  class, 
which  creates  an  object  containing  a 
single  quote-delimited  field,  has  a  re¬ 
cursive  function  field:  :getfield(  )  (shown 
in  Listing  Two,  page  98)  to  read  one 
character  at  a  time,  keeping  track  of  the 
number  of  characters  encountered,  un¬ 
til  the  end  of  the  field.  When  the  clos¬ 


TAWK 


ing  quotation  mark  is  encountered,  mem¬ 
ory  is  allocated  for  exactly  the  right 
number  of  characters  and  the  function 
returns.  As  it  unwinds,  characters  are 
placed  in  the  object’s  data  buffer.  Us¬ 
ing  recursive  descent  means  no  restric¬ 
tions  are  imposed  on  the  field  size  (other 
than  stack  space). 

The  token  class  uses  recursive  de¬ 
scent  in  a  more  sophisticated  way.  When 
a  token  object  is  created  by  handing  it 
an  input  stream  (by  way  of  the  con¬ 
structor  function  token: :token(istream 


TAWK  demonstrates 
one  of  the  thornier 
problems  in  computer 
science:  parsing  and 
executing  a 

programming  language 


&  input J),  it  reads  the  input  stream 
until  it  has  scanned  a  complete  token. 
When  the  constructor  completes,  a  new 
token  has  been  created. 

A  token  is  a  group  of  symbols  that 
represent  a  single  concept.  A  C++  com¬ 
piler  uses  a  large  number  of  tokens:  I 
means  begin  a  scope,  for  means  start  a 
for  loop,  foo  means  a  variable.  TAWK 
has  a  much  smaller  number  of  tokens. 
All  tokens  in  TAWK  are  delimited  by 
the  “@”  sign,  which  starts  a  new  com¬ 
mand.  When  is  encountered,  it  is 
pushed  back  onto  the  input  stream  (for 
use  in  the  next  token  object)  and  the 
current  token  is  completed.  The  cen¬ 
tral  recursive-descent  function  for  to¬ 
ken  is  token: :get_token( ),  shown  in  List¬ 
ing  Seven,  page  100. 

The  class  parse_array  builds  an  ar¬ 
ray  of  tokens  by  recursively  calling 
parse_array: :build_array( )  (shown  in 
Listing  Seven).  This  function  makes  a 
new  token,  then  looks  at  the  token  to 
decide  what  to  do  next.  The  two  pro¬ 
grams  (LOOKUP  and  TAWK)  are  built 
from  several  classes.  Each  of  these 
classes  will  be  examined. 

The  Class  Field 

The  declaration  of  the  field  class  is 
shown  in  Listing  One,  page  98,  and  the 
definitions  are  in  Listing  Two.  The  field 
object  doesn’t  control  opening  or  clos¬ 


ing  files.  It  is  simply  handed  an  istream 
from  which  it  takes  its  input.  If  it  finds 
the  end  of  input,  it  just  makes  an  inter¬ 
nal  note  (by  setting  its  end_of_file  flag) 
and  returns.  It’s  up  to  the  caller  to 
check  for  end-of-file  with  the  function 
field:  :eof(  ). 

The  operator«( )  is  overloaded  so 
that  a  field  object  may  be  put  to  a 
stream  output  object.  When  this  oc¬ 
curs,  the  data  field  is  copied  to  the 
output. 

The  field  constructor  field: field 
(istream  &  instream)  initializes  all  the 
variables  to  zero  and  sets  the  member 
istream  *  input  equal  to  instream.  This 
allows  field:  :getfield( )  to  treat  input  as 
a  global  variable  and  to  simply  get  the 
next  character.  The  last  thing  the  con¬ 
structor  does  is  call  the  recursive-de¬ 
scent  function  field: :getfield( ),  which 
recurses  until  it  reaches  the  end  of  the 
field.  When  the  constructor  finishes, 
the  field  is  complete. 

The  function  field: :getfield( )  reads 
a  character  from  the  input  stream.  If  it 
isn’t  an  end-of-file  character,  it  checks 
for  terminators,  which  include  a  comma 
if  not  enclosed  by  quotation  marks  (de¬ 
termined  by  a  special  flag  infield)  or  a 
carriage  return,  which  delimits  the  en¬ 
tire  record.  If  no  terminator  is  found, 
the  function  counts  the  current  charac¬ 
ter  and  calls  itself  to  get  the  next  char¬ 
acter.  If  a  terminator  is  found,  memory 
is  allocated  to  hold  the  string  (using  the 
C++  dynamic-memory  allocation  key¬ 
word  new )  and  the  string  terminator 
\  0  is  inserted.  As  the  function  returns 
from  calling  itself,  each  character  is 
inserted,  from  right  to  left,  into  the 
buffer. 

Memory  is  not  always  allocated  for 
a  field.  The  constructor  for  a  field  ob¬ 
ject  sets  the  data  pointer  to  zero.  If 
memory  is  never  allocated,  the  destruc¬ 
tor  will  delete  a  null  pointer,  which  is 
defined  to  have  no  effect. 

The  Class  csascii 

The  csascii  (for  comma-separated-AS- 
CII)  class  is  shown  in  Listings  Three 
(the  declaration)  and  Four  (the  defini¬ 
tion)  (see  page  98).  The  constructor 
opens  the  input  file,  counts  the  num¬ 
ber  of  fields  in  a  record,  and  closes  the 
file.  It  then  creates  an  array  of  pointers 
to  field  objects,  reopens  the  file  and 
reads  in  the  first  record.  Every  time 
csascii: :next( )  is  called,  a  new  record 
is  read  until  the  end  of  the  file. 

The  operator ( ]( )  is  overloaded  so 
the  individual  fields  may  be  selected 
from  each  record.  This  function  checks 
to  ensure  that  the  index  is  within 
bounds. 

The  method  of  opening  files  should 
be  examined  here.  The  line 
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istream 

infile(new  filebuf>open  (filename, 
input)); 

is  a  succinct  way  to  create  a  buffer  and 
open  a  file.  The  new  filebuf  creates  a 
filebuf  object  (necessary  to  open  a  file 
as  an  istream)  on  the  free  store  and 
returns  a  pointer  to  this  object.  The 
pointer  is  used  to  call  a  member  func¬ 
tion,  filebuf:  :open( ).  The  pointer  is  also 
handed  to  the  constructor  of  istream 
to  create  an  object  called  infile. 

This  is  a  clever  piece  of  code,  and 
nice  for  quick  programming  — I  got  it 
from  the  Glockenspiel/Advantage  man¬ 
ual,  so  I  suspect  it’s  something  John 
Carolan  cooked  up.  Unfortunately,  it 
isn’t  robust  unless  you  know  that  the 
file  exists.  If  the  file  doesn’t  exist  on 
DOS  machines,  the  system  locks  up. 

A  more  robust  way  to  open  the  files 
in  this  program  is  to  replace  the  previ¬ 
ous  code  with  the  code  in  Example  3- 
Notice  that  in  csascii::csascii( ),  the  file 
is  closed  implicitly  by  putting  braces 
around  the  first  clause  in  the  construc¬ 
tor  where  the  fields  are  counted.  When 
the  istream  object  goes  out  of  scope, 
the  file  is  closed.  This  is  the  only  pur¬ 
pose  for  putting  the  braces  there.  Any¬ 
time  you  want  to  control  the  destruc¬ 
tion  of  a  local  variable,  simply  put  it  in 
braces. 

Testing  Fieldt ind  csascii 

Listing  Five,  page  98,  is  a  short  pro¬ 
gram  to  show  the  use  of  class  csascii. 
The  csascii  object  file  is  created  by 
giving  it  the  name  of  the  comma-sepa¬ 
rated  ASCII  file  PPQUICK.ASC.  (See  Ex¬ 
ample  4  for  a  sample  file.)  Then  the 
records  are  read  one  at  a  time  and  field 
0  is  compared  to  the  first  argument  on 
the  command  line  (presumably  the  last 
name  of  the  persons  in  the  database). 
When  a  record  is  found,  it  is  displayed 
on  the  screen  (notice  the  use  of  the 
ANSI  screen-control  codes).  A  flag  called 
found  is  set  to  indicate  at  least  one 
record  is  found.  When  no  more  matches 
occur,  the  program  knows  to  exit  (it  is 


assumed  the  file  has  been  sorted  by  the 
database  manager). 

The  ANSI  C  library  function  strcmp( ) 
has  been  used  here  for  compatibil¬ 
ity.  To  ignore  uppercase  or  lowercase 
in  the  comparisons,  Microsoft  C  pro¬ 
vides  strcmpi( )  and  Zortech  provides 
strcmplC  ). 

Notice  how  easy  it  is  to  use  a  class 
once  it  has  been  created.  One  of  the 
advantages  of  C++  is  the  ease  of  use 
of  library  functions.  (That  is,  when  li¬ 
brary  functions  become  available!) 

TAWK 

Table  1  provides  the  complete  syntax 
for  the  TAWK  language.  You  can  see 
that  each  TAWK  command  consists  of 
an  sign  and  a  single  character  (in 
the  case  of  ©()  and  ©<>,  the  com¬ 
mands  are  @f  and  @<  and  the  )  and  > 
are  used  by  the  function  that  reads  the 
number,  to  find  the  end). 

The  execution  of  a  tawkscript  paral¬ 
lels  the  compilation  or  interpretation 
of  other  programming  languages.  The 
tawkscript  is  parsed  into  arrays  of  to¬ 
kens  when  the  program  starts  up.  An 
execution  routine  steps  through  the  ar¬ 
rays  and  performs  actions  based  on  the 
tokens  to  run  the  tawkscript. 

Listing  Six,  page  100,  is  the  declara¬ 
tion  for  class  token  and  class  parse_ 
array.  Listing  Seven  contains  the  defini¬ 
tions.  Listing  Eight,  page  102,  is  the 
main( )  function  for  TAWK.  In  Listing 
Eight  the  tawkscript  is  parsed  into  three 
different  parse_arrays,  one  each  for 
the  @ preamble ,  ©main,  and  ©conclu¬ 
sion.  These  arrays  are  executed  using 
the  database  file  as  input. 

The  Class  token 

Each  token  must  be  a  particular  type. 
The  kind  of  information  a  token  con¬ 
tains  depends  on  what  type  it  is.  In 
TAWK,  the  possible  token  types  are  as 
follows:  a  field  number  (for  printing 
out  a  field  or  testing  if  a  field  is  empty 
in  an  (/statement),  a  string  (simple  text 
including  nonprintable  characters),  parts 
of  a  conditional  statement  (/  else,  and 


endij),  or  a  phase  change  (which  indi¬ 
cates  a  transition  from  @ preamble  to 
@main  or  @ main  to  @ conclusion ).  Be¬ 
cause  a  phase  change  is  never  exe¬ 
cuted  but  is  simply  used  to  terminate 
the  creation  of  a  parse_array,  it  isn’t  a 
token  in  the  same  sense,  but  some 
form  of  communication  was  necessary 
and  this  seemed  the  cleanest. 

The  different  types  of  tokens  and 
phases  are  enumerated  in  the  tokentype 
and  phase  declarations.  The  phase  in¬ 
formation  is  kept  by  the  main  program, 
but  each  token  contains  a  tokentype 
identifier.  Because  a  token  can  never 
be  a  field  number  and  a  string  at  the 
same  time,  the  data  container  in  a  to¬ 
ken  is  combined  into  an  anonymous 
union  (which  is  like  a  regular  union 
only  it  has  no  name).  The  union  is 
used  to  save  space. 

A  token  also  contains  information 
about  the  level  of  the  if  statement.  Be¬ 
cause  /statements  can  be  nested,  each 
token  that  is  an  if,  else,  or  endif  must 
have  information  about  the  nesting  level. 
If  the  conditional  evaluates  to  false  (that 
is,  the  field  is  empty),  the  interpreter 
must  hunt  through  tokens  in  the 
parse_array  until  it  finds  the  else  state¬ 
ment  at  the  same  level,  and  continue 
executing  statements  from  there. 

While  token; :get_token( )  is  perform¬ 
ing  its  recursive-descent  scanning,  it 
calls  several  other  functions,  which  are 
made  private  because  they  aren’t 
needed  by  the  user,  token: :get_next( ) 
gets  a  character  and  tests  for  end-of-file 
(which  is  an  error  condition,  because 
an  ©end  statement  should  always  ter¬ 
minate  the  tawkfile).  token: :get_value( ) 
is  used  for  the  @( )  and  @<>  state¬ 
ments.  token: :dumpline( )  is  called  for 
comments. 

Listing  Seven  starts  with  a  number 
of  global  variables  that  are  declared 
static.  This  means  they  cannot  be  ac¬ 
cessed  outside  the  file  (this  use  of  the 
static  keyword  is  called  file  static).  When 
the  constructor  is  called,  it  establishes 
the  source  of  input  characters  ( token- 
stream ),  sets  the  length  of  the  string 
(which  has  been  read  so  far)  to  zero, 
and  begins  the  descent  by  calling  to¬ 
ken:  :get_token(  ). 

The  following  are  three  possibilities 
in  token: :get_token( ): 

1.  The  next  character  in  the  input  stream 
is  an  @  and  the  length  is  zero.  This 
means  you  are  at  the  beginning  of  a 
command  and  the  next  character  will 
determine  what  the  command  is.  In 
this  case,  a  large  switch  statement  is 
executed. 

2.  The  next  character  is  an  @  and  the 
length  is  not  zero.  This  means  you  are 
in  the  middle  of  a  string  and  a  com¬ 
mand  is  starting.  In  this  case,  the  @  is 
pushed  back  on  the  input  stream  (for 
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Example  3:  Opening  files 


filebuf  fl; 

if  (fl .open (argv[l] , input)  ==  0)  { 

cout  «  "cannot  open  "  <<  argv[l]  <<  "\n"; 
exit  (1) ; 

} 

istream  infile (&fl); 


Example  4:  A  sample  comma-separated  ASCII  file  PPQUICK.ASC 
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use  by  the  next  token),  space  is  allo¬ 
cated  for  the  string,  and  the  unwinding 
of  the  stack  is  started  with  a  return. 

3.  The  next  character  is  not  an  This 
means  it  must  be  plain  text.  In  this 
case,  token: :get_token( )  calls  itself  to 
get  more  characters. 

The  Class parse_array 

The  class  parse  array  is  a  container 
class,  because  it  is  only  used  to  contain 
objects  of  another  class  (token).  There 
is  no  way  to  know  how  many  tokens 
a  parse_array  will  contain,  so  the  re¬ 
cursive  approach  is  used  again.  The 
constructor  initializes  some  variables 


and  calls  the  recursive  function  parse_ 
array: :build_array(  ),  which  keeps  get¬ 
ting  tokens  and  calling  itself  until  a 
phase  change  or  the  end  of  the  input 
(an  @end  statement).  At  this  point,  it 
allocates  space  to  hold  all  the  tokens 
(which  it  has  been  counting  during  the 
descent)  and  ascends,  storing  a  token 
on  each  function  return. 

The  individual  tokens  in  a  parse_ 
array  can  be  selected  by  using  brack¬ 
ets  (t  ])  because  the  bracket  operator 
has  been  overloaded  in  parse_array: 
: operator. ( ]( ).  Because  token  has  a 
stream  function  defined,  tokens  can 
be  put  directly  to  cout. 


TAWK:  A  Tiny  database  processor,  vaguely  like  AWK 

usage: 

where: 

tawk  tawkfile  csafile 

csafile  contains  comma-separated  ASCII  records.  Each  field  in  a  record  is  contained  in 
quotes,  and  each  record  is  delimited  by  a  newline.  These  are  standard  records  that  can 
be  generated  by  the  Basic  language  and  most  database  management  systems. 

tawkfile  is  a  file  that  contains  formatting  commands.  Each  record  in  the  csafile  is  read  and 
fields  in  the  record  are  printed  out  according  to  the  formatting  commands  in  the  tawkfile. 
Everything  in  the  tawkfile  (characters,  spaces,  newlines)  is  printed  literally  except  for  the 
following: 

@(n) 

Print  field  number  n;  @(3)  prints  field  3  of  the  current 
record.  The  first  field  in  a  record  is  field  0. 

@<n> 

Print  an  ascii  character  number  n;  @<27>  prints  the  es¬ 
cape  character 

@! 

This  line  is  a  comment  until  the  end  of  the  line 

@?nn@: 

(then  statements)  @(else  statements)  <®.  An  if-then- 
else  conditional.  If  field  nn  is  not  empty,  the  then  state¬ 
ments  are  executed,  otherwise  the  else  statements  are 
executed.  A  conditional  must  have  all  three  parts,  but  the 
statements  may  be  empty.  Conditionals  can  be  nested. 

^Preamble  or 

@P  or  @p 

When  a  tawkfile  is  begun,  all  statements  until  @main  are 
considered  to  be  part  of  the  preamble.  The  preamble  is 
only  executed  once,  at  the  beginning  of  the  program.  The 
preamble  must  be  strictly  text;  it  cannot  contain  field  num¬ 
bers  or  conditionals.  The  @preambte  statement  is  optional; 

@preamble  is  assumed  until  @main . 

@main 
or  @M  or  @m 

The  main  section  is  executed  once  for  each  record  in  the 
file.  All  statements  between  @main  and  @con- 
clusion  are  part  of  the  main  section.  @main  may  contain 
field  numbers  and  conditionals.  The  @main  statement  is 
required. 

@ conclusion 
or  @C  or  @c 

The  conclusion  is  executed  after  the  last  record  in  the 
database  file  is  read  and  the  file  is  closed.  The  conclusion, 
like  the  preamble,  may  only  contain  text.  All  other  charac¬ 
ters  on  the  same  line  as  @preamble,  @main,  or  (3>conclu- 
sion  are  ignored.  The  @ conclusion  statement  is  required. 

@end 

This  must  be  at  the  end  of  the  tawkfile 

@@ 

Print  an  @  sign 

Example  tawkfile: 

@!  A  comment,  which  isn’t  printed 

@!  The  @preamble  is  optional,  but  promotes  understanding 
@main 

This  is  field  1 :  @(1) 

This  is  field  10:  @(10) 

@?4@:  @(4)  @Field  4  is  empty  @. 
print  an  escape:  @<27> 

Re-generate  comma-separated  ASCII  record: 

Table  1:  The  TAWK  syntax 
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(continued  from  page  58) 

Executing  a  TAWKscript 

Listing  Eight  shows  the  main( )  func¬ 
tion  for  TAWK.  After  the  command¬ 
line  arguments  are  checked,  the  tawk- 
file  is  opened  and  three  parse_arrays 
are  created:  one  for  the  @preamble, 
one  for  @main,  and  one  for  the  Con¬ 
clusion.  The  second  command-line 
argument  is  used  to  create  a  csascii 
object. 

At  the  beginning  and  end  of  the  script 
execution,  the  preamble  and  conclu¬ 
sion  parse_arrays  are  simply  sent  to 
standard  output  {cout).  Because  they 
can  only  contain  text,  no  other  action 
is  necessary. 

The  central  loop  executes  the  state¬ 
ments  in  the  ®main  phase  for  each 
record  the  csascii  object  reads  from  the 
database  file.  After  a  record  is  read,  the 
type  of  each  token  in  parse_array 
Amain  is  used  in  a  switch  statement  to 
choose  the  proper  action.  Strings  are 
sent  to  cout  and  fieldnumbers  send  the 
selected  field  to  cout. 

In  an  if  statement,  if  the  selected 
field  is  empty  in  the  current  record,  the 
parse_array  index  is  incremented  until 
the  e/setoken  at  the  same  level  is  found. 
If  the  field  is  not  empty,  no  action  is 
taken  (the  following  statements  are  exe¬ 
cuted).  When  an  else  is  encountered, 
it  means  the  t/evaluated  to  true,  so  the 
else  clause  is  skipped  over  until  the 
endif  of  the  same  level  is  found. 

Listing  Nine,  on  page  102,  is  a  make¬ 
file  to  make  all  the  examples  in  this 
project. 

Example  TAWKscripts 

Listings  Ten  and  Eleven  show  exam¬ 
ples  of  tawkscripts.  Listing  Ten,  page 
102,  reformats  a  file  with  six  fields  into 
one  with  five  fields,  combining  the  last 
two  fields.  If  both  of  the  last  two  fields 
are  not  empty,  a  space  is  inserted  be¬ 
tween  them. 

Listing  Eleven,  page  102,  shows  the 
usefulness  of  the  preamble  and  con¬ 
clusion.  It  creates  a  tiny  telephone  list 
(which  I  carry  in  my  wallet)  on  an  HP 
LaserJet  printer.  The  preamble  and  con¬ 
clusion  are  used  to  send  special  con¬ 
trol  codes  to  the  printer.  The  use  of 
nested  if-then-else  statements  is  shown 
here:  If  field  3  exists,  it  is  printed  fol¬ 
lowed  by  a  carriage  return  and  a  test 
to  see  if  field  4  exists,  which  is  printed 
with  a  linefeed  if  it  does  (nothing  hap¬ 
pens  if  it  isn't).  If  field  3  doesn't  exist, 
field  4  is  tested  and  printed  with  a 
linefeed  (otherwise  only  a  linefeed  is 
printed).  When  everything  is  completed 
a  reset  is  sent  to  the  LaserJet. 

If  you  want  a  further  challenge,  try 
adding  a  goto  system  to  TAWK.  You 
will  need  to  create  a  label  command 
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and  a  goto  command,  gotos  can  be 
executed  from  if-then-else  statements. 

Conclusion 

The  main( )  program  for  TAWK  is  ac¬ 
tually  quite  small  for  what  it  does.  Be¬ 
cause  the  details  are  hidden  in  the  csas¬ 
cii  and  parse_array  objects,  you  can 
imagine  creating  a  much  more  sophis¬ 
ticated  program  without  losing  control 
of  the  complexity.  This  is  typical  of 
C++.  Indeed,  it  was  designed  to  allow 
one  programmer  to  handle  the  same 
amount  of  code  that  previously  required 
several  programmers.  The  compiler  sup¬ 
ports  the  creation  of  large  projects  by 
hiding  initialization  and  cleanup,  and 
by  enforcing  the  correct  use  of  user- 
defined  types. 

Availability 

All  source  code  for  articles  in  this  issue 
is  available  on  a  single  disk.  To  order, 
send  $14.95  (Calif,  residents  add  sales 
tax)  to  Dr.  Dobb’s  Journal ,  501  Gal¬ 
veston  Dr.,  Redwood  City,  CA  94063; 
or  call  800-356-2002  (from  inside  Calif.) 
or  800-533-4372  (from  outside  Calif.). 
Please  specify  the  issue  number  and 
format  (MS-DOS,  Macintosh,  Kaypro). 
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QuickDrawing 

with 

XCMDs 

Don’t  let  HyperTalk 
slow  you  down 


Jay  Martin  Anderson 


It’s  no  secret  that  XCMDs  (external 
CoMmanDs)  can  be  used  to  pro¬ 
vide  access  to  the  Macintosh  Tool¬ 
box.  Since  the  introduction  of  Hy¬ 
perCard,  in  fact,  a  variety  of  XCMDs 
that  provide  access  to  dialog  boxes, 
the  standard  Macintosh  file  system,  and 
the  serial  port  have  been  published. 
In  this  article,  I  will  examine  a  few 
examples  of  using  external  commands 
to  provide  access  to  QuickDraw. 

Why  is  access  to  QuickDraw  useful? 
The  process  of  drawing  with  Hyper¬ 
Talk  is  directly  tied  to  the  painting  tools 
that  are  provided  with  HyperCard.  That 
is,  to  draw  a  straight  line,  you  select  the 
line  tool  and  drag  it  from  the  starting 
to  the  ending  point.  To  draw  a  straight 
line  using  one  of  the  available  painting 
patterns,  select  a  brush  tool,  then  a 
pattern,  and  finally  drag  the  brush  tool 
from  the  starting  to  the  ending  point. 
The  drawing  that  has  been  done  ap¬ 
pears  on  the  card  and,  unless  the  stack 
has  been  protected  against  writing,  will 
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be  saved  with  the  card  when  the  stack 
is  closed. 

It  is  clear  (even  to  a  casual  observer) 
that  something  happens  in  HyperCard 
when  you  select  any  of  the  painting 
tools.  There  is  a  noticeable  pause,  the 
cursor  turns  into  the  watch,  and  the 
menu  bar  (if  visible)  expands  to  in¬ 
clude  the  paint  and  options  menus.  A 
similar  transition  takes  place  in  reverse 
when  you  abandon  the  painting  tools 
for  the  browse  tool.  In  addition  to  the 
time  penalty  that  you  pay  when  you 
select  a  painting  tool  and  then  aban¬ 
don  it,  the  appearance  of  the  card  or 
stack  also  suffers.  While  the  painting 
tools  are  being  selected,  the  cursor  flick¬ 
ers  and  bounces  from  browse  to  brush 
and  back;  the  menubar  extends  to  re¬ 
veal  two  additional  menus  and  then 
contracts  when  the  painting  tools  have 
been  abandoned.  Although  this  activ¬ 
ity  is  necessary  and  helpful  when  you 
are  doing  the  painting,  it  is  unattractive 
and  distracting  when  you  only  expect 
to  watch  a  drawing  appear. 

If  you  could  avoid  using  the  painting 
tools  and  make  calls  to  QuickDraw 
directly,  you  could  avoid  both  the  time 
penalty  in  loading  and  unloading  the 
painting  tools,  and  the  aesthetic  pen¬ 
alty  you  experience  while  the  cursor 
and  menubar  flicker  and  jump. 

Access  to  QuickDraw  can  also  be 
dangerous.  QuickDraw  operations  take 
place  on  the  screen,  not  on  the  card  in 


a  HyperCard  stack.  The  person  using 
a  stack  may  not  be  able  to  distinguish 
between  a  display  drawn  with  Quick¬ 
Draw  routines  and  a  display  drawn 
with  HyperTalk  painting  tools;  but  the 
drawing  made  with  the  painting  tools 
is  (in  principle)  savable  on  the  card  in 
the  stack,  whereas  the  drawing  made 
with  QuickDraw  routines  is  not.  Fur¬ 
thermore,  mixing  QuickDraw  routines 
with  painting  tools  can  lead  to  unde¬ 
sired  results.  Loading  the  painting  tools, 
for  example,  refreshes  the  display  so 
that  only  the  card  contents  are  visible; 
any  drawing  made  on  the  screen  with 
QuickDraw  routines  will  disappear.  Fi¬ 
nally,  the  user  of  QuickDraw  must  be 
careful  to  confine  the  drawing  to  the 
active  window  on  the  screen,  whose 
dimension  is  the  same  as  the  Hyper¬ 
Card  card.  The  user  of  QuickDraw  can¬ 
not  draw  on  the  card  and  cannot  draw 
outside  the  region  bounded  by  the  card. 

In  a  HyperCard  tutorial,  designed  to 
demonstrate  and  teach  the  features  of 
Graphic  Session  (a  commercial  termi¬ 
nal  emulator),  I  needed  to  draw  a  gray 
cross  hair  on  the  display.  When  the 
mouse  was  clicked,  I  needed  to  erase 
the  first  gray  cross  hair  and  to  draw 
another  gray  cross  hair  at  the  mouse 
position.  Using  HyperTalk  and  paint¬ 
ing  tools  led  me  to  the  two  scripts 
shown  in  Listing  One  (page  104). 

Although  these  scripts  serve  to  pro¬ 
vide  the  necessary  functionality,  they 


Dr.  Dobb’s  Journal,  May  1989 


63 

315 


(continued  from  page  63) 
are  slow  to  execute  and  distracting  to 
watch.  Furthermore,  this  is  just  the  situ¬ 
ation  where  drawing  on  the  screen  and 
not  on  the  card  is  useful:  I  do  not  want 
cross  hairs  left  behind  on  the  card  after 
clicking.  The  user  is  supposed  to  prac¬ 
tice  clicking,  thereby  moving  the  cross 
hair;  the  user  is  not  supposed  to  alter 
the  tutorial  stack.  Consequently,  I  ap¬ 
pealed  to  QuickDraw  directly  and  de¬ 
veloped  two  brief  XCMDs  — for  pen 
movement  with  and  without  drawing. 

If  you  could  make 
calls  to  QuickDraw 
directly,  you  could 
avoid  both  the  time 
penalty  and  the 
aesthetic  penalty 


The  XCMD  that  performs  pen  move¬ 
ment  without  drawing  is  called 
XMoveTo,  and  it  is  a  simple  “cover”  for 
the  QuickDraw  routine  MoveTo.  The 
XCMD  that  performs  pen  movement 
with  drawing  is  called  XLineTo-,  be¬ 
sides  serving  as  a  “cover”  for  the  Quick¬ 
Draw  routine  LineTo,  XLineTo  also  in¬ 
cludes  the  ability  to  change  the  pen 
pattern  and  drawing  mode.  Therefore, 
XLineTo  can  both  draw  and  erase.  The 
syntax  of  these  two  XCMDs  is  shown 
in  Listing  Two  (page  104).  The  new 
HyperTalk  scripts  for  drawing  the  in¬ 
itial  cross  hair  and  erasing  and  redraw¬ 
ing  the  cross  hair  on  a  mouse  click  are 
shown  in  Listing  Three  (page  104). 

These  scripts  are  no  more  complex 
than  the  script  using  the  painting  tools; 
the  drawing  takes  place  faster  with  the 
XCMD  script  than  with  the  tools  script, 
and  there  is  no  distracting  change  to 
the  cursor  or  menu  bar  while  the  draw¬ 
ing  takes  place. 

The  two  XCMDs  were  developed  us¬ 
ing  Think  Technology’s  Lightspeed  C 
(Version  3.0).  The  C  source  code  for 
XMoveTo  is  shown  in  Listing  Four  (on 
page  104). 

The  source  code  for  XLineTo ,  shown 
in  Listing  Five  (page  104),  is  slightly 
more  complex;  it  permits  a  variable 
number  of  parameters  (two  are  required, 
the  third  and  fourth  are  optional)  and 
it  must  select  a  QuickDraw  pen  pattern 
and  pen  drawing  mode. 

There  are  four  steps  to  making  a 


HyperTalk  script  using  an  XCMD,  which 
is  written  in  Lightspeed  C.  Two  of  these 
steps  are  handled  within  Lightspeed  C 
itself. 

1.  To  construct  a  Lightspeed  “project,” 
load  the  appropriate  Macintosh  librar¬ 
ies,  following  the  guidelines  in  the  Light¬ 
speed  C  manual.  Then  create  and  edit 
the  source  code  file.  Finally,  build  or 
make  the  project  within  Lightspeed  C. 

2.  Next,  use  Lightspeed  C  to  con¬ 
struct  an  XCMD  instead  of  an  applica¬ 
tion.  The  XCMD  is  left  — as  a  pure  code 
resource  — in  a  file. 

3.  The  third  step  in  constructing  the 
HyperTalk  script  using  an  XCMD  re¬ 
quires  a  resource  editor,  such  as  Res- 
Edit.  By  using  ResEdit,  you  can  move 
the  XCMD  resource,  such  as  XMoveTo , 
from  the  file  in  which  Lightspeed  C 
leaves  it  into  a  HyperCard  stack.  These 
steps  are  repeated  in  order  to  create 
and  embed  each  XCMD  in  the  same 
stack.  The  XCMD’s  XLineTo  and 
XMoveTo  are  now  available  anywhere 
within  the  stack,  but  in  no  other  stack. 
If  I  wanted  the  XCMDs  to  be  available 
to  other  stacks  as  well,  I  could  have 
embedded  them  in  the  home  stack  or 
in  HyperCard  itself. 

4.  The  fourth  step  is  to  write  Hyper¬ 
Talk  scripts,  as  shown  earlier,  to  use 
these  XCMDs  in  order  to  achieve  faster, 
less  detracting  drawing. 

On  a  Macintosh  with  sufficiently  large 
memory  (probably  2.5  Mbytes  or  larger), 
you  can  run  HyperCard,  Lightspeed  C, 
and  ResEdit  all  under  MultiFinder,  and 
quickly  bounce  from  editing  and  com¬ 
piling  to  managing  resources  to  con¬ 
structing  HyperTalk  scripts.  On  a  smaller 
Macintosh,  or  without  the  use  of  Multi- 
Finder,  you  will  have  to  perform  these 
steps  separately  by  quitting  each  appli¬ 
cation  before  starting  another. 

The  same  procedures  that  have  been 
discussed  here  for  using  QuickDraw 
LineTo  and  MoveTo  procedures  from  a 
HyperCard  stack  can  be  applied  to  other 
QuickDraw  procedures  as  well.  Al¬ 
though  it  did  not  come  up  in  the  design 
of  the  Graphic  Session  tutorial,  I  might 
equally  well  have  wanted  to  demon¬ 
strate  the  positioning  of  a  conventional 
box-like  alpha  cursor  by  a  mouse  click. 
In  this  situation,  instead  of  drawing  a 
gray  cross  hair  at  the  location  of  the 
mouse  click,  I  would  draw  a  small  black 
rectangle  at  the  location  of  the  mouse 
click.  This  leads  naturally  to  the  devel¬ 
opment  of  an  XCMD,  called  XBox, 
which  covers  the  QuickDraw  proce¬ 
dure  PaintRect,  as  shown  in  Listing  Six 
(page  106). 

Finally,  some  amusing  effects  can 
be  achieved  by  combining  QuickDraw 
operations  on  the  screen  with  the  paint¬ 
ing  of  similar  objects  on  the  card.  For 


example,  the  small  rectangle  painted 
with  the  XCMD  XBox  can  be  repeated 
often,  leading  to  the  effect  of  anima¬ 
tion.  This  animated  rectangle  can  then 
appear  to  come  to  rest  in  the  form  of  a 
rectangle  that  is  actually  painted  on  a 
card.  The  script  in  Listing  Seven  (page 
106)  illustrates  this  action:  for  this  exam¬ 
ple,  the  animated  rectangle  painted  by 
the  XCMD  XBox  appears  on  the  screen 
in  front  of  a  blank  card;  after  the  ani¬ 
mation  sequence  is  finished,  a  card 
with  a  painted  rectangle  is  brought  into 
view. 

The  use  of  XCMDs  for 
access  to  QuickDraw 
allows  you  access  to 
faster  drawing 


The  construction  of  XCMDs  that  cover 
QuickDraw  procedures  can  be  accom¬ 
plished  easily  within  either  C  or  Pascal, 
and  can  be  done  largely  by  rote.  The 
use  of  XCMDs  for  access  to  QuickDraw 
allows  you  access  to  faster,  but  tran¬ 
sient  drawing. 

Notes 

1.  Graphic  Session,  software  for  the 
Macintosh  that  emulates  an  Hewlett- 
Packard  HP  2393A  monochrome  graph¬ 
ics  terminal,  is  available  from  Tymlabs 
Corp.,  811  Barton  Springs  Rd.,  Austin, 
TX  78704;  512-478-0611;  the  HyperCard 
tutorial  for  this  product  is  available  from 
the  author,  or  for  downloading  on  GE- 
nie  and  CompuServe. 

2.  Version  3  0  of  THINK  C  (Symantec 
Corp.,  10201  Torre  Ave.,  Cupertino,  CA 
95014;  408-253-9600)  is  MultiFinder  com¬ 
patible.  Its  predecessor,  Lightspeed  C 
Version  2. Ox,  was  not. 

3.  For  well-worked  examples  in  Light¬ 
speed  C,  see  Gary  Bond,  XCMDs  for 
HyperCard  (MIS  Press,  1988). 

Availability 

All  source  code  for  articles  in  this  issue 
is  available  on  a  single  disk.  To  order, 
send  $14.95  (Calif,  residents  add  sales 
tax)  to  Dr.  Dobb’s  Journal,  501  Galves¬ 
ton  Dr.,  Redwood  City,  CA  94063;  or 
call  800-356-2002  (fron  inside  Calif.) 
or  800-533-4372  (from  outside  Calif.). 
Please  specify  the  issue  number  and 
format  (MS-DOS,  Macintosh,  Kaypro). 
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The  competition  goes  on. . . 


Scott  Robert  Ladd 


Product  Information 

Turbo  C  — Borland  International 
1800  Green  Hills  Rd. 

Scotts  Valley,  CA  95066-0001 
408-438-8400 

QuickC  — Microsoft  Corp. 

Box  97017 

Redmond,  WA  98073-9717 
206-882-8080 


In  the  world  of  software,  the  war 
for  market  share  goes  on  and  on. 
At  the  forefront  of  this  conflict  are 
two  titans,  Microsoft  and  Borland. 
It  is  inarguable  that  these  two  in¬ 
dustry  giants  influence  the  type  and 
quality  of  products  available  both  now 
and  in  the  future.  In  particular,  their 
language  products  are  among  the  first 
in  line  when  companies  and  individu¬ 
als  consider  which  products  to  buy. 

This  article  reviews  and  compares 
Borland’s  Turbo  C  and  Microsoft’s 
QuickC  compilers.  Due  to  their  low 
prices  and  the  name  recognition  of  their 
vendors,  Turbo  C  and  QuickC  (or  TC 
and  QC)  are  often  the  C  compilers  cho¬ 
sen  by  people  who  are  just  learning  the 
C  language.  One  of  the  most  popular 
questions  raised  in  user  groups  and 
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electronic  forums  is,  “Which  one  is 
best?”  That’s  not  an  easy  question  to 
answer. 

Part  of  the  problem  is  that,  although 
similar  in  many  ways,  TC  and  QC  are 
aimed  at  different  programmer  audi¬ 
ences.  Microsoft  targets  QC  chiefly  at 
newcomers  and  casual  users.  Experi¬ 
ence  with  Version  1 .0  apparently  con¬ 
vinced  Microsoft  that  these  are  the  buy¬ 
ers  for  QC,  and  so  Version  2.0  is  tai¬ 
lored  to  their  needs,  with  Microsoft  C 
5.1  for  professionals.  Meanwhile, 
Borland’s  TC  competes  with  both  Mi¬ 
crosoft  C  offerings,  thus  aiming  higher. 
This  introduces  some  subtle,  but  tell¬ 
ing  differences. 

And  precisely  because  TC  goes  after 
the  spectrum  of  Microsoft  C  products, 
we’re  going  to  compare  it  with  both  in 
a  two-part  review:  this  month  with  QC, 
in  August  with  Microsoft  C.  That  month’s 
installment  will  include  benchmark  re¬ 
sults  for  all  three. 

TC  and  QC  are  very  similar  in  scope 
and  appearance.  TC  costs  $150,  while 
QC  costs  $99.  In  the  basic  package, 
each  product  has  an  integrated  envi¬ 
ronment  that  includes  an  editor,  a  com¬ 
piler,  a  linker,  a  debugger,  and  Make 
facilities.  Command-line  utilities  are  also 
provided  for  programmers  who  dislike 
environments.  TC  and  QC  are  fast  prod¬ 
ucts  — both  compile  tens  of  thousands 
of  lines  of  source  code  per  minute  on 
an  80286-based  PC.  Documentation  for 
both  products  consists  of  paperback 
manuals.  With  all  of  these  similarities, 


it  might  appear  difficult  to  find  true 
qualitative  differences  between  the  two 
products.  Appearances,  however,  can 
be  deceiving.  .  .  . 

Installation 

Both  TC  and  QC  offer  automated  in¬ 
stallation  programs.  TC’s  automated  in¬ 
stallation  program  is  a  bit  “prettier,” 
with  fancy  pop-up  windows  and  back¬ 
ground  shading.  QC’s  installation  is 
more  austere,  but  equally  adequate. 

It  is  possible  to  make  TC  and  QC 
work  in  a  diskette-only  environment  — 
but  I  strongly  recommend  against  do¬ 
ing  so.  The  installation  programs  set 
the  compilers  up  on  multiple  diskettes, 
and  your  arm  will  quickly  become  tired 
swapping  disks.  The  situation  improves 
if  you  have  high-capacity  diskettes,  such 
as  the  3V2-inch  drives  found  in  many 
newer  machines.  I  had  no  problems 
using  both  QC  and  TC  on  my  dual- 
720K  microfloppy  laptop.  A  hard  disk 
is  best  for  both. 

The  installation  programs  leave  little 
room  for  complaint.  The  user  is  given 
complete  control  over  which  compo¬ 
nents  are  installed  and  which  directo¬ 
ries  the  components  are  installed  into. 
Each  installation  program  reminds  the 
user  to  set  the  proper  environment  vari¬ 
ables.  In  keeping  with  QC’s  less  expe¬ 
rienced  target  audience,  Microsoft’s 
more  detailed  (but  also  more  verbose) 
description  of  the  installation  process  is 
a  bonus  for  those  unfamiliar  with  mem¬ 
ory  models  and  compiler  installation. 
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While  it’s  not  a  “bug”  per  se  QC’s 
installation  program  does  have  the  an¬ 
noying  habit  of  placing  the  font  files 
into  the  same  directory  as  the  sample 
programs.  I  always  think  of  sample 
code  as  something  to  be  deleted  (sooner 
or  later).  I  would  prefer  the  fonts  to  be 
copied  into  the  directory  where  library 
files  are  stored. 

If  you  use  a  hard  disk  drive,  you’ll 
need  more  than  2  Mbytes  of  free  space 

QC  and  TC  follow 
the  ANSI  standard 
as  well  as,  or  better 
than,  most  other 
MS-DOS  C  compilers  on 
the  market 


on  the  drive  when  you  install  these 
products.  After  cleaning  up  example 
files  and  read-me  files,  you  can  easily 
fit  either  product  into  about  one  and 
one-half  Mbytes. 

Documentation 

TC’s  documentation  consists  of  a  425- 
page  user's  guide,  and  a  61 2-page  refer¬ 
ence  guide.  The  user’s  guide  contains 
tutorials  on  the  environment,  the  de¬ 
bugger,  and  the  C  language.  The  refer¬ 
ence  guide  includes  a  library  function 
dictionary  and  detailed  information 
about  the  command-line  utilities. 

Borland  has  created  a  good  set  of 
tutorials  that  cover  all  of  the  necessary 
subjects  and  include  well-designed  ex¬ 
amples.  I  especially  like  the  “helpful 
hints,”  such  as  a  section  on  common 
C  programming  pitfalls.  These  “dos  and 
don’ts”  are  valuable  to  the  beginning 
programmer  who  has  little  experience 
with  C. 

Documentation  of  the  TC  command¬ 
line  compiler  and  utilities  is  terse  but 
complete.  By  placing  this  information 
in  appendices,  Borland  seems  to  indi¬ 
cate  that  they  expect  most  program¬ 
mers  to  use  the  environment.  Exam¬ 
ples  that  show  how  to  use  the  command¬ 
line  compiler  and  the  linker  are  virtu¬ 
ally  nonexistent. 

QC’s  documentation  also  consists  of 
three  manuals  — a  64-page  Up  and  Run¬ 
ning  booklet,  the  336-page  toolkit  man¬ 
ual,  and  the  376-page  C  for  Yourself. 
Up  and  Running  covers  installation  and 


includes  some  basic  details  about  how 
to  run  the  environment.  The  toolkit 
manual  covers  the  command-line  utili¬ 
ties  in  detail.  C  for  Yourself  is  a  C- 
language  tutorial  and  reference. 

Despite  the  number  of  its  pages,  I 
consider  this  set  of  documentation 
largely  inadequate.  Microsoft  assumes 
that  the  user  will  run  through  the  inter¬ 
active  tutorial.  While  the  tutorial  is  well- 
designed  and  informative,  it  does  not 
touch  on  all  of  the  subjects  that  a  com¬ 
plete  manual  would  cover.  At  least  half 
of  the  editor  functions  are  not  docu¬ 
mented  anywhere.  Many  menu  items 
are  ignored  or  glossed  over.  The  user 
must  explore  the  environment  in  order 
to  completely  learn  it.  While  the  tuto¬ 
rial  is  a  general  introduction  to  the 
product,  it  is  not  comprehensive  enough 
to  replace  thorough  paper  documenta¬ 
tion. 

C  for  Yourself  is  a  superb  C  tutorial 
that  leads  the  programmer  through  all 
of  the  fundamentals  of  the  language 
and  into  implementation-specific  fac¬ 
ets  of  QC.  Unfortunately,  this  manual 
falls  short  of  perfection  by  omitting  any 
mention  of  many  important  library  func¬ 
tions.  For  instance,  there  is  no  mention 
about  the  MS-DOS  interface  functions, 
such  as  intdos( )  and  int86( ).  Several 
keywords,  including  far,  near ,  and  in¬ 
terrupt r,  are  also  ignored.  Information 
about  these  subjects  is  available  in  the 
on-line  help  (described  later),  but  that 
is  not  a  viable  solution  — a  beginning 
C  programmer  will  not  know  which 
questions  to  ask  in  order  to  be  able  to 
look  up  this  missing  information  on¬ 
line.  The  solution  is  to  purchase  a  $25 
supplemental  manual. 

Microsoft’s  documentation  of  the  com¬ 
mand-line  utilities  is  first-class.  The 
toolkit  manual  begins  with  a  short  sec¬ 
tion  discussing  the  utilities  in  general, 
and  then  moves  on  to  chapters  that 
describe  each  tool  in  detail.  Liberal  ex¬ 
amples  illustrate  the  use  of  the  differ¬ 
ent  utilities. 

On-line  Help 

Microsoft  has  put  a  great  deal  of  effort 
into  QC’s  on-line  help  system,  which 
it  considers  an  essential  part  of  the 
documentation.  The  help  system  is  con¬ 
text-sensitive  and  uses  some  of  the  con¬ 
cepts  of  hypertext.  You  point  to  an 
item  with  the  cursor  and  then  press  FI 
to  get  help;  this  method  works  even 
on  help  information.  All  of  the  library 
functions,  error  messages,  and  C  key¬ 
words  are  documented.  “Hotlinks”  in 
each  description  block  can  be  used  to 
move  to  other  areas,  including  an  al¬ 
phabetical  index  and  a  table  of  con¬ 
tents.  You  can  set  “bookmarks”  in  the 
help  system  that  let  you  quickly  return 


to  a  specific  piece  of  information.  As 
an  added  bonus,  you  can  cut  and  paste 
information  in  the  help  system  (includ¬ 
ing  example  programs)  into  a  file  that 
you  are  editing. 

Despite  its  many  strong  points,  QC’s 
help  system  has  a  few  holes.  The  Huge 
keyword  can  be  found  in  the  list  of  C 
keywords,  but  not  in  the  alphabetical 
index.  Also,  the  help  system  requires  a 
great  deal  of  hard  disk  space  — more 
than  half  a  megabyte!  Because  the  sys¬ 
tem  is  built  into  the  QC  environment, 
it  is  impossible  to  access  the  help  infor¬ 
mation  if  you  use  your  own  editor.  On 
the  other  hand,  the  QC  help  has  more 
than  200  working  code  samples  that 
the  user  can  copy  directly  into  a  pro¬ 
gram. 

TC’s  help  system  is  less  sophisticated 
but  adequate.  A  general  index  and/or 
table  of  contents  is  missing  from  the 
help  system.  To  retrieve  help  informa¬ 
tion  on  the  current  window,  you  press 
FI.  To  obtain  details  about  the  item 
that  the  cursor  is  currently  pointing  to, 
such  as  a  standard  library  function  or 
keyword,  you  press  Ctrl-Fl.  By  point¬ 
ing  to  a  header  file  name  (such  as 
stdio.h)  with  the  cursor  and  pressing 
Ctrl-Fl,  you  can  access  a  list  of  the 
function  prototypes  and  definitions  that 
the  file  contains.  In  the  long  run,  though, 
TC’s  help  system  is  less  extensive  than 
the  help  system  in  QC. 

However,  TC  provides  a  TSR  to  make 
the  help  information  available  in  an 
external  editor.  This  is  very  handy  for 
those  who  prefer  to  use  their  favorite 
editor  and  the  command-line  utilities. 

Thus  we  have  a  trade-off:  more  and 
better  paper  documentation  but  less 
on-line  help  in  TC,  more  help  and  less 
detailed  manuals  with  QC. 

Language  Implementations 

QC  and  TC  follow  the  ANSI  standard 
as  well  as,  or  better  than,  most  other 
MS-DOS  C  compilers  on  the  market. 
Both  products  include  all  of  the  com¬ 
mon  MS-DOS  language  extensions,  such 
as  the  near  and  far  keywords.  Pro¬ 
grammers  will  not  be  disappointed  with 
the  languages  supported  by  either  of 
the  products. 

While  both  compilers  support  inline 
assembly,  QC’s  implementation  is  by 
far  the  better.  With  TC,  each  line  of 
inline  assembly  language  must  be  pref¬ 
aced  with  the  keyword  _asm.  TC  also 
requires  that  you  have  a  command-line 
assembler,  such  as  Borland’s  TASM  or 
Microsoft’s  MASM,  in  order  to  use  the 
inline  assembler.  On  the  other  hand, 
QC  includes  a  complete  built-in  assem¬ 
bler.  Multiline  blocks  of  inline  assem- 
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bly  code  can  be  created  within  curly 
braces  following  a  single  instance  of 
the  _asm  keyword. 

Function  Libraries 

Competing  vendors  are  always  looking 
for  ways  to  spice  up  their  products. 
With  C  compilers,  an  excellent  way  to 
do  this  is  by  adding  functions  to  the 
library.  TC  and  QC  sport  some  of  the 
largest  libraries  in  existence. 

With  the  exception  of  multicharacter 
and  international  support  functions,  the 
libraries  are  very  complete  from  an  ANSI 
standpoint.  QC  and  TC  provide  addi¬ 
tional  functions  for  direct  access  to  the 
underlying  hardware  and  MS-DOS.  Most 
of  the  function  names  and  parameters  are 
similar  between  the  two  products. 

Borland  added  an  excellent  graphics 
library  with  TC,  Version  1.5,  that  was 
not  significantly  changed  for  Version 
2.0.  When  QC  was  first  introduced,  it 
included  a  modest  graphics  library, 
which  has  been  dramatically  improved 
in  the  most  recent  version  of  QC. 

QC  and  TC  support  all  of  the  basic 
graphics  primitives,  along  with  stroked 
and  bit-mapped  fonts.  TC  “autodetects” 
the  type  of  graphics  adapter  installed; 
QC  does  not,  but  listings  in  the  manu¬ 
als  provide  a  “trial  and  error”  loop  for 
finding  and  entering  the  best  graphics 
mode.  Borland  allows  fonts  and  graph¬ 
ics  device  drivers  to  be  loaded  at  run 
time  or  to  be  made  into  linkable  object 
modules.  Microsoft’s  graphics  drivers 
are  linkable,  but  the  fonts  must  be 
loaded  from  disk  files  at  run  time. 

If  you  work  with  charts  and  tables, 
QC  has  as  a  real  treat  in  store.  Its  graph¬ 
ics  library  includes  a  set  of  presenta¬ 
tion  graphics  functions.  A  special  struc¬ 
ture  is  loaded  with  information  that 
can  be  used  to  draw  pie,  bar,  stacked- 
bar,  line,  or  scatter  charts.  Hatching, 
borders,  legends,  and  headings  are  all 
handled  very  nicely.  By  contrast,  TC 
provides  a  full  complement  of  lower- 
level  functions  to  help  you  build  charts, 
but  Microsoft’s  package  is  more  auto¬ 
mated  and  convenient. 

Environment 

QC  and  TC  are  both  chiefly  integrated 
environments  combining  an  editor,  a 
compiler,  and  a  linker  into  a  single, 
all-in-one  program.  A  menu  bar  across 
the  top  of  the  screen  provides  pull¬ 
down  menus  for  various  operations, 
such  as  loading  and  saving  files,  com¬ 
piling,  and  debugging.  Program  op¬ 
tions  can  be  set  through  these  menus 
and  then  saved  to  disk.  Both  programs 
permit  such  configurations  to  be  stored 
in  files  in  different  directories,  offering 
you  the  flexibility  to  specify  options  for 
different  projects.  When  you  start  the 


environment  from  a  given  project  di¬ 
rectory,  the  configuration  stored  there 
becomes  the  default. 

In  keeping  with  its  target  audience 
of  less  experienced  users,  QC  offers  a 
unique  two-level  menuing  system.  The 
lower  (default)  level  provides  a  “bare 
bones”  set  of  menus,  presumably  in¬ 
tended  to  keep  the  novice  user  from 
being  intimidated  by  the  environment. 
As  the  QC  user  becomes  more  confi¬ 
dent,  he  or  she  can  set  an  option  that 
activates  the  more  complete  menuing 
system. 

I  truly  like  both  products 
— each  has  good  and 
bad  points,  and 
there  is  no  loser.  The 
winners  are  the 
programmers  who 
benefit  from  the 
competition 


The  QC  and  TC  editors  are  not  going 
to  excite  programmers  accustomed  to 
sophisticated  editing  programs  such  as 
Brief  and  QEdit.  Both  editors  use  an 
extended  subset  of  the  WordStar  com¬ 
mand  set.  By  “extended  subset,”  I  mean 
that  they  use  many  of  the  WordStar 
commands,  and  also  add  several  of 
their  own.  QC  has  a  menu  option  to 
install  an  alternate  editor.  In  addition, 
QC’s  “notepad”  window  allows  you 
to  edit  more  than  one  file  at  a  time. 
QC  and  TC  both  include  utilities  for 
redefining/adding  command  keys  and 
otherwise  adjusting  the  editor  to  per¬ 
sonal  preferences. 

Neither  product  supports  editor  mac¬ 
ros  or  context-sensitive  editing.  QC  ac¬ 
commodates  — in  fact,  almost  de¬ 
mands  — a  mouse,  which  makes  many 
operations  easier.  (Why  Borland  prod¬ 
ucts  lack  mouse  support  is  a  matter  of 
ongoing  curiosity  and  annoyance.)  The 
undo  facilities  of  both  editors  are  virtu¬ 
ally  nonexistent. 

Both  products’  compilers  and  link¬ 
ers  are  very  fast  and  support  a  full  line 
of  memory  models.  TC  supports  a  Tiny 
model  (unavailable  from  Microsoft)  that 
can  be  made  into  .COM  files.  Other¬ 
wise,  the  basic  code-generation  capa¬ 
bilities  of  the  two  products  are  similar. 


Errors  are  tracked  and  displayed  in  their 
own  window. 

In  QC’s  favor  is  its  “incremental”  com¬ 
pile  and  link.  In  effect,  the  compiler 
only  recompiles  and  relinks  those  parts 
of  a  program  that  have  changed.  On  a 
large  source  program,  QC’s  ability  to 
perform  incremental  compiles  gives  this 
compiler  an  amazing  speed  advantage. 
This  is  particularly  important  during 
debugging,  when  compiles  often  take 
place  after  only  a  few  changes  are  made 
to  a  program. 

Make  facilities  are  built  into  both 
environments.  TC  calls  the  control  enti¬ 
ties  “Project  Files,”  while  QC  names 
them  “Program  Lists.”  Each  lists  the 
files  belonging  to  a  multimodule  pro¬ 
gram,  and  the  compiler/linker  is  intelli¬ 
gent  enough  to  process  only  those  mod¬ 
ules  that  have  changed  since  the  last 
program  build.  I  like  QC’s  built-in  Make 
better,  because  it  creates  a  true  Make¬ 
file  on  disk  for  use  with  the  stand¬ 
alone  Make  program.  On  the  other 
hand,  TC  needs  differently-formatted 
project  and  Make  files  for  the  environ¬ 
ment  and  command-line  utilities,  even 
when  the  same  source  modules  are  in¬ 
volved.  There  are  conversion  utilities, 
but  the  different  formats  are  a  hassle. 

Here’s  an  interesting  statistic  about 
memory  usage:  When  no  files  are  loaded 
TC  uses  318K  of  memory.  By  contrast, 
QC  uses  only  185K,  an  amazing  im¬ 
provement  over  the  previous  version 
that  barely  fit  into  640K.  Note,  how¬ 
ever,  that  TC  takes  advantage  of  EMS 
when  present,  whereas  QC  does  not. 

Debuggers 

The  debuggers  included  in  integrated 
environments  are  not  as  capable  as 
their  stand-alone  brethren.  This  does 
not  mean  they’re  useless;  it  merely 
means  that  these  debuggers  are  de¬ 
signed  to  detect  the  most  comon  kinds 
of  run-time  problems.  The  debuggers 
for  QC  and  TC  can  step  through  pro¬ 
grams  line-by-line,  set  breakpoints, 
watch  variables  while  the  program  runs, 
and  change  the  values  of  variables  while 
the  program  runs.  They  can  also  follow 
pointers,  display  structures,  examine 
the  stack  and  registers,  and  provide 
output  in  several  forms  (hex,  decimal, 
and  so  on). 

The  TC  debugger  is  an  easy-to-use 
product  that  is  solid  and  useful  for  find¬ 
ing  common  bugs.  Borland  devotes  a 
great  deal  of  space  in  the  TC  manuals 
to  the  discussion  of  debugging  tech¬ 
niques  and  strategies.  Unfortunately, 
TC  does  not  support  conditional  break¬ 
points  or  the  “animation”  (execution 
in  slow  motion)  of  programs. 

QC’s  debugger,  a  subset  of  Code- 
view,  has  several  pluses  and  one  sur- 
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(continued  from  page  71) 
prising  minus.  I  like  the  “locals”  win¬ 
dow,  which  shows  the  values  of  all 
local  variables  for  whatever  function 
is  currently  being  traced.  The  “regis¬ 
ters”  window  shows  the  processor  reg¬ 
isters  as  if  they  were  variables,  and 
makes  the  debugging  of  inline  assem¬ 
bler  much  easier.  The  ability  to  store 
“history”  information  permits  you  to 
retrace  steps  previously  executed.  User 
input  can  also  be  recorded  and  re¬ 
played,  saving  a  great  deal  of  time  when 
bugs  are  located  deep  within  a  pro¬ 
gram’s  logic. 

The  omission  in  QC’s  debugger  is 
almost  unbelievable  — it  is  not  possi¬ 
ble  to  simply  check  a  variable;  instead 
you  have  to  put  the  variable  into  the 
watch  window!  This  process  involves 
several  keystrokes,  where  one  would 
be  sufficient.  And  having  seen  the  value, 
it  takes  several  more  keystrokes  to  get 
rid  of  it. 

In  contrast,  TC’s  debugger  allows  you 
to  see  the  value  of  any  variable  instan¬ 
taneously  by  pressing  Ctrl-F4.  The  vari¬ 
able  name  under  the  cursor  is  auto¬ 
matically  displayed.  You  can  “rip  out” 
further  text  from  the  source  — for  ex¬ 
ample,  a  structure  field  name  — by  press¬ 
ing  the  right  arrow  key  until  the  com¬ 
plete  name  of  the  variable  you  want  to 
see  is  in  the  window.  If  the  cursor 
location  selects  the  wrong  variable 
name,  you  simply  type  the  one  you 
want.  Similarly,  you  can  type  C  expres¬ 
sions  and  see  the  result,  and  also  change 
a  value  “on  the  fly,”  as  for  example  in 
finding  out  how  the  program  deals  with 
an  unexpected  data  value.  You  press 
Esc  to  make  the  examination  window 
go  away.  TC’s  integrated  debugger  also 
includes  a  watch  window  similar  to 
QC’s  for  more  permanently  displaying 
selected  variables  and  their  dynami¬ 
cally  updated  values. 

Command-line  Utilities 

For  those  who  dislike  environments, 
QC  and  TC  supply  utilities  for  use  at 
the  MS-DOS  prompt.  Each  product  in¬ 
cludes  a  command-line  compiler,  linker, 
Make  facility,  and  object-module  librar¬ 
ian.  Each  also  furnishes  some  unique 
utilities.  For  example,  TC  adds  a  pre¬ 
processor,  a  grep,  an  object-module 
cross-reference  utility,  and  a  program 
to  convert  graphics  drivers  and  fonts 
to  object  modules.  As  for  QC,  it  fur¬ 
nishes  a  utility  to  create  customized 
help  files. 

Conclusions 

TC  has  few  blemishes.  For  example, 
documentation  of  the  command-line 
utilities  could  be  expanded,  and  real 
inline  assembly  would  elimiate  the  need 


for  an  external  assembler.  On  the  plus 
side,  the  integrated  debugger  is  more 
powerful,  documentation  is  more  com¬ 
plete,  and  the  set  of  command-line  utili¬ 
ties  is  more  extensive  than  that  of  QC. 
All  in  all,  TC  is  a  quality  product  with 
features  aimed  at  a  more  demanding, 
competent  C  programmer  than  QC. 

Probably  the  most  important  area 
where  QC  needs  improvement  is  the 
paper  documentation  — more  informa¬ 
tion  is  needed  for  beginners  who  are 
moving  toward  the  realm  of  experts. 
In  spite  of  this,  QC  has  a  slight  edge 
over  TC  in  a  couple  of  areas.  QC  cleanly 
supports  inline  assembler,  has  a  supe¬ 
rior  graphics  library,  and  incorporates 
some  impressive  new  technology  with 
its  incremental  compilation  and  linking 
capabilities.  One  dramatic  improvement 
over  the  earlier  version  is  that  QC  is 
no  longer  a  “toy”  compiler  with  no 
selection  of  memory  models.  It  now 
supports  all  models  except  Tiny. 

I  truly  like  both  products  — each  has 
good  and  bad  points,  and  there  is  no 
loser.  The  winners  are  the  program¬ 
mers  who  benefit  from  the  competition 
that  generates  better  products.  No  mat¬ 
ter  which  product  you  buy,  be  assured 
that  you’re  not  wasting  your  money. 

So  much  for  TC  versus  QC.  In  the 
August  issue  we’ll  pit  TC  against  QC’s 
“big  brother”  and  wrap  up  with  a  bench¬ 
mark  report  that  compares  the  perform¬ 
ance  of  all  three. 

DDJ 

Vote  for  your  favorite  feature/article. 

Circle  Reader  Service  No.  6. 


ARCHIVES 


And  We’re  Still  Trying  to  Define 
What  OOP  Is 

“Actor  languages,  also  known  as  object- 
oriented  languages,  are  languages  in  which 
objects  communicate  by  the  sending  and 
receiving  of  messages.  Each  actor  is  a  member 
of  a  class,  and  that  class  may  be  a  member 
of  a  superclass,  and  so  on.  Actor  languages 
provide  a  new  perspective  to  Turing’s  idea 
of  the  incremental  computer.”  — Ronald  L. 
Nicol,  "Actors,  Property  Lists,  and  LISP,  "DDJ, 
December,  1981. 
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TSR  PROGRAMS 


Listing  One  (Text  begins  on  page  14.) 

{  5) 

$73/<22 — 7 / 

JNB  IncF 

function — skip  table.} 

UNIT  TSRUnit;  {Create  TSR  programs  with  Turbo  Pascal  5.0  &  TSRUnit} 

{  7] 

$50/ 

PUSH  AX 

Save  registers.  } 

{  8] 

$53/ 

PUSH  BX 

Load  offset  to  table.} 

{$B-,F-, I+,R-, S+)  {Set  compiler  directives  to  normal  values.) 

{  9] 

$BB/>DosTab/ 

MOV  BX, [DosTab] 

} 

{  12] 

$8A/$C4/ 

MOV  AL,  AH 

Load  table  entry  } 

INTERFACE  { - ) 

<  14} 

$2E/ 

CS: 

index.  } 

{ 

{  15} 

$D7/ 

XLAT 

Get  value  from  table.) 

The  author  and  any  distributor  of  this  software  assume  no  responsi- 

{  16) 

$3C/$00/ 

CMP  AL,  0 

If  TRUE  then  set  flag) 

bility  for  damages  resulting  from  this  software  or  its  use  due  to 

{  18) 

$5B/ 

POP  BX 

Restore  registers.  } 

} 

errors,  omissions,  incompatibility  with  other  software  or  with 

{  19) 

$58/ 

POP  AX 

hardware,  or  misuse.  Specifically  disclaimed  is  any  implied  warranty 

{  20} 

$74/$17/ 

JZ  JmpDos21 

Jump  to  orig.  intr.  } 

of  fitness  for  any  particular  purpose  or  application. 

{  22} 

$2E/  { IncF 

CS: 

) 

} 

{  23} 

$FE/$06/>UnSafe/ 

INC  [Unsafe] 

Set  UnSafe  flag.  ) 

USES  DOS,  CRT; 

<  27} 

$9D/ 

POPF 

Restore  flags.  ) 

) 

CONST 

{  28} 

$9C/ 

PUSHF 

{***  Shift  key  combination  codes.  ) 

{  29) 

$2E/ 

CS: 

} 

AltKey  =  8;  CtrlKey  =  4;  LeftKey  =  2;  RightKey  =  1? 

{  30) 

$FF/$lE/>Dos21/ 

CALL  FAR  [Dos2l ] 

Call  orig.  intr.  } 

{  34) 

$FB/ 

STI 

Enable  interrupts.  } 

TSRVersion  :  WORD  =  $0203;  {Low  byte. High  byte  =2.03  ) 

{  35) 

$9C/ 

PUSHF 

Save  flags.  } 

} 

{  36} 

$2E/ 

CS: 

TYPE 

{  37} 

$FE/$0E/>UnSafe/ 

DEC  [Unsafe] 

Clear  UnSafe  flao.  ) 

String80  =  STRING (80); 

{  41} 

$9D/ 

POPF 

Restore  flags.  } 

ChrWords  =  RECORD  CASE  INTEGER  OF 

{  42) 

$CA/$02/$00/ 

RETF  2 

Return  &  remove  flag.} 

1:  (  W:  WORD  ); 

2:  (  C:  CHAR;  A:  BYTE  ); 

{  45} 

$9D/  { JmpDos21 

POPF 

Restore  flags.  ) 

END; 

{  46} 

$2E  / 

CS: 

} 

LineWords  =  ARRAY [1.. 80)  OF  ChrWords; 

{  47} 

$FF/$2E/>Dos21/ 

JMP  FAR  [Dos21] 

Jump  to  orig.  intr.  } 

WordFuncs  =  FUNCTION  :  WORD; 

(  51} 

,**. 

0urlntr25  ********** 

Intercept  routine  for  DOS  Abs.  Read  ***  } 

VAR 

{  0} 

$9C/ 

PUSHF 

Save  flags.  } 

TSRScrPtr  :  POINTER;  {Pointer  to  saved  screen  image.  ) 

{  1) 

$2E/ 

CS: 

) 

TSRChrPtr  :  POINTER;  {Pointer  to  first  character  to  insert.  ) 

{  2) 

$FE/$06/>UnSafe/ 

INC  [Unsafe] 

Set  UnSafe  flag.  ) 

TSRMode  :  BYTE;  {Video  mode  -  before  TSR  popped  up.) 

{  6) 

$9D/ 

POPF 

Restore  flags.  } 

TSRWidth  :  BYTE;  {Number  of  screen  columns —  "  "  "  "  .} 

{  7} 

$9C/ 

PUSHF 

) 

TSRPage  :  BYTE;  {Active  video  page  number —  "  "  "  "  . ) 

(  8) 

$2E/ 

CS: 

} 

TSRColumn  :  BYTE;  {Cursor  column  number  -  "  "  "  "  .) 

{  9} 

$FF/$lE/>Dos25/ 

CALL  FAR  [Dos25] 

Call  DOS  abs.  read.  ] 

TSRRow  :  BYTE;  {Cursor  row  number - "  "  "  "  .) 

{  13} 

$83/$C4/$02/ 

ADD  SP, 2 

Clean  up  stack.  ) 

( 

{  16} 

$9C/ 

PUSHF 

Save  flags.  ) 

**  Procedure  for  installing  the  TSR  program.  ) 

{  17} 

$2E/ 

CS: 

) 

PROCEDURE  TSRInstall (  TSRName  :  STRING;  (Name  or  title  for  TSR.  ) 

{  18) 

$FE/$0E/>UnSafe/ 

DEC  [Unsafe) 

Clear  UnSafe  flag.  } 

TSRFunc  :  WordFuncs; {Ptr  to  FUNCTION  to  call) 

{  22) 

$9D/ 

POPF 

Restore  flags.  Leave} 

ShiftComb:  BYTE;  {Hot  key — shift  key  comb) 

{  23) 

$CB/ 

RETF  ;old  flags  on  the  stk.)  j 

KeyChr  :  CHAR  );  (Hot  Key— character  key.) 

{  24) 

{ 

{***  OurIntr26  ********** 

Intercept  routine  for  DOS  Abs.  Write  ***} 

ShiftComb  and  KeyChr  specify  the  default  hot  keys  for  the  TSR. 

(  0} 

$9C/ 

PUSHF 

Save  flags.  ) 

ShiftComb  may  be  created  by  adding  or  ORing  the  constants  AltKey, 

{  1) 

$2E/ 

CS: 

) 

CtrlKey,  LeftKey,  and  RightKey  together.  KeyChr  may  be 

(  2} 

$FE/$06/>UnSafe/ 

INC  [Unsafe] 

Set  UnSafe  flag.  ) 

characters  0-9  and  A-Z. 

{  6} 

$9D/ 

POPF 

Restore  flags.  ) 

{  7} 

$9C/ 

PUSHF 

) 

The  default  hot  keys  may  be  overridden  when  the  TSR  is  installed 

{  8) 

$2E/ 

CS: 

) 

by  specifying  optional  parameters  on  the  command  line.  The 

{  9} 

$FF/$lE/>Dos26/ 

CALL  FAR  [Dos26] 

Call  DOS  abs.  write.  ) 

parameter  format  is: 

{  13} 

$83/$C4/$02/ 

ADD  SP, 2 

Clean  up  stack.  ) 

(/A)  [/C]  (/R)  [/L]  [ / "  [ K [ " ]  ] ) 

{  16) 

$9C/ 

PUSHF 

Save  flags.  } 

The  square  brackets  surround  optional  items — do  not  include  them. 

{  17) 

$2E/ 

CS: 

} 

Any  characters  between  parameters  are  ignored.  The  order  of  the 

{  18) 

$FE/$OE/>UnSafe/ 

DEC  [Unsafe] 

Clear  UnSafe  flag.  } 

characters  does  not  matter;  however,  the  shift  keys  specified  are 

{  22} 

$9D/ 

POPF 

Restore  flags.  Leave) 

cummulative  and  the  last  character  key  "K"  specified  is  the  used. 

) 

1  23) 

{  24) 

$CB/ 

RETF 

old  flags  on  the  stk.) 

{ 

**  Functions  for  checking  status  of  printer  LPT1.  ) 

{***  OurIntr9  **********  intercept  for  BIOS  Hardware  Keyboard  Intr) 

FUNCTION  PrinterOkay:  BOOLEAN;  {Returns  TRUE  if  printer  is  okay.) 

{  0} 

$9C/ 

PUSHF  ;Entry  point.  } 

FUNCTION  PrinterStatus:  BYTE;  {Returns  status  of  printer. 

{  1) 

$FB/ 

STI 

Enable  interrupts.  } 

Definition  of  status  byte  bits  (1  &  2  are  not  used),  if  set  then: 

{  2} 

$1E/ 

PUSH  DS 

) 

Bit:  —  7 -  - 6 -  —  5  —  4  —  —  3  —  - 0  — 

{  3) 

$0E/ 

PUSH  CS 

DS  :=  CS;  ) 

Not  busy  Acknowledge  No  paper  Selected  I/O  Err.  Timed-out 

{  4} 

$1F/ 

POP  DS 

} 

) 

{  5) 

$50/ 

PUSH  AX 

Preserve  AX  on  stack.) 

{ 

{  6) 

$31/$C0/ 

XOR  AX, AX 

Set  AH  to  0.  } 

**  Routines  for  obtaining  one  row  of  screen  characters.  ) 

{  8) 

$E4 / $  60 / 

IN  AL, 60h 

Read  byte  from  keybd  } 

FUNCTION  ScreenLineStr (  Row:  BYTE  ):  String80;  (Returns  char,  str.) 

{  10} 

$3C/$E0/ 

CMP  AL, OEOh 

If  multi-byte  codes,  } 

PROCEDURE  ScreenLine(  Row:  BYTE;  VAR  Line:  LineWords;  {Returns  ) 

{  12) 

$74/ <75—14/ 

JE  Sfx 

then  jump  and  set  } 

VAR  Words:  BYTE  );  {chr  &  color) 

{  14) 

$3C/$F0/ 

CMP  AL, OFOh 

multi-byte  flag,  Flg9) 

{  16} 

$74/<75— 18/ 

JE  Sfx 

) 

IMPLEMENTATION  { ================================================== ) 

{  18} 

$80/$3E/>Flg9/$00/ 

CMP  [Flg9] , 0 

Exit  if  part  of  } 

VAR 

{  23} 

$75/<77— 25/ 

JNZ  Cfx 

multi-byte  code.  ) 

BuffSize,  InitCMode  :  WORD; 

(  25} 

$3A/$06/>Key/ 

CMP  AL, [Key] 

Exit  if  key  pressed  ) 

NpxFlag  :  BOOLEAN; 

Buffer  :  ARRAY [0 .. 8191)  OF  WORD; 

{  29} 

$75/<88— 31/ 

JNE  PreExit 

is  not  hot  key.  } 

NpxState  :  ARRAY[0..93]  OF  BYTE; 

{  31} 

$50/ 

PUSH  AX 

Hot  key  was  pressed,  } 

RetrnVal,  InitVideo  :  BYTE; 

{  32} 

$06/ 

PUSH  ES 

check  shift  key  } 

TheirFunc  :  WordFuncs; 

{  33} 

$B8/$40/$00/ 

MOV  AX, 004  Oh 

status  byte.  First  } 

{  36} 

$8E/$C0/ 

MOV  ES, AX 

load  BIOS  segment.  } 

CONST  {Offsets  to  items  contained  in  PROCEDURE  Asm.  ) 

{  38} 

$26/ 

ES: 

} 

Unsafe  =  0;  Fig  =  1;  Key  =  2;  Shft  =  3; 

{  39} 

$A0/>$0017/ 

MOV  AL, [ 00 1 7h ] 

AL:=  Shift  key  status} 

StkOfs  =  4;  StkSs  =  6;  DosSp  =  8;  DosSs  =  10; 

{  42} 

$07/  i 

POP  ES 

Restore  ES  register.  } 

Prev  =  12;  Flg9  =  13;  InsNumb  =  14; 

{  43} 

$24/$0F/  1 

AND  AL, OFh 

Clear  unwanted  bits.  } 

Dos21  =  $10;  Dos25  =  Dos21+4;  Dos26  =  Dos25+4; 

{  45} 

$3A/$06/>Shft/  1 

CMP  AL, [Shft] 

Exit  if  not  hot  key  ) 

Bios9  =  Dos26+4;  Biosl6  =  Bios9+4;  DosTab  =  Biosl6+4; 

{  49) 

$58/  1 

POP  AX 

shift  key  combination} 

Our21  =  DosTab+99;  Our25  =  Our21+51;  Our26  =  Our25+24; 

Our09  =  Our26+24;  Ourl6  =  Our09+127+8;  InsChr  =  Ourl6+180-8; 

{  50} 

$75/<88— 52/ 

JNE  PreExit 

(Restore  AX  first) .  } 

PopUp  =  InsChr+4; 

1 

;Hot  Keys  encountered.} 

{  52} 

$3A/$06/>Prev/  { 

CMP  AL, [Prev] 

Discard  repeated  hot  } 

PROCEDURE  Asm;  {Inline  code — data  storage  and  intercept  routines.  ) 

{  56} 

$74/<107— 58/  I 

JE  Discard 

key  codes.  } 

INTERRUPT; 

{  58} 

$A2/>Prev/  { 

MOV  [Prev] , AL 

Update  Prev.  } 

BEGIN 

{  61} 

$F6/$06/>Flg/3/  { 

TEST  [Fig], 3 

If  Fig  set,  keep  key  } 

INLINE ( 

{  66} 

$75/09-68/  1 

JNZ  JmpBios9 

&  exit  to  orig.  BIOS  ) 

{***  Storage  for  interrupt  vectors.  ) 

{  68} 

$80/$0E/>Flg/l/  | 

OR  [Fig] , 1 

9.  Else  set  flag  and) 

{Dos21:  )  >0/>0/  {DOS  func.  intr  vector.  } 

{Dos25:  )  >0/>0/  {DOS  abs.  disk  read  intr.  vector.  } 

{  73} 

$EB/<107-75/  { 

JMP  SHORT  Discard 

discard  key  stroke.  } 

{Dos26:  )  >0/>0/  {DOS  abs.  sector  write  intr. vector.  ) 

{  75} 

$B4/$01/  { Sf x : 

MOV  AH,  1 

Load  AH  with  set  flag) 

{Bios9:  )  >0/>0/  {BIOS  key  stroke  intr.  vector.  } 

{  77} 

$88/$26/>Flg9/  {Cfx: 

MOV  [Flg9] , AH 

Save  multi-byte  flag. ) 

{Biosl6:  }  >0/>0/  {BIOS  buffered  keybd.  input  intr.vect.) 

{  81} 

$C6/$06/>Prev/$FF /  { 

MOV  (Prev],0FFh  ;Change  prev  key  byte.) 

{  86} 

$EB/<99-88/  { 

JMP  SHORT  JmpBios9 

} 

{DosTab:  ARRAY[0..98]  OF  BYTE  =  {Non-reetrant  DOS  functions.) 
0/0/0/0/0/0/0/0/  0/0/0/0/0/1/1/1/  l/l/l/l/l/l/l/l/ 

{  88} 

$3C/$FF/  {PreExit: 

CMP  AL, OFFh 

Update  previous  key  ) 

l/l/l/l/l/l/l/l/  1/1/1/1/1/1/0/1/  1/1/1/1/1/1/1/0/ 

{  90} 

$74/<99— 92/  { 

JE  JmpBios9  ,-unless  key  is  buffer-} 

1/0/0/0/0/0/1/1/  l/l/l/l/l/l/l/l/  l/l/l/l/l/l/l/l/ 

{  92} 

$3C/$00/  ( 

CMP  AL,  0 

full  code — a  OOh  } 

0/0/0/0/0/0/1/1/  0/0/0/0/1/0/1/1/  0/1/1/1/1/0/0/0/  0/0/0/ 

{  94} 

$74/09-96/  { 

JZ  JmpBios9  ; 

OFFh  } 

{  96} 

$A2/>Prev/  { 

MOV  [Prev],AL  ; Update  previous  key.  ) 

{***  OurIntr21  *******  Intercept  routine  for  DOS  Function  Intr.***} 

{  0}  $9C/  (  PUSHF  ;Save  flags.  ) 

{  99} 

$58/  {JmpBios9: 

POP  AX  ; Restore  registers  and}  | 

(  1}  $FB/  {  STI  ;Enable  interrupts.  } 

{  2)  $80/$FC/$63/  {  CMP  AH, 63H  ;Assume  unsafe  if  new  ) 

(continued  on  page  76) 
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{100} 

$1F/ 

PROCEDURE  PopUpCode;  (Interface  between  the  BIOS  intercept  )  1 

{101} 

$9D/ 

INTERRUPT;  {routines  and  your  TSR  function. 

I 

{102} 

$2E/ 

CS: 

CONST  BSeg  =  $0040;  VBiosOfs  =  $49; 

{103} 

$FF/$2E/>Bios9/ 

JMF  [Bios9] 

VideoRecs  =  RECORD 

{107} 

IN  AL, 61h 

VideoMode  :  BYTE 

{109} 

$8A/$E0/ 

MOV  AH, AL 

•by  resetting  keyboard) 

NumbCol,  ScreenSize,  MemoryOfs  :  WORD 

{111} 

$0C/$80/ 

OR  AL, 80h 

•port  and  sending  EOI  } 

CursorArea  :  ARRAY [0.. 7]  OF  WORD 

{113} 

$E6/$61/ 

OUT  61h, AL 

•to  intr.  handler  } 

CursorMode  :  WORD 

{115} 

$86/$E0/ 

XCHG  AH, AL 

CurrentPage  :  BYTE 

{117} 

$E6/$  6 1  / 

OUT  61h, AL 

VideoBoardAddr  :  WORD 

{119} 

$B0/$20/ 

MOV  AL, 20h 

•processed.  } 

CurrentMode,  CurrentColor  :  BYTE 

{121} 

$E6/ $20/ 

OUT  20h, AL 

{123} 

?  58  / 

POP  AX 

•Restore  registers  and} 

{124} 

$1F/ 

POP  DS 

Regs  :  Registers; 

{125} 

$9D/ 

POPF 

VideoRec  :  VideoRecs; 

{126} 

$CF  / 

IRET 

(127} 

ScrnSeg,  NumbChr  :  WORD; 

BEGIN 

(***  OurIntrl6  *****  Intercept  routine  for  Buffered  Keyboard  Input} 

SwapVectors;  (Set  T.P.  intr.  vectors.) 

{  0} 

$58/  {JmpBiosl6: 

POP  AX 

Restore  AX,  DS,  and  } 

Move(  Ptr (BSeg, VBiosOfs) A,  VideoRec,  {Get  Video  BIOS  info.  } 

{  1} 

$1F/ 

POP  DS 

FLAGS  registers  then  ) 

SizeOf (VideoRec)  ) ; 

(  2} 

$9D/ 

POPF 

WITH  VideoRec,  Regs  DO  BEGIN 

(  3} 

$2E/ 

CS: 

intr.  16h  routine.  } 

IF  (VideoMode  >  7)  OR  {Abort  pop 

up  if  unable} 

{  4} 

$FF/$2E/>Biosl6/ 

JMP  [Biosl6] 

} 

(ScreenSize  >  Buff Size)  THEN  BEGIN  {to  save  screen  image.  } 

SwapVectors;  {Restore  intr.  vectors.) 

(  8} 

$9C/  {OurIntrl6: 

PUSHF 

•Preserve  FLAGS.  } 

Exit; 

{  9} 

$FB/  i 

STI 

•Enable  interrupts.  } 

END; 

{  10} 

$1E/ 

PUSH  DS 

KeyLock  :=  Mem [BSeg: $0017 ) ;  {Save  lock 

key  states.  } 

{  ID 

$50/ 

PUSH  AX 

IF  VideoMode  =  7  THEN  ScrnSeg  :=  $B000  {Save  screen — supports  } 

{  12} 

$0E/ 

PUSH  CS 

•DS  :=  CS;  } 

ELSE  ScrnSeg  :=  $B800;  {text,  MGA 

&  CGA  modes . ) 

{  13} 

$  IF/ 

POP  DS 

} 

Move(  PTR(  ScrnSeg,  MemoryOfs  )A,  Buffer,  ScreenSize  ); 

{  14} 

$F6/$C4/$EF/ 

TEST  AH, EFh 

Jmp  if  not  read  char.} 

AX  :=  InitVideo;  (If  in  graphics  mode,  } 

{  17} 

$75/<48— 19/ 

JNZ  C3 

request .  } 

IF  (VideoMode  >=4)  {switch  to 

text  mode.  } 

AND  (VideoMode  <=  6)  THEN  Intr(  $10,  Regs  ); 

***  Intercept  loop 

for  Read  Key  service.} 

AX  :=  $0500;  {Select  display  page  0.) 

{  19} 

$F6/$06/>Flg/l/  (Cl: 

TEST  [Fig] , 1 

If  pop  up  Fig  bit  is  } 

Intr (  $10,  Regs  ); 

{  24} 

$74/<29-26/  I 

JZ  C2 

set  then  call  INLINE  ) 

CX  :=  initCMode;  {Set  cursor  size.  } 

{  26} 

$E8/>122— 29/  1 

CALL  ToPopUp 

pop  up  routine.  } 

AH  :=  1; 

{  29} 

$F6/$06/>Flg/16/(C2: 

TEST  [Fig] , lOh 

Jmp  if  insert  fig  set) 

Intr(  $10,  Regs  ); 

{  34} 

$7  5/<48— 36/  1 

JNZ  C3 

) 

{  36} 

$FE/$C4/ 

INC  AH 

Use  orig.  BIOS  ) 

TSRMode  :=  VideoMode;  {Fill  global 

variables  } 

{  38} 

$9C/ 

PUSHF 

service  to  check  for  } 

TSRWidth  :=  NumbCol;  {with  current  information} 

{  39} 

$FA/ 

CLI 

character  ready.  } 

TSRPage  :=  CurrentPage; 

{  40} 

$FF/$lE/>Biosl6/  { 

CALL  FAR  [Biosl6] 

Disable  interrupts.  } 

TSRColumn  :=  Succ (  Lo(  CursorArea [CurrentPage]  )  ) ; 

{  44} 

$58/ 

POP  AX 

Restore  AX  and  save  ) 

TSRRow  :=  Succ(  Hi (  CursorArea [CurrentPage]  ) 

{  45} 

$50/  | 

PUSH  AX 

it  again.  } 

I  46} 

$74/ <19—48/ 

JZ  Cl 

Loop  until  chr.  ready} 

IF  NpxFlag  THEN  {Save  co-processor  state.} 

INLINE (  $98/  $DD/$36/>NpxState  );  {WAIT  FSAVE 

NpxState)  } 

{  48) 

$F6/$06/>Flg/17/{C3: 

TEST  [Fig] , llh 

Exit  if  neither  bit  } 

{ 

{  53} 

$74/<— 55/  | 

JZ  JmpBiosl6 

of  Fig  is  set.  } 

***  Call  user's  program  and  save  return  code--no.  char,  to  insert. 

{  55} 

$F6/$06/ >Flg/$0 1 /  { 

TEST  [Fig] , 1 

If  pop  up  Fig  bit  is  } 

1 

(  60} 

$74 /<65— 62/  | 

JZ  C4 

{  62} 

$E8/>122— 65/  { 

MemW [CSeg: InsNumb]  :=  NumbChr; 

{  65} 

$F6/$06/>Flg/$10/{C4 :TEST  [Flq] , lOh 

IF  NumbChr  >  0  THEN  BEGIN  (Have  char,  to  insert.) 

{  70} 

$74/ <— 72 /  { 

JZ  JmpBiosl6 

MemL[CSeg: InsChr]  :=  LONG I NT (  TSRChrPtr  ) ; 

{  72} 

$F6/$C4/$EE/  { 

TEST  AH, OEEh 

If  request  is  not  a  } 

Mem[CSeg:Flg]  :=  Mem [CSeg : Fig]  OR  $10; 

{  75} 

$75/ <-77/  { 

JNZ  JmpBiosl6 

chr.  request,  exit.  ) 

( 

{ 

***  Insert  a  character.  } 

***  Pop  TSR  back  down--Restore  computer  to  previous  state. 

{  77} 

$58/  { 

POP  AX 

1  ... 

{  78} 

$53/  { 

PUSH  BX 

IF  NpxFlag  THEN  (Restore  co-prcssr  state.) 

{  79} 

$06/  { 

PUSH  ES 

} 

INLINE  (  $98/  $DD/$36/>NpxState  );  (WAIT  FSAVE  [NpxState]  ) 

{  80} 

$C4/$lE/>InsChr/  { 

LES  BX, [InsChr] 

PTR (ES, BX)  :=  InsChr;} 

{  84} 

$26/  { 

ES: 

Mem[BSeg:$17)  :=  {Restore  key 

lock  status.) 

{  85} 

$8A/$07/  { 

MOV  AL, [BX] 

} 

(Mem[BSeg:$17)  AND  $0F)  OR  (KeyLock  AND  $F0); 

{  87} 

$07/  { 

POP  ES 

(  88} 

$5B/  { 

IF  Mem [BSeg: VBiosOfs]  <>  VideoMode  THEN  BEGIN 

{  89} 

$F6/$C4/$01/  { 

TEST  AH, Olh 

IF  AH  IN  ($01, $11]  } 

AX  :=  VideoMode;  {Restore  video  mode.  } 

1  92} 

$B4/$00/  { 

MOV  AH, OOh 

THEN  ReportOnly;  ) 

Intr (  $10,  Regs  ) ; 

1  94} 

$75/ <114—96/  { 

JNZ  ReportOnly 

Set  Scan  code  to  0.  } 

{  96} 

$FE/$06/>InsChr/  { 

INC  [InsChr] 

Inc (  InsChr  ) ;  } 

AH  :=  1;  CX  :=  CursorMode;  {Restore  cursor  size.  } 

{100} 

$FF/$0E/>InsNumb/  { 

DEC  [InsNumb] 

Dec(  InsNumb  );  ) 

Intr (  $10,  Regs  ) ; 

{104} 

$75/<lll-106/  { 

JNZ  SkipReset 

IF  InsNumb  =  0  THEN  ) 

AH  :=  5;  AL  :=  CurrentPage;  {Restore  active  page.  ) 

{106} 

$80/$26/>Flg/$EF/  { 

AND  [Fig] , OEFh 

Clear  insert  chr  fig) 

Intr(  $10,  Regs  ); 

(111) 

$ IF/  {SkipReset: 

POP  DS 

AH  :=  2;  BH  :=  CurrentPage;  {Restore  cursor  positon.  } 

1112} 

$9D/  { 

POPF 

DX  :=  CursorArea [CurrentPage) ; 

{113} 

$CF  /  { 

IRET 

Intr(  $10,  Regs  );  (Restore  screen  image.  } 

Move(  Buffer,  PTR(  ScrnSeg,  MemoryOfs  )A,  ScreenSize  ); 

{114} 

$1F/  {ReportOnly: 

POP  DS 

Report  char,  ready.  } 

{115} 

$9D/  { 

POPF  /Restore  DS  and  FLAGS.) 

SwapVectors;  {Restore  non-T 

.P.  vectors.) 

{116} 

$50/  { 

PUSH  AX 

Clear  zero  flag  bit  } 

{117} 

$40/  { 

INC  AX 

to  indicate  a  } 

END;  (PopUp.) 

{118} 

$58/  ( 

POP  AX 

character  ready •  ) 

( 

{119} 

$CA/>0002/  { 

RETF  2  /Exit  &  discard  FLAGS  } 

*****  Printer  Functions: 

{ 

***  Interface  to  PopUpCode  Routine.  } 

FUNCTION  PrinterStatus:  BYTE;  {Returns  status  of  LPT1.} 

(122) 

$50/  {ToPopUp: 

PUSH  AX 

Save  AX.  } 

{  Definition  of  status  byte  bits  (1  &  2  are  not  used), 

if  set  then: 

{123} 

$FA/  { 

CLI 

Disable  interrupts.  } 

Bit:  —  7  —  - 6 -  —  5  —  —  4  — -  —  3 

—  —  0  — 

{124} 

$F6/$06/>UnSafe/$FF/ (TEST  [UnSafe] , OFFh  ; IF  UnSafe  <>  0  } 

Not  busy  Acknowledge  No  paper  Selected  I/O  Err.  Timed-out 

{129} 

$75/<177— 131/  { 

JNZ  PP2 

;  THEN  Return.  } 

1 

{131} 

$A0/>Flg/  { 

MOV  AL, [Fig] 

Set  in-use  bit;  clear} 

VAR  Regs  :  Registers; 

{134} 

$24/$FE/  ( 

AND  AL, OFEh 

pop  up  bit  of  Fig.  } 

{136} 

$  0C/ $02 /  { 

OR  AL,  2 

Fig  :=  (Fig  AND  $FE)  } 

WITH  Regs  DO  BEGIN 

{138} 

$A2/>Flg/  { 

MOV  [Fig] , AL 

OR  2;  } 

AH  :=  2;  DX  :=  0;  {Load  BIOS  function  and  printer  number.  ) 

{ 

* 'Switch  to  our  stack} 

Intr(  $17,  Regs  );  (Call  BIOS  printer  services 

1 

{141} 

$Al/>StkOfs/  { 

MOV  AX, [StkOfs] 

Load  top  of  our  stack} 

PrinterStatus  :=  AH;  {Return  with  printer  status 

byte.  } 

{144} 

$87 / $C4/  ( 

XCHG  AX, SP 

Exchange  it  with  } 

{146} 

$A3/>DosSp/  { 

MOV  [DosSp) , AX 

stk.ptr,  save  old  SP.} 

END;  (PrinterStatus.) 

{149} 

$8C/$16/>DosSs/  { 

MOV  [DosSs] , SS 

Save  old  SS.  } 

(153} 

$8E/$16/>StkSs/  { 

MOV  SS, [StkSs] 

Replace  SS  with  our  ) 

FUNCTION  PrinterOkay:  BOOLEAN;  {Returns  TRUE  if  printer  is  okay.  } 

1157} 

$FB/  ( 

STI 

SS.  Enable  interrupts} 

VAR  S  :  BYTE; 

{158} 

$9C/  { 

PUSHF 

Interrupt  call  to  pop) 

BEGIN 

1159} 

$FF/$lE/>PopUp/  ( 

CALL  FAR  [PopUp] 

S  :-  PrinterStatus; 

IF  ((S  AND  $10)  <>  0)  AND  ( (S  AND  $29)  =  0)  THEN 

{163} 

$FA/  { 

CLI  /Disable  interrupts.  } 

PrinterOkay  :=  TRUE 

{164} 

$8B/$26/>DosSp/  ( 

MCV  SP, [DosSp] 

Restore  stack  ptr  ) 

ELSE  PrinterOkay  :=  FALSE; 

{168} 

$8E/$16/>DosSs/  { 

MOV  SS, [ DosSs j 

SS:SP.  Clear  in-use  } 

{172} 

$80/$26/>Flg/$FD/  { 

AND  [Flq] , OFDh  /bit  of  Flq.  } 

*****  procedures  to  obtain  contents  of  saved  screen  image. 

{177} 

$FB/  { PP2 : 

1 

{178} 

$58/  { 

PROCEDURE  ScreenLine (  Row:  BYTE;  VAR  Line:  LineWords; 

{179} 

$C3  );  { 

VAR  Words :  BYTE  ) ; 

{180} 

END; 

Asm.}  {END  corresponds  to  12  bytes  of  code — used  for  storage} 

Words  :=  40;  {Determine  screen  line  size.) 
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IF  TSRMode  >  1  THEN  Words  :=  Words*2;  {Get  line's  ) 
Move(  Buffer [Pred(Row) *Words] ,  Line,  Words*2  );  (characters  and  ) 
ND;  (ScreenLine. )  {colors.  | 


FUNCTION  ScreenLineStr {  Row: 

VAR 

Words,  i  :  BYTE; 

LineWord  :  LineWords; 

Line  :  String80; 

BEGIN 

ScreenLine (  Row,  LineWord,  Words  ) 

Line  :=  "; 

FOR  i  :=  1  TO  Words  DO  Insert  (  LineWord [ i] .C,  Line, 
ScreenLineStr  :=  Line; 

END;  {Screenstring.) 

( 

*****  TSR  Installation  procedure. 

) 

PROCEDURE  TSRInstall (  TSRName:  STRING;  TSRFunc:  WordFuncs; 

ShiftComb:  BYTE;  KeyChr:  CHAR  ) ; 

CONST 

ScanChr  = 

CombChr  = 

VAR 

PlistPtr  :  "STRING; 

i,  j,  k  :  WORD; 

Regs  :  Registers; 

Comb,  ScanCode  :  BYTE; 

BEGIN 

IF  Ofs (  Asm  )  <>  0  THEN  EXIT; 


'+1234567890+ 
' RLCA" ' ; 


BYTE  ) :  String80;  (Returns  just  chars) 


Get  chars  &  attributes.  ) 
Move  characters  to  string) 


++QWERTYUIOP++++ASDFGHJKL+++++ZXCVBNM'  . 


MemW[CSeg:StkSs] 
MemW (CSeg : StkOf s ] 
MemL[ CSeg: Popup) 
TheirFunc 


{Offset  of  Asm  must  be  0) 
=  SSeg;  {Save  pointer  to  top  of  ) 

=  Sptr  +  562;  {TSR's  stack.  ) 

=  LONGINT (@PopUpCode) ;  {Save  PopUpCode  addr.  ) 
TSRFunc;  {&  their  TSR  func.  addr.) 

, TSRName  ); 


(Check  equipment  list  for  } 
{math  co-processor.  ) 
{Get  current  video  mode  ) 
{and  save  it  for  when  TSR  ) 
{is  activated.  ) 
{Get  current  cursor  size  ) 
{and  save  it  for  when  TSR  ) 
{is  activated.  ) 


Writeln (' Installing  Stay-Resident  program: 

{ 

*****  save  intercepted  interrupt  vectors:  $09,  $16,  $21,  $25,  $26. 

) 

GetlntVec (  $09,  POINTER {  MemL(CSeg:Bios9]  )  ); 

GetlntVec {  $16,  POINTER{  MemL[CSeg:Biosl6]  )  ); 

GetlntVec (  $21,  POINTER(  MemL[CSeg:Dos21)  )  ) 

GetlntVec {  $25,  POINTER(  MemL[CSeg:Dos25]  )  ) 

GetlntVec (  $26,  POINTER (  MemL[CSeg:Dos26]  )  ) 

{ 

*****  get  equipment  list  and  video  mode. 

) 

WITH  Regs  DO  BEGIN 
Intr(  $11,  Regs  ); 

NpxFlag  :=  (AL  AND  2)  =  2; 

AH  :=  15; 

Intr{  $10,  Regs  ); 

InitVideo  :=  AL; 

AH  :=  3;  BH  :=  0; 

Intr (  $10,  Regs  ); 

InitCMode  :=  CX; 

END;  {WITH  Regs) 

{ 

*****  Get  inf0-  on  buffer  for  saving  screen  image. 

) 

BuffSize  :=  SizeOf (  Buffer  ); 

TSRScrPtr  :=  @Buffer; 

( 

***  Determine  activation  key  combination. 

} 

Comb  :=  0;  i  :*  1; 

PlistPtr  :=  Ptr {  PrefixSeg,  $80  ); 

WHILE  i  <  Length (  PlistPtr"  )  DO  BEGIN 
IF  PlistPtr" (i)  =  '/'  THEN  BEGIN 
Inc(  i  ); 

j  :=  Post  UpCaset  PlistPtr" [i]  ),  CombChr  ); 

IF  (j  >  0)  AND  (j  <  5)  THEN  Comb  :=  Comb  OR  (1  SHL  Pred { j ) ) 
ELSE  IF  j  <>  0  THEN  BEGIN  (New  activation  char. 

Inc (  i  ) ;  k  :=  Succ(  i  ) ; 

IF  i  >  Length (PlistPtr")  THEN  KeyChr  :=  #0 
ELSE  BEGIN 

IF  ( (k  <=  Length (PlistPtr") )  AND  (PlistPtr" [k]  =  '"')) 

OR  (PlistPtr" [i]  <>  '"')  THEN  KeyChr  :=  PlistPtr" [i] 
ELSE  KeyChr  :=  #0; 

END;  {ELSE  BEGIN) 

END;  {ELSE  IF  ...  BEGIN) 

END;  {IF  PlistPtr" [ i ]  =  '/'  ) 

Inc(  i  ); 

END;  {WHILE  ...) 

IF  Comb  =  0  THEN  Comb  :=  ShiftComb, 

IF  Comb  =  0  THEN  Comb  :=  AltKey; 

ScanCode  :=  Pos {  UpCase(  KeyChr  ),  ScanChr  ); 

IF  ScanCode  <  2  THEN  BEGIN 
ScanCode  :=  2;  KeyChr  := 

END; 

Mem [CSeg :Shft)  :=  Comb;  {Store  shift  key  combination) 

Mem[CSeg:Key]  :=  ScanCode;  {and  scan  code.  ) 

Output  an  installation  message:  Memory  used  &  activation  code. 

Writeln (  'Memory  used  is  approximately  ', 

(  ($1000  +  Seg  (FreePtr")  -  PrefixSeg) /64.0) :7:1, '  K  (K=1024).'); 
Writeln ( 

'Activate  program  by  pressing  the  following  keys  simultaneously:'); 
IF  (Comb  AND  1)  <>  0  THEN  Write ('  [Right  Shift]'); 

IF  (Comb  AND  2)  <>  0  THEN  Write  (' 

IF  (Comb  AND  4)  <>  0  THEN  Write  (' 

IF  (Comb  AND  8)  <>  0  THEN  Write  (' 

Writeln)'  and  "',  KeyChr,  '".'); 


(Create  ptr  to  ) 
(parameter  list.  ) 
{Check  for  parameters.) 
{Process  parameter.  } 


} 


Use  default  combination.  ) 
(No  default,  use  [Alt]  key.) 

{Convert  char,  to) 
{scan  code.  ) 


[Left  Shift] ' ) ; 
[Ctrl]'); 
[Alt]'); 


Intercept  orig.  interrupt  vectors;  Then  exit  and  stay-resident. 


SetlntVec (  $21,  Ptr(  CSeg,  Our21  )  ) 

SetlntVec (  $25,  Ptr(  CSeg,  Our25  )  ) 

SetlntVec (  $26,  Ptr(  CSeg,  Our26  )  ) 

SetlntVec (  $16,  Ptr(  CSeg,  Ourl6  )  ) 

SetlntVec (  $09,  Ptr{  CSeg,  Our09  )  ) 

SwapVectors; 

MemW [CSeg: Unsafe]  :=  0; 

Keep (  0  )  ; 

END;  (TSRInstall.) 

END.  (TSRUnit . ) 


(Save  turbo  intr .vectors . ) 

(Allow  TSR  to  pop  up.  ) 

{Exit  and  stay-resident.  ) 

End  Listing 


K  E  R  M  I T 


Listing  One  (Text  begins  on  page  22.) 

MODULE  PCKermjit; 

FROM  Break  IMPORT 

DisableBreak,  EnableBreak; 

FROM  Terminal  IMPORT 

WriteString,  WriteLn,  Read; 

FROM  Shell  IMPORT 

dispOpts,  Options,  Dir,  Connect,  exit,  MainHelp; 

FROM  PAD  IMPORT 
Send,  Receive; 


Quit  :  BOOLEAN; 
ch  :  CHAR; 


BEGIN  (*  main  program  *) 

DisableBreak;  (*  dcn't  recognize  Control-C  *) 

WriteLn;  WriteLn; 

WriteString  ("Welcome  to  PCKermit  --  Mainframe  to  Micro  Communications"); 

WriteLn; 

dispOpts; 

Quit  :=  FALSE; 

REPEAT 

WriteLn;  WriteLn; 

WriteString  ("PCKermit  [0,  C,  D,  S,  R,  X,  ?] :  "); 

LOOP 

Read  (ch); 

CASE  CAP  (ch)  OF 
'O'  :  Options; 


'S' 

'R' 

'X' 


Connect ; 

Dir; 

Send; 
Receive; 
eXit  (Quit); 
MainHelp; 


EXIT 

EXIT 

EXIT 

EXIT 

EXIT 

EXIT 

EXIT, 


ELSE 

(*  ignore  *) 
END; 

END; 

UNTIL  Quit; 
EnableBreak; 

END  PCKermit . 


Listing  Two 

DEFINITION  MODULE  Shell; 


End  Listing  One 


(*  User  interface  for  Kermit  *) 


EXPORT  QUALIFIED 

dispOpts,  Options,  Dir,  Connect,  eXit,  MainHelp; 

PROCEDURE  dispOpts; 

(*  Display  communications  parameters  for  the  user  *) 

PROCEDURE  Options; 

(*  set  communications  options  *) 

PROCEDURE  Dir; 

(*  Displays  a  directory  *) 

PROCEDURE  Connect; 

(*  Terminal  mode  allows  connection  to  host  (possibly  through  MODEM)  *) 
PROCEDURE  exit  (VAR  q  :  BOOLEAN) ; 

(*  Allow  user  to  exit  program  after  prompting  for  confirmation  *) 
PROCEDURE  MainHelp; 

(*  help  menu  for  main  program  loop  *) 


End  Listing  Two 

Listing  Three 

DEFINITION  MODULE  PAD;  (*  Packet  Assembler/Disassembler  for  Kermit  *) 

EXPORT  QUALIFIED 

PacketType,  yourNPAD,  yourPADC,  yourEOL,  Send,  Receive; 

TYPE 

(*  PacketType  used  in  both  PAD  and  DataLink  modules  *) 

PacketType  =  ARRAY  [1..100]  OF  CHAR; 

VAR 

(*  yourNPAD,  yourPADC,  and  yourEOL  used  in  both  PAD  and  DataLink  *) 
yourNPAD  :  CARDINAL;  (*  number  of  padding  characters  *) 

yourPADC  :  CHAR;  (*  padding  characters  *) 

yourEOL  :  CHAR;  (*  End  Of  Line  —  terminator  *) 

PROCEDURE  Send; 

(*  Sends  a  file  after  prompting  for  filename  *) 

PROCEDURE  Receive; 

(*  Receives  a  file  (or  files)  *) 


End  Listing  Three 
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listing  Four 

DEFINITION  MODULE  Files;  (*  File  I/O  for  Kermit  *) 

PROCEDURE  Initialize; 

BEGIN 

FROM  FileSystem  IMPORT 

Init  (baudRate,  stopBits,  parityBit,  evenParity,  nbrOfBits,  OK); 

File; 

END  Initialize; 

EXPORT  QUALIFIED 

Status,  FileType,  Open,  Create,  CloseFile,  Get,  Put,  DoWrite; 

PROCEDURE  ClrScr; 

(*  Clear  the  screen,  and  home  the  cursor  *) 

TYPE 

BEGIN 

Status  =  (Done,  Error,  EOF) ; 

FileType  =  (Input,  Output); 

PROCEDURE  Open  (VAR  f  :  File;  name  :  ARRAY  OF  CHAR)  :  Status; 

(*  opens  an  existing  file  for  reading,  returns  status  *) 

SETREG  (AX,  3600H) ;  (*  function  6  =  scroll  or  clear  window  *) 

SETREG  (BX,  0700H);  (*  7  =  normal  screen  attribute  *) 

SETREG  (CX,  0000H);  (*  top  LH  of  screen  *) 

SETREG  (DX,  184FH) ;  (*  bottom  RH  of  screen  *) 

SWI  ( 1 OH ) ;  {*  call  bios  *) 

SETREG  (AX,  0200h) ;  (*  function  2  =  position  cursor  *) 

SETREG  (BX,  0000H) ;  (*  page  0  *) 

SETREG  (DX,  OOOOH) ;  (*  home  position  *) 

SWI  (10H);  (*  call  bios  *) 

PROCEDURE  Create  (VAR  f  :  File;  name  :  ARRAY  OF  CHAR)  :  Status; 

(*  creates  a  new  file  for  writing,  returns  status  *) 

PROCEDURE  CloseFile  (VAR  f  :  File;  Which  :  FileType)  :  Status; 

END  ClrScr; 

(*  closes  a  file  after  reading  or  writing  *) 

PROCEDURE  Get  (VAR  f  :  File;  VAR  ch  :  CHAR)  :  Status; 

PROCEDURE  CommHelp; 

(*  Reads  one  character  from  the  file,  returns  status  *) 

(*  help  menu  for  communications  options  *) 

BEGIN 

PROCEDURE  Put  (ch  :  CHAR) ; 

ClrScr; 

(*  Writes  one  character  to  the  file  buffer  *) 

WriteString  {"  Communications  Option  s"); 

WriteLn; 

PROCEDURE  DoWrite  (VAR  f  :  File)  :  Status; 

WriteString  ("  Help  Menu"); 

(*  Writes  buffer  to  disk  only  if  nearly  full  *) 

WriteLn;  WriteLn; 

END  Files. 

WriteString  ("set  Baud  rate  .  B"); 

WriteLn; 

End  Listing  Four 

WriteString  ("set  Parity  .  P"); 

WriteLn; 

WriteString  ("set  Word  length  .  W"); 

WriteLn; 

WriteString  ("set  Stop  bits  .  S"); 

Listing  Five 

WriteLn; 

WriteString  ("exit  .  X"); 

DEFINITION  MODULE  DataLink;  (*  Sends  and  Receives  Packets  for  PCKermit  *) 

WriteLn; 

END  CommHelp; 

FROM  PAD  IMPORT 

PacketType; 

PROCEDURE  dispOpts; 

EXPORT  QUALIFIED 

(*  Display  communications  parameters  for  the  user  *) 

BEGIN 

WriteLn; 

FlushUART,  SendPacket,  ReceivePacket; 

WriteString  ("Baud  rate  =  ");  WriteCard  (baudRate,  0); 

(*  ensure  no  characters  left  in  UART  holding  registers  *) 

WriteString  (" ;  "); 

IF  parityBit  THEN 

PROCEDURE  SendPacket  (s  :  PacketType) ; 

IF  evenParity  THEN 

(*  Adds  SOH  and  Checksum  to  packet  *) 

PROCEDURE  ReceivePacket  (VAR  r  :  PacketType)  :  BOOLEAN; 

WriteString  ("Odd  "); 

(*  strips  SOH  and  checksum  --  return  FALSE  if  timed  out  or  bad  checksum  *) 

END; 

ELSE 

END  DataLink. 

WriteString  ("No  "); 

END; 

End  Listing  Five 

WriteString  ("parity;  "); 

WriteCard  (nbrOfBits,  0) ; 

WriteString  ("  Data  bits;  "); 

IF  stopBits  =  1  THEN 

WriteString  ("One  stop  bit."); 

Listing  Six 

ELSE 

WriteString  ("Two  stop  bits."); 

END; 

IMPLEMENTATION  MODULE  Shell;  (*  User  interface  for  Kermit  *) 

WriteLn; 

END  dispOpts; 

FROM  SYSTEM  IMPORT 

AX,  BX,  CX,  DX,  SETREG,  SWI; 

PROCEDURE  Options; 

FROM  Exec  IMPORT 

(*  set  communications  options  *) 

DosCommand; 

VAR 

FROM  Terminal  IMPORT 

WriteString,  WriteLn,  KeyPressed,  Readstring; 

Quit  :  BOOLEAN; 

BEGIN 

TMPORT  Terminal;  ("  for  Terminal .Write  and  Terminal .Read  *) 

ClrScr; 

Quit  :=  FALSE; 

FROM  InOut  IMPORT 

dispOpts; 

WriteCard; 

REPEAT 

FROM  RS232lnt  IMPORT 

Init,  StartReading,  StopReading; 

WriteLn;  WriteLn; 

WriteString  ("Set  Communications  Options  [B,  P,  W,  S,  X,  ?] :  "); 

LOOP 

IMPORT  RS232lnt;  (*  for  RS232lnt .Write  and  RS232Int . BusyRead  *) 

Terminal .Read  (ch) ; 

CASE  CAP  (ch)  OF 

FROM  Strings  IMPORT 

'B'  :  Baud;  EXIT; 

Length,  Concat; 

1  ' P'  :  Parity;  EXIT; 

1  'W'  ;  Word;  EXIT; 

FROM  NumberConversion  IMPORT 

1  'S'  :  Stops;  EXIT; 

StringToCard; 

1  '?'  :  CommHelp;  EXIT; 

1  'X'  :  Quit  :=  TRUE;  EXIT; 

IMPORT  ASCII; 

ELSE 

(*  ignore  *) 

END; 

VAR 

END; 

baudRate  :  CARDINAL; 

IF  Quit  THEN 

stopBits  :  CARDINAL; 

ClrScr; 

parityBit  :  BOOLEAN; 

ELSE 

evenParity  :  BOOLEAN; 

Initialize; 

nbrOfBits  :  CARDINAL; 

dispOpts; 

OK  :  BOOLEAN; 

echo  :  (Off,  Local,  On) ; 

ch  :  CHAR; 

str  :  ARRAY  [0..10]  OF  CHAR; 
n  :  CARDINAL; 

END; 
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UNTIL  Quit; 

PROCEDURE  ConnectHelp; 

END  Options; 

{*  provide  help  while  in  connect  mode  *) 

BEGIN 

ClrScr; 

PROCEDURE  Baud; 

WriteString  ("LOCAL  COMMANDS: ") ;  WriteLn; 

(*  Allow  user  to  charge  the  bit  rate  of  the  communications  port  *) 

WriteString  ("AE  =  Echo  mode");  WriteLn; 

BEGIN 

WriteString  ("AL  =  Local  echo  mode");  WriteLn; 

WriteString  ("Baud  Rate?  [110  -  9600]:  "); 

WriteString  (,,AT  =  Terminal  mode  (no  echo)");  WriteLn; 

ReadString  (str); 

WriteString  ("AX  =  eXit  from  connect");  WriteLn; 

IF  Length  (str)  #  0  THEN 

WriteLn;  WriteLn; 

StringToCard  (str,  n,  OK) ; 

IF  OK  THEN 

END  ConnectHelp; 

CASE  n  OF 

110,  150,  300,  600,  1200,  2400,  4800,  9600  :  baudRate  :=  n; 

PROCEDURE  Connect; 

ELSE 

(*  Terminal  mode  allows  connection  to  host  (possibly  through  MODEM)  *) 

(*  do  nothing  *) 

END; 

VAR 

END; 

Input  :  BOOLEAN; 

END; 

END  Baud; 

BEGIN 

ConnectHelp; 

REPEAT 

PROCEDURE  Word; 

RS232Int .BusyRead  (ch,  Input); 

(*  Allow  user  to  change  the  word  length  of  the  communications  port  *) 

IF  Input  THEN 

BEGIN 

IF  ((ch  >=  40C)  AND  (ch  <  177C)) 

WriteString  ("Word  Length?  (7,  8]:  "); 

OR  (ch  =  ASCII. cr)  OR  (ch  =  ASCII. If)  OR  (ch  =  ASCII. bs)  THEN 

ReadString  (str); 

Terminal .Write  (ch) ; 

IF  Length  (str)  #  0  THEN 

END; 

StringToCard  (str,  n,  OK); 

IF  echo  =  On  THEN 

IF  OK  AND  (n  IN  (7,  8))  THEN 

RS232Int. Write  (ch) ; 

nbrOfBits  :=  n; 

END; 

END; 

END; 

END; 

END  Word; 

IF  KeyPressedO  THEN 

Terminal. Read  (ch) ; 

IF  ch  =  ASCII. enq  THEN  (*  Control-E  *) 

PROCEDURE  Parity; 

echo  :=  On; 

(*  Allow  user  to  change  the  parity  bit  of  the  communications  port  *) 

ELSIF  ch  =  ASCII. ff  THEN  (*  Control-L  *) 

BEGIN 

echo  :=  Local; 

WriteString  ("Parity?  [None,  Even,  Odd]:  "); 

ELSIF  ch  =  ASCII. dc4  THEN  (*  Control-T  *) 

ReadString  (str); 

echo  :=  Off; 

IF  Length  (str)  #  0  THEN 

ELSIF  ((ch  >=  40C)  AND  (ch  <  177C) ) 

CASE  CAP  (str [0] )  OF 

OR  (ch  =  ASCII. EOL)  OR  (ch  =  ASCII. bs)  THEN 

'N'  :  parityBit  :=  FALSE; 

IF  ch  =  ASCI I. EOL  THEN 

I  'E'  :  parityBit  :=  TRUE;  evenParity  :=  TRUE; 

RS232Int. Write  (ASCII. cr); 

|  'O'  :  parityBit  :=  TRUE;  evenParity  :=  FALSE; 

RS232Int. Write  (ASCII. If); 

ELSE 

ELSE 

(*  no  action  *) 

RS232Int. Write  (ch) ; 

END; 

END; 

END; 

IF  (echo  =  On)  OR  (echo  =  Local)  THEN 

END  Parity; 

Terminal .Write  (ch) ; 

END; 

END; 

PROCEDURE  Stops; 

END; 

(*  Allow  user  to  change  the  number  of  stop  bits  *) 

UNTIL  ch  =  ASCII. can;  (*  Control-X  *) 

BEGIN 

END  Connect; 

WriteString  ("Stop  Bits?  [1,  2]:  "); 

ReadString  (str); 

IF  Length  (str)  #  0  THEN 

PROCEDURE  eXit  (VAR  q  :  BOOLEAN); 

StringToCard  (str,  n,  OK); 

(*  Allow  user  to  exit  program  after  prompting  for  confirmation  *) 

IF  OK  AND  (n  IN  (1,  2))  THEN 

BEGIN 

stopBits  :=  n; 

WriteString  ("Exit  PCKermit?  [Y/N] :  "); 

END; 

Terminal. Read  (ch) ; 

END; 

IF  CAP  (ch)  =  'Y'  THEN 

END  Stops; 

Terminal .Write  ( ' Y ' ) ; 

StopReading;  (*  turn  off  the  serial  port  *) 

q  :=  TRUE; 

PROCEDURE  Dir; 

ELSE 

Terminal .Write  ( ' N ' ) ; 

VAR 

END; 

done,  gotFN  :  BOOLEAN; 

WriteLn; 

path  :  ARRAY  [0..60]  OF  CHAR; 

END  eXit; 

filename  :  ARRAY  [0..20]  OF  CHAR; 
i,  j,  k  :  INTEGER; 

PROCEDURE  MainHelp; 

BEGIN 

(*  help  menu  for  main  program  loop  *) 

filename  :=  (*  in  case  no  directory  change  *) 

BEGIN 

WriteString  ("Path?  (*.*):  "); 

ClrScr; 

ReadString  (path) ; 

WriteString  ("  PCKermit  Help  Men  u");  WriteLn; 

i  :=  Length  (path); 

WriteLn; 

IF  i  #  0  THEN 

WriteString  ("set  communications  Options  .  O'); 

gotFN  :=  FALSE; 

WriteLn; 

WHILE  (i  >=  0)  AND  (path [ i ]  #  '\')  DO 

WriteString  ("Connect  to  host  .  C"); 

IF  path [i]  =  '  . '  THEN 

WriteLn; 

gotFN  :=  TRUE; 

WriteString  ("Directory  .  D"); 

END; 

WriteLn; 

DEC  (i) ; 

WriteString  ("Send  a  file  .  S"); 

END; 

WriteLn; 

IF  gotFN  THEN 

WriteString  ("Receive  a  file  .  R"); 

j  :=  i  +  If 

WriteLn; 

k  :=  0; 

WriteString  ("eXit  .  X"); 

WHILE  path[ j]  #  0C  DO 

WriteLn;  WriteLn; 

filename [k]  :=  path [ j ] ; 

WriteString  ("To  establish  connection  to  Host:");  WriteLn; 

INC  (k);  INC  (j); 

WriteString  ("  -Use  Connect  Mode");  WriteLn; 

END; 

WriteString  ("  -Dial  Host  (AT  command  set?)");  WriteLn; 

filename [k]  :=  0C; 

WriteString  ("  -Log  On  to  Host");  WriteLn; 

IF  (i  =  -1)  OR  ( (i  =  0)  AND  (path[0]  =  ' \' ))  THEN 

WriteString  ("  -Issue  Send  (or  Receive)  command");  WriteLn; 

INC  (i); 

WriteString  {"  -Return  to  main  menu  (AX)");  WriteLn; 

END; 

WriteString  ("  -Issue  Receive  (or  Send)  command");  WriteLn; 

path[i]  :=  QC; 

WriteLn; 

END; 

END  MainHelp; 

END; 

IF  Length  (path)  #  0  THEN 

DosCommand  ( "CHDIR" ,  path,  done); 

BEGIN  (*  module  initialization  *) 

END; 

ClrScr; 

IF  Length  (filename)  =  0  THEN 

baudRate  :=  1200; 

filename  := 

stopBits  :=  1; 

END; 

parityBit  :=  TRUE; 

Concat  (filename,  ”/w" ,  filename); 

evenParity  :=  TRUE; 

ClrScr; 

DosCommand  ("DIR",  filename,  done); 

(continued  on  page  86) 

END  Dir; 
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Listing  Six  (Listing  continued,  text  begins  on  page  22.) 

Initialize; 

StartReading;  (*  turn  on  the  serial  port  *) 
echo  :=  Off; 

END  Shell. 

End  Listing  Six 


Listing  Seven 

IMPLEMENTATION  MODULE  PAD;  (*  Packet  Assembler/Disassembler  for  Kermit  *) 
FROM  InOut  IMPORT 

Write,  WriteString,  Writelnt,  WriteHex,  WriteLn; 

FROM  Terminal  IMPORT 

ReadString,  Read,  KeyPressed; 

FROM  Strings  IMPORT 
Length; 

FROM  BitByteOps  IMPORT 
ByteXcr; 

FROM  FileSystem  IMPORT 
File; 


sP [ 3 ]  :=  'E';  (*  E-type  packet  *) 

sP [4]  :=  'R';  (*  error  message  starts  *) 

sP [5]  :=  'e'; 

sP [6]  :=  'm'; 

sP [7]  :=  'o'; 

sP [8]  :=  't'; 

sP [9]  :=  'e'; 

sP  [10]  :=  '  '; 

sP  [  11 ]  :=  'A' ; 

sP  [12]  :=  'b'; 

sP [13]  :=  'o'; 

sP [14 ]  :=  'r'; 

sP[15]  :=  't'; 

sP [16]  :=  CC; 

SendPacket  (sP) ; 

END  TellError; 


PROCEDURE  ShowError  (p  :  PacketType) ; 

(*  Output  contents  of  error  packet  to  the  screen  *) 

VAR 

i  :  INTEGER; 

BEGIN 

FOR  i  :=  4  TO  UnChar  (p[l ] )  DO 
Write  (p [ i ] ) ; 

END; 

WriteLn; 

END  ShowError; 


FROM  Files  IMPORT 

Status,  FileType,  Open,  Create,  CloseFile,  Get,  Put,  DoWrite; 
FROM  DataLink  IMPORT 

FlushUART,  SendPacket,  ReceivePacket; 

IMPORT  ASCII; 


CONST 

myMAXL  »  94; 
my TIME  =  10; 
myNPAD  =  0; 
my P ADC  =  0C; 
myEOL  =  0C; 
myQCTL  =  '#'; 
myQBIN  =  '&'; 

myCHKT  =  '1';  (*  one  character  checksum  *) 

MAXtrys  =  5; 


PROCEDURE  youlnit  (type  :  CHAR) ; 

(*  I  initialization  YOU  for  Send  and  Receive  *) 
BEGIN 

sP [ 1 ]  :=  Char  (11);  (*  Length  *) 

sP[2]  :=  Char  (0);  (*  Sequence  *) 

sP [3]  :=  type; 

sP [ 4 ]  :=  Char  (myMAXL); 

sP [5]  :=  Char  (myTIME) ; 

sP [ 6]  :=  Char  (myNPAD); 

sP [7]  :=  CHAR  (ByteXor  (myPADC,  100C) ) ; 

sP [8]  :=  Char  (ORD  (myEOL)); 

sP [9]  :=  myQCTL; 

sP [10]  :=  myQBIN; 

sP [ 11 )  :=  myCHKT; 

sP  [12]  :=  0C;  (*  terminator  *) 

SendPacket  (sP); 

END  youlnit; 


(*  From  Definition  Module: 

PacketType  =  ARFAY  [1 .  .100]  OF  CHAR; 
*) 

PathnameType  =  ARRAY  [0..40]  OF  CHAR; 


yourMAXL  :  INTEGER;  (*  maximum  packet  length  —  up  to  94  *) 
yourTIME  :  INTEGER;  (*  time  out  —  seconds  *) 

(*  From  Definition  Module 


yourNPAD 
yourPADC 
yourEOL 
*) 


CHAR; 

CHAR; 


(*  number  of  padding  characters 
padding  characters  *) 

End  Of  Line  --  terminator  *) 


yourQCTL 

yourQBIN 

yourCHKT 


CHAR 
CHAR 
CHAR 
File; 

sFname,  rFname 
sP,  rP  :  PacketType 
sSeq,  rSeq  :  INTEGER; 


(*  character  for  quoting  controls  ' 
(*  character  for  quoting  binary 
(*  check  type  —  1  =  checksum,  etc. 
(*  files  being  sent/received  *) 
PathnameType; 

(*  packets  sent/received  *) 

(*  sequence  numbers  *) 


PktNbr  :  INTEGER;  (*  actual  packet  number  —  no  repeats  up  to  32,000 


PROCEDURE  Char  (c  :  INTEGER)  :  CHAR; 

(*  converts  a  number  0-94  into  a  printable  character  *) 
BEGIN 

RETURN  (CHR  (CARDINAL  (ABS  (c)  +  32))); 

END  Char; 


PROCEDURE  UnChar  (c  :  CHAR)  :  INTEGER; 

(*  converts  a  character  into  its  corresponding  number  *) 
BEGIN 

RETURN  (ABS  (INTEGER  (ORD  (c) )  -  32)); 

END  UnChar; 


PROCEDURE  Aborted (i  :  BOOLEAN; 

VAR 

ch  :  CHAR; 

BEGIN 

IF  KeyPressed ()  THEN 
Read  (ch) ; 

IF  ch  =  033C  THEN  (*  Escape  *) 
RETURN  TRUE; 

END; 

END; 

RETURN  FALSE; 

END  Aborted; 


PROCEDURE  mylnit; 

(*  YOU  initialize  ME  for  Send  and  Receive  *) 
VAR 

len  :  INTEGER; 


len  :=  UnChar  (rP[l|); 
IF  len  >=  4  THEN 

yourMAXL  :=  UnChar 
ELSE 

yourMAXL  :=  94; 

END; 

IF  len  >=  5  THEN 

yourTIME  :=  UnChar 
ELSE 


yourTIME  :=  10; 
END; 

IF  len  >=  6  THEN 

yourNPAD  :=  UnChar 
ELSE 


(rP [ 4] )  ; 


(rP [5] )  ; 


(rP [ 6] )  ; 


yourNPAD  :=  0; 

END; 

IF  len  >=  7  THEN 

yourPADC  :=  CHAR  (ByteXor  ( rP [ 7 ] ,  100C) ) ; 
ELSE 


yourPADC  :=  0C; 

END; 

IF  len  >=  8  THEN 

yourEOL  :=  CHR  (UnChar  (rP  [ 8 ] ) ) ; 
ELSE 


yourEOL  :=  0C; 

END; 

IF  len  >=  9  THEN 

yourQCTL  :=  rP [ 9 ] ; 
ELSE 


yourQCTL  :=  0C; 

END; 

IF  len  >=  10  THEN 
yourQBIN  :=  rP [ 10 ] ; 

ELSE 

yourQBIN  :=  0C; 

END; 

IF  len  >=  11  THEN 

yourCHKT  :=  rP [ 1 1 ] ; 

IF  yourCHKT  #  myCHKT  THEN 
yourCHKT  :=  '1'; 

END; 

ELSE 


yourCHKT  :=  '1'; 
END; 

END  mylnit; 


PROCEDURE  TellError  (Seq  :  INTEGER); 
(*  Send  error  packet  *) 

BEGIN 

sF [1 ]  :=  Char  (15) ; 
sP [-21  :=  Char  (Seq); 


PROCEDURE  Sendlnit; 
BEGIN 

youlnit  ('S'); 
END  Sendlnit; 
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IF  GetAckO  THEN 

PROCEDURE  SendFileName; 

mylnit; 

RETURN  TRUE; 

VAR 

ELSE 

i-  j  : 

INTEGER; 

RETURN  FALSE; 

END; 

BEGIN 

END  GetlnitAck; 

(*  send  file  name  *) 

i  :=  4 

j  :=  0; 

WHILE 

sFname [j]  #  0C  DO 

PROCEDURE  Send; 

sP[ 

]  : =  sFname [ j ] ; 

(*  Sends  a  file  after  prompting  for  filename  *) 

INC 

(i);  INC  (j); 

END; 

VAR 

SP[1] 

=  Char  ( j  +  3) ; 

ch  :  CHAR; 

sP  [2 

=  Char  (sSeq); 

i  :  INTEGER; 

sP  [3] 

=  'F';  (*  filename  packet  *) 

sP[i) 

=  0C; 

BEGIN 

SendPacket  (sP); 

WriteString  ("Send:  (filename?):  "); 

END  SendFileName; 

Readstring  (sFname) ; 

WriteLn; 

IF  Length  (sFname)  =  0  THEN 

PROCEDURE  SendEOF; 

RETURN; 

BEGIN 

END; 

sP  [1] 

=  Char  (3) ; 

IF  Open  (sF,  sFname)  #  Done  THEN 

sP  [2] 

=  Char  (sSeq); 

WriteString  ("No  such  file:  ");  WriteString  (sFname); 

sP  [3] 

=  ' Z' ;  (*  end  of  file  *) 

WriteLn; 

sP  [4] 

=  0C; 

RETURN; 

SendPacket  { s P ) ; 

END; 

END  SendEOF; 

WriteString  ("(<ESC>  to  abort  file  transfer.)"); 

WriteLn;  WriteLn; 

FlushUART; 

PROCEDURE  SendEOT; 

sSeq  :=  0;  PktNbr  :=  0; 

BEGIN 

Sendlnit;  (*  my  configuration  information  *) 

sP[l) 

=  Char  (3); 

IF  NOT  GetlnitAckO  THEN  (*  get  your  configuration  information  *) 

SP  [2] 

=  Char  (sSeq); 

WriteString  ("Excessive  Errors...");  WriteLn; 

sP  [3] 

=  'B';  (*  break  --  end  of  transmit  *) 

RETURN; 

SP  (4) 

=  0C; 

END; 

SendPacket  (sP); 

END  SendEOT; 

SendFileName; 

PROCEDURE  GetAckO  :  BOOLEAN; 

IF  NOT  GetAckO  THEN 

(*  Look  for  acknowledgement  —  retry  on  timeouts  or  NAKs  *) 

WriteString  ("Excessive  Errors...");  WriteLn; 

RETURN; 

VAR 

END; 

Type  : 

CHAR; 

Seq  :  INTEGER; 

(*  send  file  *) 

retrys 

:  INTEGER; 

i  :=  4; 

AckOK 

BOOLEAN; 

LOOP 

IF  Aborted ()  THEN 

BEGIN 

TellError  (sSeq) ; 

WriteString  ("Sent  Packet  #"); 

RETURN; 

Writelnt  (PktNbr,  5); 

END; 

WriteString  ("  (ID:  ");  WriteHex  (sSeq,  4); 

IF  Get  (sF,  ch)  =  EOF  THEN  (*  send  current  packet  &  terminate  *) 

WriteString  ("h)"); 

sP ( 1 ]  :=  Char  (i  -  1) ; 

WriteLn; 

sP (2 ]  :=  Char  (sSeq); 

sP(3)  :=  'D';  (*  data  packet  *) 

retrys 

:=  MAXtrys; 

sP(ij  :=  0C;  (*  indicate  end  of  packet  *) 

LOOP 

SendPacket  (sP); 

IF  Aborted ()  THEN 

IF  NOT  GetAckO  THEN 

TellError  (sSeq) ; 

WriteString  ("Excessive  Errors...");  WriteLn; 

RETURN  FALSE; 

RETURN; 

END 

END; 

IF 

ReceivePacket  (rP) )  THEN 

SendEOF; 

Seq  :=  UnChar  (rP[2]); 

IF  NOT  GetAckO  THEN 

Type  : =  rP ( 3 ] ; 

WriteString  ("Excessive  Errors...");  WriteLn; 

F  (Seq  =  sSeq)  AND  (Type  =  'Y')  THEN 

RETURN; 

AckOK  :=  TRUE; 

END; 

ELSIF  (Seq  =  (sSeq  +  1)  MOD  64)  AND  (Type  =  'N' )  THEN 

SendEOT; 

AckOK  :=  TRUE;  (*  NAK  for  (n  +  1)  taken  as  ACK  for  n  *) 

IF  NOT  GetAckO  THEN 

ELSIF  Type  =  'E'  THEN 

WriteString  ("Excessive  Errors ...") ;  WriteLn; 

ShowError  (rP); 

RETURN; 

AckOK  :=  FALSE; 

END; 

retrys  :=  0; 

EXIT; 

ELSE 

AckOK  :=  FALSE; 

END; 

END; 

IF  i  >=  (yourMAXL  -  4)  THEN  {*  send  current  packet  *) 

ELSE 

sP ( 1]  :=  Char  (i  -  1); 

AckOK  :=  FALSE; 

sP [ 2 ]  :=  Char  (sSeq) ; 

END 

sP(3]  :=  'D'; 

IF  AckOK  OR  (retrys  =  0)  THEN 

sP[i]  :=  0C; 

EXIT; 

SendPacket  (sP); 

ELSE 

IF  NOT  GetAckO  THEN 

WriteString  ("Resending  Packet  #"); 

WriteString  ("Excessive  Errors...");  WriteLn; 

Writelnt  (PktNbr,  5) ; 

RETURN; 

WriteString  {"  (ID:  ");  WriteHex  (sSeq,  4); 

END; 

WriteString  ("h)"); 

i  :=  4; 

WriteLn; 

END; 

DEC  (retrys); 

FlushUART; 

(*  add  character  to  current  packet  --  update  count  *) 

IF  ch  >  177C  THEN  (*  must  be  quoted  (QBIN)  and  altered  *) 

END 

(*  toggle  bit  7  to  turn  it  off  *) 

END; 

ch  :=  CHAR  (ByteXor  (ch,  2000); 
sP[i]  :=  my QBIN;  INC  (i); 

IF  AckOK  THEN 

END; 

INC 

(PktNbr) ; 

IF  (ch  <  40C)  OR  (ch  =  177C)  THEN  (*  quote  (QCTL)  and  alter  *) 

sSeq  :=  (sSeq  +  1)  MOD  64; 

(*  toggle  bit  6  to  turn  it  on  *) 

RETURN  TRUE; 

ch  :=  CHAR  (ByteXor  (ch,  100C) ) ; 

ELSE 

sP [ i]  :=  myQCTL;  INC  (i); 

RETURN  FALSE; 

END; 

END; 

IF  (ch  =  myQCTL)  OR  (ch  =  myQBIN)  THEN  (*  must  send  it  quoted  *) 

END  GetAck; 

sP [ i J  :=  myQCTL;  INC  (i); 

END; 

sP [i]  :=  ch;  INC  (i); 

PROCEDURE  GetlnitAckO  :  BOOLEAN; 

END;  (*  loop  *) 

(*  configuration  for  remote  station  *) 

BEGIN 

IF  CloseFile  (sF,  Input)  #  Done  THEN 

WriteString  ("Problem  closing  source  file...");  WriteLn; 
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END; 

TYPE 

)ND  Send; 

HeaderType  =  (name,  eot,  fail); 

PROCEDURE  ReceiveHeader ()  :  HeaderType; 

PROCEDURE  Receiveln.it  ()  :  BOOLEAN; 

(*  receive  the  filename  --  alter  for  local  conditions,  if  necessary  *) 

(*  receive  my  initialization  information  from  you  *) 

VAR 

VAR 

i,  j,  k  :  INTEGER; 

RecOK  :  BOOLEAN; 

RecOK  :  EOOLEAN ; 

errors  :  INTEGER; 

errors  :  INTEGER; 

BEGIN 

BEGIN 

errors  :=  0; 

errors  :=  0; 

LOOP 

LOOP 

IF  Aborted!)  THEN 

RecOK  :=  ReceivePacket  (rP)  AND  ( < rP [ 3 ]  =  ' F' )  OR  ( rP [ 3 ]  =  'B')); 

TellError  (rSeq) ; 

IF  errors  =  MAXtrys  THEN 

RETURN  FALSE; 

RETURN  fail; 

END; 

ELSIF  RecOK  AND  (rP[3]  =  'F')  THEN 

RecOK  :=  (ReceivePacket  ( rP ) )  AND  ( rP [ 3 )  =  'S'); 

i  :=  4;  (*  data  starts  here  *) 

IF  RecOK  OR  (errors  =  MAXtrys)  THEN 

j  :=  0;  (*  beginning  of  filename  string  *) 

EXIT; 

WHILE  (ValidFileChar  (rP [ i ] ) )  AND  (j  <  8)  DO 

ELSE 

rFname( j]  :=  rP [i] ; 

INC  (errors); 

INC  (i);  INC  (j); 

SendNak; 

END; 

END; 

REPEAT 

END; 

INC  (i); 

UNTIL  (ValidFileChar  ( rP  [ i ) ) )  OR  (rP[i]  =  0C) ; 

IF  RecOK  THEN 

rFname(j)  :=  INC  (j); 

mylnit; 

k  :=  0; 

RETURN  TRUE; 

WHILE  (ValidFileChar  (rP [ i ) ) )  AND  (k  <  3)  DO 

ELSE 

rFname [ j  +  k )  : =  rP  [  i ) ; 

RETURN  FALSE; 

INC  (i);  INC  (k); 

END; 

END; 

END  Receivelnit; 

rFname [j  +  k]  :=  0C; 

WriteString  ("Filename  =  ");  WriteString  (rFname);  WriteLn; 

RETURN  name; 

PROCEDURE  SendlnitAck; 

ELSIF  RecOK  AND  (rP ( 3 ]  =  ' B'  )  THEN 

(*  acknowledge  your  initialization  of  ME  and  send  mine  for  YOU  *) 

RETURN  eot; 

BEGIN 

ELSE 

WriteString  ("Received  Packet  #"); 

INC  (errors); 

Writelnt  (PktNbr,  5); 

SendNak; 

WriteString  ("  (ID:  ");  WriteHex  (rSeq,  4); 

END; 

WriteString  ("h)"); 

END; 

WriteLn; 

END  ReceiveHeader; 

INC  (PktNbr); 

rSeq  :=  (rSeq  +  1)  MOD  64; 

youlnit  ('Y'); 

PROCEDURE  SendNak; 

END  SendlnitAck; 

BEGIN 

WriteString  ("Requesting  Repeat  of  Packet  #"); 

Writelnt  (PktNbr,  5); 

PROCEDURE  ValidFileChar  (VAR  ch  :  CHAR)  :  BOOLEAN; 

WriteString  ("  (ID:  ");  WriteHex  (rSeq,  4); 

(*  checks  if  character  is  one  of  'A'..'Z',  '0'..'9',  makes  upper  case  *) 

WriteString  ("h)"); 

BEGIN 

WriteLn; 

ch  :=  CAP  (ch); 

FlushUART; 

RETURN  ((ch  >=  'A')  AND  (ch  <=  'Z'))  OR  ( (ch  >=  '0')  AND  (ch  <=  '9')); 

sP [ 1 )  :=  Char  (3) ;  (*  LEN  *) 

END  ValidFileChar; 

sP [ 2 j  :=  Char  (rSeq) ; 

KERMIT 


Listing  Seven  (Listing  continued,  text  begins  on  page  22.) 

sP[3]  :=  'N';  (*  negative  acknowledgement  *) 

WriteString  ("Unable  to  open  file:  "); 

WriteString  (rFname);  WriteLn; 

SendPacket  (sP); 

RETURN; 

END  SendNak; 

ELSE 

PktNbr  :=  1; 

EOF  :=  FALSE; 

PROCEDURE  SendAck  (Seq  :  INTEGER); 

END; 

BEGIN 

1  fail  :  WriteString  ("Excessive  Errors...");  WriteLn; 

IF  Seq  #  rSeq  THEN 

RETURN; 

WriteString  ("Duplicate  Packet  "); 

END; 

ELSE 

SendAck  (rSeq) ;  (*  acknowledge  for  name  or  eot  *) 

WriteString  ("Received  Packet  #");  Writelnt  (PktNbr,  5); 

WHILE  NOT  EOF  CO 

rSeq  :=  (rSeq  +  1)  MOD  64; 

IF  Aborted ()  THEN 

INC  (PktNbr); 

TellError  (rSeq); 

RETURN; 

WriteString  ("  (ID:  ");  WriteHex  (Seq,  4); 

END; 

WriteString  ("h)"); 

IF  ReceivePacket  (rP)  THEN 

WriteLn; 

Seq  :=  UnChar  (rP  [2] ) ; 

sP [ 1)  :=  Char  (3); 

Type  : =  rP ( 3 ] ; 

sP [2)  :=  Char  (Seq) ; 

IF  Type  =  'Z'  THEN 

sP[3]  :=  'Y';  (*  acknowledgement  *) 

EOF  :=  TRUE; 

IF  CloseFile  (rF,  Output)  #  Done  THEN 

SendPacket  (sP); 

WriteString  ("Error  closing  file:  "); 

END  SendAck; 

WriteString  (rFname);  WriteLn; 

RETURN; 

END; 

PROCEDURE  Receive; 

SendAck  (rSeq); 

(*  Receives  a  file  (or  files)  *) 

ELSIF  Type  =  'E'  THEN 

ShowError  (rP)  ; 

VAR 

RETURN; 

ELSIF  (Tvpe  =  'D')  AND  ((Seq  +  1)  MOD  64  =  rSeq)  THEN 

(*  discard  duplicate  packet,  and  Ack  anyway  *) 

SendAck  (Seq) ; 

EOF,  EOT,  QBIN  :  BOOLEAN; 

ELSIF  (Tvpe  =  'D')  AND  (Seq  =  rSeq)  THEN 

errors  :  INTEGER; 

(*  put  packet  into  file  buffer  *) 

l  :=  4;  (*  first  data  in  packet  *) 

BEGIN 

WHILE  rP[i]  #  0C  DO 

WriteString  ("Ready  to  receive  file (s) . . . ") ;  WriteLn; 

ch  :=  rP  [  i ) ;  INC  (i); 

WriteString  (”(<ESC>  to  abort  file  transfer.)"); 

IF  ch  =  yourQBIN  THEN 

WriteLn;  WriteLn; 

ch  :=  rP  [i] ;  INC  (i)  ; 

FlushUART; 

QBIN  :=  TRUE; 

rSeq  :=  0;  PktNbr  :=  0; 

ELSE 

IF  NOT  Receivelnit ()  THEN  (*  your  configuration  information  *) 

QBIN  :=  FALSE; 

WriteString  ("Excessive  Errors...");  WriteLn; 

END; 

RETURN; 

IF  ch  =  yourQCTL  THEN 

ch  :=  rP  [ i  ]  ;  INC  (i)  ; 

SendlnitAck;  (*  send  my  configuration  information  *) 

IF  (ch  #  yourQCTL)  AND  (ch  #  yourQBIN)  THEN 

EOT  :=  FALSE; 

ch  :=  CHAR  (ByteXor  (ch,  100C) ) ; 

WHILE  NOT  EOT  DO 

END; 

IF  Aborted l)  THEN 

END; 

TellError  (rSeq); 

IF  QBIN  THEN 

RETURN; 

ch  :=  CHAR  (ByteXor  (ch,  2000); 

END; 

END; 

CASE  ReceiveHeader ()  OF 

Put  (ch); 

eot  :  EOT  :=  TRUE;  EOF  :=  TRUE; 

END; 
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(*  write  file  buffer  to  disk  *) 

buffer  =  ARRAY  [1..512]  OF  CHAR; 

IF  DoWnte  (rF)  #  Done  THEN 

VAR 

WriteString  ("Error  writing  to  file:  "); 

inBuf,  outBuf  :  buffer; 

WriteString  (rFnarae) ;  WriteLn; 

inP,  outP  :  CARDINAL;  (*  buffer  pointers  *) 

RETURN; 

read,  written  :  CARDINAL;  (*  number  of  bytes  read  or  written  *) 

END; 

errors  :=  0; 

SendAck  (rSeq); 

(*  by  ReadNBytes  or  WriteNBytes  *) 

ELSE 

PROCEDURE  Open  (VAR  f  :  File;  name  :  ARRAY  OF  CHAR)  :  Status; 

INC  (errors); 

(*  opens  an  existing  file  for  reading,  returns  status  *) 

IF  errors  =  MAXtrys  THEN 

BEGIN 

WriteString  ("Excessive  errors...");  WriteLn; 

Lookup  (f,  name,  FALSE); 

RETURN; 

IF  f.res  =  done  THEN 

ELSE 

inP  :=  0;  read  :=  0; 

SendNak; 

RETURN  Done; 

END; 

ELSE 

END; 

RETURN  Error; 

ELSE 

END; 

INC  (errors); 

IF  errors  =  MAXtrys  THEN 

END  Open; 

WriteString  ("Excessive  errors...");  WriteLn; 

RETURN; 

PROCEDURE  Create  (VAR  f  :  File;  name  :  ARRAY  OF  CHAR)  :  Status; 

ELSE 

(*  creates  a  new  file  for  writing,  returns  status  *) 

SendNak; 

END; 

VAR 

END; 

ch  :  CHAR; 

END; 

END; 

BEGIN 

END  Receive; 

Lookup  (f,  name,  FALSE);  (*  check  to  see  if  file  exists  *) 

IF  f.res  =  done  THEN 

Close  (f); 

BEGIN  (*  module  initialization  *) 

WriteString  ("File  exists!  Overwrite?  ( Y/N ) :  "); 

yourEOL  :=  ASCII. cr; 

Read  (ch);  Write  (ch);  WriteLn; 

yourNPAD  :=  0; 

IF  CAP  (ch)  =  'Y'  THEN 

yourPADC  :=  0C; 

Delete  (name,  f); 

END  PAD. 

Close  (f); 

ELSE 

RETURN  Error; 

END; 

END; 

Lookup  (f,  name,  TRUE); 

IF  f.res  =  done  THEN 

Listing  Eight 

outP  :=  0; 

RETURN  Done; 

ELSE 

IMPLEMENTATION  MODULE  Files;  (*  File  I/O  for  Hermit  *) 

RETURN  Error; 

END; 

FROM  FileSystem  IMPORT 

END  Create; 

File,  Response,  Delete,  Lookup,  Close,  ReadNBytes,  WriteNBytes; 

FROM  InOut  IMPORT 

PROCEDURE  CloseFile  (VAR  f  :  File;  Which  :  FileType)  :  Status; 

Read,  WriteString,  WriteLn,  Write; 

(*  closes  a  file  after  reading  or  writing  *) 

BEGIN 

FROM  SYSTEM  IMPORT 

written  :=  outP; 

ADR,  SIZE; 

(continued  on  page  92) 

TYPE 

KERMIT 


Listing  Eight  (Listing  continued,  text  begins  on  page  22.) 

Listing  Nine 

IF  (Which  =  Output)  AND  (outP  >  0)  THEN 

IMPLEMENTATION  MODULE  DataLink;  (*  Sends  and  Receives  Packets  for  PCKermit  *) 

WriteNBytes  (f,  ADR  (outBuf),  outP,  written); 

END; 

FROM  InOut  IMPORT 

Close  (f); 

WriteString,  WriteLn; 

IF  (written  =  outP)  AND  (f.res  =  done)  THEN 

RETURN  Done; 

FROM  Delay  IMPORT 

ELSE 

Delay;  (*  delay  is  in  milliseconds  *) 

RETURN  Error; 

END; 

FROM  BitByteOps  IMPORT 

END  CloseFile; 

Byte And; 

IMPORT  RS232lnt;  (*  for  RS232lnt . BusyRead,  RS232Int .Write  *) 

PROCEDURE  Get  (VAR  f  :  File;  VAR  ch  :  CHAR)  :  Status; 

(*  Reads  one  character  from  the  file,  returns  status  *) 

FROM  PAD  IMPORT 

BEGIN 

PacketType,  yourNPAD,  yourPADC,  yourEOL; 

IF  inP  =  read  THEN 

ReadNBytes  (f,  ADR  (inBuf),  SIZE  (inBuf),  read); 

IMPORT  ASCII; 

inP  :=  0; 

END; 

IF  read  =  0  THEN 

CONST 

RETURN  EOF; 

MAXtime  =  10000; 

ELSE 

MAXsohtrys  =  100; 

INC  (inP); 

ch  :=  inBuf [inP] ; 

VAR 

RETURN  Done; 

ch  :  CHAR; 

END; 

GotChar  :  BOOLEAN; 

END  Get; 

PROCEDURE  Char  (c  :  INTEGER)  :  CHAR; 

PROCEDURE  Put  (ch  :  CHAR); 

(*  converts  a  number  0-95  into  a  printable  character  *) 

(*  Writes  one  character  to  the  file  buffer  *) 

BEGIN 

BEGIN 

RETURN  (CHR  (CARDINAL  (ABS  (c)  +  32))); 

INC  (outP); 

END  Char; 

outBuf [outP]  :=  ch; 

END  Put; 

PROCEDURE  UnChar  (c  :  CHAR)  :  INTEGER; 

(*  converts  a  character  into  its  corresponding  number  *) 

PROCEDURE  DoWrite  (VAR  f  :  File)  :  Status; 

BEGIN 

(*  Writes  buffer  to  disk  only  if  nearly  full  *) 

RETURN  (ABS  (INTEGER  (ORD  (c) )  -  32)); 

BEGIN 

END  UnChar; 

IF  outP  <  400  THEN  (*  still  room  in  buffer  *) 

RETURN  Done; 

ELSE 

PROCEDURE  FlushUART; 

WriteNBytes  (f,  ADR  (outBuf),  outP,  written); 

(*  ensure  no  characters  left  in  UART  holding  registers  *) 

IF  (written  =  outP)  AND  (f.res  =  done)  THEN 

BEGIN 

outP  :=  0; 

Delay  (500); 

RETURN  Done; 

REPEAT 

ELSE 

RS232lnt .BusyRead  (ch,  GotChar); 

RETURN  Error; 

UNTIL  NOT  GotChar; 

END; 

END  FlushUART; 

END; 

End  Listing  Eight 

END  Files. 
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PROCEDURE  SendPacket  (s  :  PacketType) ; 

(*  Adds  SOH  and  Checksum  to  packet  *) 

VAR 

i  :  INTEGER; 
checksum  :  INTEGER; 

BEGIN 

Delay  (10);  (*  give  host  a  chance  to  catch  its  breath  *) 

FOR  i  :=  1  TO  yourNPAD  DO 
RS232Int. Write  (yourPADC) ; 

END; 

RS232Int. Write  (ASCII. soh); 
i  :=  1; 

checksum  :=  0; 

WHILE  s [ i]  #  OC  DO 

INC  (checksum,  ORD  (s[i])); 

RS232Int. Write  < s [ i ] ) ; 

INC  (i); 

END; 

checksum  :  =  checksum  +  (INTEGER  (BITSET  (checksum)  *  {7,  6))  DIV  64); 
checksum  :  =  INTEGER  (BITSET  (checksum)  *  (5,  4,  3,  2,  1,  0)); 
RS232Int. Write  (Char  (checksum)); 

IF  yourEOL  #  OC  THEN 

RS232lnt. Write  (yourEOL); 

END; 

END  SendPacket; 


PROCEDURE  ReceivePacket  (VAR  r  :  PacketType)  :  BOOLEAN; 

(*  strips  SOH  and  checksum  —  return  FALSE  if  timed  out  or  bad  checksum  *) 


sohtrys,  time  :  INTEGER; 
i,  len  :  INTEGER; 
ch  :  CHAR; 
checksum  :  INTEGER; 
mycheck,  yourcheck  :  CHAR; 

BEGIN 

sohtrys  :=  MAXsohtrys; 

REPEAT 

time  :=  MAXtime; 

REPEAT 

DEC  (time); 

RS232Int .BusyRead  (ch,  GotChar); 

UNTIL  GotChar  OR  (time  =  0) ; 

ch  :=  CHAR  (ByteAnd  (ch,  177C) ) ;  (*  mask  off  MSB  *) 

(*  skip  over  up  to  MAXsohtrys  padding  characters,  *) 

(*  but  allow  only  MAXsohtrys/10  timeouts  *) 

IF  GotChar  THEN 
DEC  (sohtrys); 

ELSE 

DEC  (sohtrys,  10); 

END; 

UNTIL  (ch  =  ASCII. suh)  OR  (sohtrys  <=  0) ; 

IF  ch  =  ASCI I. soh  THEN 

(*  receive  rest  of  packet  *) 
t ime  : =  MAXt ime ; 

REPEAT 

DEC  (time); 

RS232lnt. BusyRead  (ch,  GotChar); 

UNTIL  GotChar  OR  (time  =  0); 
ch  :=  CHAR  (ByteAnd  (ch,  177C) ) ; 
len  :=  UnChar  (ch) ; 
r [ 1 ]  :=  ch; 
checksum  :=  ORD  (ch) ; 

i  :=  2;  (*  on  to  second  character  in  packet  —  after  LEN  *) 

REPEAT 

time  :=  MAXtime; 

REPEAT 

DEC  (time); 

RS232Int. BusyRead  (ch,  GotChar); 

UNTIL  GotChar  OR  (time  =  0); 
ch  :=  CHAR  (ByteAnd  (ch,  177C) ) ; 
r [i]  :=  ch;  INC  (i); 

INC  (checksum,  (ORD  (ch) ) ) ; 

UNTIL  (i  >  len); 
time  :=  MAXtime; 

REPEAT 

DEC  (time); 

RS232lnt. BusyRead  (ch,  GotChar); 

UNTIL  GotChar  OR  (time  =  0);  (*  get  checksum  character  *) 

ch  :=  CHAR  (ByteAnd  (ch,  177C) ) ; 
yourcheck  :  =  ch; 
r [i]  :=  0C; 

checksum  :=  checksum  + 

(INTEGER  (BITSET  (checksum)  *  (7,  6))  DIV  64); 
checksum  :=  INTEGER  (BITSET  (checksum)  *  (5,  4,  3,  2,  1,  0)); 

mycheck  :=  Char  (checksum); 

IF  mycheck  =  yourcheck  THEN  (*  checksum  OK  *) 

RETURN  TRUE; 

ELSE  (*  ERROR!!!  *) 

WriteString  ("Bad  Checksum");  WriteLn; 

RETURN  FALSE; 

END; 

ELSE 

WriteString  ("No  SOH");  WriteLn; 

RETURN  FALSE; 

END; 

END  ReceivePacket; 

END  DataLink. 


End  Listings 


Listing  One  (Text  begins  on  page  39.) 

DEFDBL  A-Z 
DIM  i  AS  LONG 

k  =  1#  /  LOG { 2 # )  'convert  to  base  2 

OPEN  "o",  1,  "c:temp" 

FOR  i  =  1  TO  100000 
t  =  t  +  LOG ( i )  *  k 

IF  i  MOD  10000  =  0  OR  i  <  11  OR  i  =  100  OR 
(i  <  10000  AND  i  MOD  1000  =  0)  THEN 
PRINT  #1,  i,  t  /  i,  ( LOG ( i  *  .737)  *  k)  -  1 
NEXT  i 


End  Listing  One 


Listing  Two 


.MODEL  MEDIUM 
.CODE 

PUBLIC  convint 

;convint  written  by  Bruce  W.  Tonkin  on  8-14-88  for  use  with  QB  4.0  &  MASM 
; convint  will  convert  a  binary  2-byte  integer  passed  as  a  string  into 
;a  string  with  the  bytes  re-ordered  so  an  ASCII-order  sort  will  sort  in 
.•numeric  order.  It  is  called  with: 

;call  convint  (x$) 

,-where  x$  is  the  string  to  convint  (in  the  current  data  segment)  . 

;The  routine  does  not  check  for  a  zero  length  of  the  passed  string, 
convint  PROC 

push  bp  ;save  old  BP 

mov  bp, sp  ;Set  framepointer  to  old  stack 

bx, [bp+6]  ;bx  points  to  string  length,  which  we  don't  need 


mov 

mov 

inc 


bx, [bx]+2  ;move  the  string  address  to  bx 


dh.byte  ptr  [bx] 
bx 


mov 

dl.byte  ptr  [bx] 

xor 

dl, 080h 

mov 

byte  ptr 

[bx] ,dh 

dec 

bx 

mov 

byte  ptr 

[bx] ,dl 

pop 

bp 

; resto: 

ret 

2 

; clear 

convint 

ENDP 

END 

;get  first  byte 
; point  to  next  byte 
; get  second  byte 
; invert  the  sign  bit 
; store  first  byte  where  second  was 
;now  for  modified  second  byte 
; store  where  first  byte  went 


End  Listing  Two 


Listing  Three 


.MODEL  MEDIUM 
.CODE 

PUBLIC  convlong 

;convlong  written  by  Bruce  W.  Tonkin  on  8-14-88  for  use  with  QB  4.0  &  MASM  5.0 
; convlong  will  convert  a  long  integer  passed  as  a  packed  4-byte  string  into 
;a  string  with  the  bytes  re-ordered  so  an  ASCII-order  sort  will  sort  in 
.•numeric  order.  It  is  called  with: 

;call  convlong  (x$) 

,-where  x$  is  the  string  to  convlong  (in  the  current  data  segment)  . 

;The  routine  does  not  check  for  a  zero  length  of  the  passed  string, 
convlong  PROC 

push  bp  ;save  old  BP 

mov  bp.sp  ;Set  framepointer  to  old  stack 

bx, [bp+6]  ; address  of  string  length  isn't  needed 
bx, [bx] +2  ;move  the  string  address  to  bx 


mov 

mov 

mov 

inc 

mov 

inc 

mov 

inc 

mov 

mov 

dec 

mov 

dec 

mov 

dec 

xor 

mov 

pop 


ret 

convlong  ENDP 
END 


dh.byte  ptr  [bx]  ;get  first  byte 

bx  ; point  to  next  byte 

dl.byte  ptr  [bx]  ;get  second  byte 

bx  ; point  to  third  byte 

ah, byte  ptr  [bx]  ;get  third  byte 
bx  ,-point  to  last  byte 

al.byte  ptr  [bx]  ;get  fourth  and  last  byte 

byte  ptr  [bx],dh  ;store  first  byte  in  fourth  spot 

bx  ; point  to  third  spot 

byte  ptr  [bx],dl  ; store  former  second  byte 
bx  ,-point  to  second  spot 

byte  ptr  [bx],ah  ; store  former  third  byte 
bx  ,-point  to  former  first  byte  spot 

al,08Gh  ; invert  the  sign  bit 

byte  ptr  [bx],al  ;and  store  the  fourth  byte  where  first  was 

bp  ; restore  old  base  pointer 

2  ; clear  2  bytes  of  parameters  on  return 


End  Listing  Three 


Listing  Four 

.MODEL  MEDIUM 
.CODE 

PUBLIC  convof 

;convof  written  by  Bruce  W.  Tonkin  on  8-14-88  for  use  with  QB  4.0  &  MASM  5.0 
;  convof  will  convert  a  Microsoft  Binary  format  floating-point  number  passed  as 
;a  string  into  a  string  with  the  bytes  re-ordered  so  an  ASCII-order  sort  will 
;sort  in  numeric  order.  It  is  called  with: 

;call  convof  (x$) 

,-where  x$  is  the  string  to  convof  (in  the  current  data  segment)  . 

;The  routine  does  not  check  for  a  zero  length  of  the  passed  string, 
convof  PROC 

push  bp  ;save  old  BP 

mov  bp,sp  ;Set  framepointer  to  old  stack 
mov  bx,  [bp+6]  ,-move  the  string  length  to  cx 
mov  cx, [bx] 

push  si  ,-save  si--used  by  routine 

mov  ax,cx  ;copy  cx  into  ax 

dec  ax  ; subtract  one  from  ax 
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shr 

cx,  1 

/divide  cx  by  two 

mov 

bx, [bx]+i 

!  /move  the  string  address  to  bx 

push  bx 

/save  that  address 

add 

bx,  ax 

/look  at  the  end  of  the  string 

emp  byte  ptr  | 

;bx],0  /check  the  first  byte 

pop 

bx 

/restore  string  pointer 

jnz 

va 

/last  byte  was  not  zero 

mov 

byte  ptr 

[bx],Q81h  /it  was  zero,  so  make  first  byte  129 

dec 

cx 

/and  make  all  other  bytes  zero 

inc 

bx 

/point  to  next  byte 

mov 

byte  ptr 

[bx],0  /clear  it 

inc 

bx 

/point  to  next  byte 

loop  vt 

/decrement  cx  and  loop  until  done 

jmp 

vi 

/then  go  to  the  end  and  restore  registers 

mov 

si,  bx 

/set  up  si  to  point  to  bytes  to  swap 

add 

si,  ax 

/points  to  last  byte  of  string 

mov 

dl, [bx] 

/first  byte  of  string  to  dl 

mov 

dh, [si] 

/second  byte  to  dh 

mov 

[bx] , dh 

/and  save  it 

mov 

[sij , dl 

/swap  two  bytes  to  reverse  order 

inc 

bx 

/point  to  next  byte 

dec 

si 

/and  get  ready  for  corresponding  byte  to  move 

loop 

iv 

/dec  cx  and  repeat  until  all  bytes  were  swapped 

mov 

bx, [bp+6] 

/restore  the  original  string  pointer 

mov 

cx, [bx] 

Z length  to  cx 

mov 

bx, [bx]+2 

/location  in  bx 

this 

point,  all  the  bytes  in  the  string  have  been  put  m  reverse 

mov 

ah, [bx] 

/save  first  string  byte  into  ah 

inc 

bx 

/point  to  second  byte 

mov 

al, [bx] 

/second  byte  into  al 

dec 

bx 

/now  point  to  first  byte  again 

mov 

dh,  ah 

/save  copies 

mov 

dl,  al 

/of  both  bytes 

push 

cx 

/save  cx=length 

mov 

cl, 7 

/get  ready  to  rotate 

shl 

ah,  cl 

/move  low  bit  left  7  positions  for  first  byte 

shr 

al,  cl 

/move  high  bit  right  7  positions  for  second  byte 

pop 

cx 

/restore  count  in  cx 

and 

dl, 07fh 

/mask  high  bit  for  byte  two 

add 

dl,  ah 

/low  bit  of  byte  one  to  high  bit  of  byte  two 

shr 

dh,  1 

/shift  byte  one  right  one  bit 

or 

dh, 080h 

/and  turn  high  bit  on  for  byte  one 

emp 

al,  1 

/check  status  of  former  high  bit  on  byte  two 

jnz 

V 

/high  bit  wasn't  set 

push  bx 

/save  string  pointer 

xor 

dx, Off f fh 

/invert  first  two  bytes 

inc 

bx 

/point  to  second  byte 

inc 

bx 

/point  to  third  byte 

dec 

cx 

/decrement  counter  accordingly 

dec 

cx 

xor 

byte  ptr 

[bx],0ffh.  /invert  successive  bytes  three  to  end 

inc 

bx 

/point  to  next  byte 

loop 

vv 

/decrement  cx  and  repeat  until  done 

pop 

bx 

/restore  string  pointer 

mov 

byte  ptr 

[bx],dh  /save  altered  byte  one 

inc 

bx 

mov 

byte  ptr 

[bx],dl  /and  byte  two 

pop 

si 

/restore  si 

pop 

bp 

/restore  old  base  pointer 

ret 

2 

/clear  2  bytes  of  parameters  on  return 

convof  ENDP 
END 


Listing  Six 

.MODEL  MEDIUM 
.CODE 

PUBLIC  INVERT 

/INVERT  written  by  Bruce  W.  Tonkin  on  8-13-88  for  use  with  QB  4.0  &  MASM  5.0 
; INVERT  will  xor  all  the  bytes  in  a  string,  thus  allowing  it  to  be  sorted  in 
/descending  order.  It  is  called  with: 

/call  INVERT  (x$) 

/where  x$  is  the  string  to  invert  (in  the  current  data  segment) . 

/The  routine  does  not  check  for  a  zero  length  of  the  passed  string. 

INVERT  PROC 

push  bp  /save  old  BP 

mov  bp,sp  /Set  framepointer  to  old  stack 

mov  bx, [bp+6]  /move  the  string  length  to  cx 
mov  cx, [bx] 

mov  bx, [bx]+2  /put  the  string  address  into  bx 
iv:  xor  byte  ptr  [bx],0ffh  /convert  the  first  byte 
inc  bx 

loop  iv  /decrement  cx  and  repeat  until  done 

pop  bp  /restore  old  base  pointer 

ret  2  /clear  2  bytes  of  parameters  on  return 

INVERT  ENDP 

End  Listing  Six 

Listing  Seven 

defint  a-z 
dim  t ! (17) 
dim  t$ (17) 

open "o", 1, "bench. dat" 
els 

t !  (0) =timer 
for  i=l  to  100 

for  j=l  to  1000 
next  j 
next  i 

t ! (0) =timer-t ! (0)  'time  for  bare  loop 
t$(0)="Raw  integer  loop" 

d$=mki$ (-13) 
t ! (1) =timer 
for  i=l  to  100 

for  j=l  to  1000 

CALL  convint(d$) 
next  j 
next  i 

t ! (1) =timer-t ! (1)  'time  for  integer  conversions 

t$ (1) =" Integer  conversion" 

d$=mkl$ (-130000) 
t !  (2) =timer 
for  i=l  to  100 

for  j=l  to  1000 

CALL  convlong(dS) 
next  j 
next  i 

t ! (2) =timer-t ! (2)  'time  for  long  integer  conversions 

t$(2)="Long  integer  conversion" 


End  Listing  Four 


Listing  Five 


.MODEL  MEDIUM 
.CODE 

PUBLIC  convnf 

/convnf  written  by  Bruce  W.  Tonkin  on  8-13-88  for  use  with  QB  4.0  &  MASM  5.0 
/convnf  will  convert  an  IEEE  floating-point  number  passed  as  a  string  into 
;a  string  with  the  bytes  re-ordered  so  an  ASCII-order  sort  will  sort  in 
/numeric  order.  It  is  called  with: 

/call  convnf  (x$) 

/where  x$  is  the  string  to  convnf  (in  the  current  data  segment) . 

/The  routine  does  not  check  for  a  zero  length  of  the  passed  string, 
convnf  PROC 


push 

bp 

/save  old  BP 

mov 

bp,  sp 

/Set  framepointer  to  old  stack 

mov 

mov 

bx, [bp+6] 
cx, [bx] 

/move  the  string  length  to  cx 

push 

si 

/save  si — used  by  routine 

mov 

ax,  cx 

/copy  cx  into  ax 

dec 

ax 

/subtract  one  from  ax 

shr 

cx,  1 

/divide  cx  by  two 

mov 

bx, [bx]+2 

/move  the  string  address  to  bx 

mov 

si ,  bx 

/set  up  si  to  point  to  bytes  to  swap 

add 

si,  ax 

/points  to  last  byte  of  string 

mov 

dl, [bx] 

/first  byte  of  string  to  dl 

mov 

dh, [si] 

/ second  byte  to  dh 

mov 

[bx] , dh 

/and  save  it 

mov 

[sij , dl 

/swap  two  bytes  to  reverse  order 

inc 

bx 

/point  to  next  byte 

dec 

si 

/and  get  ready  for  corresponding  byte  to  move 

loop 

iv 

/dec  cx  and  repeat  until  all  bytes  were  swapped 

mov 

bx, [bp+6] 

/restore  the  original  string  pointer 

mov 

cx, [bx] 

/length  to  cx 

mov 

bx, [bx] +2 

/location  in  bx 

test 

byte  ptr 

[bx],080h  /check  the  high-order  bit  of  the  first  byte 

jnz 

V 

/high-order  bit  was  set 

xor 

byte  ptr 

[bx],080h  /fix  the  first  byte 

jmp 

vi 

/and  done 

xor 

byte  ptr 

[bx],0ffh  /invert  all  the  bytes  in  the  string 

inc 

bx 

/next  location 

loop 

V 

/dec  cx  and  repeat  until  all  bytes  have  been  inverted 

pop 

si 

/restore  si 

pop 

bp 

/restore  old  base  pointer 

ret 

2 

/clear  2  bytes  of  parameters  on  return 

convnf  ENDP 

END  End  Listing  Five 


d$=string$ (4, 204) 
t ! (3) =timer 
for  i=l  to  100 

for  j=l  to  1000 

CALL  convof (d$) 
next  j 
next  i 

t ! (3) =timer-t ! (3)  'time  for  old  single-precision  float  conversion 

t$(3)="01d  single  float  conversion" 

d$=string$ (8, 204) 
t ! (4) =timer 
for  i=l  to  100 

for  j=l  to  1000 

CALL  convof (d$) 
next  j 
next  i 

t ! (4)=timer-t ! (4)  'time  for  old  double-precision  float  conversion 

t$(4)="01d  double  float  conversion" 

d$=mks$ (-13.0405) 
t ! (5) =timer 
for  i=l  to  100 

for  j=l  to  1000 

CALL  convnf (d$) 
next  j 
next  i 

t ! (5) =timer-t ! (5)  'time  for  IEEE  single-precision  float  conversion 

t$(5)="IEEE  single  float  conversion" 

d$=mkd$ (-13.04050607) 
t ! (6) =timer 
for  i=l  to  100 

for  j=l  to  1000 

CALL  convnf (d$) 
next  j 
next  i 

t ! (6)=timer-t ! (6)  'time  for  IEEE  double-precision  float  conversion 

t$(6)="IEEE  double  float  conversion" 

t ! (7) =timer 
for  i=l  to  100 

for  j=l  to  1000 

CALL  invert (d$) 
next  j 
next  i 

t ! (7) =timer-t ! (7)  'time  for  inverting  8  bytes 

t$ (7) ="lnvert  8  bytes" 

a$="AB" 

b$="AX" 
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t!  (8) =timer 
for  i=l  to  100 

for  j=l  to  1000 

if  a$>b$  then  j=j+l 
next  j 
next  i 

t ! (8) =timer-t ! (8)  'time  to  compare  two-byte  strings 

t$ (8) “"Compare  two-byte  strings" 

a=100 

b=200 

t!  (9)=timer 
for  i=l  to  100 

for  j=l  to  1000 

if  a>b  then  j=j+l 
next  j 
next  i 

t! (9)=timer-t! (9)  'time  to  compare  two  integers 

t$ (9) “"Compare  two  integers" 

a$="ABCD" 
b$="ABCX" 
t !  (10) “timer 
for  i=l  to  100 

for  j=l  to  1000 

if  a$>b$  then  j=j+l 
next  j 
next  i 

t ! (10)=timer-t! (10)  'time  to  compare  two  4-byte  strings 
t$  (10) “"Compare  two  four-byte  strings" 

a ! =1 00 . 01 ! 
b! =200 .01 ! 
t!  (lljftimer 
for  i=l  to  100 

for  j=l  to  1000 

if  a ! >b !  then  j=j+l 
next  j 
next  i 

t ! (ll)=timer-t! (11)  'time  to  compare  two  single  floats 
t$ (11) ="Compare  two  single  floats" 

a#=100.01# 
b#=200 .01# 
t ! (12) “timer 
for  i=l  to  100 

for  j=l  to  1000 

if  a#>b#  then  j=j+l 
next  j 
next  i 

t ! (12) “timer-t ! (12)  'time  to  compare  two  double  floats 
t$ (12) “"Compare  two  double  floats" 

a$="ABCDEFGH" 
b$="ABCDEFGX" 
t ! (13) “timer 
for  i=l  to  100 

for  j=l  to  1000 

if  a$>b$  then  j=j+l 
next  j 
next  i 

t! (13)=timer-t! (13)  'time  to  compare  two  8-byte  strings 
t$ (13) “"Compare  two  8-byte  strings" 

a&=123456& 
b&=123457& 
t ! (14) “timer 
for  i=l  to  100 

for  j=l  to  1000 

if  a&>b&  then  j=j+l 
next  j 
next  i 

t ! (14) =timer-t ! (14)  'time  to  compare  two  long  integers 
t$ (14) “"Compare  two  long  integers" 

a  $ = " ABCDEFGH I JKLMNOPQRST " 
b$="ABCDEFGHIJKLMNOPQRSX" 
t ! (15) “timer 
for  i=l  to  100 

for  j=l  to  1000 

if  a$>b$  then  j=j+l 
next  j 
next  i 

t ! (15) =timer-t! (15)  'time  to  compare  two  20-byte  strings 

t$ (15) “"Compare  two  20-byte  strings" 

a$="ABCDEFGHI JKLMNOPQRST" 

b$="XBCDEFGHI JKLMNOPQRST" 

t! (16)=timer 

for  i=l  to  100 

for  j=l  to  1000 

if  a$>b$  then  j=j+l 
next  j 
next  i 

t ! (16) =timer-t ! (16)  'best?  time  to  compare  two  20-byte  strings 
t$ (16) “"Compare  two  20-byte  strings  (best?)" 

t ! (17) =timer 
for  i=l  to  100 

for  j=l  to  1000 

call  dummy(a,b,c) 
next  j 
next  i 

t ! (17) =timer-t ! (17)  'time  to  make  a  call  with  three  parameters 
t$ (17)  ="Three-integei:-parameter  call" 

print  t$ (0) , t !  (0) 
print  #1, t$ (0) , t ! (0) 
for  i=l  to  17 

t! (i)=t! ( i) — t ! (0) 
print  t$ ( i) , t ! (i) 
print  #l,t$ (i) ,t!  (i) 
next  i 

sub  dummy(a,b,c)  static 

c-1  End  Listings 

end  sub  _ 


Listing  One  ( Text  begins  on  page  50.) 

//  FIELD. HXX:  used  by  csascii  class  to  build  a  single  field. 

//  Fields  are  collected  by  csascii  to  create  a  record. 

//by  Bruce  Eckel 
# include  <stream.hxx> 

class  field  {  //  one  field  in  a  comma-separated  ASCII  record 
istream  *  input;  //  where  to  get  the  data 
char  *  data; 
int  length,  fsize; 

int  end_of_file;  //  flag  to  indicate  the  end  of  file  happened 
void  getfieldO;  //  recursive  function  to  read  in  a  field; 

//  treats  data,  length  &  input  as  globals 
int  infield;  //  flag  used  by  getfieldO  to  determine  whether 
//  it's  inside  a  quoted  field 

public: 

f ield(istream  &  instream); 
field () ; 

friend  ostream&  operator« (ostream  &s,  field  &  f)  { 
s  «  f.data; 
return  s; 

) 

int  eof()  (  return  end_of_file;  )  //to  check  for  end 

int  size()  {  return  fsize;) 

int  last_length()  (return  length;  ) 

char  *  string ()  {  return  data;  ) 

) ;  End  Listing  One 


Listing  Two 

//  FIELD. CXX:  definitions  for  class  field 

//  A  "recursive  descent"  scanning  scheme  is  used  because  field 
//  length  is  always  unknown. 

//by  Bruce  Eckel 
#include  "field. hxx" 

field: : field(istream  &  instream)  { 
input  =  &instream; 
length  =  0; 

end_of_file  =  0;  //  set  flag  to  say  "we're  not  at  the  end" 
infield  =  0;  //  set  flag  to  say  "we're  not  inside  a  field" 
data  =  (char  *)0;  //  to  show  no  memory  has  been  allocated 
getfieldO;  //  recursively  get  characters  until  end  of  field 


field: : field ( )  ( 

delete  data;  //  if  no  memory  has  been  allocated, 
//  data  =  (char  *)0  so  this  will  have  no  effect. 


//  A  Comma-separated  ASCII  field  is  contained  in  quotes  to  allow 
//  commas  within  the  field;  these  quotes  must  be  stripped  out 
void  field: :getfield()  ( 
char  c; 

//  This  happens  when  DEscending: 
if ( (input->get (c) ) .eof ()  )  ( 

end_of_file++;  //  just  say  we  reached  the  end... 
return; 

) 

else  //  watch  out  for  the  Unix  vs.  DOS  LF/CR  problem  here: 
if  (((c  !=  ',')  ||  infield)  &&  (c  !=  '\n'))  { 

if  (  (c  !=  '"')  &&  (c  !=  ' \r' ) )  //  watch  for  quotes  or  CR 
length++;  //  no  quotes  —  count  this  character 
else  { 

if  (  c  ==  '"') 

infield  =  ! infield;  //  if  we  weren't  inside  a  field 
//  and  a  quote  was  encountered,  we  are  now  inside 
//  a  field.  If  we  were  inside  a  field  and  a  quote 
//  was  found,  we're  cut  of  the  field, 
c  =  0;  //  a  quote  or  CR;  mark  it  so  it  isn't  included 

) 

getfieldO;  //  recursively  get  characters  in  field 
//  after  returning  from  function  call,  we  jump  past 
//  the  following  "else"  part  to  finish  the  recursion 
I 

else  {  //  This  happens  once,  when  the  terminator  is  found: 
fsize  =  length;  //  remember  how  long  the  string  is 
data  =  new  char [length  +  1];  //  space  for  null  terminator 
data (length]  =  '\0';  //  highest  index  is  "length" 

//  when  you  allocate  an  array  of  length  +  1 
length—;  //  notice  we  don't  insert  the  delimiter 
//  Now  the  first  "if"  statement  evaluates  to  TRUE  and 
//  the  function  rises  back  up. 
return; 

I 

//  This  happens  when  Ascending: 

if  (  c  )  //  if  it  wasn't  a  quote  or  CR, 

data[length — ]  =  c;  //  put  chars  in  as  we  rise  back  up... 


End  Listing  Two 


Listing  Three 

//  CSASCII. HXX:  class  to  manipulate  comma-separated  ASCII 
//  database  files. 

//by  Bruce  Eckel 
#include  <stream.hxx> 

# include  "field. hxx" 

class  csascii  {  //  manipulates  comma-separated  ascii  files, 

//  generated  by  most  database  management  systems  (generated  and 
//  used  by  the  BASIC  programming  language) .  Each  field 
//  is  separated  by  a  comma;  records  are  separated  by  newlines, 
int  fieldcount; 

field  **  data;  //  an  array  to  hold  the  entire  record 
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istream  *  datafile;  //  file  with  comma  separated  ASCII  input 
int  readrecord ( ) ;  //  private  function  to  read  a  record 
public: 

csascii (  char  *  filename  );  //  Open  file,  get  first  record 

csasciiO;  //  destructor 

int  next();  //  get  next  record,  return  0  when  EOF 
field  &  operator!] (int  index);  //  select  a  field 
int  number_of_fields ()  (  return  fieldcount;  ) 


End  Listing  Three 


Listing  Four 

//  CSASCII.CXX:  function  definitions  for  comma-separated 
//  ascii  database  manipulation  class 
//by  Bruce  Eckel 
♦include  "csascii .hxx" 

int  csascii :: readrecord ()  { 

for  (int  fieldnum  =  0;  fieldnum  <  fieldcount;  fieldnum++  )  { 
data [fieldnum]  =  new  field (*datafile) ; 
if  (data [ fieldnum] ->eof () )  return  0; 

I 

return  1; 


csascii: '.csascii  (  char  *  filename  )  { 
char  c; 

fieldcount  =  0; 
int  quote  =  0; 

//  first,  determine  the  number  of  fields  in  a  record: 

I 

//  See  text  for  dangers  of  opening  files  this  way: 
istream  infile (new  filebuf->open (filename,  input)); 
while (infile. get  (c) ,  c  !=  '\n')  { 

//  keep  track  of  being  inside  a  quoted  string: 
if  (c  ==  '"')  quote  =  (quote; 

//  fields  are  delimited  by  unquoted  commas: 
if  (  c  ==  ' , '  &&  (quote) 
fieldcount++; 

> 

)  //  infile  goes  out  of  scope;  file  closed 

f ieldcount++;  //  last  field  terminated  by  newline,  not  comma 
//  an  array  of  field  pointers: 
data  =  new  field  *  [  fieldcount  ); 

//  re-open  at  start;  dynamically  allocate  so  it  isn't  scoped: 
datafile  =  new  istream(new  filebuf->open (filename,  input)); 
readrecord () ; 


csascii: :csascii ()  1 
delete  data; 

delete  datafile;  //  calls  istream  destructor  to  close  file 

) 

int  csascii: :next  ()  { 

for  (int  i  =  0;  i  <  fieldcount;  i++  ) 

delete  data[i];  //  free  all  the  data  storage 
return  readrecord () ;  //  0  when  end  of  file 

I 

field  &  csascii: :operator[) (int  index)  { 
if  (index  >=  fieldcount)  ( 

cerr  <<  "index  too  large  for  number  of  fields  in  record\n"; 
exit  (1) ; 

) 

return  * (data [index] ) ; 


End  Listing  Four 


Listing  Five 

//  LOOKUP. CXX:  simple  use  of  csascii  to  find  name  in  a  database 
//by  Bruce  Eckel 
♦include  "csascii. hxx" 

♦include  <string.h> 
main (int  argc,  char  **  argv)  ( 
if  (argc  <  2)  ( 

cerr  «  "usage:  lookup  lastname\n"; 
exit  (1) ; 

} 

//  This  puts  the  database  file  in  the  root  directory: 
csascii  f ile ("Wppquick.asc") ;  //  create  object  &  open  file 
int  found  =  0;  //  indicates  one  record  was  found 

do  { 

if  (strcmp (file [0] . string () , argv[l] )  ==  0)  ( 

found++;  //  found  one.  File  is  sorted,  so  if  we  stop 
//  finding  them,  quit  instead  of  wasting  time, 
cout  «  chr(27)  «  "[2J";  //  ANSI  clear  screen 
for  (int  i  =  0;  i  <  file.number_of_fields () ;  i++) 
cout  <<  filefi]  «  "\n"; 

cout  «  chr(27)  «  "(7m"  «  "press  any  key"  « 
chr(27)  «  ”[0m"; 
if (  getch()  ==  27)  break; 

}  else  if  (found)  exit(0);  //  quit  if  that  was  the  last 
)  while  ( file. next () ) ; 

) 


End  Listing  Five 


Listing  Six 

//  PARSE. HXX:  class  to  parse  a  tawk  script  file.  Creates 
//  a  structure  which  can  be  used  at  run-time  to  "execute" 

//  the  tawk  script. 

//by  Bruce  Eckel 
♦include  <stream.hxx> 

//  types  of  tokens  the  scanner  can  find: 
enum  tokentype  ( 

fieldnumber,  string,  if_,  else_,  endif_,  phase_change 

}; 

//  preamble  and  conclusion  of  the  tawk  script  are  only  executed 
//  once,  while  main  is  executed  once  for  every  data  record 
enum  phase  (  preamble,  tmain,  conclusion]; 

class  token  { 
tokentype  ttype; 

union  (  //  an  "anonymous  union" 

int  fieldnum;  //  if  type  is  a  fieldnumber 
unsigned  char  *  literal;  //  if  type  is  a  string 
I; 

int  if_level;  //  if  this  is  an  if_,  then_,  or  else_ 

//  private  functions: 

void  get_token();  //  recursive  descent  scanner 
//  Functions  to  help  in  scanning: 
void  getnext(char  &  c) ;  //  used  by  get_token(); 
unsigned  char  get_value (char  delimiter,  char  *  msg); 
void  dumpline ();  //  for  @!  comments 
void  error (char  *  msg  =  char  *  msg2  =  ""); 
public: 

token (istream  &  input); 
token ( ) ; 

friend  ostream  &  operator<< (ostream  &s,  token  &t); 
int  field_number ()  (  return  fieldnum;  ) 
int  token_type()  (  return  ttype;  ) 
int  nesting_level ()  (  return  if_level; ] 

1; 

//  The  following  is  called  a  "container  class,"  since  its  sole 
//  purpose  is  to  hold  a  list  of  objects  (tokens,  in  this  case) : 
class  parse_array  { 

token  **  tokenarray;  //an  array  of  token  pointers 
istrean.  *  parse_stream; 
int  token_count; 

int  end;  7/  the  size  of  the  array 
phase  p_section;  //  of  the  program  (preamble,  etc.) 
void  build_array () ;  //  another  recursive  function 
public: 

parse_array (istream  &  input); 
parsearray () ; 

int  size()  f  return  end;  1  //  how  big  is  it? 
token  &  operator [] (int  index);  //  select  a  token 
phase  section ()  {  return  p_section;  ) 

I; 

End  listing  Six 


Listing  Seven 

//  PARSE. CXX:  class  parse  function  definitions 
//  by  Bruce  Eckel 
♦include  "csascii .hxx" 

♦include  "parse. hxx" 

♦include  <ctype.h> 

♦include  <stdlib.h> 

//  The  following  are  "file  static,"  which  means  no  one  outside 
//  this  file  can  know  about  them.  This  is  the  meaning  when  a 
//  global  variable  is  declared  "static." 
static  istream  *  tokenstream; 

static  int  length;  //  to  remember  size  of  string 
static  int  line_number  =  1;  //  line  counting  for  errors 

static  int  if_counter  =  0;  //  monitors  "if"  statement  nesting 
static  phase  program_section  =  preamble;  //  ...  until  @main 
static  int  end_of_file  =  0;  //  zero  means  not  end  of  file 

token: : token (istream  &  input)  ( 

//  initialize  values  and  start  the  descent 
tokenstream  =  &  input; 
length  =  0; 

get_token();  //  recursively  get  characters  to  end  of  token 

) 

token: : token ()  (  //  delete  heap  if  any  has  been  allocated: 
if  (ttype  ==  string) 
delete  literal; 

] 

void  token: :error (char  *  msg,  char  *  msg2)  ( 

cerr  «  "token  error  on  line  "  «  line_number  «  ":  "  << 
msg  «  "  "  «  msg2  «  "\n"; 
exit (1) ; 


ostream  &  operator<< (ostream  &s,  token  & t )  1 
switch  (t. ttype)  ( 
case  string: 

s  «  (char  *) t. literal; 
break; 

case  fieldnumber:  //  only  for  testing 

s  «  "  fieldnumber:  "  «  t. fieldnum  «  "\n"; 

} 

return  s; 


//  Get  a  character  from  the  tokenstream,  checking  for 
//  end-of-file  and  newlines 
void  token: :getnext (char  &  c)  ( 
if (end_of_file) 
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error  ("attempt  to  read  after  0end  statements", 
"missing  @conclusion  ?"); 
if ( (tokenstream->get (c) ) .eof ()  ) 
error ("@end  statement  missing"); 
if  (c  ==  ' \n' ) 

line_number++;  //  keep  track  of  the  line  count 


//  See  text  for  description  of  tokens 
void  token: :get_token()  ( 
char  c; 

//  This  happens  when  DEscending: 
get next (c) ; 
if  (  c  ==  ' 0' )  ( 

if  (length  ==  0)  {  //  length  0  means  start  of  token 
getnext (c) ; 
switch (c)  ( 

case  //  comment  line 

dumpline ();  //  dump  the  comment 
get_token();  //  get  a  real  token 
break; 

case  'p'  :  case  'P'  :  //  preamble  statement 
if  (  program_section  !=  preamble  ) 
error("only  one  preamble  allowed"); 
dumplineO;  //  just  for  looks,  ignore  it 
get_token();  //  get  a  real  token 
break; 

case  'm'  :  case  'M'  :  //  start  of  main  loop 
dumplineO;  //  toss  rest  of  line 
program_section  =  tmain; 
ttype  =  phase_change; 
return;  //  very  simple  token 
case  'c'  :  case  'C'  :  //  start  conclusion 
dumpline {) ; 

program_section  =  conclusion; 
ttype  =  phase_change; 
return;  //  very  simple  token 
case  'e'  :  case  'E':  //  end  statement 
end_of_file++;  //  set  flag 
ttype  =  fieldnumber;  //  so  destructor  doesn't 
//  delete  free  store  for  this  token, 
if  (if_counter) 

error ("unclosed  'if'  statement (s) ") ; 
return; 
case  ' ('  : 

if  (  program_section  ==  preamble  | I 
program_section  ==  conclusion  ) 
error{"@()  not  allowed  in  preamble  or  conclusion"); 
fieldnum  =  get_value(' ) ' , "0 () ") ; 
ttype  =  fieldnumber; 

//  This  is  a  complete  token,  so  quit 
return; 
case  '<'  : 

c  =  get_value('>' , "@<>") ; 
length++; 

get_token();  //  get  more... 
break; 

case  '?'  :  //  beginning  of  an  "if"  statement 
if  (  program_section  ==  preamble  | | 
program_section  ==  conclusion  ) 
error{"@?  not  allowed  in  preamble  or  conclusion"); 
fieldnum  =  get_value I' @' , "@?@") ; 
ttype  =  if_; 

getnext (c);  //  just  eat  the  colon 

if  (c  !=  ' :') 

error ("@?  must  be  followed  by  0:  (then)"); 
if_level  =  ++if_counter;  //  for  nesting 
return; 

case  "  :  //  the  "else”  part  of  an  "if"  statement 
ttype  =  else_; 
if_level  =  if_counter; 
return; 

case  '.'  :  //  "endif"  terminator  of  an  "if"  statement 
ttype  =  endif_; 
if_level  =  if_counter — ; 
if (if_counter  <  0) 

error ("incorrect  nesting  of  if-then-else  clauses"); 
return; 

case  '0'  :  //  two  '@'  in  a  row  mean  print  an  '@' 
length++;  //  just  leave  '0'  as  the  value  of  c 
get_token () ; 
break; 
default : 

error ("'0'  must  be  followed  by:", 

"'(',  '<',  'p' , 'm' , 'c'  or  '0'"); 

> 

)  else  {  //  an  '@'  in  the  middle  of  a  string;  terminate 
//  the  string.  PutbackO  is  part  of  the  stream  class. 

//  It  is  only  safe  to  put  one  character  back  on  the  input 
tokenstream->putback (c) ;  //  to  be  used  by  the  next  token 
//  allocate  space,  put  the  null  in  and  return  up  the  stack 
literal  =  new  unsigned  char[length  +  1];  //  space  for  ' \0' 
literal [length — ]  =  '\0';  //  string  delimiter 
ttype  =  string;  //  what  kind  of  token  this  is 
return;  //  back  up  the  stack 

1 

)  else  (  //  not  an  '0',  must  be  plain  text 
length++; 
get_token ( )  ; 

) 

//  This  occurs  on  the  "tail"  of  the  recursion: 

literal [length — ]  =  c;  //  put  chars  in  as  we  rise  back  up... 


//  This  function  is  used  by  get_token  when  it  encounters  a  @( 
//  or  a  @<  to  get  a  number  until  it  finds  "delimiter." 

//  If  an  error  occurs,  msg  is  used  to  notify  the  user  what 
//  kind  of  statement  it  is. 

unsigned  char  token: :get_value( char  delimiter,  char  *  msg)  ( 
char  c; 
char  buf[5]; 
int  i  =  0; 

while (getnext (c) ,  c  !=  delimiter)  ( 
if  ( ! isdigit (e) ) 

error ("must  use  only  digits  inside",  msg); 


buf[i++]  =  c; 

} 

buf[i]  =  0; 
return  atoi(buf); 

} 

void  token: : dumpline ()  {  //  called  when  '0!'  encountered 
char  c; 

while (getnext (c) ,  c  !=  '  \n' ) 

;  //  just  eat  characters  until  newline 

} 

//  Since  there' s  no  way  to  know  how  big  a  parse_array  is 
//  going  to  be  until  the  entire  tawkfile  has  been  tokenized, 
//  the  recursive  approach  is  again  used: 

parse_array : :parse_array (istream  &  input)  ( 
parsestream  =  fiinput; 
token_count  =  0; 

p_section  =  program_section;  //  so  we  know  at  run-time 
build_array ( ) ; 


void  parse_array: :build_array ()  { 

token  *  tk  =  new  token (*parse_stream) ; 

if (  !  end_of_file  &&  tk->token_type ()  !=  phase_change)  ( 

//  normal  token,  not  end  of  file  or  phase  change: 
token_count++; 

//  recursively  get  tokens  until  eof  or  phase  change: 
build_array () ; 

)  else  (  //  end  of  file  or  phase  change 
//  only  done  once  per  object: 

//  allocate  memory  and  return  up  the  stack 
tokenarray  =  new  token  *  [end  =  token_count) ; 
if (token_count)  token_count — ;  //  only  if  non-zero 
return; 

} 

tokenarray [token_count— ]  =  tk;  //  performed  on  the  "tail" 


parse_array : :parse_array ()  ( 
for  (int  i  =  0;  i  <  end;  i++) 
delete  tokenarray [i] ; 
delete  tokenarray; 

) 

token  &  parse_array : :operator [ ] (int  index)  ( 
if  (  index  >=  end  )  ( 

cerr  «  "parse_array  error:  index  "  <<  index 
«  "  out  of  bounds \n"; 
exit  (1) ; 

} 

return  ^tokenarray [index) ; 

) 

End  listing  Seven 


Listing  Eight 

//  TAWK.CXX:  parses  a  tawk  script  and  reads  an  ascii  file; 

//  generates  results  according  to  the  tawk  script. 

//  by  Bruce  Eckel 
#include  "csascii.hxx" 
tinclude  "parse. hxx" 

main  (int  argc,  char  *  argv[])  ( 

int  screen  =  0;  //  flag  set  true  if  screen  output  desired 

if  (argc  <  3)  [ 

cerr  «  "usage:  tawk  tawkfile  datafile\n"  << 

"trailing  -s  pages  output  to  screen"; 
exit  (1) ; 

} 

if  (argc  ==  4)  [ 

if  (argv [3] [0]  !=  '-')  { 

cerr  «  "must  use  '-'  before  trailing  flag\n"; 
exit  (1) ; 

)  else 

if  (argv[3) [1]  !=  's')  ( 

cerr  «  "'s'  is  only  trailing  flag  allowed"; 
exit  (1) ; 

)  else 

screen++;  //  set  screen  output  flag  true 

) 

istream  tawkfile (new  filebuf->open (argv [ 1 ) ,  input)); 
parse_array  Apreamble (tawkfile) ;  //  the  @preamble 

parse_array  Amain (tawkfile) ;  //  the  @main  section 

parse_array  Aconclusion (tawkfile) ;  //  the  0conclusion 
csascii  datafile (argv[2) ) ;  //  make  a  comma -separated  ASCII 
//  object  from  the  second  arg 

// - @preamble  - 

for  (int  i  =  0;  i  <  Apreamble . size () ;  i++) 

cout  «  Apreamble [i] ;  //  preamble  can  only  contain  strings 
if (screen)  { 

//  ANSI  reverse  video  sequence: 
cout  «  chr(27)  «  "[7m"  «  "press  any  key"  « 
chr  (27)  «  ”[0m"; 
getch () ; 

) 

//  -  The  Central  Loop  (@main)  - 

do  {  //  for  each  record  in  the  data  file 

if (screen)  cout  «  chr (27)  «  "[2J";  //  ANSI  clear  screen 
for (int  i  =  0;  i  <  Amain. size {) ;  i++)  ( 
switch (Amain [ i ) .token_type () )  [ 
case  fieldnumber: 

cout  «  datafile (Amain [i] . field_number () ] ; 
break; 

case  string: 

cout  «  Amain [i] ; 
break; 
case  if_: 

int  fn  =  Amain [ i] . f ield_number () ; 

if  (datafile(fn) .size ()  ==  0)  f  //  conditional  false 
int  level  =  Amain [i] .nesting_level () ; 

//  find  the  "else"  statement  on  the  same  level: 
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while  (  ! (Amain [i] .token  type()  ==  else 

&&  Amain [i] .nesting  level ()  ==  level)) 
i++; 

Listing  One  (Text  begins  on  page  63  ) 

)  //  conditional  true  —  just  continue 
break; 

on  openCard 

case  else  :  //  an  "if"  conditional  was  true  so  skip 

—  draw  the  crosshair  at  400,  200  when  card  is 

//  all  the  statements  in  the  "else"  clause 

—  first  displayed 

int  level  =  Amain [i] .nesting  level (); 

global  oldH,  oldV 

//  find  the  "endif"  statement  on  the  same  level: 

—  keep  location  of  crosshair  in  global  vars 

while  (  ! (Amain [i] .token  type()  ==  endif 

put  400  into  oldH 

&&  Amain [i] .nesting  level ()  ==  level)) 

put  200  into  oldV 

i++; 

choose  brush  tool 

break; 

set  the  brush  to  4 

case  endif  :  //  after  performing  the  "else"  clause 

set  the  pattern  to  22 

break;  //  ignore  it;  only  used  to  find  the  end 

drag  from  oldH-8,oldV  to  oldH+8,oldV 

//of  the  conditional  when  "if"  is  true. 

drag  from  oldH,oldV-8  to  oldH,oldV+8 

default:  //  should  never  happen  (caught  in  parsing) 

choose  browse  tool 

cerr  <<  "unknown  statement  encountered  at  run-time\n"; 
exit  (1) ; 

end  openCard 

} 

on  mouseup 

) 

—  erase  crosshair  where  it  was 

if (screen)  ( 

—  draw  crosshair  at  new  location 

cout  «  chr(27)  «  ”[7m"  « 

global  oldH,  oldV 

"press  a  key  (ESC  quits)"  «  chr(27)  «  "(Om"; 

choose  eraser  tool 

if (  getch{)  ==  27)  break; 

) 

drag  from  oldH-8,oldV  to  oldH+8,oldV 
drag  from  oldH,oldV-8  to  oldH,oldV+8 

)  while  (datafile. next () ) ;  //  matches  do  (  ... 

choose  brush  tool 

//  - @conclusion - - 

set  the  brush  to  4 

for  (  i  =  0;  i  <  Aconclusion. size () ;  i++) 

set  the  pattern  to  22 

cout  «  Aconclusion [i] ;  //conclusion  contains  only  strings 

) 

get  the  mouseH 
put  it  in  oldH 
get  the  mouseV 
put  it  in  oldV 

End  Listing  Eight 

drag  from  oldH-8,oldV  to  oldH+8,oldV 
drag  from  oldH,oldV-8  to  oldH,oldV+8 

Listing  Nine 

choose  browse  tool 
end  mouseUp 

#  makefile  for  tawk.exe  &  lookup.exe 

#  Zortech  C++: 

CPP  =  ztc 

End  Listing  One 

#  Glockenspiel  C++  w/  MSC  4: 

#CPP  =  ccxx  ! 4 

all:  tawk.exe  lookup.exe 

Listing  Two 

tawk.exe  :  tawk.obj  parse. obj  csascii.obj  field. obj 

5 (CPP)  tawk.obj  parse. obj  csascii.obj  field. obj 

lookup.exe  :  lookup. cxx  csascii.obj  field. obj 

$  (CPP )  lookup. cxx  csascii.obj  field. obj 

XMoveTo  x,y 

—  x  and  y  are  coordinates  in  pixels  in  the  usual 

—  QuickDraw  coordinate  system. 

XLineTo  x,y, pen, mode 

—  x  and  y  are  coordinates  as  for  XMoveTo;  pen  is 

tawk.obj  :  tawk.cxx  parse. hxx  csascii.hxx  field. hxx 

—  the  number  of  a  QuickDraw  pen  pattern,  selected 

$  (CPP)  -c  tawk.cxx 

—  from  the  system  pattern  list  as  shown  on  page  1-474 

—  of  Inside  Macintosh;  mode  is  0  to  erase  and  1  to 

parse. obj  :  parse. cxx  parse. hxx 
$ {CPP )  -c  parse. cxx 

—  draw.  If  mode  is  omitted,  it  is  presumed  to  be  1 

—  (draw);  if  pen  is  omitted,  it  is  presumed  to  be  1 

—  (solid  black) . 

csascii.obj  :  csascii.cxx  csascii.hxx  field. hxx 

$(CPP)  -c  csascii.cxx 

field. obj  :  field. cxx  field. hxx 

End  Listing  Two 

$  (CPP )  -c  field. cxx 

End  Listing  Nine 

Listing  Ten 

Listing  Three 

on  openCard 

--  draw  crosshair  at  400,  200  when  card  is 

@!  REFORM. TWK 

--  first  displayed 

0!  A  tawk  script  to  reformat  a  comma-separated  ASCII  file 

global  oldX,  oldY 

0!  with  6  fields.  This  creates  a  new  CS-ASCII  file  with 

—  maintain  position  of  crosshair  in  global  var 

@!  fields  4  and  5  combined. 

put  400  in  oldX 

0main 

put  200  in  oldY 

"0  (0)  ",  "0  (1) ",  "0  (2)  ",  "@  (3)  ",  "@  (4)  @?4@:  00.0  (5)  " 

XMoveTo  oldX-8,oldY 

@conclusion 

XLineTo  oldX+8, oldY, 4 , 1 

0end 

XMoveTo  oldX, oldY-8 

XLineTo  oldX, oldY+8, 4 , 1 

End  Listing  Ten 

end  openCard 

on  mouseUp 

--  erase  former  crosshair  and  draw  new  crosshair 

Listing  Eleven 

—  at  position  of  mouse-click 
global  oldX,  oldY 

--  erase  former  crosshair;  pattern  4  (gray); 

—  mode  0  (erase) . 

@!  WALLET. TWK 

XMoveTo  oldX-8,  oldY 

@!  Tawkfile  to  create  a  tiny  phone  listing  for  a  wallet 

XLineTo  oldX+8,  oldY, 4,0 

@ !  on  a  Hewlett-Packard  Laser jet-compatible  printer 

XMoveTo  oldX,  oldY- 8 

0!  From  a  comma-separated  ASCII  file  generated  by  a  DBMS 

XLineTo  oldX,  oldY+8,4,0 

@preamble 

—  draw  new  crosshair;  pattern  4  (gray). 

@<27>&15C@!  approximately  10  lines  per  inch 

@<27> (sl6 . 66H@ !  small  typeface,  built  into  Laser  jet 

put  the  mouseH  in  oldX 

0main 

put  the  mouseV  in  oldY 

@!  last,  first,  (area  code)  phonel 

XMoveTo  oldX-8,oldY 

@(0), @(1)  (0(2)  )@?30:@(3) 

XLineTo  oldX+8, oldY, 4 , 1 

0  phone2,  if  it  exists 

XMoveTo  oldX, oldY-8 

0?4@:@  (4) 

XLineTo  oldX,oldY+8, 4, 1 

@0 .00740  :@  (4) 

0 

@.@. 0conclusion 

@<27>E  0!  Reset  the  Laser jet 

@end 

end  mouseUp 

End  Listing  Three 

End  Listings 
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Listing  Four 

♦include  <Types.h> 

♦include  <MemoryMgr .h> 

♦include  <OSUtil.h> 

♦  include  QuickDraw. h> 

♦include  "XCmd.h" 
pascal  void  main(paramPtr) 

XCmdBlockPtr  paramPtr; 

( 

short  x,y; 

Str31  str; 

/*  There  are  two  parameters  to  the  XCMD  XMoveTo: 

*  the  x  and  y  coordinates  no  which  to  move.  These 

*  are  found  as  C-strings  (null-terminated 

*  strings),  converted  to  Pascal-strings,  and  then 

*  to  integers.  There  must  be  just  two  parameters; 

*  if  there  are  more  or  less,  nothing  happens. 

*/ 

if  (paramFtr->paramCount  ==  2) 

{ 

ZeroToPas (paramPtr, 

(char  *) * (paramPtr->params (0] ) , 

(StringPtr) Sstr) ; 
x  =  StrToNum (paramPtr,  Sstr); 

ZeroToPas (paramPtr, 

(char  *) * (paramPtr->params(l) ) , 

(StringPtr) Sstr) ; 
y  =  StrToNum (paramPtr,  Sstr); 

MoveTo(x,  y) ; 

) 

) 


End  Listing  Four 


Listing  Five 

♦include  <Types.h> 

♦include  <MemoryMgr .h> 

♦include  <OSUtil.h> 

♦  include  QuickDraw. h> 

♦include  "XCmd.h" 
pascal  void  main (paramPtr) 

XCmdBlockPtr  paramPter; 

{ 

short  x,  y,  pat,  mode; 

Str31  str; 

Pattern  thePattern; 

PenState  oldPenState; 

/*  There  are  four  possible  parameters;  two  are 

*  required.  The  first  two  (required)  are  the 

*  x  and  y  coordinates  to  which  to  draw.  The 

*  third  is  the  pattern,  taken  from  SysPatList, 

*  (see  Inside  Macintosh  1-474);  the  fourth  is 

*  the  mode  (0  =  erase,  1  =  draw) .  The  four 

*  parameters  are  found  as  C-strings  (null- 

*  terminated  strings),  converted  to  Pascal- 

*  strings,  and  then  to  short  integers.  If  the 

*  fourth  parameter  is  omitted,  it  is  presumed 

*  to  be  "1"  for  draw.  If  the  third  parameter 

*  is  also  omitted,  it  is  presumed  to  be  "1"  for 

*  black.  If  there  are  fewer  than  2  or  more  than 

*  4  parameters,  nothing  happens. 

*/ 

if  ( (paramPtr->paramCount  <  2)  || 

(paramPtr->paramCount  >  4))  return; 

ZeroToPas (paramPtr,  (char  *) * (paramPtr->params [0] ) , 
(StringPtr) Sstr) ; 
x  =  StrToNum  (paramPtr,  Sstr); 

ZeroToPas  (paramPtr,  (char  *)  MparamPtr->params  ( 1] ) , 
(StringPtr) Sstr) ; 
y  =  StrToNum (paramPtr,  sstr); 
if  (paramPtr->paramCount  <  3) 
pat  =  1; 

else 

{ 

ZeroToPas (paramPtr, 

(char  *) * (paramPtr->params [2] ) , (StringPtr) Sstr) ; 
pat  =  StrToNum(paramPtr,  Sstr); 

) 

if  (paramPtr->paramCount  <  4) 
mode  =  1; 

else 


ZeroToPas (paramPtr, 

(char  *) * (paramPtr->params[3) ) , 
(StringPtr) Sstr) ; 
mode  =  StrToNum (paramPtr,  Sstr); 

) 


/*  preserve  former  pen  state  */ 

GetPenState (SoldPenState) ; 

/*  set  pen  state  to  our  pattern  and  mode  */ 
GetlndPattern (SthePattern,  0,  pat); 

PenPat (thePattern) ; 
if  (mode)  PenMode (patCopy) ; 
else  PenMode (patBic) ; 

/*  draw  the  line  */ 

LineTo(x,  y) ; 

/*  restore  pen  state  */ 

SetPenState (SoldPenState) ; 

} 


End  Listing  Five 


Listing  Six 

/* 

XBox  —  a  HyperCard  user-defined  command  in  C. 

J.  M.  Anderson,  1988 
All  Rights  Reserved. 

This  XCMD  draws  a  rectangle. 

*/ 

♦include  <Types.h> 

♦include  <MemoryMgr .h> 

♦include  <OSUtil.h> 

♦include  <QuickDraw ,h> 

♦include  "XCmd.h" 

/*  ****  WARNING:  DO  NOT  USE  GLOBAL  VARIABLES!  ****  */ 

pascal  void  main (paramPtr) 

XCmdBlockPtr  paramPtr; 

{ 

short  x,  y,  u,  v,  pat,  mode; 

Rect  box; 

Str31  str; 

Pattern  thePattern; 

PenState  oldPenState; 

/*  The  six  parameters  are  the  x  and  y  coordinates  of 

*  the  upper  left  corner  of  the  box,  its  width  and 

*  height, the  pattern  (taken  from  the  SysPatList) 

*  and  the  mode  with  which  to  draw.  These  are  found 

*  as  C-strings,  converted  to  P-strings,  and  then  to 

*  numbers.  The  "mode"  is  either  0  to  erase  or  1  to 

*  draw.  There  may  be  four,  five,  or  six 

*  parameters.  If  the  sixth  parameter  is  omitted,  it 

*  is  presumed  to  be  "1"  for  draw.  If  the  fifth 

*  parameter  is  omitted, it  is  presumed  to  be  "1"  for 

*  black.  The  x  and  y  coordinates  and  sizes  u  and  v 

*  must  be  present.  If  there  are  fewer  than  4  or  r 

*  than  6  parameters,  nothing  happens. 

*/ 

if  ( (paramPtr->paramCount  <  4)  | | 

(paramPtr->paramCount  >  6) )  return; 

ZeroToPas (paramPtr, (char  *) 

* (paramPtr->params (0) ) , (StringPtr) sstr) ; 
x  =  StrToNumfparamPtr,  sstr) ; 

ZeroToPas (paramPtr,  (char  *) 

* (paramPtr->params [ 1) ) , (StringPtr) sstr)  ; 
y  =  StrToNum(paramPtr,  sstr)  ; 

ZeroToPas (paramPtr, (char  *) 

* (paramPtr->params [2] ) , (StringPtr) Sstr) ; 
u  =  StrToNum (paramPtr,  Sstr)  ; 

ZeroToPas (paramPtr,  (char  *) 

* (paramPtr->params [3] ) , (StringPtr) Sstr) ; 
v  =  StrToNum (paramPtr,  Sstr) ; 
if  (paramPtr->paramCount  <  5) 
pat  =  1; 

else 

I 

ZeroToPas (paramPtr, (char  *) 

* (paramPtr->params [4] ) , (StringPtr) Sstr) ; 
pat  =  StrToNum (paramPtr, Sstr) ; 

) 

if  (paramPtr->paramCount  <  6) 
mode  =  1; 

else 

I 

ZeroToPas (paramPtr,  (char  *) 

* (paramPtr->params [5] ) , (StringPtr) Sstr) ; 
mode  =  StrToNum (paramPtr, sstr) ; 

} 

/*  preserve  pen  state  */ 

GetPenState (SoldPenState)  ; 

/*  set  pen  state  to  our  pattern  and  mode  */ 
GetlndPattern (SthePattern,  0,  pat); 

PenPat (thePattern) ; 
if  (mode)  PenMode (patCopy) ; 
else  PenMode (patBic) ; 

/*  draw  the  box  */ 

SetRect (Sbox,  x,  y,  x+u,  y+v) ; 

PaintRect (Sbox) ; 

/*  restore  the  pen  state  */ 

SetPenState (SoldPenState) ; 


Listing  Seven 

on  mouseUp 

—  Effect  animation  of  a  small  black  rectangle.  This 

—  card  is  blank;  the  next  card  has  a  small  black 

—  rectangle  painted  on  the  card  at  location  298,  167. 

—  draw  and  erase  many  times  a  QuickDraw  black 

—  rectangle;  its  location  starts  at  the  left  edge 

—  of  the  card  (x  =  5) ,  and  167  pixels  down.  It 

—  moves  to  x  =  298,  y  =  167. 
put  3  into  x 

repeat  while  x  <  298 

XBox  x,  167,  10,  10,  1,  1  —  draw 

XBox  x-5,  167,  10,  10,  1,  0  —  erase 
put  x  +  5  into  x 
end  repeat 

—  now  show  next  card  with  rectangle  painted  in  place 
go  to  next  card 
end  mouseUp 


End  Listing  Six 


End  Listings 
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PROGRAMMING  PARADIGMS 


A  Decade  Later 


Each  year,  The  Association  for  Com¬ 
puting  Machinery  (ACM)  gives  its 
Turing  Award  to  a  computer  scien¬ 
tist  who  has  earned  distinction 
for  technical  contributions  of  lasting 
and  major  importance  to  the  field  of 
computer  science.  The  recipients 
through  1985  were  Charles  Bachman, 
John  Backus,  E.F.  Codd,  Stephen  Cook, 
EdsgerDijkstra,  Robert  Floyd,  R.W.  Ham¬ 
ming,  C.A.R.  Hoare,  Kenneth  Iverson, 
Richard  Karp,  Donald  Knuth,  John  Mc¬ 
Carthy,  Marvin  Minsky,  Allen  Newell, 
Alan  J.  Perlis,  Michael  O.  Rabin,  Dennis 
Ritchie,  Dana  S.  Scott,  Herbert  Simon, 
Ken  Thompson,  Maurice  V.  Wilkes,  J. 
H.  Wilkinson,  and  Niklaus  Wirth. 

I  list  them  all  here  not  only  because 
they  all  deserve  recognition,  but  also 
to  give  a  sense  of  the  range  of  contribu¬ 
tions  honored,  from  Minsky’s  AI  work 
to  Codd’s  creation  of  the  relational  da¬ 
tabase  model,  from  Hoare’s  founda¬ 
tional  work  in  axiomatic  semantics  to 
Ritchie  and  Thompson’s  creation  of  C 
and  Unix. 

Clearly,  recognition  is  not  solely  re¬ 
stricted  to  abstract,  academic  achieve¬ 
ments.  And  in  fact  the  Turing  Award 
lectures,  delivered  by  the  recipients  at 
annual  conferences  of  the  ACM,  usu¬ 
ally  stress-broad  issues  of  concern  to 
all  programmers.  These  lectures  have 
been  collected  in  a  great  book  ACM 
Turing  Award  Lectures:  The  First  Twenty 


Michael  Swaine 


Years:  1966-1985,  Addison  Wesley,  1987. 

The  1978  Turing  Award  went  to 
Robert  Floyd  for  his  work  in  the  foun¬ 
dations  of  the  theory  of  parsing,  pro¬ 
gramming  language  semantics,  the  auto¬ 
mation  of  program  synthesis  and  verifi¬ 
cation,  and  the  analysis  of  algorithms. 

It  was  Floyd’s  Turing  Award  lecture, 
The  Paradigms  of  Programming,  that 
inspired  this  column.  In  that  lecture, 


he  cited  inadequacies  in  our  store  of 
programming  paradigms,  in  our  knowl¬ 
edge  of  existing  paradigms,  in  the  way 
we  teach  paradigms,  and  in  the  way 
our  languages  support  the  paradigms 
of  their  user  communities.  Recently  I 
talked  with  Professor  Floyd  about  his 
thinking  in  the  area  of  programming 
paradigms  a  decade  after  the  lecture. 

Swaine:  In  this  column,  I’ve  talked 
about  paradigms  generally  at  the  level 
of  the  programming  language  implemen¬ 
tation.  But  you’re  really  not  working 
with  different  paradigms  at  that  level, 
are  you? 

Floyd:  No,  I  do  most  of  my  program¬ 
ming  in  Pascal.  There  are  paradigms 
on  all  scales. 

On  one  end  of  the  scale  you  have  the 
paradigm  that’s  embodied  in  a  language: 
object-oriented  programming  and  func¬ 
tional  programming  and  logic  program¬ 
ming  and  all  these  things.  At  the  other 
extreme  there  are  things  that  would  be 
substantial  conveniences  right  down  at 
the  micro  level,  like  having  parallel  as¬ 
signment.  Then  there’s  the  intermediate 
level,  the  paragraph  of  programming. 

Swaine:  How  would  you  characterize 
your  work  today? 

Floyd:  My  own  programming  efforts 
for  a  very  long  time  have  been  con¬ 
cerned  with  programming  in  the  small 
rather  than  in  the  large.  The  programs 
I  write  myself  seldom  go  more  than 
four  pages  of  Pascal.  Typically,  I’m  con¬ 
cerned  with  getting  the  very  good  ten-to- 
fifty-line  program  for  a  mathematically 
sharply-defined  task.  I  spend  a  lot  of 
my  time  deducing  the  mathematical  char¬ 
acteristics  that  the  solution  has  to  have 
and  substantially  less  time  working  out 
how  the  mathematical  objects  will  be 
represented  as  data  structures  and  how 
the  coding  will  go.  I  don’t  face  the 


software  engineering  problems  of  pro¬ 
gramming  in  the  large. 

Swaine:  You  work  more  at  the  para¬ 
graph  level?  Can  you  cite  some  exam¬ 
ples  of  these  paragraph -level  paradigms? 

Floyd:  A  couple  of  those  that  are  rea¬ 
sonably  well  known  that  I  can  mention 
as  typical  are  dynamic  programming 
and  branch-and-bound  algorithms. 
Then  I  use  various  subject-matter  ori¬ 
ented  paradigms.  Statistical  sampling 
is  an  example  of  that. 

Swaine:  I  think  you  'll  have  to  explain 
how  statistical  sampling  can  be  a  pro¬ 
gramming  paradigm. 

Floyd:  There  are  problems  that  are  not 
in  themselves  statistical  problems  but 
where  you  can  improve  the  perform¬ 
ance  of  an  algorithm  by  taking  a  ran¬ 
dom  sample  of  the  data  set  and  pre- 
computing  something  for  that,  in  ef¬ 
fect,  gives  you  an  estimate  of  what 
your  final  result  is  going  to  be. 

The  algorithm  that  Ron  Rivest  and  I 
developed  for  calculating  the  median 
and  other  quantiles  is  an  example  of 
that.  Random  sampling  is  in  no  way 
required,  but  it  turns  out  to  be  the  way 
that  we  got  an  algorithm  that  appears 
to  be  asymptotically  close  to  the  maxi¬ 
mum  efficiency,  and  I  don't  think  any¬ 
body  has  discovered  a  non-sampling 
algorithm  that  can  accomplish  that. 

Here’s  another  example.  I  have  a 
mathematical  sample  that  is  quite  tightly 
clustered,  where  the  mean  is  very  large 
compared  to  the  standard  deviation, 
and  I  want  to  calculate  the  standard 
deviation  very  precisely.  The  obvious 
ways  of  calculating  standard  deviation 
are  numerically  rather  dangerous.  Not 
only  can  they  be  very  inaccurate,  but 
the  cumulative  effect  of  rounding  er¬ 
rors  can  very  easily  lead  to  your  taking 
the  square  root  of  a  negative  number. 
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One  way  to  attack  that  problem  would 
be  to  take  a  random  subset  of  the  data, 
using  that  get  an  estimate  of  the  mean, 
then  to  run  through  the  entire  data  set, 
subtracting  that  estimate  off  all  the  data. 
That  doesn’t  change  the  standard  de¬ 
viation,  but  it  does  scale  the  data  down 
in  magnitude  so  that  the  variations  among 
them  are  now  large  compared  to  the 
data  themselves.  And  that  makes  the 
problem  numerically  well  conditioned. 

Swaine:  So  in  one  case  you’ve  used 
sampling  to  produce  an  efficient  algo¬ 
rithm,  and  in  another  case  to  improve 
accuracy ? 

Floyd:  Yes,  that  kind  of  use  of  sam¬ 
pling  is  a  general  paradigm.  I’ve  used 
it  in  lots  of  areas  that  are  not  necessar¬ 
ily  terribly  close  to  one  another.  It’s 
obviously  not  something  that’s  going 
to  be  put  forward  as  a  way  to  solve  all 
the  world’s  problems,  the  way  that  func¬ 
tional  programming  and  such  are  pre¬ 
sented  as  the  universal  solvent.  But  I 
think  that  the  high-level  programmer 
is  going  to  need  to  know  a  lot  of  these 
paradigms  on  the  intermediate  scale, 
the  scale  of  the  sentence  and  the  para¬ 
graph  rather  than  the  scale  of  the  page 
and  the  book. 

Swaine:  One  paradigm  that  some  have 
put  forth  as  the  universal  solvent  is 
structured  programming.  You  describe 
it  in  your  Turing  Award  lecture  as 
“ the  dominant  paradigm  in  most  cur¬ 
rent  treatments  of  programming  meth¬ 
odology.  ”  But  it  has  its  detractors: 
Rich  Gabriel  at  Software  Development 
88  last  year  said  something  to  the 
effect  that  structured  programming  had 
done  more  damage  to  programmers’ 
thought  processes  than  the  GOTO  state¬ 
ment. 

Floyd:  I  don’t  know  why  Rich  would 
have  said  that. 

Swaine:  Don ’t  take  the  quote  too  seri¬ 
ously;  I’m  misquoting  from  memory. 
But  where  do  you  stand  on  structured 
programming  today? 

Floyd:  As  I  said  in  the  lecture:  “Its  firmest 
advocates  would  acknowledge  that  it 
does  not  by  itself  suffice  to  make  all 
hard  problems  easy.”  An  example  where 
the  top-down  structured  programming 
approach  doesn’t  work  very  effectively 
is  the  eight  queens  problem.  Wirth  tack¬ 
led  that  in  Program  Development  by 
Stepwise  Refinement,  and  he  got  an 
answer,  but  it’s  a  real  kludge.  There’s 
an  earlier  paper  of  mine  that  solved  it 
using  a  non-deterministic  paradigm.  You 
write  a  program  for  an  imaginary  non- 
deterministic  computer  that  makes  ar¬ 


bitrary  choices  in  deciding  where  to 
put  the  queens  on  the  chessboard,  but 
also  makes  tests  to  see  if  it’s  still  on 
track,  to  see  if  it’s  violated  any  rules 
yet,  and  aborts  if  it  has  made  any  mis¬ 
takes.  Then  that  can  be  macro-expanded 
into  a  backtracking  program  that  backs 
up  wherever  the  original  program  would 
have  aborted,  and  systematically 
searches  the  entire  space  of  choices. 

The  program  that  you  write  as  a  non- 
deterministic  program  is  very  simple 
and  is  itself  within  the  classical  top- 
down  discipline,  but  the  macro  expan¬ 
sion  from  it  produces  a  program  in 
which  the  loops  don't  nest.  If  you 
looked  directly  at  the  result  from  the 
macro  expansion  you’d  say  that  there’s 
no  structure  here,  this  is  a  kludge,  this 
is  hacking.  But  there  is  a  conceptual 
structure  in  the  sense  that  it’s  the  result 
of  a  simple  transformation  from  a  sim¬ 
ple  formulation. 

That’s  the  kind  of  thing  that  makes 
me  think  of  the  top-down  viewpoint 
as  excessively  limited.  It  has  its  uses, 
but  within  that  framework  there  are 
some  thoughts  that  are  too  complicated 
to  think. 

Swaine:  In  your  lecture,  you  dismiss 
the  idea  that  automatic  programming 
will  solve  the  so-called  software  crisis. 
Is  there  any  more  promise  there  today? 

Floyd:  I  don’t  think  that  there  is  going 
to  be  any  universal  solvent  for  pro¬ 
gramming.  Programming  is  hard. 

There  has  been  some  interesting  work 
on  automatic  program  generation.  Cor¬ 
dell  Green  has  concentrated  on  algo- 

Was  it  Euclid  who  said 
“There  is  no  royal  road 
to  geometry?”  There  is 
no  royal  road  to 
programming 

rithms  for  sorting  and  searching.  He 
estimates  that  a  program  to  come  close 
to  human  performance  in  this  area  has 
to  simply  know  a  lot  of  facts  that  a 
skilled  programmer  in  this  area  would 
know.  The  number  of  facts  is  on  the 
order  of  five  hundred. 

So  one  can’t  expect  to  march  up  to 
a  completely  naive  computer  and  give 
it  a  problem  and  expect  it  to  come  out 


with  a  really  neat  program.  Because 
really  neat  programs  are  based  on  a  lot 
of  world  knowledge. 

I  am  sure  that  what  he  found  in  his 
subject  matter  you  would  find  in  any 
subject  matter  that  people  want  to  ap¬ 
ply  programming  to.  I  know  that  if  you 
want  to  do  sophisticated  graphic  pro¬ 
gramming,  there’s  a  lot  that  you  have 
to  know  about  computational  geome¬ 
try  and  appropriate  representation  and 
algorithms  for  triangulation. 

These  things  don’t  invoke  a  software 
crisis.  These  things  are  problems  typi¬ 
cally  at  the  scale  of  the  programs  that  I 
have  been  talking  about,  that  fit  on  a 
page  or  so.  But  they  are  hard.  You 
have  to  know  a  lot  and  be  able  to  use 
that  knowledge  in  order  to  be  able  to 
do  these  things  well. 

Was  it  Euclid  who  said  “There  is  no 
royal  road  to  geometry?”  There  is  no 
royal  road  to  programming.  Program¬ 
ming  is  hard.  On  the  other  hand,  there 
are  problems  that  look  very  hard,  but 
if  you  have  the  appropriate  paradigm 
they  become  easy. 

Swaine:  For  example? 

Floyd:  In  the  context  of  a  spelling 
checker,  I’ve  got  a  misspelled  word, 
and  I  want  to  compare  it  to  a  word  from 
the  dictionary,  to  measure  how  differ¬ 
ent  they  are.  I’m  looking  for  the  most 
similar  word  in  the  dictionary;  which 
is  to  say  I  want  to  know  the  minimum 
number  of  editing  operations,  from  a 
limited  set  of  editing  operations,  that 
will  convert  the  one  word  into  the  other. 

Years  ago  I  gave  that  as  a  final  pro¬ 
ject  in  a  programming  course  in  which 
I  hadn’t  talked  about  dynamic  program¬ 
ming,  and  nobody  got  anywhere  with 
it.  Those  who  did  it  ended  up  limiting 
themselves  very  severely ,  restricting  them¬ 
selves  to  looking  at  one  or  two  editing 
operations.  But  if  you  formulate  it  as  a 
dynamic  programming  problem  where 
the  subproblems  are  to  measure  the 
difference  between  every  prefix  of  the 
one  word  and  every  prefix  of  the  other, 
and  you  go  through  those  in  increasing 
length  of  these  prefixes,  it’s  a  very  straight¬ 
forward  problem.  Ten  or  twenty  lines 
does  it.  I  could  write  it  in  half  an  hour 
and  have  time  left  over  to  trim  my  nails. 

Swaine:  What  general  paradigm  do 
you  find  most  useful  in  your  work? 
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Floyd:  In  my  programming,  I  try  to  find 
mathematical  characterizations  of  what 
I’m  looking  for,  to  limit  my  search  space. 

You’re  familiar  with  loops  that  you 
have  to  go  through  n  plus  one-half 
times?  For  example,  you’re  processing 
a  data  set  and  one  of  the  data  is 
a  sentinel.  You  have  to  read  all  the 
n+1  data,  but  the  processing  part 
omits  the  sentinel.  That  can  be  very 
difficult  to  explain  to  a  novice  pro¬ 
grammer. 

Swaine:  And  yet  it’s  something  that  nov¬ 
ice  programmers  run  into  immediately. 

Floyd:  Very  definitely.  Well,  they  can 
deduce  from  the  statement  of  the  prob¬ 
lem  some  things  that  tell  them  that  their 
programs  are  going  to  need  some  things 
that  they  might  not  guess.  It’s  plausible 
that  the  program  is  going  to  use  some 
kind  of  iteration,  and  that  the  process¬ 
ing  step  is  going  to  be  inside  the  loop 
so  that  they  can  do  it  as  many  times  as 
they  need  to.  But  they’re  only  going  to 
process  n  items,  while  they  need  to 
read  n+1  items.  From  this  they  can 
deduce  that  there  has  to  be  a  read 
outside  the  loop  or  they  have  to  have 
some  conditional  branching  inside  the 
loop.  And  when  they  argue  that  the 
test  that  controls  the  loop  is  going  to 
have  to  always  have  one  datum  avail¬ 
able  to  it,  that  tells  them  that  they  need 
one  read  outside  the  loop,  and  in  par¬ 
ticular  before  the  loop.  And  if  they’re 
going  to  alternate  between  reading  and 
processing,  that  tells  them  that  inside 
the  loop,  they  need  first  to  process  and 
then  to  read,  which  is  contrary  to  what 
they’d  expect. 

So  by  just  some  logical  reasoning 
you  characterize  the  kind  of  program 
you  need  well  enough  that  your  search 
space  is  starting  to  get  quite  reason¬ 
able,  even  if  you  are  a  novice. 

Swaine:  Speaking  of  novices ,  one  of 
the  emphases  of  your  Turing  Award 
lecture  was  on  the  way  in  which  we 
educate  people  about  programming.  It 
strikes  me  that  American  education 
generally  shortchanges  students  on  the 
paradigm  level  when  dealing  with  tech¬ 
nical  and  quantitative  matters.  Most 
people  don’t  even  know  how  to  check 
results  for  plausibility . 

Floyd:  Right.  They  come  out  of  school 
never  having  learned  to  subject  their 
answers  to  plausibility  checks.  A  good 
many  schools  seem  to  adopt  an  ap¬ 
proach  to  mathematical  problem  solv¬ 
ing  that  shows  the  student  how  to  turn 
himself  into  a  machine.  And  machines 
don’t  worry  about  the  plausibility  of 
their  results. 


Swaine:  I  suppose  that  implementing 
plausibility  checks  in  a  programming 
language  would  be  something  of  a  chal¬ 
lenge. 

Floyd:  Well,  you  could  have  a  lan¬ 
guage  in  which  every  datum  had  di¬ 
mension,  and  the  type  checking  in¬ 
cluded  dimension  checking,  so  that  you 
couldn’t  add  feet  to  square  feet  and  if 
you  added  feet  to  yards  an  automatic 
conversion  took  place.  It  would  be  fairly 
straightforward  to  incorporate  that  in 

A  good  many  schools 
seem  to  adopt  an  ap¬ 
proach  to  mathematical 
problem  solving  that 
shows  the  student  how 
to  turn  himself  into  a 
machine 


a  programming  language  if  you  wanted 
to  do  it. 

Or  you  could  write  a  programming 
language  for  banks.  Banks  neither  cre¬ 
ate  nor  destroy  money,  and  their 
programs  should  embody  that  fact.  The 
programmer  should  not  be  able  to  make 
money  disappear,  because  if  there’s 
money  disappearing  in  the  program, 
the  chances  are  there’s  real  money 
disappearing. 

Swaine:  That  sounds  useful.  But  to 
get  back  to  education,  where  do  para¬ 
digms  fit  into  the  computer  science 
curriculum? 

Floyd:  Paradigms  are  not  something 
you  could  have  a  separate  course  about. 
They  fit  in  by  getting  professors  to  talk 
explicitly  about  the  paradigms  that  they 
use  in  the  particular  subject  discipline 
in  which  they’re  lecturing. 

Swaine:  It's  appealing  to  believe  that 
we  could  educate  and  excite  new  pro¬ 
grammers  about  programming  through 
the  concepts  and  paradigms  of  pro¬ 
gramming  as  effectively  as  we  now  do 
through  that  sense  of  power  or  mastery 
or  relief  or  whatever  it  is  that  they  get 
when  they  finally  make  the  machine 
do  what  they  want.  I  assume  you  ’re 
doing  that  in  your  courses.  How  do  you 
go  about  it? 


Floyd:  Right  now  I’m  teaching  a  course 
in  searching  and  sorting  out  of  Knuth 
Volume  3,  which  is  a  huge  compen¬ 
dium  of  great  algorithms  in  that  area 
and  analyses  of  their  performance,  but 
which  to  my  mind  lacks  a  unifying 
viewpoint.  What  I  use  as  the  unifying 
viewpoint  is  the  idea  that  every  prob¬ 
lem  in  that  domain  has  a  certain  inher¬ 
ent  difficulty  that  I  call  its  entropy;  the 
formula  from  information  theory  and 
thermodynamics  that  gives  you  that. 
So  I  use  an  information-and-entropy 
paradigm  to  get  an  overall  viewpoint. 

Because  of  the  way  in 
which  programmers 
acquire  what  they 
know,  they  often  don ’t 
know  what  they  know; 
they  can ’t  articulate  it 
in  any  general  terms 


Swaine:  How  do  you  do  that? 

Floyd:  In  these  sorting  and  searching 
programs,  you  are  extracting  informa¬ 
tion  from  data  sets.  The  program  makes 
various  queries  of  the  data,  and  each 
query  gathers  a  certain  amount  of  in¬ 
formation,  and  you  can  derive  a  for¬ 
mula  for  that.  Then  you  can  character¬ 
ize  the  algorithms  by  the  rate  at  which 
they  gather  relevant  information,  and 
divide  that  into  the  entropy  of  the  origi¬ 
nal  problem  to  get  the  time  that  it’s 
going  to  take. 

A  well  known  case  is  that  you’re 
sorting  a  data  set  and  the  incoming 
order  of  the  data  is  random.  Then  each 
of  the  possible  reorderings  is  equally 
likely  and  has  probability  1/n!  and  the 
entropy  of  that  problem  turns  out  to 
be  log  of  nl  and,  applying  Sterling’s 
approximation  you  end  up  with  n  log 
n.  This  tells  you  that  any  method  that 
you  apply  that  only  extracts  one  bit  of 
information  per  step  will  necessarily 
need  time  proportional  to  n  log  n  to 
determine  the  right  permutation  to  re¬ 
order  the  data. 

They  go  up  in  sophistication  from 
there,  but  one  can  view  most  sorting 
and  searching  problems,  and  some  other 
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(continued  from  page  1 12) 
problems  like  problems  of  large-scale 
movement  of  information  in  memory, 
from  an  information-and-entropy  view¬ 
point.  And  you’ll  end  up  not  only  hav¬ 
ing  some  insight  into  whether  an  algo¬ 
rithm  is  efficient  as  a  whole,  but  you’ll 
also  have  a  microscope  with  which 
you  can  look  at  each  phase  of  an  algo¬ 
rithm  and  ask,  What’s  its  information- 
theoretic  efficiency?  Is  there  room  in 
there  for  potential  improvement? 

Swaine:  Are  there  books  on  paradigms 
or  problem  solving  that  you  admire ? 

Floyd:  In  one  of  your  columns  you  cite 
George  Polya’s  How  to  Solve  It,  but  to 
my  mind  the  great  one  is  his  two- 
volume  Patterns  of  Plausible  Inference. 
In  it,  he  deals  with  several  tough  prob¬ 
lems  from  the  history  of  mathematics, 
such  as  the  isoperimetric  inequality. 
When  you  read  Polya  you  not  only 
leam  about  paradigms,  you  learn  some¬ 
thing  about  the  subject  matter. 

Educating  programmers  is  only  part 
of  the  business  of  educating  people 
about  programming.  It  strikes  me  as 
plausible  that  the  level  of  paradigms 
might  be  the  appropriate  level  for  talk¬ 
ing  to  intelligent  non-programmers 
about  what  programming  is  about.  But 
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that  doesn’t  seem  to  happen  at  all. 

Because  of  the  way  in  which  pro¬ 
grammers  acquire  what  they  know,  they 
often  don’t  know  what  they  know;  they 
can’t  articulate  it  in  any  general  terms. 

Swaine:  I  just  read  an  article  that  ad¬ 
dresses  exactly  that.  It  was  the  public 
lecture  that  Tony  Hoare  gave  on  his 
induction  to  one  of  the  professorships 
he  held.  He  was  describing  adapting 
the  Quicksort  algorithm  to  find  a  par¬ 
ticular  quantile,  and  he  illustrated  it 
by  hand  using  cards  with  numbers 
printed  on  them.  The  whole  thing  was 
nonmath ematical  and  directed  at  an 
audience  that  was  not  at  all  familiar 
with  the  shoptalk  of  computing.  It's  in 
a  book  that  just  came  out:  Lectures  in 
Computer  Science,  Hoare  et  al,  from 
Prentice-Hall,  1989. 

Floyd:  There  have  only  been  a  few 
good  essays  of  that  sort  directed  at  the 
layperson.  All  too  often,  if  they  don’t 
think  that  the  computer  is  an  electronic 
brain,  they  think  that  it’s  a  glorified 
adding  machine. 

Swaine:  You  certainly  staked  out  the 
high  ground  in  your  Turing  Award 
lecture.  What  do  you  think  the  impact 
of  the  speech  has  been ? 


Floyd:  The  lecture  had  very  little  ob¬ 
servable  effect.  It’s  been  cited  very  little 
in  the  literature;  I’ve  checked  that 
through  science  citation  indices,  and 
most  of  the  citation  has  been  periph¬ 
eral:  citation  of  specific  examples  or 
problems,  rather  than  concerned  with 
the  thesis.  My  overall  feeling  is  that  the 
world  has  not  advanced  very  much  in 
that  direction. 

Swaine:  Perhaps  this  interview  will  give 
the  world  a  tiny  nudge  in  that  direc¬ 
tion.  It  occurs  to  me  that,  although 
we’ve  used  the  word  paradigm  liber¬ 
ally,  we  haven 't  really  defined  it  except 
through  example.  Maybe  that’s  the  best 
way  to  define  it.  But  could  you  give  one 
more  example  of  a  paradigm? 

Floyd:  In  high  school  you  probably 
learned  to  solve  quadratic  equations 
by  completing  the  square.  The  theo¬ 
rem  says,  You  can  complete  the  square. 
The  paradigm  says,  In  a  lot  of  situ¬ 
ations  you  ought  to  complete  the  square. 


DDJ 


Vote  for  your  favorite  feature/article. 
Circle  Reader  Service  No.  9. 


Dr.  Dobb’s Journal,  May  1989 
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SI:  A  C-Like  Script 
Interpreter 


This  month  we  begin  the  construc¬ 
tion  of  a  script  interpreter  for  the 
SMALLCOM  communications  pro¬ 
gram.  A  script  is  a  command  lan¬ 
guage  that  allows  a  communications 
program  to  automatically  interact  with 
an  online  service.  The  language  we’ll 
use  for  this  project  is  a  subset  of  C,  so 
the  interpreter  looks  a  lot  like  a  tradi¬ 
tional  C  language  interpreter.  For  this 
phase  of  the  project  we  will  build  an 
interpreter  “engine,”  one  that  we  can 
use  to  interpret  C-like  statements  for 
general  purposes.  This  month  we’ll  con¬ 
centrate  on  the  engine.  Later  we’ll  inte¬ 
grate  it  into  SMALLCOM  as  a  script 
interpreter  and  try  out  some  scripts. 

SMALLCOM  manages  the  connection 
with  remote  computers  running  online 
services,  bulletin  boards,  other  com¬ 
munications  programs,  or  SMALLCOM 
itself.  Most  such  remote  programs  in¬ 
volve  sign-on  sequences  where  the  call¬ 
ers  identify  themselves,  and  the  remote 
program  grants  or  denies  access.  Once 
the  caller  gets  in,  a  command  language 
gives  access  to  electronic  mail,  confer¬ 
ences,  forums,  files  to  download,  and 
places  to  upload  files.  Virtually  every 
such  service  is  unique  with  respect  to 
its  sign-on  sequence  and  command  lan¬ 
guage.  Most  BBSs  use  one  of  the  popu¬ 
lar  BBS  programs  (RBBS,  FIDO,  and 
so  on),  but  have  their  own  file  and 
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forum  architecture.  The  online  services 
are  usually  made  of  custom  software 
and  have  their  own  proprietary  com¬ 
mand  languages. 

The  command  languages  share  one 
trait:  They  are  designed  to  be  under¬ 
stood  by  people  in  an  interactive  dia¬ 
logue.  This  approach  makes  the  serv¬ 
ices  available  to  users  with  terminals 
and  modems  as  well  as  to  those  with 


personal  computers.  The  PC  users  have 
an  advantage.  They  can  use  their  PCs 
to  automate  routine  parts  of  the  dia¬ 
logue.  If  you  can  execute  the  sign-on, 
move  into  the  forum  of  your  choice, 
send  your  messages,  capture  messages 
from  other  members,  and  all  at  the 
speed  of  the  modem,  then  you  have 
saved  connect  charges.  A  shareware 
program  named  TAPCIS  automates  this 
procedure  for  CompuServe.  Other  serv¬ 
ices  are  supported  by  scripts  in  share¬ 
ware  and  commercial  communications 
programs.  A  general-purpose  commu¬ 
nications  program  that  uses  a  script 
must  have  a  script  processor. 

Let’s  examine  the  requirements  for 
a  communications  script.  Once  you  have 
connected  with  a  service,  the  script 
processor  watches  the  input  stream  and 
waits  for  one  or  more  character  se¬ 
quences.  When  one  appears,  the  proc¬ 
essor  makes  a  decision.  Perhaps  it  sends 
a  character  sequence  to  the  service.  It 
might  tell  the  service  to  execute  com¬ 
mands,  such  as  to  upload  or  download 
files.  When  the  script  processor  de¬ 
cides  that  the  online  tasks  are  done,  it 
disconnects.  These  actions  are  the  same 
ones  you  would  take  if  you  signed  on 
and  did  the  typing  yourself.  You  could 
hard-code  the  decisions,  character  se¬ 
quences,  and  commands  into  a  dedi¬ 
cated  script  processor  such  as  the  one 
in  TAPCIS,  or  you  could  develop  a 
general-purpose  script  processor  that 
uses  an  external  script  file  such  as  is 
done  by  ProComm.  Our  script  proces¬ 
sor  will  use  an  external  interpreted  script 
language  that  resembles  C.  We  call  the 
script  language  “S”  and  the  script  proc¬ 
essor  program  the  “S  Interpreter,”  or 
simply  SI. 

Si’s  operation  will  be  mostly  trans¬ 
parent  to  the  rest  of  SMALLCOM.  It  will 
be  invoked  when  you  dial  a  service 
that  has  a  script  named  in  the  SMALL¬ 
COM  phone  directory.  SI  will  use  the 


waitforstring  function  in  SMALLCOM 
to  watch  for  character  sequences,  in¬ 
terceding  when  required.  To  emulate 
the  user’s  keystrokes,  SI  will  stuff  the 
characters  it  wants  to  type  into  the  BIOS 
keyboard  buffer.  These  characters  will 
then  be  returned  to  the  program  as  if 
they  had  been  keyed  by  the  user. 

The  S  Language 

S  is  a  subset  of  C.  If  you  know  C  you 
know  S  once  you  learn  what  the  subset 
includes.  I  chose  this  approach  for  three 
reasons.  First,  the  syntax  of  C  is  easily 
processed  by  an  interpreter.  Second, 
the  decision-making  properties  of  a  com¬ 
munications  script  processor  are  well 
supported  by  C’s  structured  program¬ 
ming  features.  Third,  this  is  the  “C  Pro¬ 
gramming”  column,  and  we  all  know 
C  to  one  degree  or  another.  Why  wres¬ 
tle  with  a  new  language? 

The  S  syntax  differs  from  C  in  these 
ways:  S  has  two  data  types,  the  int  and 
the  char,  and  the  two  are  usually  syn¬ 
onymous.  Either  one  can  be  declared 
as  a  pointer  or  used  as  a  pointer  by 
reference.  A  variable  works  the  same 
whether  you  declare  it  as  a  pointer  or 
not.  If  you  reference  it  by  name  alone, 
you  get  its  value.  If  you  reference  it 
with  an  asterisk  in  front  of  its  name, 
then  what  the  variable  points  to  is  what 
is  returned.  This  is  weak  typing  to  the 
extreme  and  follows  in  the  waning  spirit 
of  the  earliest  C  compilers.  All  pointers 
are  treated  as  character  pointers.  You 
can  code  a  pointer-to-pointer  reference 
but  it  will  not  work.  All  variables  are 
treated  as  integers  except  in  the  case 
where  the  char  type  is  used  in  an  array 
of  char  pointers  like  this: 

char  *mylist[  ]={  "password?" ,  "offline" } ; 

This  format  is  valid  only  in  the  global, 
external  scope.  Scope  rules  in  S  are  the 
same  as  those  in  C. 
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S  has  no  other  arrays,  structures,  or 
unions.  It  supports  decimal  and  hex 
constants  and  lets  you  code  string  liter¬ 
als  as  parameters  to  functions  or  identi¬ 
fiers  to  ints  or  chars  (which  then  be¬ 
come  implied  character  pointers).  You 
build  a  script  consisting  of  a  main  func¬ 
tion  and  subordinate  functions  of  your 
own.  S  provides  for  a  library  of  intrinsic 
functions  that  support  the  environment 
the  interpreter  will  support. 

All  global  variables,  except  function 
parameters,  are  by  default,  static  and 
extern.  All  local  variables  are  auto.  Be¬ 
cause  these  scopes  are  defaults,  S  does 
not  recognize  the  keywords.  There  are 
no  shifts,  bitwise  logical  operators,  con¬ 
tinue,  do,  goto,  typedef,  switch,  casts, 
prototypes,  or  function  declarations.  The 
<expr>?<expr>:<expr>  operation  is  not 
supported.  The  <op>=  operators  (+=, 
-=,  etc.)  are  not  supported.  Every  func¬ 
tion  is  assumed  to  return  an  int  unless 
it  returns  nothing.  The  unary  +  and  - 
operators  and  the  ones-complement  op¬ 
erator  are  not  supported.  There  is  no 
preprocessor. 

S  includes  for,  while,  break,  return, 
if,  else,  brace  surrounded  statement 
blocks,  recursion,  the  &&  and  !  !  op¬ 
erators  and  the  !  (not)  and  &  (address 
of)  operators.  The  relational  operators 
=  =,  !=,  <,  >,  <=,  and  >=  are  supported. 
Comments  are  the  same  as  in  C. 

Intrinsic  Functions 

An  implementation  of  SI  must  provide 
a  library  of  intrinsic  functions.  These 
are  not  functions  such  as  you  would 
have  in  an  object  library  or  in  inter¬ 
preted  source  code,  but  ones  that  are 
built  into  the  interpreter  itself.  Intrinsic 
functions  are  what  give  the  generic 
interpreter  its  intended  functionality. 
SI  is  built  under  a  shell  program  that 
includes  the  intrinsic  functions,  provides 
an  array  of  structures  that  describes  the 
intrinsic  functions,  manages  the  source 
code  file  and  errors,  and  executes  the 
three  phases  of  the  interpreter. 

The  S  Interpreter 

The  SI  interpreter  code  is  built  to 
be  reusable.  We  will  separate  those 
parts  of  SI  that  are  script  specific  into  a 
shell  code  module  so  that  the  inter¬ 
preter  can  be  used  for  other  purposes. 
For  example,  we  might  add  a  macro 
processor  to  the  editor.  By  isolating  the 
interpreter  from  its  original  purpose, 
we  leave  the  door  open  for  its  use  in 
other  areas. 

Listing  One,  page  138,  is  interp.h,  a 
header  file  that  an  application  shell 
will  use  to  implement  the  interpreter. 
The  first  several  items  are  configura¬ 
tion  global  macros  that  you  set  to  the 
values  that  define  limits  for  the  inter¬ 


preter.  The  first  such  global,  TOK- 
BUFSIZE,  defines  the  number  of  char¬ 
acters  in  the  token  buffer.  Each  S  key¬ 
word  and  operator  is  translated  into  a 
token.  Each  identifier  and  string  is  kept 
in  the  token  buffer.  Each  newline  char¬ 
acter  in  the  source  stream  is  recorded 
in  the  buffer  with  a  newline  token  and 
a  three  character  line  number.  If  you 
get  the  error  that  says  the  token  buffer 
has  overflowed,  you  will  need  to  in¬ 
crease  the  TOKBUFSIZE  global  or 
shorten  the  source  file.  The  MAXSYM- 
BOLS  global  controls  how  many  sym¬ 
bols  can  be  in  the  symbol  table  at  a 
given  time.  This  maximum  is  equal  to 
the  total  number  of  functions  and  ex¬ 
ternal  globals  with  any  local  automatics 
that  are  in  scope.  As  locals  go  out  of 
scope,  they  are  removed  from  the  sym¬ 
bol  table  and  their  entries  are  reused. 
MAXSTRINGS  is  the  maximum  number 
of  strings  that  can  appear  in  external 
character  pointer  arrays.  MAXPARAMS 
is  the  maximum  number  of  parameters 
a  function  can  have. 

The  error  codes  are  defined  as  an 
enumerated  data  type.  SI  is  managed 
by  a  shell  program,  an  example  of  which 
is  described  later.  The  shell  provides 
all  error  processing  and  must  react  to 
these  codes.  The  shell  also  provides 
the  table  of  intrinsic  functions.  The  for¬ 
mat  for  entries  in  that  table  is  described 
by  the  INTRINSIC  structure. 

Interp.h  defines  the  format  of  the 
symbol  table,  which  is  a  structure  with 
four  elements.  The  symbol  table  has 
an  entry  for  each  function  and  variable 
in  the  source  file.  The  table  entry  in¬ 
cludes  a  pointer  to  the  symbol’s  name. 
If  the  symbol  is  a  function,  the  entry 
has  a  pointer  to  the  location  in  the 
token  buffer  of  the  start  of  the  func¬ 
tion’s  tokens.  If  the  symbol  is  an  array 
of  character  pointers,  the  table-  has  a 
pointer  to  the  array.  If  the  symbol  is 
an  integer  or  pointer,  the  table  has  an 
entry  that  contains  the  symbol’s  value. 
Pointers  in  S  are  always  equivalent  to 
integers.  Finally,  interp.h  contains  func¬ 
tion  prototypes  and  external  references 
to  the  critical  data  items  produced  by 
the  lexical  scan  and  linker.  These  refer¬ 
ences  will  allow  a  shell  to  record  the 
pseudocompiled  tokens  for  repeated 
interpreting  later. 

Listing  Two,  page  138,  is  interp.c, 
the  core  of  the  interpreter.  You  would 
link  this  program  with  a  shell  that  man¬ 
ages  the  source  file  and  user  interface 
and  provides  the  intrinsic  functions  that 
give  SI  its  purpose.  These  functions  are 
described  later. 

Interpreting  the  S  language  involves 
these  three  steps.  First,  the  source  file 
is  read  and  the  statements  are  trans¬ 
lated  into  tokens  in  the  token  buffer. 


In  traditional  language  processing  this 
step  is  called  the  lexical  scan.  The  load- 
source  function  in  interp.c  starts  the 
lexical  scan.  If  the  lexical  scanner  finds 
a  character  sequence  in  the  source  file 
that  it  cannot  recognize,  it  declares 
an  error  and  quits.  During  the  lexical 
scan,  source  file  line  number  tokens 
are  inserted  into  the  token  buffer.  These 
line  number  tokens  identify  the  source 
file  lines  when  errors  occur.  If  anyone 
ever  writes  a  debugger  for  the  S  lan¬ 
guage,  these  line  numbers  might  be 
useful. 

When  loadsource  has  successfully 
loaded  the  source  file  and  translated  it 
into  lexical  tokens,  loadsource  calls  the 
linker  function.  The  linker  scans  the 
token  buffer  and  builds  the  global  sym¬ 
bol  table,  which  contains  the  names 
and  locations  of  functions  and  the 
names  and  values  of  variables.  When 
the  linker  finds  errors  in  the  S  grammar 
the  scan  terminates.  Following  this  step 
the  three  data  structures,  the  token 
buffer,  string  space,  and  symbol  table 
could  be  written  to  a  file  for  later 
interpretation.  SI,  as  we  build  it  here, 
will  not  take  that  intermediate  step 
but  will  move  directly  into  the  inter¬ 
preter.  We  do,  however,  provide  for 
that  feature  in  case  we  should  want 
it  later.  An  editor  macro  interpreter 
would  probably  use  the  compile-now- 
interpret-later  strategy  to  speed  up  the 
process. 

After  the  linker  is  finished,  loadsource 
returns  to  its  caller,  the  applications 
shell  program  that  must  start  the  inter¬ 
preter  by  calling  the  interpreter  macro 
defined  in  interp.h.  This  macro  sets  up 
a  pseudotoken  buffer  with  a  tokenized 
call  to  the  main  function  of  the  S  lan¬ 
guage  source  program.  The  macro  calls 
function  in  the  interpreter  and  gets  the 
main  function  underway.  This  proce¬ 
dure  interprets  the  tokens,  executes  the 
language,  and  parses  the  S  grammar 
for  errors.  Obviously,  scripts  should 
be  tested  before  they  are  used  on  an 
expensive  long-distance  hookup. 

Interpreting  begins  in  function  to 
execute  the  S  main.  All  subsequent  S 
function  calls  come  through  here,  so 
the  process  is  recursive.  First,  the  inter¬ 
preter  looks  for  a  parameter  list  in 
the  function  call.  Each  parameter  is 
evaluated  by  the  expression  function, 
and  its  value  is  stored  in  an  array  of 
incoming  parameters.  Then  the  inter¬ 
preter  searches  the  table  of  intrinsic 
functions  to  see  if  the  function  is  one 
of  them.  If  so,  the  interpreter  calls  the 
intrinsic  function  through  its  pointer 
in  the  INTRINSIC  structure  array  in  the 
shell.  If  not,  the  interpreter  searches 
the  global  symbol  table  for  the  called 
function  and  points  the  token  pointer 
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to  the  beginning  of  that  function.  The 
parameters  named  in  the  function  dec¬ 
laration  go  into  the  local  symbol  table 
and  the  parameter  values  from  the  caller 
go  into  the  value  elements  of  the  new 
local  symbols.  The  interpreter  now  be¬ 
gins  interpreting  the  function’s  proce¬ 
dure  by  calling  the  compound_state- 
ment  function. 

The  compound_statement  function 
processes  brace  surrounded  statement 
blocks.  It  adds  variables  within  the  block 
to  the  local  symbol  table  and  then  exe¬ 
cutes  each  statement  in  the  block  by 
calling  the  statementsfunction.  The  state¬ 
ments  function  calls  compound_state- 
ment  recursively  if  it  finds  another  left 
brace  in  the  token  stream.  Otherwise 
it  calls  the  statement  function. 

The  statement  function  processes  if, 
while,  for,  return,  break,  and  simple 
expression  statements.  The  first  three 
operators  involve  expression  evaluation 
and  executing  or  skipping  blocks  oftoken- 
ized  statements.  The  return  and  break 
set  flags  to  be  sensed  by  subsequent 
statements.  Simple  expressions  are  evalu¬ 
ated  by  the  expression  function. 

SI  evaluates  expressions  with  a  re¬ 
cursive  descent  parsing  algorithm.  The 
precedence  of  operators  is  controlled 
by  the  position  of  the  operators’  proc¬ 
essing  functions  in  the  recursive  de¬ 
scent  function  chain.  You  can  trace  the 
progress  of  this  chain  by  beginning 
with  the  expression  function.  This  algo¬ 
rithm  expects  the  program  token  pointer 
variable,  tptr,  to  point  to  the  first  token 
of  an  expression.  When  the  expression 
function  returns  the  evaluated  result, 
the  pointer  will  point  to  the  first  token 
past  the  expression.  First  the  expres¬ 
sion  function  calls  the  and  function  to 
get  its  result.  Then,  as  long  as  there  are 
logical  ortokens  in  the  expression,  the 
result  is  ORed  with  subsequent  results 
from  the  and  function.  Looking  up  at 
the  and  function,  you  can  see  that  it 
has  a  similar  relationship  with  the  eq 
function  above  it.  All  these  operator 
functions  trace  up  the  chain  of  prece¬ 
dence  to  the  primary  function,  which 
evaluates  a  primary  element  of  an  ex¬ 
pression.  A  primary  element  is  a  con¬ 
stant,  pointer,  or  variable.  If,  however, 
the  primary  function  finds  a  left  paren¬ 
thesis  as  the  next  token,  the  primary 
function  starts  the  evaluation  all  over 
again  by  first  calling  expression  and 
then  requiring  a  right  parenthesis.  The 
primary  function  handles  the  NOT  op¬ 
erator,  the  pointer  operator,  the  address- 
of  operator,  and  auto-increment  and 
decrement  operators.  Each  function  in 
the  precedence  chain  returns  its  result 
to  the  function  below  it  until  control  is 
back  at  the  expression  function.  If  you 
wanted  to  change  the  precedence  of 


operators,  you  would  change  the  se¬ 
quence  of  these  functions  in  the  chain. 
When  two  or  more  operators  have  the 
same  precedence,  as  do  multiply  and 
divide,  they  are  processed  together  in 
the  same  function  and  have  left-to- 
right  precedence  because  the  token  scan 
is  in  that  direction. 

The  SI  Shell 

Listing  Three,  page  142,  is  si.c,  a  throw¬ 
away  demonstration  shell  that  lets  you 
test  SI.  It  illustrates  how  an  application 
would  be  integrated  with  the  interpreter 
and  has  three  intrinsic  functions:  printf 
getchar,  and  putchar.  An  SI  shell  pro¬ 
gram  has  four  responsibilities.  First,  the 
shell  must  provide  the  intrinsic  func¬ 
tions  and  the  array  of  INTRINSIC  struc¬ 
tures  that  describes  them.  Second,  the 
shell  must  manage  the  S  source  code 
file  by  providing  the  functions  named 
getsource  and  ungetsource,  which  the 
interpreter  calls  to  get  and  push  back 
characters  from  and  to  the  source  file. 
This  way  the  interpreter  does  not  care 
whether  the  code  comes  from  a  file  or 
an  edit  buffer.  Third,  the  shell  must 
execute  the  interpreter  by  calling  get¬ 
source  and  interpreter  in  that  order. 
Finally,  the  shell  must  provide  the  sier- 
rarfunction  to  manage  the  errors  found 
by  the  interpreter.  This  strategy  hides 
the  details  of  error  processing  from  the 
interpreter.  The  interpreter  passes  to 
sierror an  error  code,  a  string  that  might 
amplify  the  error  such  as  the  word  be¬ 
ing  parsed  when  the  error  occurred, 
and  the  source  code  line  number  where 
the  error  was  found. 

Another  C  Interpreter 

For  a  look  at  a  different  approach  to  a 
subset  C  interpreter,  watch  for  the  DDJ 
annual  C  issue  in  August.  Well-known 
C  author  Herbert  Schildt  has  contrib¬ 
uted  an  article  that  includes  such  a 
program.  While  our  S  interpreter  is  in¬ 
tended  to  be  an  engine  for  interpreting 
C-like  script  languages,  Schildt’s  is  ori¬ 
ented  to  the  execution  of  C  source 
programs  and  is  offered  as  a  study  in 
interpreter  design  and  implementation. 
You  will  see  many  similarities  in  our 
approaches,  perhaps  because  interpreter 
theory  is  well-defined  and  understood. 
We  selected  different  subsets  of  C,  and 
some  of  our  terminology  differs,  but 
the  principles  are  similar. 

QuickC  2.0:  Worth  Another  Look 

After  a  year  on  the  market,  QuickC  1.0 
is  replaced  by  QuickC  2.0.  QuickC  1.0 
was  a  compiler  with  plenty  of  bugs  and 
some  design  features  that  hindered  the 
development  environment.  Its  integrated 
environment  limited  you  to  the  medium 
memory  model.  The  .OBJ  files  gener¬ 


ated  by  the  environment  and  the  com¬ 
mand  line  compiler  were  incompatible. 
The  .EXE  files  generated  to  be  run  by 
the  environment  would  not  run  from 
the  command  line.  There  were  known, 
but  unacknowledged  and  unattended 
compiler  bugs  from  the  beginning. 

QuickC  2.0  is  another  story.  Micro¬ 
soft  has  eliminated  the  dubious  fea¬ 
tures  and  seems  to  have  cleared  up  the 
bugs.  QuickC  2.0  is  faster  than  Micro¬ 
soft  C  5.1  but  generates  bigger  pro¬ 
grams.  On  a  20-MHz  386,  QuickC  built 
a  47,481  byte  TWRP.EXE  file  in  1  min¬ 
ute,  14  seconds.  MSC  built  a  35,507 
byte  file  in  2  minutes,  59  seconds. 

The  programs  in  our  “C  Programming” 
column  project  now  compile  correctly 
with  QuickC  2.0.  You  will  recall  from 
January  that  I  had  a  problem  with  one 
module.  The  problem  is  gone  with  2.0. 

Microsoft  changed  the  makefile  syn¬ 
tax  for  their  new  NMAKE  program, 
which  works  more  like  the  traditional 
make  programs  that  programmers  are 
accustomed  to.  If  you  have  the  older 
MAKE  program,  you  can  use  the  make¬ 
files  I  published  by  changing  the  cl 
command  to  the  qcl  command  to  use 
the  QuickC  2.0  command  line  com¬ 
piler.  With  minor  modifications,  the 
makefiles  can  be  adapted  to  NMAKE. 

QuickC  includes  a  book  called  C  For 
Yourself  that  describes  the  C  language 
at  the  introductory  level — at  least  as 
well  as  most  books  you  will  find  at  the 
store.  The  weakness  in  this  book  is  its 
treatment  (or  neglect)  of  the  run-time 
library.  Microsoft  expects  you  to  use 
the  Microsoft  Advisor,  their  on-line  help 
utility,  for  complete  library  reference 
information.  This  assumes  that  you  use 
the  QuickC  editor,  which  many  of  us 
will  not.  QuickC  has  no  equivalent  to 
Turbo  C’s  THELP  program,  which  pops 
up  the  help  data  base  from  inside  your 
own  editor.  You  do  get  the  HELPMAKE 
utility  program  that  lets  you  modify 
and  add  to  the  help  texts.  Third-party 
library  developers  can  provide  help  texts 
that  users  can  integrate  into  their  de¬ 
velopment  environments.  Microsoft 
does  not,  however,  supply  the  format 
of  the  compressed  help  text  database, 
which  a  TSR  developer  would  need  to 
write  a  THELP  clone  for  QuickC. 

ANSI  Answers 

In  January  I  took  Borland  to  task  for 
conforming  to  what  they  said  was  a 
new  ANSI  rule  that  allowed  the  back¬ 
slash  octal  escape  sequence  to  exceed 
three  digits.  The  effect  of  the  rule  was 
that  existing  code  would  no  longer  com¬ 
pile  the  same  way,  and  there  was  no 
warning  message  to  let  you  know. 

No  sooner  had  the  issue  hit  the  stands 
than  I  found  myself  reading  a  letter 
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from  P.J.  Plaugher,  a  member  of  the 
committee,  and  talking  to  Tom  Plum, 
the  vice  chairman.  Both  members  as¬ 
sured  me  in  certain  terms  and  with 
authority  that  the  so-called  rule  was 
not  the  rule  at  all  and  that  tradition 
prevails  with  respect  to  the  octal  es¬ 
cape  sequence.  Discussions  with  Bor¬ 
land  reveal  that  they  genuinely  believed 
they  were  tracking  the  evolving  ANSI 
standard  with  accuracy.  The  misunder¬ 
standing  resulted  from  Borland’s  inter¬ 
pretation  of  the  committee  vote  on 
the  matter.  They  decided  to  conform 
to  the  rule  and  we  had  our  original 
discussions  (and  I  wrote  my  criticism) 
before  the  December  draft  was  pub¬ 
lished.  Now  the  draft  is  out,  and  Borland 
will  fix  the  discrepancy  in  a  future  re¬ 
lease  of  Turbo  C. 

The  consequences  of  the  issue  will 
vary  from  user  to  user.  Those  of  you 
using  Turbo  C  2.0  for  new  software  are 
well-advised  to  avoid  the  octal  escape 
sequence  until  the  problem  is  fixed. 
The  new  ANSI  hex  sequence  works  as 
specified  and  will  do  the  job.  Those  of 
you  using  Turbo  C  2.0  to  compile  exist¬ 
ing  programs  are  counseled  to  watch 
for  the  offending  octal  sequences. 

The  upshot  of  this  episode  is  that  I  am 
now  the  proud  owner  of  a  copy  of  the 
“Draft  Proposed  American  National  Stan¬ 
dard  for  Information  Systems  — Program¬ 
ming  Language  C”  document  dated  De¬ 
cember  7, 1988  and  a  card-carrying  mem¬ 
ber  of  the  X3J11  committee.  Just  in 
time  — their  work  is  done. 

Availability 

All  source  code  for  articles  in  this  issue 
is  available  on  a  single  disk.  To  order, 
send  $14.95  (Calif,  residents  add  sales 
tax)  to  Dr.  Dobb’s Journal,  501  Galves¬ 
ton  Dr.,  Redwood  City,  CA  94063,  or 
call  800-356-2002  (from  inside  Calif.) 
or  800-533-4372  (from  outside  Calif.). 
Please  specify  the  issue  number  and 
format  (MS-DOS,  Macintosh,  Kaypro). 
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Fencing  The  Dog 


If  you  were  awake,  you  noticed  that 
viewports  disappeared  from  the 
GRAFIX  library  during  March  and 
April.  Didn’t  matter  much.  We  hadn’t 
talked  specifically  about  viewports,  so 
I  decided  to  send  them  on  vacation 
while  rethinking  the  whole  subject.  Now 
they’re  back,  ready  to  go. 

In  a  way,  I’m  sorry  I  brought  them 
up  at  all  in  the  first  incarnation  of  the 
GRAFIX  library.  As  so  often  happens 
with  any  programming  project,  I  had 
plans  for  viewports  that  changed  as  the 
project  progressed.  Now  we  have  to 
undo  some  old  damage  before  we  can 
begin  with  the  new. 

Fortunately,  that’s  not  a  Big  Deal.  All 
you  have  to  do  is  delete  a  few  lines 
from  GRAFIX. C.  In  general,  all  refer¬ 
ences  to  the  VUPORT  structure  go. 
Here’s  what  to  do: 

•  About  20  lines  down,  remove  the  four 
lines  beginning  with  the  comment 
“/‘Viewport  structure  */” 

•  About  a  dozen  lines  below  that,  de¬ 
lete  the  two  variables  of  type  VUPORT. 
•  At  about  line  85,  strike  the  statement 
vuport  =  &def_vp; 

•  At  around  old  line  120,  remove 
def_vp.height  =  480; 

Luckily,  that’s  all  there  is  to  it:  an  an¬ 
noyance  rather  than  a  hardship. 

There’s  one  more  thing  you  have  to 
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do  with  GRAFIX.C.  At  the  end  of  the 
init_video( )  function,  just  before  the 
return  statement,  add  the  following: 

if  (mode  =  =  VGA16  &&  vga) 
default_viewport  (480); 

Now  save  GRAFIX.C.  Don’t  recompile 
it  yet,  though,  because  we  have  some 
other  fish  to  fry  first. 


In  a  strategic  sense,  what’s  the  point 
of  all  this?  As  the  project  has  advanced, 
it’s  becoming  rapidly  apparent  that  we 
can’t  keep  adding  stuff  to  GRAFIX.C. 
The  source  file  would  soon  swell  to 
enormous  size  if  we  did.  This  would 
force  us  to  search  through  zillions  of 
functions  to  find  the  one  we  want  and 
to  wait  interminably  during  each  re¬ 
compile.  That’s  the  whole  oomph  be¬ 
hind  the  concept  of  modular  develop¬ 
ment:  Keep  related  things  together  in 
their  own  files. 

So  what  we’ve  done  here  is  to  re¬ 
move  the  VUPORT  references  from 
GRAFIX.C,  where  they  don’t  belong, 
in  preparation  for  constructing  a  new 
viewport  support  file,  where  they  do. 
The  reference  to  default_viewport( ) 
merely  calls  a  viewport  initialization 
function  that  lives  among  its  relatives. 

Now  we  can  bring  in  the  new.  But 
first  let's  consider  the  question  .  .  . 

So  What's  a  Viewport? 

A  viewport  is  to  graphics  what  a  win¬ 
dow  is  to  text:  a  subset  of  the  display 
that  thinks  it’s  an  entire  self-contained 
screen.  After  you  define  a  viewport,  all 
operations  are  confined  within  its 
boundaries,  and  the  coordinate  system 
is  relative  to  the  upper  left  corner. 

For  example,  say  you  define  a  view¬ 
port  with  its  upper  left  corner  at  X=320, 
Y=175.  If  the  device  is  an  EGA,  you 
have  opened  the  viewport  in  the  lower 
right  quadrant.  This  implies  that,  while 
the  viewport  is  active,  everything  above 
and  to  the  left  of  the  display  area  is 
inaccessible.  All  coordinate  references 
thus  become  relative  to  the  viewport’s 
origin.  This  leads  to  the  concept  of 
coordinate  remapping:  A  pixel  written 
at  10,  01  is  automatically  remapped  to 
absolute  location  1320, 175).  Don’t  worry 
right  now  about  how  it’s  done.  We’re 
still  at  the  conceptual  level,  with  me¬ 
chanics  to  follow  later. 

The  second  major  concept  of  view¬ 


ports  is  clipping.  Say  the  viewport  at 
(320,  175)  has  a  width  of  100  pixels  and 
a  height  of  50.  The  right  side  of  the 
viewport  is  therefore  at  x=420  and  the 
bottom  is  at  y=225.  These  coordinates 
form  the  boundaries  of  the  clipping 
region.  You  can’t  write  pixels  outside 
of  them,  just  as  you  can’t  write  pixels 
off-screen. 

The  idea  is  analogous  to  fencing  the 
backyard.  The  dog  can  go  anywhere  it 
wants  within  the  yard,  but  that’s  all 
because  the  fence  defines  the  limits  of 
its  world.  The  dog  can  look  through 
the  fence  and  bark  at  the  cat  on  the 
other  side,  thus  conceiving  of  a  world 
beyond,  but  it  can’t  get  there.  That’s 
dipping. 

If  a  dog  thought  about  such  things, 
it  might  regard  one  corner  of  its  world 
as  point  (0,  0),  with  the  capability  to 
move  100  paces  along  one  axis  and  50 
along  the  other.  The  dog  might  decide 
to  start  at  some  arbitrary  point  and 
walk  200  paces  along  a  straight  line.  It 
could  move  for  some  distance,  but  even¬ 
tually  its  travel  would  be  arrested  — 
that  is,  clipped  — upon  encountering 
the  fence.  The  dog  would  thus  have 
completed  as  much  of  the  actual  jour¬ 
ney  as  possible,  with  the  rest  existing 
only  in  its  imagination. 

Similarly,  we  can  draw  a  line  from  a 
point  within  a  viewport  to  a  point  out¬ 
side  it,  and  the  line  stops  when  it  hits 
the  edge  of  the  clipping  region.  By 
extension,  we  can  also  draw  a  line 
between  two  points,  both  of  which  are 
outside  the  clipping  region,  and  we’ll 
see  only  the  portion  that  actually  falls 
within  the  viewport  it  crosses. 

How?  The  obvious  place  to  control 
remapping  and  clipping  is  at  the  pixel¬ 
writing  level.  In  DRAWPT.ASM  (Listing 
One,  page  143)  the  magic  happens  be¬ 
tween  lines  24  and  43.  This  passage  of 
code  points  ES:BX  at  the  current  view¬ 
port  structure,  then  compares  the  X 
and  Y  coordinates  with  the  width  and 
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(continued  from  page  124) 
height,  respectively.  If  either  is  outside 
the  viewport,  the  code  jumps  to  the 
exit,  thus  inhibiting  a  pixel  write.  When 
both  coordinates  are  inside  the  view¬ 
port,  lines  39-43  remap  the  viewport 
coordinates  to  absolute  screen  coordi¬ 
nates  relative  to  the  viewport’s  origin. 
HLINE.ASM  (Listing  Two,  page  143) 
performs  similar  clipping  and  remap¬ 
ping  in  lines  63-82. 

These  routines  could  be  made  more 
robust.  For  example,  both  assume  that 

The  real  work  of 
coordinate  remapping 
and  clipping  is  done 
by  the  two  pixel-writing 
routines 


the  coordinates  are  in  the  positive  do¬ 
main,  and  so  don’t  check  for  coordi¬ 
nates  to  the  left  of  or  above  the  view¬ 
port  origin  (either  of  which  would  be 
negative  values).  The  intent  here  is  to 
show  how  it  works,  so  I’ve  deliberately 
omitted  the  extensive  validity  checks 
that  rightfully  characterize  industrial- 
grade  software. 

Note  that  I’ve  added  a  short  “hack” 
to  each  routine  (lines  76  -  79  in 
DRAWPT.ASM  and  lines  104-107  in 
HLINE.ASM).  These  enhancements  pro¬ 
gram  the  graphics  chip  to  replace  af¬ 
fected  pixels.  The  6845  can  also  per¬ 
form  bitwise  operations  (AND,  OR, 
XOR)  on  pixels.  By  setting  bits  3  and  4 
of  the  6845’s  Data  Rotate/Function  Se¬ 
lect  register  to  zeros,  you  tell  the  chip 
not  to  perform  any  of  these  special 
color  effects,  but  instead  to  change  the 
affected  pixel  to  the  new  value  without 
gamesmanship. 

Make  sure  line  14  in  each  assembly- 
language  routine  reads  as  shown  in  the 
listings,  then  reassemble  them.  You  can 
implement  the  enhanced  versions  in 
your  copy  of  GRAFIX.LIB  with  the  com¬ 
mand 

LIB  grafix  — t-drawpt  — i-hline; 

Now  we’re  ready  to  take  on  viewports 
themselves. 

Bring  In  The  New! 

The  real  work  of  coordinate  remap¬ 


ping  and  clipping  is  done  by  the  two 
pixel-writing  routines.  A  viewport  de¬ 
scriptor  is  itself  a  rather  simple  struc¬ 
ture  defining  the  origin  coordinates, 
width,  and  height.  However,  programs 
shouldn’t  have  to  concern  themselves 
with  viewport  management,  instead  deal¬ 
ing  with  strategic  issues.  Consequently 
the  new  VUPORT.C  module  defines 
eight  functions  for  operating  on  view¬ 
ports,  relieving  applications  of  the  de¬ 
tails  and  even  hiding  the  descriptor 
structure  itself. 

The  overall  thrust  of  the  VUPORT 
module  is  to  treat  viewports  in  a  man¬ 
ner  analogous  to  files.  Like  a  file,  a 
given  viewport  has  a  handle  (type 
VP_HAN)  assigned  at  its  birth  and  re¬ 
maining  with  it  during  its  lifetime.  The 
library  module  provides  functions  to 
open  and  close  viewports,  to  switch 
among  existing  viewports,  and  to  make 
inquiries. 

Listing  Three,  page  146,  shows  the 
additions  to  GRAFIX. H,  the  library 
header  file,  to  define  the  new  viewport 
functions.  After  appending  these  en¬ 
tries  to  the  end  of  the  header  file,  re- 
ccompile  GRAFIX.C,  then  put  it  into 
the  library  with  the  command 

LIB  grafix  — tgrafix; 

VUPORT.C  in  Listing  Four,  page  146, 
provides  the  source  for  the  new  rou¬ 
tines.  Compile  it,  then  add  it  to  the 
library  with 

LIB  grafix  +vuport; 

Now  let’s  examine  the  VUPORT  mod¬ 
ule  to  see  what  it  does. 

The  VPNODE  structure  at  the  top  of 
the  file  defines  a  viewport  descriptor 
node  to  be  used  in  a  dynamic  list. 
Several  of  the  functions  manage  this 
list,  which  contains  information  about 
the  viewports  your  program  opens.  In 
addition,  the  module  maintains  the  de¬ 
fault  viewport  definition  def_up,  which 
describes  the  display  as  a  whole,  and 
the  wtportvariable,  which  always  points 
to  the  descriptor  for  the  currently  ac¬ 
tive  viewport. 

The  default_viewport( )  function  is 
called  by  init_video( )  from  GRAFIX.C 
to  change  the  default  viewport’s  height. 
The  default  structure  is  born  with  a 
height  of  350  pixels  (EGA).  The  call 
from  init_video( )  automatically  adjusts 
the  height  to  480  when  the  graphics 
mode  is  VGA  640  x  480.  Though  acces¬ 
sible  to  your  programs,  there  is  little 
reason  for  them  to  call  the  de- 
fault_viewport(  )  function. 

The  vp_open( )  routine  creates  a  new 
viewport.  The  XY  position  of  the  upper 
left  comer  is  expressed  in  absolute  co- 
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ordinates  and  is  not  relative  to  the  cur¬ 
rently  active  viewport.  Upon  comple¬ 
tion  of  the  routine,  the  newly  opened 
viewport  is  the  active  one  and  subse¬ 
quent  drawing  occurs  within  it.  Like 
the  familiar  file  open( )  function, 
vp_open( )  returns  a  handle  identifying 
the  viewport.  Handles  are  integers  work¬ 
ing  upward  from  1 ;  the  0  handle  refers 
to  the  default  full-screen  viewport  de¬ 
fined  in  def_vp. 

vp_open( )  adds  the  new  viewport 
to  a  doubly  linked  dynamic  list,  to  which 
the  vplist  variable  acts  as  a  head  pointer. 
The  list  contains  descriptor  nodes  for 
all  user-defined  viewports  that  currently 
exist.  A  new  viewport  is  appended  at 
the  tail  and  assigned  a  handle  numeri¬ 
cally  one  greater  than  that  of  the  old 
tail.  The  routine  makes  the  new  view¬ 
port  active  by  repointing  the  vuport 
variable  to  it,  and  then  returns  the 
handle. 

You  can  switch  around  among  exist¬ 
ing  viewports  by  calling  vpjuseC ).  The 
argument  is  a  handle  identifying  the 
desired  viewport,  or  0  for  the  full¬ 
screen  default.  This  routine  searches 
the  viewport  list  for  a  node  whose  han¬ 
dle  matches  the  non-zero  argument, 
returning  TRUE  or  FALSE  to  indicate 
the  outcome.  When  successful,  vp 
_use( )  repoints  the  vuport  variable  to 
the  indicated  viewport  descriptor,  thus 
activating  it.  Subsequent  pixel  opera¬ 
tions  occur  relative  to  the  selected 
viewport. 

A  viewport  ceases  to  exist  when  you 
pass  its  nonzero  handle  to  vp_close( ). 
The  act  of  closing  entails  removing  the 
descriptor  node  from  the  viewport  list. 
The  routine  does  this  by  searching  for 
the  handle,  then  rearranging  the  neigh¬ 
bors’  pointers  to  bypass  the  closed  node. 
This  has  the  effect  of  pinching  the  node 
out  of  the  list.  The  memory  space  can 
then  be  freed.  vp_close( )  also  checks 
the  closed  node  against  the  global  tplist 
and  vuport  pointers.  If  you’ve  closed 
the  head  node,  its  successor  is  pro¬ 
moted  to  the  head  of  the  list,  and  if 
you’ve  closed  the  active  node,  the  de¬ 
fault  node  becomes  active. 

Viewports  are  handy  for  confining 
drawing  activity  to  a  certain  part  of  the 
screen,  and  for  dynamically  placing  vis¬ 
ual  objects  according  to  conditions  en¬ 
countered  at  runtime.  Another  use  is 
analogous  to  text  windows,  in  which 
a  region  of  the  screen  is  set  aside  for 
some  purpose  such  as  displaying  a 
graph.  In  the  latter  case,  programmers 
usually  want  to  make  the  viewport  visu¬ 
ally  distinctive  by  outlining  it.  That’s 
the  purpose  of  the  vp_outline() 
function. 

vp_outline( )  draws  a  rectangle  in 
the  current  foreground  color.  The  bor¬ 


der  is  immediately  outside  the  view¬ 
port  itself,  so  that  it  doesn’t  impinge 
on  the  drawing  area  or  get  clobbered 
by  activity  inside  the  viewport.  The 
viewport  to  be  outlined  doesn’t  have 
to  be  active  at  the  time,  but  it  must  be 
open  inasmuch  as  the  function  requires 
a  valid  handle.  After  calculating  the 
border’s  location  and  dimensions,  vp_out- 
line( )  switches  to  full-screen  mode  and 
draws  the  outline,  then  reinstates  the 
former  active  viewport. 

The  library  routines  hide  the  struc¬ 
ture  of  the  viewport  descriptor  from 
applications.  Consequently  some  way 
must  be  available  for  programs  to  in¬ 
quire  about  important  characteristics 
of  the  current  viewport:  its  handle  and 
dimensions.  The  functions  vp_active( ), 
vp_width( ),  and  vp_height( )  provide 
those  services.  Using  them,  subprograms 
with  no  knowledge  of  the  current  view¬ 
port  can  make  intelligent  decisions 
about,  say,  scaling  output  to  fit  within 
the  available  drawing  area.  You’ll  see 
examples  Real  Soon  Now. 

Before  we  move  on,  don’t  forget  to 
compile  GRAFLX.C  and  VUPORT.C  and 
then  put  them  into  your  GRAFLX.LIB. 

Let's  Put  It  To  Work 

A  couple  of  application  programs  will 
prove  the  pudding  we’ve  cooked  up 
here,  and  probably  give  you  some  other 
ideas  about  how  to  use  viewports. 

Listing  Five,  on  page  148,  is  VP.C,  a 
simple  program  that  draws  some  six- 
pointed  stars  in  viewports.  The  first  star 
(magenta)  is  drawn  in  default  full¬ 
screen  mode.  The  second  (blue  near 
the  bottom  of  the  screen)  is  inside  a 
viewport,  but  you  can’t  tell  that  be¬ 
cause  there’s  no  border.  It  appears  to 
have  been  drawn  with  different  coordi¬ 
nates  than  the  first,  even  though  the 
positions  of  both  are  the  same  in  rela¬ 
tion  to  their  enclosing  viewports.  The 
third  star  near  the  center  of  the  screen 
is  within  a  bordered  viewport.  The  area 
is  too  small  to  contain  the  star,  so  clip¬ 
ping  occurs.  The  white  star  and  blue 
border  clearly  reveal  that  there  is  no 
conflict  between  the  outline  and  ob¬ 
jects  within  the  viewport,  and  also 
(lower  right  comer)  that  the  portion  of 
a  line  beginning  and  ending  outside 
the  viewport  shows  up  within  the  draw¬ 
ing  area.  The  final  viewport  is  outlined 
in  white,  filled  with  green,  and  bears  a 
red  star.  The  call  to  fill_rect( )  illus¬ 
trates  one  application  of  inquiry  func¬ 
tions. 

The  second  program  is  LINEGRAF.C 
(Listing  Six,  page  148).  This  program 
illustrates  how  a  graphics  subroutine 
can  intelligently  adjust  its  behavior  ac¬ 
cording  to  the  dimensions  of  the  active 
viewport.  It  plots  the  same  series  of 


data  points  in  three  viewports  of  differ¬ 
ent  sizes  and  shapes. 

The  smarts  are  in  the  graph( )  func¬ 
tion.  The  first  three  expressions  calcu¬ 
late  the  factors  required  to  scale  the 
line  graph.  The  number  of  data  points 
is  the  size  of  the  data  series  array  di¬ 
vided  by  the  size  of  its  type  (assuming 
that  the  array  is  always  full).  If  there  are 
n  points,  then  the  number  of  intervals 
across  the  width  of  the  plot  area  is  n-1. 
Therefore  the  horizontal  scaling  factor 
is  the  width  divided  by  the  number  of 
intervals,  which  must  be  a  floating  point 
value  in  order  to  avoid  roundoff  errors. 
This  program  knows  that  all  values  in 
the  data  series  are  positive  integers  less 
than  100,  so  it  factors  the  vertical  inter¬ 
val  per  unit  on  a  scale  of  100. 

The  graph  itself  is  drawn  by  the  loop, 
which  pulls  each  line  segment  forward 
from  the  previous  point  to  the  current 
point.  Accordingly,  before  entering  the 
loop  the  program  computes  the  loca¬ 
tion  for  element  0  as  the  previous  point, 
so  that  it  has  a  valid  place  to  draw  from 
during  the  first  iteration.  Now  let’s  con¬ 
sider  the  sanity  of  the  statement 

cury  =  vp_height(  )  - 

(int)(data[p]  *  vint); 

The  second  factor  is  fairly  obvious:  It 
finds  the  height  of  the  point  scaled  by 
the  vertical  factor,  and  because  coordi¬ 
nates  are  integers,  the  cast  converts  it 
appropriately.  But  why  subtract  the  Y 
coordinate  from  the  viewport  height? 
Because  display  coordinate  systems  are 
upside  down.  The  rest  of  the  world 
thinks  of  Y  as  increasing  upward,  while 
on  a  display  Y  increases  downward. 
By  subtracting  the  computed  value  from 
the  viewport  height,  we  “flip”  the  Y  so 
that  the  graph  comes  out  right  side  up. 

So  the  old  is  out  and  the  new  is  in, 
and  that’s  how  viewports  work. 

Availability 

All  source  code  for  articles  in  this  issue 
is  available  on  a  single  disk.  To  order, 
send  $14.95  (Calif,  residents  add  sales 
tax)  to  Dr.  Dobb’s Journal ,  501  Galves¬ 
ton  Dr.,  Redwood  City,  CA  94063;  or 
call  800-356-2002  (from  inside  Calif.) 
or  800-533-4372  (from  outside  Calif.). 
Please  specify  the  issue  number  and 
format  (MS-DOS,  Macintosh,  Kaypro). 
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Run  Length  Encoding 

Revisited 

There’s  more  than  one  way  to  skin  RLE 


Phil  Daley 


Many  files  stored  on  computer 
systems  have  a  lot  of  wasted 
space:  Often,  records  have 
duplicated  spaces  or  fixed 
length  records  that  aren’t  fully 
used,  so  blank  areas  of  unused  space 
exist  that  could  be  compressed  out  of 
the  records.  (Notice  how  much  smaller 
an  .EXE  file  is  after  being  processed 
by  EXEPACK,  if  it  wasn’t  linked  with 
/£)  In  my  work  with  user  interfaces 
and  screen  files,  a  good  deal  of  each 
record  is  either  blanks  or  zeros.  Rou¬ 
tines  to  squeeze  this  space  out  of  re¬ 
cords  can  be  very  simple  (saving  a 
minimum  amount  of  space)  or  very 
complex  (designed  by  the  program  for 
each  record  and  requiring  significant 
amounts  of  processing  time).  What 
brought  this  all  to  mind  was  the  RLE 
presented  in  Robert  Zigon’s  “Run  Length 
Encoding”  iDDJ,  February  1989).  The 
approach  presented  in  that  article,  how¬ 
ever,  doesn’t  do  well  with  runs  of  unique 
characters,  doubling  the  length  of  each 
unique  character  as  it  goes.  Two 
changes  to  the  encoding  rules  can  re¬ 
sult  in  a  dramatic  increase  in  the  com¬ 
pression  factor  without  a  large  increase 
in  processing  time:  1.  Don’t  compress 
less  than  three  duplicated  characters; 
and  2.  Mark  areas  of  unduplicated  char¬ 
acters  the  same  as  duplicated  ones, 
using  a  bit  to  indicate  whether  the  next 
run  is  compressed  or  not. 

Every  byte  in  the  file  is  marked  as 
either  “compressed”  or  “uncom- 
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now  a  software  engineer  at  Mentor  Re¬ 
sources,  1  Tara  Blvd.,  Nashua,  NH 
03062;  603-888-2580. 


pressed.”  The  markers  (or  “compres¬ 
sion  bytes”)  are  1  byte  in  size.  A  com¬ 
pression  byte  has  the  high  bit  set  if  it 
indicates  a  run  of  redundant  bytes,  and 
clear  if  it  marks  a  set  of  unique  bytes. 
The  other  seven  bits  are  used  to  indi¬ 
cate  the  length  (1  -  128)  of  the  run  of 
compressed  or  uncompressed  bytes. 

In  the  case  of  a  compression  byte 
with  the  high  bit  set  (>=128),  the  next 
byte  is  the  character  that  is  duplicated. 
When  a  compression  byte  indicates 
unique  characters  (<=127),  the  next  com- 
pression_byte  +  l  characters  are  the 
normal  bytes  in  the  file.  The  worst  case 
(all  unique  characters)  becomes  129 
bytes  for  128  bytes,  and  the  best  case 
is  2  bytes  for  128  duplicated  bytes.  This 
is  illustrated  in  Figure  1,  which  equals 
a  total  of  10  bytes,  the  same  as  Zigon’s. 
Notice  that  the  CCD  pattern  only  in¬ 
creased  the  character  count  by  1  byte. 
This  would  be  true  for  any  number  of 
unique  bytes  in  a  row,  up  to  128.  Zigon’s 
method  increases  each  different  char¬ 
acter  to  2  bytes  each. 

In  my  application  of  saving  screen 
images  and  other  database-type  records, 
where  a  good  deal  of  the  record  is 
either  spaces  or  zeros,  this  routine  saves 
50  percent  of  the  record  space,  on  the 
average.  The  routine  does  require  you 
to  save  the  record  length  along  with 
the  record,  but  most  C  implementa¬ 


tions  of  variable  length  indexed  records 
require  this  information. 

While  I  haven’t  coded  this  in  assem¬ 
bly  because  the  C  implementation  runs 
fast  enough  for  my  practical  purposes, 
it  probably  runs  a  little  slower  than 
Zigon’s  for  compression.  (See  Listing 
One,  page  154.)  The  uncompress  rou¬ 
tine  is  probably  just  as  fast  as  his,  be¬ 
cause  of  its  simplicity. 

Notes 

The  disk  program  files  were  compiled 
using  the  large  model,  the  only  one  for 
which  I  keep  libraries  on  my  disk.  The 
source  would  produce  smaller,  faster 
.OBJ  and  .EXE  files  if  it  were  recom¬ 
piled  with  the  small  memory  model. 

Availability 

All  source  code  for  articles  in  this  issue 
is  available  on  a  single  disk.  To  order, 
send  $14.95  (Calif,  residents  add  sales 
tax)  to  Dr.  Dobb’s Journal,  501  Galves¬ 
ton  Dr.,  Redwood  City,  CA  94063;  or 
call  800-356-2002  (from  inside  Calif.) 
or  800-533-4372  (from  outside  Calif.). 
Please  specify  the  issue  number  and 
format  (MS-DOS,  Macintosh,  Kaypro). 

DDJ 

(Listing  begins  on  page  154.) 
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Figure  1:  Compression  byte  with  high  list  set 
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STRUCTURED  PROGRAMMING 


Pizza  Terra 


One  roasty  Saturday  last  summer, 
Mr.  Byte  and  I  were  steaming 
over  The  Hill  in  the  Magic  Van 
to  pick  up  some  end  mills  in 
San  Jose  when  the  KWSS  DJ  caught 
my  ear: 

.  .  and  up  next  is  the  great  new 
single  by  Pizza  Terra!” 

Pizza  Terra?  What  a  great  name  for  a 
rock  band!  We  haven’t  seen  names  like 
that  since  the  Strawberry  Alarm  Clock 
and  the  Peppermint  Trolley  Company, 
and  I  was  duly  impressed  — if  also  won¬ 
dering  why  I  hadn’t  ever  heard  of  Pizza 
Terra  before. 

Then  he  played  the  song.  And  mo¬ 
ment  by  moment  I  found  myself  think¬ 
ing,  Boy,  that  sure  sounds  like  Peter 
Citera  .  .  . 

Peter  Citera  .  .  .  Pete  Citera  .  .  .  Pizza 
Terra! 

I’d  been  type  cast! 

Homonymously  Yours 

The  last  part  of  Pascal  to  resist  my 
understanding  was  the  subject  of  type 
casting,  and  in  Pizza  Terra  I’ve  found 
a  wonderful  metaphor  to  make  it  go 
down  easier.  What  the  DJ  said  was 
perfectly  correct:  Four  spoken  sylla¬ 
bles  that  sounded  like  “pee-tzuh-tear- 
uh.”  Given  your  typical  DJ’s  level  of 
enunciation,  those  four  syllables  could 
as  easily  be  taken  to  mean  “Pizza  Terra” 
as  “Pete  Citera.” 


Jeff  Duntemann,  KI6RA 


And  that’s  the  whole  point. 

Type  casting  is  the  process  of  taking 
a  variable  of  one  type  and  treating  it 
as  a  variable  of  another  type.  This  sticks 
to  the  roofs  of  most  mouths  fed  on 
Pascal  and  Modula-2,  both  of  which 
are  pretty  hardnosed  about  type  check¬ 
ing.  Type  casting  jumps  the  type  check¬ 
ing  safety  railing,  allowing  you  to  get 
into  two  different  kinds  of  trouble  if 


you’re  not  careful. 

One  kind  of  trouble  is  semantic  non¬ 
sense.  Both  Turbo  Pascal  and  Modu¬ 
la-2  allow  a  variable  of  type  Char  to 
be  cast  onto  a  variable  of  type  Boolean 
through  this  notation: 

MyChar  :=  CHAR(MyBoolean); 

This  is  completely  legal.  But  what  does 
it  mean?  Can  a  character  be  TruS  Is 
False  an  aspect  of  the  letter  ‘Q’?  It  sounds 
like  nonsense  to  me  — which  is  a  ma¬ 
jor  reason  we  have  type  checking  in 
civilized  languages  like  Pascal  and 
Modula-2. 

The  Pascal/Modula-2  statement  above 
implies  that  some  sort  of  conversion 
process  is  going  on,  and  that  processor 
cycles  are  being  spent  somehow  con¬ 
verting  data  from  type  Boolean  to  type 
Char  before  copying  them  to  variable 
MyChar.  Not  so— the  data  is  simply 
copied  from  MyBoolean  to  MyChar  with 
nary  a  thought  for  data  typing.  It’s  like 
picking  up  a  cylindrical  crucible  of  mol¬ 
ten  aluminum  and  pouring  the  metal 
into  a  cubical  mold.  The  shape  of  the 
aluminum  changes,  but  the  metal  itself 
is  still  aluminum.  It  doesn’t  change  to 
copper  or  zinc. 

Underneath  the  level  of  Pascal  or 
Modula-2,  a  Boolean  variable  is  just  a 
single  byte  of  memory  with  some  bit 
pattern  in  it.  Like  the  syllables  of  speech, 
what  a  byte  of  memory  means  to  us  is 
pretty  much  what  we  decide  it  is  to 
mean,  according  to  some  preagreed 
scheme.  If  a  byte  of  memory  with  the 
value  01 H  is  poured  into  a  mold  marked 
Boolean ,  we  agree  that  it  has  the  value 
True,  if  we  pour  the  same  byte  into  a 
mold  marked  Char,  it  comes  up  on  the 
screen  as  a  white  smiley  face. 

Think  of  type  casting  as  another  form 
of  metal  casting:  pouring  raw  materials 
into  a  mold.  The  mold  dictates  the  shape 
of  the  metal,  but  the  underlying  nature 
of  the  raw  material  is  unchanged  in  the 


process.  Cast  the  four  syllables  “pee- 
tzuh-tear-uh”  into  a  mold  marked  “male 
vocalist”  and  you  get  Pete  Citera.  Cast 
the  same  four  syllables  into  a  mold 
marked  “imaginary  Sixties  rock  band” 
and  you  get  Pizza  Terra. 

The  Second  Kind  of  Trouble 

It’s  easy  enough  to  imagine  a  second 
kind  of  trouble  connected  with  break¬ 
ing  the  rules  of  type  checking:  What 
happens  if  you  have  more  data  in  one 
type  than  in  another?  If  you  cast  6  bytes 
of  data  into  10  bytes  of  data,  what  do 
you  have?  Or  worse,  if  you  cast  10 
bytes  of  data  into  6  bytes  of  data,  does 
anything  overflow?  Do  you  overwrite 
unrelated  variables  that  just  happen  to 
be  adjacent  in  memory? 

Casting  between  any  two  types,  even 
of  different  sizes,  is  possible  in  both 
Turbo  Pascal  and  Modula-2  by  the  same 
syntax  shown  earlier.  If  the  source  type 
is.  smaller  than  the  destination  type, 
you  end  up  with  a  partially  filled  desti¬ 
nation  type.  The  generated  code  sim¬ 
ply  picks  up  bytes  from  the  source 
type,  starting  with  the  lowest  memory 
address,  and  drops  bytes  into  the  desti¬ 
nation  type  until  there  are  no  more 
bytes  to  drop.  Coping  with  the  result¬ 
ing  semantic  nonsense  is  left  to  you, 
but  there’s  no  danger  of  overwriting 
adjacent  data. 

When  there’s  more  source  than  des¬ 
tination,  the  code  copies  bytes  from 
the  source  until  the  destination  is  full, 
then  stops.  This  eliminates  any  danger 
of  overwriting  data  adjacent  in 
memory. 

Sign  Extension  and  Modula-2 
Numeric  Casts 

One  hiccup  in  the  casting  process  oc¬ 
curs  when  data  from  one  numeric  type 
is  moved  into  another.  The  notion  of 
simply  moving  bytes  blindly  from  one 
variable  to  another  no  longer  applies. 

Turbo  Pascal  and  Modula-2  perform 
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(continued  from  page  132) 
something  called  sign  extension  when 
data  is  moved  between  a  signed  nu¬ 
meric  type  into  a  larger  signed  numeric 
type;  for  example,  from  type  Integer 
to  type  Longlnt.  The  sign  bit  of  the 
shorter  type  is  moved  into  the  sign  bit 
of  the  larger  type,  even  though  the 
bytes  from  the  shorter  type  do  not  en¬ 
tirely  fill  the  larger  type.  The  end  result 
is  that  a  negative  integer  value  cast 
onto  a  long  integer  will  result  in  a 
negative  long  integer  value. 

There  is  really  only 
one  portable  way 
to  perform  typecasts 
in  Pascal 


Most  Turbo  Pascal  users  take  sign 
extension  for  granted,  because  numeric 
types  are  nearly  always  assignment  com¬ 
patible,  and  explicit  casting  between 
numeric  types  never  needs  to  be  done. 
However,  even  if  you  explicitly  cast 
an  integer  onto  a  long  integer,  sign 
extension  will  still  happen. 

Modula-2  is,  again,  much  more  stub¬ 
born  than  Pascal  when  moving  nu¬ 
meric  values  between  types.  Nearly  all 
movement  of  values  between  numeric 
types  must  be  done  through  explicit 
casting.  INTEGER  and  CARDINAL  are 
assignment  compatible,  as  are  SHORT- 
CARD  and  SHORTINT.  But  that’s  about 
it.  All  other  numeric  value  transfers  are 
done  through  an  implied  call  to  the 
VAL  function,  which  includes  sign  ex¬ 
tension. 

Numeric  types  demonstrate  one  Pas¬ 
cal  safety  railing  that  can’t  be  jumped: 
Turbo  Pascal  somewhat  remarkably  for¬ 
bids  a  type  cast  of  any  real  number 
type  onto  any  integer  type,  just  as  it 
forbids  assignment  of  any  real  number 
type  to  any  integer  type.  Type  Real 
cannot,  in  fact,  be  cast  onto  any  other 
type.  To  get  at  the  bytes  inside  type 
Real,  you  have  to  use  union  labor,  as 
I’ll  explain  shortly.  Modula-2,  by  con¬ 
trast,  allows  byte-by-byte  casting  of  real 
numbers  onto  any  non-numeric  type 
at  all. 

An  All  Union  Cast 

One  problem  with  type  casting  in  Turbo 
Pascal  is  that  it’s  not  really  part  of  the 
Pascal  language,  and  other  compilers 
in  other  environments  may  or  may  not 
implement  it.  For  most  of  us  that  doesn’t 


matter;  I  consider  the  differences  in 
paradigms  among  environments  (say, 
DOS,  Mac,  OS/2,  and  Unix)  far  more 
of  a  barrier  to  portability  than  any 
deviation  from  an  HLL’s  syntactic 
standard. 

But  the  issue  remains  for  those  who 
care:  There  is  really  only  one  portable 
way  to  perform  typecasts  in  Pascal. 
This  is  the  free  union  variant  record  (or 
simply  the  free  union),  and  it  is  about 
the  most  peculiar  thing  Niklaus  Wirth 
decided  to  include  in  his  definition  of 
Pascal. 

The  best  way  to  approach  free  un¬ 
ions  is  to  start  with  their  less  libertarian 
relatives,  discriminated  unions.  (We  usu¬ 
ally  call  discriminated  unions  variant 
records.)  The  familiar  Pascal  variant  re¬ 
cord  looks  like  this: 

ID  = 

RECORD 

CASE  AJien  :  Boolean  OF 
True  :  (HomeStarlD  :  StarlD); 
False  :  (EarthID  :  CountrylD); 

END; 

There  are  three  fields  defined  here 
{Alien,  HomeStarlD,  and  EarthID)  but 
only  two  exist  at  any  one  time.  The 
Boolean  field  Alien  is  called  the  tag 
field  and  is  always  present  in  any  in¬ 
stance  of  the  record  type.  Which  of  the 
other  two  fields  is  considered  present 
in  the  record  depends  on  the  value 
loaded  into  Alien.  If  Alien  contains  True, 
then  the  other  field  in  the  record  is 
HomeStarlD.  If  Alien  contains  False, 
then  the  other  field  is  EarthID. 

Beginners  often  ask:  Well,  who  en¬ 
forces  that?  Nobody;  there’s  nothing  to 
enforce.  People  who  think  “enforce¬ 
ment”  are  thinking  backwards.  The  tag 
field  exists  to  tell  users  of  the  record 
what  information  was  written  into  the 
record  earlier  so  that  those  users  can 
know  how  to  interpret  what  they  find. 
The  tag  field  is  a  flag,  not  a  switch. 
Changing  the  value  of  Alien  has  no 
effect  on  the  data  in  the  rest  of  the 
record.  Given  an  instance  of  ID  named 
ScienceOfficer,  the  tag  field  is  used  this 
way: 

WITH  ScienceOfficer  DO 
IF  Alien  THEN 

SendHyperwaveTo 

(HomeStarlD) 

ELSE 

SendTelegramTo(EarthlD); 

Changing  the  value  in  Alien  in  viola¬ 
tion  of  the  agreed  upon  scheme  (that 
is,  setting  it  to  False  (or  that  guy  Spock) 
will  cause  confusion,  but  only  seman¬ 
tic  confusion.  The  system  won’t  crash. 

If  you’re  sharp  it  may  occur  to  you 


that  variant  records  are  themselves  a 
means  of  type  casting,  and  you’re  right. 
Once  you  write  a  HomeStarlD  into  an 
ID  record,  you  can  ignore  the  tag  field 
and  read  the  identical  data  right  back 
as  an  EarthID  type,  essentially  casting 
a  HomeStarlD  type  onto  an  EarthID 
type. 

And  if  the  only  reason  for  the  record 
is  to  cast  one  type  onto  another,  who 
needs  the  tag  field?  In  fact,  dropping 
the  tag  field  is  how  we  turn  a  discrimi¬ 
nated  union  into  a  free  union: 

ScreenAtom  = 

RECORD 

CASE  Boolean  OF 

True  :  (Ch  :  Char; 

Attr  :  Byte); 

False  :  (Atom  :  Word); 

END; 

Like  the  Cheshire  cat,  the  tag  field 
has  vanished,  but  its  type  remains.  The 
need  for  the  tag  field  as  flag  is  gone, 
but  we  need  something  to  enumerate 
the  different  variants,  and  the  lonely 
type  specifier  Boolean  does  that  quite 
well  by  providing  the  True  and  False 
CASE  labels.  Any  ordinal  type  {Char, 
Integer,  Word,  Byte,  or  enumerations) 
would  do  as  well,  and  you  don’t  have 
to  account  for  every  value  in  the  type 
as  long  as  you  define  at  least  two. 

So  what  do  we  have  here?  A  record 
of  type  ScreenAtom  occupies  2  bytes 
of  storage,  and  that’s  all.  The  two  vari¬ 
ants  may  be  considered  two  molds  into 
which  those  2  bytes  of  storage  may  be 
cast.  One  mold  provides  two  byte¬ 
sized  compartments  called  Ch  and  Attr. 
The  other  is  a  single  2-byte  field  called 
Atom.  We  can  write  a  word-sized  value 
to  the  Atom  field  and  then  pick  out  its 
two  component  bytes  separately  as  Ch 
or  Attr.  The  reverse,  of  course,  is  just 
as  true:  We  can  build  an  atom  in  two 
operations,  first  by  storing  a  character 
in  Ch,  and  then  by  storing  its  attribute 
in  Attr.  That  done,  we  can  read  the 
finished  atom  out  as  Atom-. 

MyAtom.Ch  :=  ’A’; 

My  Atom.  Attr  :=  $07; 

MEMW[$B800  :  0]  :=  MyAtom.Atom; 

If  you  haven’t  already  recognized  this 
record  type,  it’s  from  the  SCREENS. PAS 
unit  presented  in  last  month’s  column. 
A  character  on  the  PC’s  text  screen  is 
stored  as  2  bytes  side  by  side:  The 
ASCII  code  for  the  character,  and  a 
byte  specifying  the  attribute  of  the  char¬ 
acter;  that  is,  its  color  for  color  screens, 
or  things  like  underlining  and  reverse 
video  for  monochrome  screens.  ScreenA¬ 
tom  lets  us  look  at  these  two  bytes  as 
a  unit,  or  else  as  the  two  individual 
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components,  as  we  choose. 

In  the  case  of  ScreenAtom,  both  of 
the  two  variants  are  of  the  same  size, 
so  everything’s  tidy.  That’s  not  a  re¬ 
quirement;  if  the  several  variants  vary 
in  size,  the  record  as  a  whole  is  as  large 
as  its  largest  variant.  This  prevents  any 
danger  to  adjacent  data. 

Registers  on  a  Half  Shell 

The  best  example  of  a  free  union  whose 
variants  are  not  the  same  size  is  the 
Registers  type  exported  by  the  Turbo 
Pascal  DOS  unit,  and  the  similar  Regis- 
ters  type  exported  by  TopSpeed  Modula- 
2’s  SYSTEM  module.  In  both  cases,  the 
idea  is  to  provide  access  to  the 
86-family  CPU  registers.  Listing  One 
(UNIONS. SRC),  page  149  shows  the 
two  free  unions  side  by  side  for  compari¬ 
son  purposes. 

There  are  ten  accessible  registers  al¬ 
together:  AX,  BX,  CX,  DX,  BP,  SI,  DI, 
DS,  ES,  and  Flags.  The  first  four,  how¬ 
ever,  are  commonly  treated  in  two  ways: 
As  1 6-bit  units  whose  names  end  in  X, 
or  with  each  16-bit  unit  seen  as  two 
8-bit  components  ending  in  H  (for  high) 
and  L  (for  low.)  For  example,  AX  is 
composed  of  AL  and  AH,  BX  of  BL  and 
BH,  and  so  on. 

Both  free  unions  provide  easy  ac¬ 
cess  to  the  four  general-purpose  regis¬ 
ters  AX,  BX,  CX,  and  DX  as  both  1 6-bit 
units  and  pairs  of  8-bit  halves.  Given 
an  instance  of  type  Registers  named 
Regs,  when  you  want  to  access  all  of 
AX,  you  specify  Regs. AX.  If  you  simply 
want  to  access  the  high  half  of  AX 
without  disturbing  the  low  half  (say, 
for  passing  parameters  to  a  DOS  or 
BIOS  service)  you  specify  Regs.AH. 

A  drawing  of  the  internals  of  the 
Turbo  Pascal  Registers  type  is  shown 
in  Figure  1,  reprinted  from  my  book, 
Complete  Turbo  Pascal,  Third  Edition. 
Each  variant  maps  a  different  structure 
on  the  same  20  bytes  of  memory.  The 
0  variant  partitions  those  20  bytes  into 
ten  2-byte  words.  The  1  variant  treats 
the  first  eight  bytes  as  single-byte  quan¬ 


tities  — and  ignores  the  remaining  12 
bytes. 

The  Modula-2  version  provides  the 
additional  service  of  subdividing  the 
Flags  register  into  the  16  separate  bits 
of  a  Modula-2  BITSET  type,  allowing 
individual  flags  to  be  tested  by  the  very 
intuitive  set  operators. 

In  summary,  what  both  Registers  types 
provide  are  two  different  interpreta¬ 
tions  of  the  same  region  of  memory, 
safely  and  with  zero  overhead  in  proc- 

Unfortunately,  it 
takes  a  lot  of 
pennies  to  buy 
anything  useful 


essor  cycles.  Like  Pizza  Terra  and  Pete 
Citera,  it  all  depends  on  how  you  look 
at  (or  listen  to)  things. 

Boxes  and  Bars 

Now,  as  the  retired  Tibetan  nomad 
might  have  said  after  a  big  dinner,  ’Nuff 
yak.  Code  is  It,  as  John  Sculley  didn’t 
say  — keep  your  soda  pop  salesmen 
straight  — but  I  will.  And  here’s  some 
more. 

In  last  month’s  column  I  presented 
the  core  of  a  virtual  screens  module  in 
Turbo  Pascal.  The  idea,  to  recap  briefly, 
is  to  create  a  virtual  screen  on  the  heap, 
the  size  of  an  8'/2-inch  by  1 1-inch  piece 
of  paper,  and  use  the  full  display  screen 
as  a  window  onto  that  virtual  screen. 

The  core  unit,  SCREENS. PAS,  pre¬ 
sented  primitives  for  initializing  and 
disposing  of  virtual  screens,  clearing 
them  and  writing  to  them,  and  panning 


the  visible  display  up  and  down  a  vir¬ 
tual  screen.  In  this  issue  I’m  providing 
the  beginning  of  a  second-level  unit, 
VTOOLS.PAS,  (Listing  Two,  page  149) 
to  contain  higher-level  display  routines 
like  forms  and  menus.  In  the  future, 
when  I  say,  “Add  this  procedure  to  the 
VTOOLS  unit,”  you’ll  know  what  I 
mean. 

Building  things  on  the  screen  de¬ 
mands  easy  access  to  the  PC’s  line¬ 
drawing  characters,  and  this  is  what 
VTOOLS  provides  in  this  first  iteration. 
The  characters  come  in  two  forms:  single- 
line  and  double-line.  I’ve  defined  each 
character  as  a  two-element  array,  in¬ 
dexed  by  the  Boolean  constants  Single- 
Line  and  DoubleLine,  with  the  sense 
that  DoubleLine  (  True)  selects  the  dou¬ 
ble-line  characters.  The  character  defi¬ 
nitions  are  stored  in  a  record  constant 
whose  fields  are  of  type  LineChars. 
Picking  a  specific  character  from  the 
record  is  done  this  way: 

BoxChars .  LLCornerlSingleLine] 

This  expression  “cooks  down”  to  char¬ 
acter  192  — and  makes  a  lot  more  sense 
when  you  read  the  code.  It’s  often  use¬ 
ful  to  have  vertical  and  horizontal  bars 
within  easy  reach  for  drawing  forms 
and  boxes.  I’ve  provided  an  array  type 
called  BarStrings  containing  two  255- 
character  long  STRING  types,  again  in¬ 
dexed  by  those  same  two  Boolean  con¬ 
stants  SingleLine  and  DoubleLine.  For 
example,  when  you  need  a  long  string 
of  single-line  vertical  bars,  you  would 
use  this  expression: 

VBarslSingleLine] 

To  generate  a  bar  shorter  than  255 
characters,  you  would  use  the  Copy 
function: 

Copy(HBars[DoubleLine],  1  .BarLength) 

Having  a  string  full  of  vertical  bar  char¬ 
acters  is  pointless  if  there’s  no  way  to 


Address  of 
The  Registers  record 


Figure  1:  The  Registers  free  union  variant  record 
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write  that  string  to  the  screen  .  .  .  verti-  tarpits  of  our  industry;  no  matter  how  truly  the  next  generation.  Certainly  it’s 

cally.  So,  Listing  Three,  (WRTDOWN.  many  times  newcomer  programmers  time  for  a  trip  to  Fry’s,  which  (for  those 

SRC)  page  1 50,  provides  vertical  string  are  reminded  how  dangerous  such  crit-  of  you  who  haven’t  heard)  was  a  drug- 

display  to  virtual  screens.  Add  Write-  ters  are,  they  march  into  the  tar  up  to  store  with  a  computer  comer  that  even- 

DownTo  to  the  SCREENS. PAS  source  the  neck  and  then  squeak  when  they  tually  became  a  computer  store  with  a 

code  file  presented  last  issue!  If  you  get  stuck.  In  Turbo  Professional’s  toothpaste-and-Kleenex  aisle, 

don’t,  this  month’s  code  will  not  scheme  you  write  your  program  as  a  Besides,  I  think  I’m  out  of  Ultra  Brite. 
compile.  single,  large  procedure  and  then  drop 

Prime  user  of  WriteDouinTo  is  Make-  the  procedure  into  a  very  tidy  TSR  pro-  Availability 

Box,  which  is  quite  straightforward  and  gram  shell.  The  whole  thing,  when  run,  All  source  code  for  articles  in  this  issue 

fast.  MakeBox  draws  boxes  on  a  virtual  loads  your  procedure  as  a  TSR  and  is  available  on  a  single  disk.  To  order, 

screen,  in  either  single-line  or  double-  handles  all  the  hairy  stuff  like  assigning  send  $14.95  (Calif,  residents  add  sales 

line  form  as  selected.  To  demonstrate  hot-keys  and  keeping  DOS  from  meet-  tax)  to  Dr.  Dobb’s Journal,  501  Galves- 

MakeBox,  try  BOXTEST.PAS  (Listing  ing  itself  in  a  dark  alley  with  bloody  ton  Dr.,  Redwood  City,  CA  94063,  or 

Four,  page  150),  which  I  adapted  from  results.  call  800-356-2002  (inside  Calif.)  or  800- 

Complete  Turbo  Pascal  to  operate  with  I  don’t  have  time  to  say  more,  but  I  533-4372  (outside  Calif.).  Please  spec- 

virtual  screens.  BoxTest)uSl  throws  ran-  will  say  that  if  you  intend  to  write  TSRs  ify  the  issue  number  and  format  (MS- 

dom-sized  boxes  all  over  the  place,  you  must  get  this  package.  All  the  source  DOS,  Macintosh,  Kaypro). 

and  allows  you  to  pan  through  the  is  present,  so  if  you  choose  to,  (and 

chaos  without  interrupting  it  — dem-  you  should,  for  your  own  protection)  Products  Mentioned 

onstrating  that  virtual  screens  can  be  you  can  read  the  source  and  under-  Turbo  Professional  5.0 

easily  examined  in  media  res  without  stand  all  the  considerable  magic  going  Turbo  Power  Software 

disrupting  ongoing  work.  Run  BoxTest  on  beneath  the  surface.  P.O.  Box  66747 

and  pan  with  the  up/down  arrow  keys  —  To  say  “highly  recommended”  abuses  Scotts  Valley,  CA  95066-0747 
you’ll  be  seeing  boxes  before  your  eyes  the  word  “highly.”  408-438-8608 

for  some  time  to  come. 

Cheaper  Chips 

A  Never  Ending  Life  Saver  While  curled  up  with  the  Sunday  paper  ddj 

There’s  a  funny  fantasy  story  by  Ber-  this  morning,  I  saw  that  Fry’s  is  selling 

nard  Wolfe  called  “The  Never  Ending  1MB  100ns  DRAMs  for  $24.95,  making  . 

Penny”  in  which  a  man  wishes  that  a  bank  of  nine  cost  only  $225  - — down  (Listings  begin  on  page  149.) 

there  would  always  be  a  penny  in  his  by  a  third  from  when  I  last  looked. 

pocket.  He  gets  his  wish,  and  no  matter  Maybe  it’s  time  to  see  for  myself  if  OS/2  Vote  for  your  favorite  feature/article. 

how  many  times  he  pulls  the  penny  really  is  half  an  operating  system,  or  Circle  Reader  Service  No.  12. 

from  his  pocket,  there  is  always  an- 

other  there.  Unfortunately,  it  takes  a  lot 

of  pennies  to  buy  anything  useful,  and 

when  he  complains  that  his  arm  is  fit 

to  fall  off  from  pulling  pennies  out  of 

his  pocket,  his  fairy  godmother  chides 

him  to  be  glad  he  didn’t  wish  for  a 

never  ending  Wintergreen  Lifesaver  — 

the  chap  who  did  soon  weighed  300 

pounds. 

In  reading  through  the  documenta¬ 
tion  for  Turbo  Power  Software’s  new 
Turbo  Professional  5.0,  I  felt  that  no 
matter  how  many  routines  I  pulled  out, 
there  would  always  be  another  one 
there.  The  range  of  this  toolkit  package 
is  simply  astonishing.  Just  a  few  of  its 
video-related  abilities  include  mouse 
support,  a  popup  help  system,  pick 
lists  and  menus,  and  (gasp)  a  virtual 
screen  system.  (I  guess  — fortunately 
for  this  column  — Kim  &  Company  don’t 
share  my  obsession  with  66-line 
screens.)  Also  in  the  package  are  data 
entry  screen  support,  extended  and  ex¬ 
panded  memory  support,  long  ASCIIZ 
strings,  critical  error  handlers,  in-mem¬ 
ory  sorts,  and  virtual  data  arrays  up  to 
32  Mbytes  in  size.  The  full  $125  price 
of  the  package,  however,  may  well  be 
worth  a  single  section  of  the  product 
devoted  to  interrupt  service  routines 
and  TSRs. 

Interrupts  and  TSRs  are  the  LaBrea 
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Listing  One  ( Text  begins  on  page  1 1 7J 

/* - interp.h - */ 

♦define  TOKBUFSIZE  4096  /*  token  buffer  size  */ 

♦define  MAXSYMBOLS  100  /*  maximum  symbols  in  table  */ 

♦define  MAXSTRINGS  50  /*  maximum  strings  in  arrays  */ 

♦define  MAXPARAMS  10  /*  maximum  parameters  in  calls  */ 

/* - error  codes - */ 

enum  errs  (EARLYEOF, UNRECOGNIZED, DUPL_DECLARE, TABLEOVERFLOW, 
OMERR, UNDECLARED, SYNTAX, BRACERR, PARENERR, MISSING, 
NOTFUNC, BREAKERR, OUTOFPLACE, TOOMANYSTRINGS, BUFFULL, 
DIVIDEERR}; 

/*  - -  intrinsic  function  table  -  */ 

typedef  struct  { 
char  ‘fname; 
int  (*fn) (int  *); 

)  INTRINSIC; 

/* - symbol  table - */ 

typedef  struct  { 

char  ‘symbol;  /*  points  to  symbol  name  */ 

char  ‘location;  /*  points  to  function  code  (NULL  if  int)  */ 

char  “tblloc;  /*  points  to  table  array  (NULL  if  func)  */ 

int  ival;  /*  value  of  integer  */ 

}  SYMBOL; 

/* - function  prototypes - */ 

void  loadsource (void) ; 

int  function (char  *,  SYMBOL  *); 

♦define  interpret ()  function ("main\0 (); ",  symtop); 

/* - functions  provided  by  the  shell - */ 

int  getsource (void) ; 

void  ungetsource (int) ; 

void  sierror(enum  errs,  char  »,  int); 

/* - the  compiled  (interpretable)  S  source - */ 

extern  SYMBOL  globalsf]; 
extern  char  ‘tokenbf; 
extern  char  ‘strings []; 
extern  SYMBOL  ‘symtop; 


End  Listing  One 


Listing  Two 

/*  - interp.c - */ 

♦include  <stdio.h> 

♦include  <conio.h> 

♦include  <string.h> 

♦include  <stdlib.h> 

♦include  <ctype.h> 

♦include  <process.h> 

♦  include  ''interp.h" 

♦define  TRUE  1 
♦define  FALSE  0 

/* - the  compiled  (interpretable)  S  source - */ 

SYMBOL  globals (MAXSYMBOLS ] ;  /*  function/variable  symbol  table  */ 

char  ‘tokenbf  =  NULL;  /*  compiled  token  buffer  */ 

char  ‘strings [MAXSTRINGS];  /*  char  *[]  string  arrays  */ 

SYMBOL  ‘symtop;  /*  top  of  symbol  table  */ 

/*  -  the  external  intrinsic  functions  -  */ 

extern  INTRINSIC  ‘infs;  /*  initialized  by  the  SI  shell  */ 

/* - function  macros - */ 

♦define  bypass ()  tptr+=strlen (tptr) +1 

♦define  isletter(c)  (isalpha  (c)  ! ,' isdigit  (c)  !  |c  =='_') 

♦define  iswhite(c)  (c=='  '!!c=='\t') 

/* - function  prototypes - */ 

static  void  linker (void) ; 
static  int  gettoken (void) ; 
static  int  getok(void); 
static  int  iskeyword (void) ; 
static  int  isident (void) ; 
static  int  istoken (void) ; 
static  int  getword(void) ; 
static  int  getcx(void); 

static  void  compound_statement (SYMBOL  *) ; 
static  void  statement (SYMBOL  *); 
static  void  statements (SYMBOL  *); 
static  void  skip_statements (SYMBOL  *); 

static  void  addsymbol (SYMBOL  *,  char  *,  char  *,  char  “); 

static  SYMBOL  ‘findsymbol (SYMBOL  *,  char  *,  SYMBOL  *); 

static  SYMBOL  ‘ifsymbol (SYMBOL  *,  char  *,  SYMBOL  *); 

static  void  freesymbols (SYMBOL  *); 

static  void  error (enum  errs,  char  *); 

static  int  iftoken (int) ; 

static  void  skippair (int,  int); 

static  void  needtoken (int) ; 

static  int  iftoken (int) ; 

static  int  nexttoken (void) ; 

static  int  expression (SYMBOL  *); 

static  int  escseq(void) ; 

/* - tokens - */ 

♦define  AUTOINC 
♦define  AUTODEC  'D' 

♦define  EQUALTO  'E' 

♦define  NOTEQUAL  'N' 

♦define  GE  'G' 


♦define  LE  ' L' 

♦define  IF  '  f ' 

♦define  ELSE  '  e' 

♦define  WHILE  'w' 

♦define  FOR  'F' 

♦define  CHAR  ' c' 

♦define  INT  'i' 

♦define  STRING  's' 

♦define  COMMENT 1  '/' 

♦define  COMMENT2  '*' 

♦define  POINTER  '*' 

♦define  PLUS  '+' 

♦define  MINUS 
♦define  MULTIPLY  '*' 

♦define  DIVIDE  '/' 

♦define  EQUAL 
♦define  LESS  •<• 

♦define  GREATER  '>' 

♦define  NOT  ' ! ' 

♦define  LPAREN  '  (' 

♦define  RPAREN  ')' 

♦define  LBRACE  '{' 

♦define  RBRACE  ' > ' 

♦define  LBRACKET  '  ( ' 

♦define  RBRACKET  ' ] ' 

♦define  COMMA 
♦define  AND  'S' 

♦define  ADDRESS  '(?' 

♦define  OR  '  j ' 

♦define  QUOTES 
♦define  QUOTE  '\" 

♦define  UNDERSCORE  '_' 

♦define  SEMICOLON 
♦define  IDENT  'I' 

♦define  CONSTANT  'C' 

♦define  LINENO  127 

♦define  RETURN  '  r' 

♦define  BREAK  'b' 

/* - table  of  key  words  and  their  tokens - */ 

static  struct  keywords  { 
char  *kw; 
int  kwtoken; 

)  kwds [ ]  -  { 

”\n",  LINENO, 

"for",  FOR, 

"while",  WHILE, 

"if",  IF, 

"else",  ELSE, 

"int",  INT, 

"char",  CHAR, 

"return", RETURN, 

"break",  BREAK, 

NULL,  0 

}; 

/*  -  table  of  direct  translate  tokens  -  */ 

static  int  tokens (]  =  { 

COMMA, LBRACE, RBRACE, LPAREN, RPAREN, EQUAL, NOT,  POINTER, 

LESS, GREATER, AND, OR, QUOTES, SEMICOLON, LBRACKET, RBRACKET, 
MULTIPLY, DIVIDE, PLUS, MINUS, EOF, LINENO, 0 

}; 

/»  - local  data - */ 

static  char  word [81];  /*  word  space  for  source  parsing  */ 

static  int  linenumber;  /*  current  source  file  line  number  */ 

static  int  frtn;  /*  return  value  from  a  function  */ 

static  char  ‘tptr;  /*  running  token  pointer  */ 

static  int  stptr;  /*  running  string  allocation  offset  */ 

static  int  breaking,  returning,  skipping; 
static  SYMBOL  ‘endglobals; 

/* - lexical  scan  and  call  linker - */ 

void  loadsource (void) 

( 

int  tok  =  0; 
if  (tokenbf  ==  NULL) 

if  ((tokenbf  =  malloc (TOKBUFSIZE+81) )  ==  NULL) 
error (OMERR,  ""); 

symtop  =  symtop  ?  symtop  :  globals; 

freesymbols (globals) ; 

memset (tokenbf,  '\0\  TOKBUFSIZE+81); 

linenumber  =  1; 

tptr  =  tokenbf; 

while  (tok  !=  EOF)  { 

if  (tptr  >=  tokenbf  +  TOKBUFSIZE) 
error (BUFFULL,  ""); 

*tptr++  =  tok  =  gettoken (); 
switch  (tok)  { 
case  LINENO: 

sprintf (tptr,  "%03d",  linenumber); 

tptr  +=  3; 

break; 

case  CONSTANT: 
case  IDENT: 
case  STRING: 

strcpy(tptr,  word) ; 
bypass () ; 
break; 
default : 
break; 

} 

} 

linker ();  /*  link  the  external  variables  and  functions  */ 

} 

/*  —  convert  a  script  program  to  tokens  for  interpreter, 

return  the  next  token - */ 

static  int  gettoken (void) 

{ 

int  tok  =  getword ( ) ; 
if  (tok  ==  0) 

if  ((tok  =  iskeywordO)  ==  0) 
if  ((tok  =  istoken ())  ==  0) 
tok  =  isident (); 
if  (tok  ==  0) 
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error (UNRECOGNIZED,  word); 

return  tok; 

i 

1 

*wd  =  '\0';  /*  null  terminate  the  word  or  token  */ 

/* - test  to  see  if  current  word  is  a  token - */ 

return  tok; 

static  int  istoken (void) 

i 

i 

/*  -  escape  sequence  in  literal  constant  or  string  -  */ 

int  *t  =  tokens,  t2; 

static  int  escseqO 

while  (*t  &&  word[l]  -=  '\0') 

( 

if  (‘word  ==  *t++)  { 

int  c  =  getcx (); 

switch  (‘word)  ( 

return  (c  ==  'n'  ?  '\n' 

case  EOF: 

c  ==  't'  ?  '\t' 

break; 

c  ==  'f'  ?  '\f' 

case  MID: 

c  ==  'a'  ?  ' \a' 

if  ( (t2  =  getcx () )  !=  AND)  ( 

c  ==  'b'  ?  ' \b' 

‘word  =  ADDRESS; 

c  ==  'r'  ?  ' \r' 

ungetsource(t2) ; 

c  =  '0'  ?  '\0' 

c); 

break; 

/* - get  a  character  from  the  input  stream - */ 

case  OR: 

static  int  getok (void) 

if  (getcx ()  !=  OR) 

{ 

error (MISSING,  word); 

int  c,  cl; 

break; 

while  ( (c  =  getsourceO) 

==  C0MMENT1 )  { 

case  PLUS: 

if  ( (cl  =  getcx  () )  !  = 

C0MMENT2 )  (  /*  comment  */ 

case  MINUS: 

ungetsource (cl) ; 

if  ( (t2  =  getcx ())  ==  ‘word) 

break; 

‘word  =  *word==PLUS  ?  AUTOINC  :  AUTODEC; 

} 

else 

while  (TRUE)  (  /*  found  comment  begin  token  pair  */ 

ungetsource (t2) ; 

while  ((cl  =  getcx ())  !=  COMMENT2 ) 

break; 

default: 

if  ((cl  =  getcx ())  ==  COMMENT 1) 

if  ( (t2  =  getcx ())  ==  EQUAL)  ( 

break;  /*  found  comment  end  token  pair  */ 

switch  (‘word)  ( 

i 

case  EQUAL:  return  EQUALTO; 

i 

case  NOT:  return  NOTEQUAL; 

if  (c  ==  '\n')  /*  count  source  line  numbers  */ 

case  LESS:  return  LE; 

linenumber++; 

case  GREATER:  return  GE; 

return  c; 

default:  break; 

) 

1 

/* - read  a  character  from  input,  error  if  EOF - */ 

) 

static  int  getcx (void) 

ungetsource (t2) ; 

{ 

break; 

int  c; 

) 

if  ( (c  =  getsourceO)  — 

EOF) 

return  ‘word; 

error (EARLYEOF,  ""); 

) 

return  c; 

return  0; 

) 

) 

/* - build  the  global  symbol  table  -  */ 

/* - test  word  for  a  keyword - */ 

static  void  linker (void) 

static  int  iskeyword() 

{ 

{ 

int  tok  =  0; 

struct  keywords  *k  =  kwds; 

char  ‘svtptr; 

while  (k— >kw) 

INTRINSIC  *ff  =  infs; 

if  (strcmp (k->kw,  word)  ==  0) 

tptr  =  tokenbf; 

return  k->kwtoken; 

/*  —  add  intrinsic  functions  to  the  symbol  table  —  */ 

else 

while  (ff->fname)  { 

k++; 

addsymbol (globals,  f f- 

>fname,  f f->fname, NULL) ; 

return  0; 

f  f++; 

/* - test  for  an  ident - */ 

while  (tok  !=  EOF)  ( 

static  int  isidentO 

switch  (tok  =  nexttokenO)  ( 

I 

case  CHAR: 

char  *wd  =  word; 

svtptr  =  tptr; 

int  n  =  0; 

if  (iftoken (POINTER)  )  ( 

if  (isalpha (*wd)  1  *wd  ==  UNDERSCORE) 

needtoken (IDENT) ; 

return  IDENT; 

bypass () 

if  (strlen(wd)  <=  6)  ( 

if  ( iftoken (LBRACKET))  (  1 

if  (strncmp(wd,  "Ox",  2)  ==  0)  ( 

tptr 

=  svtptr; 

wd  +=  2;  /*  Ox....  hex  constant  */ 

nexttoken () ; 

while  (*wd)  ( 

nexttoken  () ; 

n  =  (n*16) +(isdigit (*wd)  ?  *wd-'0'  : 

addsymbol (globals, tptr,  NULL, 

tolower(*wd)  -  'a'  +  10); 

strings+stptr) ; 

wd++; 

bypass () ; 

1 

needtoken (LBRACKET) ; 

sprintf (word, "%d",  n) ;  /*  converted  hex  constant  */ 

needtoken (RBRACKET) ; 

) 

needtoken (EQUAL) ; 

else  /*  test  for  decimal  constant  */ 

needtoken (LBRACE) ; 

while  (*wd) 

while 

(TRUE)  ( 

if  { ! isdigit (*wd++) ) 

if  ( (iftoken (STRING) ) 

return  0; 

break; 

return  CONSTANT; 

if  (stptr  ==  MAXSTRINGS) 

} 

error (TOOMANYSTRINGS,  ""); 

return  0; 

strings [stptr++]  =  tptr; 

} 

bypass () ; 

/* - get  the  next  word  from  the  input  stream - */ 

if  (! iftoken (COMMA) ) 

static  int  getword (void) 

break; 

char  *wd  =  word; 

strings [stptr++]  =  NULL; 

int  c  =  '  ' ,  tok  =  0; 

needtoken (RBRACE) ; 

while  (iswhite(c))  /*  bypass  white  space  */ 

needtoken (SEMICOLON) ; 

c  =  getok () ; 

break; 

if  (c  ==  QUOTE)  ( 

} 

tok  =  CONSTANT;  /*  quoted  constant  ('x')  */ 

) 

if  (<c  =  getcx ())  ==  '\\')  /*  escape  sequence  (\n)  */ 

tptr  =  svtptr 

c  =  escseqO ; 

case  INT: 

sprintf (word,  "%d",  c) ;  /*  build  the  constant  value  */ 

while  (TRUE) 

f 

wd  +=  strlen (word) ; 

if  (iftoken (POINTER) ) 

if  (getcx ()  !=  QUOTE)  /*  needs  the  other  quote  */ 

error (MISSING, "' ") ; 

needtoken (IDENT) ; 

) 

addsymbol (globals, tptr, NULL, NULL) ; 

tok  =  STRING;  /*  quoted  string  "abc"  */ 

if  (iftoken (EQUAL) ) 

while  ( (c  =  getcx ())  !=  QUOTES) 

(symtop-1) ->ival=expression (globals) ; 

*wd++  =  c  ==  '\\'  ?  escseqO  :  c; 

if  (! iftoken (COMMA) ) 

) 

break; 

else  ( 

1 

*wd++  =  c;  /*  1st  char  of  word  */ 

needtoken (SEMICOLON) ; 

while  (isletter (c) )  (  /*  build  an  ident  */ 

break; 

c  =  getok () ; 

case  IDENT: 

if  (isletter (c) ) 

addsymbol (globals,  tptr,  tptr,  NULL); 

*wd++  =  c; 

bypass () ; 

else 

skippair (LPAREN,  RPAREN) ; 

ungetsource (c) ; 

(continued  on  page  140) 
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Listing  Two  (Listing  continued,  text  begins  on  page  1 1 7.) 

Skippair (LBRACE,  RBRACE) ; 
break; 
case  EOF: 

break; 
default : 

error (OUTOFPLACE,  (char  *)  4tok) ; 

} 

} 

endglobals  =  symtop; 

} 

/* - a  function  is  called - * / 

int  function (char  *fnc,  SYMBOL  *sp) 

{ 

int  params [MAXPARAMS+1] ,  p,  i; 

INTRINSIC  *ff  =  infs; 
char  ‘savetptr  =  tptr; 
frtn  =  0; 
tptr  =  fnc; 
bypass () ; 

needtoken (LPAREN)  ; 

for  (p  -  0;  p  <  MAXPARAMS;  )  {  /*  scan  for  parameters  */ 

if  (iftoken (RPAREN) ) 
break; 

params [p++] =expression (sp) ;  /*  build  params  */ 
if  (! iftoken (COMMA) )  {  /*  into  parameter  array  */ 

needtoken (RPAREN) ; 
break; 

} 

1 

params [p]  =  0; 

while  (ff->fname)  (  /*  search  the  intrinsic  table  */ 

if  (strcmp(fnc, ff->fname)  ==  0)  ( 

frtn  =  (*ff->fn) (params) ;  /*  call  intrinsic  func  */ 
tptr  -  savetptr; 
return  frtn; 

) 

f  f++; 

> 

if  ( (tptr-f indsymbol (globals, fnc, endglobals) ->location) 

==  NULL) 

error (NOTFUNC, fnc) ;  /*  function  not  declared  */ 

bypass () ; 

needtoken (LPAREN)  ; 
sp  =  symtop; 

for  (i  =  0;  i  <  p;  i++)  {  /*  params  into  local  sym  tbl  */ 

needtoken (I DENT) ; 
addsymbol (sp, tptr,  NULL,  NULL)  ; 

(symtop-1) ->ival  =  params ( i) ; 
bypass {); 
if  (i  <  p-1) 

needtoken (COMMA) ; 

) 

needtoken (RPAREN)  ; 

compound_statement (sp) ;  /*  execute  the  function  */ 

freesymbols (sp) ;  /*  release  the  local  symbols  */ 

tptr  =  savetptr; 
breaking  =  returning  =  FALSE; 

return  frtn;  /*  the  function's  return  value  */ 

) 

/* - execute  one  statement  or  a  ()  block - */ 

static  void  statements (SYMBOL  *sp) 

( 

if  (iftoken (LBRACE) )  ( 

--tptr; 

compound_statement (sp)  ; 

) 

else 

statement (sp) ; 

) 

/* - execute  a  ()  statement  block - */ 

static  void  compound_statement (SYMBOL  *sp) 

( 

char  ‘svtptr  =  tptr; 

SYMBOL  *spp  =  symtop; 
needtoken (LBRACE) ; 

while  (iftoken (CHAR)  ||  iftoken (INT) )  { 

while  (TRUE)  (  /*  local  variables  in  block  */ 

if  (iftoken (POINTER) ) 

;  /*  bypass  pointer  token (s)  */ 

needtoken (IDENT) ; 
addsymbol (spp, tptr, NULL, NULL) ; 
bypass () ; 

if  (iftoken (EQUAL) )  /*  handle  assignments  */ 

(symtop-1) ->ival=expression (sp) ; 
if  (! iftoken (COMMA) ) 
break; 

) 

needtoken (SEMICOLON) ; 

} 

while  (! iftoken (RBRACE)  &&  Ibreaking  &&  ! returning) 
statements (sp) ; 

tptr  =  svtptr;  /*  point  to  the  opening  (  brace  */ 

freesymbols (spp) ;  /*  free  the  local  symbols  */ 

skippair (LBRACE,  RBRACE);  /*  skip  to  end  of  block  */ 

) 

/* - execute  a  single  statement - */ 

static  void  statement (SYMBOL  *sp) 

{ 

char  *svtptr,  *fortest,  ‘forloop,  *forblock; 
int  rtn,  tok  =  nexttoken(); 
switch  (tok)  { 
case  IF: 

needtoken (LPAREN) ; 

rtn  =  expression (sp) ;  /*  condition  being  tested  */ 
needtoken (RPAREN) ; 
if  (rtn) 

statements (sp) ;  /*  condition  is  true  */ 

else 


skip_statements (sp) ;  /*  condition  is  false  */ 
while  (iftoken (ELSE) ) 

if  (rtn)  /*  do  the  reverse  for  else  */ 

skip_statements (sp) ; 

else 

statements (sp) ; 

break; 
case  WHILE: 

rtn  =  TRUE; 

breaking  =  returning  =  FALSE; 
svtptr  =  tptr; 

while  (rtn  &&  Ibreaking  &&  ! returning)  ( 
tptr  =  svtptr; 
needtoken (LPAREN) ; 

rtn  =  expression (sp) ;  /*  the  condition  tested  * 
needtoken (RPAREN) ; 
if  (rtn) 

statements (sp) ;  /*  true  */ 

else 

skipstatements (sp) ;  /*  false  */ 

} 

breaking  =  returning  =  FALSE; 
break; 
case  FOR: 

svtptr  =  tptr;  /*  svptr  ->  1st  (  after  for  */ 

needtoken (LPAREN) ; 

if  (! iftoken (SEMICOLON) )  ( 

expression (sp) ;  /*  initial  expression  */ 

needtoken (SEMICOLON) ; 

) 

fortest  =  tptr;  /*  fortest  ->  terminating  test  */ 

tptr  =  svtptr; 

skippair (LPAREN, RPAREN) ; 

forblock  =  tptr;  /*  forblock  ->  block  to  run  */ 

tptr  =  fortest; 

breaking  =  returning  =  FALSE; 

while  (TRUE)  { 

if  (! iftoken (SEMICOLON) )  ( 

if  (iexpression(sp) )  /*  terminating  test  */ 
break; 

needtoken (SEMICOLON) ; 

) 

forloop  -  tptr; 
tptr  =  forblock; 

statements (sp) ;  /*  the  loop  statement (s)  */ 

if  (breaking  ! !  returning) 
break; 

tptr  =  forloop; 

if  (! iftoken (RPAREN))  ( 

expression (sp) ;  /*  the  end  of  loop  expr  */ 

needtoken (RPAREN) ; 

) 

tptr  =  fortest; 

} 

tptr  =  forblock; 

skip_statements (sp) ;  /*  skip  past  the  block  */ 

breaking  =  returning  =  FALSE; 

break; 

case  RETURN: 

if  (! iftoken (SEMICOLON) )  ( 

frtn  -  expression (sp) ; 
needtoken (SEMICOLON) ; 

) 

returning  -  ! skipping; 
break; 
case  BREAK: 

needtoken (SEMICOLON)  ; 
breaking  =  ! skipping; 
break; 
case  IDENT: 

— tptr; 

expression (sp) ; 
needtoken (SEMICOLON) ; 
break; 
default : 

error (OUTOFPLACE,  (char  *)  &tok); 

} 

) 

/* - bypass  statement  (s)  - */ 

static  void  skip_statements (SYMBOL  *sp) 

( 

skipping++;  /*  semaphore  that  suppresses  assignments,  */ 
statements (sp) ;  /*  breaks, returns, ++, — , function  calls  */ 

— skipping;  /*  turn  off  semaphore  */ 

) 

/*  -  recursive  descent  expression  analyzer  -  */ 

static  int  primary (SYMBOL  *sp) 

{ 

int  tok,  rtn  =  0; 

SYMBOL  *spr; 

switch  (tok  =  nexttoken(J)  ( 
case  LPAREN: 

rtn  =  expression (sp)  ; 
needtoken (RPAREN)  ; 
break; 
case  NOT: 

rtn  =  Iprimary (sp) ; 
break; 

case  CONSTANT: 

rtn  =  atoi(tptr); 
bypass  () ; 
break; 

case  POINTER: 

rtn  =  *(int  *)primary (sp)  &  255; 
break; 

case  ADDRESS: 
case  AUTOINC: 
case  AUTODEC: 

needtoken (IDENT)  ; 
case  IDENT: 
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if  ((spr  =  ifsymbol (sp, tptr, symtop) )  ==  NULL) 
spr  =  findsymbol(globals,tptr,endglobals) ; 
if  (spr->location)  { 

/* - this  is  a  function  call - */ 

if  (toll  !  =  IDENT) 

error (OUTOFPLACE,  (char  *)  itok) ; 
rtn  =  skipping  ?  0  :  function (tptr,  sp) ; 
bypass () ; 

skippair (LPAREN, RPAREN) ; 
break; 

) 

bypass () ; 

if  (spr->tblloc)  ( 

/* - this  is  a  table - */ 

rtn  =  (tok  =  ADDRESS  ? 

(int)  (&spr->tblloc)  : 

(int)  (  spr->tblloc)  ); 

break; 

) 

if  ([skipping  &&  tok  ==  AUTOINC) 

++(spr->ival) ; 

else  if  ([skipping  &&  tok  ==  AUTODEC) 

— (spr->ival) ; 

if  (tok  !*  ADDRESS  &&  if token (EQUAL) )  ( 

rtn  =  expression (sp) ; 
spr->ival  =  skipping  ?  spr->ival  :  rtn; 

1 

rtn  =  tok  ==  ADDRESS  ?  (int) &spr->ival  :  spr->ival; 
if  (tok  ! =  ADDRESS) 

if  (iftoken (AUTOINC)  [skipping) 

(spr->ival) ++; 

else  if  (iftoken (AUTODEC)  [skipping) 
(spr->ival) — ; 

break; 

case  STRING: 

rtn  *  (int)  tptr; 
bypass () ; 
break; 
default: 

error (OUTOFPLACE,  (char  *)  &tok) ; 


static  int  mult (SYMBOL  *sp) 

{ 

int  drtn,  rtn  =  primary (sp); 
while  (TRUE) 

if  (iftoken (MULTIPLY)) 

rtn  =  (rtn  *  primary (sp) ) ; 
else  if  (iftoken (DIVIDE) )  ( 

if  ((drtn  =  primary (sp))  -«  0) 
error (DIVIDEERR,  ""); 
rtn  /=  drtn; 

) 

else 

break; 
return  rtn; 

) 

static  int  plus (SYMBOL  *sp) 

( 

int  rtn  =  mult (sp) ; 
while  (TRUE) 

if  (iftoken (PLUS) ) 

rtn  =  (rtn  +  mult(sp)); 
else  if  (iftoken (MINUS) ) 

rtn  =  (rtn  -  mult(sp)); 

else 

break; 
return  rtn; 


/*  -  skip  the  tokens  between  a  matched  pair  -  */ 

static  void  skippair (int  ltok,  int  rtok) 

{ 

int  pairct  =  0,  tok; 

if  ((tok  =  nexttokenO)  !=  ltok) 

error (ltok  ==  LBRACE  ?  BRACERR  :  PARENERR,  ""); 
while  (TRUE)  ( 
if  (tok  ==  ltok) 
pairct++; 
if  (tok  ==  rtok) 

if  { — pairct  ==  0) 
break; 

if  ((tok  =  nexttokenO)  ==  EOF) 

error (ltok  ==  LBRACE  ?  BRACERR  :  PARENERR,  "") ; 


} 

/*  -  a  specified  token  is  required  next  - 

static  void  needtoken (int  tk) 

( 

if  (nexttokenO  !=  tk) 

error (MISSING,  (char  *)  &tk) ; 

) 

/*  -  test  for  a  specifed  token  next  in  line 

static  int  iftoken (int  tk) 

( 

if  (nexttokenO  ==  tk) 
return  TRUE; 

— tptr; 
return  FALSE; 

) 

/*  -  get  the  next  token  from  the  buffer  - 

static  int  nexttoken (void) 

{ 

while  (*tptr  ==  LINENO) 
tptr  +=  4; 
return  *tptr++; 


/* - add  a  symbol  to  the  symbol  table - */ 

static  void 

addsymbol (SYMBOL  *s,char  *sym,char  *floc,char  **tloc) 

{ 

if  (ifsymbol (s, sym, symtop)  !=  NULL) 
error (DUPL_DECLARE,  sym) ; 
if  (symtop  ==  globals  +  MAXSYMBOLS) 
error (TABLEOVERFLOW,  ""); 

if  ( (symtop->symbol  =  malloc (strlen (sym)  +  1))  «=  NULL) 
error (OMERR,  ""); 
strcpy (symtop->symbol,  sym) ; 
symtop->location  =  floe; 
symtop->tblloc  =  tloc; 
symtop->ival  =  0; 

symtopt*,-  (continued  on  page  142) 


static  int  le (SYMBOL  *sp) 

I 

int  rtn  =  plus(sp); 
while  (TRUE) 

if  (iftoken (LE) ) 

rtn  =  (rtn  <=  plus(sp)); 
else  if  (iftoken(GE) ) 

rtn  =  (rtn  >=  plus(sp)); 
else  if  (iftoken (LESS) ) 

rtn  =  (rtn  <  plus(sp)); 
else  if  (iftoken (GREATER) ) 
rtn  =  (rtn  >  plus(sp)); 

else 

break; 
return  rtn; 

} 

static  int  eq (SYMBOL  *sp) 

{ 

int  rtn  =  le(sp); 
while  (TRUE) 

if  (iftoken (EQUALTO)) 

rtn  =  (rtn  ==  le(sp)); 
else  if  (iftoken (NOTEQUAL) ) 
rtn  =  (rtn  !=  le (sp) ) ; 

else 

break; 
return  rtn; 

) 

static  int  and (SYMBOL  *sp) 

{ 

int  rtn  =  eq(sp); 
while  (iftoken (AND) ) 

rtn  =  (eq(sp)  &&  rtn) ; 
return  rtn; 


static  int  expression (SYMBOL  *sp) 
{ 

int  rtn  =  and(sp); 
while  (iftoken (OR) ) 

rtn  =  (and(sp)  !!  rtn) ; 
return  rtn; 
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Listing  Two  (Listing  continued,  text  begins  on  page  117.) 

) 

/* - find  a  symbol  on  the  symbol  table - */ 

static  SYMBOL  ‘findsymbol (SYMBOL  *s,  char  *sym,  SYMBOL  *ends) 

( 

if  ( (s  =  ifsymbol(s,  sym,  ends))  ==  NULL) 
error (UNDECLARED,  sym); 
return  s; 

> 

/* - test  for  a  symbol  on  the  symbol  table - */ 

static  SYMBOL  *if symbol (SYMBOL  *s,  char  *sym,  SYMBOL  *sp) 

( 

while  (s  <  sp — ) 

if  (strcmp(sym,  sp->symbol)  ==  0) 
return  sp; 
return  NULL; 

} 

/* - free  the  symbols  from  a  symbol  table - */ 

static  void  freesymbols (SYMBOL  *s) 

{ 

while  (s  <  symtop) 

free( ( — symtop) ->symbol) ; 

) 

/* - post  an  error  to  the  shell - */ 

static  void  error (enum  errs  erno,  char  *s) 

{ 

while  (*tptr  !=  LINENO  tptr  >  tokenbf) 

— tptr; 

sierror (erno,  s,  (*tptr  ==  LINENO)  ?  atoi(tptr+l)  :  1); 

) 


End  Listing  Two 


Listing  Three 


/* - si.c - */ 

♦include  <stdio.h> 

♦include  <conio.h> 

♦include  <stdlib.h> 

♦include  "interp.h" 

/*  -  intrinsic  interpreter  functions  -  */ 

static  int  iprntf(int  *p)  /*  printf  */ 

( 

printf ( <char*)p[0] ,p[l] ,p[2] ,p[3] ,p[4] ) ; 
return  0; 

) 

static  int  igtch(int  *p) 

{ 

return  putch (getch () ) ; 

} 

static  int  iptch(int  *c) 

( 

return  putchar (*c); 

) 


/*  get char  */ 


/*  putchar  */ 


INTRINSIC  ffs[]  =  {  "printf",  iprntf, 
"getchar",  igtch, 
"putchar",  iptch, 
NULL,  NULL 

extern  INTRINSIC  *infs  =  ffs; 

/*  -  error  messages  - 

char  *erm(]={  "Unexpected  end  of  file", 
"Duplicate  ident", 

"Out  of  heap  memory", 
"Syntax  Error", 

"Unmatched  ()", 

"Not  a  function", 

"Out  of  place", 

"Token  buffer  overflow", 
static  FILE  *fp; 

void  main (int  argc,  char  *argv[]) 

( 


); 

-  */ 

"Unrecognized", 

"Symbol  table  full", 
"Undeclared  ident”, 
"Unmatched  (}", 
"Missing", 

"Misplaced  break", 

"Too  many  strings", 
"Divide  by  zero"  }; 


if  (argc  ==  2) 

if  ( ( f p  =  fopen (argv(l) ,  "r"))  !=  NULL)  { 
loadsource () ; 
f close (fp) ; 
interpret () ; 


) 

void  sierror (enum  errs  erno,  char  *s,  int  line) 

( 

printf ("\r\n%s  %s  on  line  %d\n", s, ermferno] , line) ; 
exit  (1) ; 


int  getsource (void)  {  return  getc(fp);  } 

void  ungetsource (int  c)  (  ungetc(c,  fp) ;  ) 


End  Listings 


142 


Dr.  Dobb’s  Journal,  May  1989 

357 


GRAPHICS  PROGRAMMING 


Listing  One  (Text  begins  on  page  124.) 


11 

DRAWPT . ASM:  Writes  pixel  directly  to 

6845  Video  Controller 

2  | 

Microsoft  MASM  5.1 

31 

C  prototype  is 

41 

void  far 

draw  point  (int  x,  int 

y); 

5 1 

To  be  included  in  GRAFIX.LIB 

61 

K.  Porter,  DDJ  Graphics  Programming  Column,  February  '89 

8 1 

MODEL  LARGE 

9 1 

CODE 

10| 

PUBLIC 

draw_point 

111 

12| 

Externals  in 

GRAFIX.LIB 

13 1 

EXTRN 

_colorl  :  BYTE 

;  Pixel  color  reg  value 

14  | 

EXTRN 

vuport  :  WORD 

;  far  ptr  to  vuport  structure 

15| 

161 

Arguments  passed  from  C 

17  | 

EQU 

(bp+6) 

;  Arguments  passed  from  C 

181 

EQU 

[bp+8] 

19| 

201 

draw_point 

PROC  FAR 

211 

push 

bp 

;  Entry  processing 

22| 

mov 

bp,  sp 

231 

24| 

Point  ES: [BX] 

to  vuport  structure 

25| 

mov 

ax,  _vuport+2 

;  get  pointer  segment 

261 

mov 

es,  ax 

27  | 

mov 

bx,  _vuport 

;  get  offset 

281 

291 

Clip  if  coordinates  outside  viewport 

301 

mov 

cx,  y 

;  get  y 

311 

cmp 

cx,  es:[bx+6] 

;  is  y  within  viewport? 

32| 

jl 

checkx 

;  ok  if  so 

331 

jmp 

exit 

;  else  quit 

34 |  checkx:  mov 

ax,  x 

;  get  x 

35| 

cmp 

ax,  es:[bx+4] 

;  is  x  within  viewport? 

361 

jl 

remap 

;  ok  if  so 

37| 

jmp 

exit 

;  else  quit 

381 

391 

Map  pixel  coordinates  to  current  viewport 

40 |  remap:  add 

ax,  es:[bx] 

;  offset  x  by  vuport. left 

411 

mov 

x,  ax 

;  save  remapped  X 

42| 

add 

cx,  es:[bx+2] 

;  offset  y  by  vuport. top 

43| 

mov 

y ,  cx 

;  save  remapped  Y 

44  | 

45| 

Point  ES  to  video  memory  segment 

46 |  vmem:  mov 

ax,  OAOOOh 

47 1 

mov 

es,  ax 

48| 

49| 

Row  offset  = 

y  *  80; 

50| 

mov 

bx,  y 

;  Get  y  argument 

51 1 

mov 

ax,  80 

52| 

mul 

bx 

;  Result  in  AX 

53| 

mov 

bx,  ax 

;  Row  offset  in  BX 

54  | 

551 

Column  offset 

=  x  SHR  3 

56| 

mov 

ax,  x 

;  Get  x 

57| 

mov 

cl,  3 

;  Shift  operand 

581 

shr 

ax,  cl 

;  Column  offset 

591 

601 

Complete  address  of  pixel  byte 

611 

add 

bx,  ax 

;  ES:BX  =  address 

621 

631 

Build  bit  mask  for  pixel 

64| 

mov 

cx,  X 

;  Get  x  again 

65| 

and 

cx,  7 

;  Isolate  low-order  bits 

66 

xor 

cl,  7 

;  Number  of  bits  to  shift 

67| 

mov 

ah,  1 

;  Start  bit  mask 

681 

shl 

ah,  cl 

;  Shift  for  pixel 

691 

mov 

cl,  ah 

;  Save  it 

701 

711 

Use  write  mode  2  (single-pixel  update) 

72| 

mov 

dx,  03CEh 

;  6845  command  register 

73| 

mov 

al,  5 

;  Specify  mode  register 

74| 

mov 

ah,  2 

;  Read  mode  0,  write  mode  2 

751 

out 

dx,  ax 

;  Send 

76| 

;  Following  added  May  '89 

77 1 

mov 

al,  3 

;  Specify  function  select  reg 

78| 

xor 

ah,  ah 

;  Replace-pixel  mode 

79| 

out 

dx,  ax 

;  Send 

80| 

811 

Set  6845  bit 

mask  register 

82| 

mov 

al,  8 

;  Specify  bit  mask  register 

83| 

mov 

ah,  cl 

;  al  =  mask 

84 1 

out 

dx,  ax 

;  Send  bit  mask 

85| 

86| 

Draw  the  pixel 

87| 

mov 

al,  es : [bx] 

;  Load  6845  latch  registers 

88| 

xor 

al,  al 

;  Clear 

891 

mov 

byte  ptr  es:[bx],  al 

;  Zero  the  pixel  for  replace 

90 1 

mov 

al,  _colorl 

;  Get  the  pixel  value 

911 

mov 

es: [bx] ,  al 

;  Write  the  pixel 

921 

931 

Restore  video 

controller  to  default  state 

94  | 

mov 

dx,  03CEh 

95| 

mov 

ax,  0005h 

;  write  mode  0,  read  mode  0 

96| 

out 

dx,  ax 

97  | 

mov 

ax,  0FF08h 

;  default  bit  mask 

981 

out 

dx,  ax 

99 1 

mov 

ax,  0003h 

;  default  function  select 

1001 

out 

dx,  ax 

101| 

xor 

ax,  ax 

;  zero  Set/Reset 

102| 

out 

dx,  ax 

1031 

mov 

ax,  OOOlh 

;  zero  Enable  Set /Reset 

1041 

out 

dx,  ax 

105| 

mov 

dx,  03C4h 

;  6845  address  reg 

106| 

mov 

ax,  0F02h 

;  Data  reg,  enable  all  planes 

107| 

out 

dx,  i 

1081 

1091 

exit : 

110| 

mov 

sp,  ) 

nil 

pop 

bp 

1121 

retf 

1131 

draw  point 

ENDP 

114| 

END 

End  Listing  One 


Listing  Two 


11 

;  HLINE.ASM:  Fast  horizontal  line  dra 

wing  routine 

21 

;  Uses 

6845  Write  Mode  0  to  update  8 

pixels  at  a  time  on  EGA/VGA 

31 

;  C  prototype  is 

41 

;  void  far 

hline  (int  x,  int  y,  int  length  in  pixels); 

51 

;  Writes  in  current  colorl  from  GRAFIX.LIB 

61 

;  Microsoft  MASM  5.1 

7  1 

;  K.  Porter,  DDJ  Graphics  Programming  Column,  March  89 

91 

.MODEL 

LARGE 

10| 

.CODE 

111 

PUBLIC 

hline 

121 

EXTRN 

colorl  :  BYTE 

;  Current  palette  reg  for  pixel 

131 

EXTRN 

draw  point  :  PROC 

;  Pixel  writing  routine 

14| 

EXTRN 

vuport  :  WORD 

;  far  ptr  to  vuport  structure 

151 

16| 

;  Declare  arguments  passed  by  caller 

17| 

X 

EQU  [bp+6] 

181 

y 

EQU  [bp+8] 

191 

len 

EQU  [ bp  +10] 

201 

211 

;  Declare  auto 

variables 

221 

last 

EQU  [bp-  2] 

;  Last  byte  to  write 

231 

solbits 

EQU  [bp-  4] 

;  Mask  for  start  of  line 

241 

oddsol 

EQU  [bp-  6] 

;  #  odd  bits  at  start  of  line 

251 

eolbits 

EQU  [bp-  8] 

;  Mask  for  end  of  line 

261 

oddeol 

EQU  [bp-10] 

;  #  odd  bits  at  end  of  line 

27  | 

; - 

281 

29| 

hline 

PROC  FAR 

;  ENTRY  POINT  TO  PROC 

301 

push 

bp 

;  entry  processing 

311 

mov 

bp,  sp 

32| 

sub 

sp,  10 

;  make  room  for  auto  variables 

331 

xor 

ax,  ax 

;  initialize  auto  variables 

34| 

mov 

last,  ax 

351 

mov 

solbits,  ax 

36| 

mov 

oddsol,  ax 

37| 

mov 

eolbits,  ax 

381 

mov 

oddeol,  ax 

391 

40| 

;  Do  nothing  if 

line  length  is  zero 

411 

mov 

bx,  len 

;  get  line  length 

42| 

cmp 

bx,  0 

;  length  =0? 

43| 

jnz 

chlen 

;  if  not,  go  on 

44| 

jmp 

quit 

;  else  nothing  to  draw 

451 

461 

;  Call 

draw  point!)  with  a  loop  if  line  length  <  8 

47| 

chlen: 

cmp 

bx,  8 

481 

jnb 

getvp 

;  go  if  len  >=  8 

491 

mov 

ax,  y 

;  get  args 

50| 

mov 

cx,  X 

511 

drpt : 

push 

bx 

;  push  remaining  length 

52| 

push 

ax 

;  push  args  to  draw  point () 

531 

push 

cx 

541 

call 

draw  point 

;  draw  next  pixel 

551 

pop 

cx 

;  clear  args  from  stack 

561 

pop 

ax 

57  | 

pop 

bx 

;  fetch  remaining  length 

581 

inc 

cx 

;  next  x 

591 

dec 

bx 

;  count  pixel  drawn 

60| 

jnz 

drpt 

;  loop  until  thru 

611 

jmp 

quit 

;  then  exit 

621 

63| 

;  Point 

ES: [BX] 

to  vuport  structure 

64| 

getvp: 

mov 

ax,  vuport+2 

;  get  pointer  segment 

65| 

mov 

es,  ax 

66| 

mov 

bx,  vuport 

;  get  offset 

67  | 

681 

;  Clip 

if  starting  coordinates  outside  viewport 

691 

mov 

cx,  y 

;  get  y 

701 

cmp 

cx,  es:[bx+6] 

;  is  y  within  viewport? 

711 

ji 

checkx 

;  ok  if  so 

72| 

jmp 

quit 

;  else  quit 

73| 

checkx. 

mov 

ax,  x 

;  get  x 

74| 

cmp 

ax,  es:[bx+4] 

;  is  x  within  viewport? 

751 

jl 

remap 

;  ok  if  so 

761 

jmp 

quit 

;  else  quit 

77| 

781 

;  Map  starting  coordinates  to  current 

viewport 

791 

remap : 

add 

ax,  es: [bx] 

;  offset  x  by  vuport. left 

80| 

mov 

x,  ax 

;  save  remapped  X 

811 

add 

cx,  es:[bx+2] 

;  offset  y  by  vuport. top 

821 

mov 

y ,  cx 

;  save  remapped  Y 

831 

84| 

;  Clip 

line  length  to  viewport  width 

851 

mov 

ax,  es : [bx+4 ] 

;  get  vuport. width 

86| 

sub 

ax,  x 

;  maxlength  =  width  -  starting  x 

87 

add 

ax,  es: [bx] 

;  +  vuport. left 

88| 

cmp 

ax,  len 

;  if  maxlength  >  length 

891 

jg 

wmO 

;  length  is  ok 

(continued  on  page  146) 
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Listing  Two  (Listing  continued,  text  begins  on  page  124.) 


90| 

mov 

len,  ax 

;  else  length  =  maxlength 

911 

921 

;  Set  6845  for  write  mode  0,  all  planes  enabled,  color  selected 

93! 

wmO :  mov 

dx,  03CEh 

94 

mov 

ax,  0005h 

;  Set  write  mode 

951 

out 

dx,  ax 

961 

mov 

ax,  OFFOOh 

;  Set/Reset  reg,  enable  all  planes 

97| 

out 

dx,  ax 

98| 

mov 

ax,  OFFOlh 

;  Enable  set/reset  reg,  all  planes 

99| 

out 

dx,  ax 

1001 

mov 

dx,  03C4h 

;  6845  address  reg 

1011 

mov 

al,  2 

;  Data  reg 

102| 

mov 

ah,  _colorl 

;  Palette  reg  planes  enabled 

1031 

out 

dx,  ax 

;  Set  color  code 

104| 

;  Following  added  May  '89 

1051 

mov 

ah,  3 

;  Function  select  reg 

1061 

xor 

al,  al 

;  Pixel-replace  mode 

107| 

out 

dx,  ax 

1081 

1091 

;  Compute  x 

coord  for  last  byte  to  be 

written 

1101 

mov 

bx,  x 

;  get  start  of  line 

nil 

add 

bx,  len 

;  end  =  start  +  length 

112| 

mov 

cx,  bx 

1131 

and 

cx,  0FFF8h 

;  x  coordinate  where  odd  bits 

114| 

mov 

last,  cx 

;  at  end  of  line  begin 

1151 

1161 

;  Compute  number  of  odd  pixels  at 

end 

of  line 

117| 

sub 

bx,  cx 

1181 

mov 

oddeol,  bx 

;  save  it 

1191 

1201 

;  Construct 

pixel  mask  for  last  byte  of  line 

1211 

cmp 

bx,  0 

1221 

jz 

bsol 

;  go  if  no  odd  pixels 

123| 

xor 

ax,  ax 

124| 

eolb:  shr 

ax,  1 

;  shift  right  and 

1251 

or 

ax,  80h 

;  set  H/O  bit 

1261 

dec 

bl 

;  until  mask  is  built 

127| 

jnz 

eolb 

128| 

mov 

eolbits,  ax 

;  then  save  mask 

1291 

1301 

;  Compute  number  of  odd  pixels  at 

start  of  line 

1311 

bsol :  mov 

cx,  X 

;  get  starting  X  again 

1321 

and 

cx,  7 

;  ♦  of  pixels  from  start  of  byte 

1331 

jz 

saddr 

;  go  if  none 

1341 

mov 

bx,  8 

1351 

sub 

bx,  cx 

;  ♦  of  pixels  to  write 

1361 

mov 

oddsol,  bx 

;  save 

137| 

1381 

;  Construct 

pixel  mask  for  first 

byte 

of  line 

1391 

xor 

ax,  ax 

1401 

solb:  shl 

ax,  1 

;  shift  left  and 

141| 

or 

ax,  1 

;  set  L/O  bit 

142| 

dec 

bl 

;  until  mask  is  built 

143| 

jnz 

solb 

144| 

mov 

solbits,  ax 

;  then  save  mask 

145| 

146| 

;  Translate 

last  byte  X  into  an  address 

147| 

saddr :  mov 

ax,  OAOOOh 

148| 

mov 

es,  ax 

;  ES  ==>  video  buffer 

1491 

mov 

bx,  y 

;  get  row 

1501 

mov 

ax,  80 

1511 

mul 

bx 

1521 

mov 

bx,  ax 

;  BX  =  row  offset  =  row  *  80 

1531 

push  bx 

;  save  row  offset 

154| 

mov 

ax,  last 

;  get  last  byte  X 

155| 

mov 

cl,  3 

1561 

shr 

ax,  cl 

;  shift  for  col  offset 

157| 

add 

bx,  ax 

;  last  offs  -  row  offs  +  col  offs 

1581 

mov 

last,  bx 

159| 

160| 

;  Compute  address  of  first  byte  (ES : [BX] ) 

161| 

pop 

bx 

;  fetch  row  offset 

162| 

mov 

ax,  x 

;  get  col  offset 

1631 

mov 

cl,  3 

1641 

shr 

ax,  cl 

;  shift  right  3  for  col  offset 

165| 

add 

bx,  ax 

;  offset  =  row  offs  +  col  offs 

1661 

cmp 

bx,  last 

;  is  first  byte  also  last? 

167| 

jz 

weol 

;  skip  to  end  mask  if  so 

1681 

1691 

;  Write  start  of  line 

1701 

mov 

dx,  03CEh 

;  6845  port 

171| 

mov 

ah,  solbits 

;  start-of-line  mask 

172| 

cmp 

ah,  0 

173| 

jz 

w8 

;  go  if  empty  mask 

174  | 

mov 

al,  8 

;  set  bit  mask  reg 

1751 

out 

dx,  ax 

1761 

mov 

cl,  es: [bx] 

;  load  6845  latches 

177| 

mov 

ax,  solbits 

1781 

neg 

al 

;  complement 

179| 

dec 

al 

;  for  reversed  bit  mask 

180| 

and 

al,  cl 

;  filter  previously  unset  pixels 

181| 

mov 

es: [bx] ,  al 

;  clear  affected  bits 

1821 

mov 

al,  colorl 

183| 

mov 

es : [bx] ,  al 

;  set  affected  bits 

184| 

inc 

bx 

;  next  byte 

185| 

cmp 

bx,  last 

;  ready  for  end  of  line  yet? 

186| 

jae 

weol 

;  go  if  so 

187| 

188| 

;  Write  8  pixels  at  a  time  until 

last 

byte  in  line 

189| 

w8 :  mov 

ax,  0FF08h 

;  update  all  pixels  in  byte 

190| 

out 

dx,  ax 

;  set  bit  mask  reg 

191| 

mov 

al,  es:[bx] 

;  load  6845  latches 

192| 

xor 

al,  al 

1931 

mov 

es : [bx] ,  al 

;  clear  all  pixels 

194| 

mov 

al,  _colorl 

195| 

mov 

es : [bx] ,  al 

;  set  all  bits 

1961 

inc 

bx 

;  next  byte 

197| 

cmp 

bx,  last 

;  thru? 

1981 

1991 

jnz 

w8 

200| 

;  Write  end  of 

Line 

2011 

weol :  mov 

dx,  03CEh 

2021 

mov 

ah,  eolbits 

203| 

cmp 

ah,  0 

204| 

jz 

rvc 

205| 

mov 

al,  8 

2061 

out 

dx,  ax 

207| 

mov 

cl,  es : [bx] 

2081 

mov 

ax,  eolbits 

2091 

neg 

al 

210| 

dec 

al 

211 1 

and 

al,  cl 

2121 

mov 

es:(bx],  al 

213| 

mov 

al,  colorl 

2141 

215| 

mov 

es:[bx],  al 

2161 

;  Restore  video 

controller 

217| 

rvc :  mov 

dx,  03CEh 

2181 

mov 

ax,  0005h 

219| 

out 

dx,  ax 

2201 

mov 

ax,  0FF08h 

221| 

out 

dx,  ax 

222| 

mov 

ax,  0003h 

223| 

out 

dx,  ax 

224| 

xor 

ax,  ax 

2251 

out 

dx,  ax 

2261 

mov 

ax,  OOOlh 

227| 

out 

dx,  ax 

228| 

mov 

dx,  03C4h 

2291 

mov 

ax,  0F02h 

2301 

2311 

out 

dx,  ax 

232| 

;  End  of  routine 

2331 

quit :  mov 

sp,  bp 

2341 

pop 

bp 

2351 

retf 

2361 

hline  ENDP 

237| 

2381 

2391 

END 

;  loop  if  not 

;  6845  port 
;  end-of-line  mask 

;  go  if  empty  mask 
;  set  bit  mask  reg 

;  load  6845  latches 

;  complement 

;  for  reversed  bit  mask 
;  filter  previously  unset  pixels 
;  clear  affected  bits 

;  set  affected  bits 

state 

;  write  mode  0,  read  mode  0 

;  default  bit  mask 

;  default  function  select 

;  zero  Set/Reset 

;  zero  Enable  Set/Reset 

;  6845  address  reg 
;  Data  reg,  enable  all  planes 


End  Listing  Two 


Listing  Three 

/*  From  May,  ' 89  */ 

I*  - */ 

typedef  int  VP_HAN; 

void  far  default_viewport  (int  height); 

VP_HAN  far  vp_open  (int  x,  int  y,  int  width,  int  height); 

/*  open  viewport,  make  it  active 


/*  viewport  handle  type 
/*  init  default  viewport 


int  far  vp_use  (VP_HAN  vp) ; 
void  far  vp_close  (VP_HAN  vp) ; 
void  far  vp_outline  (VP_HAN  vp) ; 
VP_HAN  far  vp_active  (void); 
int  far  vpwidth  (void) 
int  far  vp_height  (void) 


/*  make  vp  active 
/*  close  viewport 
/*  outline  vp 
/*  get  handle  of  active  vp 
/*  get  active  vp  width 
/*  get  active  vp  height 


*/ 

*/ 

*/ 

*/ 

*/ 

*/ 

*/ 

*/ 

*/ 


End  Listing  Three 


Listing  Four 


/*  VUPORT.C:  Library  source  for  viewport  support  */ 

/*  This  is  part  of  the  GRAFIX  library  */ 

/*  K.  Porter,  DDJ  Graphics  Programming  Column,  May  '89  */ 

♦include  <stdio.h> 

♦include  <stdlib.h> 

♦include  "grafix.h" 

typedef  struct  vpnode  (  /*  viewport  descriptor  node  */ 

int  left,  top,  width,  height, 

handle; 

struct  vpnode  far  *next,  far  *prev; 

)  VPNODE; 

♦if  ! defined  TRUE 
♦define  FALSE  0 
♦define  TRUE  ! FALSE 
♦endif 

VPNODE  far  *vplist  =  NULL;  /*  pointer  to  list  of  vpnodes  */ 

VPNODE  def_vp  =  (0,  0,  640,  350,  0);  /*  default  viewport  */ 

VPNODE  far  *vuport  =  &def_vp;  /*  ptr  to  current  viewport  */ 

(continued  on  page  148) 
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Listing  Four  (Listing  continued,  text  begins  on  page  124.) 


void  far  default_viewport  (int  height) 

(  /*  initialize  default  viewport 

vuport->height  =  height; 

,  /* - */ 

VP_HAN  far  vp_open  (int  x,  int  y,  int  width,  int  height) 

(  /*  open  a  viewport 

VPNODE  far  *newvp,  far  *listnode; 


newvp  =  malloc  (sizeof  * newvp ) ; 
newvp->next  =  newvp->prev  =  NULL; 
newvp->left  =  x; 
newvp->top  =  y; 
newvp->width  =  width; 
newvp->height  =  height; 
newvp->handle  =  1; 
if  (vplist  ==  NULL) 
vplist  =  newvp; 
else  { 

listnode  =  vplist;  /* 

while  (listnode->next  !=  NULL) 
listnode  =  listnode->next; 
listnode->next  =  newvp; 
newvp->prev  =  listnode; 
newvp->handle  -  listnode->handle 


/*  make  space 
/*  init  list  ptrs 
/*  set  descriptor 


/*  set  first  viewport 
add  viewport  to  list 


/*  find  tail 
/*  update  pointers 


1; 


/*  and  handle 


vuport  =  newvp; 
return  newvp->handle; 
/*  - 


/*  make  new  viewport  active 


int  far  vp_use  (VP  HAN  vp) 

( 

VPNODE  far  *port; 
int  success  =  FALSE; 

if  (vp  ==  0)  ( 
vuport  =  &def_vp; 
success  =  TRUE; 

)  else  { 
port  =  vplist; 
do  ( 

if  (port->handle  ==  vp) 
success  -  TRUE; 
break; 

1 

port  =  port->next; 

)  while  (port  !=  NULL); 
if  (success) 

vuport  =  port; 

} 

return  success; 

,  /*  - 


/*  make  vp  active 


/*  switch  to  default  viewport 
/*  find  desired  viewport 


/*  jump  out  of  loop  when  found  */ 


/*  make  active  */ 


void  far  vp_close  (VP_HAN  vp) 

{ 

VPNODE  far  *port; 

if  (vp  ==  0)  return; 
port  =  vplist; 

while  (port->next  !=  NULL)  { 
if  (port->handle  ==  vp) 
break; 

port  =  port->next; 

) 

if  (port  !=  NULL)  { 

if  (port->next  !=  NULL) 

port->next->prev  =  port->prev; 
if  (port->prev  !=  NULL) 

port->prev->next  =  port->next; 
if  (port  ==  vplist) 
vplist  =  port->next; 
if  (port  ==  vuport)  /*  if  removing  active  vp 

vuport  =  sdefvp; 
free  (port); 

I 

,  /*  - 

void  far  vp_outline  (VP_HAN  vp)  /*  outline  vp 

/*  outline  is  immediately  outside  viewport  area 

{ 

VP_HAN  active; 
int  x,  y,  w,  h; 


/*  close  a  viewport 


/*  can't  close  default  vp 
/*  find  desired  viewport 


/*  viewport  was  found 
/*  so  remove  from  list 


/*  if  removing  head 


active  =  vp_active(); 
if  (vp_use  (vp) )  { 
x  =  vuport->left-l; 
y  =  vuport ->t op- 1; 
w  =  vuport ->width+l; 
h  =  vuport->height+l; 

/*  draw  outline  */ 
vp_use  (0) ; 

draw_rect  (x,  y,  w,  h; 
vp_use  (active) ; 

) 

,  /* - 


/*  save  current  viewport  */ 


/*  full  screen 
/*  restore  active  viewport 


VP_HAN  far  vp_active  (void) 


return  vuport ->handle; 

,  /* - 


/*  get  handle  of  active  vp 


int  far  vp_width  (void) 


return  vuport->width; 

,  /* - 


/*  get  active  vp  width 


int  far  vp_height  (void)  /*  get  active  vp  height  */ 

{ 


return  vuport->height; 

I  /* - */ 


End  listing  Four 


Listing  Five 


/*  VP.C:  Draws  several  viewports  */ 

/*  Hex  star  inside  each  */ 

/*  K.  Porter,  DDJ  Graphics  Programming  Col,  5/89  */ 

finclude  "grafix.h" 
finclude  <conio.h> 

int  hexl ( ]  =  (25,55,  110,20,  110,90,  25,55); 
int  hex2 ( ]  =  (55,20,  135,55,  55,90,  55,20); 

void  main() 

( 

VP_HAN  vpl ,  vp2,  vp3; 

if  (init_video  (EGA))  ( 

/*  Draw  star  in  default  viewport  */ 
set_colorl  (5);  /*  magenta  */ 

polyline  (3,  hexl); 
polyline  (3,  hex2); 
set_colorl  (9); 

/*  Draw  star  in  unbordered  viewport  */ 
set_colorl  (1);  /*  blue  */ 

vpl  =  vp_open  (60,  250,  200,  95); 
polyline  (3,  hexl); 
polyline  (3,  hex2) ; 

/*  Draw  star  in  small  bordered  viewport  */ 
vp2  =  vp_open  (200,  150,  100,  75); 
vp_outline  (vp2); 

set_colorl  (15);  /*  white  */ 

polyline  (3,  hexl); 
polyline  (3,  hex2); 

/*  Draw  star  in  filled  bordered  viewport  */ 
vp3  =  vp_open  (400,  60,  140,  100); 
vpoutline  (vp3) ; 

set_colorl  (2);  /*  green  */ 

fill_rect  (0,  0,  vp_width(),  vp_height () ) ; 
set_colorl  (4);  /*  red  */ 

polyline  (3,  hexl); 
polyline  (3,  hex2); 

/*  Wait  for  keypress,  then  close  vp's  and  quit  */ 

getch () ; 

vp_close  (vpl); 

vp_close  (vp2); 

vp_close  (vp3); 

) 

) 


End  Listing  Five 


Listing  Six 


/*  LINEGRAF.C:  Self-scaling  viewports  showing  a  line  graph  */ 
/*  K.  Porter,  DDJ  Graphics  Programming  Column,  May  '89  */ 

linclude  "grafix.h" 
linclude  <conio.h> 

int  data  []  =  (30,  70,  10,  40,  30,  80,  60,  90,  40,  50,  40); 

void  main  () 

{ 

void  graph  (void) ; 

VP_HAN  vpl,  vp2,  vp3; 

if  (init_video  (EGA) )  ( 

/*  Open  three  viewports  */ 

vpl  =  vp_open  (  1,  1,  360,  150); 

vp2  =  vpopen  (  1,  170,  638,  170); 

vp3  =  vp_open  (500,  50,  80,  50); 
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/*  First  version  upper  left  quadrant  */ 
vp_use  (vpl); 

set_colorl  (14);  /*  yellow  */ 

vp_outline  (vpl); 
graph  ()  ; 

getch();  /*  wait  for  keypress  */ 

vp_close  (vpl); 


/*  Second  across  bottom  */ 


vp_use  (vp2); 
set_colorl  (2); 
vp_outline  (vp2); 
graph () ; 
getch () ; 
vp_close  (vp2); 

/*  Third  at  upper 
vp_use  (vp3); 
set_colorl  (3); 
vp_outline  (vp3); 
graph ( ) ; 
getch () ; 
vp_close  (vp3); 

I 

)  /* - 


/*  green  */ 

/*  wait  for  keypress  */ 

right  */ 

/*  cyan  */ 

/*  wait  for  keypress  */ 
- */ 


void  graph  (void)  /*  draw  self-scaling  line  graph  */ 

( 

int  npts,  p,  prevx,  prevy,  curx,  cury; 
double  vint,  hint; 

npts  -  sizeof  (data)  /  sizeof  (int);  /*  #  data  points  */ 
/*  Scaling  factors  for  data  points  */ 

hint  =  (double)  vp_width{)  /  (npts  -  1);  /*  horizontal  */ 
vint  =  (double)  vp_height()  /  100.0;  /*  vertical  */ 

/*  Draw  the  graph  */ 

prevx  =  0;  prevy  =  vp_height()  -  (int) (data [0]  *  vint); 
for  (p  =  1;  p  <  npts;  p++)  { 
curx  =  (int) (p  *  hint) ; 

cury  =  vp_height()  -  (int) (data (p)  *  vint); 
draw_line  (prevx,  prevy,  curx,  cury); 
prevx  =  curx;  prevy  =  cury; 

) 


End  Listings 


SfRUCJURED  PROGRAMMING 


listing  One  (Text  begins  on  page  132.) 

{  Turbo  Pascal  4. 0/5.0  Registers  type,  from  the  DOS  unit:  ) 

Registers  =  RECORD 

CASE  Integer  OF 

0  :  (AX,  BX,  CX,  DX,  BP,  SI,  DI,  DS,  ES,  Flags  :  Word; 

1  :  (AL, AH, BL, BH, CL, CH,DL, DH  :  Byte; 

END; 

(*  TopSpeed  Modula  2's  Registers  type,  from  the  SYSTEM  module:  *) 

Registers  =  RECORD 

CASE  :  BOOLEAN  OF 

I  TRUE  :  AX, BX, CX, DX, BP, SI , DI , DS, ES  :  CARDINAL; 

Flags  :  BITSET; 

|  FALSE  :  AL, AH, BL, BH, CL, CH, DL, DH  :  SHORTCARD; 
END; 

END; 


End  listing  One 


Listing  Two 


VTOOLS 

Virtual  screen  I/O  tools  unit 


by  Jeff  Duntemann  KI6RA 
Turbo  Pascal  5.0 
Last  modified  1/17/89 


UNIT  VTools; 


USES  DOS, 

Textlnfo, 

Screens; 


f  Standard  Borland  unit  } 
(  Given  in  DDJ  3/89  ) 
(  Given  in  DDJ  4/89  ) 


CONST 

SingleLine  =  False; 
DoubleLine  =  True; 


{  To  specify  single  vs.  double  line 
{  bars  and  boxes  ) 


TYPE 

LineChars 

BarStrings 

BoxRec 


CONST 

BoxChars 


VAR 

HBars 

VBars 


=  ARRAY [SingleLine. .DoubleLine]  OF  Char; 

=  ARRAY [SingleLine. .DoubleLine]  OF  String; 
=  RECORD 


ULCorner, 

(  Each  field  in  this  record 

URCorner, 

(  contains  both  the  single 

LLCorner, 

(  line  and  double 

line 

LRCorner, 

(  form  of  the  named  line 

HBar, 

(  character,  indexed  by 

VBar, 

{  the  Boolean  constants 

LineCross 

1  SingleLine  and 

DoubleLine 

TDown, 

{  defined  above. 

TUp, 

TRight, 

TLeft  :  LineChars 

END; 

BoxRec  = 

(ULCorner 

(#218, #201);  1  Z 

I  ) 

URCorner 

(#191, #187);  {  ? 

;  ) 

LLCorner 

(#192, #200);  f  0 

H  ) 

LRcorner 

(#217, #188);  (  Y 

<  ) 

HBar 

(#196, #205);  {  - 

M  ) 

VBar 

(#179, #186);  (  - 

:  ) 

LineCross 

(#197, #206);  (  E 

N  ) 

TDown 

(#194, #203);  (  B 

K  ) 

TUp 

(#193, #202);  (  A 

J  ) 

TRight 

(#195, #185);  (  C 

9  ) 

TLeft 

(#180, #204) ) ;  (  4 

L  > 

BarStrings; 

BarStrings; 


{  Horizontally  oriented  bars  ) 
(  Vertically  oriented  bars  ) 


PROCEDURE  MakeBox (Target 

X,Y, Width, Height 
IsSingleLine 


IMPLEMENTATION 


PROCEDURE  MakeBox (Target 

X, Y, Width, Height 
IsSingleLine 


ScreenPtr; 
Integer; 
Boolean)  ; 


ScreenPtr; 
Integer; 
Boolean) ; 


(continued  on  page  1 50) 
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STRUCTURED  PR0GRAMMIN6 


Listing  Two  (Listing  continued,  text  begins  on  page  132.)  I  listing  Three 


BEGIN 

GotoXY (Target,  X,Y) ; 

WITH  BoxChars  DO 
BEGIN 

{  Display  the  top  line:  } 

WriteTo (Target ,ULCorner[IsSingleLine]+ 

Copy (HBars [IsSingleLine) , 1, Width-2) + 
URCorner [IsSingleLine] ) ; 

{  Display  the  left  side:  } 

GotoXY (Target,  X,Y+1) ; 

WriteDownTo (Target, Copy (VBars [IsSingleLine] , 1, Height-2) ) ; 
{  Display  the  right  side:  ) 

GotoXY (Target, X+Width-1, Y+l) ; 

WriteDownTo (Target, Copy (VBars [IsSingleLine] ,1, Height-2) ) ; 
{  Display  the  bottom  line:  } 

GotoXY (Target, X, Y+Height-1) ; 

WriteTo (Target , LLCorner [ IsSingleLine] + 

Copy (HBars [IsSingleLine] , 1, Width-2) + 
LRCorner [IsSingleLine] ) ; 

END; 

END; 


{  VTOOLS  Initialization  Section  } 

BEGIN 

(  This  fills  the  predefined  HBars/VBars  variables  with  line  characters: 
FillChar (HBars [SingleLine] , 

SizeOf (HBars [SingleLine] ) , 

BoxChars. HBar [SingleLine]) ; 

FillChar (HBars [DoubleLine] , 

SizeOf (HBars [DoubleLine] ) , 

BoxChars. HBar [DoubleLine] ) ; 

HBars [SingleLine,  0]  :=Chr(255); 

HBars (DoubleLine,  0]  :=  Chr (255) ; 


{  V-Screen  procedure  that  writes  from  X,Y  downward:  ) 

PROCEDURE  WriteDownTo (Target  :  ScreenPtr;  S  :  String); 

VAR 

I,K  :  Integer; 

TY  :  Byte; 

ShiftedAttr  :  Word; 

BEGIN 

{  Put  attribute  in  the  high  byte  of  a  word:  } 

ShiftedAttr  :=  CurrentAttr  SHL  8; 

WITH  Target"  DO 
BEGIN 
TY  :=  Y; 

K  :=  0; 

FOR  I  :=  0  TO  Length (S) -1  DO 
BEGIN 

IF  Y+I  >  VHEIGHT  THEN  (  If  string  goes  past  bottom  of  screen, 
BEGIN  (  we  wrap:  ) 

Inc (X) ;  (  Increment  X  value  } 

Y  :=  1;  TY  :=  1;  {  Reset  Y  and  temp  Y  value  to  1  } 

K  :=  0;  (  K  is  the  line-offset  counter  } 

END; 

(  Here  we  combine  the  character  from  the  string  and  the  ) 

(  current  attribute  via  OR,  and  assign  it  to  its  location  ) 

[  on  the  screen:  | 

Word (ShcwPtrs [Y+K] A [X] )  :=  Word(S[I+l])  OR  ShiftedAttr; 

Inc (TY) ;  Inc(K); 

END; 

Y  :=  TY;  {  Update  Y  value  in  descriptor  record  ) 

END 

END; 


End  Listing  Three 


FillChar (VBars [SingleLine] , 

SizeOf (VBars [SingleLine] ) , 
BoxChars. VBar [SingleLine] ) ; 
FillChar (VBars [DoubleLine] , 

SizeOf (VBars [DoubleLine] ) , 
BoxChars. V3ar [DoubleLine] ) ; 
VBars [SingleLine, 0]  :=  Chr (255); 
VBars [DoubleLine, 0]  :=  Chr (255); 

END. 


Listing  Four 


End  Listing  Two 


Character  box  draw  demo  program 


by  Jeff  Duntemann  KI6RA 
Turbo  Pascal  V5.0 
Last  update  1/21/89 


PROGRAM  BoxTest; 


USES  Crt, 

Screens, 

VTools; 


{  Standard  Borland  unit  ) 
[  Given  in  DDJ;  4/89  ) 
(  Given  in  DDJ;  5/89  ) 


VAR 

WorkScreen 
MyScreen 
X,  Y 

Width, Height 

Count 

Ch 

Quit 


:  Screen; 

:  ScreenPtr; 
:  Integer; 

:  Integer; 

:  Integer; 

:  Char; 

:  Boolean; 


BEGIN 

Randomize;  (  Seed  the  pseudorandom  number  generator  ) 
MyScreen  :=  @WorkScreen;  {  Create  a  pointer  to  WorkScreen  } 
InitScreen (MyScreen, True) ; 

ClrScreen (MyScreen, ClearAtom) ;  {  Clear  the  entire  screen  } 

Quit  :=  False; 


REPEAT  {  Draw  boxes  until  "Q"  is  pressed:  } 

IF  Keypressed  THEN  {  If  a  keystroke  is  detected  ) 

BEGIN 

Ch  :=  ReadKey;  [  Pick  up  the  keystroke  ) 

IF  Ord(Ch)  =  0  THEN  {  See  if  it's  an  extended  keystroke 

BEGIN 

Ch  :=  ReadKey;  (  If  so,  pick  up  scan  code  ) 

CASE  Ord(Ch)  OF  [  and  parse  it  ) 

72  :  Pan (MyScreen, Up, 1) ;  {  Up  arrow  ) 

80  :  Pan (MyScreen, Down, 1) ;  (  Down  arrow  ) 

END  (  CASE  } 


ELSE  (  If  it's  an  ordinary  keystroke,  test  for  quit:  ) 
IF  Ch  IN  ['Q','q'l  THEN  Quit  :=  True 

END; 

|  Now  we  draw  a  random  box.  } 

(  First  get  random  X/Y  position  on  the  virtual  screen:  } 

REPEAT  X  :=  Random (VWIDTH-5)  UNTIL  X  >  1; 

REPEAT  Y  :=  Random (VHEIGHT-5)  UNTIL  Y  >  1; 

(  Next  get  a  random  width  and  height  to  avoid  wrapping:  ) 
REPEAT 

Width  :=  Random (VWIDTH) 

UNTIL  (Width  >1)  AND  ( (X  +  Width)  <  VWIDTH);; 

REPEAT 

Height  :=  Random (VHEIGHT) 

UNTIL  (Height  >  1)  AND  ( (Y  +  Height)  <  VHEIGHT);; 

(  Draw  the  box:  ) 

MakeBox (MyScreen, X, Y, Width, Height, DoubleLine) ;  {  and  draw  it! 

UNTIL  Quit 
END. 


End  listings 
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RUN  LENGTH  ENCODING 


Listing  One  (Text  begins  on  page  130.) 

*  PROGRAM  RLE.C  * 

*  written  by  Phil  Daley  * 

*  February  3,  1989  * 

int  main (void); 

int  uncompress (unsigned  char  *, int, unsigned  char  *)  ; 
int  compress (unsigned  char  *, int, unsigned  char  *)  ; 
int  process_comp (unsigned  char  *, int, int)  ; 
int  process_uncomp (unsigned  char  *, int, int)  ; 

•include  <stdio.h> 

•include  <memory.h> 

unsigned  char  screen[24] (80]  -  { 

" IMMMMMMMMMMMMMM4MMMMMMMPfl,iMMMMMMMMMMMMMJfl4MMMMMMMMMMMMMMMMM<MMMMMMMMMMMMMMMMM; " , 


o  This  is  a  sample  screen  that  would  be  typical  of  the  type 
that  would  present  information  to  a  user  for  instructions 
or  a  help  screen,  etc. 


o  While  it  contains  a  lot  of  unique  characters  in  the  text 
lines,  it  also  contains  a  lot  of  white  space  in  empty  lines 
and  margins. 


o  It  would  be  unusual  for  the  compression  algorithm  used 
here  to  find  any  repeated  characters  other  than  spaces 
and  the  border. 


) 

else  ( 

k  -  process_uncomp(in_array,i,in_size)  ; 
out_array [ j++]  -  (unsigned  char)k  ; 
for~(l  -  0;  1  <  k;  1++) 

out_array [ j++]  -  in_array (i++) 

) 


» 

process_comp(in_array, i, ii 
unsigned  char  *in_array  ; 
int  i  ; 

int  in_size  ; 

( 


register  : 


.  len  ■ 


while  (in_array(i)  —  in_array[i  +  1)  ii  i  <  in_size)  ( 
len++  ; 
i++  ; 

if  (len  ~  126) 
break  ; 

} 

return (len  +1)  ; 

) 

process_uncomp  »***»»*****•***»*•»******»•*/ 
process_uncomp(in_array,  i,  insize) 
unsigned  char  *in_array  ; 
int  i  ; 

int  in_size  ; 

( 

register  int  len  -  0  ; 


unsigned  char  new (2000)  ; 


main  •***•••***•**•*<* 

int  main()  /*  this  is  a  demo  main  */ 

1 

int  orig_length  -  1920  ; 
int  compressed_length  ; 

int  i,  j  ; 


/ 


compressed  length  -  compress (screen (0) , orig_length, new)  ; 
printf ("Original  screen  (1920)  compressed  to  %d  bytes \n", compressed_length)  ; 
memset (screen, 0,1920)  ;  /*  erase  the  orig  */ 

orig_length  -  uncompress (new, compressed_length, screen (0))  ; 
printf ("And  back  to  the  original  (%d)  length\n", orig_length)  ; 
for  (i  -  0;  i  <  24;  i++) 

for  (j  -  0;  j  <  80;  j++)  /»  show  it  •/ 

printf ("%c", screen(i) |jj)  ; 

return (0)  ; 

» 

compress  **»♦»****»*•»***»«**»*******/ 
compress (in_array, in_size, out_array) 
unsigned  char  »in_array  ; 
int  in_size  ; 

unsigned  char  *out  array  ; 

( 

register  int  i  -  0  ; 
register  int  j  «  0  ; 
register  int  k  ; 
register  int  1  ; 

while  (i  <  in_size)  ( 

if  (in_array[i]  --  in  array (i  +1)  &t  in_array(i  +  1]  —  in_array(i  +2))  ( 
k  -  process_comp(In_array, i,in_size)  7 

out_array[ j++)  -  (unsigned  char)k  |  0x80  ; 
out_array[  -  in_array[i]  ; 
i  +-  k  ; 


while  ( (in_array [i ]  !-  in_array(i  +  1)  || 
in_array(i)  ! « 

len++  ; 
i++  ; 

if  (len  —  127) 
break  ; 


) 

return (len)  ; 


in_array [i 


2))  &s  i  <  in_size)  ( 


/•*•**•.*.*.*.*•*.*****  uncompress  »*»»*«•********»»*****«/ 

uncompress (in_array, in_size, out_array) 

unsigned  char  *in_array  ; 

int  in_size  ; 

unsigned  char  *out_array  ; 

( 


register  int  i  ; 

register  int  j  ; 

register  int  k-0  ; 

register  int  1  ; 

for  (i  -  0;  i  <  in_size;)  ( 

j  -  in_array [i++]  ; 
if  (j  >  128)  ( 

for  (j  —  128;  j  >  0;  j— ) 

out_array (k++)  -  in_array[i]  ; 

i+*  ; 

) 

else 

for  (1  -  0;  1  <  j;  1++) 

out_array (k++)  -  inarray (i++)  ; 

) 

return  (k)  ; 

i  End  Listing  One 
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The  Lattice  C++  compiler  package  now 
includes  new  documentation  for  the 
standard  Lattice  C  library.  The  separate 
volume  describes  the  more  than  300 
Lattice  C  functions  that  are  also  avail¬ 
able  to  C++. 

Lattice  C++  translates  C++  source 
code  into  C  programs  that  are  then 
compiled  by  the  Lattice  C  compiler. 
The  new  volume  of  documentation 
gives  users  a  synopsis  of  each  C  func¬ 
tion’s  use,  a  description  of  the  func¬ 
tion’s  purpose,  the  return  value  pro¬ 
vided  by  the  function,  and  a  cross  ref¬ 
erence.  The  reference  manual  also  pro¬ 
vides  application  examples. 

C++  programmers  can  call  a  Lattice 
C  function  for  math,  file  I/O,  memory 
allocation,  and  system  functions;  write 
complete  program  modules  in  C  when 
the  programs  do  not  require  C++  fea¬ 
tures;  and  build  C++  objects  utilizing 
C  functions. 

Lattice’s  C++  package  uses  the  AT&T 
translator  kit.  A  driver,  similar  to  the 
LC  driver  in  the  Lattice  AmigaDOS  C 
compiler,  is  provided  for  translating, 
compiling,  and  linking. 

The  price  of  Lattice  C++  is  $500.  Reg¬ 
istered  users  of  Lattice  C++  will  receive 
a  copy  of  the  new  Lattice  C  Library 
manual  at  no  charge.  Lattice  C++  re¬ 
quires  1.5-Mbyt:e  memory  and  two 
floppy  drives;  a  hard  disk  is  recom¬ 
mended.  Reader  Service  No.  21. 

Lattice  Inc. 

2500  S  Highland  Ave. 

Lombard,  IL  60148 
312-916-1600 

Cortex  Computing  Corp.’s  Enhance! 
adds  several  features  to  DOS  2.0  and 
greater.  Accessed  from  the  command 
line  and/or  batch  files,  Enhance!  coex¬ 
ists  with,  not  replaces,  DOS  and  COM¬ 
MAND.  COM. 

According  to  Cortex,  Enhance!  adds 
symbol/alias  defining  and  processing, 
file  management  (move,  copy,  remove, 
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append,  list,  locate,  and  change  files/ 
groups/attributes),  retrieval  and  reissu¬ 
ing  of  previously  entered  commands, 
the  ability  to  issue  several  commands 
at  one  DOS  prompt,  command  line 
editing,  and  simplified  DOS  directory/ 
drive  maneuvering.  Enhance!  is  RAM 
resident  and  can  load  and  run  in  ex¬ 
panded  memory. 

Symbol  (alias)  processing  allows  the 
user  to  use  symbols  (words)  at  the 
DOS  command  line  for  which  Enhance! 
will  substitute  one  or  more  other  words. 
Symbols  may  be  defined  to  represent 
commands,  parts  of  commands,  sev¬ 
eral  commands,  and  other  symbols.  In 
some  instances,  symbol  processing  re¬ 
places  batch  files  with  symbols  and 
exact  commands  with  abbreviations. 
For  instance,  entering  any  of  DIR 
through  DIRECTORY  could  perform  as 
though  DIR  were  entered. 

With  Enhance!’s  file  management,  the 
user  can  perform  the  following  from 
the  command  line:  list,  copy,  move, 
remove,  protect,  hide,  and  change  the 
date  and  time  values  of  disk  files.  An¬ 
other  feature  is  the  ability  to  specify 
and/or  exclude  files  with  names  and/ 
or  extensions  that  begin  with  one  or 
more  sets  of  letters,  end  with  a  certain 
letter  or  letters,  or  have  a  certain  letter 
or  letters  somewhere  in  between. 

Retrieval  and  reissuing  of  previously 
entered  commands  allows  the  user  to 
recall  and  optionally  modify  and  re¬ 
send  commands  that  have  already  been 
entered.  Several  commands  can  be  en¬ 
tered  at  once,  and  command  line  edit¬ 
ing  supports  lines  longer  than  80  char¬ 
acters. 

This  product  sells  for  $79-95  and  sup¬ 
ports  the  IBM  PC,  XT,  AT,  PS/2,  and 
compatibles  with  at  least  256K  RAM 
and  DOS  2.0  or  greater.  Reader  Service 
No.  20. 

Cortex  Computing  Corp. 

P.O.  Box  116788 
Carrollton,  TX  75011 
214-492-5124 

Quadram  has  released  Version  1.1  of 
its  program  development  toolkit  for  the 
JT  Fax  9600  PC  facsimile  board.  The 
toolkit  contains  instructions  that  en¬ 
able  programmers  to  write  to  the  JT 
Fax  9600’s  shared  RAM  interface,  as 
well  as  working  programs  for  opera¬ 
tions  supported  by  the  board. 

The  code  necessary  to  transmit  a  fac¬ 
simile  resides  on  the  board.  In  addi¬ 
tion,  the  board’s  facsimile  capabilities 
can  be  accessed  without  Quadram  code 
being  resident  with  the  PC’s  main  mem¬ 
ory.  The  JT  Fax  9600  can  also  be  adapted 
to  PC  bus  systems  running  operating 
systems  other  than  MS-DOS,  such  as 
Unix  or  Xenix. 


This  product  is  a  three-quarter  size 
9600  baud  background  board  with  an 
on-board  80188  processor.  It  installs 
in  an  IBM  PC,  XT,  AT,  and  most  com¬ 
patibles,  plus  PS/2  Models  25  and  30. 
A  unit  retails  for  $795.  The  toolkit  is 
available  free  to  registered  JT  Fax  9600 
users  by  contacting  Tom  McElroy  at 
404-564-2353,  ext.  2135. 

Quadram  produces  three  other  PC 
facsimile  products.  JT  Fax  Internal, 
which  sells  for  $395,  is  a  4800  baud 
half  card  for  the  IBM  PC,  XT,  AT,  and 
PS/2  Models  25  and  30,  as  well  as  most 
compatibles.  JT  Fax  Portable  sells  for 
$495  and  is  a  4800  baud  external  ver¬ 
sion,  which  plugs  into  a  computer’s 
serial  port.  Selling  for  $595,  JT  Fax 
PS/Q  is  a  4800  baud  full-length  card 
that  installs  inside  the  IBM  PS/2  Models 
50,  50Z,  60,  70,  80,  and  most  compa¬ 
tibles.  Reader  Service  No.  22. 

Quadram 
One  Quad  Way 
Norcross,  GA  30093-2919 
404-923-6666 

Formation,  Version  1.1,  by  Aspen  Sci¬ 
entific  supports  various  application  in¬ 
terfaces,  such  as  overlapping  windows, 
different  menu  styles,  and  dialog  boxes. 
Formation  in  source  code  form  is  trans¬ 
ported  to  several  operating  systems. 
The  source  code  is  compatible  with 
MS-DOS,  OS/2,  and  Unix  System  V,  as 
well  as  Unix  System  look-a-likes,  such 
as  SCO  Xenix  System  V/386. 

Formation  not  only  supports  menu 
interfaces,  such  as  drop-down  menus, 
pop-up  menus,  and  Lotus-style  menus, 
but  it  also  provides  dialog  boxes  for 
user-to-application  input.  Formation  dia¬ 
log  boxes  support  scrolling  text  prompt¬ 
ers,  option  buttons,  check  boxes,  com¬ 
mand  buttons,  and  scrolling  list  boxes. 
Additionally,  Formation  supports  line 
borders,  shadowing,  and  exploding  win¬ 
dow  refreshes. 

Under  MS-DOS  and  OS/2,  this  prod¬ 
uct  supports  VGA,  EGA,  CGA,  and  MDA 
displays  and  C  compilers.  Formation 
under  Unix  supports  terminals  defined 
in  the  terminfo  database  and  exploits 
line-graphics  capabilities  where  avail¬ 
able. 

Prices  are  $399  for  the  source  code 
bundle  supporting  MS-DOS,  OS/2,  and 
Unix,  and  $159  for  the  binary  bundle 
supporting  MS-DOS  and  OS/2.  Forma¬ 
tion  requires  Aspen  Scientific’s  Curses, 
Version  4.0,  for  MS-DOS  and  OS/2,  and 
Unix  Curses  (provided  with  Unix). 
Reader  Service  No.  23. 

Aspen  Scientific 
10580  W  46th  Ave. 

P.O.  Box  72 

Wheat  Ridge,  CO  80034-0072 
303-423-8088 
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For  writing  memory-resident  programs 
in  Basic,  MicroHelp  has  released  Stay- 
Res  Plus,  Version  3  0.  One  feature  of 
Stay-Res  Plus  is  the  ability  to  specify 
up  to  21  “hot  keys”  that  will  pop  up  the 
program.  Each  hot  key  can  be  a  regular 
key  press  or  a  “shift  only”  hot  key, 
such  as  Ctrl-Alt.  The  SysReq  key  can 
also  be  used  as  a  hot  key. 

The  SRPOKER.COM  program  can  be 
used  to  pop  up  the  program  from  the 
DOS  command  prompt  or  a  batch  file, 
or  pop  the  program  up  after  n  ticks 
have  occurred.  Other  features  include 
shelling  other  programs  or  batch  files 
from  resident  programs  and  removing 
the  program  from  memory  from  within 
the  program,  or  by  executing  a  .COM 
program  from  the  DOS  command  line 
or  a  batch  file. 

The  system’s  current  environment  vari¬ 
ables  can  be  accessed  even  if  they  have 
been  changed  after  the  program  has 
become  resident.  This  includes  PATH, 
COMSPEC,  and  LIB.  In  addition,  files 
can  be  left  open  between  pop  ups. 

System  requirements  include  an  IBM 
PC,  XT,  AT,  PS/2,  80386,  or  compat¬ 
ible;  Microsoft  QuickBasic  2  -  4  or  Bas- 
com  6  with  DOS  3  0  or  later;  QuickBa¬ 
sic  1  or  Bascom  1-5  with  DOS  2.1  or 
later;  an  80  column  monitor;  and  a 
360K  floppy  disk. 


Stay-Res  Plus,  Version  3.0,  sells  for 
$89;  upgrades  are  $60.  Reader  Service 
No.  24. 

MicroHelp  Inc. 

4636  Huntridge  Dr. 

Roswell,  GA  30075 

404-552-0565 

800-922-3383 

Human  Intellect  Systems  has  an¬ 
nounced  the  upgrade  of  its  first  expert 
system  shell  — Instant-Expert  — for  the 
Macintosh.  Instant-Expert,  which  sells 
for  $69.95,  is  a  software  development 
tool  used  to  created  customized  expert 
systems. 

User-entered  logic  or  if/then  rules 
drive  the  application  to  produce  infor¬ 
mation  offered  by  the  subject-area  author¬ 
ity.  Users  can  build  a  stand-alone  ex¬ 
pert  system  based  on  their  knowledge 
of  a  particular  field. 

Release  2.0  features  an  inference  en¬ 
gine  that  uses  forward  and  backward 
chaining,  as  well  as  a  mixed  strategy 
in  which  both  forward  and  backward 
reasoning  are  used.  The  product  sup¬ 
ports  true,  false,  and  unknowns,  and 
allows  the  user  to  ask  “why?”  and 
“how?”  Instant-Expert  also  offers  trace 
functions,  interactive  deduction,  op¬ 
tional  search  strategies  (depth  first  or 
breadth  first),  and  uncertainty  controls. 

- -  The  more  advanced 

expert  system  shell 
Instant-Expert  Plus, 
offers  advanced 
graphics  and  user- 
defined  variables 
and  sells  for  $498. 

Applications  com¬ 
pleted  in  Instant-Ex¬ 
pert  2.0  are  compat¬ 
ible  with  Instant-Ex¬ 
pert  Plus.  Registered 
users  may  also  ap¬ 
ply  their  purchase 
price  toward  the  pur¬ 
chase  of  Instant-Ex¬ 
pert  Plus.  Registered 
Instant-Expert  1.5 
owners  can  up¬ 
grade  to  Instant-Ex¬ 
pert  2.0  for  $25. 

Both  Instant-Ex¬ 
pert  and  Instant-Ex¬ 
pert  Plus  run  on  the 
Apple  Macintosh 
512KE,  SE,  and  II 
computers.  Instant- 
Expert  Plus  also 
runs  on  an  IBM  PC 
or  compatible  with 
640K.  Reader  Serv¬ 
ice  No.  25. 

Human  Intellect 
Systems 

1670  S  Amphlett 


Blvd.,  Ste.  326 
San  Mateo,  CA  94402 
415-571-5939 
800-522-5939 

ParcPlace  Systems  will  soon  release 
the  Smalltalk-80  object-oriented  develop¬ 
ment  environment  for  DECstation  3100 
computers.  The  DECstation  3100  is  a 
MIPS-based  system  using  the  Ultrix  op¬ 
erating  system.  Smalltalk-80  features  a 
set  of  development  and  information 
access  tools,  an  object-oriented  pro¬ 
gramming  language,  tested  applications, 
and  portability  to  a  variety  of  worksta¬ 
tion  and  microcomputer  environments. 

With  this  product,  users  program  by 
selecting  code  modules  from  a  reus¬ 
able  library  and  by  using  built-in  appli¬ 
cations  and  simulations.  It  also  allows 
programmers  to  move  between  writing 
code,  debugging,  and  inspecting  levels 
of  system  operation.  The  environment 
can  also  link  and  access  subroutines 
written  in  other  languages,  such  as  C. 
Smalltalk-80  includes  a  graphical  user 
interface  based  on  overlapping  win¬ 
dows,  pop-up  menus,  multiple  fonts, 
and  mouse-oriented  control. 

Smalltalk-80  is  compatible  with  the 
X-Window  environment  and  is  port¬ 
able  to  Unix,  Mac  OS,  and  MS-DOS 
operating  systems  using  Motorola 
680X0,  Intel  80386,  Sun  SPARC,  or  MIPS 
processors.  Software  support  includes 
a  customer  hotline,  free  upgrades  to 
new  releases,  an  electronic  bulletin 
board,  ParcPlace  newsletters,  Smalltalk- 
80  books  on  advanced  programming 
and  user  interface,  and  in-house  and 
on-site  training  covering  introductory 
through  advance  level  programming. 

This  product  sells  for  $3,995.  Reader 
Service  No.  26. 

ParcPlace  Systems 
2400  Geng  Rd. 

Palo  Alto,  CA  94303 
415-859-1000 


Errata 

In  the  “Of  Interest”  column  (April  1989) 
the  price  of  Glockenspiel  C++  1.2  by 
Imagesoft  was  incorrectly  stated  on  page 
146.  The  correct  price  of  the  product 
is  $495. 


DDJ 


156 


Dr.  Dobb’s Journal,  May  1989 
365 


LETTERS 


(continued  from  page  12) 

Columnist’s  Comedy 

Dear  DDJ, 

I  bought  the  December  1988  issue  of 
DDJ  at  a  software  store  and  was  de¬ 
lighted  with  Al  Stevens’  column  (“C 
Programming”).  It’s  refreshing  to  see 
his  droll  treatment  of  the  C  language’s 
imaginary  portability  and  Intel  8X86 
architecture  in  the  “C  Tool  Set  Errata,” 
and  then  his  sarcastic  declarations  that 
C  is  “language  of  choice,”  to  be  “the 
best  programming  language  ever  de¬ 
vised,”  and  that  he  is  “C  purist.”  Nam¬ 
ing  a  word  processor  “twerp”  is  cute 
too:  What  does  it  really  do?  Play  the 
Mickey  Mouse  Club  theme  song  with 
a  brightly  colored  screen  and  bounc¬ 
ing  ball? 

So  many  microcomputer  magazines 
and  columnists  seem  to  be  overly  seri¬ 
ous.  Thanks  for  bringing  a  bit  of  humor 
to  this  often  drab  and  tedious  business. 
Jim  Miller 

Nashua,  New  Hampshire 

“Find  That  Function”  Revisited 

Dear  DDJ, 

It  made  me  smile  to  read  all  of  the 
“mine-is-better-than-yours”  letters  re¬ 
garding  “Find  that  Function!”  So  far 


we  have  been  shown  “better”  ways  of 
doing  this  task  using  AWK,  GREP,  LEX, 
and  C.  All  of  the  examples  showed 
improvement  on  the  original,  given  one 
assumption.  The  programmer  must 
know  AWK,  GREP,  or  LEX. 

Perhaps  my  mind  is  not  as  powerful 
as  those  of  some  of  the  AWK  wizards 
in  the  world,  but  it  would  take  me 
much  longer  to  do  this  job  in  AWK 
than  in  C  because  I  don’t  know  AWK. 

The  list  of  helpful  programmer’s  tools 
is  long,  and  it  grows  daily.  These  tools 
can  be  fantastically  helpful  for  tasks 
such  as  “Find  That  Function!”  but  most 
programmers  don’t  have  the  time  nec¬ 
essary  to  get  over  the  learning  curve 
of  such  tools.  The  only  programmers 
who  know  them  all  are  the  gurus  whose 
jobs  are  not  to  write  code  but  to  know 
stuff. 

If  I  took  the  time  to  learn  every  use¬ 
ful  tool  that  is  available  to  me,  I  would 
be  much  less  productive  than  I  am 
today.  This  is  because  I  would  spend 
a  significant  portion  of  every  day  pid¬ 
dling  with  the  latest  tool  that  came 
across  my  development  platform. 

It  is  up  to  every  one  of  us  to  deter¬ 
mine  where  to  draw  the  line  on  “pro¬ 
ductivity”  tools.  I  prefer  to  invest  my 


time  in  management,  database  man¬ 
agement,  and  communications.  I  am 
able  to  save  myself  weeks  and  even 
months  by  learning  and  using  tools 
such  as  these. 

Many  of  the  other  productivity  tools 
seem  to  me  to  be  little  more  than  typ¬ 
ing  tools.  And  because  I  type  well,  I 
don’t  spend  much  time  using  this  type 
of  tool.  A  good  editor,  a  source  code 
control  system,  and  my  trusty  Norton 
Utilities  do  everything  I  expect  out  of 
my  typing  tools.  Perhaps  I  would  spend 
a  minute  or  two  less  a  day  if  I  knew 
AWK,  LEX,  GREP,  YACC,  and  so  forth, 
but  it  is  a  long  return  on  investment  for 
the  time  I  must  put  in  to  learn  them. 

My  “mine-is-better-than-yours”  solu¬ 
tion  to  the  “Find  That  Function!”  prob¬ 
lem  is  to  write  programmer’s  documen¬ 
tation  that  includes  the  source  file  for 
the  function.  Then  when  I  need  to  find 
the  function,  I  just  RTFM  (Read  The 
[Dam]  Manual).  When  that  won’t  work, 
I  use  a  simple  text  search  utility  and 
my  eyeballs. 

Tim  Berens 

Dayton,  Ohio 

DDJ 
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$  W  A  I  N  E'  $  FLAMES 


Satanic  Verses 


Could  Intel  policy  at  last  be  forcing 

An  innovation  in  second  sourcing? 

pencer  Katt’s  suggestion  in  January  16’s  PC  Week  that  Chips  &  Technologies  may  “second 
source”  the  Intel  386  by  cloning  it  in  RISC  technology  reminds  me  of  something  Hal 
Hardenbergh  wrote  over  seven  years  ago.  In  issue  #4  of  his  DTACK  Grounded  newsletter  back 
in  November  1981,  Hardenbergh  told  a  hilarious  story  of  Intel’s  search  for  a  domestic  second  source 
(dss)  for  the  8086  to  satisfy  its  new  customer,  IBM.  After  negotiations  with  Jerry  Sanders’  AMD  blew 
up,  Intel  lined  up  Mostek  as  dss,  but  declined  to  give  Mostek  the  mask  set,  expecting  Mostek 
engineers  to  reconstruct  the  chip  from  the  logic  design  data.  This  arrangement  did  not  result  in  any 
8086  chips  being  produced  by  Mostek,  and  Mostek  eventually  defected  to  Motorola.  At  this  point, 
under  pressure  from  its  biggest  customer  to  line  up  a  dss,  Intel  looked  around  and  found  only  one 
candidate  not  pursuing  its  own  device  or  working  with  Motorola,  swallowed  hard,  and  approached 
that  candidate.  What  Intel  swallowed  was  apparently  crow,  served  at  Jerry  Sanders’  table. 

Hardenbergh  opened,  “Intel  has  never  been  philosophically  attuned  to  the  idea  of  a  second 
source.” 

Hardenbergh  has  generally  been  insightful,  and  all  of  three  years  ago  pointed  out  the  overuse 
of  the  word  “paradigm”  in  technical  writing 

Perils  emerge  in  the  new  bus  master: 

You’re  risking  a  crash  if  you  drive  much  faster. 

Steve  Gibson  sometimes  leaves  his  InfoWorld  readers  in  the  dust  as  he  hot-rods  over  the  techie 
terrain.  He  took  some  abuse  recently  for  complaining  that  PostScript  is  too  slow,  which  it  is,  but 
which  is  not  interesting  news  to  people  who  believe  that  PostScript  is  the  only  game  in  town. 
Subsequently,  he  pointed  out  a  big  problem  with  bus  master  cards  for  the  original  AT  bus.  Seems 
that  the  cards,  which  take  over  control  of  the  bus  to  speed  SCSI  hard  disk  access,  work  OK  with  a 
286  or  a  simple  386  system,  but  send  the  system  south  fast  when  invoked  while  running  in  protected 
mode  with  memory  mapping  enabled.  He  discussed  it  in  the  January  16  InfoWorld. 

People  and  firms,  it’s  my  job  to  report, 

Are  judged  by  the  companies  with  which  they  consort. 

George  Bush  says  he  wants  to  be  the  education  president.  Well,  American  education  could  use 
some  attention,  and  he  is  the  most  intellectual  president  we’ve  had  in  eight  years.  The  IEEE  wants 
to  help,  and  has  offered  George  some  advice  on  education  and  scientific  policy.  The  IEEE  U.S. 
Technology  Policy  Conference,  Policy  Imperatives  for  Commercialization  of  U.S.  Technology, 
presented  the  IEEE’s  agenda  for  engineering  education,  technical  innovation,  international 
competitiveness,  and  effective  utilization  of  science  and  technology.  Interestingly,  from  what  I 
could  tell  (I  wasn’t  there),  the  panel  on  technological  innovation  appeared  to  be  a  pitch  for  federal 
support  for  consortiums.  Sure,  I  thought  that  was  where  innovation  took  place,  didn’t  you? 

The  problem  with  which  John  Sculley  must  grapple 

Is,  how  many  ways  can  you  slice  up  an  apple? 

How  many  different  ways  can  a  company  be  structured?  Since  Jobs  left,  Apple  has  been  organized 
and  reorganized  along  —  at  least  —  product,  business  function,  and  now  geopolitical  lines.  My  bet 
for  the  next  organizational  dimension  is  product  footprint.  Seriously. 

There  is  little  of  which  M.  Gasse  is  fonder 

Than  comparing  himself  to  the  chairman  of  Honda. 

Jean-Louis  Gasse  wasn’t  at  his  charming  best  when  he  spoke  at  Macworld  Expo  in  January.  His  first 
mistake  was  in  choosing  Harry  “Absent-Minded  Professor”  Anderson  to  introduce  him.  Anderson’s 
hilarious  speech  would  have  been  tough  for  anyone  to  follow.  Then  he  downplayed  the  importance 
of  voice  recognition,  a  technology  crucial  to  Apple’s  public  daydream,  Knowledge  Navigator. 

Finally,  he  came  off  cold  in  responding  to  questioners  who  wanted  to  know  why  the  Education 
Computer  Company  couldn’t  sell  a  home-priced  Mac  that  people  could  buy  for  the  kids.  Gasse 
compared  Apple  to  Honda,  saying  that  Apple  wasn’t  in  the  low-priced  computer  business.  That 
would  go  down  easier  if  we  didn’t  know  what  would  happen  to  a  low-priced  computer  company 
that  tried  to  fill  the  gap  with  a  Mac  clone. 

Michael  Swaine 
editor-at-large 
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It’s  graphics  time  again  and  in  July  we’ll  be 
giving  you  the  tools  to  roll  your  own  icons, 
examine  how  graphics  are  accomplished 
under  Presentation  Manager,  and  find  out 
what  graphics  programming  is  like  under 
a  multitasking  operating  system  when  graph¬ 
ics  coprocessors  are  used  (yes,  that’s  the 
Amiga).  Add  to  that  an  examination  of 
image  mathematics  that  will  help  you  multi¬ 
ply  your  output,  and  an  indepth  look  at 
debugging  with  Turbo  Debugger,  and  you 
have  next  month’s  DDJ. 
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E  D  I  T  0  R  I 


You  Make 
The  Call 


A  L 


Every  time  we  get  close  to  wrapping  up  another  month’s  worth  of  DDJ,  I  start  thinking 
of  last  February’s  issue  with  the  multitasking  juggler  on  the  cover.  What  with  last  minute 
changes  in  the  number  of  pages  we  have  available,  articles  coming  in  long,  articles 
coming  in  short,  articles  coming  in  late  (or  not  at  all),  and  editors  in  and  out  of  the  office  at 
all  hours,  it  sometimes  amazes  me  that  we  get  the  magazine  out  at  all.  Add  to  that  the  desire 
for  variety  and  balance  among  the  articles  (we  don’t  want  to  have  all  C  or  all  DOS  articles) 
and  we  sometimes  feel  like  we’re  juggling  while  walking  on  a  tightrope. 

As  a  case  in  point,  this  month  we  planned  on  running  the  follow-up  to  our  February  feature 
on  the  Rhealstone,  our  real-time  benchmarking  proposal.  However,  we  underestimated  the 
volume  of  response  (and  thanks  to  all  of  you  who  sent  in  comments)  and  we  simply  weren’t 
able  to  evaluate  and  incorporate  the  recommendations  in  time  for  this  issue.  Our  follow-up 
will  run  later  this  year.  Likewise,  in  May  we  intended  on  running  Martin  Tracy’s  Zen  Forth 
System,  but  we  flat  ran  out  of  room.  It  too  will  run  later  this  year. 

As  for  operating  systems,  we  were  recently  asked  by  a  leading  application  developer 
what  our  cut  —  or  at  least  the  cut  of  DDJ  readers  —  is  on  OS/2.  Their  reason  for  asking,  they 
said,  was  that  they  have  a  lot  of  OS/2  products  that  (surprise,  surprise)  aren’t  selling  too 
well;  and  a  recent  cross-country  trip  hadn’t  shored  up  their  spirits  as  major  customers  said 
that  more  DOS  —  not  OS/2  —  applications  were  what  they  wanted. 

Our  experience  is  that  we’re  beginning  to  see  a  rise  in  the  OS/2  noise  level,  although  the 
major  interest  on  the  part  of  readers  continues  to  be  on  DOS  and,  to  a  lesser  degree,  Unix. 
The  difference  in  our  experience  and  that  of  the  company  mentioned  is  that  the  noise  we 
hear  is  coming  from  developers  —  not  end  users  who  seem  to  be  reacting  with  silence.  We 
get  calls  pretty  much  every  day  from  developers  who  are  looking  for  OS/2  information. 
More  significantly,  we’re  getting  more  and  more  article  proposals  from  programmers  who’ve 
been  working  with  OS/2.  (One  example  of  the  latter  is  a  nice  little  article  by  Nico  Mak,  who 
wrote  April’s  popular  SWAP  article.  After  becoming  frustrated  with  OS/2’s  cryptic  error 
messages,  Nico  wrote  a  utility  that  provides  a  more  detailed  error  report.  Unfortunately,  we 
again  ran  into  one  of  those  situations  where  we  just  didn’t  have  room  to  run  the  utility  this 
month,  but  you  can  expect  to  see  it  before  long.) 

Another  thing  we're  hearing  from  developers  who’ve  been  working  with  OS/2  is  that  once 
they’ve  started  programming  under  OS/2,  they  don’t  want  to  go  back  to  DOS.  That’s  the 
opinion  of  Mansour  Safai,  the  chief  architect  of  Logitech’s  MultiScope  OS/2  debugger.  (And 
if  you  get  a  chance  to  see  this  debugger,  don’t  pass  it  up).I  suspect  that  Nico  Mak  concurs 
even  though  he  hasn’t  explicitly  said  so.  What  he  has  said  is  that  he  rarely,  if  ever,  bothers 
to  boot  DOS  anymore.  OS/2  is  his  primary  working  environment. 

What  this  leads  up  to  is  a  growing  demand  for  OS/2  products,  but  not  the  end-user 
applications  people  expected.  Instead,  the  current  market  seems  to  be  built  around  sophisticated 
development  tools  (like  new  debuggers). 

The  question  developers  must  grapple  with  is  twofold:  should  they  spin  their  wheels 
working  on  OS/2  tools  for  a  market  that’s  still  evolving,  and  how  can  they  get  those  tools 
into  programmer’s  hands.  Vaughn  Vernon’s  idea  sounds  good  to  me.  Vaughn,  who  heads 
Aspen  Scientific,  thinks  developers  ought  to  give  OS/2  tools  away  by  bundling  them  with 
existing  DOS  packages.  His  theory  is  that  developers  can  back  into  the  OS/2  market  with 
character-based  tool  kits,  buying  time  to  develop  “real"  OS/2  programs  that  have  Presentation 
Manager  support.  Vaughn  has  been  doing  this  for  a  while  with  his  tools  and  I’m  interested 
in  keeping  track  of  whether  or  not  it  works.  What  do  you  think? 


Jonathan  Erickson 
editor-in-chief 
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C++ Kernel  Comments 

Dear  DDJ, 

I’m  new  to  C++  and  to  Zortech’s  im¬ 
plementation,  so  I  really  enjoyed  Tom 
Green’s  “A  C++  Multitasking  Kernel” 
in  the  February  1989  issue.  There  is  a 
simple  error  in  Listing  Two,  page  84, 
line  58.  The  new  task. workspace  con¬ 
structor  method  should  end  with  a  clos¬ 
ing  brace  instead  of  the  opening  brace 
as  shown  in  the  listing. 

After  entering  all  the  listings,  MASM 
was  nowhere  to  be  found.  Since  the 
Zortech  compiler  (ZTC)  calls  the  as¬ 
sembler  program  automatically  (and  as¬ 
sumes  MASM),  I  thought  that  I  would 
probably  not  be  able  to  produce  an 
.EXE  program.  By  using  Borland’s  Turbo 
Assembler  and  temporarily  renaming  it, 
I  was  able  to  produce  an  .EXE  program 
that  is  14,685  bytes  long  (small  model). 

This  was  an  interesting  experience 
in  piecing  together  a  running  program. 
Keep  up  the  good  work. 

James  H.  Wilbanks 

Dacula,  Georgia 

Tom  responds:  I  am  glad  you  enjoyed 
my  article.  It  was  a  lot  of  fun  to  write. 
You  are  correct;  there  is  an  error  in  the 
code.  When  I  got  the  first  proofs  back 
from  DDJ,  there  were  a  couple  of  lines 
of  code  missing.  The  last  line  of  the  task 
class  constructor  was  one  of  the  miss¬ 
ing  lines.  I  guess  we  got  crossed  up  on 
what  the  missing  line  should  be.  As  you 
also  found  out,  Borland’s  TASM  works 
just  fine  with  my  code  and  with  the 
Zortech  C++  compiler,  if  you  rename 
it  so  that  the  ZTC  shell  can  find  it.  In 
taskdemo.cpp,  I  say  that  you  must  use 
MASM  5. xx.  I  use  some  of  the  advanced 
features  introduced  in  MASM  5  0  (such 
as  .MODEL,  .DATA,  etc.).  TASM  also 
supports  all  of  these  features.  I  use  both 
TASM  and  MASM  with  my  Zortech  C++ 
compiler.  Here  are  two  more  errors  in 
the  code:  In  Listing  Two  (page  84),  line 
49  reads:  task( );  //  destructor,  but 
should  read:  ~task(  );  //  destructor. 
In  Listing  Two  (page  84),  line  78  reads: 
task::task(void),  but  should  read: 
task:  :~task(void) . 


A  Little  More  on  Little  and  Mohr 

Dear  DDJ, 

Your  magazine  is  informative  as  usual. 
In  reading  through  the  letters  to  the 
editor  (February  1989),  I  couldn’t  help 
but  notice  where  Frank  Little  of  Clydach, 
Swansea  brought  up  the  topic  of  paper 
transfer  vs.  computer  transfer.  I  also 
couldn’t  help  but  notice  that  he  seems 
to  lack  a  basic  understanding  of  the 
human.  I’m  not  putting  him  down,  just 
amplifying  the  missed  point.  Frank,  did 
you  ever  see  any  student  open  only 
one  book  at  a  time  when  really  digging 
in  to  study? 

Currently,  one  of  the  major  differ¬ 
ences  between  humans  and  computers 
is  that  humans  rely  extensively  on  pat¬ 
tern  recognition  for  even  the  most  com¬ 
mon  of  day-to-day  survival  and  com¬ 
puters  (percentage  wise)  have  yet  to 
recognize  any  patterns  beyond  simple 
binary  “text”  (instructions).  Even  on  a 
CAD/CAM  system,  the  computer  can¬ 
not  point  out  the  file  cabinet  on  the 
floor  plan.  And  you  and  I  each  re¬ 
ceived  and  processed  numerous  pat¬ 
terns  in  order  to  navigate  our  way  to 
work  today  (and  in  “real  time”  no  less). 

To  further  belabor  the  point,  even 
children  that  were  raised  by  wolves 
and  such,  who  speak  “no  language,” 
recognize  weeds,  rabbits,  and  rabbits 
in  the  weeds.  Try  getting  your  com¬ 
puter  to  pick  out  your  child  or  sweet¬ 
heart  in  the  picture  there.  The  “raised 
wild”  child  can. 

More:  I  read  Jay  van  Santen’s  request 
for  help  on  large  arrays,  and  I  do  not 
understand  Tonkin’s  reply.  Jay  made  a 
straight  request,  and  Tonkin  simply  went 
off  in  his  own  world.  I  too  now  want  to 
know:  How  large  is  the  data  segment? 

More:  Mr.  Douglas  Mohr  is  quite  cor¬ 
rect;  Intel  propagates  ineptitude  at  an 
alarming  rate,  and  at  the  chip-level  no 
less.  Zilog  has  superior  design  and  im¬ 
plementation  at  most  all  levels  of  IC 
CPUs.  I  also  agree  that  “of  CP/M”  is 
still  a  better  operating  system.  Data  loss 
was  far  less  than  in  my  experiences 
with  MS-DOS,  and  data  recovery  was 
almost  always  possible,  even  in  mul¬ 
tiuser  environments.  Data  recovery  un¬ 
der  MS-DOS  is  almost  nonexistent.  The 
file  following  (linked  list)  method  of 
data  storing  is  full  of  trouble.  Always 
has  been,  always  will  be.  If  you  break 
the  chain  (lose  the  pointers),  you  get 
to  fish  for  your  “anchor”  (data)  at  the 
bottom  of  the  bay  with  all  the  other 
discarded  anchors  (released  data 
blocks).  Even  under  the  best  of  condi¬ 
tions,  I  find  data  recovery  attempts  im¬ 
practical  fewer  than  50  percent  of  the 
time  under  MS-DOS. 

Who  knows,  Mr.  Mohr,  maybe  some¬ 
day  MS-DOS  will  actually  be  docu¬ 


mented  so  users  can  use  it.  I’d  even 
settle  for  consistent  reactions  to  a  given 
program.  Don’t  hold  your  breath 
though.  I’m  not. 

Steven  L.  Turner 

Sacramento,  Calif. 

My  God,  what  a  bunch  of  cry  babies 
in  your  February  letters  page!  Since 
there  were  only  three  letters,  may  I 
respond  to  each  of  them? 

To  Mr.  Frank  Little,  about  your  sen¬ 
tence  “(Programmers’)  salaries  are  sky 
high  .  .  I’ve  read  this  often,  and  my 
response  is  always  “balderdash!”  (Fre¬ 
quently  expressed  in  a  pithier,  shorter 
word.)  I  don’t  think  I’m  overpaid.  My 
clients  don’t  think  I’m  overpaid.  If  they 
did,  they  would  hire  someone  else. 
(On  the  other  hand,  my  wife  thinks  I’m 
underpaid.)  I’ll  gladly  charge  less  once 
someone  decides  that  my  gasoline,  hous¬ 
ing,  utilities,  and  taxes  will  be  compa¬ 
rably  reduced. 

To  Mr.  van  Santen  about  QuickBasic 
and  Bruce  Tonkin  in  his  reply:  First, 
Mr.  van  Santen  obviously  meant  to  say 
that  QB  uses  the  Compact  memory 
model,  not  the  medium  model.  The 
64K  restriction  is,  as  everyone  knows, 
an  artifact  of  the  Intel  architecture.  Every 
language  implemented  for  the  80x86 
family  has  this  problem,  and  most  offer 
at  least  one  way  around  it. 

To  Mr.  Douglas  Mohr  (whose  whin¬ 
ing  prompted  this  letter):  First,  I’m  sorry 
you  were  “forced”  to  use  a  PC  at  work, 
and  I  hope  you  will  soon  be  allowed 
to  work  on  a  PDP  11  again.  In  the 
meantime,  I’d  like  to  douse  your  flames. 

Flame  Zero:  Yes  there  is  abysmal 
PC  software,  and  maybe  Aztec  C  is  one 
example.  There  are  terrible  restaurants, 
terrible  cab  drivers,  and  terrible  cities 
as  well;  very  few  of  them  come  with 
free  upgrades. 

Flame  One:  In  the  Intel  architecture, 
programmers  must  pick  the  memory 
model  for  the  same  reason  that  they 
must  pick  the  variable  types,  file  struc¬ 
tures,  and  sorting  algorithm.  “One  size 
fits  all”  might  work  for  muu  muus,  but 
it  makes  lousy  code.  I  also  prefer  a 
linear  address  space,  such  as  the  680x0 
architecture  provides. 

Flame  Two:  Yes,  you  are  being  naive. 
In  the  case  of  the  C  Users  Group,  you 
are  getting  unsupported  source  code 
for  whatever  machine  and  compiler 
someone  chooses  to  upload.  If  you  use 
CP/M,  and  don’t  have  BDS-C,  then  buy 
if.  If  you  were  looking  for  executables, 
write  to  PC-SIG  or  FOG. 

Flame  Three:  If  you  truly  want  a 
TECO-like  editor  for  the  CP/M,  look  at 
VEdit  (from  CompuView)  or  PMate  (from 
Phoenix,  I  think).  Why  not  write  your 
own  TECO,  starting  with  source  code 
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from  Edward  Ream  ’s  public  domain  ED 
editor,  or  David  Conroy’s  micro-Emacs? 

Flame  Four:  1  also  prefer  Unix,  but 
that’s  not  where  the  market  is.  NeXT  is 
the  next  step  up  from  CP/M?  Funny,  I 
thought  it  was  a  step  up  from  Macin¬ 
tosh. 

Mr.  Mohr,  you  have  the  right  to  bitch  as 
much  as  you  want.  DDJ  editors,  why  must 
you  inflict  this  bitching  on  us  readers? 
Arthur  Metz 
Los  Angeles,  Calif. 

I  read  with  considerable  interest  Douglas 
Mohr’s  letter  in  the  February  1989  issue 
of  DDJ.  I  couldn’t  agree  more!  I  am  a 
programmer  by  profession;  I  write  and 
test  software  for  my  company’s  line  of 
IBM  compatible,  industrial  computer 
systems.  8086  assembly  code  and  MS- 
DOS  bring  home  the  bacon,  but  I  have 
little  love  for  either.  So  I’ll  add  a  few 
more  flames  to  the  fire. 

Continuing  where  Mohr  left  off.  Flame 
Four:  Why  did  Intel  create,  and  Micro¬ 
soft  propagate,  a  set  of  assembler 
pseudo-ops  that  are  totally  unneces¬ 
sary?  MASM  and  its  clones  require  high- 
level  language  constructs,  such  as  “PRO- 
Cedures.”  What  does  that  have  to  do 
with  assembly  language? 

MASM  also  insists  upon  knowing  the 
contents  of  segment  registers.  Why?  Hav¬ 
ing  programmed  just  about  every  mi¬ 
croprocessor  from  the  4004  forward,  I 
have  never  seen  such  a  disastrous  as¬ 


sembler.  It  is  obvious  that  MASM  is  an 
assembler  for  the  C  programmer,  what 
with  structures  and  records  and  such, 
not  an  assembler  for  the  experienced 
assembly  language  programmer.  I  use 
the  version  that  runs  under  CP/M-80, 
although  an  MS-DOS  version  is  avail¬ 
able.  It  isn’t  perfect,  but  it  allows  pro¬ 
grammers  to  write  in  assembly  code, 
not  in  a  pseudohigh-level  language. 

Flame  Five:  Mohr  is  right  in  his  state¬ 
ments  regarding  MS-DOS.  What  do  you 
expect  from  an  illegitimate  cross  be¬ 
tween  CP/M  and  TRS-DOS?  Except  now 
it’s  a  three-way  incestuous  cross  with 
Unix  as  well.  The  original  MS-DOS  com¬ 
bined  the  worst  features  of  CP/M  and 
TRS-DOS,  with  the  best  features  of  nei¬ 
ther.  If  you  want  that,  you’re  much 
better  off  the  CP/M;  it’s  a  much  friend¬ 
lier  development  environment,  even  for 
alien  processors.  Now  they’ve  thrown 
in  some  Unix  features.  If  you  want  that, 
you  might  as  well  go  with  pure  Unix 
and  get  all  the  benefits! 

Flame  Six:  Now  that  we  have  cheap 
AT-class  machines  with  ten  times  the 
memory,  we  can  write  all  our  code  in 
inefficient  high-level  languages,  hog  all 
kinds  of  memory,  and  get  about  the 
same  level  of  performance  as  we  got 
ten  years  ago  from  a  4MHz  Z-80  run¬ 
ning  efficient  machine  code.  The  origi¬ 
nal  4.77MHz  PX  was  a  joke.  My  2-MHz 
IMSAI  will  run  rings  around  it. 

Flame  Seven:  This  is  something  that 


really  doesn’t  matter,  but  I’ve  never 
seen  anyone  say  it  before:  MS-DOS 
machines  in  general,  and  the  original 
PC/XT  in  particular,  have  to  be  the 
ugliest  computers  in  existence.  Just  be¬ 
fore  the  PC  was  introduced  in  1981, 
we  were  starting  to  get  some  really 
nice,  integrated  systems  like  the  TRS- 
80  model  III/IV,  the  NorthStar  Advan¬ 
tage,  the  Superbrain  line,  and  so  forth. 
Then  along  comes  IBM  with  a  system 
that  instantly  reminded  me  of  a  bad 
cross  between  a  model  I  TRS-80  and 
an  Apple  11+ .  Suddenly,  we  were  thrown 
back  to  1977  with  three  boxes  con¬ 
nected  together  by  ten  million  miles  of 
cables.  And  the  three  boxes  didn’t  even 
go  together.  At  least  the  old  model  I 
TRS-80’s  parts  looked  like  they  belonged 
together!  I  suppose  I  have  to  reluc¬ 
tantly  agree  with  the  thought  that  this 
allows  you  to  select  your  own  monitor 
and  keyboard,  which  brings  us  to  .  .  . 

Flame  Eight:  Keyboards.  There  was 
a  huge  stink  about  keyboards  when 
the  PC  was  introduced,  and  it  has  never 
really  died  down.  With  the  millions  of 
replacement  keyboards  available,  how¬ 
ever,  I  have  found  only  one  that  is 
acceptable,  the  Jameco  that  sold  for 
$30  a  couple  of  years  ago,  a  surplus 
Televideo  PC  keyboard.  IBM  has  to¬ 
tally  mined  the  world  of  keyboards. 
Almost  all  the  keyboards  made  prior 
to  the  PC  were  similar.  Look  at  a  TRS- 
80,  any  older  terminal,  and  especially 
an  IBM  Selectric  typewriter.  I’m  not 
talking  about  layout;  I  have  typed  on 
everything  from  old  manual  typewrit¬ 
ers  to  teletype  machines,  and  can  adapt 
to  any  layout.  I’m  talking  about  the  size 
and  shape  of  the  key  caps,  and  the 
slope.  I  am  a  very  fast  touch  typewise, 
and  I  just  flat  cannot  type  on  those  flat 
IBM-style  keyboards.  I  expect  a  dis¬ 
crete  step  between  the  rows  of  keys 
and  these  keyboards  do  not  have  it. 
The  key  caps  are  a  different  size,  and 
many  of  the  keys,  such  as  Control, 
Shift,  and  Return  are  “stepped”  for  what¬ 
ever  insane  reason.  My  kingdom  for  a 
decent  keyboard!  The  above  mentioned 
Televideo  keyboard  is  pretty  good;  it 
is  made  in  the  old  style,  and  I  can  type 
on  it.  It’s  in  the  original  PC  layout, 
which,  yes,  is  dumb,  but  I  can  adapt 
to  it  if  the  keyboard  is  good.  And  the 
IBM  keyboard  clicks  .  .  . 

End  of  Flames:  Overall,  the  IBM  world 
has  brought  little  to  us  in  a  new  tech¬ 
nology.  So  I’ll  just  sit  here  in  front  of 
my  IMSAI  until  a  Mac  II  becomes  af¬ 
fordable,  or  even  the  NeXT.  Absolutely 
a  real  first  step  up  from  CP/M. 

Mark  D.  Pickerill 

Salinas,  Calif. 

DDJ 


Errata 

Somewhere  twixt  the  programmer  and  the  printed  page,  our  production 
equipment  developed  the  habit  of  eating  tildes  (~)  when  they  appeared  in 
program  listings  over  the  last  couple  of  months.  We’ve  solved  the  problem 
and  you  can  be  assured  that  it  won’t  recur.  (Neither  the  source  disk  nor  the 
listings  on  CompuServe  were  involved.) 

Two  articles  affected  were  May’s  “TAWK:  A  Simple  AWK  Interpreter  in 
C++”  by  Bruce  Eckel  and  April’s  “C  Programming  Column”  by  Al  Stevens. 
Please  note  the  corrections  below.  We  apologize  to  readers  and  authors  alike. 

TAWK:  A  SIMPLE  AWK  INTERPRETER  IN  C++ 

Listing  1,  line  17:  "field (  )  ; 

Listing  2,  line  16:  field:  :~field (  )  ( 

Listing  3,  line  17:  "csascii  (  ) ;  //  destructor 
Listing  4,  line  38:  csascii:  :~csascii  (  )  ( 

Listing  6,  line  32:  "token  (  )  ; 

line  50:  ~parse_array  (  )  ; 

Listing  7,  line  25:  token: : "token  (  )  {// delete  heap  if  allocated: 

line  119:  case  :  //  the  "else”  part  of  an  "if"  statement 
line  135:  (',  '<',  '?',':','~','.','p','m','c'or'@'"); 

line  207:  parse_array:  :~parse_array(  )  { 

Listing  10,  line  6:  (0)  (1)  (2)  ",  (3)  (4)  @?4@  :  @  (5)  " 

Listing  11,  line  10:  . @~@?4@  :@  (4) 

line  11: 

C  PROGRAMMING  COLUMN 

Listing  4,  line  75:  writecomm("bno) ;  /*  Is  complement  */ 

line  190:  if  ( (nbn  &  255)  !=  ("blk  &  255) )  { 


12 

372 


Dr.  Dobb’s Journal,  June  1989 


;  above .  rely  on-  named,. 
U3J  aiB'' controlled  and 
;  The?  Baffles  are  said  t< > 


Regardless  of  whatev  er  other  nits  you  might  pick  w  ith 
OS/2,  you  could  never  complain  that  its  array  of 
interprocess  communications  tli’O  facilities  is  too 
austere  fn  fact,  OS  2‘s  IPO  support  could  aptly  be 
termed  an  “embarrassment  of  riches'  (the  title  of  a 
recent  book,  by  the  way,  which  has  nothing  whatsoever  to 
do  with  protected  mode  programming)  Browsing  through 
the  reference  manual,  one  gets  the  distinct  impression  that 
the  IBM  Microsoft  11*0  Design  Subcommittee  •  -oukln'i  agree 
on  anything,  so  they  threw  iri  everything'  OS  2  offers  all  of 
the  following  classic  I  PC.  mechanisms:  semaphores,  pipes, 
shared  memory,  queues,  and  signals.  When  the  LAN  Man¬ 
ager  is  running,  OS '2  also  .supports  an  I  PC  mechanism 
called  madsluts  (w  hich  will  riot  lx1  mentioned  further  in  this 
artideX 

.kegfetfctbh'',  while  the  IBM  arid  Microsoft  manuals  are 
.passable  complete  on  the  “how  to"  for  each  individual  IPX 
'(IKS) tod,  they  are  lemarkablv  stingy  xvjth  the  “which  to,” 
"why  to,"  and  ‘‘when. fix”' lathis  article,  I'll  try  to  provide 
•;  yod-  WMi  a  soertew hat  more  cosmic  overview  of  US,  l  IPC. 

arts  of  capability,  per- 


The  resemblance  between  IPC  objects  and  hies  does  hot 
end  with  their  naming.  To  gain  access  to  most  types  of  IPC 
objects,  a  program  must  first  "open"  or  “create"  the  object 
in  a  manner  analogous  to  opening  or  creating  a  file.  OS/2 
then  returns  a  token  (a  selector  or  an  arbitrary  "handfe"),  % 
which  the  process  uses  to  manipulate  the  IPC  object,  read¬ 
ing,  writing  querying  the  number  of  waiting  messages,  and 
so  on. 

In  order  to  understand  OS  2  IPC,  it's  also  crucial  that  you 
grasp  r wo  essential  OS  2  terms:  processes  and  threads.  In  its 
simplest  form,  a  process  is  conceptually  equivalent  to  a 
program  loaded  for  execution  under  Ms  DOS  OS/2  creates 
a  process  by  allocating  memory  to  hold  its  code,  data.'  and 
stack,  and  by  initializing  the  memory  from  the  contents  of  a 
program  (  f’XT >  file.  One  6  it  is  running,  a;  pr« k-<?5$  gaa  obtain  ; 
additional  resources  —such  as  memory  and  access  to  files  — 
with  appropriate  system  function  rails,  .". 

The  OS/2  module  which  oversees  multitasking,  however  — * 
..the  schedulci  — cates  nothing  for  processes-  it  with 
entities  called  threads.  A  thread  consists  of  a  set  ofwgisfer 
contents  a  stack  an  execution  ftoini.  a  Pfiontv  and  a  spin  . 
executing,  ready  in  execute,  or  waking  tot:  some  event  e. 
( "blocking" >.  Rjst  h  p:r<  .cess  starts  life  with  -a  primary  thread, 
w  hose  execution  begins  at  the  entry  point  designated  m  the 

,EXE  file  Ijeadrat,:. but,  that  if  "  "  . ''4 

f.itlun,  tiw  same  process: "  all 
nously  and  sham  ownership 
’  'erg's  vyhy  tlK/disdrtctk' 
portant  when’-'  M'isSa 
reute.s  a  semaphore:.  'pipe, 

Of»^2.'-ret4tbMRa.  ,{gl 
within  dial  process 
iSSt) 
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(continued  from  page  15) 

Semaphores 

Semaphores  are  simple  IPC  objects  with  two  states.  These 
two  states  can,  in  turn,  be  viewed  in  two  different  ways, 
depending  on  how  a  semaphore  is  being  used.  When  a 
semaphore  is  being  used  for  signalling  between  threads  or 
processes,  it  is  said  to  be  either  “set”  or  “clear.”  Typically, 
one  thread  sets  the  semaphore,  and  then  clears  it  upon  the 
occurrence  of  some  event;  other  threads,  which  wish  to  be 
notified  of  the  same  event,  “block  on”  the  semaphore  by 
issuing  a  “semaphore  wait”  function  call  that  does  not 
complete  until  either  the  semaphore  is  cleared  or  a  desig¬ 
nated  timeout  interval  has  elapsed. 

When  a  semaphore  is  being  used 
for  mutual  exclusion,  it  is  said  to  be 
either  “owned”  or  “available.”  In  this 
model,  the  semaphore  symbolizes  a 
resource  (such  as  a  file  or  a  data  struc¬ 
ture)  that  would  be  corrupted  if  it  was 
manipulated  by  more  than  one  thread 
or  process  at  a  time.  To  prevent  such 
damage,  threads  or  processes  coop¬ 
erate  by  refraining  from  accessing  the 
resource  unless  they  have  acquired 
ownership  of  the  corresponding  sema¬ 
phore  with  an  OS/2  function  call. 

Aside  from  the  two  ways  in  which 
they  may  be  used,  OS/2  semaphores 
come  in  three  flavors:  system  sema¬ 
phores,  RAM  semaphores,  and  Fast- 
Safe  RAM  semaphores.  System  sema¬ 
phores  are  named,  global  objects, 
which  reside  outside  every  process’s 
memory  space  and  are  completely 
under  the  control  of  the  operating 
system.  They  must  be  “opened”  or  “created”  with  a  system 
call  before  they  can  be  used.  System  semaphores  support 
“counting;”  that  is,  a  process  can  make  “nested”  requests 
for  ownership  of  the  semaphore,  and  the  semaphore  will 
not  become  available  again  until  a  corresponding  number 
of  “release”  calls  have  been  issued.  OS/2  also  provides 
cleanup  support  for  system  semaphores;  if  a  process  dies 
owning  a  semaphore  that  another  process  is  waiting  for, 
that  other  process  will  be  notified  with  a  unique  error  code. 

RAM  semaphores,  on  the  other  hand,  reside  in  memory 
controlled  by  a  process.  They  consist  of  any  arbitrary,  but 
properly  initialized  doubleword  of  memory  in  the  applica¬ 
tion’s  address  space,  and  the  “handle”  for  a  RAM  semaphore 
is  just  its  address  (selector  and  offset)  — no  “open”  or  “cre¬ 
ate”  operation  is  required.  The  number  of  RAM  semaphores 
that  a  process  may  use  is  limited  only  by  the  amount  of 
virtual  memory  it  can  allocate.  RAM  semaphores  are  used 
to  communicate  between  threads,  but  since  memory  seg¬ 
ments  can  be  shared,  they  can  also  be  used  to  communicate 
between  processes.  In  the  latter  case,  OS/2  does  not  provide 
any  assistance  if  a  process  dies  owning  a  RAM  semaphore 
and  another  process  is  waiting  for  the  same  semaphore. 

The  so-called  Fast-Safe  RAM  semaphores,  which  were  added 
to  OS/2  in  Version  1.1,  combine  characteristics  of  both 
system  semaphores  and  RAM  semaphores.  They  are  imple¬ 
mented  as  14-byte  structures  in  a  process’s  own  memory 
space;  so,  like  plain  vanilla  RAM  semaphores,  the  number 
of  Fast-Safe  RAM  semaphores  that  a  process  can  use  is  huge. 
Like  system  semaphores,  Fast-Safe  RAM  semaphores  sup¬ 
port  “counting”  and  are  also  endowed  with  a  certain  amount 
of  clean-up  assistance  by  the  operating  system.  Unfortunate¬ 
ly,  Fast-Safe  RAM  semaphores  must  be  manipulated  with 
special-purpose  function  calls  — the  general  purpose  set, 


request,  wait,  and  clear  functions  employed  for  both  system 
and  RAM  semaphores  cannot  be  used  — and  they  support 
only  the  “owned/available”  model  for  mutual  exclusion. 

Pipes 

Pipes,  which  were  first  popularized  under  Unix,  are  basically 
conduits  for  byte  streams.  In  OS/2,  processes  refer  to  pipes 
with  handles  that  are  allocated  out  of  the  same  sequence  as 
file  handles,  and  they  read  and  write  pipes  with  the  same 
function  calls  as  are  used  for  files.  The  transfer  of  informa¬ 
tion  through  a  pipe  is  much  faster  than  it  would  be  through 
an  intermediary  file,  however,  because  the  ring  buffer  that 
implements  a  pipe  is  always  kept  resi¬ 
dent  in  memory. 

OS/2,  Version  1.1,  supports  two  dif¬ 
ferent  species  of  pipes:  anonymous 
pipes  and  named  pipes.  When  a  pro¬ 
cess  creates  an  anonymous  pipe,  no 
global  name  is  involved;  the  system 
merely  returns  read  and  write  han¬ 
dles.  These  handles  can  be  inherited 
by  child  processes,  which  is  what  en¬ 
ables  anonymous  pipes  to  be  used 
for  IPC.  However,  because  a  child 
has  no  way  to  predict  what  handle 
should  be  used  for  what,  a  common 
practice  is  for  a  parent  process  to 
redirect  the  child’s  standard  input  and 
standard  output  handles  to  pipe  han¬ 
dles,  so  that  the  child  unknowingly 
communicates  with  the  parent  rather 
than  with  the  keyboard  and  display. 
The  corollary  handicap  of  anonymous 
pipes  is  that  processes  which  are  not 
direct  descendants  of  a  pipe’s  creator 
cannot  inherit  handles  for  the  pipe  and  thus  have  no  way 
to  access  it. 

Named  pipes,  on  the  other  hand,  are  global  objects,  and 
any  process  — related  or  unrelated  to  the  pipe’s  creator  — 
can  open  the  pipe  by  name  to  obtain  handles  for  reading 
and  writing.  Another  important  feature  of  named  pipes  is 
that  they  can  be  used  in  either  byte  stream  mode  or  message 
mode.  In  byte  stream  mode,  a  named  pipe  behaves  like  an 
anonymous  pipe  — the  exact  number  of  bytes  requested  is 
always  read  or  written.  In  message  mode,  a  named  pipe  acts 
more  like  a  first-in-first-out  (FIFO)  queue:  the  length  of  each 
message  written  into  the  pipe  is  encoded  in  the  pipe,  and  a 
read  operation  returns  at  most  one  message  at  a  time  regard¬ 
less  of  the  number  of  bytes  requested.  Last  but  not  least, 
named  pipes  can  be  used  to  communicate  between  pro¬ 
cesses  running  on  two  different  nodes  of  a  network,  simply 
by  prefixing  the  name  of  the  pipe  with  the  name  of  the  target 
machine. 

Shared  Memory 

Shared  memory  segments  are  potentially  the  most  efficient 
of  all  OS/2’s  IPC  mechanisms.  If  two  or  more  processes 
have  addressability  for  the  same  segment,  they  can  theoreti¬ 
cally  pass  data  back  and  forth  at  speeds  limited  only  by  the 
CPU’s  ability  to  copy  bytes  from  one  place  to  another,  with 
no  need  for  additional  calls  to  the  operating  system.  Of 
course,  the  threads  and  processes  using  a  shared  segment 
are  responsible  for  synchronizing  any  changes  to  the  seg¬ 
ment’s  content,  and  this  synchronization  is  often  most  con¬ 
venient  to  accomplish  with  semaphores  (requiring  system 
calls  after  all). 

OS/2  supports  two  distinct  methods  by  which  processes 
can  share  memory:  creation  of  named  segments  and  giving 


We  need  an 
understanding  of  the 
operating  system’s 
overall  behavior  that 
has  never  before  been 
necessary  in  the 
microcomputer  world 
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and  getting  of  selectors  for  anonymous  segments.  Each 
method  offers  different  advantages  for  security  and  speed 
of  access.  Named  segments  are  restricted  to  a  maximum  size 
of  64K  bytes;  once  a  named  segment  is  created,  any  process 
which  knows  the  name  of  the  segment  can  “open”  it  to 
obtain  a  selector  with  which  it  can  read  or  write  the  seg¬ 
ment.  The  segment  persists  until  all  the  processes,  which 
have  valid  selectors  for  the  segment  have  either  released  the 
selector  or  have  terminated. 

Anonymous  segments,  on  the  other  hand,  can  be  any  size 
at  all  (huge  segments,  consisting  of  logically  contiguous 
64-bytes  segments,  can  be  as  large  as  available  virtual  mem¬ 
ory),  but  sharing  is  more  difficult  to  arrange.  The  selectors 
for  such  shared  segments  must  be  explicitly  made  address¬ 
able  for  each  process  that  needs  them,  and  passed  between 
the  processes  by  some  other  means  of  IPC.  One  technique, 
called  segment  giving,  requires  the  process  that  created  a 
segment  to  request  an  additional  selector  for  use  by  a 
specific  other  process  then  send  the  selector  to  that  process. 

The  other  technique,  segment  getting,  requires  the  creating 
process  to  pass  its  own  selector  for  the  segment  to  the  other 
process  by  some  IPC  mechanism.  The  other  process  then  gains 
addressability  to  the  shared  segment  by  issuing  a  function 
call  that  makes  the  selector  valid.  Segment  getting  allows  far 
pointers  to  be  passed  around  freely,  but  it  is  correspond¬ 
ingly  less  secure  than  the  use  of  giveable  selectors. 

Queues 

Queues  are  the  most  powerful  IPC  mechanism  in  OS/2,  and 
inevitably  are  also  the  most  complex  to  use.  Queues  are 
named  global  objects,  and  any  process  which  knows  a 
queue’s  name  can  “open”  it  and  write  records  into  it,  al¬ 
though  only  the  process  which  created  the  queue  can  read 
messages  from  it  or  destroy  it. 

In  essence,  an  OS/2  queue  is  an  ordered  list  of  shared 
memory  segments;  the  operating  system  maintains  and 
searches  the  list  on  behalf  of  the  communicating  processes. 
Data  in  the  queue  is  not  copied  from  place  to  place, 
instead,  pointers  are  passed  from  the  queue  writer  to  the 
queue  reader  (the  operating  system  also  provides  the  queue 
reader  with  supplementary  information  such  as  the  process 
ID  of  the  queue  writer).  The  items  in  a  queue  can  be 
ordered  in  several  different  ways:  first-in-first-out  (FIFO), 
last-in-first-out  (LIFO),  or  by  a  priority  in  the  range  0  through 
15.  Moreover,  the  queue  reader  has  the  freedom  to  in¬ 
spect  and  remove  queue  messages  in  any  arbitrary  order,  if 
it  needs  to. 

Writing  a  message  into  a  queue  is  a  relatively  complicated 
process.  First,  the  queue  writer  must  allocate  a  “giveable” 
memory  segment  and  build  the  queue  message  in  it.  Next, 
the  writer  must  obtain  a  giveable  selector  for  the  segment 
that  is  valid  for  the  queue  reader.  Finally,  the  writer  must 
request  the  queue  write,  passing  the  giveaway  selector,  and 
release  its  own  original  selector  for  the  segment.  Thus,  a 
minimum  of  four  system  calls  are  typically  required  at  the 
queue  writer’s  end  for  each  queue  transaction.  At  the  queue 
reader’s  end,  luckily,  only  two  system  calls  are  usually 
required:  one  to  read  the  message  (obtain  a  pointer  to  the 
message  and  its  length),  and  one  to  release  the  selector  for  the 
segment  containing  the  message  after  it  has  been  processed. 

Signals 

Signals,  which  (like  pipes)  have  their  conceptual  origin  in 
Unix,  are  analogous  to  a  hardware  interrupt.  They  are  unique 
among  OS/2’s  IPC  mechanisms  in  that  the  time  of  a  signal’s 
arrival  is  not  completely  under  the  control  of  the  receiving 
process.  OS/2  supports  two  classes  of  signals.  The  first  class, 


which  consists  of  signals  generated  by  the  operating  system, 
includes  the  following: 


SIGINTR 

SIGBREAK 

SIGTERM 

SIGBROKENPIPE 


a  Ctrl-C  was  detected 
a  Ctrl-Break  was  detected 
the  process  is  being  terminated 
a  pipe  read  or  write  failed 


Signals  in  the  second  class  are  explicitly  sent  by  one 
process  to  another.  These  are  known  as  event  flags,  and 
three  types  are  available  (each  of  which  may  have  a  distinct 
handler):  Flags  A,  B,  and  C.  Event  flag  signals  may  be 
accompanied  by  an  arbitrary  word  (16  bits)  of  data. 

For  each  signal  type,  a  process  may  either  register  its  own 
handler,  instruct  the  system  to  ignore  the  signal,  or  allow  the 
system’s  default  handler  to  take  its  usual  action.  If  a  particu¬ 
lar  signal  occurs  and  the  process  has  previously  indicated  its 
desire  to  service  that  signal  type,  the  primary  thread  of  the 
process  is  transferred  forcibly  to  the  routine  designated  as 
the  signal  handler.  When  the  handler  completes  its  process¬ 
ing  control  is  restored  to  the  point  of  interruption. 

The  system’s  default  handling  of  the  different  signal  types 
varies.  SIGTERM  terminates  the  target  process.  SIGINTR  and 
SIGBREAK  are  fielded  by  the  ancestor  process  which  has 
registered  an  appropriate  handler;  if  this  ancestor  is  CMD.EXE 
or  the  Presentation  Manager  shell,  SIGBREAK  and  SIGINTR 
are  translated  to  SIGTERM.  SIGBROKENPIPE  and  the  Event 
Flag  signals,  on  the  other  hand,  are  by  default  discarded. 

Assessing  IPC  Throughput 

From  the  preceding  discussion  and  the  summary  in  Table  1,  it 
is  clear  that  the  characteristics  of  OS/2’s  various  IPC  facilities 
vary  drastically.  Yet,  at  least  several  of  them  can  be  made 
to  do  essentially  the  same  job.  How  does  one  assess  their 
relative  performance  and  suitability  for  a  specific  applica¬ 
tion?  The  OS/2  documentation  gives  little  guidance  here, 
except  to  note  in  passing  that  RAM  semaphores  are  faster 
than  system  semaphores,  semaphores  in  general  are  faster 
than  everything  else,  and  pipes  are  faster  than  queues. 

In  order  to  try  and  get  a  feel  for  these  issues,  I  carried  out 
some  simple  timings  on  the  most  commonly  used  IPC 
methods,  which  I  will  describe  shortly.  The  timings  were 
obtained  on  a  IBM  PS/2  Model  80  at  l6MHz  with  4  Mbytes 
of  RAM,  running  under  IBM’s  OS/2  Standard  Edition,  Ver¬ 
sion  1.1.  The  relevant  CONFIG.SYS  parameters  were: 


BUFFERS=30 

BREAK=OFF 

DISKCACHE=64 

IOPL=YES 

MAXWAIT=3 

MEMMAN=SWAP,MOVE 

PROTECTONLY=NO 

RMSIZE=640 

THREADS=128 


The  only  significant  processes  that  were  running  during  the 
timings  were  the  Presentation  Manager  shell  and  two  in¬ 
stances  of  LMI  UR/FORTH  in  PM  windows.  I  judged  the 
system  to  be  lightly  loaded,  a  conclusion  supported  by  my 
observation  that  no  swapping  occurred  during  the  timings 
(as  evidenced  by  the  fixed  disk  light)  and  by  the  fact  that  the 
DosMemAvail  function  returned  the  size  of  the  largest  block 
of  available  physical  memory  as  1,367,520  bytes. 

The  programs  used  to  obtain  the  timings  were  written  in 
LMI  UR/FORTH,  my  own  company’s  protected  mode  Forth 
interpreter/compiler  for  OS/2.  Forth  is  an  ideal  language  for 

(continued  on  page  24) 
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(continued  from  page  20) 

this  sort  of  system  probing  because  it  is  fast  enough  for 
real-time  work,  yet  it  affords  interactive,  direct  access  to  all 
operating  system  functions. 

Semaphore  Performance 

Let’s  look  first  at  the  semaphore  family.  To  appraise  the 
relative  speeds  of  system,  RAM,  and  Fast-Safe  RAM  sema¬ 
phores  for  both  the  “signalling”  and  “mutual  exclusion” 
models,  I  timed  100,000  request/ release  cycles  and  set/clear 
cycles  for  each  semaphore  type  (Table  2).  The  tare  time  for 
the  loop  was  determined  by  substituting  a  dummy  function 
for  each  system  call  that  simply  returned  a  success  status; 
this  time  was  then  subtracted  from  the  total  before  calculat¬ 
ing  the  cycles  per  second. 

As  you  can  see  from  the  Table,  the  difference  between  the 
performance  of  system  and  RAM  semaphores  is  not  nearly 
as  great  as  you  might  expect  from  reading  the  OS/2  techni¬ 
cal  manuals.  Your  selection  of  system,  RAM,  or  Fast-Safe 


IPC 

Mechanism 

Global  Name 

Form 

Resident/ 

Swappable 

Maximum 

Data  Held 

RAM  Semaphore 

not 

applicable 

Swappable 

set/clear  or 
owned/avallable 

Fast-Safe 

RAM  Semaphore 

not 

applicable 

Swappable 

owned/available 

System 

Semaphore 

\SEM\name 

Resident 

set/clear  or 
owned/available 

Anonymous 

Pipe 

not 

applicable 

Resident 

64  Kbyte 

Named  Pipe 

\P\PE\name 

Resident 

64  Kbyte 

Anonymous 
Shared  Memory 

not 

applicable 

Swappable 

limited  only  by 
virtual  memory 

Named  Shared 
Memory 

\SHAREMEM\name 

Swappable 

64  Kbyte  per 
named  segment 

Queue 

\QUEUES\name 

Swappable 

limited  only  by 
virtual  memory 

Signal 
(Event  Flag) 

not 

applicable 

not 

applicable 

16  bits  passed 
with  signal 

Table  1:  Summary  of  the  various  OS/2  interprocess 
communication  facilities 


Semaphore  type 

Request/Release 

Set/Clear 

Cycles  per  Second 

Cycles  per  Second 

RAM  Semaphore 

16,507 

17,156 

Fast-Safe 

RAM  Semaphore 

17,066 

not  applicable 

System  Semaphore 

7,464 

7,532 

Table  2:  Performance  comparisons  of  various  OS/2 
semaphore  types  Timings  are  based  on  100,000  complete 
cycles  (request  then  release,  or  set  then  clear)  on  the 
same  semaphore. 


IPC  Method 

Message  Round-Trips 

Per  Second 

Shared  Memory 

661 

Anonymous  Pipe 

346 

Queue 

76 

Table  3:  Comparison  of  IPC  throughput  using  named  shared 
memory,  anonymous  pipes,  and  queues.  The  timings  are 
based  on  100,000  round-trips  of  a  512-byte  message  be¬ 
tween  two  processes. 


RAM  semaphores  should  really  be  made  on  other  grounds. 
I  have  already  mentioned  some  of  the  important  differences 
(counting  and  cleanup),  but  there  are  additional  subtle 
differences  that  might  prove  important  in  a  real-life  project. 

First,  the  apparent  performance  advantage  of  RAM  sema¬ 
phores  in  a  lightly-loaded  system  cannot  be  generalized  to 
a  heavily-loaded  system.  System  semaphores  are  imple¬ 
mented  in  fixed,  non-swappable  memory  owned  by  the 
operating  system;  the  access  time  to  a  system  semaphore 
will  always  be  consistent.  In  contrast,  RAM  semaphores  are 
located  in  memory  owned  by  a  process  — which  is  by 
default  moveable  and  swappable.  If  the  segment  containing 
a  RAM  semaphore  has  been  swapped  out  to  disk,  a  refer¬ 
ence  to  the  semaphore  could  be  delayed  for  an  unpredict¬ 
able  length  of  time  (but  on  the  order  of  tens  or  even 
hundreds  of  milliseconds)  until  the  virtual  memory  manager 
can  roll  the  segment  back  into  physical  memory. 

Another  important  aspect  of  system  semaphores  is  that 
they  are  implemented  in  memory  below  the  640K-byte 
boundary,  so  that  they  can  be  addressed  in  either  real  mode 
or  protected  mode.  This  is  vital  if  you  wish  to  use  sema¬ 
phores  to  communicate  between  a  closely  coupled  process 
and  device  driver  and  the  driver  might  need  to  manipulate 
the  semaphore  during  service  of  an  hardware  interrupt, 
because  the  CPU  mode  at  the  time  of  an  interrupt  cannot 
be  predicted. 

Finally,  we  should  note  that  the  location  of  system  sema¬ 
phores  in  physical  memory  severely  constrains  the  number 
that  OS/2  can  make  available.  The  memory  below  the 
640K-byte  boundary  is  dear,  because  it  must  be  conserved 
for  the  execution  of  real-mode  programs  in  the  DOS  Com¬ 
patibility  Environment.  Consequently,  the  maximum  num¬ 
ber  of  system  semaphores  is  128  in  OS/2,  Version  1.0,  and 
256  in  OS/2,  Version  1.1,  and  many  of  these  are  used  up  by 
the  operating  system  itself.  If  you  need  large  numbers  of 
semaphores  in  your  application,  you  will  have  to  use  RAM 
or  Fast-Safe  RAM  semaphores  and  simply  work  around  their 
other  limitations. 

Message-Passing  Performance 

As  I  thought  about  assessing  the  relative  throughput  of 
message  passing  using  shared  memory,  pipes,  and  queues, 
I  realized  that  simplistic  timings  of  system  calls  would  not 
be  very  helpful.  The  amount  of  tangential  work  that  is 
associated  with  the  use  of  these  IPC  mechanisms  can  be 
fairly  extensive  (allocating  and  deallocating  memory  seg¬ 
ments,  setting  and  clearing  semaphores  to  control  access  to 
shared  segments,  copying  data  to  and  from  local  buffers, 
and  so  on). 

Eventually,  I  settled  upon  a  timing  model  which,  I  think, 
is  at  least  reasonably  parallel  to  the  IPC  performed  by  real 
applications.  I  obtained  each  set  of  timings  by  running  two 
processes,  a  parent  and  a  child.  The  parent’s  only  function 
was  to  launch  the  child,  then  serve  as  a  message  turn¬ 
around  point.  As  the  parent  received  each  message  from  its 
child  via  the  IPC  mechanism  under  test,  it  would  simply  do 
whatever  was  necessary  to  ship  the  message  back  to  the 
child  again  (a  more  detailed  sketch  of  the  timing  procedure 
for  each  IPC  method  can  be  found  in  Figures  1,  2,  and  3).  A 
consistent  message  size  of  512  bytes  was  used. 

The  results,  which  are  reported  in  Table  3,  are  based  on 
100,000  message  round-trips  — from  child  to  parent  and 
back  again.  The  tare  times  were  found  and  subtracted  using 
equivalent  loops  where  the  system  calls  had  been  replaced 
with  dummy  functions  that  returned  a  success  status  or 
other  reasonable  result. 

IPC  performance  via  shared  memory  segments,  even  with  the 
overhead  of  system,  calls  to  set  and  clear  RAM  semaphores 
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that  synchronize  access  to  the  segments,  is  seen  to  be  far 
faster  than  either  pipes  or  queues.  In  fact,  because  processes 
can  easily  simulate  the  behavior  of  a  pipe  by  explicitly 
controlling  a  ring  buffer  in  a  shared  segment,  the  use  of 
pipes  for  any  reason  other  than  “transparent”  communication 
with  an  oblivious  child  process  is  probably  ill-advised. 

Communication  by  queues  turns  out,  as  expected,  to  be 
the  slowest  method.  It  is  an  order  of  magnitude  slower  than 
IPC  using  shared  memory,  and  two  orders  of  magnitude 
slower  than  signalling  with  system  semaphores.  It  seems 
clear  that  IPC  with  queues  should  be  reserved  for  those 
occasions  where  message  prioritizing  and  selective  message 
scanning  and  extraction  are  really  needed.  The  complexity 
of  queue  manipulation,  the  number  of  system  calls  in¬ 
volved,  and  the  relatively  heavy  demand  for  system  re¬ 
sources,  such  as  sharable  selectors,  should  deter  you  from 
casual  use  of  queues. 

As  with  the  semaphores,  these  comparisons  on  a  lightly- 
loaded  system  could  turn  out  quite  differently  on  a  heavily- 
loaded  system,  where  applications  have  over-committed 
virtual  memory  and  the  virtual  memory  manager  and  swap¬ 
per  are  constantly  busy.  Pipe  performance  should  be  rela¬ 
tively  consistent,  because  the  system  buffers  used  by  pipes 
are  not  swappable.  On  the  other  hand,  named  shared  mem¬ 
ory  segments,  and  the  giveable  shared  segments  used  in 
queue  messages,  are  swappable,  so  IPC  performance  via 
shared  memory  or  a  queue  could  be  quite  erratic  depending 
on  swapper  activity,  thread  priorities,  and  so  on. 

Some  Final  Thoughts 

Although  OS/2  has  gotten  off  to  a  slow  start,  its  eventual 
importance  in  the  desktop  computer  world  can  no  longer  be 
doubted.  I  feel  strongly  that  the  appearance  of  the  high- 
performance  file  system  (HPFS)  and  80386-specific  versions 


Process  A  Procsss  B 


Figure  1:  Procedure  used  to  measure  IPC  throughput  using 
a  named  shared  memory  segment 


over  the  next  year  or  so  will  make  it  the  platform  of  choice 
for  software  developers.  Users  will  migrate  more  slowly  (we 
have  the  history  of  the  Macintosh  to  guide  us  here),  but  the 
benefits  of  OS/2’s  multitasking,  virtual  memory,  and  graphi¬ 
cal  user  interface  will  eventually  draw  them  in. 

With  such  a  complex  system,  though,  the  ad  hoc  design 
methods  we  all  used  in  the  CP/M  and  MS-DOS  days  will  no 
longer  cut  the  mustard.  We  need  detailed  and  reliable  met¬ 
rics  that  can  help  us  make  tradeoffs  between  code  size, 
code  complexity,  and  code  performance  at  every  level  of 
an  application  — in  short,  we  need  an  understanding  of  the 
operating  system’s  overall  behavior  that  has  never  before 
been  necessary  in  the  microcomputer  world.  The  timings 
presented  in  this  article  are  crude  and  their  scope  is  narrow, 
but  perhaps  (with  luck)  they  will  inspire  successor  articles 
by  wiser  and  more  experienced  DDJ  readers! 

DDJ 

Vote  for  your  favorite  feature/article. 

Circle  Reader  Service  No.  1 . 


Figure  2:  Procedure  used  to  measure  IPC  throughput  using 
anonymous  pipes 


Process  A  Process  B 


Figure  3-'  Procedure  to  measure  IPC  throughput  using  queues 
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Undocumented 

DOS 


Uncover  the  mysteries  behind  undocumented  DOS  calls  to 
break  the  32-Mbyte  drive  partition  barrier 


Rahner  James 


MS-DOS  is  a  fairly  well-docu¬ 
mented  operating  system.  A 
person  only  needs  to  browse 
through  the  computer  sec¬ 
tion  of  their  local  bookstore 
to  get  an  idea  about  how  much  has 
been  written  about  MS-DOS.  Powerful 
manuals  for  powerful  programmers  de¬ 
veloping  powerful  tools  for  powerful 
users. 

After  readers  have  shaken  off  the 
giddiness  from  all  of  that  power  going 
to  their  heads,  they  begin  to  notice 
evidence  of  a  mystery  — there  are  gaps 
in  the  numbering  sequence  for  system 
calls.  At  first  glance,  it’s  as  if  Rosemary 
Woods  went  to  work  for  Microsoft  af¬ 
ter  her  White  House  experience.  At 
second  glance,  an  interested  party  can 
see  that  DOS  does  indeed  respond  to 
the  numbers  that  fill  the  gaps,  but  the 
purpose  of  those  numbers  may  be  un¬ 
clear.  This  article  examines  one  of  those 
undocumented  system  calls,  DOS  func¬ 
tion  52h,  which  returns  a  pointer  to 
an  internal  buffer  that  contains  point¬ 
ers  to  various  DOS  structures.  Once 
I’ve  covered  the  system  call,  I’ll  show 
you  how  it  can  be  used  to  create  drive 
partitions  greater  than  32  Mbyte.  I  have 
also  included  a  subroutine  that  can  be 
added  to  any  DOS  block  device  driver 
to  allow  for  the  larger  drive  partitions. 


Rahner  James  is  an  independent 
consultant  living  near  Sacramento, 
Calif.  He  can  be  reached  by  calling 
91 6-  722-1 939  or  through  CompuServe 
71450,  757. 


Using  Undocumented  Features 

The  first  reaction  to  the  idea  of  using 
any  undocumented  commands  should 
probably  be  one  of  skepticism.  Why 
would  anyone  use  an  undocumented 
feature  in  their  program?  If  the  feature 
is  undocumented,  then  the  manufac¬ 
turer  has  no  reason  to  change  it  from 
version  to  version.  Any  program  that 
uses  such  a  call  would  have  to  be 
changed  every  time  a  new  version  of 
DOS  is  released!  In  theory,  this  is  true  — 
but  when  marketing  realities  meet  with 
theory,  the  bigger  word  wins. 

The  fact  is  that  most  undocumented 
calls  were  written  to  allow  upper  layers 
of  the  operating  system  to  access  the 
lower  layers,  while  still  maintaining  a 
standard  interface.  Because  it  is  easier 
and  more  economical  to  continue  us¬ 
ing  old  system  call  structures,  there  is 
a  high  probability  of  little  or  no  change 
to  the  major  undocumented  calls. 

The  undocumented  system  calls  usu¬ 
ally  deal  with  low-level  operating  sys¬ 


tem  data  structures.  Normally,  when  a 
programmer  wants  low-level  partition 
information  that  cannot  be  found 
through  the  standard  calls,  he  or  she 
writes  a  routine  to  read  the  partition 
boot  record  from  the  device,  and  then 
gleans  the  required  data  from  the  re¬ 
cord.  Unfortunately,  a  DOS  block  de¬ 
vice  is  not  required  to  have  a  partition 
boot  record,  and  any  assumption  about 
the  data  structures  on  the  first  logical 
sector  are  bound  to  be  wrong  in  sev¬ 
eral  cases.  Any  data  structure  that  is  left 
up  to  the  discretion  of  the  developer 
should  be  considered  more  trouble¬ 
some  than  a  data  structure  that  has 
been  defined  and  used  by  Microsoft  — 
if  the  developers  are  given  structural 
leeway  by  Microsoft,  it  should  be  as¬ 
sumed  that  they  will  take  it. 

MS-DOS  Function  52h 

DOS  function  52h  is  probably  the  most 
useful  of  the  undocumented  system 
calls  because  it  contains  a  great  deal 
of  information.  The  purpose  of  this 
function  call  is  to  get  the  internal  buffer 
pointers.  The  call  returns  a  pointer  to 
a  table  of  pointers  and  data.  This  table 
describes  most  of  the  DOS  internal  struc¬ 
tures  that  are  associated  with  the  stor¬ 
age  subsystem.  Figure  1  describes  the 
calling  sequence  used  in  calls  to  DOS 
function  52h. 

The  function  returns  a  far  pointer  to 
an  internal  DOS  buffer.  The  structure 
of  this  buffer  differs  depending  upon 
the  major  version  of  DOS.  Although  I 
have  not  tested  it,  function  52h  is  prob- 


26 

378 


Dr.  Dobb’s Journal,  June  1989 


ably  not  supported  in  Version  1  .xx. 

Table  1  shows  the  buffer  structure 
for  MS-DOS,  Version  2.xx. 

The  buffer  structure  for  Version  3  xx 
is  identical  to  2.xx  up  to  offset  10b.  The 
buffer  structure  for  3xx,  beginning  with 
byte  lOh ,  is  shown  in  Table  2. 

Disk  Parameter  Structure 

Each  disk  parameter  block  entry  con¬ 
tains  basic  information  about  the  logi¬ 
cal  disk  drives  attached  to  the  DOS 
system.  The  structure  of  the  disk  Pa¬ 
rameter  Block  entry  is  similar  to  the 
structure  of  the  BIOS  Parameter  Block 
(BPB)  described  in  the  DOS  Technical 
Reference  Manual.  The  use  of  the  BIOS 
Parameter  Block  structure  to  obtain  in¬ 
formation  about  the  physical  constraints 
of  the  disk  storage  subsystem  has  sev¬ 
eral  advantages. 

In  several  of  the  disk-related  appli¬ 
cations  that  I  have  worked  on  over  the 
years,  the  programmer  reads  the  Disk 
Parameter  Block  off  logical  partition 
sector  0  in  order  to  determine  the  physi¬ 
cal  characteristics  of  the  disk  partition. 
The  assumption  was  that  all  block  de¬ 
vices  followed  the  IBM  partition  struc¬ 
ture  definition.  Unfortunately,  that  defi¬ 
nition  is  not  a  standard,  and  turns  out 
to  be  version-  and  implementation- 
dependent.  In  contrast,  the  disk  pa¬ 
rameter  structure  has  not  changed  since 
MS-DOS,  Version  2.00  (although  no  test¬ 
ing  has  been  done  on  Version  4.00), 
and  contains  all  of  the  necessary  infor¬ 
mation  (short  of  the  physical  disk  drive 
characteristics). 


Purpose: 

Returns  a  pointer  to  internal  buffer  that 
contains  pointers  to  various  MS-DOS 
structures. 


On  entry 

Register  contents 

AH 

52H 

On  return 

Register  contents 

ES:BX 

Pointer  to  internal 
MS-DOS  structure 

Remarks: 

This  function  returns  a  far  pointer  to  an 
internal  MS-DOS  buffer.  The  structure 
of  this  buffer  differs  depending  on  the 
major  version  of  MS-DOS.  This 
function  is  probably  not  supported  by 
Version  1  .xx. 


Figure  1:  The  calling  sequence  used 
in  call  to  DOS  function  52h 


Another  advantage  of  using  the  disk 
parameter  structure  is  that  some  of  the 
other  DOS  calls  that  are  used  to  obtain 
logical  drive  information  access  the  drive 
for  readiness.  In  some  cases,  the  nor¬ 
mal  state  for  the  drive  is  to  be  not 
ready.  If  the  device  is  not  ready,  re¬ 
peated  retries  cause  a  delayed  call  re¬ 
turn,  and  extra  programming  is  neces¬ 
sary  in  order  to  handle  the  uninten¬ 
tional  error  that  is  returned. 

In  addition  to  providing  informational 
advantages,  the  disk  parameter  struc¬ 
ture  offers  an  additional  feature  that  is 
not  available  through  any  other  system 
call  — the  “media  flag.”  The  media  flag 
indicates  whether  the  device  has  been 
read.  If  the  programmer  sets  the  flag 
to  —  1,  DOS  forces  a  reread  of  basic 
device  information  from  the  device.  This 
approach  is  particularly  useful  if  the 


programmer  modifies  the  FAT  and 
wants  DOS  to  update  its  internal  struc¬ 
tures  with  the  updated  table. 

The  structure  for  the  disk  parameter 
block  is  shown  in  Table  3. 

Open  File  Table  List 

DOS  stores  all  of  its  information  about 
open  files  in  a  linked  list  of  tables.  Each 
node  in  the  linked  list  is  a  table  of  file 
entries  that  contain  information  about 
each  open  file.  The  first  table  always 
contains  the  five  predefined  I/O  han¬ 
dles.  The  linked  list  of  tables  is  not 
particularly  useful,  because  the  infor¬ 
mation  that  it  contains  can  be  gleaned 
from  other,  more  standard  system  calls. 
The  list  is  included  here  for  the  sake 
of  completeness  (though  even  that 
could  be  questioned  since  it  is  not  com¬ 
pletely  defined).  The  structure  for  the 


Offset 

Size 

Description 

-2 

word 

Segment  value  of  the  first  memory  block  available  through  the 
Allocate  Memory  call. 

0 

dword 

Far  pointer  to  the  first  MS-DOS  Disk  Parameter  Block.  This  structure 
is  defined  after  this  table  as  the  Disk  Parameter  Structure. 

4 

dword 

Far  pointer  to  a  linked  list  of  MS-DOS  open  file  tables.  This 
structure  is  defined  after  this  table  as  the  Open  File  Table  List. 

8 

dword 

Far  pointer  to  the  beginning  of  the  CLOCKS  device  driver. 

OCh 

dword 

Far  pointer  to  the  beginning  of  the  CON:  device  driver. 

lOh 

byte 

Contains  the  number  of  logical  drives  presently  supported  by  the 
system. 

1 1  h 

word 

This  contains  the  size  of  the  largest  logical  sector  size  supported 
by  the  system. 

13h 

dword 

Far  pointer  to  the  first  sector  buffer  structure  used  by  the  logical 
disks.  The  size  of  each  sector  buffer  is  equal  to  the  largest 
logical  sector  size  plus  a  sixteen  byte  header.  This  header  is 
defined  after  this  table  as  the  Sector  Buffer  Structure.  The  number 
of  these  buffers  is  defined  by  the  ’BUFFERS=xx'  entry  in  the 
CONFIG.SYS  file. 

17h 

This  is  the  start  of  the  first  device  driver  (NUL). 

Table  1: 

The  buffer  structure  for  MS-DOS,  Version  2 

Offset 

Size 

Description 

lOh 

word 

Contains  the  size  of  the  largest  logical  sector  size  supported  by 
the  system. 

12h 

dword 

Far  pointer  to  first  sector  buffer  structure  used  by  the  logical  disks. 
This  is  defined  after  this  table  as  the  Sector  Buffer  Structure. 

16h 

dword 

Far  pointer  to  the  drive  path  and  seek  information  table.  This 
structure  is  defined  after  this  table  as  the  Drive  Path  Table. 

1Ah 

dword 

Far  pointer  to  a  table  of  FCBs.  This  table  is  only  valid  if  the 
”FCBS=xx"  command  is  used  in  CONFIG.SYS. 

1Eh 

word 

Size  of  FCB  table. 

20h 

byte 

Contains  the  number  of  logical  drives  presently  supported  by  the 
system. 

21  h 

byte 

The  value  of  "LASTDRIVE=xx"  in  CONFIG.SYS.  The  default 
value  is  5. 

22h 

This  is  the  start  of  the  first  device  driver  (NUL). 

Table  2:  The  buffer  structure  for  MS-DOS,  Version  3,  beginning  with  byte  1  Oh 
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Open  File  Table  List  is  shown  in  Table 
4,  and  the  structure  for  an  Open  File 
Table  entry  is  shown  in  Table  5. 

Sector  Buffer  Structure 

The  number  of  sector  buffers  that  DOS 
uses  is  predefined  at  boot  time.  Each 
sector  buffer  consists  of  a  16-byte  header 
followed  by  an  area  equal  to  the  size 
of  the  largest  logical  sector.  The  header 
contains  information  about  the  origin 
of  the  data  in  the  buffer,  and  a  link  to 
the  next  sector  buffer  in  line.  The  fact 


that  this  linked  buffer  list  is  not  hard¬ 
coded,  and  that  this  system  call’s  pointer 
is  the  primary  reference  to  this  area, 
creates  some  interesting  possibilities  (as 
you’ll  soon  see).  The  structure  for  the 
header  of  the  sector  buffer  is  shown  in 
Table  6. 

Drive  Path  Table 

The  Drive  Path  Table  contains  the  de¬ 
fault  path,  drive  head  location,  and  vari¬ 
ous  flags  and  pointers.  As  with  the 
Open  File  Table  List,  all  of  the  informa¬ 


tion  in  the  Drive  Path  Table  is  also 
available  through  other  documented 
system  calls.  The  number  of  table  en¬ 
tries  is  equal  to  the  number  of  valid 
logical  drives  plus  one.  The  last  entry 
contains  a  zero  in  the  flags  variable  and 
does  not  have  any  useful  data.  The 
structure  for  a  Drive  Path  Table  entry 
is  shown  in  Table  7. 

As  you  can  see,  DOS  function  52h 
holds  a  considerable  amount  of  infor¬ 
mation.  Virtually  everything  that  the 
programmer  needs  to  know  about  the 
disk  is  accessible  through  this  call. 

Creating  Expanded  Partition  Sizes 

Since  the  advent  of  the  inexpensive 
hard  disk,  the  DOS  32-Mbyte  disk  par¬ 
tition  limitation  has  been  a  real  prob¬ 
lem.  Until  the  joint  Microsoft/Compaq 
“BIGFOOT”  development  on  Version 
3.31  and  the  later  4.00  release,  Micro¬ 
soft  had  not  offered  any  remedies  to 
this  deficiency.  To  fill  the  marketing 
requirement,  several  companies  have 
released  hard  disk  partitioning  software 
packages  that  allow  DOS  to  access  par¬ 
titions  up  to  1  gigabyte. 

In  theory,  MS-DOS,  Versions  2.xx 
and  3. xx,  can  access  disk  partitions  up 
to  4  gigabytes  simply  by  increasing  the 
sector  size  from  512  bytes  to  some  larger 
power  of  two.  In  reality,  a  block  device 
driver  written  to  test  this  theory,  simply 
dies.  The  artificial  limitation  stems  from 
the  buffer  initialization  at  boot  time, 
when  somewhere  in  the  recesses  of 
DOS,  an  assumption  is  made  that  the 
basic  sector  size  is  going  to  be  512 
bytes.  Because  all  of  the  buffers  are 
statically  allocated  according  to  that  as¬ 
sumption,  no  sector  size  larger  then 
512  bytes  are  allowed.  Obviously,  since 
there  are  programs  that  allow  larger 
partitions,  there  must  be  a  way  to  cir¬ 
cumvent  the  assumption.  In  fact,  there 
are  a  couple  of  ways. 

One  of  the  easier  routines  that  you 
can  build  allows  a  DOS  block  device 
driver  to  access  up  to  2  gigabytes  per 
partition  and  uses  two  of  the  items 
provided  by  function  52h.  The  first  item 
is  the  maximum  sector  size  variable  — 
the  routine  simply  needs  to  change 
that  variable  to  the  maximum  sector 
size  supported  by  the  driver.  The  sec¬ 
ond  item  provided  by  function  52h  is 
the  linked  list  of  sector  buffers.  If  a 
sector  is  read  into  a  buffer  that  is  too 
small  to  hold  that  sector,  catastrophic 
results  and  bit  death  usually  occur.  To 
avoid  the  overwriting  of  useful  data, 
the  sector  buffer  linked  list  must  be 
redone. 

Expanding  the  Partition  Horizon 

I  have  written  a  small  routine  in  8086 
assembly  language  that  can  be  included 


Offset 

Size 

Description 

0 

byte 

Disk  unit  number,  basically  this  is  the  drive  number  zero  based 
(0=A,  1  =B,  etc.).  If  this  and  the  next  byte  are  OFFh  then  this  entry 
is  the  end  of  the  linked  list  and  invalid. 

1 

byte 

Disk  unit  number  passed  to  the  block  device  driver  responsible 
for  this  logical  drive. 

2 

word 

The  logical  sector  size  of  this  drive  in  bytes. 

4 

byte 

Number  of  sectors  per  cluster  - 1 .  The  number  of  sectors  per 
cluster  must  be  a  power  of  two. 

5 

byte 

Allocation  shift.  It  is  the  shift  value  used  to  calculate  number  of 
sectors  from  number  of  clusters  without  having  to  use  division. 
Number  of  sectors  =  number  of  clusters  «  allocation  shift. 

6 

word 

Reserved  sectors.  This  is  the  number  of  reserved  sectors  at  the 
beginning  of  the  logical  drive.  The  reserved  sectors  may  include 
partition  information. 

8 

byte 

Number  of  FATs.  This  is  usually  two. 

9 

word 

Number  of  root  directory  entries.  The  root  is  the  only  directory 
that  has  a  structural  limitation  on  the  number  of  entries.  This  is 
usually  32  factored  into  some  multiple  of  the  logical  sector  size. 

OBh 

word 

First  data  sector.  This  is  the  first  sector  that  contains  file  data.  This 
is  also  defined  as  cluster  two  since  cluster  zero  and  one  have 
special  definitions.  Conceivably,  there  could  be  a  hidden  area 
between  the  end  of  the  root  directory  and  the  first  data  sector. 

ODh 

word 

Last  cluster  number.  This  is  the  number  of  clusters  in  the  data 
area  +  1 .  If  this  is  less  than  0FF6h  then  the  FAT  uses  12-bit 
entries;  otherwise,  it  uses  16-bit  entries. 

OFh 

byte 

FAT  size.  This  the  size  of  one  FAT  in  logical  sectors. 

lOh 

word 

First  root  sector.  This  is  the  sector  number  of  the  first  root  directory 
entry. 

12h 

dword 

Far  pointer  to  the  block  device  driver. 

16h 

byte 

Media  descriptor.  This  is  the  media  descriptor  byte  as  described 
in  the  MS-DOS  Technical  Reference  Manual. 

17h 

byte 

Media  flag.  If  this  is  0,  the  drive  has  been  accessed.  If  it  is  -1  (or 
is  set  to  -  1),  MS-DOS  will  build  all  its  internal  data  structures 
concerning  the  drive  when  it  is  next  accessed. 

18h 

dword 

Far  pointer  to  the  next  disk  parameter  block. 

Table  3-  The  structure  for  the  disk  parameter  block 


Offset 

Size 

Description 

0 

dword 

Far  pointer  to  the  next  table  in  the  list.  If  the  offset  of  this  pointer 
is  OFFFFh,  then  the  table  is  the  final  entry  and  invalid. 

4 

word 

Number  of  table  entries.  Each  table  entry  is  53  bytes  long.  There 
will  be  at  least  one  entry  in  each  table  except  the  terminal  entry. 

6 

The  open  file  table  entries  begin  here. 

Table  4:  The  structure  for  the  Open  File  Table  List 
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Offset 

Size 

Description 

0 

word 

The  number  of  file  handles  that  refer  to  this  table  entry. 

2 

byte 

[5] 

Not  defined. 

6 

dword 

Far  pointer  to  the  device  driver  header  if  this  is  a  character  device. 

If  it  is  a  block  device,  this  will  be  a  far  pointer  to  the  Disk  Parameter 
Block. 

OAh 

byte 

[21] 

Not  defined. 

20h 

byte 

[11] 

This  is  the  filename  as  it  would  appear  on  the  diskspace  filled  and 
with  no  period  to  separate  the  name  from  the  extension. 

2Bh 

word 

This  is  the  PSP  segment  number  of  the  file's  owner. 

2Dh 

dword 

Not  defined. 

31  h 

word 

Not  defined. 

33h 

word 

Not  defined. 

Table  5 :  The  structure  for  an  Open  File  Table  entry 


Offset 

Size 

Description 

0 

dword 

Far  pointer  to  the  next  sector  buffer.  The  buffers  are  filled  in  order 
of  their  appearance  in  this  linked  list.  The  last  buffer  has  a 
OFFFFFFFFh  in  this  location  and  is  a  valid  buffer. 

4 

byte 

Drive  number.  This  is  the  drive  number  that  the  data  currently  in 
this  buffer  was  read/written  from/to.  If  this  buffer  has  not  been 
used,  this  byte  will  be  set  to  OFFh. 

5 

byte 

Data  type  flags.  The  bit  fields  show  what  area  of  the  drive  that  the 
data  is  associated.  The  bits  are  defined  as  follows: 

Bit 

Description 

1 

File  Allocation  Table  data 

2 

Directory  or  subdirectory  data 

3 

File  data 

6 

word 

Logical  sector  number.  This  is  the  logical  sector  number  that  this 
structure  has  buffered. 

8 

word 

Access  number. 

OAh 

dword 

Far  pointer  to  the  disk  parameter  block. 

OEh 

word 

Unused. 

Table  6 :  The  structure  for  the  header  of  the  sector  buffer 


Offset 

Size 

Description 

0 

byte 

Contains  the  current  default  pathname  in  ASCIIZ  format.  It  con- 

[64] 

tains  the  drive  letter,  colon  delimiter  and  the  initial  'V.  For  example, 
the  string  for  the  second  table  entry  with  default  path  of  'my _path' 
would  be  B:\  MY_PATH. 

40h 

dword 

Reserved,  set  to  0. 

44h 

byte 

Flags  variable.  All  valid  entries  contain  a  40h;  the  last  entry 
contains  0. 

45h; 

dword 

Far  pointer  to  the  Drive  Parameter  Block. 

49h 

word 

Current  block  or  track/sector  number  for  this  drive. 

4Bh 

dword 

Far  pointer.  Unknown  purpose. 

4Fh 

word 

Unknown  storage. 

Table  7:  The  structure  for  a  Drive  Path  Table  entry 


(continued  from  page  28) 
in  any  MS-DOS  block  device  driver  that 
supports  logical  sector  sizes  above  512 
bytes  (see  Listing  One,  page  84).  These 
days  DOS  block  device  drivers  are  com¬ 
monplace,  so  a  thorough  explanation 
of  how  this  type  of  device  driver  works 
is  unnecessary.  But,  a  few  relevant  points 
should  be  reiterated  before  jumping 
right  into  the  routine. 

Normal  block  device  drivers  have  a 
basic  data  block  size  that  is  some  power 
of  two.  The  basic  block  size,  usually 

The  fact  that  this  linked 
buffer  list  is  not  hard 
coded  and  that  this 
system  call’s  pointer  is 
the  primary  reference 
to  this  area,  creates 
some  interesting 
possibilities  as  you  ’ll 
soon  see 


one  512-byte  sector,  is  defined  in  the 
BIOS  Parameter  Block  provided  by  the 
driver  as  part  of  the  initialization  proc¬ 
ess.  Because  the  BPB  storage  variable 
for  the  number  of  blocks  in  the  parti¬ 
tion  is  16  bits,  a  partition  cannot  be 
larger  than  65,535  logical  blocks.  This 
limitation  means  that  in  order  to  in¬ 
crease  the  storage  capacity  beyond  32 
Mbytes,  the  block  size  must  be  increased 
beyond  512  bytes. 

Most  controllers  do  not  support  sec¬ 
tor  sizes  other  than  512  bytes.  Rather 
than  expecting  the  hardware  to  be  the 
answer  to  larger  logical  sectors,  the 
easiest  way  and  the  most  generally  ap¬ 
plicable  is  to  just  read  more  512-byte 
sectors.  For  example,  to  get  a  block 
size  of  1024  (partition  size  of  64 
Mbytes),  read  two  sequential  512-byte 
sectors.  To  get  a  block  size  of  32,768 
(partition  size  of  two  gigabytes),  read 
64  sequential  512-byte  sectors.  A  well 
designed  block  device  driver  should 
easily  accommodate  this  method. 

After  the  block  device  driver  initial¬ 
izes  all  the  devices  and  their  partition 
structures,  the  BPB  table  should  be  com- 
(continued  on  page  34) 
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(continued  from  page  30) 
plete.  The  largest  block  size  can  be 
found  by  scanning  the  valid  BPB  array 
entries.  This  maximum  block  size  is 
required  by  the  MODIFY_DOS  routine 
in  a  word-size  variable  called  BIG- 
GEST_SECTOR. 

After  getting  the  vector  from  DOS 
function  52b,  a  comparison  is  made 
between  the  driver’s  largest  block  size 
and  the  largest  block  size  supported 
by  DOS  at  the  moment.  If  DOS  already 
supports  a  block  size  equal  to  or  larger 
than  the  driver’s  block  size,  no  changes 
are  needed. 

If  the  driver’s  block  size  is  larger,  the 
routine  changes  two  parameters.  First, 
it  alters  DOS’s  largest  block  size  vari¬ 
able  with  the  driver’s  larger  value.  Sec¬ 
ond,  the  routine  works  its  way  down 
DOS’s  block  buffer  list  and  “revectors” 
them  to  a  new  storage  location.  Care 
should  be  taken  that  a  buffer  is  not 
allocated  twice. 

Tricks  of  the  Trade 

I  should  mention  that  the  routine  uses 
some  of  the  features  in  Microsoft’s 
MASM,  Version  5.10.  I  make  use  of  the 
USES  directive  in  the  procedure  decla¬ 
ration.  This  directive  PUSHes  any  regis¬ 
ters  listed  after  the  word  USES  and 
POPs  them  at  the  end  of  the  routine. 
USES  is  a  handy  directive  for  the  men¬ 
tal  defective  (a  group  which  includes 
myself)  who  are  forever  PUSHing  and 
POPing  in  the  wrong  order  or  the  wrong 
registers. 

I  also  make  use  of  the  local  label 
(@@)  for  short  jumps.  The  syntax  for  a 
forward  jump  to  a  @@  label  is  @F.  The 
syntax  for  a  backward  jump  is  @B.  I 
generally  use  these  labels  for  tight  loops 
and  comparison  skips  to  differentiate 
them  from  labels  referenced  farther 
away  in  the  program.  This  type  of  label 
should  either  not  be  used  in  macros, 
or  only  used  in  macros  because  subtle 
bugs  could  result.  As  an  example,  say 
a  macro  called  DELAY  has  been  coded 
as  shown  below: 


DELAY  macro 

jmp  short  @F 


endm 


This  macro  was  used  in  the  following 
code  segment: 


(0) 

cmp 

bl,  8 

(1) 

jb 

@F 

(2) 

out 

Oath,  al 

(3) 

delay 

(4) 

sub 

bl,  8 

(5)  @@: 

mov 

INT_  NUMBER,  bl 

In  this  case,  the  comparison  skip  goes 
to  line  4  rather  than  line  5  as  you  might 
expect. 

Final  Note 

Several  other  undocumented  MS-DOS 
system  calls  exist.  Many  of  them  pro¬ 
vide  pointers  to  the  data  structures 
shown  in  this  article.  All  of  them  need 
only  a  debugger  and  a  little  patience 
to  discover.  In  finding  an  application 
for  the  information  uncovered,  the 
reader  is  only  constrained  by  imagina¬ 
tion  and  the  bouncer  at  the  door. 

Availability 

All  source  code  for  articles  in  this  issue 
is  available  on  a  single  disk.  To  order, 
send  $14.95  (Calif,  residents  add  sales 
tax)  to  Dr.  Dobb’s Journal ,  501  Galves¬ 
ton  Dr.,  Redwood  City,  CA  94063;  or 
call  800-356-2002  (from  inside  Calif.) 
or  800-533-4372  (from  outside  Calif.). 
Please  specify  the  issue  number  and 
format  (MS-DOS,  Macintosh,  Kaypro). 

DDJ 

(Listing  begins  on  page  84.) 
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REAL-TIME 


Data  Acquisition 


Collecting  and  storing  large  amounts  of  data,  such  as  music, 
has  special  requirements 


Mike  Bunnell  and  Mitch  Bunnell 


The  acquisition  and  storage  of 
large  amounts  of  data  is  vital 
in  many  industrial,  research,  and 
aerospace/defense  applications 
in  which  computer  systems  typi¬ 
cally  must  collect  analog  data  at  very 
high  rates  (1,000  to  1,000,000  samples/ 
sec.)  for  relatively  long  periods  (a  few 
seconds  to  a  few  days).  Consequently, 
computers  used  in  these  environments 
must  be  able  to  assemble  huge  vol¬ 
umes  of  data  in  real  time  and  store 
them  in  an  organized  way  so  that  the 
information  can  be  analyzed  later.  Un¬ 
til  recently,  systems  that  could  do  this 
cost  more  than  $100,000.  With  current 
hardware  and  software  technologies, 
however,  equivalent  PC-based  systems 
are  one-tenth  that  price. 

A  computer  system  — large  or  small  — 
designed  for  real-time  data  acquisition 
must  meet  four  basic  requirements:  It 
needs  to  have  an  interface  that  con¬ 
verts  continuous  real-world  data  into 
discrete,  digitized  samples  at  a  rapid 
sampling  rate;  there  must  be  sufficient 
throughput  to  mass  storage  to  save  the 
samples  at  the  sampling  rate;  a  data 
acquisition  program  must  read  the  sam¬ 
ples  from  the  interface  and  write  them 
to  mass  storage;  and  the  software  must 
have  sufficient  real-time  response  so 
data  samples  are  never  lost.  In  this 
article,  we’ll  describe  the  elements  of 
a  common  PC-based  data  acquisition 
system  and  show  how  it  can  be  used 
in  a  typical  application. 


Mike  and  Mitch  are  engineers  at  Lynx 
Real-Time  Systems  Inc.  and  can  be 
reached  at  550  Division  St.,  Campbell, 
CA  95008. 


Principles  of  Real-Time 
Data  Acquisition 

Although  most  real-world  data  is  ana¬ 
log  in  nature,  digital  computers,  by  defi¬ 
nition,  can  only  process  discrete  digital 
data.  To  solve  this  dilemma,  an  analog- 
to-digital  (A/D)  interface  is  needed.  Be¬ 
cause  analog  data  is  continuous,  the 
A/D  interface  must  take  a  snapshot  of 
the  analog  data  at  one  point  in  time. 
This  process,  called  sampling,  is  usu¬ 
ally  done  at  a  particular  sampling  rate 
depending  on  how  fast  the  analog  data 
is  expected  to  change.  The  interface 
must  digitize  each  sample  by  convert¬ 
ing  it  to  a  numerical  value.  The  resolu¬ 
tion,  or  number  of  bits,  used  to  repre¬ 
sent  this  value  is  dependent  on  the 
analog  interface.  Unless  the  sampling 
rate  is  slow  (less  than  100  samples/ 
sec.)  the  interface  must  provide  some 
way  of  buffering  the  digitized  data  un¬ 
til  the  CPU  accesses  it.  This  can 
be  done  either  by  providing  a  first-in, 
first-out  (FIFO)  buffer  as  part  of  the 


analog  interface  or  direct-memory-ac¬ 
cess  (DMA)  capability  so  the  interface 
can  save  the  data  directly  to  computer 
memory  without  using  the  CPU. 

Handling  the  analog  interface  is  left 
to  a  device-dependent  code  — the  de¬ 
vice  driver.  The  device  driver  sets  the 
operating  parameters  of  the  interface, 
maintains  the  data  buffers,  and  serv¬ 
ices  requests  to  read  converted  data  or 
set  the  sampling  rate.  In  the  same  way 
as  the  analog-to-digital  converter  is  the 
interface  beteen  the  computer  and  the 
real  world,  the  device  driver  is  the  in¬ 
terface  between  a  data  acquisition  pro¬ 
gram  and  the  converter  hardware. 

In  a  data  acquisition  system,  sam¬ 
pled  data  is  saved  to  mass  storage  (typi¬ 
cally  a  hard  disk)  for  later  processing. 
The  reason  for  saving  the  data  to  disk 
and  not  just  computer  memory  is  that 
there  is  usually  more  data  that  must  be 
saved  than  there  is  memory  available. 
For  convenience  sake,  it  is  preferable 
that  data  be  saved  in  named  files  on  the 
disk  so  the  data  can  be  conveniently 
accessed  simply  by  reading  it  from  the 
appropriate  files. 

Writing  data  to  a  file  must  be  fast 
enough  to  keep  up  with  the  sampling 
rate.  If,  for  example,  the  sampling  rate 
is  100,000  samples/sec.  and  each  sam¬ 
ple  is  2  bytes,  then  the  computer  must 
be  capable  of  writing  200,000  bytes/ 
sec.  to  a  file  on  a  sustained  basis.  Al¬ 
though  disk-drive  manufacturers  may 
quote  burst  transfer  rate  and  seek  rates, 
these  do  not  reveal  the  sustained  data 
rate.  The  best  way  to  determine  this 
rate  is  to  do  real-life  testing. 

This  testing  process  must  include  writ¬ 
ing  data  to  a  file,  a  process  that  is 
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typically  slower  than  writing  directly 
to  the  disk.  On  most  operating  systems 
(including  Unix  and  DOS),  file  access 
is  optimized  assuming  random  inter¬ 
mittent  access  and  blocks  are  dynami¬ 
cally  added  to  the  file  as  it  grows.  The 
data  blocks  that  make  up  a  file  may  be 
scattered  all  over  the  disk,  making  ac¬ 
cess  to  some  files  faster  than  to  others. 
To  provide  faster  reads  and  writes  to 
files  used  for  high-speed  data  acquisi¬ 
tion,  some  operating  systems  offer  con¬ 
tiguous  files  that  have  data  blocks  that 
are  preallocated  on  the  media  to  pro¬ 
vide  maximum  speed  for  sequential 
access.  The  file  cannot  grow  dynami¬ 
cally  beyond  a  preset  maximum  size, 
but  it  can  be  written  to  as  fast  as  writing 
directly  to  the  disk. 

To  acquire  data  at  high  speed,  there 
must  be  a  program  to  read  the  data 
from  the  analog  input  device  and  write 
it  to  the  file  on  mass  storage.  This  pro¬ 
gram  must  use  a  FIFO  buffering  scheme 
to  simultaneously  read  data  from  the 
analog  device  and  write  it  to  disk.  Buff¬ 
ering  is  important  because  it  allows 
large  buffers  to  be  transferred  to  disk 
without  losing  input  samples  during 
the  disk  access.  Although  this  can  be 
done  with  a  single  task  and  asynchro¬ 
nous  I/O,  it  is  much  easier  to  use  two 
tasks  — one  to  store  sampled  data  into 
the  buffer  and  one  to  write  data  from 
the  buffer  to  disk.  The  ability  of  a  pro¬ 
gram  to  write  to  a  file  on  disk  presup¬ 
poses  that  the  program  is  running  un¬ 
der  some  operating  system.  A  multi¬ 
tasking  operating  system  is  needed  to 
support  the  data  acquisition  program 
so  it  can  read  and  write  simultaneously 
(the  CPU  can’t  continually  read  from 
the  analog  input  if  it  is  in  a  busy  wait 
loop  waiting  for  the  disk). 

Real-Time  Response 

For  a  real-time  data  acquisition  system 
to  work,  much  care  must  be  taken  to 
ensure  that  samples  are  not  lost  be¬ 
cause  the  input  buffer  of  the  analog 
device  driver  has  overflowed.  Because 
the  input  buffer  is  filled  at  the  sampling 
rate,  the  buffer  must  be  emptied  within 
a  certain  period  of  time. 

In  a  multitasking  system,  the  prob¬ 
lem  of  emptying  the  input  buffer  in 
time  becomes  one  of  CPU  throughput 
and  task  response.  The  computer  must 
run  fast  enough  to  be  able  to  copy  the 
data  from  the  input  buffer  before  any 
of  it  is  overwritten.  This  is  the  easy  part; 
32-bit  microprocessors  can  typically 
copy  2  to  8  Mbytes/sec.  and  the  setup 
time  is  minimal.  The  more  difficult  part 
is  task  response.  The  input  task  waits 
for  the  input  buffer  to  fill  to  a  certain 
point  by  giving  up  use  of  the  CPU.  This 
gives  other  tasks  in  the  system  the 


chance  to  run  (such  as  the  task  that 
writes  the  sampled  data  to  disk).  When 
the  buffer  has  filled  to  the  certain  point, 
the  device  driver  schedules  the  input 
task  to  run.  The  time  to  schedule  a  task, 
the  amount  of  time  for  which  task 
switches  are  disabled,  and  the  time  it 
takes  to  do  a  task  switch  all  contribute 
to  the  worst-case  task  response. 

Many  operating  system  manufactur¬ 
ers  quote  only  the  best  and  typical  task 
responses  because  they  have  not  taken 
care  to  limit  the  time  for  which  task 
switches  are  disabled.  This  is  not  use¬ 
ful  because  data  samples  can  still  be 
lost  if  the  input  task  cannot  respond  in 
time  occasionally.  For  this  reason, 
programmers  must  construct  their  code 
with  the  worst-case  task  response  times 
in  mind  rather  than  best,  typical,  or 
average  reponse  times. 

A  real-time  operating  system  guaran¬ 
tees  fast  worst-case  task  response,  mak¬ 
ing  the  operating  system  an  important 
part  of  a  high-speed  data  acquisition 
system.  These  requirements  and  how 
they  can  be  met  are  best  explained 
with  an  example  of  a  data  acquisition 
system. 

A  Data  Acquisition  System 

For  the  purposes  of  this  article,  we’ll 
describe  a  typical  data  acquisition  sys¬ 
tem  that  can  collect  12-bit  analog  data 
on  up  to  16  channels  and  save  it  to  disk 
at  rates  from  as  low  as  once  every  two 


Figure  1:  The  hardware  configuration 
of  a  typical  data  acquisition  system 


seconds  up  to  250,000/sec.  (aggregate). 
The  hardware  in  our  system  consists 
of  an  80386  AT-compatible  computer, 
an  analog  I/O  board,  and  a  high-ca¬ 
pacity  hard  disk.  The  software  consists 
of  a  real-time  operating  system,  an  ana¬ 
log  I/O  device  driver,  and  a  couple  of 
utility  programs. 

The  PC  chosen  for  our  high-speed 
data  acquisition  system  is  an  80386  AT 
compatible  manufactured  by  Mylex.  The 


20-MHz  model  comes  with  4  Mbytes 
of  main  memory  and  is  rated  at  ap¬ 
proximately  4  MIPS.  The  80386  AT  com¬ 
patible  was  chosen  for  several  reasons. 
First,  it  has  the  ability  to  run  the  LynxOS, 
Unix-compatible,  real-time  operating  sys¬ 
tem.  Second,  many  I/O  boards  are  avail¬ 
able  for  the  AT  bus.  Third,  because 
they  are  produced  in  such  large  vol¬ 
umes,  80386  AT  compatibles  have  an 
excellent  price/performance  ratio.  Fig¬ 
ure  1  shows  the  hardware  configuration. 

The  analog  I/O  board  used  in  this 
system  is  the  DT2821  from  Data  Trans¬ 
lation.  It  features  16  input  channels 
and  2  output  channels,  both  with  12- 
bit  (or  16-bit)  resolution.  The  DT2821 
was  chosen  because  of  its  DMA  sup¬ 
port  for  both  input  and  output  chan¬ 
nels.  Either  a  DMA  interface  or  on¬ 
board  FIFO  is  necessary  to  allow  high¬ 
speed  transfers  without  hogging  the 
CPU.  The  CPU  needs  to  be  free  to 
perform  other  tasks,  not  the  least  of 
which  is  saving  the  transferred  data  to 
disk.  Both  the  high-speed  input  and 
output  capabilities  of  the  DT2821  are 
used  in  our  example.  The  board  has 
an  input  throughput  of  up  to  250KHz 
and  an  output  throughput  of  up  to 
130KHz  per  channel. 

The  last  hardware  component  of  the 
computer  system  is  the  mass  storage 
device.  LynxOS,  the  operating  system 
we  use,  comes  with  an  optional  high¬ 
speed  SCSI  interface  that  breaks  the 
normal  DMA  bottleneck  on  the  AT  by 
bursting  32  bytes  at  a  time  over  the  bus 
using  16-bit  transfers.  This  SCSI  inter¬ 
face  has  a  maximum  throughput  of  3  5 
Mbytes/sec.  The  average  AT  SCSI  inter¬ 
face,  which  does  8-bit  DMA  transfers, 
has  a  maximum  throughput  of  250K/ 
sec.  Our  sample  system  uses  a  CDC 
270-Mbyte  Wren  IV  drive.  Its  through¬ 
put  in  our  system  is  over  1  Mbyte/sec. 
We  could  have  chosen  the  standard 
AT  interface  and  hard  drive,  which  has 
a  sustained  throughput  of  211K/sec., 
but  we  wanted  higher  capacity. 

The  most  important  piece  of  soft¬ 
ware  in  our  system  is  the  operating 
system.  We  use  LynxOS,  a  real-time, 
multitasking,  multiuser  operating  sys¬ 
tem  especially  designed  for  closed- 
loop  control  and  data  acquisition. 
LynxOS  is  a  4.2BSD  Unix  look-alike 
with  features  added  from  System  V  Unix. 

Compatibility  with  Unix  gives  users 
a  wide  choice  of  programs  with  which 
to  develop  software  and  process  col¬ 
lected  data,  but  the  major  feature  of 
this  operating  system  is  its  real-time 
capability.  It  has  guaranteed  worst- 
case  interrupt  response  and  task  re¬ 
sponse  delays,  which  means  that  the 
worst-case  response  to  external  events 
can  be  calculated  for  every  program 
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running.  LynxOS  also  has  user-con¬ 
trolled  priority  scheduling,  which  means 
that  data  acquisition  tasks  can  be  set 
at  high  priority  and  will  not  be  affected 
by  tasks  running  at  lower  priority.  In 
addition,  multiple  streams  of  high-speed 
data  can  be  acquired  concurrently.  Pro¬ 
gram  development  can  be  done  while 
acquiring  data,  and  data  can  be  proc¬ 
essed  and  displayed  while  other  data 
is  being  acquired. 

Another  important  feature  of  Lynx¬ 
OS  is  the  ability  to  create  contiguous 
files  within  the  normal  file  system.  Con¬ 
tiguous  files  are  files  whose  data  blocks 
are  sequential  on  the  disk.  Accesses  to 
contiguous  files  do  not  go  through  the 
disk  cache.  Instead,  the  data  is  trans¬ 
ferred  directly  from  user  task  memory 
via  DMA  to  and  from  the  mass  storage 
device.  Not  only  is  there  practically  no 
CPU  overhead  transferring  the  data,  but 
also  larger  amounts  of  data  can  be  trans¬ 
ferred  per  request.  Most  SCSI  disk  drives 


Figure  2:  The  circular  DMA  buffer  in 
a  DT2821  driver 


can  transfer  data  with  64K  requests  more 
than  twice  as  fast  as  8K  requests  be¬ 
cause  of  controller  overhead  in  SCSI 
command  processing. 

Contiguous  files  are  just  like  regular 
files,  with  two  restrictions:  The  maxi¬ 
mum  size  must  be  specified  when  cre¬ 
ating  them,  and  access  requests  to  them 
must  be  made  in  multiples  of  512  bytes. 
The  size  of  a  contiguous  file  can  vary 
just  as  can  a  normal  file.  The  creation 
size  is  simply  the  maximum  size  the  file 
can  become. 

The  next  piece  of  software  is  the 
device  driver  for  the  DT2821  I/O  board. 
The  device  driver  is  the  link  between 
the  operating  system  and  the  DT2821 
device.  The  operating  system  and  the 
device  driver  make  the  device  look  just 
like  a  file  on  disk.  The  device  can  be 
opened,  read  from,  or  written  to  just 
as  a  file  can. 

When  the  device  is  opened  for  read¬ 
ing,  the  device  driver  starts  up  a  DMA 


channel  to  read  from  the  DT2821  and 
write  into  a  4K  circular  buffer.  Figure 
2  shows  the  circular  DMA  buffer  in  the 
DT  2821  driver. 

The  PC/AT  DMA  controller  is  pro¬ 
grammed  for  auto-initialize  mode  so 
that  when  it  fills  up  the  4K  buffer,  it 
starts  over  again  automatically.  This 
mode  is  important  because  at  250,000 
samples/sec.  there  would  only  be  4 
microseconds  to  reload  the  DMA  con¬ 
troller,  which  is  not  enough  time. 


A  multitasking 
operating  system  is 
needed  to  support  the 
data  acquisition 
program  so  it  can  read 
and  write 
simultaneously 


When  it  receives  a  read  request,  the 
driver  uses  a  timer  to  wait  approxi¬ 
mately  the  time  it  takes  to  acquire  2K 
into  the  circular  buffer.  Then  the  driver 
copies  from  the  circular  buffer  to  the 
buffer  in  the  requesting  task.  Waiting 
and  copying  is  repeated  until  the  re¬ 
quested  number  of  bytes  is  copied,  at 
which  time  readf )  returns  to  the  call¬ 
ing  program.  The  driver  handles  writ¬ 
ing  to  the  D/A  ports  of  the  DT2821  in 
a  similar  fashion. 

The  rest  of  the  software  is  made  up 
of  two  utility  programs  provided  with 
the  operating  system.  The  first  of  these 
is  saio.  Saio  allows  you  to  set  the  rate 
of  acquisition  and  the  gain  on  each 
channel  and  to  group  channels  for  si¬ 
multaneous  access.  It  does  this  by  mak¬ 
ing  requests  through  the  ioctl  system 
call  to  the  device  driver. 

The  second  utility  program  is  dbuff. 
Dbuff  reads  data  from  standard  input 
and  writes  it  to  standard  output  con¬ 
tinuously.  Dbuff  begins  by  forking  it¬ 
self  into  two  tasks.  The  input  (pro¬ 
ducer)  task  puts  its  data  into  one  of  two 
shared  buffers;  the  output  (consumer) 
task  gets  the  data  from  each  shared 
buffer  when  full.  Figure  3  shows  the 
double-buffering  scheme  used  by  dbuff. 
This  double-buffering  scheme  allows 
large  buffers  to  be  written  to  the  disk, 
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a  necessity  when  high  throughput  is 
required.  Dbuff  uses  many  of  the  oper¬ 
ating  system  features,  such  as  multi¬ 
tasking,  shared  memory,  and  sema¬ 
phores.  A  complete  listing  of  dbuff  is 
shown  in  Listing  One,  page  86. 

Real-Time  Considerations 

Before  we  start  acquiring  data,  we  must 
make  sure  that  we  have  the  real-time 
response  necessary  to  make  our  sys¬ 
tem  work.  The  task  reading  from  the 
DT2821  device  has  to  read  the  data  out 
of  the  circular  buffer  before  the  DMA 
controller  overwrites  the  data.  The  task 
reading  is  awakened  by  the  timer  to 
read  out  of  the  4K  circular  buffer  after 
the  DMA  has  time  to  fill  half  the  buffer. 
This  gives  the  task  half  of  the  time  it 
takes  to  fill  the  buffer  to  get  the  data. 
At  our  maximum  DMA  transfer  speed 
of  500K/sec. ,  2,048/500,000  seconds  (ap¬ 
proximately  4  milliseconds),  are  avail¬ 
able  to  transfer  the  data. 

The  operating  system  guarantees  500 
microseconds  (0.50  milliseconds)  worst- 
case  response  for  the  highest  priority 
task  on  a  4-MIP  80386  computer.  There¬ 
fore,  if  the  task  reading  from  the  DT2821 
is  the  highest  priority  task,  we  are  as¬ 
sured  of  success.  If  there  are  other  tasks 
at  higher  priority,  such  as  another  data 
acquisition  task,  we  would  have  to  meas¬ 
ure  its  longest  continuous  CPU  usage 
and  add  that  to  the  500  microseconds 
and  make  sure  that  that  value  was  less 
than  4  milliseconds. 

We  can  estimate  the  longest  continu¬ 
ous  CPU  usage  for  our  data  acquisition 
tasks.  The  task  accessing  the  DT2821 
incurs  a  system  call  overhead  of  25 
microseconds  when  reading  or  writ¬ 
ing.  The  longest  stretch  of  time  the 
DT2821  device  driver  uses  the  CPU  is 
the  0.3  to  0.6  milliseconds  it  takes  to 
copy  2K.  Thanks  to  contiguous  files, 
the  task  writing  to  the  disk  uses  even 
less  CPU  time,  only  about  70  microsec¬ 
onds  to  set  up  the  DMA  controller  and 
SCSI  controller  to  transfer  the  data  to 
or  from  disk,  including  the  system 
call  overhead.  The  continuous  CPU 
usage  for  both  data  acquisition  tasks  is 
0.02  +  0.60  +  0.07  =  0.69  milliseconds. 

Thus  the  worst-case  response  of  a 
task  running  at  lower  priority  than  both 
tasks  doing  the  data  acquisition  is  the 
guaranteed  worst-case  response  of  500 
microseconds  plus  the  CPU  usage  of 
the  data  acquisition  tasks,  or  0.69  + 
0.50  =  1.19  milliseconds. 

A  Data  Acquisition  Session 

As  an  application  of  a  high-speed  data 
acquisition  system,  we  can  record  a 
song  on  the  hard  disk  at  compact  disc 
speeds  and  then  play  it  back,  first  on 
just  one  channel,  then  in  stereo. 


This  particular  application  shows  ac¬ 
quisition  of  analog  data,  which  is  the 
kind  of  data  usually  acquired.  The  rate 
of  acquisition  is  on  the  same  order  as 
that  of  a  typical  application.  The  quan¬ 
tity  of  data  acquired  is  also  common 
to  many  high-speed  data  acquisition 
applications.  Finally,  recording  and  play¬ 
ing  back  music  is  a  good  test  of  the 
acquisition  system  because  you  can  hear 
whether  data  is  acquired  properly  when 
it  is  played  back. 

Suppose  we  record  the  music  from  a 
home  stereo  receiver.  Standard  voltage 
levels  for  these  devices  are  in  the  range 


-  1  to  +1  volts.  The  DT2821  board’s 
bipolar  range  is  - 10  to  10  volts.  So, 
we  need  to  set  the  gain  as  close  to  10 
as  we  can  for  the  input  signal  and  use 
a  voltage  divider  circuit  made  from  two 
resistors  to  get  the  output  in  the  correct 
range.  We  tie  input  channel  0  on  the 
DT2821  to  TAPE  OUT  LEFT  on  our 
stereo,  and  we  tie  output  channel  0  to 
our  resistor  circuit,  then  to  AUX  LEFT 
input  on  the  back  of  the  amplifier.  For 
stereo,  we  can  tie  input  channel  1  and 
output  channel  1  to  TAPE  OUT  RIGHT 
and  AUX  RIGHT.  Figure  4  shows  the 
stereo/computer  combination. 
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Normally,  you  must  use  a  Nyquist 
filter,  which  is  a  low-pass  filter  with  a 
cutoff  of  half  the  sampling  frequency, 
on  the  input  to  the  A/D  converter.  Ex¬ 
perimentation  has  shown,  however,  that 
the  filtering  through  the  stereo  is  suffi¬ 
cient.  It  is  also  a  good  idea  to  put  an 
anti-aliasing  filter  on  the  output  so  that 
the  output  frequency  can’t  be  heard. 
An  anti-aliasing  filter  is  not  really  nec¬ 
essary  in  this  case  because  it  is  impos¬ 
sible  to  hear  the  sampling  frequency 
of  44KHz.  The  amplifier  effects  some 
filtration  internally  as  well. 

Now  let’s  do  some  data  acquisition. 
Compact  disc  speed  is  44,000  samples/ 
sec.,  which  means  we  will  have  to  save 
88K/sec.  to  disk  for  a  single  channel 
and  176K/sec.  to  disk  for  stereo. 

First,  we  create  a  30-Mbyte  contigu¬ 
ous  file  to  hold  the  song.  With  a  file  of 
this  size  we  can  record  about  6  minutes 
from  a  single  channel  or  3  minutes  of 
stereo.  The  LynxOS  command  to  cre¬ 
ate  a  contiguous  file  is 

mkcontig  music. data  30m 

Now  we  set  input  and  output  transfer 
rates  and  the  input  gain  of  the  DT2821. 
The  device  node  for  the  DT2821  is 
called  dtaio  and  is  located  in  the  direc¬ 
tory  /dev.  We’ll  just  collect  one  chan¬ 
nel  of  data  first: 

saio  -  rate  .000027  -  gain  10 

<  /dev/dtaio 

saio  -  rate  .000027  >  /dev/dtaio 

The  driver  will  set  the  gain  and  rate 
values  as  close  as  it  can  to  the  re¬ 
quested  values.  The  actual  values  can 
be  inspected  as  follows: 

saio  <  /dev/dtaio 

Next  we  can  set  the  stereo  to  our 
favorite  FM  station  and  record  a  song 
off  the  air.  We  can  use  dbuff  and  redi¬ 
rect  the  input  from  /dev/dtaio  and  di¬ 
rect  the  output  to  our  file  music. data: 

dbuff  21  20  <  /dev/dtaio  >  music,  data 

When  the  song  ends,  we  can  press 
Ctrl-C  to  stop  collecting.  Note  that  dbuff 
takes  two  numeric  arguments.  The  first 
value  is  used  for  the  priority  of  the 
producer  task,  and  the  second  value  is 
used  for  the  priority  of  the  consumer 
task.  We  have  set  the  priority  of  the 
task  reading  from  /dev/dtaio  to  21  and 
that  of  the  task  writing  to  the  file  mu¬ 
sic. data  to  20.  It  is  not  really  necessary 
to  set  the  task  accessing  /dev/dtaio  to 
be  of  higher  priority  than  the  consumer 
task  in  this  case  because  the  consumer 


is  writing  to  a  contiguous  file  and  will 
not  use  much  CPU  time. 

Now  let’s  play  back  the  song.  We  set 
the  stereo  to  AUX  and  type 

dbuff  20  21  <  music. data 

>  /dev/dtaio 

To  add  echo  or  reverberation  to  the 
data,  you  can  run  the  data  through  the 
reverb  program  in  Listing  Two,  page 
88,  using: 

reverb  <  music.data  I  dbuff  20  21 

>/dev/dtaio 

Reverb  reads  from  standard  input,  so 
it  is  necessary  to  use  redirection  to 
make  it  read  from  music.data. 

To  hear  what  a  song  sounds  like  back¬ 
ward,  you  can  use  the  program  in  List¬ 
ing  Three,  page  90,  to  reverse  the  sam¬ 
ples.  The  program,  hypothetically  called 
reverse,  could  be  executed  as  follows: 


Figure  3.'  The  double-buffering  scheme 
used  by  dbuff 


Figure  4:  The  stereo/computer 
combination 


reverse  music.data  I  dbuff  20  21 

>/dev/dtaio 

The  output  from  reverse  is  piped 
through  dbuff,  then  sent  to  the  DT2821. 
We  have  told  dbuff  to  set  the  priority 
of  the  task  writing  to  /dev/dtaio  higher 
than  that  of  the  producer  task  to  guar¬ 
antee  its  response  time.  We  can  com¬ 
bine  these  “filter”  programs  easily: 

reverse  music.data  I  reverb  I  dbuff 
20  21  >  /dev/dtaio 

To  record  and  play  in  stereo,  we  use 
saio  to  group  input  channels  0  and  1 
and  output  channels  0  and  1 : 

saio  -  group  0  1  <  /dev/dtaio 

saio  -  group  0  1  >  /dev/dtaio 

The  commands  to  record  and  play  a 
song  are  the  same  as  before. 

We  are  now  collecting  data  at  88,000 
samples/sec.,  or  176K/sec.  After  acquir¬ 
ing  the  data,  it  can  be  processed  and 
analyzed  on  our  system  or  sent  to  an¬ 
other  computer.  (LynxOS  comes  with 
a  powerful  software  development  en¬ 
vironment  and  X  Windows,  which  can 
be  used  to  create  programs  to  display, 
edit,  and  process  the  acquired  data. 
Also,  it  supports  Ethernet  and  TCP/IP 
to  provide  high-speed  links  to  other 
computers.) 

Summary 

The  computer  system  described  in  this 
article  meets  all  requirements  of  a  high¬ 
speed  data  acquisition  system.  The 
DT2821  analog  I/O  board  serves  to 
change  the  real-world  data  to  discrete 
digital  data.  The  SCSI  disk  system  pro¬ 
vides  the  high-speed  mass  storage  ca¬ 
pability.  LynxOS,  dbuff,  and  the  device 
driver  for  the  DT2821  are  the  software 
that  performs  the  acquisition.  The  op¬ 
erating  system  guarantees  the  real-time 
response  and  provides  the  environment 
to  analyze  the  data. 
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This  approach  is  a  good  compromise  when 
performance  considerations  prevent  the  complete  usage 
of  a  high-level  language 

Ronald  Fischer 


Looking  back  at  approximately  30 
years  of  steady  development  of 
programming  languages,  there  is 
no  doubt  that  development 
strives  towards  more  generality, 
more  abstraction,  and  — last  but  not 
least  — more  expressional  power.  The 
first  assembler  programs  of  the  early 
1950s  were  a  giant  achievement  over 
machine  code  (binary)  programming. 
Later,  the  first  so  called  high-level  lan¬ 
guage  was  invented  by  software  pio¬ 
neer  John  Backus.  This  language  was 
called  Fortran,  and  its  descendant,  For¬ 
tran  77,  is  still  in  use  today. 

The  next  development  in  program¬ 
ming  languages  was  known  as  “non¬ 
procedural  languages”  (sometimes 
called  5th-generation  languages,  a  term 
that  I  do  not  like  because  it  has  be¬ 
come  rather  worn  over  the  years).  The 
very  same  expression  is  used  today  not 
only  for  pure  database  languages  like 
SQL,  Nomad,  and  RAMIS  but  also  for 
true  general-purpose  languages  such 
as  Prolog. 

No  one  debates  that  you  can  code  a 
given  problem  much  faster  using,  say, 
Prolog  rather  than  assembler.  We  call 
this  modern  approach  “high-level  pro¬ 
gramming,”  compared  to  the  “low  level” 
of  assembly  language.  So  why  do  as¬ 
semblers  still  exist?  As  every  system 
programmer  knows,  there  are  situations 
where  you  have  to  use  assembler.  Most 
operating  system  kernels  are,  for  instance, 
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written  in  assembler.  Even  the  famous 
Lilith  machine,  designed  in  the  early 
1980s  by  a  design  team  led  by  Pascal 
inventor  Niklaus  Wirth,  had  a  few  criti¬ 
cal  routines  written  in  machine  lan¬ 
guage,  although  most  of  the  operating 
system  was  coded  in  Modula-2.  The 
reasons  for  such  decisions  are  — in  most 
cases  — speed,  but  sometimes  space  con¬ 
siderations  also  play  a  critical  role. 

On  the  other  hand,  given  a  suffi¬ 
ciently  huge  problem,  like  coding  a 
multiuser  operating  system,  it  becomes 
too  complex  for  the  human  brain  to 
manage  at  assembly  level.  In  most  ap¬ 
plications,  a  mix  of  assembler  and  high- 
level  language  (HLL)  is  used.  Examples 
are  the  PICK  operating  system  (Ba- 
sic+assembler)  and  some  of  IBM’s  main¬ 
frame  operating  systems  (PL/1  and  as¬ 
sembler).  One  could  call  this  approach 
“two-level  programming,”  because  lan¬ 
guages  at  precisely  two  different  levels 
are  used. 

When  developing  system  software, 
two-level  programming  is  often  an  un¬ 
satisfactory  solution:  For  much  of  the 
code,  the  HLL  is  “too  high,”  but  assem¬ 
bly  language  is  too  “low.”  System  pro¬ 
grammers  therefore  have  been  looking 
for  languages  that  can  better  accom¬ 
modate  the  range  of  needs.  We  call  a 
programming  language  that  satisfies  this 
property  “variable  level." 

Many  experiments  were  carried  out 
in  this  area  during  the  late  1960s  and 
throughout  the  1970s:  BCPL,  BLISS, 
SPL3000  (Hewlett-Packard)  and  Siemens 
SPL  are  just  a  few  examples.  Three 
languages,  however,  proved  to  be  very 
successful:  C,  which  was  used  to  write 
the  Unix  operating  system,  PL/M  used 


for  system  programming  by  Digital  Re¬ 
search,  and  Charles  Moore’s  Forth.  But 
only  the  latter  really  earns  the  tag  “vari¬ 
able  level,”  because  neither  C  nor 
PL/M,  despite  their  success,  provide  a 
single  framework  for  system  program¬ 
ming:  Both  Unix  and  Digital  Research’s 
Concurrent  CP/M  contain  some  assem¬ 
bler  code  and  the  user  does  not  have 
much  influence  on  the  degree  of  ab¬ 
straction  or  “level”  of  the  statements 
used. 

Forth  is  different.  A  Forth  program 
consists  of  a  collection  of  words  (simi¬ 
lar  to  functions  or  procedures  in  other 
languages).  Each  word  in  turn  is  com¬ 
posed  of  other  words.  The  user  there¬ 
fore  may  assign  to  each  conceptional 
level  (or  abstraction  layer)  a  family  of 
Forth  words  that  are  defined  in  terms 
of  lower-level  words  only.  The  assem¬ 
bler  is  integrated  into  the  language  and 
represents  the  bottom  level.  In  practice, 
this  means  that  a  function  for  searching 
through  a  text  file  uses  high-level  Forth 
words  like  EOF?,  GET-NEXT-LINE,  or 
MATCH-PATTERN,  while  an  interrupt 
handler  manipulates  bits  and  bytes. 

Variable-Level  Approaches 

Recently  two  new  languages  aimed  at 
variable-level  programming  have  gained 
attention  from  system  programmers:  FU- 
TURE86  and  CDL2.  The  remainder  of 
this  article  covers  some  of  the  main 
features  of  these  languages.  For  com¬ 
parison  purposes,  two  sample  programs 
are  coded  in  FUTURE86  and  CDL2. 
Because  many  readers  may  be  familiar" 
with  C,  these  sample  programs  are  de¬ 
scribed  first  in  C.  All  programs  were 
developed  on  a  80386  system  running 


46 

388 


Dr.  Dobb’s Journal,  June  1989 


(continued  from  page  46) 

PC-DOS  3  3.  The  compilers  used  were 
MIX  Power  C,  Development  Associates 
FUTURE86,  and  epsilon  CDL2Lab. 

The  first  example  is  a  subroutine, 
AUXOUT,  which  sends  one  character 
to  the  serial  device  (called  AUX  under 
DOS).  This  is  an  example  of  a  low- 
level  system  dependent  function,  be¬ 
cause  it  is  unlikely  that  the  very  same 
call  exists  on  different  operating  sys¬ 
tems.  Although  DOS,  for  example,  has 
one  primary  serial  port  — namely  AUX  — 
other  operating  systems  might  always 
require  an  identification  of  which  serial 
interface  to  use. 

Most  C  compilers  support  some  ge¬ 
neric  interface  to  the  host  system.  For 
example,  Power  C  has  among  its  func¬ 
tions  a  routine  called  bdos,  which  ac¬ 
cepts  three  parameters  and  generates 
an  /AT  21H  interrupt  to  call  DOS.  The 
parameters  are  placed  in  the  registers 
AH,  DX,  and  AL,  respectively,  and  cor¬ 
respond  therefore  to  function  code,  func¬ 
tion  argument,  and  function  code  pa¬ 
rameter.  For  this  example,  a  quick  look 
in  IBM’s  DOS  Technical  Reference 
Manual  tells  that  we  have  to  use  4  as 
the  function  code  (auxiliary  output) 
and  the  character  to  be  output  as  argu¬ 
ments.  The  code  parameter  is  not  used; 


we  deliberately  set  it  to  zero.  Listing 
One  (see  page  92)  shows  the  resulting 
function. 

The  second  example  is  of  much 
higher  level.  Suppose  we  have  two  char¬ 
acter  strings,  S  and  T,  and  one  charac¬ 
ter  transformation  function  X TRANS, 
which  accepts  one  character  and  deliv¬ 
ers  an  arbitrarily  transformed  charac¬ 
ter.  The  objective  is  to  design  a  func¬ 
tion  SFILT,  which  appends  S  to  T,  but 
by  doing  so  applies  XTRANS  to  every 
character  of  S.  For  this  example,  we 
assume  that  the  array  holding  7'must  be 
large  enough  to  also  accommodate  S. 

As  an  application,  imagine  that  you 
want  to  send  one  record  of  a  binary  file 
to  the  printer.  Because  the  data  may 
also  contain  nonprintable  characters, 
such  as  escape  sequences,  we  cannot 
blindly  output  the  record.  Instead,  each 
nonprintable  character  should  be  re¬ 
placed  by  a  dash.  This  could  be  ac¬ 
complished  with  SFILTin  the  following 
way:  Let  S  be  the  record  to  be  printed, 
let  Tbe  a  sufficiently  large  buffer  con¬ 
taining  the  string 

"RECORD  #12  (non-printables  replaced 

by  ’-’):" 

and  finally  let  XTRANS  be  the  function 
that  maps  nonprintable  characters  into 
dashes  and  leaves  others  unchanged. 

For  the  sake  of  brevity  assume  in  the 
example  a  fixed  function  named 
XTRAlNS-,  in  practice,  this  function  itself 
would  be  passed  as  a  parameter  for 
added  flexibility  so  that  different  calls 
of  SFILT  could  use  different  transfor¬ 
mation  functions.  For  the  same  reason, 
no  concrete  implementation  of  XTRANS 
is  given. 

The  resulting  C  program  is  shown 
in  Listing  Two  (page  92).  Efficiency  is 
not  the  primary  goal,  however,  because 
FUTURE86  and  CDL2  are  biased  to¬ 
wards  recursive  function  calls,  we  will 
also  use  recursion  in  the  C  example. 
This  makes  it  easier  to  compare  the 
examples.  In  a  real  project,  of  course, 
you  would  use  a  loop. 

The  FUTURE86  Language 

The  history  of  FUTURE86  dates  back 
to  1979.  At  this  time  Akira  Katagiri,  a 
Japanese  scientist,  implemented  a  Forth 
compiler  for  a  Z-80-based  microcom¬ 
puter  system.  During  this  work,  he 
found  some  deficiencies  in  this  lan¬ 
guage,  most  notably  the  lack  of  read¬ 
ability.  He  then  devised  a  successor, 
appropriately  called  FIFTH,  and  imple¬ 
mented  it  on  different  environments. 
FIFTH  is  widely  used  in  Japan. 

FUTURE86  is  an  evolution  of  FIFTH 
created  during  the  1980s.  The  first  com¬ 
piler  was  commercially  available  in  1987. 


Like  FIFTH,  it  augmented  the  power 
of  Forth  without  being  just  another  Forth 
dialect.  Despite  its  short  history, 
FUTURE86  has  already  been  used  to 
implement  numerous  projects.  For  exam¬ 
ple,  software  for  sophisticated,  auto¬ 
matic  postal  scales  and  a  natural  lan¬ 
guage  compiler  has  used  FUTURE86. 
Like  Forth,  every  FUTURE86  program 
implicitly  operates  on  two  stacks,  called 
the  data  stack  (that  is,  “stack”)  and  the 
return  stack.  These  names  are  a  little 
bit  misleading,  because  the  return  stack 
may  also  contain  temporary  data  in 
addition  to  return  addresses.  Most  pre¬ 
defined  functions,  however,  operate  on 
the  data  stack. 

An  expression  is  written  in  reverse 
polish  notation  (RPN).  The  sentence 
15  27  101  +  for  instance  pushes  the 
numbers  15,  27,  and  101  sequentially 
onto  the  data  stack.  The  operation  “+” 
then  consumes  the  two  topmost  ele¬ 
ments,  27  and  101,  and  replaces  them 
by  their  sum.  The  data  stack  now  con¬ 
tains  the  numbers  15  and  128.  For  read¬ 
ers  unfamiliar  with  Forth  or  the  Hewlett- 
Packard  pocket  calculators,  this  may 
look  strange.  In  practice,  you  soon  get 
acquainted  with  this  type  of  operation. 

Not  everything  in  FUTURE86  is  RPN, 
however,  because  this  paradigm  only 
applies  to  the  evaluation  of  programs. 
Compile  time  expressions,  on  the  other 
hand,  are  written  in  the  more  tradi¬ 
tional  infix  notation.  The  following  state¬ 
ments,  for  instance,  set  MAXLENGTH 
to  1024. 

BUFSIZE  EQU  256 

NO-OF-BUFFERS  EQU  4 
MAXLENGTH  EQU  BUFSIZE 

*  NO-OF-BUFFERS 

In  fact,  every  sentence  may  contain 
compile  time  expressions  in  infix  nota¬ 
tion  by  enclosing  them  in  parentheses, 
like  this: 

17  (34  *45  +  8)  VAR  @  OVER  - 

Other  differences  from  Forth  con¬ 
cern  the  dependency  between  words: 
Because  FUTURE86  was  designed  as  a 
compiled  language,  two-pass  compila¬ 
tion  allows  extensive  forward  referenc¬ 
ing.  This  even  applies  to  different  com¬ 
pilation  units:  It  is  common  practice  for 
words  in  different  modules  to  mutually 
call  each  other. 

FUTURE86  also  contains  an  assem¬ 
bler.  Unlike  Forth,  assembler  state¬ 
ments  — which  may  be  freely  intermixed 
with  FUTURE86  words  — follow  the  syn¬ 
tax  generally  available  on  the  target 
machine.  On  a  80186  system,  you  could 
for  example,  write:  BOUND  BX, [TEST- 
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LOC]  inside  any  high-level  definition.  It 
is  therefore  the  responsibility  of  the  pro¬ 
grammer  to  select  the  desired  abstraction 
level  at  every  single  line  of  code! 

Other  minor  differences  from  Forth 
concern  the  usage  of  some  reserved 
words.  The  FUTURE86  version  of  LOOP 
functions,  for  example,  is  slightly  differ¬ 
ent  than  its  Forth  counterpart. 

Now  let’s  look  at  how  the  sample 
programs  are  written  in  FUTURE86.  List¬ 
ing  Three  (page  92)  demonstrates  one 
possible  solution  of  the  AUXOUT  prob¬ 
lem.  The  definition  of  AUXOUT,  as 
every  definition  of  a  new  word,  starts 
with  a  colon,  followed  by  the  name  of 
the  function. 

We  assume  that  the  character  to  be 
output  is  located  on  the  stack.  That  is, 
to  send  the  escape  character  to  the 
serial  interface  you  write:  27  AUXOUT. 
The  predefined  word  !DL  pops  the  top 
value  from  the  stack  and  stores  it  in  the 
pseudo  CPU  DL  register.  Of  course, 
words  like  /DL  are  hardware  depend¬ 
ent.  The  next  word,  AUXOUT-FUN, 
pushes  this  constant  onto  the  stack, 
which  now  contains  the  number  4  only; 
the  27  is  still  in  pseudoregister  DL.  Then, 
the  word  INT_21H  is  called.  This  func¬ 
tion  removes  the  top  value  of  the  stack 
(4),  uses  it  as  DOS  function  code  (that 
is,  pushes  it  into  AH)  and  performs  an 
interrupt  (21  hex).  The  semicolon  closes 
the  definition. 

At  first,  words  like  !DL  seem  strange 
for  programmers  getting  used  to  tradi¬ 
tional  languages  such  as  Fortran  or  Pas¬ 
cal.  In  reality,  however,  even  this  en¬ 
hances  readability.  Because  FUTURE- 
86  — such  as  Forth  or  Lisp  — is  not  com¬ 
mitted  to  the  traditional  “Letter+Digit” 
identifiers,  one  can  devise  more  mean¬ 
ingful  names,  like:  IS-THERE-STILL- 
ROOM-IN-THE-BUFFER?  which,  by  the 
way,  is  a  perfectly  legal  FUTURE86 
word.  In  the  case  of  !DL ,  one  needs  to 
understand  that  the  exclamation  mark 
is  generally  used  in  the  context  “store 
from  stack  into  .  .  .  while  the  charac¬ 
ter  does  the  inverse. 

The  SFILT  program  in  Listing  Four 
(page  92)  is  more  complicated.  The 
function  XTRANSwas  — for  testing  pur¬ 
poses  — defined  as  nonoperation,  which 
is  the  shortest  possible  function  defini¬ 
tion.  To  comprehend  SFILT,  you  have 
to  understand  FUTURE86’s  unique  string 
concept. 

A  string  always  consists  of  two  parts: 
A  string  buffer  somewhere  in  memory, 
holding  left  justified  the  string  charac¬ 
ters,  and  a  control  block  called  SINFO 
(String  INFOrmation),  consisting  of  a 
pointer  to  the  buffer  and  a  length  field. 
For  string  operations  the  SINFO  is  stored 
in  the  data  stack.  The  simplest  way  to 


create  a  string  is  to  place  it  within  a 
quote,  like  this: 

:  HELLO  "Hello  world!"  SPRINT  ; 

The  execution  of  HELLO  would  allocate 
a  place  in  memory,  large  enough  to 
hold  all  the  characters,  place  the  ap¬ 
propriate  SINFO  on  the  data  stack  and 
call  the  word  SPRINT  (String  PRINT), 
which  causes  the  string  to  be  printed. 

Our  definition  of  SFILT  assumes  that 
the  SINFO’s  of  the  destination  string  T 
and  the  source  string  S  (in  that  order) 
are  placed  on  the  stack.  On  return, 
these  SINFOs  should  be  replaced  by 
the  updated  SINFO  of  the  destination 
string.  This  behavior  of  SFILT  is  de¬ 
picted  in  the  comment  line  labeled 
“stack  flow.” 

Following  the  C  example  SFILT starts 
by  determining  the  source  strings  length, 
which  is  the  second  part  of  its  SINFO 
and  therefore  on  top  of  the  stack.  Be¬ 
cause  IF  consumes  its  argument,  this 
data  item  has  to  be  duplicated  by  the 
word  SLEN.  Many  FUTURE86  functions 
remove  their  arguments  from  the  stack, 
so  this  is  quite  a  common  operation. 

The  next  steps  ( CGET  and  XTRANS) 
remove  the  first  character  from  the 
source  string  and  transform  it.  The  fol¬ 
lowing  three  lines  temporarily  save  the 
character  to  the  return  stack,  interchange 
the  stack  position  of  the  two  SINFOs, 
then  restore  the  character  to  the  stack. 

The  word  C+  appends  the  character 
to  the  destination  string.  Then,  the  SIN¬ 
FOs  stack  position  is  interchanged  again 
SFILT  is  recursively  called. 

The  ELSE  part  simply  discards  the 
now  empty  SINFO  of  the  source  string 
from  the  stack  to  fulfill  the  functional 
description  of  SFILT.  The  word  THEN 
matches  the  IF  and  is  similar  to  For¬ 
tran’s  ENDIF  statement. 

The  lines  below  demonstrate  the  us¬ 
age  of  SFILT.  The  destination  buffer  is 
called  DEST  and  may  hold  up  to  80 
bytes.  This  buffer  is  initialized  with  the 
function  SETUP.MAIN  calls  SETUP,  then 
SFILT,  and  finally  prints  the  resulting 
string  using  SPRINT.  This  also  shows 
how  words  work  together:  As  men¬ 
tioned,  SFILT  leaves  the  destination 
string’s  SINFO  on  the  stack  which,  in 
turn,  is  consumed  by  SPRINT. 

The  CDL2  Language 

CDL2  is  a  radically  different  language. 
It’s  precursor  was  CDL  (compiler  de¬ 
scription  language),  a  generator  used 
to  produce  compilers  from  a  given  af¬ 
fix  grammar.  The  first  implementation 
of  CDL  took  place  at  the  Mathematical 
Center  in  Amsterdam  (The  Netherlands), 
and  soon  it  became  popular  at  a  num¬ 
ber  of  European  universities. 


In  1974  the  language  was  extended 
by  adding  modularity  and  the  ability 
to  serve  as  a  general-purpose  program¬ 
ming  language  — CDL2  was  bom.  Since 
1980  it  has  become  available  outside 
the  university  community.  It  has  been 
used  for  numerous  commercial  appli¬ 
cations:  A  Cobol  compiler  from  the 
German  company  MBP,  the  Prolog  com¬ 
piler  MProlog,  Mephisto  (a  chess  com¬ 
puter),  and  EUMEL  are  but  a  few  exam¬ 
ples.  EUMEL  is  a  German  operating 
system  featuring  the  programming  lan¬ 
guage  Elan,  which  is  targeted  to  educa¬ 
tion  institutions  (high  schools,  univer¬ 
sities,  and  so  on). 

There  are  four  basic  elements  of  a 
CDL2  program:  actions,  tests,  predi¬ 
cates,  and  functions.  The  most  tradi¬ 
tional  form  is  the  action:  A  piece  of 
code  that  performs  some  operations, 
possibly  changing  its  environment.  The 
function  is  a  similar  construct,  but  pre¬ 
serving  the  environment  like  a  mathe¬ 
matical  function.  A  test  is  a  special  func¬ 
tion  that  delivers  a  Boolean  result. 

Depending  on  the  outcome,  succeed¬ 
ing  statements  in  a  clause  are  skipped 
or  executed.  Finally,  a  predicate  is  an 
action  that  may  either  fail  or  succeed. 
Failure  causes  backtracking  so  the  be¬ 
havior  is  similar  to  Prolog  clauses. 

Every  building  block  (action,  test, 
and  so  on)  may  itself  call  other  build¬ 
ing  blocks,  in  the  same  way  FUTURE86 
words  may  call  other  words.  There  are, 
however,  no  primitives  in  CDL2!  The 
programmer  therefore  has  to  define  the 
bottom  layer  himself.  This  is  accom¬ 
plished  by  defining  an  Action  as  a 
Macro,  that  is,  consisting  of  assembly 
language  instructions  only.  The  same 
is  true,  of  course,  for  tests,  predicates, 
and  functions.  For  simplicity,  I  refer  in 
the  sequel  to  “actions”  only  when  I 
mean  all  four  kinds  of  building  blocks. 
Unlike  FUTURE86,  assembly  statements 
and  high-level  CDL2  statements  cannot 
be  intermixed  when  defining  an  action. 

To  put  different  actions  together  is, 
however,  not  sufficient  to  produce  a 
CDL2  program.  The  language  was  defi¬ 
nitely  designed  for  programming-in-the- 
large,  for  projects  requiring  a  large  staff, 
and  delivering  tens  of  thousands  of  code 
lines.  Therefore,  the  design  of  the  pro¬ 
ject  is  an  integral  part  of  the  language. 

All  actions  belonging  to  the  same 
topic  are  grouped  in  a  SECTION.  A  set 
of  sections  forms  a  LAYER  (see  Listing 
Five,  page  92).  Layers  can  be  thought 
of  as  stacked  one  on  top  of  another. 
Each  layer  must  explicitly  state  which 
actions  are  exported  to  or  imported 
from  other  layers.  The  top  layer,  for 
instance,  could  represent  the  specifica¬ 
tion  of  the  problem.  The  next  layer 
then  could  be  a  prototype,  and  by  step- 
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(continued  from  page  52) 
wise  refinement,  we  reach  the  bottom 
layer,  consisting  of  the  applications  low- 
level  words.  Therefore,  most  assembly 
language  will  be  found  in  this  bottom 
layer  but  not  necessarily  all:  This  is 
completely  up  to  the  designer.  So,  vari¬ 
able-level  programming  may  not  only 
be  accomplished  by  thinking  in  words 
or  statements  but  in  a  more  general 
abstract  entity,  the  layer. 

Different  layers  together  form  a  MOD¬ 
ULE.  A  module  is  vaguely  related  to 
separate  compilation  units  in  other  pro¬ 
gramming  languages.  In  practice,  each 
programmer  on  a  CDL2  project  will 
work  on  one  and  only  one  module  at 
a  time. 

Finally,  different  modules  together 
form  a  PROGRAM.  It  should  be  clear 
by  now  that  CDL2  was  designed  to  be 
only  used  for  large  applications.  We 
therefore  only  sketch  our  example  pro¬ 
grams  by  defining  a  few  actions,  leav¬ 
ing  out  the  lowest  part  and  overall  pro¬ 
gram  organization. 

Listing  Six  (page  92)  shows  the  lay¬ 
out  of  the  AUXOUT  action.  As  in  the 
previous  examples,  the  DOS  function 
code  is  defined  by  a  compile  time  con¬ 
stant.  Note  that  for  improved  readabil¬ 
ity  CDL2  identifiers  may  contain  em¬ 
bedded  spaces  as  that  constant  has  been 
called  “AUXOUT  FUN." 

The  action  AUXOUT  expects  one  pa¬ 
rameter  C,  the  character  to  be  output. 
Every  CDL2  statement  consists  of  a  pro¬ 
cedure  evocation  (where  a  procedure 
could  be  action,  test,  predicate  or  func¬ 
tion)  and  actual  parameters  are  sepa¬ 
rated  by  plus  signs  (+).  Statements  are 
separated  by  commas  (sequential  execu¬ 
tion)  or  semicolons  (parallel  alternatives). 

The  action  header  follows  the  same 
format  but  states  the  formal  parame¬ 
ters.  In  addition,  the  type  of  the  pa¬ 
rameter  (input,  output,  or  inout)  is  speci¬ 
fied  by  placing  the  ’>’  character  to  the 
appropriate  side  (left,  right,  or  both) 
of  the  parameter  name.  In  this  example 
C  is  therefore  an  input  parameter.  A 
colon  at  the  end  of  the  header  line 
specifies  the  ACTION  as  containing 
CDL2  statements.  An  equal  sign  would 
specify  it  as  assembly  language  action. 

The  subsequent  three  lines  load  the 
registers  and  perform  the  interrupt.  In 
this  particular  example  I  also  enclosed 
the  definitions  necessary  to  get  the  as¬ 
sembly  instructions:  The  CDL2  words 
used  in  this  small  example  are  defined 
in  the  last  three  lines  of  Listing  Six. 

SFILT  is  only  loosely  sketched,  be¬ 
cause  a  complete  CDL2  implementa¬ 
tion  would  be  beyond  the  scope  of  this 
article.  As  can  be  seen  from  Listing 
Seven  (page  92),  the  destination  string 
TARGET  is  defined  as  an  out  parameter 


because  it  will  be  modified  during  evalu¬ 
ation  of  the  action.  Note  also  the  differ¬ 
ent  usage  of  semicolon  and  comma  to 
separate  the  statements. 

Conclusion 

Today  there  is  no  generally  accepted 
opinion  on  how  a  programming  lan¬ 
guage  should  look.  This  begins  with 
the  schism  between  functional  program¬ 
ming  (no  assignment  statements,  no 
state  change,  no  loops,  no  history), 
object-oriented  programming  (every  ob¬ 
ject  has  its  own  history)  and  traditional 
imperative  programming  (“let  Cobol  and 
Fortran  live  forever!”)  and  ends  with 
debates  if  Basic  should  be  allowed/ 
forbidden  in  high  schools.  Industry  pro¬ 
grammers  and  scientists  agree  only  on 
the  fact  that  we  have  some  kind  of 
software  crisis  (we  would  like  to  do 
much  more  programming  but  we  do 
not  know  how  to  manage  it). 

Variable-level  programming  is  certainly 
a  good  compromise  for  those  projects 
where  performance  considerations  pre¬ 
vent  the  complete  usage  of  a  high-level 
language.  Very  likely  this  will  still  be 
true  for  at  least  the  next  20  years. 

Due  to  its  roots  in  grammar  analysis 
CDL2  may  attract  even  more  attention 
in  the  near  future.  As  parallel  process¬ 
ing  becomes  more  feasible,  rule-based 
languages,  like  CDL2  or  Prolog,  could 
benefit  immediately  by  new  technolo¬ 
gies  because  they  are  easily  expand¬ 
able  to  cope  with  simultaneous  explo¬ 
ration  of  different,  but  parallel  branches 
or  rules. 

In  the  next  century  we  will  likely  have 
hardware  that  runs  Smalltalk,  Prolog, 
or  Miranda  at  the  speed  of  a  today’s 
8086  object  code.  Maybe  then  we  will 
no  longer  require  FUTURE86,  CDL2, 
or  their  future  successors.  My  opinion, 
however,  is  that  the  requirements  of 
projects  will  increase  — at  more  or  less  — 
the  same  rate  of  the  performance  of 
new  hardware.  The  problems  may  shift 
slightly,  but  they  won’t  disappear. 

Notes 

The  examples  have  been  developed 
using  the  POWER  C  compiler  by  MIX 
Software.  This  is  one  of  the  least  ex¬ 
pensive  C  compiler  available  but  is  com¬ 
plemented  with  the  debugger  CTRACE, 
a  very  powerful  development  tool  and 
probably  the  C  compiler  with  the  best 
price/performance  ratio  available.  For 
further  information,  contact  Mix  Soft¬ 
ware,  1132  Commerce  Dr.,  Richardson, 
TX  75081. 

At  present,  only  one  implementation 
of  FUTURE86  is  available  in  the  U.S., 
although  in  Japan  a  similar  version  is 
sold  by  RIGY  Corp.  The  U.S.  version 
is  available  from  Development  Associ¬ 


ates.  It  runs  under  PC/MS-DOS  and 
contains  code  generators  for  both  the 
8086  and  80186.  Other  instruction  sets, 
like  the  protected  mode  instructions 
of  the  80286  processor,  can  be  user 
defined  with  a  CODEMACRO  facility. 

The  compiler  comes  complete  with 
debugger  (FDT86)  and  libraries  for  CGA 
graphics,  serial  communications,  Hayes 
and  XModem  protocols,  and  floating 
point.  Libraries  are  delivered  in  source 
code;  thus,  the  graphics  library  may  be 
extended  to  accommodate  EGA  or  VGA 
formats.  An  optional  debugger  (REM86) 
is  available  for  target  use  and  functions 
via  the  serial  communication  line. 

Although  the  debugger  commands 
are  line  oriented  and  remind  me  of  the 
now  obsolete  Microsoft  SYMDEB,  it 
has  a  powerful  operation  mode  called 
“F-mode.”  In  this  mode,  FUTURE86  com¬ 
mands  may  be  entered  interactively, 
and  it  is  even  possible  to  compile  new 
words.  In  this  respect  FDT86E  acts  simi¬ 
larly  to  an  interactive  Forth  environment 
and  has  proven  useful  for  debugging 
the  example  programs.  For  more  infor¬ 
mation,  contact  Development  Associ¬ 
ates,  1520  South  Lyon,  Santa  Ana, 
CA  92705. 

The  implementation  used  was  the 
PC-DOS  version  of  CDL2LAB  from  the 
German  company  epsilon.  Several  other 
versions  are  available  from  epsilon,  in¬ 
cluding  versions  for  OS/2  (IBM  PS/2), 
VMS  (VAX),  NOS(Cyber  180),  BSD  Unix 
(VAX),  and  Unix  V  (Sun  3/50,  PCS 
Cadmus,  Nixdorf  Targon).  Code  gen¬ 
erators  for  cross  compilation  are  also 
available  for  TOS  (Atari)  and  even  the 
good  old  CP/M. 

CDL2LAB  extends  the  CDL2  com¬ 
piler  by  providing  an  integrated  envi¬ 
ronment,  grouped  around  a  central  da¬ 
tabase.  Documentation  is  available  in 
English.  For  further  information  on 
CDL2,  contact  epsilon,  Kurfurstendamm 
188/189,  D1  Berlin  15,  W.  Germany. 

Availability 

All  source  code  for  articles  in  this  issue 
is  available  on  a  single  disk.  To  order, 
send  $14.95  (Calif,  residents  add  sales 
tax)  to  Dr.  Dobb’s Journal ,  501  Galves¬ 
ton  Dr.,  Redwood  City,  CA  94063;  or 
call  800-356-2002  (from  inside  Calif.) 
or  800-533-4372  (from  outside  Calif.). 
Please  specify  the  issue  number  and 
format  (MS-DOS,  Macintosh,  Kaypro). 
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Optimization 

Technology 


Code  optimizers  are  one  way  to  take  the 
drudgery  out  of  programming 


If  you  ask  any  programmer  what 
are  the  three  chief  design  goals  of 
his  next  project  he’ll  probably  an¬ 
swer,  “speed,  speed,  and  more 
speed.”  Writing  faster  code  is  some¬ 
thing  we  all  want  to  do,  but  it  usually 
means  a  lot  of  extra,  tedious  work. 
Writing  faster  code  also  requires  the 
hard-won  knowledge  of  the  underly¬ 
ing  architecture  and  in  the  modern  het¬ 
erogeneous  computing  environment, 
it  means  learning  the  internals  of  a 
number  of  different  machines. 

Optimizers,  however,  let  you  create 
faster  code  without  learning  the  inner¬ 
most  secrets  of  a  particular  configura¬ 
tion.  This  article  explains  how  optimiz¬ 
ers  work  and  highlights  some  of  the 
benefits  you  can  expect  from  them. 

What  is  an  Optimizer? 

An  optimizer  is  a  program  that  takes 
as  input  a  code  sequence  and  gener¬ 
ates  a  second  code  sequence  which  is 
identical  in  effect  but  is  more  efficient 
in  its  use  of  memory  space  or  in  its 
execution  time.  In  today’s  machines, 
memory  space  is  a  plentiful  resource, 
so  most  optimizers  concentrate  on  exe¬ 
cution  time.  The  term  “optimizer,”  how¬ 
ever,  can  be  a  misnomer,  because  there 
is  no  guarantee  that  the  resulting  ver¬ 
sion  of  the  code  is  the  fastest  version 
possible. 

In  general,  the  optimizer  examines 
the  input  code  sequence  for  patterns 
of  instructions  that  can  be  replaced 


Keith  is  a  programmer  with  HCR,  and 
he  can  be  reached  at  HCR  Corpora¬ 
tion,  130  Bloor  Street  West,  Toronto, 
Ontario,  Canada  M5S  1N5- 


Keith  Rowe 

with  more  efficient  patterns.  These  re¬ 
placements  are  called  transformations. 
Valid  transformations  must  have  three 
properties:  1.  Transformations  must  be 
correct.  The  resulting  code  sequence 
must  have  the  exact  same  semantics 
as  the  original  program.  2.  Transforma¬ 
tions  must  be  more  efficient.  The  aver¬ 
age  execution  time  of  the  transformed 
program  must  be  faster  than  the  origi¬ 
nal  for  most  cases.  (Note  that  in  some 
cases  some  transformations  may  slow 
down  the  code,  rather  than  speed  it 
up.  The  designer  of  the  optimizer  must 
carefully  examine  such  risky  transfor¬ 
mations  to  see  if  they  are  justified.)  3- 
Transformations  must  be  worth  find¬ 
ing.  Some  transformations  take  a  great 
amount  of  computing  resources  to  un¬ 
cover.  If  the  speedups  they  provide  are 
minimal,  they  may  not  be  worth  the 
effort  — especially  if  the  code  being 
optimized  will  be  run  infrequently  or 
is  still  being  tested  and  changed. 

A  simple  example  of  a  valid  transfor¬ 
mation  is  constant  folding.  Expressions 
which  can  be  seen  to  evaluate  to  a 
constant  value,  are  calculated  during 
optimization  and  replaced  with  the  re¬ 
sult.  For  instance,  a=3+6’5  would  be 
replaced  with  a=33-  This  clearly  has 
the  same  effect  — a  still  has  a  value  of 
33  — and  the  assignment  of  the  value 
directly  saves  an  addition  and  a  multi¬ 
plication  operation  (along  with  some 
register  operations),  so  it  is  more  effi¬ 
cient.  Because  transformations  like  this 
one  are  easy  to  spot  and  they  will  al¬ 
ways  speed  up  the  executing  code, 
they  are  certainly  worth  finding. 

Optimizers  are  closely  associated  with 
compilers.  Optimization  can  be  thought 


of  as  an  additional  pass  (or  in  some 
cases  passes)  the  compiler  makes  to 
improve  the  code.  This  pass  may  occur 
between  parsing  and  code  generation 
passes  or  after  code  generation,  de¬ 
pending  on  the  type  of  optimization 
being  performed. 

The  most  obvious  reason  to  use  an 
optimizer  is  to  create  faster  code.  The 
optimized  executable  performs  the  same 
task  in  fewer  cycles  and  thus  increases 
the  throughput  of  the  machine.  In  a 
way,  this  is  like  buying  a  cheap  form 
of  “upgrade”  for  your  system  — more 
gets  done  on  the  same  machine  with¬ 
out  spending  a  lot  of  money  on  new 
hardware.  Beyond  the  obvious  speed¬ 
up  of  executable  code,  there  are  other 
advantages  to  using  an  optimizer  that 
make  themselves  felt  at  all  points  in  the 
software  development  cycle. 

With  an  optimizer,  much  of  the  often 
tedious  work  of  code  tweaking  is  done 
automatically  and  with  greater  consis¬ 
tency.  Note  that  automatic  optimiza¬ 
tion  is  unlikely  to  be  more  efficient 
than  exquisitely  hand-tuned  code,  but 
it  requires  far  less  work  from  the  pro¬ 
grammer  to  produce  a  similar  result. 
Also,  no  optimizer  will  automatically 
replace  a  bubble  sort  with  a  quick  sort  — 
the  responsibility  of  selecting  an  ap¬ 
propriate  algorithm  still  rests  firmly  with 
the  programmer. 

Optimizers  also  allow  code  to  be 
more  readable  and  more  portable.  Most 
programmers  have  seen  code  that  has 
had  to  do  such  unusual  things  to  run 
faster  that  the  functionality  of  the  code 
is  almost  impossible  to  fathom.  An  op¬ 
timizer  can  do  many  of  these  rewrites 
during  compilation  of  the  code,  which 
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means  the  programmer  can  concen¬ 
trate  on  making  the  algorithm  clear  and 
the  logic  clean,  which  improves  code 
maintainability.  Similarly,  many  machine- 
specific  “tricks”  to  improve  code  can 
be  kept  in  the  optimizer  so  that  the 
original  source  code  can  be  more  eas¬ 
ily  ported. 

Finally,  optimizers  allow  hardware 
designers  to  produce  more  efficient  ar¬ 
chitectures.  RISC  machines  like  the  MIPS 
and  the  IBM  RT  rely  on  the  fact  that 
they  have  optimizing  compilers  to  en¬ 
sure  that  the  machine  code  that  they 
execute  takes  full  advantage  of  their 
unique  architectural  features  and  avoids 
their  areas  of  weakness  as  much  as 
possible. 

Global  and  Local  Optimization 

Optimizers  can  be  designed  to  look  for 
transformations  at  two  main  levels: 
global  and  local.  Global  optimization 
seeks  to  modify  the  source  code  (or  the 
compiler’s  intermediate  representation 
of  it)  to  find  transformations  that  are 
apparent  only  when  a  function  is  ex¬ 
amined  as  a  whole,  whereas  local  optimi¬ 
zation  usually  operates  on  small  pieces 
of  assembly  code  to  find  improvements 
of  a  more  immediate  nature. 

A  great  number  of  profitable  trans¬ 
formations  can  be  made  by  looking 
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only  at  small  pieces  of  assembly  code 
without  needing  to  understand  the  pro¬ 
gram  as  a  whole.  Programs  that  find 
these  localized,  low-level  transforma¬ 
tions  are  called  peephole  optimizers 
or  sometimes  just  peepholers. 

Figure  1  shows  two  typical  code  se¬ 
quences  (in  IBM  RT  assembly  code) 
and  their  replacements.  In  the  first  case, 

The  most  obvious  reason 
to  use  an  optimizer  is 
to  create  faster  code 


an  unconditional  branch  is  made  to 
the  immediately  following  line.  This 
commonly  occurs  when  a  compiler  is 
creating  jump  tables  and  can  be  elimi¬ 
nated.  The  removal  of  the  branch  in¬ 
struction  is  correct,  more  efficient  and 
trivial  to  find,  and  making  it  an  ideal 
transformation. 

In  the  second  case,  register  0  is  spilled 
out  to  memory  and  this  memory  loca¬ 
tion  is  immediately  reloaded  into  regis¬ 
ter  1.  Like  most  machines,  memory  ac¬ 


cesses  are  slower  than  register  trans¬ 
fers  on  the  RT.  It  is  therefore  appropri¬ 
ate  to  replace  the  regular  load  with  a 
register  load. 

Notice  that  in  both  cases  finding  the 
transformations  did  not  require  any¬ 
thing  more  than  looking  at  the  immedi¬ 
ately  surrounding  code.  Peepholers  do 
not  need  to  do  a  lot  of  analysis  and  so 
they  can  be  quite  quick.  In  general,  a 
peepholer  makes  the  compiler’s  job 
much  easier  because  the  compiler 
doesn’t  need  to  keep  excessive  state 
information. 

There  is  a  much  larger  class  of  trans¬ 
formations  that  can  be  found  only  when 
an  entire  function  is  examined  at  one 
time.  Global  optimizers  can  find  these 
high-level  transformations  by  analyz¬ 
ing  the  semantic  content  of  a  given 
function.  Constant  folding  is  an  exam¬ 
ple  of  a  global  optimization. 

Global  optimizers  can  be  designed 
to  work  directly  with  the  source  code, 
some  intermediate  representation  pro¬ 
duced  by  the  compiler,  the  assembly 
code,  or  even  the  assembly  output.  If 
you  choose  to  work  with  the  assembly 
code,  a  great  deal  of  the  high-level 
semantic  content  is  obscured,  but  work¬ 
ing  directly  with  the  source  code  re¬ 
quires  a  parsing  and  analysis  phase 
similar  to  standard  compilation.  The 
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optimizer  I  work  with  (HCR’s  Portable 
Code  Optimizer,  PCO)  takes  the  inter¬ 
mediate  code  from  the  first  pass  of  the 
compiler  and  generates  an  optimized 
intermediate  code  representation,  which 
can  be  sent  on  to  the  second  pass  for 
code  generation.  Because  this  interme¬ 
diate  code  is  semantically  similar  to 
source  code,  but  is  in  a  more  easily 
analyzable  format,  PCO  has  the  advan¬ 
tage  of  being  able  to  work  at  a  source 
code  level  without  the  overhead  usu¬ 
ally  associated  with  it. 

There  are  a  number  of  differences 
in  the  use  of  global  and  peephole  op¬ 
timizers.  Peepholers  execute  quickly 
but  global  optimizers,  which  need  to 
do  a  more  complete  analysis  of  the 
code,  tend  to  take  much  longer.  This 
makes  global  optimization  something 
best  left  undone  during  the  iterative  test 
and  debug  cycle  of  program  development. 

A  Closer  Look  at  Global  Optimization 

There  are  quite  a  few  transformations 
that  can  be  made  by  a  global  optimizer 
and,  depending  on  the  architecture  of 
the  machine,  some  may  be  done  and 
others  may  not.  As  an  example  of  the 
kind  of  transformations  that  a  global 
optimizer  can  perform,  let’s  look  at  two 
functions  from  a  typical  piece  of  C  code 
shown  in  Example  1.  This  code  sets  the 
first  five  values  of  array  a  to  a  value. 
One  interesting  feature  of  the  calcula¬ 
tion  of  the  value  is  that  the  division  is 
kept  as  a  separate  function  that  checks 
the  divisor  and  issues  an  error  message 
if  it  is  zero.  Although,  this  example  will 
show  the  results  of  intermediate  steps 
in  C  code,  you  should  remember  that 
all  the  transformations  occur  in  the  op¬ 
timizer,  in  its  own  internal  represen¬ 
tation. 

The  first  transformation  performed 
is  inlining.  If  a  function  is  very  short 
and  is  called  in  only  a  few  places  it  may 
be  worthwhile  to  write  out  the  whole 
function  wherever  it  is  called,  and  thus 
save  the  overhead  of  the  function  call. 
(C++  provides  in  lining  as  a  standard 
part  of  the  language,  but  C  does  not, 
so  an  optimizer  is  needed  to  make  this 
change.)  Example  2  shows  a  version 
of  the  code  with  testDiv  inlined. 

The  decision  to  perform  inlining  in¬ 
volves  many  factors.  Because  the  func¬ 
tion  is  short  it  will  not  expand  the  size 
of  the  executable  to  a  great  degree. 
The  saving  of  one  function  call  would 
not  be  that  important  but  in  this  case  it 
is  within  a  loop.  Any  saving  inside  a 
loop  is  magnified  by  the  number  of 
times  the  loop  repeats.  In  this  case, 
inlining  is  a  profitable  transformation 
but  the  breakpoint,  where  it  becomes 
unprofitable,  depends  to  a  great  de¬ 
gree  on  the  underlying  architecture. 


Finding  this  breakpoint  is  part  of  the 
tuning  that  takes  place  when  an  op¬ 
timizer  is  designed. 

The  second  transformation  involves 
constant  propagation  and  constant  fold¬ 
ing.  The  use  of  immediate  values  is 
more  efficient  than  accessing  memory, 
and  any  expression  that  can  be  evalu¬ 
ated  at  compile  time  will  save  cycles 
at  runtime.  Thus,  it  is  important  to  find 
all  the  places  in  the  code  where  values 
can  be  predicted.  A  flow  analysis  of  the 
variables  in  a  piece  of  code  can  show 
where  they  are  set  and  reset.  In  our 
example,  x  and  n  are  set  at  the  begin¬ 


ning  and  never  changed  — they  act  as 
constants.  Thus,  the  optimizer  can  propa¬ 
gate  the  constant  value  of  these  vari¬ 
ables  to  every  place  they  are  used.  The 


Original  Code 

Replacement 

b  L.16 

L.16:  ... 

L.16:  ... 

stO,  16(14) 

11,  16(14) 

stO,  16(14) 

Ir  1, 0 

Figure  1:  Two  code  sequences  and 
their  respective  optimized  replacements 


Example  1:  Sample  code  before  optimization 


Example  2:  Same  code  as  in  Example  1  but  with  function  testDiv  inlined 


Example  3:  The  replacement  of  n  in  the  if  statement  makes  the  conditional 
a  constant  to  make  dead-code  elimination  optimization  possible 
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value  of  i  cannot  be  predicted,  so  it 
must  remain. 

Notice  that  when  jcand  n  are  replaced 
with  their  values  we  get  the  expression 
temp=5/2.  Here  is  another  opportunity 
for  constant  folding.  Constant  propaga¬ 
tion  and  constant  folding  often  have 
this  kind  of  interdependence  between 
them.  Each  transformation  may  pro¬ 
vide  opportunities  for  other  transfor¬ 
mations  that  did  not  exist  before. 

For  example,  the  replacement  of  n 
in  the  if  statement  (Example  3)  makes 
the  conditional  a  constant,  which  al¬ 
lows  us  to  make  another  valuable  trans¬ 
formation  — dead  code  elimination.  The 
code  in  the  else  branch  of  the  statement 
is  now  unnecessary  and  so  it  and  the 
(/statement  can  be  removed.  Dead  code 
elimination  wins  on  two  counts:  it  re¬ 
duces  the  size  of  the  executable  and  it 
saves  performing  an  expensive  test  and 
branch  operation. 

After  eliminating  the  dead  code  the 
value  of  temp  won’t  change  inside  the 
loop  and  so  its  value  can  be  propa¬ 
gated  into  the  next  statement  leaving 
us  with  the  code  in  Example  4. 

Now  we  have  an  expression,  2+/', 
which  can’t  be  folded  because  the  value 
of  j  cannot  be  predicted,  but  still  it  is 
wasteful  to  repeatedly  evaluate  it  every 
time  the  loop  executes  because  its  value 
will  not  change.  An  optimizer  can  move 
blocks  of  code  like  this  outside  the  loop 
using  a  transformation  called  loop  invari¬ 
ant  code  motion.  In  this  instance,  the 
profit  gained  by  the  transformation  may 
be  marginal  and  the  replacement  may 
not  have  taken  place  at  all  if  the  op¬ 
timizer  had  been  tuned  differently,  but 
in  general,  code  motion  is  an  important 
source  of  increased  code  efficiency. 

At  last  we  have  the  code  in  Example 
5.  Although  both  Example  1  and  5  have 


Example  4:  The  code  in  Example  3 
after  dead  code  has  been  eliminated 


Example  5:  Both  Example  2  and  5 
have  the  same  net  result,  the  number 
of  instructions  the  code  executes  im¬ 
proves  by  21  percent 


the  same  net  result,  the  number  of  as¬ 
sembler  instructions  the  code  executes 
on  an  IBM  RT  drops  from  156  to  122,  an 
improvement  of  21  percent.  Note  that 
instruction  counts  do  not  give  an  exact 
representation  of  the  improvement  be¬ 
cause  the  timing  of  the  instructions  must 
also  be  considered,  but  on  the  RT  most 
instructions  are  identical  in  execution 
time.  This  code  is  representative  of  the 
kind  of  improvement  that  can  be  ex¬ 
pected  with  global  optimization. 

Implementing  a  Global  Optimizer 

Global  optimizers  are  large  and  com¬ 
plicated  pieces  of  code.  (The  PCO,  for 
instance,  is  half  again  as  large  as  the 
rest  of  the  compiler  with  which  it 
works.)  This  is  reasonable  because  the 
understanding  of  the  code  required  for 
optimization  is  much  greater  than  for 


Figure  2:  Translating  code  into  a 
flow  graph 


for  (i  =  1;  i  <  5;  i++)  { 

a  =  b  +  i ; 

d  =  a  *  4 ; 

if  (  d<e  )  ( 

b— ; 

i 

}  in:  b 

a  =  5  *  b; 

b++; 

a  <  7 

/  out:  a  \ 

in:a  /  \ 

in:  a 

c'2:  I 

c  =  3; 

out:  a.c  \  / 

out:  a,c 

\  in:  a,c  f 

d  »  2  +  a; 

|  out:  c.d 

T 

•  in:  c,d 

Figure  3'  A  data  flow  graph  created 
for  live  variable  analysis 


compilation.  Rather  than  trying  to  un¬ 
derstand  all  of  this  code,  let’s  focus  on 
a  few  of  the  principal  data  structures 
and  show  how  they  are  used  to  find 
optimizing  transformations. 

The  first  step  in  analyzing  the  code 
is  to  break  it  into  basic  blocks.  A  basic 
block  is  a  sequence  of  instructions  that 
execute  without  any  transfer  of  control 
occurring  within  the  block.  Most  of  the 
work  of  the  optimizer  is  performed  on 
these  blocks  or  on  structures  built  up 
from  them.  Basic  blocks  are  used  to 
create  a  flow  graph,  which  adds  the 
flow  of  control  information  to  the  set 
of  basic  blocks.  Each  block  is  a  node 
in  the  graph  with  each  directed  arc 
representing  a  possible  transfer  of  con¬ 
trol  from  one  block  to  another.  Figure 
2  shows  the  translation  of  a  typical 
piece  of  code  into  a  flow  graph.  Notice 
how  the  use  of  loops  and  if  statements 
both  effect  the  flow  of  control.  Flow 
graphs  are  a  much  easier  representa¬ 
tion  to  work  with  because  the  power¬ 
ful  techniques  of  graph  theory  can  be 
used  to  analyze  the  relationships  be¬ 
tween  the  various  nodes  (or  in  this 
case,  basic  blocks). 

For  example,  the  problem  of  finding 
a  loop  in  the  code  is  translated  to  find¬ 
ing  a  strongly  connected  subgraph  (a 
subset  of  nodes  in  the  graph  such  that 
each  node  in  the  set  can  reach  all  other 
nodes  in  the  subset)  with  a  unique 
entry  point.  Although  this  doesn’t  sound 
easier,  it  is  well-defined  mathematically, 
and  graph  theory  provides  algorithms 
to  find  such  a  subgraph. 

An  important  extension  of  the  flow 
graph  is  the  data  flow  graph.  A  data 
flow  graph  is  created  by  taking  a  flow 
graph  and  adding  information  about 
the  variable  usage  to  each  node.  The 
information  added  varies,  depending 
on  the  use  the  data  flow  graph  is  put 
to,  but  the  information  is  usually  one 
or  more  sets  of  variable  names  added 
to  each  of  the  blocks. 

Dead  code  elimination  uses  a  type 
of  data  flow  analysis  called  live  vari¬ 
able  analysis.  If  a  variable  is  defined 
(appears  on  the  left  hand  side  of  an 
assignment)  and  is  not  used  subse¬ 
quently,  the  defining  statement  can  be 
eliminated.  Because  all  the  statements 
in  a  basic  block  occur  in  sequential 
order,  it  is  fairly  easy  to  detect  these 
cases  within  a  single  block.  However, 
what  if  the  variable  is  used  in  a  later 
piece  of  code?  Detecting  this  case  re¬ 
quires  a  complete  analysis  of  the  use 
and  definition  patterns  of  the  code  and 
data  flow  analysis  becomes  essential. 

In  live-variable  analysis,  each  of  the 
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blocks  in  the  flow  graph  has  two  sets  of 
variable  names:  in  and  out.  A  variable 
is  considered  to  be  live  in  a  block  if  it 
is  a  member  of  the  out  set  of  the  block. 
The  out  set  of  a  block  is  the  union  of 
all  the  in  sets  of  the  block’s  successors. 
The  in  set  of  a  block  contains  all  the 
variable  names  used  in  an  expression 
in  the  block,  as  well  as  all  the  names 
in  the  outset  that  are  not  defined  in  the 
block.  The  last  definition  of  a  variable 
in  a  block  can  be  eliminated  as  dead 
code  if  the  variable  name  does  not 
appear  in  the  out  set  of  the  block. 

Figure  3  shows  a  data  flow  graph 
created  for  live  variable  analysis.  If  you 
imagine  that  the  variables  c  and  d  are 
used  in  a  later  piece  of  code,  the  in  and 
out  sets  will  be  as  shown.  The  bottom 
block  has  the  same  in  set  as  its  succes¬ 
sor’s  out  set  but  adds  an  a  to  the  in  set 
to  reflect  its  use  in  that  block.  The 
middle  two  blocks  both  remove  the  c 
from  their  in  sets,  because  the  c  is 
defined  in  those  blocks.  The  top  block 
is  of  particular  interest,  because  the  defi¬ 
nition  of  b  occurs  and  there  is  no  entry 
for  it  in  the  out  set.  Thus,  the  line  b++;  is 
dead  code  and  can  be  eliminated.  Other 
forms  of  data  flow  analysis  are  used  to 
perform  loop  invariant  code  detection, 
copy  propagation,  and  some  types  of 
common  subexpression  removal. 

The  structures  discussed  so  far  are 
used  to  analyze  large  pieces  of  the 
code.  Many  transformations  can  be 
found  within  individual  basic  blocks 
and  another  data  structure:  The  directed 
acyclic  graph  is  used  in  this  case.  A 
directed  acyclic  graph  (a  dag)  is  a  data 
structure  where  each  node  represents 
either  a  variable  or  an  operator.  Each 
operator  node  will  have  pointers  to 
other  nodes  to  represent  the  operands. 


Figure  4:  A  typical  directed  acyclic 
graph  (“dag”) 


The  dag  is  constructed  in  such  a  way 
that  no  circular  references  will  ever 
appear.  A  dag  does  not  model  control 
flow,  so  it  is  perfect  to  form  a  more 
easily  analyzed  representation  of  the 
basic  block. 

A  dag  starts  with  a  collection  of  leaf 
nodes,  one  for  each  variable  used  in 
the  block.  The  statements  in  the  block 
are  examined  one  at  a  time  and  for 
each  operator,  a  node  is  created.  The 
children  of  this  node  are  the  leaf  nodes 
of  the  variables  that  are  the  operands. 
If  the  result  of  the  operation  is  stored 
in  a  variable,  the  node  is  labelled  with 
the  variable’s  name.  The  next  time  this 
variable  is  used,  the  new  node  points 
at  this  operator  node  rather  than  the 
original  leaf  node.  If  a  node  to  be  added 
has  identical  children  and  an  identical 
operator,  it  is  not  added  to  the  dag,  but 
the  variable  it  is  assigned  to  is  added 
to  the  variable  list  of  the  existing  node. 
Figure  4  shows  a  dag  created  for  a 
typical  instruction  sequence.  The  sec¬ 
ond  use  of  d  uses  the  same  leaf  node, 
but  the  second  use  of  b  does  not  be¬ 
cause  it  has  been  used  to  label  the  '+’ 
operator  node. 

One  use  of  the  dag  is  to  assist  in 
dead  code  elimination.  If  a  node  has 
no  parents,  the  variable  it  is  labelled 
with  has  the  value  of  the  tree  under  it 
when  the  block  completes.  When  we 
know  this  variable  is  dead  (using  the 
data-flow  analysis  techniques  shown 
above)  then  this  node  can  be  elimi¬ 
nated.  This  in  turn  may  leave  other 
nodes  without  parents  and  expose  them 
to  similar  elimination.  Looking  again 
at  Figure  4,  if  c  is  dead  in  the  following 
block,  the  7’  node  can  be  removed. 
This  leaves  the  '+’  node  without  a  par¬ 
ent,  and  if  b  is  also  dead  it  can  now  be 
removed,  thus  cascading  the  dead  code 
elimination.  Dags  are  also  used  for  most 
other  transformations  that  occur  within 
a  block. 

Performance 

To  demonstrate  the  kind  of  ^peedups 
that  the  average  user  can  expect  when 
using  a  good  optimizer,  1  have  done  a 
few  brief  experiments.  Like  all  bench¬ 
marking,  these  tests  should  be  taken 
with  a  grain  of  salt,  but  they  do  give 
an  idea  of  the  range  of  performance 


Program 

No  Opt. 

Optimized 

Speed-up 

Dhrystone  (dhry/s) 

4838 

8474 

75% 

grep  (s) 

18.74 

15.88 

18% 

sort  (s) 

38.56 

33.6 

14% 

yacc  (s) 

14.95 

12.19 

22% 

Table  1:  Performance  results  with  and  without  optimization 
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improvement  available.  As  I  said  be¬ 
fore,  optimization  is  machine  specific. 
Some  machines  provide  more  latitude 
for  improvements  than  others.  As  the 
car  makers  say  “your  mileage  may  vary.” 

The  benchmarks  were  done  on  an 
IBM  RT,  model  115,  with  an  AFP  card 
installed.  This  RT  was  running  Version 
2.2.1  of  AIX  and  used  the  standard  cc 
compiler.  (This  compiler  includes  a  “per¬ 
form  optimization”  option,  which  in¬ 
vokes  PCO  as  a  global  optimizer  and 
IBM’s  copt  as  a  peepholer.) 

The  first  test  was  to  compile  and 
execute  the  standard  Dhrystone  bench¬ 
mark  with  and  without  optimization. 
Because  many  of  the  statements  in  the 
benchmark  have  no  effect,  the  global 
optimizer  can  perform  a  great  deal  of 
dead  code  elimination  and  thus  the 
Dhrystone/second  rating  increases  by 
about  75  percent  (see  Table  1). 

To  get  a  better  feel  for  what  happens 
to  real  code,  I  took  source  for  the  com¬ 
mon  Unix  utilities  grep,  sort,  and  yacc, 
compiled  them  with  and  without  opti¬ 
mization  and  set  them  to  large  tasks. 
Although  none  of  these  utilities  are  per¬ 
fect,  they  do  represent  better  than  aver¬ 
age  attempts  at  writing  fast  code. 

grep  was  asked  to  search  a  2.5-Mbyte 
on-line  dictionary  for  a  particular  word 
pattern.  The  optimized  version  ran  18 
percent  faster  over  10  tries,  sort  was 
asked  to  put  a  smaller  on-line  diction¬ 
ary  into  reverse  alphabetic  order.  Here 
the  speedup  was  14  percent,  yacc  was 
given  a  C  grammar  and  asked  to  gener¬ 
ate  a  parser  for  it.  In  this  case  the 
speedup  was  22  percent. 

Conclusion 

Optimizers  have  proven  to  be  a  valu¬ 
able  tool  for  the  software  developer. 
They  help  remove  the  drudgery  of  writ¬ 
ing  efficient  code,  allow  the  code  to 
be  more  readable  and  portable,  and 
even  in  tight  code,  they  can  find  sig¬ 
nificant  improvements.  Still,  they  can 
only  do  so  much,  and  the  most  intel¬ 
lectually  challenging  part  of  crea¬ 
ting  fast  code,  the  design  of  good 
algorithms,  will  remain  with  the  pro¬ 
grammer. 

Further  Reading 

For  a  more  complete  explanation  of 
optimization  techniques  and  their  im¬ 
plementation  look  for  Compilers,  Prin¬ 
ciples,  Techniques,  and  Tools,  Aho, 
Sethi,  and  Ullman  (Addison-Wesley, 
1986)  or  Crafting  a  Compiler,  Fischer, 
LeBlanc  (Benjamin/Cummings,  1988). 
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Writing  AWK-like 
Extensions  to  C 


When  neither  AWK  nor  C  can  do  the  job, 
try  a  combination  of  the  two 


.  im  Mischel 


The  process  of  string  searching 
is  an  important  part  of  many 
computer  applications.  Text  edi¬ 
tors,  database  managers,  spread¬ 
sheet  programs,  and  countless 
utility  programs  use  string  searching 
to  one  degree  or  another.  Unfortunately, 
other  than  the  common  case-insensi¬ 
tive  search,  most  programs  require  that 
the  search  string  be  specified  exactly. 
Very  few  programs  allow  a  search  oh 
strings  that  are  described  by  such  infor¬ 
mation  as  “all  strings  that  begin  with  a 
capital  letter,  contain  at  least  one  digit, 
and  end  with  a  period.”  This  restriction 
isn’t  very  surprising,  considering  the 
inadequacy  of  the  string  search  func¬ 
tions  in  most  popular  languages. 

The  AWK  programming  language  is 
unique  with  respect  to  string  search 
functions.  Along  with  many  other  in¬ 
teresting  features,  AWK  contains  the 
facilities  to  search  a  string  for  substrings 
that  match  a  regular  expression  (see  the 
accompanying  sidebar  on  regular  ex¬ 
pressions).  AWK  is  a  fantastic  tool  for 
in-house  use,  but  there  are  drawbacks 
to  using  it  for  commercial  software  de¬ 
velopment.  First,  AWK  is  interpreted, 
which  makes  its  programs  execute  more 
slowly  than  compiled  code.  In  addi¬ 
tion,  the  interpreter  is  an  extra-cost  item 
that  must  be  included  in  order  for  the 
program  to  run.  Second,  AWK  provides 


Jim  Mischel  is  a  former  financial  sys¬ 
tems  programmer  and  database  con¬ 
sultant.  He  can  be  reached  at  20  Ste¬ 
wart  St.,  Durango,  CO  81301  or  on 
CompuServe:  73  71 7, 1355. 


little  access  to  either  the  operating  sys¬ 
tem  or  the  underlying  hardware.  In  the 
following  discussion,  some  familiarity 
with  the  AWK  programming  language 
will  be  helpful,  but  is  not  required. 

AWK's  Functions 

AWK  is  designed  around  an  implicit 
processing  loop  that  automatically  reads 
each  input  record,  splits  the  record  into 
fields,  and  then  performs  programmer- 
specified  actions  upon  the  record.  AWK 
also  provides  global  variables  that  con¬ 
tain  several  bits  of  information  about 
program  status:  the  number  of  records 
read,  fields  in  the  current  record,  and 
so  on.  This  functionality  can  be  nearly 
duplicated  in  C  by  means  of  a  simple 
controlling  loop  and  the  AWKLIB  get- 
line( )  function,  as  shown  in  the 
QSTRING.C  program  in  Listing  One, 
page  94.  (getlineC )  and  the  other 
AWKLIB  functions  are  declared  in  the 
header  file  AWKLIB. H,  which  is  shown 
in  Listing  Two,  page  94.  AWKLIB. H 
must  be  included  in  any  program  that 
uses  AWKLIB.) 

The  awk_init( )  function,  which  must 
be  called  before  any  of  the  other  rou¬ 
tines  are  used,  initializes  the  AWKLIB 
global  variables.  Failure  to  call  this  func¬ 
tion  may  produce  some  interesting  (and 
probably  erroneous)  results. 

getlineC )  has  the  same  calling  se¬ 
quence  as  fgets( )  but  returns  EOF  on 
end-of-file  or  error,  rather  than  return¬ 
ing  NULL.  (This  change  in  return  val¬ 
ues  was  a  purely  selfish  design  deci¬ 
sion  on  my  part.)  getlineC )  reads  the 
next  input  record  (line)  into  memory, 


splits  that  record  into  fields  on  the  global 
field  separator  FS  (discussed  later), 
stores  the  fields  in  the  FIELDSl 1  array, 
and  updates  the  field  counter  (NF). 
Unlike  AWK  routines,  these  C  routines 
do  not  allow  the  record  separator  to 
be  changed,  and  they  assume  that  the 
record  separator  is  a  newline  \  n. 

The  matchC )  function  searches  the 
supplied  string  for  substrings  that  match 
the  supplied  regular  expression.  This 
function  returns  a  pointer  to  the  begin¬ 
ning  of  the  matched  substring,  or  else 
returns  NULL  if  no  match  is  found. 
matchC )  also  updates  the  RSTART  and 
RLENGTH  variables.  The  following  ex¬ 
ample  returns  a  pointer  to  the  s  in  she. 

char  *C; 

c  =  match  (“We  followed  wherever 
she  went”,  “s?he”); 

In  this  example,  RSTART  is  22  and 
RLENGTH  is  3. 

The  functions  subC )  and  gsubC )  pro¬ 
vide  string  substitution  capabilities.  subC ) 
substitutes  the  replacement  string  for  the 
first  occurrence  of  a  specified  substring, 
and  gsubC )  performs  the  substitution 
for  every  occurrence  of  the  substring. 
Both  of  these  functions  return  the  num¬ 
ber  of  substitutions  that  were  made. 
For  example,  the  following  returns  1, 
and  s  reads  “William  took  Bill’s  book.” 

char  s[80]  =  “Will  took  Bill’s  book”;, 

sub  (“[WBJill”,  “William”,  s); 

The  next  line  then  returns  2,  and  s 
reads  “William  took  William’s  book:” 


64 


Dr.  Dobb’s Journal,  June  1989 
397 


gsub  (“[WB]ill”,  “William”,  s); 

Notice  that  gsub( )  makes  only  one  pass 
through  the  string,  and  it  doesn't  try  to 
substitute  strings  that  have  already  been 
substituted  (which  is  a  good  thing,  be¬ 
cause  such  a  step  would  send  the  above 
example  an  infinite  loop). 

Both  sub!  )  and  gsub(  )  allow  you 
to  use  the  operator  to  reference  the 
matched  substring  in  the  replacement 
string.  The  following  example  appends 
“ed”  to  occurences  of  the  word  “want” 
in  a  sentence  by  modifying  sto  read  “I 
wanted  to  go  home!” 

char  s[80]  =  “I  want  to  go  home!”; 

gsub  (“[Wwlant”,  "&ed”,  s); 

In  order  to  include  the  character 
literally  in  a  string,  preceed  that  charac¬ 
ter  with  the  escape  character.  The  fol¬ 
lowing  code  modifies  s  to  read  “I  &ed 
to  go  home!” 

gsub  ("[Wwlant”,  “\  died”,  s); 

Neither  sub(  )  nor  gsub(  )  affect  any  of 
the  global  variables. 

The  split(  )  function  allows  you  to 
split  a  record  into  fields  on  a  specified 
field  separator,  which  can  be  any  regu¬ 
lar  expression.  (The  global  field  sepa¬ 
rator,  FS,  defaults  to  “[  \  t]+,”  which 
means  “one  or  more  spaces  or  tabs.” 
FS  may  be  changed  by  using  the  setfs!  ) 
function.)  The  function  getline!  )  uses 
split!  )  and  the  global  field  separator 
in  order  to  split  input  lines  into  the 
FIELDS[] array,  split (  Jean  also  be  called 
by  the  application  program,  which  may 
specify  its  own  fields  array  or  else  use 
the  global  FIELDS,  split! )  updates  NF 
and  then  returns  NF.  The  following 
example  sets  NF  to  4  and  returns  4-. 


The  Functions  at  Work 

The  AWKLIB  routines  (Listing  Three, 
page  94)  are  divided  into  three  groups: 

1.  the  compiler  Imakepat! )  and  re¬ 
lated  functions) 

2.  the  interpreter  (  match]  )  and  related 
functions) 

3.  the  user  interface  {match!  ),  split! ), 
sub!  ),  gsub! ),  and  their  re_.  .  .  alter¬ 
nates). 

The  compiler  is  based  upon  a  simple 
recursive-descent  design.  (Because  this 
article  is  not  about  compilers,  I  won’t 


char  *a[128];  /*  enough  room  for  127 

fields  V 

split  (“Will::tOok:Bill’S:book.”,  a,  “:+”); 

In  this  example,  the  a[]  array  is: 

a[0]  -  “Will::took:Bill’s:book.” 

all]  -  “Will” 

a[2]  -  “took” 

a[31  -  “Bill’s” 

a[4]  -  “book." 


Note  that  the  first  element  of  the  array 
always  contains  the  unmodified  string. 
When  calling  split! ),  make  sure  that 
the  fields  array  contains  enough  spaces 
for  all  of  the  fields  in  the  record.  Failure 
to  include  enough  spaces  will  crash 
the  program  because  split! )  handles 
allocation  of  memory  for  each  field  but 
cannot  allocate  memory  for  more  fields. 


cover  the  compiler  specifics.)  For  more 
information  on  how  compilers  are  built, 
consult  the  references  listed  at  the  end 
of  this  article.  Input  to  the  compiler 
consists  of  a  human-readable  regular 
expression.  The  compiler  outputs  the 
regular  expression  in  prefix  form,  which 
is  used  more  easily  by  the  matching 
functions.  The  compiled  form  is  very 
much  like  the  form  presented  in  Ker- 
nighan  and  Plauger’s  Software  Tools 
in  Pascal  (which,  by  the  way,  is  an 
excellent  book). 

The  simplest  form  of  regular  expres¬ 
sion,  which  is  a  literal  character  such 
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as  “a,”  is  compiled  into  an  expression 
such  as  “cae,”  which  means  “Match 
literal  character  ‘a’  and  then  end.”  A 
string  literal  is  compiled  into  a  series 
of  literal  characters.  For  example,  “hi” 
becomes  “chcie.”  The  way  that  the  in¬ 
terpreter  handles  this  process  will  be 
discussed  shortly. 

The  process  of  compiling  character 
classes  is  also  fairly  simple.  A  compiled 
character  class  is  represented  simply 
by  a  “["  (or  “]”  if  the  character  class  is 
negated),  followed  by  a  count  of  char¬ 
acters,  followed  by  the  characters  them¬ 
selves.  For  example,  the  character  class 
“[0-9A-Fa-f],”  which  specifies  a  hexa¬ 
decimal  digit,  is  represented  by 
“['22’0123456789ABCDEFabcdefe.”Note 
that  the  22  is  a  single  byte  value,  chr(22). 

(This  encoding  scheme  restricts  the 
lengths  of  character  classes  and  clo¬ 
sure  expressions  — neither  may  be 
longer  than  255  characters.  This  restric¬ 
tion  presents  only  a  minor  problem  in 
the  case  of  character  classes  because 
there  are  only  256  character  codes.  Any 
character  class  that  contains  N  charac¬ 
ters  can  be  expressed  as  a  negated 
character  class  of  256-N  characters,  or 
a  maximum  of  128.) 


The  regular  expressions  used  by 
AWK  and  similar  programs  are  de¬ 
rived  from  the  notation  used  in  auto¬ 
mata  theory  to  describe  formal  lan¬ 
guages  and  finite  state  machines. 
Regular  expressions  consist  of  nor¬ 
mal  characters  (operands),  such  as 
“a,”  “0,”  and  plus  meta-charac- 
ters  (operators),  such  as  “+,”  “  ! 
and  “[.”  A  regular  expression,  which 
is  similar  to  familiar  arithmetic  expres¬ 
sions,  can  be  either  a  basic  expres¬ 
sion  or  a  complex  expression  that 
is  formed  by  applying  operators  to 
several  basic  expressions. 

The  regular  expression  meta-charac- 
ters  and  their  uses  are: 

\  The  escape  character  is  used  in 
escape  sequences  to  specify  charac¬ 
ters  which  would  otherwise  have 
no  representation.  These  escape  se¬ 
quences  are  similar  to  those  used 
in  the  C  language: 

\  b  Backspace 
\  t  Horizontal  tab 
\  n  Newline  or  linefeed 
\  f  Newpage  or  formfeed 
\  r  Carriage  return 
\  ddd  Octal  value  “ddd.”  ddd  can 
be  one  to  three  digits  long. 
\  c  “c”  can  be  any  character 
that  is  taken  literally 


This  process  of  handling  alternation 
is  a  little  more  complex.  The  regular 
expression  “a  !  b”  compiles  to 
“  1  caecbee.”  In  this  compiled  expres¬ 
sion,  the  ‘e’s  tell  the  matching  routines 
where  to  stop  scanning.  Alternation  was 
the  last  item  that  I  included  in  my  com¬ 
piler,  and  it  created  some  problems 
that  I  hadn’t  anticipated.  This  operator 
forced  the  inclusion  of  the  end-of-term 
(‘e’)  characters  in  the  compiled  strings. 

The  compiled  form  of  a  closure  is 
much  like  the  compiled  form  of  a  char¬ 
acter  class.  The  compiled  representa¬ 
tion  of  a  closure  consists  of  the  closure 
operator  (?,  *,  or  +),  followed  by  the 
length  of  the  expression,  followed  by 
“e.”  For  example,  “(a  !  b)*”  is  encoded 
as  “*‘7’  I  caecbee.”  Note  again  that  the 
7  actually  is  chr( 7).  With  the  above 
discussion  in  mind,  let’s  take  a  look  at 
how  the  matching  functions  work. 

In  a  real  sense,  the  matching  func¬ 
tions,  starting  with  match _term(  ),  make 
up  an  interpreter  — these  functions  run 
a  program  (the  compiled  regular  ex¬ 
pression)  against  input  data  (the  string 
to  be  searched)  in  order  to  produce 
output  (the  matched  substring).  The 
interpreter  is  based  upon  a  fairly  sim- 


Regular  Expressions 

a  The  carat  matches  the  begin¬ 
ning  of  a  string.  For  example,  “Aa” 
matches  only  those  strings  that  have 
“a”  as  the  first  character.  When  “A” 
is  the  first  character  in  a  character 
class,  the  character  denotes  a  ne¬ 
gated  character  class. 

$  The  dollar  sign  matches  the  end 
of  a  string.  For  example,  “z$”  matches 
only  those  strings  that  have  “z”  as 
the  last  character. 

.  The  period  matches  any  char¬ 
acter.  Be  careful  with  this  one  “.*” 
matches  everything. 

[  The  open  bracket  denotes  the 
beginning  of  a  character  class. 

]  The  closed  bracket  denotes  the 
end  of  a  character  class. 

I  This  character  is  the  alternation 
operator,  “a  !  b”  matches  either  “a” 
or  “b”. 

(  )  Parentheses  are  used  to  group 
expressions  in  much  the  same  man¬ 
ner  in  that  they  are  used  with  arithme¬ 
tic  expressions. 

*  The  closure  operator  matches  0 
or  more  of  the  specified  expression, 
“a*”  matches  a  string  of  0  or  more 
“a”s. 

+  The  plus  sign  indicates  positive 
closure  and  matches  1  or  more  of 
the  specified  expression.  “z+” 
matches  a  string  of  1  or  more  “Z”s. 

?  The  question  mark  matches  0 


pie  design  (thanks  to  the  pre-processing 
done  by  makepat(  J)  and  holds  very 
few  tricks.  In  fact,  the  only  pieces  that 
gave  me  any  real  trouble  were  the  al¬ 
ternation  processing  (“  !  ”  operator)  and 
the  closure  matching. 

The  heart  of  the  interpreter  is  the 
match_term( )  function,  which  deter¬ 
mines  what  is  to  be  matched  and  then, 
depending  upon  the  operator,  either 
attempts  to  match  the  next  character 
or  else  dispatches  to  the  proper  routine 
for  further  processing.  “Further  pro¬ 
cessing”  is  either  a  character  class,  alter¬ 
nation,  or  a  closure  operation. 

Character  classes  are  easy  to  match 
by  using  match_ccl( ),  which  looks  for 
a  match  by  scanning  the  list  of  charac¬ 
ters.  match_ccl( )  then  returns  the 
proper  value,  depending  upon  if  a 
match  was  found  and  whether  that 
match  is  a  negated  character  class. 

Alternation  matching  was  the  most 
difficult  part  for  me  to  implement  cor¬ 
rectly.  There  is  probably  a  better  way 
to  handle  this  step,  but  my  solution 
works  well  and  is  fast  enough  for  my 
purposes.  The  match _or( )  function 
breaks  the  remaining  pattern  into  two 
patterns  (one  pattern  for  each  branch), 


or  1  of  the  specified  expression.  “9?” 
matches  either  the  null  string  or  “9”. 

Character  classes  are  “shorthand” 
for  matching  one  of  several  charac¬ 
ters.  For  example,  [AaBb]  is  the  same 
as  (A  1  a  1  B  !  b)  and  matches  “A,” 
“a,"  “B,”  or  “b.”  There  are  also  char¬ 
acter  ranges,  such  as  [A  -  Z],  which 
match  any  uppercase  alpha  charac¬ 
ter.  Negated  character  classes  act  in 
the  opposite  way,  and  they  specify 
characters  that  should  not  be 
matched.  For  example,  [AA  -  Z] 
matches  everything  except  upper¬ 
case  alpha  characters. 

With  the  above  in  mind,  let’s  exam¬ 
ine  some  regular  expressions. 

“AEa  -  z]$”  matches  any  line  that 
consists  of  only  lowercase  letters. 

“[A  -  Za-z_][A-Za  -  z_0-9]*” 
matches  a  C  variable  anywhere  on 
a  line. 

“(soft  !  loud)  (classical  !  rock  ! 
country)  music”  matches  six  strings 
from  “soft  classical  music”  to  “loud 
country  music.” 

“AE0  -  9].*tA0  -  9l$”  matches  any 
line  that  begins  with  a  digit  and 
doesn’t  end  in  a  digit. 

“80[123l?8[86]  !  680[01234]0” 
matches  any  of  the  more  popular 
microprocessors,  plus  a  few  that 
never  made  it. 


66 


Dr.  Dobb’s Journal,  June  1989 
399 


AW  K-  LIKE  EXTENSIONS 


AWK-LIKE  EXTENSIONS 


(continued  from  page  66) 
searches  both  branches,  and  then  re¬ 
turns  the  longest  substring  that  matched, 
if  any  matches  occurred.  For  example, 
the  match_qr( )  breaks  the  regular  ex¬ 
pression  “(b  !  c)d,”  which  reads"  1  cbec- 
cecde”  when  compiled  into  the  two 
patterns  “cbcde”  and  “cccde,"  and  then 
uses  each  pattern  to  search  the  string. 
The  step  of  splitting  the  patterns  is 
performed  by  the  skip_term( )  function. 

Closure  is  handled  by  generating  the 
longest  possible  substring  that  matches 

Along  with  many  other 
interesting  features, 
AWK  contains  facilities 
to  search  a  string  for 
substrings  that  match 
a  regular  expression 


the  closure  operator,  then  backtrack¬ 
ing  to  discover  where  the  closure  should 
stop  in  order  to  correctly  match  the 
rest  of  the  pattern.  Because  of  the 
amount  of  backtrack  ing  that’s  involved, 
closure  can  become  very  inefficient. 
This  is  especially  true  when  nested  clo¬ 
sure  operators,  such  as  (a*b)*,  are  in¬ 
volved.  Since  closure,  by  definition, 
can  match  a  null  string,  making  this 
process  work  correctly  for  all  cases  was 
a  little  difficult. 

I  had  originally  designed  the 
matcb_closure( )  function  to  return  a 
Boolean  value,  but  ran  into  trouble 
during  testing  when  I  (inadvertently) 
tried  a  pattern  that  contained  a  double 
closure  operator  ((a*)*).  According  to 
the  automata  theory  books,  “(a*)*”  is 
the  same  as  “a*”  — but  my  program 
didn’t  know  that.  Consequently,  match_ 
closureC )  kept  looping  between  the 
failure  of  the  outer  closure  and  the 
success  of  the  inner  closure.  After  spend¬ 
ing  several  fruitless  days  attempting  to 
have  the  compiler  optimize  the  expres¬ 
sions  (which  is  quite  a  bit  more  diffi¬ 
cult  than  it  looks),  I  finally  hit  upon  the 
simple  solution.  Why  not  add  another 
return  to  match _closure( )  to  indicate 
that  the  closure  matches  a  null?  Some¬ 
times  the  simplest  solutions  are  the  most 
difficult  to  come  up  with. 

Using  the  Functions 

The  QSTRING.C  program  (in  Listing 
One)  locates  and  outputs  all  quoted 


strings  into  a  C  source  file.  This  is  the 
first  version  of  a  utility  I’ve  been  work¬ 
ing  on;  although  QSTRING.C  is  primi¬ 
tive,  it  illustrates  the  use  of  the  AWKLIB 
routines. 

The  most  important  point  here  is 
that  awk_init( )  should  always  be  called 
at  the  beginning  of  any  program  that 
uses  the  AWKLIB  functions.  Failure  to 
do  so  will  cause  the  functions  to  act 
erratically. 

The  makepat( )  function  has  been 
provided  so  that  the  program  can  com¬ 
pile  a  regular  expression  and  then  save 
the  compiled  form  of  the  expression 
sfor  later  processing.  The  routines 
re_match( ),  re_sub( ),  re_gsub( ),  and 
re_split( )  use  a  compiled  pattern  in 
lieu  of  a  regular  expression  in  order  to 
speed  processing.  The  two  program 
fragments  shown  in  Example  1  pro¬ 
duce  the  same  output,  but  Program  A 
executes  much  faster  because  it  only 
compiles  the  regular  expression  once. 
In  contrast,  Program  B  compiles  the 
regular  expression  each  time  that 
match(  )is  called.  Typically,  a  program 
will  attempt  to  match  multiple  strings 
against  one  or  two  regular  expressions. 
In  this  case,  the  program  executes  much 
faster  if  the  regular  expressions  are  com¬ 
piled  first  with  makepat( ),  and  then 
re_match( )  (rather  than  matchC  ))  is 
used  inside  the  processing  loop.  This 
increase  in  program  speed  also  holds 
true  with  respect  to  use  of  the  other 
major  functions:  split(  Xuse  re_split( )), 
sub( )  (use  re_sub(  )\  and  gsub( )  (use 
re_gsub(  )). 

Notice  in  the  example  program  that 
gets( ),  rather  than  getline( ),  is  used  to 
read  the  file.  Because  getlineC )  must 
split  the  input  record  into  fields,  it’s 
much  slower  than  gets( ).  Use  getlineC ) 
only  when  the  record  must  be  split  into 
fields  on  every  (or  most)  input  records. 

The  RLENGTH  global  variable  ex¬ 
tracts  the  matched  substring  from  the 
rest  of  the  string  and  updates  the  string 
pointer  for  the  next  match. 


Conclusion 

This  entire  project  has  been  quite  an 
education  in  compilers,  interpreters,  and 
automata  theory.  Construction  of  the 
compiler  was  made  much  easier  by  a 
tutorial  series  on  compiler  design  that 
I  found  in  the  Computer  Language  Fo¬ 
rum  on  CompuServe.  While  attempting 
to  make  the  compiler  optimize  regular 
expressions,  I  had  to  delve  into  auto¬ 
mata  theory  —  and  I  intend  to  pursue 
that  interesting  subject  further. 
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Program  A 

while  (getline (line, 80, f ) 

!=  EOF)  ( 

Program  B 

makepat ("a+bc", pat) ; 

if  (matchdine,  "a+bc") 

=  NULL) 

while  (getline (line, 80, f ) 

!=  EOF)  ( 

puts (line) ; 

if  (re  match (line, pat) 

!«  NULL) 

1 

puts (line) ; 

} 

Example  1:  Program  A  executes  faster  because  it  only  compiles  the  regular 
expression  once,  while  Program  B  compiles  the  regular  expression  each  time 
that  match(  )  is  called. 


68 

400 


Dr.  Dobb’s  fournal,  fune  1989 


Putting  common  TSR  tasks  to  work 


Ken  L.  Pottebaum 


This  is  the  second  part  of  a  two- 
part  article  about  creating  TSR 
(Terminate-and-Stay-Resident) 
programs  with  Turbo  Pascal  5.0 
and  TSRUnit.  The  first  part  dealt 
with  the  inside  workings  of  TSRUnit. 
This  part  focuses  on  how  to  use  TSRUnit 
and  provides  an  example  program.  Al¬ 
though  the  example  program  is  simple, 
it  illustrates  methods  for  accessing  files, 
printing,  inserting  characters  into  the 
keyboard  input  stream,  and  other  use¬ 
ful  tasks.  If  you  missed  the  first  part  of 
the  series,  you  can  still  create  your  own 
TSR  programs  because  the  INTERFACE 
section  of  TSRUnit  (Listing  One,  page 
106)  provides  information  about  how 
to  use  the  unit. 

Using  TSRUnit 

In  order  to  use  TSRUnit,  your  program 
must  provide  a  function  for  TSRUnit  to 
call  when  the  unit  pops  up  and  also 
perform  a  call  to  TSRInstall. 

The  function  that  TSRUnit  calls  when 
it  pops  up  may  have  any  valid  function 
name.  For  simplicity,  I  will  refer  to  this 
function  as  DemoTasks.  {DemoTasks  is 
also  the  name  for  this  function  in  the 
example  program  TSRDemo,  which  is 
discussed  later  in  this  article.)  Demo¬ 
Tasks  must  be  compiled  as  a  far  func¬ 
tion  (without  any  parameters)  that  re¬ 
turns  a  WORD  value.  The  WORD  value 
is  the  number  of  characters  to  be  in¬ 
serted  into  the  keyboard  input  stream. 
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(The  character  insertion  option  is  a  spe¬ 
cial  feature  provided  by  TSRUnit  and 
is  explained  later,  along  with  the  other 
features  illustrated  in  the  example  pro¬ 
gram.)  Generally  speaking,  the  jarfunc- 
tion  can  contain  any  valid  Turbo  Pascal 
statement,  including  calls  to  other  pro¬ 
cedures  and  functions.  Common  sense 
is  important,  however,  when  any  of  the 
routines  from  the  standard  DOS  UNIT 
are  used.  For  example,  it  would  not 
make  sense  to  use  the  Keep  procedure 
because  Keep  has  already  been  used. 
Also,  if  you  use  any  of  the  procedures 
that  change  interrupt  vectors,  be  sure 
to  restore  those  procedures  before  exit¬ 
ing  DemoTasks. 

As  shown  in  Listing  One,  the  call  to 
TSRInstall  requires  four  parameters.  The 
first  parameter  is  a  character  string  that 
contains  the  name  of  the  TSR;  this  name 
is  displayed  when  the  TSR  is  installed. 
The  second  parameter  is  a  procedure- 
type  parameter  that  specifies  the  func¬ 
tion  that  TSRUnit  calls  when  the  TSR  is 
popped  up.  The  last  two  parameters 
specify  the  default  hot  key  combina¬ 
tion  that  is  pressed  in  order  to  pop  up 
the  TSR.  The  first  of  the  hot  key  pa¬ 
rameters  contains  a  byte  code  that  rep¬ 
resents  the  shift  keys  that  must  be 
pressed  while  the  key  for  the  character 
specified  in  the  last  parameter  is  pressed. 
The  shift  key  code  can  be  any  combi¬ 
nation  of  the  following  constants: 
AltKey,  CtrlKey,  LeftKey,  and  RightKey. 
The  constants  stand  for  the  Alt,  Ctrl, 
Left  Shift,  and  Right  Shift  keys,  respec¬ 
tively.  Combinations  of  two  or  more 
shift  keys  may  be  formed  by  using  either 
the  OR  or  +  operators  to  combine  the 
constants.  The  valid  characters  for  the 
last  parameter  are  0-9  and  A  -  Z. 


Example  TSR 

The  example  program,  TSRDEMO. PAS, 
is  shown  in  Listing  Two,  page  106. 
Although  Turbo  Pascal  normally  de¬ 
faults  the  stack  size  to  16K,  the  com¬ 
piler  memory  directive  may  be  used  to 
set  the  stack  and  heap  sizes.  TSRDemo 
uses  the  compiler  directive  to  reduce 
its  memory  requirements  by  specifying 
a  2K  stack  and  no  heap.  To  find  the 
minimum  stack  size  with  which  your 
program  will  work,  simply  run  the  pro¬ 
gram  with  different  stack  sizes.  In 
order  for  the  stack  size  check  to  be 
valid,  test  all  of  the  program’s  features 
(unless  you  already  know  which  fea¬ 
ture  of  the  program  uses  the  most  stack 
space).  If  you  know  the  worst  case,  limit 
the  testing  to  the  worst  case  operations. 
Set  the  stack  size  for  your  program 
slightly  higher  than  the  minimum  size 
for  which  the  program  worked,  in  or¬ 
der  to  allow  for  variations  in  stack  us¬ 
age  that  occur  due  to  differences  in 
versions  of  DOS  and  BIOS  used  and  due 
to  the  presence  of  other  TSR  programs. 
Although  you  can  reduce  memory  usage 
by  specifying  a  stack  that  is  only  as 
large  as  necessary,  do  not  confuse  this 
step  with  avoiding  using  the  stack  alto¬ 
gether  —  the  use  of  the  stack  for  local 
variables  and  for  passing  information 
is  an  efficient  allocation  of  memory. 

When  TSRDemo  is  popped  up,  its 
routine,  DemoTasks,  is  called  from 
TSRUnit.  DemoTasks  creates  a  window 
on  the  screen,  displays  some  instruc¬ 
tions,  and  displays  miscellaneous  in¬ 
formation  about  the  computer  system. 
It  then  echoes  the  keyboard  input  to 
the  screen  until  a  key  that  activates  a 
demonstration  of  one  of  DemoTasks 
special  features  is  pressed.  DemoTasks 
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provides  four  special  features:  file  ac¬ 
cessing,  printing,  accessing  the  saved 
screen  image,  and  inserting  characters. 

File  Accessing 

When  the  FI  key  is  pressed,  the  standard 
file-handling  routines  are  used  to  write 
a  short  message  to  the  TSRDEMO.DAT 
file.  It  is  advisable  to  disable  the  com¬ 
piler  I/O  error-checking  directive,  and 

Although  the  example 
program  is  simple, 
it  illustrates  methods 
for  accessing  files, 
printing,  inserting 
characters  into  the 
keyboard  input  stream, 
and  other  useful  tasks 


to  use  the  lOResult  function  to  check 
for  errors  when  files  are  accessed. 

Printing 

When  F2  is  pressed,  DemoTasks  per¬ 
forms  the  operations  that  are  required 
in  order  to  print  a  short  message.  Pro¬ 
grams  normally  use  the  standard 
PRINTER  unit  to  automatically  assign, 
open,  and  close  the  printer  device.  The 
TSR  installation  process  causes  a  printer 
device  that  was  opened  in  this  fashion 
to  be  closed.  Therefore,  the  TSR  program 
must  treat  the  printer  as  a  normal  file 
device,  and  use  the  Assign,  Rewrite,  and 
Close  procedures  to  open  and  close  it. 

Printing  from  a  TSR  poses  a  special 
hazard.  If  the  TSR  writes  to  the  printer 
when  the  printer  is  not  ready,  an  error 
occurs.  When  the  standard  lOResult  func¬ 
tion  is  used,  the  error  is  reported,  but 
damage  that  may  be  caused  by  the 
error  is  not  prevented.  The  consequence 
of  this  “device  not  ready"  error  is  that 
the  computer  may  crash  when  the  TSR 
is  popped  back  down.  An  easy  way  to 
prevent  this  problem  is  to  always  check 
the  printer  status  before  using  the 
printer.  TSRUnit  provides  two  auxiliary 
functions  for  this  purpose:  PrinterOkay 
and  PrinterStatus.  PrinterOkay  returns 
a  TRUE  value  if  the  printer  is  selected, 
the  printer  has  paper,  and  no  I/O  or 
time-out  error  has  occurred.  Printer- 
Status  returns  the  actual  status  byte  for 
the  printer. 
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Accessing  Saved  Screen  Text 

When  F3  is  pressed,  the  program 
prompts  you  for  the  row  number  of  the 
saved  screen  text  to  be  displayed. 
TSRUnit  provides  the  pointer  TSRScrPtr, 
which  points  to  the  saved  screen  im¬ 
age.  In  addition,  TSRUnit  provides  two 
auxiliary  routines  that  return  the  con¬ 
tents  of  one  row  of  a  text  image.  The 
function  ScreenLineStr  returns  all  of  the 
characters  contained  on  the  line  in  a 
character  string.  The  procedure  Screen- 
Line  returns  an  array  of  records,  where 
each  record  contains  a  character  and 
the  character’s  display  attribute. 

Inserting  Characters 

DemoTasks  fourth  special  feature  is 
the  insertion  of  characters  into  the  key¬ 
board  input  stream.  When  F8  is  pressed, 
you  are  prompted  to  specify  the  char¬ 
acters  to  be  inserted.  After  you  type  the 
characters,  the  TSR  pops  back  down 
and  inserts  them  into  the  keyboard  in¬ 
put  stream.  A  useful  application  of  this 
feature  is  to  insert  a  result  obtained 
from  the  TSR  into  a  spreadsheet  or 
word  processor  program. 

In  order  for  TSRUnit  to  insert  the 
characters,  the  pointer  ISRChrPtr  must 
be  set  to  point  to  the  first  character 
to  be  inserted,  and  the  return  value 
for  DemoTasks  must  be  set  to  the  num¬ 
ber  of  characters.  The  only  restriction 
on  the  number  of  characters  to  be 
inserted  is  that  all  of  the  characters 
must  reside  in  the  same  64K  segment 
of  memory.  Because  the  example  pro¬ 
gram  restricts  the  number  of  characters 
to  255,  it  stores  the  characters  in  string 
InsStr  and  puts  the  address  of  InsStr[lJ 
in  TSRChrPtr. 

Overriding  Default  Hot  Keys 

To  allow  the  users  of  TSRs  to  avoid  hot 
key  conflicts  with  other  programs, 
TSRUnit  permits  the  default  hot  key 
combination  to  be  overridden  when 
the  TSR  is  installed.  To  replace  the  hot 
key  combination,  include  some  com¬ 
mand-line  parameters  along  with  the 
TSR’s  program  name.  The  format  for 
the  parameters  is 

[/A]  t/C]  [/R]  [/L]  [/"[K[1]] 

The  square  brackets  surround  optional 
items.  (Do  not  include  the  brackets.) 
Spaces  or  characters  between  the  pa¬ 
rameters  are  ignored  and  the  parame¬ 
ters  may  be  listed  in  any  order.  Al¬ 
though  the  shift  key  parameters  (/A, 
/C,  /R,  and  /L)  are  cumulative,  only  the 
last  character  key  specified  is  used. 
The  command  to  install  TSRDemo  with 
hot  key  combination  Alt,  Left  Shift,  T  is 

TSRDEMO  /A/L/"T 
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Caution:  The  Effects  of  Run-Time  Errors 

Although  it  is  always  good  program¬ 
ming  technique  to  take  steps  to  pre¬ 
vent  run-time  errors  from  occurring,  it 
is  especially  important  to  do  so  in  a 
TSR  program.  Depending  upon  the  error¬ 
handling  methods  used,  the  occurrence 
of  an  error  can  cause  the  execution  of 
the  TSR  to  be  aborted.  In  some  cases, 
execution  will  resume  at  the  DOS 
prompt  level.  In  more  severe  cases,  the 
computer  will  “hang  up”  either  imme¬ 
diately,  or  later  when  the  TSR  is  popped 
back  down. 

Several  approaches  can  be  used  to 
deal  with  run-time  error  situations.  The 
example  program  TSRDemo  illustrates 
two  approaches.  One  of  these  meth¬ 
ods  is  to  replace  Turbo  Pascal’s  stan¬ 
dard  I/O  operation  error-checking  code 
with  code  that  simply  displays  an  error 
message.  (The  default  error-checking 
code  terminates  the  program  after  dis¬ 
playing  an  error  message.)  The  stan¬ 
dard  I/O  error  checking  is  disabled 
with  the  compiler  directive  ($1-1.  As  an 
example  of  a  second  type  of  error  check¬ 
ing,  TSRDemo  uses  TSRUnit’s  Printer¬ 
Okay  function  to  verify  that  the  printer 
is  ready  before  writing  to  it.  This 
approach  can  also  be  used  to  prevent 
numerical  errors,  such  as  divide- 
by-zero  errors.  A  third  method,  which 
is  too  complicated  to  cover  in  this  arti¬ 
cle,  is  to  intercept  the  error  handling 
routines. 

One  important  category  of  errors  that 
should  be  prevented  from  occurring  is 
that  of  “device  not  ready”  errors  —  this 
type  of  error  causes  the  computer  to 
“hang  up”  either  when  the  error  occurs 
or  when  the  TSR  pops  back  down.  The 
rhost  likely  cause  for  this  type  of  error 
is  an  attempt  to  use  either  a  diskette 
drive  or  a  printer  when  it  is  not  ready. 
To  prevent  either  of  these  events  from 
occurring,  the  example  program  takes 
the  precaution  of  querying  the  user 
and  checking  the  printer  status. 

Availability 

All  source  code  for  articles  in  this  issue 
is  available  on  a  single  disk.  To  order, 
send  $14.95  (Calif,  residents  add  sales 
tax)  to  Dr.  Dobbs  Journal,  501  Galves¬ 
ton  Dr.,  Redwood  City,  CA  94063,  or 
call  800-356-2002  (from  inside  Calif.) 
or  800-533-4372  (from  outside  Calif.). 
Please  specify  the  issue  number  and 
format  (MS-DOS,  Macintosh,  Kaypro). 

DDJ 

(Listings  begin  on  page  106.) 

Vote  for  your  favorite  feature/article. 

Circle  Reader  Service  No.  8. 


Dr.  Dobb 's Journal,  June  1989 

402 


73 


Maintaining 

System  Security 

File  system  vulnerability  and  threats  to 
network  security  can  be  avoided 


Maintaining  computer  security, 
whether  it  be  “open”  systems 
like  the  Unix  system  or 
“closed”  systems  like  those 
carrying  government  ap¬ 
proved  security  ratings,  involves  a  wide 
range  of  complex  issues.  Among  the  more 
pressing  security  issues  are  vulnerabilities 
in  the  user  file  system  and  threats  to 
network  security.  Although,  these  areas 
are  not  necessarily  related,  similar  ap¬ 
proaches  can  be  applied  to  each. 

Vulnerabilities  to  User  File  Systems 

Computer  system  administrators  are  re¬ 
sponsible  for  maintaining  security,  san¬ 
ity,  and  day-to-day  functionality.  To 
some  extent,  users  are  capable  of  inter¬ 
fering  with  most  or  all  of  these  goals 
and  there  are  several  possible  security 
risks  that  can  be  caused  by  naive  or 
inattentive  users.  Because  threats  to  com¬ 
puter  security  can  come  from  the  out¬ 
side  in  the  form  of  hackers  or  com¬ 
puter  intruders  or  from  the  inside  in  the 
form  of  malicious  or  disgruntled  em¬ 
ployees,  there  exists  a  need  to  protect 
users  from  each  other  and  from  them¬ 
selves.  With  this  in  mind,  I’ll  look  first 
at  the  vulnerabilities  that  can  occur  in 
the  user  file  system  or  the  area  where 
users  store  their  programs  and  data, 
the  “home  directory.” 

File  permissions  determine  whether 
a  file  is  readable,  writable,  or  execut¬ 
able  and  are  an  important  component 
of  information  access  control  in  any 
system.  Consider  the  case  where  a  ma¬ 
licious  user  wants  to  dupe  a  naive  user 
into  executing  some  command.  Per¬ 
haps  the  simplest  way  to  achieve  this 
is  by  placing  that  command  in  an  execut¬ 
able  file  owned  by  the  naive  user.  This 
can  be  accomplished  if  the  naive  user 
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has  an  executable  file  that  is  writable 
by  users  other  than  himself.  The  mali¬ 
cious  user  need  only  place  the  mali¬ 
cious  commands  in  the  writable  execut¬ 
able  file  and  wait  for  the  user  to  run  the 
contaminated  program. 

Consider  the  following  “malicious 
command:” 

cd$HOME 

rm-rf* 

The  first  command,  derived  from  Unix, 
changes  the  current  directory  to  be  the 
user’s  home  directory.  The  second  com¬ 
mand  recursively  removes  all  files  and 
directories  located  beneath  the  current 
directory.  Thus,  if  a  malicious  user  were 
able  to  cause  an  unsuspecting  user  to 
execute  these  commands,  then  the  un¬ 
suspecting  user  would  unknowingly 
remove  all  his  files  and  directories.  Of 
course,  there  are  more  subtle  methods 
of  attack  available  to  the  malicious  user 
but  this  one  is  quite  effective. 

The  vulnerability  in  this  case  stems 
from  the  fact  that  one  user  is  “giving 
away”  his  execution  privilege  to  an¬ 
other  in  the  form  of  a  writable  execut¬ 
able  file.  The  point  is  that  all  execut¬ 
able  files  imply  an  execution  privilege  — 
some  user  will  be  invoking  that  pro¬ 
cess  at  some  time  or  another.  As  such, 
all  executable  files  should  be  write  pro¬ 
tected,  just  like  the  system  executable 
files.  Assuming  that  you  have  access 
to  a  list  of  a  user’s  home  directories,  it 
is  a  good  idea  to  look  for  vulnerable 


user  files;  a  recursive  algorithm  like 
that  in  Example  1  shows  a  way  of  keep¬ 
ing  tabs  on  vulnerable  files. 

Many  people  seem  to  believe  that  a 
write-protected  file  is  always  safe,  even 
if  it  resides  in  a  writable  directory.  A 
writable  directory,  however,  allows 
other  users  to  move  (or  rename)  write- 
protected  files.  Once  done,  a  file  of  the 
same  name  can  be  created  in  the  same 
writable  directory.  As  an  example,  con¬ 
sider  the  case  where  a  user’s  start-up 
file,  such  as  profile  in  Unix,  is  write 
protected,  but  the  user’s  home  direc¬ 
tory  is  writable.  A  malicious  user  would 
be  able  to  rename  the  start-up  file  and 
create  a  new  file  called  “profile.  "This 
new  start-up  file  could  contain  the  ma¬ 
licious  shell  commands  shown  earlier. 
When  the  naive  user  logs  in,  the  mali¬ 
cious  start-up  file  will  be  executed  by 
the  log-in  shell.  Even  a  write-protected 
file  is  vulnerable  if  the  directory  it  re¬ 
sides  in  is  not  write  protected,  too. 

Files  and  directories  should  always 
be  write  protected,  especially  execut¬ 
able  files  and  directories  containing 
executable  files.  A  file  that  is  not  execut¬ 
able  but  is  writable  might  also  present 
a  problem.  On  systems  where  users  are 
billed  for  disk  utilization,  for  example, 
it  would  be  cost  effective  for  malicious 
users  to  append  their  data  files  to  other 
users’  writable  files  or  place  them  in 
other  users’  directories.  To  address  the 
more  general  issue  of  write  protection, 
(continued  on  page  156) 


FOR  {every  users'  home  directory)  DO 
checkdir (directory) 

DONE 

PROCEDURE  checkdir  (directory) 

FOR  (every  file  in  the  directory)  DO 
IF  ((file  is  executable)  AND  (file  is  writable))  THEN  flag  this  file 
ELSE  IF  (file  is  a  directory)  THEN  checkdir (file) 

DONE 

ENDPROCEDURE 


Example  1:  A  recursive  algorithm  like  this  provides  one  means  of  keeping 
tabs  on  vulnerable  files. 
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EXAMINING  ROOM 


Generating  Parsers 

"» PCYACC 


C++,  SQL,  Smalltalk,  and  PostScript  are  just  a  few  of  the 
grammars  provided  with  this  parser  generator 


Alex  Lane 


YACC  is  an  acronym  for  Yet 
Another  Compiler  Compiler.  Its 
name  reflects  both  the  preoc¬ 
cupation  with  parser  genera¬ 
tors  that  engaged  computer  sci¬ 
entists  back  in  the  early  70s,  as  well  as 
Unix’s  sometimes  whimsical  naming  prac¬ 
tices.  For  many  years,  YACC  (or  more 
properly,  yacc)  has  been  a  powerful 
basic  tool  in  the  toolchests  of  compiler 
writers  working  with  Unix-based  sys¬ 
tems.  Recently,  however,  several  com¬ 
panies  have  ported  yacc  to  the  MS- 
DOS  environment.  Among  them  is 
Abraxas  Software,  which  publishes 
PCYACC.  I  reviewed  Version  2.0  of  the 
product  on  an  ARC  386i  equipped  with 
1  Mbyte  of  RAM  and  a  hard  disk. 

A  bare-bones  definition  of  a  com¬ 
piler  is  “a  program  that  reads  an  input 
file  of  instructions  written  in  one  lan¬ 
guage  and  translates  them  into  an  out¬ 
put  file  of  instructions  in  another,  lower- 
level  language.”  Although  the  most  com¬ 
mon  form  of  output  file  that  the  casual 
compiler  user  deals  with  is  a  linkable 
object  code  file,  the  output  file  may 
contain  statements  in  any  language,  in¬ 
cluding  a  high-level  language. 

Indeed,  the  output  from  PCYACC  is 
a  C  source  program.  This  C  program 
can,  in  turn,  be  compiled  and  linked 
to  form  an  executable  file.  This  execut¬ 
able  file  is  capable,  in  its  turn,  of  pars- 


Alex  Lane  is  a  knowledge  engineer  for 
Technology  Applications  Inc.  of  Jackson¬ 
ville,  Fla.  He  can  be  reached  as  a.lane 
on  BIX  and  as  MANE  on  MCI  mail. 


ing  input  from  a  file  written  in  what¬ 
ever  language  was  specified  in  the  in¬ 
put  files  for  PCYACC.  It’s  perhaps  a 
mite  confusing  in  words,  so  maybe  a 
glance  at  Figure  1  will  help  clarify  the 
relationships  among  all  these  files. 

The  input,  or  source  language,  for 
PCYACC  is  what  the  folks  at  Abraxas 
call  a  grammar  description  language 
(GDL).  Statements  in  this  language  re¬ 
semble  Backus-Naur  Form  (BNF)  nota¬ 
tion,  which  is  commonly  used  to  de¬ 
scribe  context-free  grammars. 

A  PCYACC  input  program,  called  a 
grammar  description  program  (GDP), 
is  made  up  of  three  sections,  arranged 
in  the  following  order:  a  declaration 


section,  a  grammar  rule  section,  and  a 
program  section.  The  three  sections  are 
separated  from  one  another  by  the  de¬ 
limiter  %%. 

In  the  declaration  section,  anything 
enclosed  with  %( and  %/  is  passed  di¬ 
rectly  to  the  output  without  change. 
This  is  a  convenient  place  for  C  decla¬ 
rations  and  itemization  of  #include  files. 
PCYACC  tokens  are  identified  in  this 
section  by  the  keyword  %token,  and 
operator  associativity  is  declared  using 
the  %left,  %right,  and  %nonassoc  key¬ 
words.  Precedence  of  operators  is  im¬ 
plied  by  the  order  in  which  associa¬ 
tivity  declarations  appear.  Data  types 
of  grammar  symbols  are  declared  with 


Figure  1:  Relationship  among  the  various  PCYACC  files 
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the  keyword  %type,  and  the  keyword 
%start  can  be  used  to  declare  the  start 
symbol  of  the  grammar. 

The  second  section  of  the  GDP  con¬ 
tains  all  the  grammar  description  lan¬ 
guage  statements  for  the  target  com¬ 
piler.  Statements  in  GDL  have  the  fol¬ 
lowing  form: 

LHS  :  RHS  (C  code  segment); 

The  LHS  (left-hand  side)  of  the  rule 
consists  of  a  nonterminal  symbol.  The 
RHS  (right-hand  side)  is  a  sequence  of 
zero  or  more  grammar  symbols.  Fol¬ 
lowing  the  RHS  is  a  segment  of  C  code 
that  describes  an  associated  action  to 
be  performed  when  the  RHS  is  en¬ 
countered.  The  LHS  and  RHS  are  sepa¬ 
rated  by  a  colon,  and  the  rule  itself  is 
terminated  with  a  semicolon.  Multiple 
rules  having  a  common  LHS  are  often 
expressed  using  a  vertical  bar  to  de¬ 
note  an  OR  choice,  like  this: 

LHS  :  RHS1  (C  code  for  RHS1); 

I  RHS2  1C  code  for  RHS2I; 


Everything  in  the  program  section 
of  the  PCYACC  input  file  is  copied  to 
the  output  without  change.  The  man¬ 
ual  states  that  the  program  section  must 
contain  definitions  for  at  least  three 
functions:  the  familiar  main( ),  a  lexical- 
analyzer  function  called  yylexC ),  and 
an  error-reporting  function  yyerrorf ). 
I  found  that  although  definitions  for 
these  three  functions  must  appear  some¬ 
where  in  the  C  source  code  for  the 
target  parsing  program,  the  auxiliary 
files  supplied  with  PCYACC  show  that 
the  definitions  do  not,  as  stated  in  the 
book,  have  to  be  in  the  GDP. 

The  output  of  the  PCYACC  program 
is  a  C  source  file  that  contains  any  code 
passed  in  from  the  declaration  section 
and  all  the  code  from  the  program  sec¬ 
tion.  In  addition,  the  output  file  con¬ 
tains  the  code  for  a  function  called 
yyparse( ),  which  was  generated  using 
the  grammar  definition  rules. 

The  yyparse(  )  function  performs  look¬ 
ahead  left  and  right  (LALR)  parsing  for 
the  language  using  the  rules  from  the 
PCYACC  input  file.  The  LALR  method 
is  an  efficient,  bottom-up  syntax-analy¬ 
sis  technique  that  is  used  to  parse  virtu¬ 
ally  any  programming  language  con¬ 
structs  expressible  in  context-free  gram¬ 
mar  terms. 

The  yyparse( )  function  is  fed  by  a 
user-written  function  called  yylex( ), 
which  performs  lexical  analysis.  Basi¬ 
cally  this  means  that  the  input  is  bro¬ 
ken  into  meaningful  chunks  called  “to¬ 
kens,”  which  are  in  turn  passed  to  the 
parser. 


What  You  Get 

The  PCYACC  package  consists  of  a  126- 
page  spiral  bound,  8V2  x  11-inch  man¬ 
ual  entitled  Compiler  Construction  on 
Personal  Computers  (with  PCYACC)  and 
three  36OK  diskettes.  The  main  PCYACC 
diskette  contains  the  basic  PCYACC.EXE 
program,  a  couple  of  explanatory  text 
files,  and  several  subdirectories  of  fairly 
simple  examples.  A  second  diskette  pro¬ 
vides  grammar  description  files  for  sev¬ 
eral  languages,  including  K&R  and  ANSI 
C,  Pascal,  dBase  III  and  IV,  SQL,  Small- 

The  PCYACC 
specification  is  quite 
short  when  compared 
to  the  resulting  C  source 
program 


talk,  Prolog,  PostScript,  and  HyperTalk. 
The  third  diskette  supplies  a  fairly  com¬ 
plete  set  of  grammar  definition  and  C 
source  files  for  a  C++  preprocessor. 

The  PCYACC  manual  assumes  that 
users  are  familiar  with  C,  which  is  not 
an  unreasonable  assumption  under  the 
circumstances.  It  is  well  organized, 
makes  good  use  of  fonts  and  white 
space,  and  for  the  most  part  is  clear  in 
its  explanations.  Following  a  brief  over¬ 
view  that  includes  an  explanation  of 
typographical  conventions  in  the  man¬ 
ual,  the  book  uses  two  fairly  simple 
examples  as  a  basis  for  presenting 
PCYACC  concepts.  Much  of  the  rest  of 
the  book  then  concerns  itself  with  the 
theory  and  practice  behind  PCYACC, 
including  techniques  for  debugging. 
There  will  be  tough  going  here  for 
anyone  just  becoming  familiar  with 
parser  generators  and  yacc,  but  be¬ 
tween  the  clear  explanations  and  the 
numerous  examples  that  come  with 
PCYACC,  it’s  an  achievable  goal. 

From  a  hardware  perspective, 
PCYACC  works  on  most  PC-style  mi¬ 
crocomputers,  including  PS/2  and  386- 
based  machines.  PCYACC  can  be  run 
using  either  two  floppy  drives  or  a  hard 
disk  and  one  floppy  drive.  Software 
required  to  do  compiler  development 
with  PCYACC  includes  a  text  editor 
(such  as  Brief)  and  a  C  language  com¬ 
piler.  For  those  who  use  the  Brief  prod¬ 
uct,  Abraxas  supplies  two  macro  files 
(in  both  compiled  and  source  format) 
for  use  with  the  editor.  Installation  is 
straightforward;  I  merely  copied  the 


files  (and  subdirectories)  into  a  subdi¬ 
rectory  on  my  hard  disk. 

Using  PCYACC 

Developing  software  using  PCYACC  is 
a  six-step  procedure.  First,  as  with  any 
project,  you  identify  the  problem.  Be¬ 
cause,  typically,  parsing  input  is  only 
part  of  the  problem,  PCYACC  does  not 
play  a  central  role  at  this  stage  of  the 
development  process. 

The  second  step  is  to  define  the 
source  language.  This  definition  is  most 
commonly  done  using  a  context-free 
grammar  notation  such  as  BNF,  although 
the  specification  for  the  grammar  can 
be  written  directly  in  PCYACC’s  GDL. 
The  third  step  is  to  incorporate  the 
rules  into  a  PCYACC  grammar  descrip¬ 
tion  file. 

Next,  the  grammar  rules  should  have 
associated  action  code  written  for  them. 
The  required  support  routines  (main( ), 
yylex(  ),  and  yyerror( ))  should  be  coded 
to  allow  debugging  of  the  grammar 
description  program.  This  is  an  ideal 
place  to  use  the  -S  command-line  op¬ 
tion,  which  allows  the  grammar  de¬ 
scription  to  be  checked  without  going 
to  the  added  trouble  of  generating  a  C 
source  file.  You  can  really  appreciate 
this  feature  when  working  with  large 
grammar  definitions.  You  use  PCYACC’s 
other  command-line  options  mostly  to 
override  default  file-name  conventions 
or  to  indicate  actions  you  want  the 
program  to  perform  in  addition  to  what 
it  does  automatically.  Using  the  help 
option  (-h),  you  can  get  a  brief  synop¬ 
sis  of  all  available  options. 

Perhaps  the  second  most  valuable 
service  provided  by  a  compiler  is  the 
reporting  of  errors  in  input  files,  where 
accuracy  and  detail  count  for  a  lot  of 
time  saved  tracking  down  subtle  errors 
in  logic.  Here,  PCYACC  takes  advan¬ 
tage  of  the  LALR  parser’s  capability  to 
detect  syntactic  errors  as  soon  as  possi¬ 
ble  while  performing  a  left-to-right  scan 
of  the  input.  This  results  in  good  error 
trapping  while  generating  the  parser. 
In  addition,  there  are  a  couple  of  fea¬ 
tures  of  PCYACC  you  can  use  to  en¬ 
hance  the  debugging  process. 

You  can,  for  example,  use  the  -t 
command-line  option  mentioned  pre¬ 
viously  to  build  a  parser  that  outputs 
text  file  parse  trees  to  the  default  file 
YY.AST.  This  option  is  useful  for  de¬ 
bugging  grammar  files  and  studying 
source  code  written  in  a  particular  lan¬ 
guage  and  can  help  determine  whether 
there’s  a  problem  in  a  new  compiler 
or  in  a  source  file. 

Alternately,  you  can  use  the  -v  (ver¬ 
bose)  command-line  option  to  produce 
verbose  output  from  PCYACC  in  the 
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default  file  YY.LRT.  This  file  notes  all 
the  applicable  rules  and  actions  to  use 
for  all  possible  states  of  the  parser.  In 
addition,  a  summary  at  the  end  of  the 
file  shows  a  number  of  vital  statistics, 
including  several  terminal  symbols  used, 
the  number  of  grammar  rules  in  the 
program,  the  number  of  states,  and  the 
number  of  errors  (both  of  the  shift/ 
reduce  and  reduce/reduce  variety) 
found  in  the  GDP. 

Once  the  grammar  description  pro¬ 
gram  has  been  debugged  to  the  devel- 

Although  the  most 
common  form  of  output 
file  that  the  casual 
compiler  user  deals  with 
is  a  linkable  object  code 
file,  the  output  file  may 
contain  statements  in 
any  language, 
including  a  high-level 
language 


oper’s  satisfaction,  PCYACC  is  used  to 
compile  the  program  into  source  code 
for  yyparsej  ).  Other  C  code  should  be 
developed  at  this  point  as  well.  The 
last  step  is  to  build  an  executable  file 
that  correctly  solves  the  problem  you 
identified  in  the  first  place. 

To  give  you  an  idea  of  how  PCYACC 
works,  let’s  see  what  it  does  with  the 
specification  for  a  crude  desk  calcula¬ 
tor  shown  in  Listing  One,  page  110. 
The  code  for  this  example  draws  heav¬ 
ily  on  the  yacc  specification  for  a  sim¬ 
ple  desk  calculator  presented  in  the 
book  Compilers:  Principles,  Techniques, 
and  Tools,  by  Aho  et  al.  (Addison- 
Wesley,  1986).  The  specification  has 
been  modified  slightly  for  use  with 
PCYACC. 

The  declaration  section  first  passes 
the  names  of  two  include  files  to  the 
output  file  and  identifies  a  token  called 
DIGIT.  Next,  both  the  ‘+’and  ‘"’opera¬ 
tors  are  declared  to  be  left-associative, 
with  '+’  having  a  higher  precedence 
than  The  grammar  rule  section  con¬ 
tains  the  rules  for  the  “language”  to  be 
used  by  the  calculator.  The  symbols 


$$,  $1,  and  so  on  have  special  mean¬ 
ings  in  the  semantic  actions.  For  in¬ 
stance,  consider  the  following  rule: 

expr  :  expr  ’+’  term  (  $$  =  $1  +  $3;1 

The  symbol  $$  refers  to  the  value  asso¬ 
ciated  with  the  nonterminal  on  the  LHS 
of  the  rule.  The  symbols  $1  and  prefer 
to  the  expr  and  term  grammar  symbols 
on  the  RHS  of  the  rule.  (If  the  symbol 
$2  were  used,  it  would  refer  to  the  ‘+  ’ 
operator  in  the  RHS  of  the  rule.) 

The  program  part  of  the  GDP  simply 
provides  a  main ( /function  (which  calls 
the  yyparse(  )  generated  by  PCYACC); 
a  yy error! )  function  that  can  accept 
an  error  string  when  called;  and  a 
yylex( /function,  which  performs  crude 
lexical  analysis  (only  single-digit  num¬ 
bers  are  accepted!)  and  produces  pairs 
consisting  of  a  token  and  its  associated 
value.  In  the  case  of  our  calculator, 
there  is  only  one  token  {DIGIT),  and  its 
value  is  communicated  to  the  parser 
through  the  yacc  variable  yylval. 

The  PCYACC  specification  is  quite 
short  when  compared  to  the  resulting 
C  source  program,  shown  in  Listing 
Two,  page  110.  This  listing  was  created 
by  invoking  PCYACC  with  no  command¬ 
line  options,  as  follows: 

PCYACC  TEST.Y 

The  default  name  for  the  C  source  file 
was  TEST.C.  I  compiled  and  linked  this 
file  using  the  Microsoft  C  compiler  (Ver¬ 
sion  5  0)  and  obtained  an  executable 
file  11K  in  size. 

Other  Files 

Earlier  I  mentioned  that  PCYACC  comes 
with  several  grammar  definition  files 
for  languages  such  as  Pascal  and  Small¬ 
talk.  Before  anyone  gets  carried  away 
thinking  that  Abraxas  is  giving  away 
the  store  and  is  handing  out  compilers 
for  all  those  languages,  hold  on!  The 
grammar  files  that  come  with  PCYACC 
basically  have  the  ability  to  check  and 
see  whether  a  file  contains  syntacti¬ 
cally  correct  “sentences”  in  a  particular 
language.  So,  if  you  go  to  the  trouble 
of  compiling  and  linking  the  Pascal 
grammar  file,  you’ll  end  up  with  a  pro¬ 
gram  that  can  parse  Pascal  code  and 
tell  you  whether  it’s  succeeded  or  not. 
Although  some  may  shrug  their  shoul¬ 
ders  and  stifle  yawns,  these  files  never¬ 
theless  represent  some  of  the  best  ex¬ 
ample  programs  I’ve  seen  bundled  with 
a  professional  software  tool. 

The  one  exception  to  the  limited  syn¬ 
tax-analysis  capabilities  of  the  gram¬ 
mar  rule  files  is  the  collection  of  source 
code  files  and  a  PCYACC  specification 
for  a  C++  preprocessor.  Working  with 
these  files  taught  me  two  things  about 


PCYACC.  First,  the  product  is  capable 
of  industrial-size  projects.  The  PCYACC 
output  file  for  the  C++  preprocessor  is 
more  than  100K  in  size,  and  the  overall 
program  requires  compiling  and  link¬ 
ing  nearly  a  dozen  object  files.  Second, 
for  large  specifications,  PCYACC  can 
take  a  long  time  to  do  its  work.  In  fact, 
the  first  time  I  attempted  to  compile  the 
C++  grammar  specification,  I  ended  up 
rebooting  my  machine  because  I 
thought  it  had  hung.  The  same  thing 
happened  the  second  time  I  tried  it, 
and  only  a  chance  look  at  the  C++ 
README.DOC  file  (which  simply  notes 
that  “this  grammar  takes  a  long  time  to 
compile”)  convinced  me  to  wait  pa¬ 
tiently  for  PCYACC  to  do  its  job.  De¬ 
spite  running  on  an  80386-based  ma¬ 
chine,  PCYACC  took  more  than  five 
minutes  to  compile  and  output  the  pars¬ 
ing  code  for  the  C++  preprocessor. 

Computer  Boot  Camp 

Today,  writing  a  compiler  is  one  of 
those  things  that  a  typical  computer 
scientist  or  engineer  does  in  the  course 
of  pursuing  an  undergraduate  degree. 
For  most,  the  experience  is  sort  of  a 
computer  boot  camp,  requiring  a  lot 
of  discipline  and  application  over  the 
short  haul  but  something  that’s  eventu¬ 
ally  left  behind  to  pursue  other  goals. 
In  the  old  days,  much  of  the  effort  of 
writing  a  compiler  was  devoted  to  the 
issue  of  parsing  the  input.  Now  this 
phase  is  one  of  the  easiest  to  imple¬ 
ment,  and  thanks  to  packages  such  as 
PCYACC,  it  can  be  easily  implemented 
on  the  PC  architecture. 


Product  Information 

PYACC:  Abraxas  Software  Inc.,  7033 
SW  Macadam  Ave.,  Portland,  OR 
97219.  IBM  PC,  XT,  AT  or  compat¬ 
ible  (Macintosh  and  OS/2  versions 
also  available).  Requires  512K  RAM 
and  any  C  compiler.  Price:  $395. 


Availability 

All  source  code  for  articles  in  this  issue 
is  available  on  a  single  disk.  To  order, 
send  $14.95  (Calif,  residents  add  sales 
tax)  to  Dr.  Dobbs  Journal,  501  Galves¬ 
ton  Dr.,  Redwood  City,  CA  94063,  or 
call  800-356-2002  (from  inside  Calif.) 
or  800-533-4372  (from  outside  Calif.). 
Please  specify  the  issue  number  and 
format  (MS-DOS,  Macintosh,  Kaypro). 

DDJ 

(Listings  begin  on  page  110.) 

Vote  for  your  favorite  feature/article. 

Circle  Reader  Service  No.  9. 
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UNDOCUMENTED  DOS 


Listing  One  (Text  begins  on  page  26.) 


;  ************* 

******** 

********** 

************************************** 

DATA  STRUCTURES 

******** 

********** 

************************************** 

CALL52_2XX 

struc 

dpb_ptr  dd 

7 

;  Far  ptr  to  first  disk  parameter  block 

open  file_ptr 

dd 

? 

;  Far  ptr  to  Open  File  table 

clock  ptr 

dd 

7 

;  Far  ptr  to  CLOCK$  device  driver 

con_ptr  dd 

7 

;  Far  ptr  to  CON:  device  driver 

num  drives_2xx 

db 

7 

;  Number  of  logical  drives 

sector  sz  2xx 

dw 

7 

;  Maximum  sector  size 

buffer  ptr  2xx 

dd 

7 

;  Far  pointer  to  next  sector  buffer 

NUL_driver_2xx 

db 

7 

;  Beginning  of  the  NUL  device  driver 

CALL52_2XX 

ends 

CALL52_3XX 

struc 

dd 

4  dup (?) 

;  This  are  defined  in  previous  structure 

sector  sz_3xx 

dw 

7 

;  Maximum  sector  size 

buf fer_ptr_3xx 

dd 

7 

;  Far  pointer  to  next  sector  buffer 

path  ptr  3xx 

dd 

7 

;  Far  pointer  to  drive  path  table 

FCB_ptr_3xx 

dd 

7 

;  Far  pointer  to  FCB  table 

FCB_sz_3xx 

dw 

7 

Size  of  the  FCB  table 

num_drives_3xx 

db 

7 

Number  of  logical  drives 

lastdrive 

db 

7 

LASTDRIVE  number 

NUL_driver_3xx 

db 

7 

Beginning  of  the  NUL  device  driver 

CALL52_3XX 

ends 

.  ************* 

******* 

********** 

************************************** 

done :  mov 

ret 

modify_dos 


bx,  dword  ptr  es: [bx] 
si,  bx 


word  ptr  es: [bx] ,  0 
es: [bx+2] ,  di 
es 

es,  di 

es: [0] ,  si 

es: [2] ,  ds 

byte  ptr  es: [4] ,  -1 

es 

di,  sect_para_size 


cs:trash_pointer,  di 
endp 


See  if  we  are  above  or  below  the  line 
Loop  again  if  already  done  this  buffer 


xchg  es:bx,  ds:si 


Previous  buffer  ->  this  one 


This  one  ->  what  previous  did 

Tell  DOS  this  hasn't  been  used  yet 

DI  ->  next  buffer  start 

See  if  we  are  at  end  of  list 
Quit  if  we  are 

ES:BX  ->  next  buffer  in  line 


New  end  of  program 


End  Listing 


Changes  MS-DOS's  internal  maximum  sector  size  and  buffer  linked  list 
to  allow  MS-DOS  to  access  partitions  above  32-megabytes 


BIGGEST_SECTOR  set  to  largest  logical  sector  of  all  partitions 
DOS_VERSION  =  major  version  of  MS-DOS 
OLD  FILE  END  ->  initial  end  of  driver 


Returns : 

TRASH_PTR  set  to  new  end  of  program 

MS-DOS's  internal  maximum  sector  setting  changed 

MS-DOS's  internal  linked  buffer  list  relocated 


modify_dos  proc  uses  ax  ds  di  si 
local  sect_para_size:word 
local  buffer_paragraph:word 

mov  ax,  offset  old_file_end 

add  ax,  15 

mov  cl,  4 

shr  ax,  cl 

mov  bx,  cs 

add  ax,  bx 

mov  buffer_paragraph,  ax 

mov  ax,  biggest_sector 

add  ax,  lOh 

shr  ax,  cl 

mov  sect_para_size,  ax 

mov  ah,  52h 

int  21h 

mov  di,  buf fer_paragraph 

mov  si,  sector_sz_2xx 

cmp  dos_version,  2 

je  @F 

mov  si,  sector_sz_3xx 

@@:  mov  cx,  es: [bx+si] 

cmp  cx,  biggest_sector 

jnc  done 

mov  cx,  biggest_sector 

add  bx,  si 

mov  es:[bx],  cx 

add  bx,  2 

mov  dx,  cs 

@@:  mov  si,  bx 


Get  pointer  to  old  end  of  file 
Change  it  to  a  segment  number  so  we 
only  have  to  deal  with  a  16-bit  number 


AX  ->  paragraph  start 
Save  it  for  later 

AX  =  size  of  buffer  we  may  need  to 
allocate 

The  buffer  header  too 

Change  bytes/sector  to  paras/sector 

Save  for  later 

Our  undocumented  system  call 
Set  ES:BX  ->  DOS  list  of  lists 
DI  ->  beg.  of  initialization  trash 

SI  =  offset  to  version  2.xx  sector 
See  if  version  2.xx 
Skip  if  it  is 

SI  =  offset  to  version  3.xx  sector 

CX  =  the  largest  block  size  supported 

See  if  we  need  to  change  anything 
Jump  if  we  don't  need  to 

Update  DOS  with  the  new  largest 
BX  ->  sector  size  variable 
Update  maximum  sector  size  w/our 
Buffer  pointer  is  right  after  for 
both  versions 


bx,  dword  ptr  es: [bx] 

bx,  -1 

done 

byte  ptr  es:[bx+4],  -1 


ES:BX  ->  next  buffer  in  list 

Are  we  at  the  end 

Quit  if  we  are 

Set  the  nasty  buffer  flag 

Calculate  absolute  memory  placement 
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REAL-TIME  DATA 


Listing  One  (Text  begins  on  page  36.) 

/*  dbuff.c  Double  buffering  program  for  continuous 
reading  from  input  and  continuous  writing  to  output 

*/ 

♦include  <stdio.h> 

♦include  <smem.h> 

♦include  <sem.h> 


} 

/*  Allocate  shared  memory  */ 
buffa  =  (struct  xbuff  *)  smem_get ( 
"buffa", 

(long) sizeof (struct  xbuff), 
SM_READ  !  SM_WRITE) ; 
buffb  =  (struct  xbuff  *)  smem_get ( 
"buf fb", 

(long) sizeof (struct  xbuff), 
SM_READ  !  SM_WRITE) ; 


extern  char  *malloc(); 
extern  int  errno; 

♦define  BSIZE  65536  /*  size  of  each  buffer  */ 

struct  xbuff  ( 

char  buffer (BSIZE]; 
int  count; 
int  psem; 
int  csem; 
int  done; 

struct  xbuff  ‘other; 

1; 

/* 

Write  function  that  is  used  by  the  output  task 

*/ 

outputr(p,  prio) 
register  struct  xbuff  *p; 
int  prio; 

{ 

int  count; 

setpriority (0,  getpid(),  prio); 
while  ()  { 

sem_wait (p->csem) ;  /*  wait  for  buffer  to  fill  */ 

if  (p->count  <=  0)  ( 

sem_signal (p->psem) ;  /*  leave  if  finished  or  error  */ 

break; 

1 

count  =  write (1,  p->buffer,  p->count);  /*  write  output  */ 
if  (count  <=  0)  ( 

/*  exit  if  error  on  write  */ 
p->done  =  1; 
sem_signal (p->psem) ; 
break; 


/*  delete  old  semaphores  if  they  exist  */ 
semdelete ("buf fac") ; 
sem_delete ("buf fap") ; 
sem_delete ("buf f be") ; 
sem_delete ("buf fbp") ; 

buffa->csem  =  sem_get ("buf fac",  0) 
buffa->psem  =  sem_get ("buf fap",  1) 
buffb->csem  =  sem_get ("buf fbc",  0) 
buffb->psem  =  sem_get ("buf fbp”,  1) 
buffa->done  =  buffb->done  =  0; 

buffa->other  =  buffb; 
buffb->other  =  buffa; 


Create  another  task  to  write. 
This  task  will  read. 


if  (fork()  !=  0)  /*  Create  another  task  to  */ 

inputr (buffa,  inprio) ;  /*  write.  This  task  will  */ 

else  /*  read  */ 

outputr (buf fa,  outprio) ; 

End  listing  One 


Listing  Two 

/*  Reverb. c  HR  filter  program  to  add  reverberation  */ 
♦include  <file.h> 
extern  char  *malloc(); 


/*  Create  new  semaphores  to  *7 
/*  control  access  to  shared  */ 
/*  memory  */ 


/*  tell  producer  buffer  has  been  emptied  */ 
sem_signal (p->psem) ; 
p  =  p->other; 

) 

1 

/* 

Read  function  that  is  used  by  the  input  task 

*/ 

inputr (p,  prio) 
register  struct  xbuff  *p; 
int  prio; 

{ 

int  count; 

setpriority (0,  getpidO,  prio); 
do  1 

/*  wait  for  consumer  to  empty  buffer  */ 
sem_wait (p->psem) ; 
if  (p->done)  ( 
break; 

1 

/*  read  from  input  and  fill  buffer  */ 
count  =  read(0,  p->buffer,  BSIZE); 
p->count  =  count; 

/*  tell  consumer  task  buffer  is  filled  */ 
sem_signal (p->csem) ; 
p  =  p->other; 

}  while  (count  >  0);  /*  exit  when  no  more  data  */ 


main(argc,  argv) 
int  arge; 
char  **arav; 

{ 

register  struct  xbuff  *buffa,  ‘buffb; 
int  inprio,  outprio; 

/*  default  to  current  priority  */ 
inprio  =  outpric  =  getpriority (0,  0) ; 
if  (arge  ==  2)  ( 

/*  Get  input  priority  from  command  line  if  present  */ 
inprio  =  atci (argv[l] ) ; 

1 

if  (arge  ==  3)  | 

/*  Get  output  priority  from  command  line  if  present  */ 
inprio  =  atoi (argv[l] ) ; 
outprio  =  atoi (argv(2] ) ; 


ewrite (s) 
char  *s; 

{ 

write  (2,  s,  strlen(s)); 

I 

/* 

Read  the  whole  size  read()  under  UNIX  returns  the  amount  it 
read.  Last  buffer  is  (biased)  zero-filled. 

*/ 

fullread(fd,  buff,  size) 
int  fd; 

char  ‘buff; 
int  size; 

1 

int  i,  j; 

i  =  0; 
do  ( 

j  =  read(fd,  &buff[i],  size  -  i) ; 
if  (j  <=  0)  { 

/*  This  must  be  the  last  buffer  of  the  file  */ 
while  (i  <  size) 

buff (i++]  =  0x800; 
return  -1; 

) 

i  +=  j; 

)  while  (i  <  size) ; 
return  size; 

I 

main(ac,  av) 
int  ac; 
char  “av; 

I 

short  ‘ibuff,  ‘obuff; 

int  delay; 

int  i  ; 

int  fd; 

int  rundown; 

int  rv; 

char  *fn; 

register  short  *p,  *q; 
if  (ac  >  2)  { 

ewrite ("usage :  reverb  [delay] \n  (delay  expressed  in  samples) \n") ; 
exit  (1) ; 

I 

if  (ac  ==  2) 

delay  =  atoi (av[l] ) ; 

else 

delay  =  10240; 

/*  make  sure  delay  is  multiple  of  512  bytes  */ 
delay  -=  delay  &  511; 

/*  make  delay  >=  512  andd  <=  128K  */ 

if  (delay  <  512) 
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REAL-TIME  DATA 


Listing  Two  (Listing  continued,  text  begins  on  page  36.) 

main(ac,  av) 

delay  =  512; 

int  ac; 

if  (delay  >  128*1024) 

char  **av; 

delay  =  128*1024; 

{ 

int  fd; 

fd  =  0; 

short  buff [4096]; 

int  rc; 

ibuff  =  (short  *)  malloc (delay  *  sizeof (*ibuff ) ) ; 

int  i,  j,  t; 

obuff  =  (short  *)  calloc (delay  *  sizeof (*obuff) ) ; 

long  pos; 

struct  st at  s; 

do  ( 

/*  Read  a  buffer,  but  don't  check  error  status  yet  */ 

++av; 

rv  =  fullread(fd,  ibuff,  delay  *  sizeof (short) ) ; 

if  ((fd  =  open(*av,  0  RDONLY,  0))  ==  -1)  ( 

perror(*av);  /*  exit  if  can't  open  file  */ 

/* 

exit  (1) ; 

Add  the  fresh  input  samples  to  the  old  samples,  after 

} 

dividing  the  old  samples  by  2 

*/ 

fstat(fd,  &s) ;  /*  find  the  size  of  the  file  */ 

for  (p  =  ibuff,  q  =  obuff,  i  =  0;  i  <  delay;  ++i,  ++p,  ++q) 

pos  =  s.st  size  &  1; 

*q  =  ((*q  -  0x800)  »  1)  +  *p; 

while  (pos  >  0)  { 

/* 

/*  See  how  many  bytes  can  be  read  now  */ 

Write  the  output  reverbed  buffer 

if  (pos  <  sizeof (buff ) ) 

*/ 

rc  =  pos; 

write (1,  obuff,  delay  *  sizeof (short) ) ; 

else 

)  while  (rv  !-  -1); 

rc  =  sizeof (buff) ; 

/* 

pos  -=  rc; 

Allow  sound  in  output  buffer  to  "die  down" 

/*  Seek  back  a  block  and  read  */ 

*/ 

lseek(fd,  pos,  0); 

for  (rundown  =  11;  — rundown  >=  0;  )  ( 

read(fd,  buff,  rc) ; 

for  (q  =  obuff,  i  =  0;  i  <  delay;  ++i) 

*q  =  (*q  -  0x800)  »  1; 

/*  Reverse  the  samples  in  the  block  */ 

for  (i  =  0,  j  =  (rc  /  2)  -  1;  i  <  j;  ++i,  — j)  ( 

write (1,  obuff,  delay  *  sizeof (short) ) ; 

t  ■  buff  [i] ; 

) 

buff  [i]  =  buff ( j] ; 

1 

buf  f ( j 1  =  t; 

) 

End  Listing  Two 

/*  Write  the  reversed  block  */ 

write(l,  buff,  rc) ; 

J 

Listing  Three 

close (fd) ; 

} 

/*  reverse. c  Write  a  file  in  reverse  to  standard  output  */ 

♦include  <file.h> 

♦include  <types.h> 

♦include  <time.h> 

♦include  <stat.h> 

End  Listings 
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VARIABLE-LEVEL  PROGRAMMING 


Listing  One  (Text  begins  on  page  46.) 

# include  <dos.h> 

#define  AUXOUT  4  /*  DOS  function  id  for  aux. output  */ 
void  auxout(char  c) 

/*  Function:  Sends  character  c  to  auxiliary  output  */ 
(  bdos (AUXOUT, c,0);  /*  generate  INT  21  */  | 


End  Listing  One 


Listing  Two 

♦include  <string.h> 
extern  char  xtrans (char  c); 

char  ‘sfilt (char  ‘source,  char  ‘target) 

/*  Appends  source  to  target  and  applies  function  xtrans  to  */ 

/*  every  character  appended.  */ 

{ 

if (‘source)  /*  check  if  length  of  source  >  0  */ 

I 

/*  find  terminating  0  of  target  string  */ 

char  *end_of_target  =  target+strlen (target) ; 

/*  replace  terminating  0  by  transformed  first  char  of  source  */ 

*  (end_of_target++)  =  xtrans (‘source) ; 

/*  add  new  terminating  0  to  target  -  hope  we  have  enough  room  */ 
*end_of_target  «*  '\0'; 

/*  drop  leading  character  from  source  and  call  sfilt  again  */ 
sf ilt (strcpy (source, source+1) , target) ; 

) 

/‘we  are  done!  */ 
return  target; 

) 


End  Listing  Two 


Listing  Three 

\  Synopsis:  c  AUXOUT 
\  Stack  diagram:  c  - 

\  Function:  Sends  c  to  serial  output  device  AUX 
AUXOUT-FUN  EQU  4  \  Function  code  for  serial  output 
:  AUXOUT 

!DL  \  load  c  into  DL 

AUXOUT-FUN  \  load  function  code 
INT_21H  ;  \  call  DOS 


End  Listing  Three 


Listing  Four 

\  String  transformation 
\  Synopsis:  destination,  source  SFILT 
\  Stack  flow:  sinfol  sinfo2  —  sinfol' 

\  Function:  Appends  string  referred  to  by  sinfo2  to  string  sinfol 
\  and  applies  transformation  function  XTRANS  to  every  character 
\  of  the  source  string.  Returns  updated  sinfol. 

DEST  DSB  80  \reserve  80  char  string  buffer 

TEMP  DSB  80  \provide  temporary  buffer  space  for  2nd  string 

:  XTRANS  ;  \empty  definition  of  arbitrary  transformation  function 

\input  is  sinfol  sinfo2;  output  is  sinfol+sinfo2 (transformed) 

:  SFILT 

SLEN  \sinfol  sinfo2  sinfol  sinfo2  stringlength2 

IF  Ncompare  length  of  source  string  to  zero 

CGET  \  not  zero:  -  sinfol  sinfo2'  char 

XTRANS  \  apply  transformation:  —  sinfol  sinfo2'  char' 

\stack  has  sinfol,  sinfo2,  trsanslatedchar 
>R  \save  chr 

SSWAP  \sinfo2  sinfol 

R>  \get  chr 

C+  \append  chr  to  sinfol 

SSWAP  \sinfol  sinfo2 

\next  instruction  is  assembler ...  if  we  use  high  level  call  linkage 
\there  is  danger  of  return  stack  overflow. . .this  way  is  stable 

JMPS  SFILT  \recursively  call  til  entire  string  scanned 

ELSE 

SDROP  \  string  exhausted. . .discard  sinfo 

THEN  ;  \complete 


:  DEST-INIT  \  -  sinfol 

"You  know  that  "  ; 

:  SOURCE  \  — -  sinfo2 

"Some  different  alpha  characters  are  commonly  used  in  Germany."  ; 

:  SETUP  \  —  sinfo 

DEST-INIT  DEST  SCOPY  ;  \copy  string  to  string  buffer 

\main  procedure 
:  MAIN 

SETUP  \initialize  destination  area 

SOURCE  SFILT  \translate  and  append  source 

SPRINT  ;  \output  result  to  console 

\  Define  MAIN  as  startup  routine: 

END  MAIN 


End  Listing  Four 


Listing  Five 

MODULE  string  handling. 

LAYER  main  layer. 

SECTION  string  transformers. 

ENDSEC  string  transformers. 

SECTION  char  transformers. 

ENDSEC  char  transformers. 
ENDLAY  main  layer. 

ENDMOD  string  handling. 


End  Listing  Five 


Listing  Six 

CONST  auxout  fun  =  4.  #  DOS  function  code  'serial  output'  # 

#  Synopsis:  auxout  +c  # 

#  Function:  Sends  character  c  to  device  AUX  t 

#  Note:  AUX  defaults  to  C0M1 .  This  assignment  may  be  t 

#  changed  by  the  MODE  command  of  DOS  # 

ACTION  auxout  +>c  : 
loadax  +auxout  fun, 
loaddl  +c, 
int21 . 

#  The  syntax  of  the  following  terminal  productions  depends  # 

#  on  the  code  generator  used.  # 

ACTION  loadax  +>value  =  "MOV  AX,"  value. 

ACTION  loaddl  +>value  =  "MOV  DL, "  value. 

ACTION  int21  =  "INT  21H" . 


End  Listing  Six 


Listing  Seven 

#  Synopsis:  sfilt  +source  string  ttarget  string  # 

!  Function:  Appends  source  to  target  string  by  applying  # 

#  transformation  'xtrans'  to  every  character  of  # 

#  source  string  # 

VAR  first  char  .  #  temporary  variable  to  hold  one  char  # 

ACTION  sfilt  +>source  +>target>  : 

nullstring  +source;  #  finish  when  source=NULL  # 

(but  first  +source  +first  char,#  else  drop  first  char  # 

xtrans  +first  char,  #  translate  it  I 

append  char  +first  char+target , #  append  to  target  # 

sfilt  +source  +target) .  #  repeat  the  process  # 

#  Refinement.  Note  that  the  following  base  words  have  to  be  # 

#  expanded  by  appropriate  assembler  statements.  # 

TEST  nullstring  +>string  =  .  #  test  if  string=NULL  # 

ACTION  but  first  +>string>  +char>  =  . 

#  move  head  of  string  to  char  # 

ACTION  xtrans  +>a  char>  =  .  #  translate  'a  char'  I 

ACTION  append  char  +>char  +>str>=. .  #  append  char  to  str  # 


End  Listings 
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AWK-LIKE  EXTENSIONS 


Listing  One  (Text  begins  on  page  64.) 

♦define  ENDSTR  '\0' 

♦define  EOL  '$' 

/* 

♦define  BOL  ,-w 

*  qstring.c  -  finds  and  outputs  all  quoted  strings  in  a  C 

source 

file. 

♦define  NEGATE 

* 

♦define  CCL  '  ! ' 

*  Copyright  1988,  Jim  Mischel 

♦define  NCCL  ' ) ' 

*/ 

♦define  CCLEND  ' ] ' 

♦include  <stdio.h> 

♦define  ANY  ' . ' 

♦include  <string.h> 

♦define  DASH 

♦include  "awklib.h" 

♦define  OR  '  ! ' 

♦define  ESCAPE  'W 

void  main  (void)  { 

♦define  LPAREN  ' (' 

char  pat [MAXPAT] ; 

♦define  RPAREN  ' ) ' 

char  buff [MAXSTR] ; 

♦define  CLOSURE 

char  s (MAXSTR); 

♦define  POS  CLO  '+' 

char  *c; 

♦define  ZERO  ONE  '?' 

♦define  LITCHAR  'c' 

awk  init  ( ) ; 

♦define  END  TERM  'e' 

if  (makepat ("\" [A\"] pat)  ==  NULL)  ( 

♦define  FS  DEFAULT  " [  \t]+" 

fprintf  (stderr,  "Error  compiling  pattern  string. \n"); 
return; 

> 

♦define  MAXSTR  1024 

♦define  MAXPAT  2 ‘MAXSTR 

♦define  MAXFIELD  128 

while  (gets  (buff)  !=  NULL)  ( 
c  =  buff; 

/* 

while  ( (c  =  re  match  (c,  pat))  !=  NULL)  ( 

*  AWKLIB  global  variables.  These  variables  are  defined  in  AWKLIB.H  and  may 

strncpy  (s,  c,  RLENGTH) ; 

*  be  accessed  by  the  application. 

s (RLENGTH)  =  '\0'; 

*/ 

puts  (s); 

int  RSTART;  /*  start  of  matched  substring  */ 

C  +=  RLENGTH; 

) 

) 

) 

int  RLENGTH;  /*  length  of  matched  substring  */ 

int  NF;  /*  number  of  fields  from  most  current  split  */ 

char  *  FS;  /*  global  field  separator  */ 

char  *  FS_PAT;  /*  compiled  field  separator  */ 

char  *  FIELDS [MAXFIELD] ;  /*  contents  of  fields  from  most  current  split  */ 

End  Listing  One 

/* 

*  Internal  function  prototypes. 

*/ 

char  *  pascal  re  match  (char  *s,  char  *pat); 

char  *  pascal  makepat  (char  *re,  char  *pat); 

int  pascal  re_split  (char  *s,  char  “a,  char  *pat); 

char  *  pascal  do  sub  (char  *str,  int  inx,  int  len,  char  ‘replace); 

char  parse_escape  (void) ; 

Listing  Two 

/* 

*  These  string  routines,  while  designed  specifically  for  this  application, 

/* 

*  may  be  useful  to  other  programs.  Their  prototypes  are  included  in  the 

*  AWKLIB.H  file. 

*  awklib.h  -  defines,  global  variables,  and  function  prototypes 

for 

*/ 

*  AWKLIB  routines. 

char  *  pascal  strins  (char  ‘s,  char  *i,  int  pos); 
char  *  pascal  strcins  (char  *s,  int  ch,  int  pos); 

*  Copyright  1988,  Jim  Mischel.  All  rights  reserved. 

*/ 

char  *  pascal  strdel  (char  *s,  int  pos,  int  n)  ; 

char  *  pascal  strcdel  (char  *s,  int  pos); 

char  *  pascal  strccat  (char  *s,  int  c); 

extern  int  RSTART; 

extern  int  RLENGTH; 

/* 

extern  int  NF; 

*  Initialize  AWKLIB  global  variables.  This  routine  MUST  be  called  before 

extern  char  *FS; 

*  using  the  AWKLIB  routines.  Failure  to  do  so  may  produce  some  strange 

extern  char  *FS  PAT; 

*  results. 

extern  char  *FIELDS[]; 

*/ 

void  pascal  awk  init  (void)  ( 

♦define  MAXSTR  1024 

int  x; 

♦define  MAXPAT  2 ‘MAXSTR 

char  *  pascal  setfs  (char  *fs) ; 

void  pascal  awk  init  (void); 

FS  =  FS  PAT  =  NULL; 

char  *  pascal  setfs  (char  *fs); 

setfs  (FS  DEFAULT); 

char  *  pascal  match  (char  *s,  char  *re) ; 

RSTART  =  RLENGTH  =  NF  =  0; 

char  *  pascal  re  match  (char  *s,  char  *pat); 

for  (x  =  0;  x  <  MAXFIELD;  x++) 

char  *  pascal  makepat  (char  *re,  char  *pat); 

FIELDS [x]  =  NULL; 

int  pascal  split  (char  *s,  char  “a,  char  *fs); 

)  /*  awk  init  */ 

int  pascal  re  split  (char  *s,  char  “a,  char  *pat); 

int  pascal  getline  (char  *s,  int  nchar,  FILE  ‘infile); 

/* 

int  pascal  sub  (char  *re,  char  ‘replace,  char  *str) ; 

*  Sets  the  field  separator  to  the  regular  expression  fs.  The  regular 

int  pascal  re  sub  (char  *pat,  char  ‘replace,  char  *str); 

*  expression  is  compiled  into  FS  PAT.  FS  PAT  is  returned.  NULL  is  returned 

int  pascal  gsub  (char  *re,  char  ‘replace,  char  *str); 

*  on  error  and  neither  FS  or  FS  PAT  is  modified. 

int  pascal  re  gsub  (char  ‘pat,  char  ‘replace,  char  *str); 

*/ 

char  *  pascal  strins  (char  *s,  char  *i,  int  pos) ; 

char  *  pascal  strcins  (char  *s,  int  ch,  int  pos); 

char  *  pascal  strdel  (char  *s,  int  pos,  int  n) ; 

char  *  pascal  setfs  (char  *fs)  ( 
char  pat [MAXPAT]; 

char  *  pascal  strcdel  (char  *s,  int  pos); 

pat [0]  =  ENDSTR; 

char  *  pascal  strccat  (char  *s,  int  c) ; 

if  (makepat  (fs  DEFAULT,  pat)  ==  NULL) 
return  (NULL) ; 
if  (FS  !=  NULL) 

free  (FS); 

if  (FS  PAT  ! =  NULL) 

End  Listing  Two 

free  (FS  PAT) ; 

FS  =  strdup  (fs); 

FS  PAT  =  strdup  (pat); 
return  (FS  PAT) ; 

)  /*  setfs  */ 

Listing  Three 

/* 

*  makepat ()  -  "compile"  the  regular  expression  re  into  pat  and  return  a 

*  a  pointer  to  the  compiled  string,  or  NULL  if  the  compile  fails. 

/* 

*  Performs  a  recursive  descent  parse  of  the  expression. 

*  awklib.c  -  C  callable  routines  that  provide  field  splitting  and  regular 

*  expression  matching  functions  much  like  those  found  in 

AWK. 

char  *_re_ptr;  /*  global  for  pattern  building  */ 

*  Copyright  1988,  Jim  Mischel.  All  rights  reserved. 

*/ 

char  *  pascal  makepat  (char  *re,  char  *pat)  ( 

♦include  <stdio.h> 

char  *t; 

♦include  <string.h> 

♦include  <alloc.h> 

char  *  parse  expression  (void) ; 

♦include  <process.h> 

_re  ptr  =  re; 

if  ( (t  =  parse  expression  ())  ==  NULL) 

return  (NULL) ; 

♦define  FALSE  0 

♦define  ALMOST  1  /*  returned  when  a  closure  matches 

a  NULL 

*/ 

else  if  (*_re_ptr  !=  ENDSTR)  f 

(continued  on  page  96) 
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free  (t); 
return  (NULL) ; 


else  ( 

strcpy  (pat,  t) ; 
free  (t); 
return  (pat); 

) 

)  /*  makepat  */ 


/* 

*  parse_expression ()  -  Parse  and  translate  an  expression.  Returns  a  pointer 

*  to  the  compiled  expression,  or  NULL  on  error. 

*/ 

char  *  parse_expression  (void)  ( 
char  pat [MAXPAT] ; 
char  *argl; 


char  *  parse_term  (void) ; 
pat  [0]  =  ENDSTR; 

if  ( (argl  =  parse_term  ())  ==  NULL)  /*  get  the  first  term  */ 
return  (NULL) ; 

while  (*_re_ptr  ==  OR)  (  /*  parse  all  subsequent  terms  */ 

strccat  (pat,  OR); 
strcat  (pat,  argl); 

strccat  (pat,  END_TERM) ; 
free  (argl); 

_re_ptr++; 

if  {(argl  =  parse_term  ())  ==  NULL) 
return  (NULL) ; 

I 

strcat  (pat,  argl); 
strccat  (pat,  END_TERM) ; 
free  (argl); 
return  (strdup  (pat)); 

)  /*  parse_expression  */ 


/* 

*  parse_term()  -  parse  and  translate  a  term.  Returns  a  pointer  to  the 

*  compiled  term  or  NULL  on  error. 

*/ 

char  *  parse_term  (void)  ( 
char  *t; 

char  pat [MAXPAT]; 


int  isfactor  (char  c); 
char  *  parse_factor  (void); 

pat  [0]  =  ENDSTR; 
if  (*_re_ptr  ==  BOL) 

strccat  (pat,  *_re_ptr++); 

do  ( 

if  ( (t  =  parsefactor  ())  ==  NULL) 
return  (NULL) ; 
else  1 

strcat  (pat,  t); 
free  (t); 

I 

)  while  (isfactor  (*_re_ptr));  /*  parse  all  factors  of  this  term  */ 

return  (strdup  (pat)); 

)  /*  parse_term  */ 


strccat  (pat,  LITCHAR) ; 
strccat  (pat,  parseescape  {)); 
break; 

case  CLOSURE  : 
case  POS_CLO  : 
case  ZEROONE  : 

case  NEGATE  : 
case  CCLEND  : 

case  RPAREN  : 

case  OR  :  /*  not  valid  characters  */ 

return  (NULL) ; 

default  :  /*  literal  character  */ 

strccat  (pat,  LITCHAR); 
strccat  (pat,  *_re_ptr++); 
break; 

) 

/* 

*  check  for  closure 
*/ 

if  (*_re_ptr  ==  CLOSURE  ||  *_re_ptr  ==  ZERO_ONE  ||  *_re_ptr  ==  POS_CLO) 
if  (parse_closure  (pat,  *_re_ptr++)  ==  FALSE) 
return  (NULL) ; 
return  (strdup  (pat)); 

}  /*  parse_f actor  */ 


/* 

*  parse_escape  ()  -  returns  ASCII  value  of  character (s)  following  ESCAPE 
*/ 

char  parse_escape  (void)  { 
unsigned  char  ch.- 
switch  (*_re_ptr)  { 
case  'b' 
case  't' 
case  '  f 
case  'n' 
case  'r' 
case  '0' 
case  '1' 
case  '2' 
case  '3' 
case  '4' 
case  '5' 
case  '6' 
case  '7' 

ch  =  *_re_ptr++  -  '0'; 

if  (*_re_ptr  >=  '0'  &&  *_re_ptr  <  '8')  ( 
ch  «-  3; 

ch  +=  *_re_ptr++  -  'O'; 

1 

if  (*_re_ptr  >=  '0'  &&  *_re_ptr  <  '8')  ( 
ch  «=  3; 

ch  +=  *_re_ptr++  -  'O'; 

I 

return  (ch) ; 

default  :  /*  otherwise,  just  that  char  */ 

return  (*_re_ptr++) ; 

) 

)  /*  parse_escape  */ 


_re 

_ptr++; 

return 

('  \b' )  ; 

/* 

backspace  */ 

re 

ptr++; 

return 

('\t'); 

/* 

tab  */ 

_re 

]ptr++; 

return 

('  \f' )  ; 

/* 

formfeed  */ 

_re 

]ptr++; 

return 

('  \n' )  ; 

/* 

linefeed  */ 

_re 

_ptr++; 

return 

('  \r' ) ; 

/* 

carriage  return 

/*  0-7  is  octal  constant  */ 


/* 

*  parse_closure ()  -  place  closure  character  and  size  before  the  factor 

*  in  the  compiled  string. 

V 

int  parse_closure  (char  *pat,  char  c)  ( 
int  len; 


/* 

*  isfactor  ()  -  returns  TRUE  if  c  is  a  valid  factor  character 
*/ 

int  isfactor  (char  c)  ( 

static  char  nfac_chars[]  =  "A| )]+?*", • 

return  (strchr  (nfac_chars,  c)  ==  NULL)  ?  TRUE  :  FALSE; 

)  /*  isfactor  */ 

/* 

*  parse_factor ()  -  parse  and  translate  a  factor.  Returns  a  pointer  to  the 

*  compiled  factor  or  NULL  on  error. 

*/ 

char  *  parse_factor  (void)  { 
char  pat [MAXPAT]; 
char  *t; 

char  *  parse_expression  (void) ; 

int  parse_closure  (char  *pat,  char  c) ; 

char  *  parse_ccl  (void) ; 


memmove  (pat+2,  pat,  strlen  (pat)  +  1); 
pat [0]  =  c; 

len  =  strlen  (pat  +  2) ; 
if  (len  >  255) 

return  (FALSE);  /*  closure  expression  too  large  */ 

else  f 

pat  [  1 )  =  len; 
return  (TRUE) ; 

» 

)  /*  parse_closure  */ 


*  parse_ccl()  -  parse  and  translate  a  character  class.  Return  pointer  to  the 

*  compiled  class  or  NULL  on  error. 

*/ 

char  *  parse_ccl  (void)  ( 
char  pat [MAXPAT]; 
int  first  =  TRUE; 
int  len; 


pat [0]  =  ENDSTR; 
switch  (*_re_ptr)  < 

case  LPAREN  :  /*  parenthesised  expression  */ 

_re_ptr++; 

t  =  parseexpression  (); 
strcat  (pat,  t); 
free  (t); 

if  (*_re_ptr++  !=  RPAREN) 

return  (NULL) ; 

break; 

case  CCL  :  /*  character  class  */ 

_re_ptr++; 

t  =  parse_ccl  (); 

strcat  (pat,  ti; 

free  (t) ; 

if  (*_re_ptr++  !=  CCLEND) 

return  (NULL) ; 

break; 

case  ANY  :  /*  '.'  or  '$'  operators  */ 

case  EOL  : 

strccat  (pat,  *_re_ptr++) ; 
break; 

case  ESCAPE  :  /*  ESCAPE  character  */ 

_re_ptr++; 


char  *  parse_dash  (char  *pat,  char  ch) ; 
strcpy  (pat,  "[  "); 

if  (*_re_ptr  ==  NEGATE)  (  /*  if  first  character  is  NEGATE  */ 

pat  [ 0 ]  =  NCCL;  /*  then  we  have  a  negated  */ 

_re_ptr++;  /*  character  class  */ 

) 

/* 

*  parse  all  characters  up  to  the  closing  bracket  or  end  of  string  marker 

*/ 

while  ( *_re_ptr  !=  CCLEND  &&  *_re_ptr  !=  ENDSTR)  ( 

if  (*_re_ptr  ==  DASH  &&  first  ==  FALSE)  (  /*  DASH,  check  for  range  */ 

if  (*++_re_ptr  ==  NCCL) 

strccat  (pat,  DASH);  /*  not  range,  literal  DASH  */ 

else 

parse_dash  (pat,  *_re_ptr++) ; 

) 

else  ( 

if  ( *_re_pt r  ==  ESCAPE)  f 
_re_ptr++; 

strccat  (pat,  parse_escape  ()); 


(continued  on  page  98) 
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Listing  Three  (Listing  continued,  text  begins  on  page  64.) 

i 

else 

strccat  (pat,  *_re_ptr++); 

} 

first  =  FALSE; 

} 

len  =  strlen  (pat+2); 
if  (len  >  255) 

return  (NULL) ;  /*  character  class  too  large  */ 

else  ( 

pat[l]  =  len;  /*  store  CCL  length  at  pat  11]  */ 

return  (strdup  (pat)); 

) 

)  /*  parse_ccl  */ 

/* 

*  parse_dash ()  -  fill  in  range  characters. 

*/ 

char  *  parse_dash  (char  *pat,  char  ch)  { 
int  chi; 

for  (chi  =  pat (strlen  (pat)  -  1]  +  1;  chi  <=  ch;  chl++) 
strccat  (pat,  chi); 
return  (pat); 

}  /*  parse_dash  */ 

/* 

*  match ()  -  Return  a  pointer  to  the  first  character  of  the  left-most  longest 

*  substring  of  s  that  matches  re  or  NULL  if  no  match  is  found.  Sets 

*  RSTART  and  RLENGTH.  This  routine  compiles  the  regular  expression  re  and 

*  then  calls  re_match  to  perform  the  actual  matching. 

*/ 

char  *  pascal  match  (char  *s,  char  *re)  { 
char  pat [MAXPAT] ; 

pat (0]  =  ENDSTR; 

if  (makepat  (re,  pat)  -«  NULL) 

return  (NULL) ; 

return  (re_match  (s,  pat)); 

}  /*  match  */ 

/* 

*  re_match()  -  Return  a  pointer  to  the  first  character  of  the  left-most 

*  longest  substring  of  s  that  matches  pat,  or  NULL  if  no  match  is  found. 

*  Sets  RSTART  and  RLENGTH.  The  !=  FALSE  test  below  must  NOT  be  changed 

*  to  ==  TRUE.  match_term()  can  return  TRUE,  FALSE,  or  ALMOST.  Both  TRUE 

*  and  ALMOST  are  considered  TRUE  by  this  routine. 

*/ 

char  *_s_end;  /*  global  points  to  last  character  matched  */ 

char  *  pascal  rejnatch  (char  *s,  char  *pat)  { 
char  *c  =  s; 

int  pascal  match_term  (int  inx,  char  *s,  char  *pat); 

_s_end  =  NULL; 
while  ( *c  ! =  ENDSTR)  ( 

if  (match_term  (c-s,  c,  pat)  !»  FALSE)  { 

RSTART  =  c-s; 

RLENGTH  =  _s_end  -  c; 
return  (c); 

} 

C++; 

) 

RSTART  =  RLENGTH  =  0; 
return  (NULL); 

)  /*  rejnatch  */ 

/* 

*  Match  a  compiled  term.  Returns  TRUE,  FALSE,  or  ALMOST. 

*/ 

int  pascal  match_term  (int  inx,  char  *s,  char  *pat)  { 
int  pascal  match_or  (int  inx,  char  *s,  char  *pat); 
int  pascal  match_ccl  (char  c,  char  *pat); 

int  pascal  match_closure  (int  inx,  char  *s,  char  *pat,  char  "clopat); 
int  pascal  match_0_l  (int  inx,  char  *s,  char  *pat); 

s_end  =  s; 
if  ("pat  ==  ENDSTR) 
return  (FALSE) ; 
do  ( 

switch  (*pat)  ( 

case  BOL  ;  /*  match  beginning  of  line  */ 

if  (inx  !=  0) 

return  (FALSE) ; 
pat++; 
break; 

case  LITCHAR  :  /*  match  literal  character  */ 

if  (*s++  !=  *++pat) 
return  (FALSE) ; 
pat++; 
break; 

case  END_TERM  :  pat++;  break;  /*  skip  end-of-term  character  */ 
case  ANY  :  /*  match  any  character  . . .  */ 

if  ( *s++  ==  ENDSTR)  /*  ...  except  end  of  string  */ 
return  (FALSE) ; 
pat++; 
break; 

case  OR  :  return  (match_or  (inx,  s,  pat)); 
case  CCL  :  /*  character  class  requires  */ 

case  NCCL  :  /*  special  processing  */ 

if  (*s  ==  ENDSTR) 
return  (FALSE) ; 
if  <!match_ccl  (*s++,  pat++) ) 
return  (FALSE) ; 
pat  +=  *pat  +  1; 
break; 

case  EOL  :  /*  match  end  of  string  */ 

if  <*s  ! =  ENDSTR) 


return  (FALSE); 
pat++; 
break; 

case  ZERO_ONE  :  return  (match_0_l  (inx,  s,  pat)); 

case  CLOSURE  : 

case  POS_CLO  :  ( 

char  clopat [MAXPAT]  ; 

strncpy  (clopat,  pat+2,  * (pat+1)); 

clopat [* (pat+1) ]  =  ENDSTR; 

return  (match_closure  (inx,  s,  pat,  clopat)); 

break; 

} 

default  : 

/* 

*  If  we  get  to  this  point,  then  something  has  gone  very  wrong. 

*  Most  likely,  someone  has  tried  to  match  with  an  invalid 

*  compiled  pattern.  Whatever  the  case,  the  only  thing  to  do 

*  is  abort  the  program. 

*/ 

fputs  ("In  match_term:  can't  happen",  stderr); 

exit  (1); 

break; 

}  /*  switch  */ 

_s_end  =  s; 

)  while  (*pat  !=  ENDSTR); 
return  (TRUE) ; 

}  /*  match_term  */ 

/* 

*  match  or()  -  Handles  selection  processing. 

*/ 

int  pascal  match_or  (int  inx,  char  *s,  char  *pat)  ( 
char  wo rkpat (MAXPAT] ; 
char  *tl,  *t2,  *junk; 

int  pascal  match_term  (int  inx,  char  *s,  char  *pat); 
char  *  pascal  skip_term  (char  *pat); 

/* 

*  The  first  case  is  build  into  workpat.  Second  case  is  already  there. 

*  Both  patterns  are  searched  to  determine  the  longest  matched  substring. 

*/ 

workpat [0]  =  ENDSTR; 
pat++; 

junk  =  skip_term  (pat); 

strncat  (workpat,  pat,  junk-pat); 

strcat  (workpat,  skip_term  (junk)); 

tl  =  (match  term  (inx,  s,  workpat)  !=  FALSE)  ?  s  end  :  NULL; 

/* 

*  The  second  pattern  need  not  be  searched  if  the  first  pattern  results 

*  in  a  match  through  to  the  end  of  the  string,  since  the  longest  possible 

*  match  has  already  been  found. 

*/ 

if  (tl  ==  NULL  | |  *_s_end  !-  ENDSTR)  ( 

t2  =  (match  term  (inx,  s,  junk)  !-  FALSE)  ?  s  end  :  NULL; 

/* 

*  determine  which  matched  the  longest  substring 
*/ 

if  (tl  ! =  NULL  &&  (t2  ==  NULL  | |  tl  >  t2)) 

_s_end  =  tl; 

) 

return  (tl  ==  NULL  &&  t2  ==  NULL)  ?  FALSE  :  TRUE; 

)  /*  match_or  */ 

/* 

*  Skip  over  the  current  term  and  return  a  pointer  to  the  next  term  in 

*  the  pattern. 

*/ 

char  *  pascal  skip_term  (char  *pat)  ( 
register  int  nterm  =  1; 

while  (nterm  >  0)  { 
switch  (*pat)  { 
case  OR  :  nterm++;  break; 
case  CCL  : 

case  NCCL  : 

case  CLOSURE: 
case  ZERO_ONE: 
case  POS_CLO: 
pat++; 

pat  +=  *pat; 

break; 

case  END_TERM:  nterm — ;  break; 
case  LITCHAR:  pat++;  break; 

} 

pat++; 

) 

return  (pat); 

)  /*  skip_term  */ 

/* 

*  Match  the  ZERO_ONE  operator.  First,  this  routine  attempts  to  match  the 

*  entire  pattern  with  the  input  string.  If  that  fails,  it  skips  over 

*  the  closure  pattern  and  attempts  to  match  the  rest  of  the  pattern. 

*/ 

int  pascal  match_0_l  (int  inx,  char  *s,  char  *pat)  { 
char  *save_s  =  s; 

if  (match_term  (inx,  s,  pat+2)  ==  TRUE) 
return  (TRUE) ; 

else  if  (match_term  (inx,  save_s,  pat+2+* (pat+1) )  ==  FALSE) 

return  (FALSE); 

else 

return  (ALMOST); 

}  /*  match_0_l  */ 

/* 

*  Match  CLOSURE  and  POS_CLO. 

*  Match  as  many  of  the  closure  patterns  as  possible,  then  attempt  to  match 

(continued  on  page  103) 
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listing  Three  (Listing  continued,  text  begins  on  page  64.) 

/* 

*  remove  'len'  characters  from  'str'  starting  at  position  'inx'.  Then  insert 

*  the  remaining  pattern  with  what’s  left  of  the  input  string.  Backtrack 

*  the  replacement  string  at  position  'inx'. 

*  until  we've  either  matched  the  remaing  pattern  or  we  arrive  back  at  where 

*/ 

*  we  started. 

char  *  pascal  do  sub  (char  *str,  int  inx,  int  len,  char  ‘replace)  { 

*/ 

char  *p; 

int  pascal  match  closure  (int  inx,  char  *s,  char  *pat,  char  ‘clopat)  ( 

char  *  pascal  makesub  (char  ‘replace,  char  ‘found,  int  len) ; 

char  *save_s  =  s; 

p  =  makesub  (replace,  Sstr[inx],  len); 

if  (match  term  (inx,  s,  clopat)  ==  TRUE)  ( 

strdel  (str,  inx,  len) ; 

save  s  =  s  end; 

strins  (str,  p,  inx); 

if  (match  closure  (inx,  save  s,  pat,  clopat)  ==  TRUE) 

return  (p) ; 

return  (TRUE); 

)  /*  do  sub  */ 

else 

return  (match  term  (inx,  save  s,  pat+2+* (pat+1) ) ) ; 

/* 

} 

*  Make  a  substitution  string. 

else  if  (*pat  !=  CLOSURE) 

*/ 

return  (FALSE) ;  /*  POS  CLO  requires  at  least  one  match  */ 

char  *  pascal  makesub  (char  ‘replace,  char  ‘found,  int  len)  ( 

else  if  (match  term  (inx,  save  s,  pat+2+* (pat+1) )  ==  TRUE) 

char  news [MAXSTR] ; 

return  (ALMOST) ; 

char  *c  =  replace; 

else 

return  (FALSE) ; 

int  x; 

}  /*  match_closure  */ 

news [0]  =  ENDSTR; 
while  (*C  ! =  ENDSTR)  ( 

/* 

if  ( *c  ==  ' s' ) 

*  Match  a  character  class  or  negated  character  class 

for  (x  =0;  x  <  len;  x++) 

*/ 

strccat  (news,  found[x]); 

int  pascal  match  ccl  (char  c,  char  *pat)  ( 

else  if  (*c  ==  ' \ \ ' )  ( 

register  int  x; 

re  ptr  *  c+1; 

char  ccl  =  *pat++; 

strccat  (news,  parse_escape  ()); 
c  =  re  ptr  -  1; 

for  (x  =  ‘pat;  x  >  0;  x — ) 

) 

if  (c  »=  pat [x] ) 

else 

return  (ccl  ==  CCL) ; 

strccat  (news,  *c) ; 

return  (ccl  !=  CCL); 

C++; 

}  /*  match_ccl  */ 

) 

return  (strdup  (news)); 

/* 

1  /*  makesub  */ 

*  Substitue  'replace'  for  the  leftmost  longest  substring  of  str  matched  by 

*  the  regular  expression  re. 

/* 

*  Return  number  of  substitutions  made  (which  in  this  case  will  be  0  or  1) . 

*  split  -  split  the  string  s  into  fields  in  the  array  a  on  field  separator  fs. 

*/ 

*  fs  is  a  regular  expression.  Returns  number  of  fields.  Also  sets  the  global 

int  pascal  sub  (char  *re,  char  ‘replace,  char  *str)  ( 

*  variable  NF.  This  routine  compiles  fs  into  a  pattern  and  then  calls 

*  re  split ()  to  do  the  work. 

if  (match  (str,  re)  !=  NULL)  ( 

*/ 

free  (do  sub  (str,  RSTART,  RLENGTH,  replace)); 

int  pascal  split  (char  *s,  char  “a,  char  * f s )  ( 

return  (1); 

char  pat [MAXPAT]; 

else 

pat [ 0]  =  ENDSTR; 

return  (0) ; 

makepat  (fs,  pat); 

}  /*  sub  */ 

return  re  split  (s,  a,  pat); 

)  /*  split  */ 

*  Substitue  'replace'  for  the  leftmost  longest  substring  of  str  matched  by 

/* 

*  the  compiled  regular  expression  pat. 

*  re  split ()  -  split  the  string  s  into  fields  in  the  array  on  field  seperator 

*  Return  number  of  substitutions  made  (which  in  this  case  will  be  0  or  1) . 

*  pat.  pat  is  a  compiled  regular  expression  (built  by  makepatO).  Returns 

*/ 

*  number  of  fields.  Also  sets  the  global  variable  NF. 

int  pascal  re  sub  (char  *pat,  char  ‘replace,  char  *str)  { 

*/ 

int  pascal  re  sub  (char  ‘pat,  char  ‘replace,  char  *str); 

int  pascal  re  split  (char  *s,  char  “a,  char  *pat)  { 

int  rstart  =  RSTART;  /*  save  RSTART  and  RLENGTH  */ 

if  (re  match  (str,  pat)  !=  NULL)  { 

int  rlength  =  RLENGTH; 

free  (do  sub  (str,  RSTART,  RLENGTH,  replace)); 

char  ‘c  =  s; 

return  (1); 

char  *oldc  =  s; 

else 

NF  =  0; 

return  (0); 

if  (a [0]  ! =  NULL) 

)  /*  re  sub  */ 

free  ( a [ 0 ] ) ; 

a [ 0 ]  =  strdup  (s) ; 

*  Substitute  'replace'  globally  for  all  substrings  in  str  matched  by  the 

while  (‘oldc  !=  ENDSTR)  ( 

*  regular  expression  re. 

while  ( (c  =  re  match  (oldc,  pat))  ==  oldc) 

*  Return  number  of  substitutions  made. 

oldc  +=  RLENGTH; 

* 

if  (‘oldc  ! *  ENDSTR)  ( 

*  This  routine  uses  makepatO  to  compile  the  regular  expression,  then  calls 

*  re_gsub()  to  do  the  actual  replacement. 

*  NOTE:  gsub()  makes  only  1  pass  through  the  string.  Replaced  strings 

if  (c  ==  NULL) 

c  =  4oldc[strlen  (oldc)]; 

if  (a [++NF]  !=  NULL) 

a [NF]  =  realloc  (a [ NF] ,  c-oldc+1); 

*  cannot  themselves  be  replaced. 

else 

*/ 

a [NF]  =  malloc  (c-oldc+1); 

int  pascal  gsub  (char  *re,  char  ‘replace,  char  *str)  ( 

memcpy  (a [NF ] ,  oldc,  c-oldc) ; 

int  pascal  re_gsub  (char  ‘pat,  char  ‘replace,  char  *str); 

a[NF] [c-oldc]  =  ENDSTR; 
oldc  =  c; 

char  pat [MAXPAT] ; 

) 

pat [0]  =  END STR; 

RSTART  =  rstart;  /*  restore  globals  */ 

if  (makepat  (re,  pat)  ==  NULL) 

RLENGTH  =  rlength; 

return  (0); 

return  (NF) ; 

return  (re  gsub  (pat,  replace,  str)); 

)  /*  re  split  */ 

}  /*  gsub  */ 

*  Substitute  'replace'  globally  for  all  substrings  in  str  matched  by  the 

*  compiled  regular  expression  pat. 

*  Reads  a  line  from  infile  and  splits  it  into  FIELDS.  Returns  EOF  on 

*  end-of-file  or  error. 

*  Return  number  of  substitutions  made. 

int  pascal  getline  (char  *s,  int  nchar,  FILE  ‘infile)  ( 

*  NOTE:  gsub()  makes  only  1  pass  through  the  string.  Replaced  strings 

char  *c; 

if  (fgets  (s,  nchar,  infile)  ==  NULL) 

*/ 

int  pascal  re_gsub  (char  ‘pat,  char  ‘replace,  char  *str)  ( 

return  (EOF) ; 

if  ( (c  =  strchr  (s,  ' \n' ) )  !=  NULL) 

*c  =  ENDSTR;  /*  look  for  and  replace  newline  */ 

char  *p; 

re_split  (s,  FIELDS,  FS_PAT) ; 
return  (0); 

while  ( (m  =  re  match  (m,  pat))  !=  NULL)  ( 

)  /*  getline  */ 

p  =  do  sub  (m,  0,  RLENGTH,  replace) ; 

m  +=  strlen  (p) ; 

*  add  a  character  to  the  end  of  a  string 

free  (p) ; 

return  (nsub) ; 

)  /*  re_gsub  */ 
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Listing  Three  (Listing  continued,  text  begins  on  page  64.) 


char  *  pascal  strccat  (char  *s,  int  ch)  { 
register  int  len  =  strlen  (s); 
s[len++]  =  ch; 
s [len]  =  ENDSTR; 
return  (s); 


*  removes  the  character  at  pos  from  the  string. 
*/ 

char  *  pascal  strcdel  (char  *s,  int  pos)  { 

memcpy  (s+posf  s+pos+1,  strlen  (s)  -pos); 
return  (s) ; 

]  /*  strcdel  */ 


*  inserts  the  character  ch  into  the  string  at  position  pos.  Assumes  there 

*  is  room  enough  in  the  string  for  the  character. 

*/ 

char  *  pascal  strcins  (char  *s,  int  ch,  int  pos)  { 
memmove  (s+pos+1,  s+pos,  strlen  (s)  -  pos  +  1); 
s[pos]  =  ch; 
return  (s); 


*  removes  n  characters  from  s  starting  at  pos 
*/ 

char  *  pascal  strdel  (char  *s,  int  pos,  int  n)  { 
memcpy  (s+pos,  s+pos+n,  strlen (s) -pos-n+1) ; 
return  (s); 


*  inserts  the  string  i  into  the  string  s  at  position  pos.  Assumes  there 

*  is  sufficient  memory  in  s  to  hold  i. 

*/ 

char  *  pascal  strins  (char  *s,  char  *i,  int  pos)  f 
char  *p  =  s+pos; 
int  ilen  =  strlen  (i); 

memmove  (p+ilen,  p,  strlen  (s)  -  pos  +  1); 
memcpy  (p,  i,  ilen); 
return  (s); 


End  Listings 


Listing  One  (Text  begins  on  page  72.) 

UNIT  TSRUnit;  (Create  TSR  programs  with  Turbo  Pascal  5.0  4  TSRUnit) 

INTERFACE  | =================== - - ========================== } 

( 

The  author  and  any  distributor  of  this  software  assume  no  responsi¬ 
bility  for  damages  resulting  from  this  software  or  its  use  due  to 
errors,  omissions,  incompatibility  with  other  software  or  with 
hardware,  or  misuse;  and  specifically  disclaim  any  implied  warranty 
of  fitness  for  any  particular  purpose  or  application. 

) 

USES  DOS,  CRT; 

CONST 

(***  Shift  key  combination  codes.  ) 

AltKey  =  8;  CtrlKey  =  4;  LeftKey  =  2;  RightKey  =  1; 


TSRVersion  :  WORD  =  $0203; 


(Low  byte. High  byte  =2.03 


TYPE 

String80  =  STRING [80]; 

ChrWords  =  RECORD  CASE  INTEGER  OF 
1:  (  W:  WORD  ); 

2:  (  C:  CHAR;  A:  BYTE  )  ; 

END; 

LineWords  =  ARRAY[1..80]  OF  ChrWords; 
WordFuncs  =  FUNCTION  :  WORD; 


VAR 

TSRScrPtr 

TSRChrPtr 

TSRMode 

TSRWidth 

TSRPage 

TSRColumn 

TSRRow 


(Pointer  to  saved  screen  image. 

(Pointer  to  first  character  to  insert. 

(Video  mode - before  TSR  popped  up 

(Number  of  screen  columns —  "  "  "  " 

[Active  video  page  number—  "  "  "  " 

(Cursor  column  number - "  "  "  " 

(Cursor  row  number - ”  ”  "  "  , 


**  Procedure  for  installing  the  TSR  program.  ) 

PROCEDURE  TSRInstalK  TSRName  :  STRING;  (Name  or  title  for  TSR.  ) 
TSRFunc  :  WordFuncs; (Ptr  to  FUNCTION  to  call) 
ShiftComb:  BYTE;  (Hot  key — shift  key  comb) 
KeyChr  :  CHAR  );  (Hot  Key — character  key.) 

{ 

ShiftComb  and  KeyChr  specify  the  default  hot  keys  for  the  TSR. 
ShiftComb  may  be  created  by  adding  or  ORing  the  constants  AltKey, 
CtrlKey,  LeftKey,  and  RightKey  together.  KeyChr  may  be 
characters  0-9  and  A-Z. 

The  default  hot  keys  may  be  overridden  when  the  TSR  is  installed 
by  specifying  optional  parameters  on  the  command  line.  The 
parameter  format  is: 

[/A]  I/C)  [/R]  [/L]  [/"  [Kf]  ]  ] 

The  square  brackets  surround  optional  items — do  not  include  them. 
Any  characters  between  parameters  are  ignored.  The  order  of  the 


characters  does  not  matter;  however,  the  shift  keys  specified  are 
cummulative  and  the  last  character  key  "K"  specified  is  the  used. 


**  Functions  for  checking  status  of  printer  LPT1 .  } 

FUNCTION  PrinterOkay:  BOOLEAN;  (Returns  TRUE  if  printer  is  okay.) 
FUNCTION  PrinterStatus :  BYTE;  (Returns  status  of  printer. 

Definition  of  status  byte  bits  (142  are  not  used),  if  set  then: 

Bit:  —  7  —  - 6 -  —  5 -  —  4  —  —  3  —  —  0  — 

Not  busy  Acknowledge  No  paper  Selected  I/O  Err.  Timed-out 


**  Routines  for  obtaining  one  row  of  screen  characters.  } 

FUNCTION  ScreenLineStr (  Row:  BYTE  ):  String80;  (Returns  char,  str.) 
PROCEDURE  ScreenLine(  Row:  BYTE;  VAR  Line:  LineWords;  (Returns  ) 
VAR  Words:  BYTE  );  (chr  4  color) 


End  Listing  One 


Listing  Two 


PROGRAM  TSRDemo;  (An  example  TSR  program  created  using  TSRUnit.  } 

($M  $0800,0,0)  (Set  stack  and  heap  size  for  demo  program.  ) 

USES  CRT,  DOS,  TSRUNIT;  (Specify  the  TSRUNIT  in  the  USES  statement.) 

(Do  not  use  the  PRINTER  unit,  instead  treat) 
(the  printer  like  a  file;  i.e.  use  the  ) 
(Assign,  Rewrite,  and  Close  procedures.  } 

CONST  DemoPgmName  :  STRING[16]  =  'TSR  Demo  Program'; 

VAR 

Lst  :  TEXT;  (Define  variable  name  for  the  printer.  ) 

TextFile  :  TEXT;  (  "  "  "  "  a  data  file.  } 

InsStr  :  STRING;  (Storage  for  characters  to  be  inserted  into) 

(keyboard  input  stream — must  be  a  gobal  or  ) 
(heap  variable.  } 


FUNCTION  IOError :  BOOLEAN;  (P 
VAR  i  :  WORD;  (o 

BEGIN 

i  :=  IOResult; 

IOError  :=  FALSE; 

IF  i  <>  0  THEN  BEGIN 
Writeln('I/0  Error  No.  ',i); 
IOError  :=  TRUE; 

END; 


(Provides  a  message  when  an  I/O  error) 
(occurs.  } 
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END;  (OurlOResult. } 


{ 

*****  Demo  routine  to  be  called  when  TSRDemo  is  popped  up. 

be  compiled  as  a  FAR  FUNCTION  that  returns  a  WORD  containing 
the  number  of  characters  to  insert  into  the  keyboard  input 
stream. 

} 

1 $F+ )  FUNCTION  DemoTasks:  WORD;  {$F-} 

CONST 

FileName  :  STRING[13]  =  '  : TSRDemo. Dat ' ; 

EndPos  =  40; 

Wxl  =  15;  Wyl  -  2;  Wx2  =  65;  Wy2  =  23; 

VAR 

Key,  Drv  :  CHAR; 

Done,  IOErr  :  BOOLEAN; 

InputPos,  RowNumb  :  INTEGER; 

DosVer  :  WORD; 

Inputstring  ;  STRING; 

PROCEDURE  ClearLine;  {Clears  current  line  and  resets  line  pointer) 
BEGIN 

Inputstring  :=  ";  InputPos  :=  1; 

GotoXY (  1,  WhereY  );  ClrEol; 

END; 

BEGIN 

DemoTasks  :=  0;  {Default  to  0  characters  to  insert.) 

Window(  Wxl,  Wyl,  Wx2,  Wy2  );  {Set  up  the  screen  display.  ) 

TextColor(  Black  ); 

TextBackground(  LightGray  ); 

LowVideo; 

ClrScr;  {Display  initial  messages.  ) 

Writeln; 

Writeln ('  Example  Terminate  &  Stay-Resident  (TSR)  program'); 
Writeln  ('  --written  with  Turbo  Pascal  5.0  and  uses  TSRUnit.'); 
Window (  Wxl’-l,  Wyl  +  4,  Wx2-1,  Wyl+12)  ; 

TextColor  (  LightGray  ) ; 

TextBackgroundl  Black  ) ; 

ClrScr;  {Display  function  key  definitions.  } 

Writeln; 

Writeln  ('  Function  key  definitions:'); 

Writeln {'  [FI]  Write  message  to  TSRDEMO.DAT' ) ; 

Writeln('  [F2 ]  "  "  to  printer. ') ; 

Writeln  ('  [F3]  Read  from  saved  screen.'); 

Writeln  {'  [F8]  Exit  and  insert  text.'); 

Writeln {'  [F10]  Exit  TSR  and  keep  it.'); 

Write  {  '  or  simply  echo  your  input.'); 

{Create  active  display  window.  ) 

Window!  Wxl+1,  Wyl+14,  Wx2-1,  Wy2-1  ); 

ClrScr; 

(Display  system  information.  ) 

Writeln ('TSRUnit  Version:  ',  Hi (TSRVersion) : 8,  '.', 


Lo (TSRVersion) :2  ); 

Writeln ('Video  Mode,  Page:',  TSRMode: 4,  TSRPage:4  ); 

Writeln {'Cursor  Row,  Col.:',  TSRRow:4,  TSRColumn:4  ); 

DosVer  :=  DosVersion; 

Writeln ('DOS  Version:  ',  Lo (DosVer) : 8,  '.',  Hi(DosVer):2  ); 

Inputstring  :=  ";  {Initialize  variables.  ) 

InputPos  :=  1; 

Done  :=  False; 

REPEAT  {Loop  for  processing  keystrokes.  ) 

GotoXY (  InputPos,  WhereY  );  (Move  cursor  to  input  position.  ) 

Key  :=  ReadKey;  (Wait  for  a  key  to  be  pressed.  ) 

IF  Key  =  #0  THEN  BEGIN  (Check  for  a  special  key.  ) 

Key  :=  ReadKey;  (If  a  special  key,  get  auxiliary) 

CASE  Key  OF  (byte  to  identify  key  pressed.  ) 

(Cursor  Keys  and  simple  editor.) 

(Home)  #71:  InputPos  :=  1; 

(Right)  #75:  IF  InputPos  >  1  THEN  Dec (  InputPos  ); 

(Left)  #77:  IF  (InputPos  <  Length!  Inputstring  )) 

OR  ((InputPos  =  Length (  Inputstring  )) 

AND  (InputPos  <  EndPos  ))  THEN  Inc (  InputPos  ); 

(End)  #79:  BEGIN 

InputPos  :=  Succ(  Length(  Inputstring  )  ); 

IF  InputPos  >  EndPos  THEN  InputPos  :=  EndPos; 

END; 

(Del)  #83:  BEGIN 

Delete!  Inputstring,  InputPos,  1  ); 

Write (  Copy(  Inputstring,  InputPos,  EndPos  ),  '  '); 

END; 

(Function  Keys — TSRDemo' s  special  features.) 

(FI)  #59:  BEGIN  {Write  short  message  to  a  file.  ) 

ClearLine; 

REPEAT 

Write('Enter  disk  drive:  ', FileName [ 1]  ); 

Drv  :=  UpCase(  ReadKey  );  Writeln; 

IF  Drv  <>  #13  THEN  FileName [1]  :=  Drv; 

Writeln (' Specifying  an  invalid  drive  will  cause  your'); 
Write (' system  to  crash.  Use  drive  ', 

FileName [1],  ?  [y/N]  '); 

Key  :=  UpCase(  ReadKey  );  Writeln(  Key  ); 

UNTIL  Key  =  'Y'; 

Writeln (' Writing  to  ', FileName  ); 

{$1-)  (Disable  I/O  checking.) 

Assign (  TextFile,  ' TSRDemo. Dat'  ); 

IF  NOT  IOError  THEN  BEGIN  (Check  for  error.  } 
Rewrite!  TextFile  ); 

IF  NOT  IOError  THEN  BEGIN 

Writeln (TextFile, ' File  was  written  by  TSRDemo.'); 


TSR  PROGRAMS 


Listing  Two  (Listing  continued,  text  begins  on  page  72.) 

IOErr  :=  IOError; 

Close)  TextFile  ); 

IOErr  :=  IOError; 

END; 

END; 

{$I+(  (Enable  standard  I/O  checking.) 

Writeln (' Completed  file  operation.'); 

END;  (FI) 

(F2)  #60:  BEGIN  (Print  a  message,  use  TSRUnit's  auxiliary  ) 

(function  PrinterOkay  to  check  printer  status.  ) 
ClearLine; 

Writeln ('Check  printer  status,  then  print  if  okay.'); 

IF  PrinterOkay  THEN  BEGIN  {Check  if  printer  is  okay) 

Assign (  Lst,  'LPT1'  );  (Define  printer  device.  ) 

Rewrite!  Lst  );  (Open  printer.  ) 

Writeln  (  Lst,  'Printing  performed  from  TSRDemo'); 

Closet  Lst  );  (Close  printer.  ) 

END 

ELSE  Writeln {' Printer  is  not  ready.'); 

Writeln!  'Completed  print  operation.'  ); 

END;  (F2) 

(F3)  #61:  BEGIN  (Display  a  line  from  the  saved  screen  image — not) 

(valid  if  the  TSR  was  popped  up  while  the  ) 

(display  was  in  a  graphics  mode.  ) 

ClearLine; 

CASE  TSRMode  OF  (Check  video  mode  of  saved  image.) 

0.  .3, 

7:  BEGIN 
($I~) 

REPEAT 

Writeln ('Enter  row  number  [1-25]  from  '); 

Write ('which  to  copy  characters:  '); 

Readln (  RowNumb  ) ; 

UNTIL  NOT  IOError; 

($1+) 

IF  RowNumb  <=  0  THEN  RowNumb  :=  1; 

IF  RowNumb  >25  THEN  RowNumb  :=  25; 

Writeln(  ScreenLineStr (  RowNumb  )  ); 

END; 

ELSE  Writeln('Not  valid  for  graphics  modes.'); 

END;  (CASE  TSRMode) 

END;  { F3 ) 

(F8)  #66:  BEGIN  {Exit  and  insert  string  into  keyboard  buffer.) 

ClearLine; 

Writeln ('Enter  characters  to  insert;'); 

Writeln ('Up  to  255  character  may  be  inserted.'); 

Writeln ('Terminate  input  string  by  pressing  [F8] . ' ) ; 

InsStr  :=  "; 

REPEAT  {Insert  characters  into  a) 

Key  :=  ReadKey;  (until  [F8]  is  pressed.  } 

IF  Key  =  #0  THEN  BEGIN  {Check  for  special  key.) 


Key  :=  ReadKey;  (Check  if  key  is  [F8] .  ) 

IF  Key  =  #66  THEN  Done  :=  TRUE;  ( [F8]  so  done.  ) 

END 

ELSE  BEGIN  (Not  special  key,  add  it  to  the  string.) 

IF  Length (InsStr)  <  Pred (SizeOf (InsStr) )  THEN 
BEGIN 

IF  Key  =  #13  THEN  Writeln 
ELSE  Write  (  Key  ); 

InsStr  :=  InsStr  +  Key; 

END 

ELSE  Done  :=  TRUE;  (Exceeded  character  limit.  ) 

END; 

UNTIL  Done; 

DemoTasks  :  =  Length!  InsStr  );  (Return  no.  of  chr.  ) 

TSRChrPtr  :=  @InsStr[l];  (Set  ptr  to  lst  chr.) 

END;  (F8 ) 

( FI 0 )  #68:  Done  :=  TRUE;  (Exit  and  Stay-Resident.  ) 

END;  (CASE  Key) 

END  {IF  Key  =  #0) 

ELSE  BEGIN  {Key  pressed  was  not  a  special  key— just  echo  it.  ] 

CASE  Key  OF 

IBS)  #08:  BEGIN  (Backspace) 

IF  InputPos  >  1  THEN  BEGIN 
Dec (  InputPos  ) ; 

Delete  (  Inputstring,  InputPos,  1  ); 

GotoXY  (  InputPos,  WhereY  ); 

Write!  Copy(  Inputstring,  InputPos,  EndPos  ),  '  '); 

END; 

END;  (BS) 

(CR)  #13:  BEGIN  (Enter) 

Writeln; 

Ir.putString  :=  "; 

InputPos  :=  1; 

END;  {CR) 

(Esc)  #27;  ClearLine; 

ELSE 

IF  Length (  Inputstring  )  >=  EndPos  THEN 
Delete (  Inputstring,  EndPos,  1  ); 

Insert (  Key,  Inputstring,  InputPos  ); 

Write!  Copy(  Inputstring,  InputPos,  EndPos  )  ); 

IF  InputPos  <  EndPos  THEN 
Inc(  InputPos  ); 

END;  (CASE...) 

END;  (ELSE  BEGIN--Key  <>  #0) 

UNTIL  Done; 

END ;  ( DemoTasks . ) 

BEGIN 

TSRInstallf  DemoPgmName,  DemoTasks,  AltKey,  'E'  ); 
end  .  ( TSRDemo . )  End  Listings 
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Listing  One  (Text  begins  on  page  76.) 

int  yyact[) 

5 

=  ( 

13 

4 

8 

Q. 

3 

1, 

yacc  specification 

2, 

o! 

o’ 

o', 

o! 

12, 

10, 

11, 

4, 

0, 

3, 

2, 

0, 

0, 

0, 

o, 

0, 

0, 

0, 

0, 

0, 

0, 

o, 

o, 

/*  TEST.Y 

0, 

0, 

8, 

o, 

0, 

0, 

o, 

o, 

0, 

0, 

0, 

0, 

o, 

0, 

o, 

o, 

This  specification  is  based  largely  on  the  yacc 

0, 

0, 

0, 

0, 

o, 

0, 

o, 

0, 

specification  for  a  simple  desk  calculator  from  "Compilers: 

0, 

0, 

0, 

0, 

o, 

0, 

0, 

0, 

Principles,  Techniques  and  Tools,"  by  Aho,  et  al.  (p.  259, 

0, 

0, 

0, 

0, 

o, 

o, 

0, 

o, 

Addison-Wesley,  1986) . 

0, 

0, 

0, 

o. 

0, 

o, 

o, 

o, 

0, 

0, 

0, 

o, 

0, 

o, 

o, 

o, 

2/2/89  a. lane 

0, 

0, 

0, 

0, 

c, 

0, 

0, 

0, 

*/ 

0, 

0, 

0, 

o, 

c. 

o, 

0, 

0, 

0, 

0, 

o, 

o, 

0, 

o, 

0, 

o, 

%( 

o, 

o, 

0, 

0, 

o, 

0, 

0, 

0, 

♦include  <stdio.h> 

o, 

o, 

o, 

o, 

0, 

o, 

0, 

0, 

♦include  <ctype.h> 

o. 

0, 

o, 

o, 

0, 

0, 

0, 

o, 

%} 

o, 

0, 

0, 

0, 

o, 

0, 

0, 

0, 

0, 

o, 

o, 

o, 

0, 

0, 

0, 

o, 

%token 

DIGIT 

o, 

0, 

o, 

o, 

0, 

o, 

0, 

o, 

%left 

+  ' 

o, 

0, 

0, 

o, 

o, 

0, 

0, 

0, 

%left 

*' 

o, 

o, 

o, 

o, 

0, 

o, 

0, 

0, 

0, 

0, 

0, 

o, 

o, 

o, 

o, 

0, 

%% 

0, 

o, 

0, 

0, 

o, 

0, 

o, 

o, 

0, 

o, 

0, 

o, 

0, 

o, 

o, 

o, 

line 

/*  nothing  */ 

o. 

o, 

0, 

0, 

o, 

0, 

o, 

o, 

expr  '\n'  (  printf ("%d\n”,  $1);  ) 

o, 

o, 

o, 

6, 

o, 

o, 

0, 

0, 

0, 

0, 

expr 

expr  '+'  term  (  $$  =  $1  +  $3;  ) 

}; 

term 

int  yypact[] 

-  [ 

term 

term  '*'  factor  {  $$  =  $1  *  $3;  } 

-40, 

-1000, 

-9, 

-37, 

-1000, 

-40, 

-1000, 

-1000, 

factor 

-40, 

}  ; 

-40, 

-39, 

-37, 

-1000, 

-1000, 

factor 

' ('  expr  ' ) '  {  $$  -  $2;  } 

DIGIT 

int  yypgo [ ] 

-  { 

0, 

7, 

8, 

6, 

3, 

%% 

}; 

main  () 

{ 

yyparse () ; 

int  yyrl []  = 

{ 

) 

0, 

4( 

1, 

1, 

2, 

2, 

3, 

3, 

4, 

yyiex ( 

{ 

}; 

int  c; 

if  (  isdigit (  (  c  =  getcharO  )  )  )  I 

int  yyr2[]  = 

I 

yylval  =  c  -  'O'; 

2, 

o, 

2, 

3, 

1, 

3, 

1, 

3, 

return  DIGIT; 

1, 

}; 

i 

return  c; 

} 

int  yychk[) 

=  { 

-1000, 

-1, 

-2, 

-3, 

-4, 

40, 

257, 

10, 

yyerror (s) 

43, 

42, 

-2, 

-3, 

-4, 

41, 

char  *£ 

; 

I; 

t 

fprintf [stderr,  "PYERR:  %s\n",  s) ; 

int  yydef[) 

=  ( 

} 

1, 

-2, 

0, 

4, 

6, 

0, 

8, 

2, 

0, 

o. 

0, 

3, 

5, 

7, 

I; 


End  Listing  One 


int 


*yyxi; 


Listing  Two 

♦  line  11  "test.y" 

♦include  <stdio.h> 

♦include  <ctype.h> 

♦define  DIGIT  257 
♦ifndef  YYSTYPE 
♦define  YYSTYPE  int 
♦endif 

YYSTYPE  yylval,  yyval; 

♦define  YYERRCODE  256 

♦  line  33  "test.y" 

main()  { 
yyparse () ; 

} 

yyiex  o  { 
int  c; 

if  (  isdigit  (  (  c  =  getcharO  )  )  ) 
yylval  =  c  -  'O'; 
return  DIGIT; 

} 

return  c; 

} 

yyerror (s) 
char  *s; 

{ 

fprintf (stderr,  "PYERR:  %s\n",  s) ; 

) 

FILE  *yytfilep; 
char  *yytfilen; 
int  yytflag  =  0; 
int  svdprd[2); 
char  svdnams [2] (2] ; 


/*  PCYACC  LALR  parser  driver  routine  —  a  table  driven  procedure  */ 


/*  for  recognizing  sentences  of  a  language  defined  by  the  */ 
/*  grammar  that  PCYACC  analyzes.  An  LALR  parsing  table  is  then  */ 
/*  constructed  for  the  grammar  and  the  skeletal  parser  uses  the  */ 
/*  table  when  performing  syntactical  analysis  on  input  source  */ 
/*  programs.  The  actions  associated  with  grammar  rules  are  */ 
/*  inserted  into  a  switch  statement  for  execution.  */ 


♦ifndef  YYMAXDEPTH 
♦define  YYMAXDEPTH  200 
♦endif 

♦ifndef  YYREDMAX 
♦define  YYREDMAX  1000 
♦endif 

♦define  PCYYFLAG  -1000 

♦define  WAS0ERR  0 

♦define  WAS 1 ERR  1 

♦define  WAS2ERR  2 

♦define  WAS 3 ERR  3 

♦define  yyclearin  pcyytoken  =  -1 

♦define  yyerrok  pcyyerrfl  =  0 

YYSTYPE  yyv [ YYMAXDEPTH ) ;  /*  value 

int  pcyyerrct  =  0;  /*  error 

int  pcyyerrfl  =0;  /*  error 

int  redseq ( YYREDMAX ] ; 

int  redcnt  =  0; 

int  pcyytoken  =  -1;  /*  input 


stack  */ 
count  */ 
flag  */ 


token  */ 


yyparse () 

( 

int  statestack [YYMAXDEPTH) ;  /*  state  stack  */ 
int  j,  m;  /*  working  index  : 

YYSTYPE  *yypvt; 

int  tmpstate,  tmptoken,  *yyps,  n; 

YYSTYPE  *yypv; 


/ 


int  yyexca [ ]  =  [ 

-1,  1, 

0,  -1, 

-2,  0, 

0, 


tmpstate  =  0; 
pcyytoken  =  -1; 
♦ifdef  YYDEBUG 


♦define  YYNPROD  9 
♦define  YYLAST  218 
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tmptoken  =  -1; 
fendif 

pcyyerrct  =  0; 
pcyyerrfl  =  0; 
yyps  =  Sstatestack [-1] ; 
yypv  =  &yyv[-l] ; 


enstack:  /*  push  stack  */ 

fifdef  YYDEBUG 

printf  ("at  state  %a,  next  token  %d\n",  tmpstate,  tmptoken); 
#endif 

if  (++yyps  -  Sstatestack [YYMAXDEPTH]  >  0)  { 
yyerror ( "pcyacc  internal  stack  overflow"); 
return (1) ; 

1 

*yyps  =  tmpstate; 

++yypv; 

*yypv  =  yyval; 
newstate: 

n  »  yypact [tmpstate] ; 

if  {n  <=  PCYYFLAG)  goto  defaultact;  /*  a  simple  state  */ 


if  (pcyytoken  <  0)  if  ( (pcyytoken=yylex () )  <  0)  pcyytoken  =  0; 
if  ((n  +*  pcyytoken)  <0  II  n  >=  YYLAST)  goto  defaultact; 


if  (yychk [n=yyact [n] ]  ==  pcyytoken)  |  /*  a  shift  */ 

#ifdef  YYDEBUG 

tmptoken  =  pcyytoken; 

#endif 

pcyytoken  =  -1; 
yyval  =  yylval; 
tmpstate  =  n; 

if  (pcyyerrfl  >  0)  — pcyyerrfl; 
goto  enstack; 

} 

defaultact: 

if  ( (n=yydef (tmpstate] )  ■■  -2)  ( 
if  (pcyytoken  <  0)  if  ( (pcyytoken=yylex () ) <0)  pcyytoken  =  0; 
for  (yyxi=yyexca;  (*yyxi!=  (-1))  II  (yyxi [1] !=tmpstate) ;  yyxi  +=  2); 
while  (*(yyxi+=2)  >=  0)  if  (*yyxi  ==  pcyytoken)  break; 
if  ( ( n— yyxi [ 1 ) )  <  0)  (  /*  an  accept  action  */ 
if  (yytf lag)  { 
int  ti;  int  tj; 

yytfilep  =  f open (yytf ilen,  "w"); 
if  (yytfilep  ==  NULL)  ( 

fprintf (stderr,  "Can't  open  t  file:  %s\n",  yytfilen); 


return (0);  ) 

for  (ti=redcnt-l;  ti>=0;  ti — )  ( 
tj  =  svdprd(redseq[ti] ] ; 
while  (strcmp(svdnams [t j] ,  "$EOP")) 

fprintf (yytfilep,  "%s  ",  svdnams [t j++] ) ; 
fprintf (yytf ilep,  "\n"); 

I 

fclose (yytfilep) ; 

) 

return  (0) ; 

1 

1 


if  (n  ==  0)  (  /*  error  situation  */ 

switch  (pcyyerrfl)  ( 

case  WAS0ERR:  /*  an  error  just  occurred  */ 

yyerror ("syntax  error"); 
yyerrlab: 

++pcyyerrct; 
case  WAS1ERR: 

case  WAS2ERR:  /*  try  again  */ 

pcyyerrfl  =  3; 

/*  find  a  state  for  a  legal  shift  action  */ 
while  (yyps  >=  statestack)  { 
n  =  yypact (*yyps)  +  YYERRCODE; 

if  (n  >=  0  &&  n  <  YYLAST  &&  yychk (yyact (n] ]  ==  YYERRCODE)  { 
tmpstate  =  yyact [n];  /*  simulate  a  shift  of  "error"  */ 

goto  enstack; 

I 

n  =  yypact ( *yyps | ; 

/*  the  current  yyps  has  no  shift  on  "error",  pop  stack  */ 
fifdef  YYDEBUG 

printf ("error :  pop  state  %d,  recover  state  %d\n",  *yyps,  yyps[- 

D); 

#endif 

— yyps; 

--yypv; 


yyabort : 

if  (vytflag)  { 
int  ti;  int  tj; 

yytfilep  =  fopen (yytfilen,  "w"); 
if  (yytfilep  ==  NULL)  { 

fprintf (stderr,  "Can't  open  t  file:  %s\n",  yytfilen); 
return  (1);  ) 

for  (ti=l;  ti<redcnt;  ti++)  |  . 

tj  -  svdprd  t  redseq  [  t  i  ]  ] ,  (continued  on  page  112) 


EXAMINING  ROOM 


Listing  Two  (Listing  continued,  text  begins  on  page  76.) 

while  (strcmp (svdnams [tj] ,  "$EOP")) 

fprintf (yytfilep,  "%s  ",  svdnams [tj++] ) ; 
fprintf (yytfilep,  "\n"); 

) 

fclose (yytfilep) ; 


case  WAS3ERR:  /*  clobber  input  char  */ 

#ifdef  YYDEBUG 

printf ("error :  discard  token  %d\n",  pcyytoken); 

iendif 

if  (pcyytoken  ==  0)  goto  yyabort;  /’  quit  */ 
pcyytoken  =  -1; 

goto  newstate;  }  /*  switch  */ 

}  /*  if  */ 


/*  reduction,  given  a  production  n  */ 

#ifdef  YYDEBUG 

printf ("reduce  with  rule  %d\n",  n); 

Kendif 

if  (yytflag  &&  redcnt<YYREDMAX)  redseq [redcnt++]  =  n; 

yyps  -=  yyr2 [n] ; 

yypvt  =  yypv; 

yypv  -=  yyr2 [ n ] ; 

yyval  =  yypv[l]; 

m  =  n; 

/*  find  next  state  from  goto  table  */ 
n  =  yyrl [n] ; 

j  =  yypgo[n]  +  *yyps  +  1; 

if  (j>=YYLAST  ||  yychk [  tmpstate  =  yyact [j]  ]  !=  -n)  tmpstate  = 
yyact [yypgo [n] ]; 

switch  (m)  (  /*  actions  associated  with  grammar  rules  */ 
case  2: 

#  line  22  "test.y" 

(  printf ("%d\n",  yypvt [-1]);  }  break; 
case  3: 

#  line  24  "test.y" 

(  yyval  =  yypvt [-2]  +  yypvt [-0];  )  break; 
case  5: 

#  line  27  "test.y" 

(  yyval  =  yypvt [-2]  *  yypvt [-0];  }  break; 
case  7: 

#  line  30  "test.y" 

{  yyval  =  yypvt [-1];  )  break;  ) 
goto  enstack; 


End  Listings 
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Babbit’s  Guide 
to  OOP 


“He  was  earnest  about  these  objects. 
They  were  of  eternal  importance,  like 
baseball  or  the  Republican  Party.  ” 

—  Babbit,  Sinclair  Lewis 

We  appear  to  be  witnessing  the 
mainstreaming  of  object-ori¬ 
ented  programming.  Regard¬ 
less  of  the  actual  number  of 
lines  of  code  written  this  year  or  the 
next  in  object-oriented  languages  as 
compared  with  other  languages,  it  looks 
as  though  object-oriented  programming 
is  on  the  verge  of  becoming  the  domi¬ 
nant  programming  paradigm  in  per¬ 
sonal  computer  software  development. 
An  area  that  had  recently  been  a  fron¬ 
tier  has  now  nearly  been  cleared  for 
farming,  4-H,  and  the  Rotary  Club. 

Although  DDJ  has  been  investigat¬ 
ing  OOP  techniques  and  the  implica¬ 
tions  of  the  paradigm  for  some  time 
now,  you’ll  be  seeing  more  detail  in 
the  near  future  as  we  cover  this  phe¬ 
nomenon.  In  April,  Mike  Floyd’s  article 
set  the  stage  on  getting  started  in  object- 
oriented  programming.  In  the  coming 
months,  Kent  and  Jeff  will  be  analyzing 
significant  new  developments  in  OOPs. 
This  month’s  “Programming  Paradigms” 
is  a  sort  of  bridge  between  Mike’s  piece 
and  greater  OOP  coverage  coming  in 
DDJ  in  that  it  defines  some  basic  terms 
and  points  out  some  of  the  chief  issues 
in  OOP  without  attempting  to  draw 
any  deep  conclusions. 

Tell  Me  Again,  What  Is 
Object-Oriented  Programming? 

Object-oriented  programming  (or  soft¬ 
ware  design)  is  “the  construction  of 


Michael  Swaine 


software  systems  as  structured  collec¬ 
tions  of  abstract  data-type  implementa¬ 
tions,”  according  to  Bertrand  Meyer.  It 
is  a  programming  paradigm  in  which  the 
emphasis  is  on  the  thing  to  be  manipu¬ 
lated  rather  than  on  the  functions  to  be 
performed.  The  things  to  be  manipu¬ 
lated  are  represented  as  abstract  data¬ 
type  representations,  and  these  repre¬ 
sentations  are  called  classes,  that’s  why 


Mike  Floyd  said  in  April  that  OOP  could 
be  called  Class-Oriented  Programming. 

Defining  “object”  to  mean  “an  in¬ 
stance  of  an  abstract  data-type  implemen¬ 
tation”  is  a  little  dry;  especially  because 
the  idea  behind  the  concept  of  an  ob¬ 
ject  is  much  more  intuitive  than  this. 
Object-oriented  programming  began 
with  the  language  Simula,  which,  while 
capable  of  much  more,  was  conceived 
as  a  language  for  designing  simula¬ 
tions.  If  you  are  writing  a  simulation 
in  an  object-oriented  language,  the  ob¬ 
jects  of  your  simulation  will  be  exactly 
the  software  simulations  of  the  physi¬ 
cal  objects  in  the  real-world  system 
you  are  simulating.  A  valve,  a  gear,  and 
an  engine  are  all  good  candidates  for 
objects  in  some  systems.  Most  programs 
are  not  direct  simulations  of  real-world 
systems,  but  the  simulation  view  of  an 
object  is  still  useful  to  keep  in  mind 
when  evaluating  candidates  for  ob- 
jecthood.  A  screen,  a  grafPort,  and  a 
window  are  some  less  real  objects. 

Brad  Cox  defines  objects  thus:  “An 
object  is  some  private  data  and  a  set 
of  operations  that  can  access  that  data. 
An  object  is  requested  to  perform  one 
of  its  operations  by  sending  it  a  mes¬ 
sage  telling  the  object  what  to  do.” 
This  sounds  like  applying  a  function 
to  some  data,  hardly  a  revolutionary 
concept  in  programming.  The  differ¬ 
ence  is  all  in  how  the  operation  gets 
matched  to  the  data  on  which  it  oper¬ 
ates.  Because  an  object  is  not  a  data 
structure  or  a  set  of  procedures  but  a 
combination  of  the  two,  a  powerful 
new  approach  to  matching  the  opera¬ 
tion  to  the  data  is  possible.  Messages 
are  the  key. 

A  message  is  a  function  call  with  a 
specified  receiver.  Sending  the  message 
triggers  a  selection  mechanism  that  uses 
the  receiver  name  to  branch  to  the  chunk 
of  code  appropriate  to  that  receiver. 
The  technique  is  simple,  but  the  effect 
is  dramatic  in  terms  of  the  division  of 
labor  in  software  development.  When 
a  programmer  writes  code  that  causes 
a  message  to  be  sent  to  an  object,  the 
responsibility  for  ensuring  that  the  op¬ 
eration  is  appropriate  to  the  data  rests 
not  with  the  programmer  but  with  the 


person  who  wrote  the  definition  of  the 
class  to  which  the  object  belongs. 

The  result  is  reusable  software  com¬ 
ponents,  at  least  in  theory.  Everyone 
who  writes  about  object-oriented  pro¬ 
gramming  seems  to  agree  that  the  mo¬ 
tivation  for  using  the  technique  is  some¬ 
thing  like  “increased  productivity,  main¬ 
tainability,  and  reliability  through  reus¬ 
able  software  components”  that  can  be 
plugged  into  new  systems.  These  reus¬ 
able  components  in  OOP  are  classes. 
Classes  in  a  true  object-oriented  system 
are  not  independent  data  types,  but  are 
part  of  one  large  structure  with  the 
structuring  principle  being  inheritance. 

When  a  new  class  is  created,  it  is 
defined  to  be  a  subclass  of  some  exist¬ 
ing  class  and  inherits  all  the  function¬ 
ality  of  the  parent  class.  What  inheri¬ 
tance  buys  you  is  the  ability  to  define 
key  elements  of  the  functionality  of  a 
system  once,  to  use  these  elements  as 
building  blocks,  and  to  do  it  all  smoothly 
and  naturally.  The  smoothness  of  the 
process  is  the  real  advance  that  OOP 
represents;  as  Zack  Urlocker  has  said, 
“Many  programmers  are  pleasantly  sur¬ 
prised  to  find  that  object-oriented  lan¬ 
guages  encourage  them  to  use  tech¬ 
niques  that  they  have  been  faking  for 
years  in  other  languages.” 

Issues  in  Object-Oriented  Programming 

The  preceding  topics  of  objects,  classes, 
messages,  and  inheritance  need  to  be 
discussed  at  the  beginning  of  any  over¬ 
view  of  OOP  because  they  are  funda¬ 
mental  to  an  understanding  of  more 
advanced  topics.  The  order  of  presen¬ 
tation  of  these  other  topics,  however, 
may  depend  on  one’s  particular  view¬ 
point  on  OOP.  I  have  deliberately 
avoided  presenting  them  in  any  of  the 
logical  sequences  in  which  they  could 
be  placed  and  have  instead  treated  each 
issue  as  an  item  unto  itself,  a  sort  of 
reusable  editorial  component.  The  or¬ 
der  is  alphabetical,  and  the  presenta¬ 
tion  is  encyclopedic  in  structure  (though 
not  in  scope). 

Abstract  data  types  —  To  specify 
an  abstract  data  type  is  to  define  a  set 
of  data  structures  strictly  in  terms  of  the 
features  of  the  structures  and  the  op- 
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(continued  from  page  114) 
erations  defined  on  them,  and  not  in 
terms  of  the  actual  physical  implemen¬ 
tation  of  the  data  structure.  Classes  in 
object-oriented  programming  are  ab¬ 
stract  data  types. 

Client  relationship  —  In  addition 
to  the  inheritance  relationship  between 
classes,  one  class  may  be  a  client  of 
another.  This  simply  means  that  the 
implementation  of  the  first  (client)  class 
relies  on  the  second  (supplier)  class, 
for  example,  by  using  objects  belong¬ 
ing  to  the  supplier  class.  Deciding  which 
relationship  should  apply  is  sometimes 
tricky  but  more  often  obvious.  The  class 
HOUSE  would  naturally  inherit  from 
the  class  BUILDING,  but  could  be  a 
client  of  classes  ROOF  and  WALLS. 

Concurrency  —  One  potential  bene¬ 
fit  of  object-oriented  programming  is 
concurrency.  Although  current  object- 
oriented  systems  do  not  provide  for 
concurrency,  the  decision  to  build  a 
system  from  independent  objects  that 
communicate  via  messages  naturally 
suggests  an  implementation  that  uses 
concurrent  processors. 

Dynamic  binding —  Binding  or  link¬ 
ing  is  the  process  of  putting  together 
elements  of  functionality  from  differ¬ 
ent  sources  into  one  executable  image. 
Dynamic  (or  delayed,  or  late)  binding 
is  binding  after  compile  time,  probably 
during  execution.  Dynamic  binding  in 
object-oriented  systems  assigns  to  the 
supplier,  rather  than  to  the  client,  the 
responsibility  for  ensuring  that  an  op¬ 
eration  is  appropriate  to  the  data  on 
which  it  operates. 

Efficiency  —  The  clearest  benefits 
of  object-oriented  programming  are  in 
the  design  of  large  and  complex  sys¬ 
tems.  When  it  comes  to  the  small  de¬ 
tails  of  implementation  that  strongly 
affect  system  performance,  it  seems  to 
be  widely  acknowledged  that  calling  a 
function  is  usually  faster  than  passing 
a  message.  Current  personal  computer 
hardware  could,  with  some  justifica¬ 
tion,  be  referred  to  as  C  machines;  hard¬ 
ware  ideally  suited  to  object-oriented 
programming  has  yet  to  be  brought 
successfully  to  market  and  may  have 
to  wait  for  parallel  architectures.  Lan¬ 
guage  and  operating  system  support 
for  object-oriented  programming  is  on 
the  increase  and  may  be  more  impor¬ 
tant  than  hardware  support,  however, 
as  operating  systems  impose  themselves 
more  and  more  between  the  program¬ 
mer  and  the  hardware. 

Encapsulation  —  To  the  user  of  an 
object  the  data  is  invisible,  the  proce¬ 
dures  for  accessing  and  operating  on 
that  data  is  visible.  This  is  encapsula¬ 
tion,  and  Meyer  has  shown  how  it  can 
be  implemented  in  even  a  non-object- 


oriented  language  such  as  Fortran. 

Hybrid  paradigms  —  Smalltalk  is 
the  best-known  example  of  a  pure  ob¬ 
ject-oriented  programming  system  in 
which  all  actions  are  implemented  as 
messages  sent  to  objects.  Objective  C 
and  C++  are  well-known  hybrids  that 
add  object-oriented  features  to  C  but 
retain  some  non-OOP  features.  The  ar¬ 
guments  usually  advanced  for  the  pure 
approach  are  just  the  arguments  for 
object-oriented  programming:  reliabil¬ 
ity,  maintainability,  and  ease  of  devel¬ 
opment.  The  usual  arguments  for  the 
hybrids  are  familiarity  and  speed. 

Information  hiding  —  Information 
hiding  is  a  desideratum  of  modular  pro¬ 
gramming:  All  information  in  a  module 
should  be  private  to  that  module  unless 
made  public  through  a  definition  known 
as  the  interface.  Encapsulation  is  one 
answer  to  what  should  remain  private 
and  what  should  go  into  the  interface. 

Modularity  —  Meyer  states  five  cri¬ 
teria  of  modularity:  decomposability, 
composability,  understandability,  con¬ 
tinuity,  and  protection.  Modules  should 
aid  in  the  top-down  analysis  of  a  prob¬ 
lem  into  subproblems,  permit  building 
laige  systems  from  smaller  building  blocks, 
be  understandable  on  their  own,  and  be 
sufficiently  separate  from  one  another 
that  a  design  change  or  run-time  ab¬ 
normality  affecting  one  module  will  not 
significantly  affect  the  whole  system. 
The  desire  for  modularity  is  a  primary 
motivation  behind  the  development  and 
use  of  object-oriented  programming. 

Multiple  inheritance  —  Eiffel  has 
it;  most  other  OOPs  don’t.  Multiple  in¬ 
heritance  is  the  capability  for  a  class  to 
inherit  features  from  two  or  more  an¬ 
cestor  classes.  With  only  single  inheri¬ 
tance,  the  inheritance  structure  is  a  tree; 
with  multiple  inheritance,  it’s  a  forest. 
Multiple  inheritance  raises  some  hotly- 
debated  questions,  such  as  how  to  re¬ 
solve  clashes  between  features  of  the 
parent  classes.  Some  cases  of  multiple 
inheritance  are  what  Meyer  calls  mar¬ 
riages  of  convenience  in  which  the  two 
ancestors  complement  each  other 
nicely.  On  the  other  hand,  it  may  be 
convenient  to  create  a  class  that  inher¬ 
its  from  two  parent  classes  that  are  not 
entirely  complementary:  Each  parent 
may  contribute  a  version  of  the  same 
method,  for  example. 

Polymorphism  —  This  is  the  abil¬ 
ity  to  send  the  same  message  to  differ¬ 
ent  objects  and  have  them  respond 
differently. 

Renaming  —  This  is  a  mechanism  that 
permits  references  to  do  the  same  thing 
under  different  names,  depending  on  the 
class  involved.  It  is  used  in  Eiffel  to 
resolve  clashes  in  multiple  inheritance. 

Redefinition  —  This  is  the  mecha¬ 


nism  that  allows  the  client  programmer 
to  use  the  same  name  to  refer  to  differ¬ 
ent  things,  depending  on  the  class  to 
which  it  is  applied.  It  makes  polymor¬ 
phism  possible. 

Repeated  inheritance  —  A  special 
case  of  multiple  inheritance  is  repeated 
inheritance  in  which  one  class  P  is  an 
ancestor  of  another  class  C  in  more 
than  one  way,  possibly  a  direct  ances¬ 
tor.  It  presents  difficulties  beyond  those 
of  ordinary  multiple  inheritance. 

Reusability  —  The  issue  was  stated 
well  by  Meyer:  “Why  isn’t  software  more 
like  hardware?  Why  must  every  new 
development  start  from  scratch?  There 
should  be  catalogs  of  software  mod¬ 
ules,  as  there  are  catalogs  of  VLSI  de¬ 
vices:  When  we  build  a  new  system, 
we  should  be  ordering  components  from 
these  catalogs  and  combining  them,  rather 
than  reinventing  the  wheel  every  time. 
We  would  write  less  software  and  per¬ 
haps  do  a  better  job  at  that  which  we 
do  develop.  Then  wouldn’t  the  prob¬ 
lems  everyone  laments  the  high  costs, 
the  overruns,  the  lack  of  reliability  just 
go  away?  Why  isn’t  it  so?” 

Selective  inheritance  —  While  mul¬ 
tiple  inheritance  is  an  issue  in  OOP, 
selective  inheritance,  the  ability  to  ex¬ 
clude  features  in  inheriting  from  a  class 
is  not.  No  object-oriented  language  im¬ 
plementation  seems  to  support  it,  prob¬ 
ably  because  it  is  a  Pandora’s  box.  But 
selective  inheritance  would  allow  object- 
oriented  systems  to  more  closely  match 
the  world-model  that  we  carry  in  our 
heads.  We  have  no  trouble  thinking  of 
an  ostrich  as  a  flightless  bird,  but  in  the 
object-oriented  aviary  this  is  a  hard 
thought  to  think.  What  we  can  do  is 
use  redefinition  to  make  flight  mean 
something  different  for  this  particular 
bird.  Depending  on  how  you  define 
the  problem  (or  whether  you  think  there 
is  a  problem)  this  may  or  may  not  be  a 
solution. 
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C  PROGRAMMING 


Scripts  for 
SMALLCOM 


Last  month  we  built  a  generic  inter¬ 
preter  of  a  C-like  language  that 
can  be  used  to  support  communi¬ 
cations  scripts  or  editor  macro  pro¬ 
cessing.  The  language  is  called  S,  and 
the  interpreter  is  called  SI.  We  included 
an  example  shell  program  that  you  can 
now  discard.  The  shell  was  to  show 
how  you  surround  the  interpreter  en¬ 
gine  with  a  user  interface  and  intrinsic 
functions  to  give  purpose  to  the  inter¬ 
preted  code.  The  SI  interpreter  engine 
has  no  permanent  dedicated  shell  be¬ 
cause  the  different  custom  shell  pro¬ 
grams  that  you  might  develop  give  each 
use  of  SI  its  purpose.  Therefore,  an  SI 
implementation  will  always  include  the 
development  of  a  custom  shell  program. 

This  month  we  will  build  a  shell  that 
uses  SI  to  implement  a  communica¬ 
tions  script  processor  into  the  SMALL¬ 
COM  program.  The  shell  and  the  inter¬ 
preter  program  link  with  the  rest  of 
SMALLCOM  through  a  hook  in  small- 
com.c.  We  will  need  all  the  code  used 
to  build  SMALLCOM  from  months  past, 
the  files  named  interp.h  and  interp.c 
from  May  1989,  and  the  script. c  file 
included  this  month  as  Listing  One, 
on  page  136.  The  complete  source  code 
package  dates  back  to  September,  1988. 
Each  succeeding  month  is  a  complete 
toolset,  usable  in  many  other  programs, 
and  yet  the  code  from  each  month 
adds  to  the  program  we  are  building. 

A  reader  asked  if  I  have  the  commu¬ 
nications  program  already  completed 
and  am  parcelling  it  out  in  little  chunks. 
The  answer  is  no.  This  program  is  de¬ 
veloping  as  you  watch  it.  I  am  about 
four  months  ahead  of  you,  though;  these 


Al  Stevens 


words  are  being  written  in  February  for 
the  June  issue.  This  incremental  ap¬ 
proach  has  its  pros  and  cons.  On  the 
up  side,  the  code  is  new  and  known 
to  work  with  the  latest  versions  of  the 
Microsoft  and  Turbo  C  compilers,  and 
we  build  new  layers  of  software  draw¬ 
ing  on  our  experiences  with  the  old. 
On  the  down  side,  I  sometimes  find 
that  I  have  coded  myself  into  a  corner. 


In  the  process  of  adding  functions  to 
the  existing  program  I  sometimes  wish 
I  could  make  little  changes  to  the  ear¬ 
lier  code.  In  the  real  world,  you  would 
do  just  that — modify  the  program  to 
fit  the  purpose  of  the  hour.  This,  how¬ 
ever,  is  not  the  real  world.  In  the  con¬ 
tinuing  saga  of  this  column  and  its  pro¬ 
ject,  I  am  trying  to  preserve  the  code 
already  published.  That  is  often  frus¬ 
trating.  As  I  learn  new  and  better  ways 
to  do  things,  I  want  to  go  into  that  old 
code  and  fix  it  up.  Maybe  a  future 
column  can  be  dedicated  to  revisiting 
old  code  and  giving  it  a  polish.  I  have 
always  believed  that  all  software  would 
be  better  if  we  were  allowed  to  write 
it  twice  — once  to  learn  how  it  should 
work  and  once  to  do  the  things  we 
wish  we  had  done  the  first  time  out. 
The  three-piece  suits  tell  me  that  my 
approach  is  not  practical  when  viewed 
from  the  perch  of  the  bottom  line. 

Every  now  and  then  I  have  no  choice 
but  to  fix  some  old  code  from  columns 
past.  For  example,  this  month  I  learned 
that  I  needed  the  file  pointer  for  the 
SMALLCOM  log  file  to  be  external,  rather 
than  static,  so  that  I  could  use  it  from 
within  the  script  processor.  Listing  Two, 
page  136,  is  junehook.c,  the  code  that 
has  the  changes  we  need  to  add  the 
script  interpreter  to  SMALLCOM.  We 
need  to  make  two  changes  to 
smallcom.c  from  the  March  ’89  column. 
The  first  makes  the  log  file  pointer  ex¬ 
ternal.  The  second  adds  the  script  pro¬ 
cessor’s  hook  to  the  program.  There 
are  no  apologies  for  the  second  one; 
that  is  the  modus  operandi  described 
for  this  project  in  April. 

The  SMALLCOM  program  was  built 
with  the  Compact  memory  model  in 
March.  The  only  advantage  to  that  is 
that  long  documents  are  permitted  in 
the  integrated  editor.  The  script  inter¬ 
preter  uses  integer  offsets  as  pointers. 
The  address  and  pointer  operators  are 
significantly  easier  to  implement  in  the 
small  model,  and  so  we  will  change  the 
SMALLCOM  model  to  the  small  one. 
The  .MAK  file  for  Microsoft  C  users  and 
the  environment  setup  for  Turbo  C  us¬ 
ers  must  be  changed  to  the  small  model. 
In  smallcom.c  change  the  MAXLINES 


assignment  from  800  to  200.  This  as¬ 
signment  is  in  the  comeditor  function 
on  about  line  474.  Documents  that  you 
edit  from  within  SMALLCOM  are  now 
limited  to  200  lines.  This  is  no  loss 
because  on-line  messages  should  be 
kept  short  anyway. 

The  Script  Language 

Our  script  language  is  S,  in  the  syntax 
and  grammar  described  last  month.  You 
will  recognize  it  as  a  subset  of  C.  To 
be  a  communications  script  language, 
S  must  be  extended  by  the  addition  of 
intrinsic  functions  built  into  its  shell. 
The  script.c  shell  program  has  several 
such  functions  as  described  next.  When 
you  write  a  script,  you  build  a  text  file 
that  contains  what  looks  like  a  C  pro¬ 
gram,  give  the  file  a  name  with  the 
extension  .SCR,  and  put  its  name  into 
the  SMALLCOM  phone  directory.  The 
directory  was  described  in  April,  and  it 
has  a  file  maintenance  screen  that  lets 
you  add  script  names  to  an  entry  asso¬ 
ciated  with  a  phone  number.  The  file 
name  goes  in  the  entry  associated  with 
the  service  that  uses  the  script,  and  you 
do  not  put  the  .SCR  extension  in  the 
directory  record.  When  you  call  a  serv¬ 
ice  that  has  a  script  associated  with  it, 
the  script  interpreter  shell  is  executed. 

The  S  interpreter  provides  the  man¬ 
agement  of  generic  S  data  types  and 
control  flow  of  the  script  program.  The 
intrinsic  functions  in  the  custom  shell 
integrate  the  script  and  the  communi¬ 
cations  program.  Be  aware  of  how  the 
intrinsic  functions  are  called.  SI  recog¬ 
nizes  that  a  program  is  calling  an  intrin¬ 
sic  function  by  finding  the  name  in  the 
global  array  of  INTRINSIC  structures 
named  ffs.  The  structure  contains  the 
ASCII  name  of  the  function  and  the 
address  of  the  script. h  function  to  be 
executed.  The  intrinsic  function  mecha¬ 
nism  uses  a  generic  parameter-passing 
technique  where  the  address  of  an  ar¬ 
ray  of  integers  is  passed  to  the  intrinsic 
function.  SI  has  built  that  array  from 
the  parameters  that  the  interpreted  call 
to  the  function  is  passing.  The  integers 
in  the  array  represent  integer  values  or 
pointers. 

If  the  name  of  an  array  of  character 
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pointers  is  passed,  the  integer  is  taken 
to  mean  a  pointer  to  a  pointer.  The 
straight  character  or  integer  pointers 
are  really  integer  offsets  to  the  loca¬ 
tions  in  the  SI  token  buffer.  The  point¬ 
ers  to  pointers  are  integer  offsets  from 
the  interpreter’s  data  segment  to  an 
array  of  pointers  that  is  built  when  the 
function  call  is  interpreted. 

The  script. c  program  is  written  to  be 
compiled  with  one  of  the  small  data 
models,  so  the  pointer  parameter  inte¬ 
ger  offsets  can  be  cast  as  pointers  and 
the  shell  works  fine.  Each  inirinsic  func¬ 
tion  knows  what  kind  and  how  many 
parameters  it  expects.  Here’s  the  rub. 
If  you  should  ever  want  to  use  the  SI 
interpreter  in  a  large  data  model  pro¬ 
gram,  you  would  need  to  coerce  those 
integer  offsets  into  far  pointers  by  us¬ 
ing  the  segment  value  assigned  to  the 
token  buffer.  You  would  do  this  in  the 
intrinsic  functions  in  your  shell.  You 
would  also  need  to  change  the  way 
that  interp.c  deals  with  the  address-of 
and  pointer  operators  since  these  are 
managed  by  brute-force  casts  of  inte¬ 
gers  to  pointers.  It  just  seemed  easier 
at  the  time. 

In  the  paragraphs  that  follow  I  de¬ 
scribe  the  communications  script  in¬ 
trinsic  functions  as  if  they  had  ANSI- 
style  prototypes.  They  do  not.  In  prac¬ 
tice,  you  simply  call  the  functions  with¬ 
out  declaring  them.  This  convention  is 
closer  to  the  style  permitted  by  the 
original  K&R  definition  of  the  C  lan¬ 
guage.  Remember,  though,  that  SI  func¬ 
tions  are  implicitly  defined  as  returning 
whatever  they  actually  return  at  run 
time.  It  is  up  to  your  SI  program  to 
know  what  is  coming  back  when  it 
calls  a  function. 

void  logon(char  filename);.  This  func¬ 
tion  turns  on  logging  of  the  data  re¬ 
ceived  from  the  remote  computer  across 
the  serial  line.  The  parameter  specifies 
a  file  name.  If  logging  is  already  on,  the 
current  log  file  is  closed,  and  this  new 
file  is  created  if  it  does  not  exist  or  is 
opened  for  appending  if  it  does  exist. 
You  would  use  this  function  in  a  script 
where  you  wanted  to  capture  the  in¬ 
coming  data  in  a  named  file,  perhaps 
a  file  of  messages  for  a  particular  on¬ 
line  forum. 

void  logoff(void);.  This  function  turns 
logging  off. 

void  upload(cbar  filename,  char  pro¬ 
tocol);.  Call  this  function  to  start  upload¬ 
ing  a  file  to  the  remote  computer.  The 
first  parameter  is  the  file  name  and  the 
second  is  ‘a’  for  an  ASCII  upload  and 
‘x’  for  an  XModem  upload.  In  a  script 
you  might  use  the  ASCII  mode  of  this 
function  when  it  is  time  to  send  a  mes¬ 
sage  to  a  forum.  You  would  assume 
the  user  has  created  a  message  by  us- 
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ing  the  SMALLCOM  editor  or  another, 
and  that  the  file  name  is  the  name  you 
include  in  the  script. 

void  download(char  filename,  char 
protocol);.  Call  thf  s  function  to  start  down¬ 
loading  a  file  from  the  remote  com¬ 
puter.  The  first  parameter  is  the  file 
name  to  be  created  locally  and  the 
second  is  ‘a’  for  an  ASCII  upload  and 
'x’  for  an  XModem  upload. 

void  hangup(void);.  This  function 
breaks  the  connection  between  the  lo¬ 
cal  and  remote  computers. 

void  quit(int  code);.  This  function 
tells  the  program  to  terminate  SMALL¬ 
COM.  If  the  code  parameter  is  zero,  the 
termination  returns  to  the  SMALLCOM 
program.  If  the  code  is  non-zero,  the 
quit  function  stuffs  characters  into  the 
BIOS  keyboard  read-ahead  buffer  to 
cause  SMALLCOM  to  return  to  DOS. 

void  sendstringCchar  'string);.  This 
function  sends  a  string  of  characters  to 
the  remote  computer.  You  can  code 
the  string  as  a  literal  within  the  call  or 
use  a  pointer. 

void  sendcharjchar  ch );.  This  func¬ 
tion  sends  a  single  character  to  the 
remote  computer.  The  character  can 
be  a  literal  or  a  char  ox  int  variable. 

int  waitforstrings(char  ' strf ]),.  This 
function  reads  the  input  stream  and 
watches  for  the  appearance  of  one  of 
the  strings  pointed  to  by  the  array.  The 
function  returns  an  integer  relative  to 
zero  as  the  subscript  to  the  string  that 
was  seen.  If  60  seconds  pass  without 
one  of  the  strings  coming  in,  the  func¬ 
tion  returns  Oxffffiox  -V,  a  good  reason 
to  have  the  unary  operator  supported 
by  SI,  which  we  do  not).  You  would 
use  this  function  in  a  script  where  your 
logic  might  be  altered  depending  on 
what  comes  in.  The  strings  “You  have 
mail  waiting”  and  “No  mail  today”  can 
imply  different  paths  in  the  script.  Here 
is  an  example  of  how  that  sequence 
would  appear: 

char  *str[  ]  =  ( 

"You  have  mail  waiting", 

"No  mail  today" 

1; 

int  answer; 

answer  =  waitforstrings(str); 
if  (answer  =  =  1) 


int  waitforichar  'str);.  This  function 
waits  for  the  appearance  of  the  speci¬ 
fied  string.  It  returns  0  if  the  string  is 
found  and  -1  if  the  60-second  timeout 
occurs.  You  would  use  this  form  when 
there  are  no  choices,  such  as  when  you 
know  the  remote  service  always  asks 
for  the  password.  An  example  of  the 
use  of  this  function  follows. 

if  (waitfor("PASSWORD:")  =  =  Oxffff) 


void  system(char  'command);.  This 
function  is  the  equivalent  of  the  Turbo 
C  and  Microsoft  C  system  functions. 
The  string  is  a  DOS  command  that  is 
to  be  executed.  You  might  use  this  to 
delete  or  rename  a  message  file  after  it 
has  been  transmitted.  For  example: 

system("del  ddjforum.xmt"); 

void  message(char  *msg);.  This  com¬ 
mand  writes  a  message  at  the  bottom 
of  the  screen  in  the  status  line.  It  is  a 
way  for  the  script  to  keep  the  user 
advised  of  its  progress.  The  earlier  status 
line  is  saved  and  restored  when  the 
script  is  done.  If  you  use  this  function, 
you  should  use  it  throughout  the  script 
to  maintain  consistency  in  your  pro¬ 
gram.  message("Receiving  Messages");. 

Building  the  Program 

Modify  the  smallcom.prj  or  smallcom 
.mak  files  from  when  we  originally  built 
SMALLCOM.  Add  the  script. c  and  in¬ 
terp.c  code  modules.  The  example  that 
follows  is  a  script  that  talks  to  a  Pro- 
Comm  host-mode  computer. 

An  Example  of  a  Script 

Listing  Three,  page  137,  is  procomm.scr, 
an  example  script.  A  casual  browser 
of  the  magazine  will  think  they  are 
looking  at  a  non-ANSI  C  program.  In¬ 
stead,  this  is  a  script  that  lets  a 
SMALLCOM  program  call  another  com¬ 
puter  that  is  running  ProComm,  the 
shareware  communications  program. 
ProComm  has  a  host  mode  that  turns 
it  into  a  miniature  bulletin  board  sys¬ 
tem.  When  ProComm  is  in  that  mode 
(activated  by  Alt-Q)  and  a  call  comes 
in,  the  caller  is  asked  to  enter  a  name 
and  password.  Then  ProComm  displays 
a  menu  of  file-related  commands  that 
the  caller  can  use.  These  include  upload 
and  download  commands.  This  envi¬ 
ronment  is  handy  for  testing  a  script, 
and  so  our  procomm.scr  script  exer¬ 
cises  this  feature. 

To  run  the  script,  you  must  put  its 
name,  procomm,  in  the  directory  entry 
of  the  remote  system  that  is  running 
ProComm.  If  you  do  not  have  two  com¬ 
puters,  two  modems,  and  two  phone 
lines,  maybe  you  can  arrange  for  a 
friend  to  help  you  out.  Call  the  Pro- 
Comm  computer  and  watch  it  go.  The 
password  programmed  into  the  script 
must  match  the  one  programmed  for 
the  ProComm  host  mode.  Let’s  step 
through  this  script  and  see  what  it  does. 

The  first  item  of  interest  is  the  array 
of  character  pointers  named  strs.  This 
array  illustrates  how  you  express  the 
list  of  strings  that  the  intrinsic  waitfor- 
strings  function  expects.  In  this  case, 
we  will  wait  for  one  of  the  two  strings 
after  we  send  the  password.  If  the  pass¬ 
word  is  correct,  the  script  will  key  on 
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the  “choice?”  string.  The  “denied”  string 
tells  us  that  ProComm  does  not  like 
our  password. 

Next  are  some  character  pointers  in¬ 
itialized  to  point  to  strings  that  Pro¬ 
Comm  sends  and  that  we  will  wait  for 
unconditionally.  These  strings  could  be 
coded  into  the  calls  to  waitfor  as  string 
literals,  but  because  several  of  them  are 
used  more  than  once,  I  coded  them 
individually  to  save  token  space.  For 
consistency,  I  put  the  strings  that  get 
sent  by  sendstring  into  external  point¬ 
ers,  too.  This  is  a  good  coding  practice. 
It  gets  all  the  data  values  that  might  be 
changed  for  another  script  up  where 
they  can  be  found  without  a  search 
through  the  script’s  code.  If  you  call  a 
lot  of  RBBS  or  FIDO  bulletin  boards 
and  want  to  automate  the  signon,  you’ll 
be  building  a  lot  of  similar  scripts. 

SI  has  no  #define  preprocessor  com¬ 
mand,  so  instead  we  use  initialized  int 
variables  with  identifiers  of  upper  case. 
The  main  function  of  procomm. scr 
posts  a  message  about  signing  on  and 
calls  the  signon  function.  If  that  func¬ 
tion  returns  a  true  value,  the  sign  on 
procedure  was  a  success.  The  signon 
function  waits  for  the  “name”  prompt 
and  sends  the  caller’s  name.  It  waits  for 
the  “password”  prompt  and  sends  the 
password.  Then  it  waits  for  either  the 
“choice”  or  “denied”  messages  and  de¬ 
termines  from  this  to  return  a  true  or 
false  value.  If  main  gets  the  false  return 
it  posts  a  message  about  being  denied 
access  and  is  done.  Otherwise  it  calls 
doumloadops  to  download  a  file  from 
the  ProComm  system,  uploadops  to 
upload  a  file,  posts  a  sign  off  message 
and  sends  a  ‘g’  to  the  ProComm  system 
to  tell  it  “goodbye.” 

The  doumloadops  and  uploadops  func¬ 
tions  post  messages,  wait  for  the  strings 
from  ProComm  that  tell  them  what  to 
do,  send  the  answers,  and  call  the  in¬ 
trinsic  download  and  upload  functions 
to  transfer  files.  The  downloadops  func¬ 
tion  calls  the  intrinsic  system  function 
to  rename  the  file  it  received. 

Software  Development  '89 

I  attended  the  Software  Development 
’89  conference  in  Burlingame,  Calif., 
south  of  San  Francisco.  SD89  was  Miller 
Freeman’s  second  annual  conference 
for  software  developers.  The  dominant 
development  platform  is  still  C,  but 
object-oriented  programming  is  rapidly 
gaining  momentum. 

The  new  C  product  of  note  is 
TopSpeed  C  from  Jensen  &  Partners 
International  (Mountain  View,  Calif.) 
TopSpeed  C  is  the  “Turbo  C  that  was 
to  be.”  Among  its  developers  are  foun¬ 
ders  of  Borland,  and  while  they  were 
building  what  was  to  be  the  Turbo  C 


compiler,  Borland’s  management  jerked 
the  rug  from  under  them  by  buying 
and  adapting  Wizard  C  into  Turbo  C. 
The  original  team  then  pulled  out  and 
took  their  compiler  code  with  them  to 
form  JPI.  From  the  unfailing  perspec¬ 
tive  of  perfect  hindsight  we  see  that 
Borland’s  change  of  direction  was  a 
good  move.  Nearly  two  years  after  the 
announcement  of  Turbo  C,  JPI’s 
TopSpeed  C  is  not  yet  ready  to  ship. 
But  what  they  are  showing  is  impres¬ 
sive.  Watch  this  one. 

Bill  Gates,  Microsoft’s  youthful  CEO, 
gave  the  welcome  address.  SD89  pre¬ 
sented  the  perfect  audience  for  Gates 
because  he  did  what  most  of  us  dream 
of  — wrote  programs  and  made  a  bil¬ 
lion  dollars.  Of  course,  there’s  more  to 
it  than  that,  but  when  a  billionaire 
speaks,  folks  tend  to  listen.  The  point 
of  his  address  was  that  OS/2  is  the 
wave  of  the  future,  but  that  there  will 
always  be  MS-DOS.  Surprise. 

Gates  maintains  that  there  is  no  fu¬ 
ture  in  developing  text-based  applica¬ 
tions.  According  to  him,  the  MS-DOS 
Windows  and  OS/2  Presentation  Man¬ 
ager  graphical  interfaces  are  where  the 
opportunities  lie.  It’s  easy  to  figure  out 
the  message.  When  a  billionaire  pro¬ 
grammer  tells  programmers  (many  of 
them  presidents  of  multi-hundred  dol¬ 
lar  software  companies)  what  code  to 
write  to  make  a  lot  more  money,  the 
masses  pay  attention.  But  let’s  not  for¬ 
get  that  Gates  has  an  axe  to  grind; 
Microsoft  has  an  investment  in  the  re¬ 
alization  of  his  advice.  Before  you  jump 
on  the  bandwagon  though,  be  advised  — 
the  learning  and  cost  ramps  for  those 
pretty  pictures  are  mighty  steep. 

His  only  real  news  was  that  Micro¬ 
soft’s  full  compiler  products  (MSC  to 
us)  will  soon  have  integrated  environ¬ 
ments  after  the  fashion  of  the  Quick 
language  products. 

Gates  pitched  incremental  compiles/ 
link,  a  feature  that  QuickC  2.0  already 
has  to  some  extent.  This  is  where  the 
environment  compiles  only  the  func¬ 
tion  just  changed.  He  said  that  hypertext- 
like  editors  would  be  big  stuff  some 
day,  too.  You  will  be  able  to  put  the 
cursor  on  a  function  name,  press  a 
key,  and  jump  to  that  function  in  its 
source  file.  You  will  then  be  able  to 
change  the  function’s  name  and  have 
the  integrated  environment  fix  all  refer¬ 
ences  to  it  in  all  related  code  modules 
and  automatically  recompile  and  link. 

I  heard  a  strange  sound.  Terry  Colli- 
gan,  president  of  Rational  Systems  Inc., 
was  snickering  into  his  fist.  Instant-C 
has  had  those  features  for  years. 


Gates  talked  about  Microsoft’s  pres¬ 
ence  in  the  international  arena.  He  made 
a  point  of  their  relationship  with  the 
USSR.  It  seems  Microsoft  sells  a  lot  of 
software  over  there.  (I  don’t  feel  so 
guilty  now  about  writing  this  column 
on  a  Toshiba  laptop.)  But  then  he  told 
us  about  how  one  of  their  overseas  sales 
otganizations  unloaded  their  last  500  cop¬ 
ies  of  QuickC  1.0  on  the  Soviets.  For 
the  first  time  since  the  Rosenbergs  were 
executed  I  felt  sorry  for  a  communist. 

Wednesday’s  bright  spot  was  Liz 
Oakley,  vivacious  publisher  of  Program¬ 
mer’s  Journal,  sitting  on  the  floor  in  the 
corridor  outside  of  the  Microsoft  hospi¬ 
tality  suite.  Liz  was  holding  court  for  a 
seated  circle  of  enchanted  followers 
(me  included).  The  denizens  of  the 
more  dignified  inner  suite  closed  the 
door  to  block  out  the  spectacle. 

On  Thursday  Microsoft  bowed  out 
of  the  Codeview/Turbo  Debugger  shoot¬ 
out.  David  Intersimone  of  Borland  gra¬ 
ciously  consented  to  objectively  repre¬ 
sent  both  views.  He  gave  a  brief  run¬ 
down  of  the  features  shared  by  both 
debuggers  and  then  treated  us  to  a 
dazzling  demonstration  of  the  Turbo 
Debugger.  Code-who?  Lest  we  forget, 
CodeView  was  a  trailblazer,  setting  the 
standard  in  source  debuggers  for  oth¬ 
ers  to  shoot  at.  Since  then  it  has  been 
left  in  the  dust,  and  we  tend  to  forget 
how  much  we  loved  it  in  its  early  days. 
No  doubt  a  next-generation  CodeView 
is  in  the  wings,  if  only  to  silence  the 
muffled  titters  heard  whenever  the  two 
debuggers  are  compared.  In  the  mean¬ 
time  Turbo  Debugger  is  a  must-have 
for  serious  debugging. 

Borland  hosted  a  grand  party  on  Thurs¬ 
day  night.  There  was  food,  drink,  T- 
shirts,  and  a  competent  jazz  quintet  of 
Borland  employees  — guitar,  flute,  key¬ 
boards,  bass,  and  drums.  In  the  second 
set,  Philippe  Kahn,  the  flamboyant 
leader  of  Borland,  sat  in  and  played  the 
tenor  saxophone.  Don’t  give  up  the 
day  gig,  Philippe. 

Availability 

All  source  code  for  articles  in  this  issue 
is  available  on  a  single  disk.  To  order, 
send  $14.95  (Calif,  residents  add  sales 
tax)  to  Dr.  Dobb’s Journal,  501  Galves¬ 
ton  Dr.,  Redwood  City,  CA  94063;  or 
call  800-356-2002  (from  inside  Calif.) 
or  800-533-4372  (from  outside  Calif.). 
Please  specify  the  issue  number  and 
format  (MS-DOS,  Macintosh,  Kaypro). 
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GRAPHICS  PROGRAMMING 


The  Software 
White  Cane 


Where  I  went  to  college,  there 
was  a  professor  who  often 
strode  purposefully  about  the 
campus,  head  high,  eyes  fixed 
resolutely  on  the  horizon.  He  never 
looked  down.  Approaching  a  curb  or 
stairs,  he  negotiated  them  confidently. 
At  a  door,  he’d  seize  the  knob  without 
a  flick  of  the  eye  and  go  inside.  Some¬ 
times,  if  late,  he’d  jog.  This  doesn’t 
seem  particularly  remarkable  until  you 
realize  that  the  man  was  totally  blind. 

One  day  I  asked  him  how  he  did  it. 
“I  just  count  steps,”  he  said  offhand¬ 
edly.  “It’s  no  big  deal.  I  know  every 
inch  of  this  campus.” 

Then  one  day  I  ran  into  him  in  a 
nearby  town.  There,  away  from  his  well- 
known  world,  he  was  like  other  blind 
men,  tapping  his  way  along  with  a 
white  cane.  Scarcely  less  vigorously,  I 
might  add,  but  he  didn’t  know  where 
the  obstacles  were.  The  cane  helped 
him  find  them. 

Now  it  might  seem  like  a  far  jump 
of  the  imagination  to  relate  this  blind 
professor  to  a  graphics  program,  but 
there  are  parallels.  Both  move  around 
in  their  worlds  knowing  there  are  things 
in  the  way,  but  unable  to  see  them.  To 
avoid  hazards,  both  need  a  replace¬ 
ment  for  sight. 

The  person  at  the  thinking  end  of  a 
white  cane  finds  walls,  curbs,  and  other 
obstacles  by  detecting  when  the  cane 
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hits  something  unexpected.  A  program 
finds  them  by  detecting  a  change  in 
the  pixel  value.  Therefore,  the  soft¬ 
ware  white  cane  is  a  routine  that  senses 
pixels. 

There  are  in  fact  several  ways  to  get 
pixel  information  back  from  the  dis¬ 
play.  The  choice  of  method  depends 
on  what  we’re  trying  to  accomplish. 
The  ability  to  “feel”  pixels  and  avoid 


obstacles  gives  graphics  programs  the 
freedom  to  do  many  things  rather  eas¬ 
ily  that  would  otherwise  be  difficult. 
That’s  exactly  what  a  white  cane  does 
for  a  blind  person. 

This  month  we’ll  examine  ways  to 
detect  individual  pixels  and  an  impor¬ 
tant  application:  filling  closed  figures. 

This  is  Not  The  Way  To  Do  It 

The  PC  ROM  BIOS  Video  Services  fur¬ 
nish  a  built-in  function  to  read  a  graph¬ 
ics  pixel  value.  You  place  ODh  into 
register  AH  and  the  X  and  Y  coordi¬ 
nates  into  registers  CX  and  DX  respec¬ 
tively,  then  issue  Int  10b.  On  return, 
the  pixel  value  is  in  register  AL.  Couldn’t 
be  simpler. 

Couldn’t  be  much  slower,  either.  I’ve 
complained  about  it  before  and  I’ll  do 
it  again:  the  ROM  BIOS  video  routines 
are  inexcusably  slow.  On  my  8MHz 
AT  clone,  it  takes  139.56  seconds  to 
read  all  224,000  EGA  pixels,  for  a  rate 
of  1605/sec. 

And  if  you’re  one  of  those  program¬ 
mers  who’s  fallen  into  the  trap  of  be¬ 
lieving  faster  chips  make  up  for  ineffi¬ 
cient  code,  think  again.  Exactly  the  same 
program  running  on  my  16MHz  ’386 
machine  takes  a  hair  under  300  sec¬ 
onds,  yielding  a  rate  — if  you  want  to 
call  it  that  — of  748  pixel  reads  per 
second:  less  than  half  the  throughput 
despite  twice  the  cycles. 

Certainly  some  part  of  this  discrep¬ 
ancy  has  to  do  with  differences  in  the 
ROM  BIOS  (they’re  both  Phoenix). 
That’s  not  the  point.  This  is:  Don’t  use 
the  ROM  BIOS  pixel  read.  It’s  just  too 
slow. 

The  Improved  White  Cane 

You  can  achieve  much  better  pixel  read¬ 
ing  rates  by  going  directly  to  the  video 
controller  with  EGAPIXEL.ASM  (List¬ 
ing  One,  page  139).  This  routine 
achieves  a  rate  of  16,500  pixels/sec. 
on  the  AT  and  32,350  on  my  ’386.  Still 


far  short  of  the  pixel-blasting  rate  for 
the  hline( )  routine,  but  10.3  to  43.2 
times  better  than  the  ROM  BIOS  Video 
Services. 

The  writing  and  reading  of  pixels 
have  a  lot  in  common:  both  have  to 
remap  the  coordinates  into  the  view¬ 
port,  compute  the  video  buffer  address, 
and  set  the  bit  mask.  Thus  the  first  70 
or  so  lines  of  EGAPIXEL.ASM  and 
DRAWPT.ASM  (from  February)  are  quite 
similar.  Then  things  change  dramatically. 

Probably  because  pixel  reading  is 
less  often  done  than  writing,  the  Video 
Controller  is  less  efficient  at  it.  To  write, 
you  jam  a  bit  pattern  into  a  hypotheti¬ 
cal  memory  location  and  the  controller 
takes  care  of  splitting  it  apart  and  up¬ 
dating  the  affected  bit  planes.  In  read¬ 
ing,  the  program  has  to  fetch  a  byte 
from  each  bit  plane  separately  and  as¬ 
semble  the  value  itself,  bit  by  bit. 

The  PIXVAL  macro  reads  each  bit 
plane  for  the  pixel  position  and  ex¬ 
tracts  its  relevant  bit,  The  pixel  value 
is  accumulated  in  register  BH  through 
rotation,  reading  from  bit  plane  3  (most 
significant)  downward.  The  bytes  at 
ES:[SI]  are  actually  taken  from  the  video 
controller’s  latch  registers  thanks  to  back¬ 
ground  meddling  by  the  6845,  but  the 
program  doesn’t  know  that.  It  just  thinks 
it’s  reading  the  same  memory  location 
over  and  over.  The  pixel  value  accu¬ 
mulated  in  BH  gets  passed  back  to  the 
caller  (unless  the  location  is  outside 
the  viewport,  in  which  case  -1  is  re¬ 
turned). 

Why  use  a  macro  when  a  loop  would 
do?  Because  conditional  jumps  in  as¬ 
sembly  language  are  time-stealers.  My 
friend  Michael  Abrash  is  doing  a  won¬ 
derful  series  of  books  on  squeezing  the 
utmost  performance  out  of  assembly 
language.  Jeff  Duntemann  mentions  it 
this  month  over  in  the  “Structured  Pro¬ 
gramming"  column,  and  I’ve  had  a  peek 
at  the  manuscript  for  Volume  1.  Michael 
abhors  conditional  jumps,  especially 
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(continued  from  page  124) 
inside  loops.  I  tested  this  routine  first 
with  a  loop,  then  with  the  macro,  and 
got  a  10  percent  improvement  simply 
by  eliminating  the  conditional  jump. 
Now  I  abhor  them,  too. 

A  white  cane  isn’t  as  good  as  eye¬ 
sight,  and  pixel  reading  isn’t  as  good 
as  pixel  writing.  At  best,  it’s  a  high- 
overhead  operation.  So  why  introduce 
any  more  overhead  than  absolutely  nec¬ 
essary?  In  this  case,  a  few  extra  bytes 
of  code  deliver  more  performance. 

After  assembling  EGAPIXEL.ASM,  add 
it  to  your  copy  of  GRAFIX.LIB  with  the 
DOS  command 

LIB  grafix  +egapixel; 

Okay,  so  now  we  can  read  a  pixel. 
What  do  we  do  with  it? 

RICOCHET.  C  in  Listing  Two  (page 
140)  might  not  be  a  very  serious  pro¬ 
gram,  but  it  gives  a  feel  for  the  possi¬ 
bilities.  It’s  a  variant  on  the  idea  of  the 
rat  in  the  maze.  The  screen  has  a  bor¬ 
der  and  several  interior  obstacles,  all 
in  white.  The  “rat”  is  a  moving  red 
pixel  subject  to  the  mle  that  it  must 
always  move  on  the  diagonal.  As  it 
travels,  it  leaves  “footprints”  or,  in  other 
words,  draws  a  line.  At  each  step,  it 
feels  ahead  for  an  obstacle:  a  white 
pixel.  Upon  encountering  one,  it 
changes  direction  appropriately. 

The  path  the  line  takes  is  erratic, 
ricocheting  around  among  the  barriers 
in  a  frenetic  pattern  that  gradually  fills 
every  nook  and  cranny  of  the  maze 
with  red.  The  fill  never  becomes  com¬ 
pletely  solid,  though,  because  eventu¬ 
ally  the  racing  rat  begins  retracing  its 
steps.  When  that  happens,  the  pro¬ 
gram  appears  to  freeze;  it’s  actually 
redrawing  the  same  complex  path  all 
over  again.  You  can  stop  the  program 
any  time  by  pressing  a  key. 

Speaking  of  Filling . . . 

RICOCHET  is  obviously  neither  effi¬ 
cient  nor  satisfactory  as  an  algorithm 
for  filling  a  closed  figure.  However,  it 
illustrates  the  important  point  that  any 
filling  algorithm  has  to  know  where  to 
stop.  And  in  order  to  do  that,  it  must 
be  able  to  detect  the  border  color. 

The  exception  to  this  general  obser¬ 
vation  is  drawing  solid  rectangles,  which 
we  covered  back  in  March.  But  fill_ 
rect( )  just  draws  a  series  of  horizontal 
lines  bounded  by  the  dimensions  of 
the  object.  One  could  also  draw  other 
regular  solid  polygons  in  this  manner, 
such  as  diamonds  and  circles.  At  any 
point  along  the  left  edge,  you  can  cal¬ 
culate  the  distance  to  the  correspond¬ 
ing  point  on  the  right  edge  and  draw  a 
line.  Although  the  visual  effect  indi¬ 
cates  otherwise,  that’s  not  really  filling. 


Instead,  it’s  a  particular  application  of 
line-drawing,  and  it  works  only  for  regu¬ 
lar  polygons,  unless  you  want  to  do 
an  enormous  amount  of  computation. 

A  more  general-purpose  filling  algo¬ 
rithm  will  fill  any  closed  object,  regular 
or  otherwise.  It  does  this  by  spreading 
“paint”  outward  from  a  known  interior 
point  — usually  called  the  seed  — until 
it  encounters  the  border  outlining  the 
object.  It  will  also  leave  holes  in  the 
interior,  provided  the  closed  inside  fig¬ 
ures  have  the  same  border  pixel  value 
as  their  container  and  the  seed  is  not 
within  one  of  them.  The  usual  name 
for  this  kind  of  algorithm  is  flood  fill. 

The  need  for  flood  filling  is  obvious. 
As  it  draws  the  lines  forming  various 
objects,  a  program  can’t  possibly  re¬ 
member  the  location  of  every  single 
pixel  it  writes.  It’s  like  my  blind  profes¬ 
sor  writing  on  the  blackboard:  Once 
the  act  was  done,  he  couldn’t  recall 
where  he’d  written,  and  sometimes  he 
wrote  right  over  other  things.  There 
was  no  white  cane  to  help  him  in  this 
case,  but  there  is  for  the  program.  It 
can  keep  tapping  ahead  looking  for 
the  border  pixels  that  comprise  the  brick 
walls  for  the  filling  algorithm. 

Computer  science  research  has  pro¬ 
duced  a  number  of  flood  fill  methods. 
Perhaps  the  simplest  is  the  recursive 
fill,  written  for  the  GRAFIX  environ¬ 
ment  as  follows: 

void  fill  (int  x,  int  y,  byte  border)  I 
if  (egapixel  (x,  y)  !=  border)  { 
draw_point  (x,  y); 
fill  (x+1,  y,  border); 
fill  (x-1,  y,  border); 
fill  (x,  y+1,  border); 
fill  (x,  y-1,  border); 


The  fill  restlessly  spreads  outward  from 
the  seed  in  all  directions,  painting  pixel 
positions  until  it  can  no  longer  find  any 
within  the  border. 

The  recursive  fill  works,  but  it  has  a 
couple  of  drawbacks.  One  is  that  it’s 
not  very  efficient.  The  multiple  recur¬ 
sive  calls  spend,  on  average,  some¬ 
thing  like  75  percent  of  the  time  revisit¬ 
ing  adjacent  positions  that  have  already 
been  filled.  Even  more  serious,  though, 
is  its  hunger  for  stack  space.  Stack  de¬ 
mands  rise  logarithmically  with  the  size 
of  the  region  being  filled.  Programs 
that  use  recursive  fill  are  always  in  dan¬ 
ger  of  crashing  due  to  stack  overflow. 

A  better  flood  fill  algorithm  is  the 
line  adjacency  method.  It  too  is  recur¬ 
sive,  but  much  less  so.  The  amount  of 
stack  space  it  consumes  depends  more 
on  the  complexity  of  the  polygon  — 
holes  to  work  around,  strange  angles  — 
than  on  the  size  of  the  filled  region. 
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Nevertheless,  if  you’re  using  Microsoft 
C  or  QuickC,  the  2K  default  stack  prob¬ 
ably  won’t  be  enough. 

The  line  adjacency  algorithm  thinks 
vertically  and  draws  horizontally.  Row 
by  row  it  strives  upward  from  the  seed. 
Whenever  it  finds  an  unfilled  row,  it 
searches  for  the  right  and  left  borders 
and  draws  a  line  between  them.  It  re¬ 
turns  to  the  seed  row  when  no  unfilled 
positions  remain  upward,  and  begins 
striving  downward  in  the  same  fash¬ 
ion.  Because  it’s  recursive,  the  algo¬ 
rithm  remembers  where  it  hasn’t  yet 
checked  its  neighboring  row,  and  even¬ 
tually  it  always  goes  back  to  take  care 
of  unfinished  business.  The  procedure 
is  done  when  there  are  no  unfilled  pixel 
positions  within  the  closed  region. 

This  is  a  somewhat  simplified  expla¬ 
nation  of  how  the  line  adjacency  algo¬ 
rithm  works.  For  a  more  thorough  un¬ 
derstanding,  watch  it  in  action  or,  better 
yet,  trace  its  execution  with  a  debugger. 

This  month’s  contribution  to  the  grow¬ 
ing  GRAFIX  library  is  EGAFILL.C  (List¬ 
ing  Three,  page  140).  The  module  con¬ 
tains  floodfill( ),  an  implementation  of 
the  line  adjacency  algorithm,  along  with 
some  supporting  functions.  If  you’re 
typing  in  the  code,  you  get  off  easy  this 
month:  All  the  listings  are  short.  After 
compiling  this  module,  add  it  to  the 
library  with 

LIB  grafix  +egafill; 

Listing  Four,  page  142,  shows  the 
additions  to  your  copy  of  GRAFIX.H. 
The  libraries  on  CompuServe  and  the 
DDJ  diskette  both  contain  a  complete, 
up-to-date  version  of  the  header  file. 

And  finally  there’s  Listing  Five  (page 
142),  a  program  called  FILLS. C  that  puts 
it  all  to  work.  FILLS  produces  three 
filled  objects  of  increasing  complexity, 
showing  how  the  line  adjacency  algo¬ 
rithm  does  its  thing.  The  first  is  a  sim¬ 
ple  triangle.  This  is  followed  by  a  mis¬ 
shapen  star  that  resembles  a  fighter 
plane.  It’s  not  actually  meant  to  look 
like  anything,  but  instead  to  show  how 
the  fill  algorithm  handles  a  complex 
shape.  And  finally  we  have  a  house, 
which  is  made  interesting  by  having 
six  unfilled  islands  — the  windows  — 
within  the  filled  area.  Note  how  the  fill 
routine  taps  its  way  around  them,  and 
how  it  returns  at  the  end  to  paint  the 
spaces  between  them. 

This  program  works  fine  with  the 
default  stack  size  in  Turbo  C,  but  with 
Microsoft  and  QuickC  you  have  to  over¬ 
ride  the  2K  default  with  a  5K  stack.  You 
can  specify  this  with  the  link  option 
/ST:5120. 

So  that’s  how  filling  works  with  the 
aid  of  a  software  white  cane.  There  are 
more  efficient  ways  of  doing  the  same 


thing,  and  sooner  or  later  we’ll  get 
around  to  them.  For  now  we  have  a 
working  tool  that’s  not  difficult  to  un¬ 
derstand,  and  which  opens  up  new 
dimensions  of  computer  graphics.  Too 
bad  that  professor  can’t  see  them. 

Pulling  My  FAT  from  the  Fire 

Horror  story:  Last  week,  while  working 
on  a  program  unrelated  to  this  column, 
I  clobbered  the  FAT  on  my  hard  disk. 
A  44-meg  hard  disk,  I  might  add,  that 
was  nearly  full.  I’m  still  not  sure  how 
it  happened.  There  were  some  prob¬ 
lems  with  a  wild  indexing  scheme,  so 
the  program  probably  corrupted  some 
code  that,  when  it  got  control  later,  did 
an  absolute  write  to  several  FAT  sec¬ 
tors.  Naturally,  I  hadn’t  done  a  backup 
in  some  time  (“Tomorrow  I’ll  do  it”). 

When  you  lose  pieces  of  the  FAT, 
you’re  in  a  heap  of  trouble.  Just  for 
starters  I  lost  the  entire  directory  for 
this  column.  Fortunately  I  had  a  backup 
of  programs  already  published  or  in 
the  mill,  but  the  future  stuff  I  was  work¬ 
ing  on  was  gone.  So  were  a  lot  of  other 
things. 

Heroics  were  in  order,  and  I  went 
to  work  in  a  panic.  First  I  got  every¬ 
thing  off  the  disk  that  I  could.  Using 
another  computer,  I  wrote  some  hasty 
software  that  allowed  me  to  browse 
sectors  and  reconstruct  broken  chains 
manually.  Talk  about  a  blind  man  tap¬ 
ping  his  way  around. 

But  what  really  pulled  my  FAT  from 
the  fire  was  the  new  Norton  Utilities 
Advanced  Edition.  Between  the  Nor¬ 
ton  Disk  Doctor  (NDD)  and  the  multi¬ 
faceted  NU  program,  I  was  able  to  find 
the  problems  and  twiddle  the  bits  to  fix 
them.  I  didn’t  get  everything  back,  but 
I  got  probably  90  percent  of  the  things 
I  cared  about. 

I  can’t  say  this  too  strongly.  Norton’s 
Advanced  Edition  is  a  superlative  prod¬ 
uct.  Get  it.  It  brought  me  back  from  a 
catastrophe,  and  it  might  do  the  same 
for  you. 

Availability 

All  source  code  for  articles  in  this  issue 
is  available  on  a  single  disk.  To  order, 
send  $14.95  (Calif,  residents  add  sales 
tax)  to  Dr.  Dobb’s  Journal,  501  Galves¬ 
ton  Dr.,  Redwood  City,  CA  94063,  or 
call  800-356-2002  (from  inside  Calif.) 
or  800-533-4372  (from  outside  Calif.). 
Please  specify  the  issue  number  and 
format  (MS-DOS,  Macintosh,  Kaypro). 
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STRUCTURED  PROGRAMMING 


Is  This  Angst 
Really  Necessary? 


Iwas  in  an  art  supplies  store  in  Roch¬ 
ester,  New  York  the  afternoon  Roch¬ 
ester  Gas  and  Electric’s  Ginna  nu¬ 
clear  power  plant  burped  and  spat 
a  little  wisp  of  radioactive  steam  into 
the  wind.  I’d  long  since  learned  to  stop 
worrying  and  love  alpha  particles;  be¬ 
tween  the  radon  from  my  basement 
and  the  cosmic  rays  one  can’t  help  but 
meet  at  30,000  feet,  I  figured  Ginna 
wasn’t  adding  any  statistically  signifi¬ 
cant  risk  to  my  life.  The  owner  of  the 
art  store,  on  the  other  hand,  was  obvi¬ 
ously  petrified.  She  had  a  little  portable 
TV  propped  up  on  a  pile  of  Strathmore 
pads,  and  was  hanging  on  the  news 
announcer’s  every  word  —  her  hands 
shaking  as  she  kept  lighting  one  ciga¬ 
rette  off  the  end  of  the  last,  going 
through  a  full  pack  in  20  minutes. 

“The  man  who  invented  radioactiv¬ 
ity  ought  to  be  shot,”  she  complained 
as  she  rang  up  my  drafting  pencils.  By 
that  time  you  could  barely  see  in  there, 
and  I  hastened  out  the  door  while  I  still 
had  my  lungs. 

My  bitter  sense  of  irony  told  me  that 
she  had  the  perfect  response  to  nuclear 
angst:  Chain  smoke  long  enough  and 
low-level  radioactivity  ceases  to  be  any 
kind  of  threat.  There  is  a  similar  (and 
just  as  pointless)  angst  prevalent  among 
naive  programmers:  The  fear  that  high- 
level  languages  invariably  produce  gla¬ 
cially  slow  code.  In  terror  of  a  threat 
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that  they  can’t  even  understand,  much 
less  begin  to  measure,  they  react  by  the 
HLL  equivalent  of  chain-smoking,  which 
is  to  replace  one  routine  after  another 
in  their  programs  with  badly-conceived 
and  barely-operable  assembly  language. 
Eventually  the  programs  implode  un¬ 
der  a  cancerous  profusion  of  interre¬ 
lated  bugs  that  freeze  their  machines 
solid  —  at  which  point  slow  code  per¬ 


formance  or  any  other  kind  of  code 
performance  ceases  to  be  an  issue. 

Don't  Worry  —  Be  Happy 

Is  this  angst  really  necessary?  Cripes 
almighty,  no!  Five  years  of  crawling 
through  native  code  HLL  programs  with 
a  debugger  have  convinced  me  of  this: 
Modern  high-level  languages  write  bet¬ 
ter  assembly  language  than  99  percent 
of  all  the  programmers  who  have  ever 
lived  or  will  ever  live.  Not  only  are 
your  chances  of  writing  faster  code 
than  the  compiler  not  good,  the  chances 
are  excellent  that  your  own  assembly 
language  will  be  slower. 

This  is  truer  now  than  ever  before. 
The  battle  of  the  titans  between  Bill 
Gates  and  Philippe  Kahn  has  produced 
some  killer  code  generators.  (This  in¬ 
cludes  TopSpeed  Modula-2,  which  be¬ 
gan  as  Turbo  Modula-2  when  Nils  Jensen 
was  still  a  Borlander.)  Out  of  the  wood¬ 
work  are  coming  new  compilers  like 
Watcom  C,  which  beats  both  Turbo 
and  Quick  C  in  the  time  trials  and  are 
raising  the  ante  in  the  programmers’ 
equivalent  of  the  nuclear  arms  race. 

The  bottom  line  is  this:  Unless  you’re 
as  good  an  assembly  language  pro¬ 
grammer  as  Anders  Hejlsberg,  the  author 
of  Turbo  Pascal,  don’t  worry  about  HLL 
code  performance.  If  you  must  do  some¬ 
thing,  think  hard  about  your  algorithms, 
remembering  that  a  bubble  sort  in  as¬ 
sembler  is  almost  certainly  slower  than 
a  shell  sort  in  interpreted  Basic.  Do 
what  you  do  best  —  program  in  your 
chosen  HLL  —  and  let  Anders  and  his 
rare  breed  do  what  they  do  best:  Write 
programs  that  write  assembly  language. 

The  20  Percent  Rule 

I’ve  identified  two  broad  categories  of 
situations  where  your  chances  of  beat¬ 
ing  the  compiler  rise  to  about  50/50: 
The  first  category  includes  situations 
when  time  resolution  is  a  factor.  The 
second  category  includes  any  move¬ 


ment  of  screen  data  that  represents  more 
than  20  percent  of  the  area  of  your 
screen. 

The  first  category  is  a  thin  one  in¬ 
deed.  I’m  speaking  of  things  like  pull¬ 
ing  data  points  in  from  some  kind  of 
analog/digital  converter.  The  simplest 
example  is  the  PC  joystick.  You  can 
poll  the  joystick  from  Pascal  or  Modula- 
2,  but  you  get  better  resolution  of  the 
stick  when  you  poll  it  from  assembler. 
The  resolution  of  the  stick  is  directly 
proportional  to  the  number  of  times 
per  second  that  your  code  can  grab  a 
value  from  a  PC  I/O  port.  Assembler 
doesn’t  necessarily  win,  but  it  can  win. 
Keep  in  mind  that  you  have  to  be  a 
good  enough  assembly  language  pro¬ 
grammer  to  code  the  tightest  possible 
loop,  taking  advantage  of  assumptions 
and  special  information  that  the  com¬ 
piler’s  code  generator  doesn’t  neces¬ 
sarily  have. 

The  second  category,  on  the  other 
hand,  is  an  area  of  critical  concern, 
especially  when  the  screen  in  question 
is  a  graphics  screen.  My  20  percent  rule 
applies  to  text  screens  only;  in  graphics 
modes  scale  that  back  to  5  percent,  or 
even  0  percent  —  maybe  I’m  picky,  but 
graphics  screens  are  never  fast  enough 
to  suit  me.  Screen  refreshes  that  are 
slow  enough  to  watch  are  too  slow. 
Lines,  windows,  and  other  screen  ob¬ 
jects  should  appear  and  vanish  instandy. 
Accept  nothing  less. 

Biasring  Lines 

I’ve  managed  to  build  the  virtual  screens 
library  through  three  columns  without 
resorting  to  assembly  language  for  any¬ 
thing  but  a  simple  INLINE  macro  for 
clearing  lines  in  SCREENS.PAS.  (DDJ, 
April  1989.)  That  macro  ( ClearLine )  was 
nothing  more  than  setup  and  minimal 
safety  check  for  a  single,  powerful  op¬ 
code:  REP  STOSW.  The  5705 Wopcode 
takes  whatever’s  in  AX  and  blasts  it  out 
into  memory  at  the  fastest  speed  of 
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which  the  ’86  is  capable.  It’s  a  machine- 
code  loop  that  executes  entirely  within 
the  CPU,  behind  the  mask  of  a  single 
instruction.  Compilers  are  not  gener¬ 
ally  smart  enough  to  identify  situations 
in  which  REP  STOSW  is  useful,  so  we 
have  to  code  them  up  ourselves. 

Turbo  Pascal  does  have  the  FillChar 
procedure,  which  uses  the  REP  STOSB, 
which  is  close,  but  not  quite  what  we 
need  to  clear  a  screen  line  with  both  a 
chosen  clear  character  and  a  chosen 
attribute  character.  Also,  there  is  con¬ 
siderable  fooling  around  that  the  more 
general  FillChar  routine  must  go 
through  to  set  itself  up  to  perform  the 
REP  STOSB.  We  don’t  need  that  in  this 
case,  but  the  compiler  can’t  help  gen¬ 
erating  it.  If  I  needed  a  maximum- 
speed  buffer  filler,  I  might  in  fact  be 
tempted  to  code  it  up  because  there’s 
not  that  much  to  it. 

The  guidance  here  is  to  keep  it  sim¬ 
ple,  and  know  your  assembly  language. 
I  can’t  teach  you  assembly  language  in 
this  column,  lordy,  but  if  you’re  going 
to  try  it  the  least  I  can  do  is  counsel  you 
to  read  up  on  it  and  try  to  understand 
what  it’s  about.  Tom  Swan  has  an  ex¬ 
cellent  book:  Mastering  Turbo  Assem¬ 
bler ;  on  the  stands  right  now,  and  my 
own  introduction  to  assembly  language, 
Assembling  From.  Square  One  (which 
speaks  of  both  TASM  and  MASM)  will 
be  out  this  fall.  Also  well  into  produc¬ 
tion  is  Michael  Abrash’s  two-volume 
opus  The  Zen  of  Assembler,  which  is 
definitely  the  category-killer  book  on 
advanced  86-family  assembly  language. 
When  both  volumes  and  all  1,600  pages 
of  Zen  are  in  print,  I  feel  confident  that 
the  work  will  stand  as  the  definitive 
reference  to  performance  programming 
in  assembler  well  into  the  Twenty-First 
Century.  Master  Zen  and  you’ll  be  quali¬ 
fied  to  outthink  the  sharpest  compiler. 

On  the  other  hand,  having  come 
away  from  the  technical  edit  of  Volume 
1:  Knowledge  with  smoking  eyeballs,  I 
will  advise  you  that  the  learning  proc¬ 
ess  could  take  awhile. 

Cloning  a  Calendar 

So  —  to  show  you  a  situation  where 
assembly  language  is  both  necessary 
and  effective,  let’s  clone  the  Sidekick 
calendar  for  virtual  screens. 

The  CALTEST.PAS  demo  program  (List¬ 
ing  One,  page  143)  puts  a  calendar  in 
the  middle  of  your  visible  screen  win¬ 
dow.  The  right  arrow  takes  you  “up¬ 
time”  and  bumps  the  month  by  one 
into  the  future;  the  left  arrow  takes  you 
“down-time”  and  bumps  the  month  by 
one  into  the  past.  Pound  on  the  arrow 
keys  and  try  to  catch  any  “flow”  as  the 
calendar  comes  in.  You  won’t,  not  even 
on  a  4.77MHZ-8088  machine. 


There  are  three  important  elements 
comprising  the  calendar.  The  CALEN¬ 
DAR. PAS  unit  (Listing  Two,  page  143) 
handles  the  display  of  the  calendar. 
The  calendar  calculations  are  done  in 
CALCALC.PAS  (Listing  Three,  page  148). 
CALCALC.PAS  comes  from  Michael  Cov¬ 
ington  at  the  University  of  Georgia, 
and  I  use  it  here  with  his  gracious 
permission.  The  key  routine  for  this 
discussion,  however,  lies  in  file 
BLKBLAST.ASM  (Listing  Four,  page 

148) .  BlkBlast  is  the  assembly  language 
external  to  Turbo  Pascal  that  actually 
moves  the  calendar  patterns  to  the  vir¬ 
tual  screen.  BlkBlast  was  placed  in  CAL¬ 
ENDAR. PAS  for  convenience’s  sake;  as 
a  virtual  screens  primitive  it  rightfully 
belongs  in  SCREENS. PAS  and  I  recom¬ 
mend  you  put  it  there. 

The  patterns  themselves  can  be 
placed  as  arrays  of  STRING  in  typed 
constants,  but  I’ve  chosen  to  gather 
them  into  a  separate  assembly  language 
file,  CALBLKS.ASM  (Listing  Five,  page 

149)  so  that  you  can  see  how  it’s  done. 
Note  that  the  patterns  stored  in 
CALBLKS.ASM  are  called  procedures, 
but  (pretty  obviously)  are  not  meant 
to  be  executed.  They  need  to  be  pack¬ 
aged  as  procedures  to  force  the  Turbo 
Pascal  linker  into  loading  and  linking 
them  to  your  program.  They  are,  in 
fact,  data,  and  are  accessed  by  deriving 
pointers  to  them  and  passing  them  as 
pointer  parameters  to  BlkBlast. 

Blasting  Blocks 

Called  from  a  Turbo  Pascal  program, 
BlkBlast  copies  a  linear  array  of  bytes 
from  one  location  of  memory  to  a  rec¬ 
tangular  region  in  a  virtual  screen.  The 
pointer  to  the  array  of  bytes  where  the 
pattern  is  stored  is  passed  in  StoreEnd, 
whereas  the  pointer  to  the  virtual  screen 
is  passed  in  ScreenEnd.  ScreenX  and 
Screen  Y  are  passed  the  current  X  and 
Y  size  of  the  visible  screen  (that  is,  the 
display  adapter’s  buffer),  respectively. 
My  Textlnfo  unit  (DDJ,  March  1989) 
exports  two  preinitialized  variables,  Vis- 
ibleX  and  VisibleY,  that  I  use  for  that 
purpose. 

ULX  and  ULY  are  passed  the  X,Y 
position  of  the  upper  left  corner  of  the 
rectangular  region  within  the  virtual 
screen  where  the  pattern  is  to  be  placed. 
Width  and  Height  are  passed  the  width 
and  height  of  the  pattern  stored  at  the 
address  passed  in  StoreEnd.  Attribute 
is  passed  the  attribute  byte  to  be  used 
for  the  display  of  the  pattern. 

DeadLines  and  TopStop  are  special 
parameters  that  serve  the  calendar  ap¬ 
plication.  A  calendar  is  displayed  by 
first  blasting  the  CalFrame  pattern 
(stored  in  CALBLKS.ASM)  up  to  the 
virtual  screen.  The  CalCalc  unit  is  used 


to  calculate  an  offset  into  the  CalData 
pattern.  This  offset  will  vary  depending 
on  what  day  of  the  week  the  first  of  any 
given  month  falls  on.  The  sooner  in  the 
week  the  first  falls,  the  farther  into  Cal¬ 
Data  you  must  move  for  a  starting  point. 
Starting  at  this  offset  position,  CalData 
is  blasted  atop  CalFrame.  Bingo!  You 
have  a  calendar. 

There  is  some  trickiness  involving 
the  blast  of  the  data  onto  the  calen¬ 
dar  frame.  If  you’ll  notice  from 
CALBLKS.ASM,  the  numbers  for  the  cal¬ 
endar  are  stored  in  a  single-spaced  ar¬ 
ray,  when  in  fact  they  must  be  overlaid 
upon  the  calendar  frame  as  double¬ 
spaced,  in  order  to  leave  undisturbed 
the  frame’s  lines  that  separate  the  rows 
of  day  blocks.  DeadLines  specifies  some 
number  of  virtual  screen  lines  that  will 
be  skipped  between  lines  of  the  pat¬ 
tern  blasted  to  the  screen.  A  line  of 
CalData  is  blasted  to  the  screen;  then 
a  screen  line  is  skipped;  the  next  line 
of  CalData  is  blasted  to  the  screen,  and 
so  on.  It  is  not  a  matter  of  inserting 
empty  lines,  but  a  matter  of  “spreading 
out”  the  lines  of  the  pattern  on  the 
screen. 

TopStop  addresses  another  calendar 
gotcha:  The  months  have  different  num¬ 
bers  of  days.  To  avoid  having  Februar¬ 
ies  with  31  days,  BlkBlast  must  stop 
blasting  CalData' s  data  onto  a  Febru¬ 
ary  calendar  frame  before  it  reaches 
the  characters  for  the  29th  (except  in 
leap  years)  30th,  and  31st  days.  If  only 
a  specific  number  of  bytes  of  the  pat¬ 
tern  are  to  be  blasted  to  the  screen, 
that  number  is  passed  in  TopStop.  If  the 
entire  pattern  is  to  be  sent  to  the  screen 
(as  for  the  calendar  frame)  then  Top- 
Stop  is  passed  a  0. 

Modelling  a  Stack  Frame 

I  won’t  do  an  instruction-by-instruc- 
tion  explanation  of  how  BlkBlast  works. 
There  simply  isn’t  room  here.  What  I 
do  want  to  do  is  point  to  some  general 
techniques  that  may  help  you  create 
your  own  assembly  language  external 
modules. 

First  of  all,  model  the  stack  frame  in 
an  assembly  language  structure.  This 
is  the  item  named  ONSTACK  'm  BlkBlast. 
The  structure  allows  you  to  access  fields 
by  “dotting,”  in  a  fashion  similar  to 
what  we  do  with  Pascal  records.  Make 
sure  you  understand  what  Turbo  Pas¬ 
cal  pushes  on  the  stack  for  your  pa¬ 
rameters,  particularly  in  areas,  like  point¬ 
ers,  where  it  may  not  be  immediately 
clear  whether  the  segment  or  offset 
portion  of  the  pointer  is  pushed  first. 
(The  segment  is  pushed  first.) 

The  identifier  ONSTACK  is  not  actu¬ 
ally  referenced  in  the  routine;  it’s  only 
there  because  all  structures  must  have 
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names.  Instead,  the  structure  is  refer¬ 
enced  as  the  referent  of  SS.  fBPj,  and 
individual  fields  within  the  structure 
resolve  to  offsets  from  BP.  In  other 
words,  a  structure  reference  like  MOV 
AX, [BP],  Attr  is  equivalent  to  MOV 
AXJBP+10],  The  idea  is  to  avoid  hav¬ 
ing  to  calculate  offsets  from  BP ;  espe¬ 
cially  when  you  find  yourself  inserting 
new  fields  into  the  structure  or  rear¬ 
ranging  the  ones  that  are  there. 

Notice  the  field  named  ENDMRK  at 
the  end  of  the  structure.  ENDMRK  is 
not  actually  the  name  of  anything 
pushed  onto  the  stack.  Instead,  it  al¬ 
lows  us  to  use  an  assembly  language 
expression  to  calculate  the  number  of 
bytes  to  be  removed  from  the  stack 
when  the  external  procedure  returns 
control  to  Turbo  Pascal.  The  expres¬ 
sion  comes  at  the  very  end  of  BlkBlast: 

RET  ENDMRK-RETADDR-4 

The  operand  to  the  RET  instruction  is 
what  “cleans  up  the  stack.”  When  it 
executes,  RET  <n>  adds  <n>  bytes  to 
the  stack  pointer  (remember,  this  is  a 
push-down  stack),  at  one  stroke  wip¬ 
ing  the  stack  frame  clean  from  the  stack. 
<n>  can  be  calculated  by  subtracting 
the  start  of  the  stack  frame  from  its 
end,  minus  4  bytes  for  the  return  ad¬ 
dress.  It’s  important  to  exclude  the  size 
of  the  return  address  from  the  calcula¬ 
tion,  because  by  the  time  the  RET  in¬ 
struction  gets  around  to  adjusting  the 
stack  pointer,  it  has  already  removed 
the  return  address  from  the  stack. 

Also,  remember  that  BlkBlast  is  a 
FAR  procedure.  Had  it  been  written  as 
a  NEAR  procedure,  the  return  address 
would  have  been  a  16-bit  offset,  rather 
than  a  full  32-bit  address,  and  the  ex¬ 
pression  would  have  been: 

RET  ENDMRK-RETADDR-2 

Other  Assembly  Language  Pointers 

Be  sure  to  declare  the  name  of  the 
external  routine  as  PUBLIC,  or  Turbo 
Pascal’s  linker  will  not  be  able  to  find 
the  name  in  the  OBJ  file’s  symbol  ta¬ 
ble.  Any  identifier  that  is  to  be  known 
outside  the  .ASM  file  must  be  explicitly 
declared  as  PUBLIC.  This  is  in  addi¬ 
tion  to  adding  the  PUBLIC  directive  to 
the  declaration  of  the  external’s  code 
segment. 

The  key  to  fast  assembly  language 
work  is  to  identify  the  tight  loops  that 
are  executed  dozens  or  hundreds  of 
times  (usually  in  moving  data  from  one 
place  to  another)  and  to  keep  those 
loops  as  simple  and  empty  as  possible. 
If  you  can,  use  the  8086  string  instruc¬ 
tions  MOVSB,  STOSB,  SCASB,  and 
CMPS  with  the  REP  prefix.  As  I  men¬ 


tioned  earlier,  this  allows  you  to  (in 
effect)  code  a  loop  that  runs  entirely 
within  the  CPU,  fetching  no  instruc¬ 
tions  and  losing  no  time  to  unneces¬ 
sary  memory  accesses.  The  string  in¬ 
structions  can't  be  used  to  solve  every 
problem,  but  when  they  can,  the  re¬ 
sults  will  scorch  your  eyeballs. 

Notice  BlkBlasts  innermost  loop: 

DoChar:  LODSB 
STOSW 
LOOP  DoChar 

Because  the  attribute  must  be  “mixed” 
with  the  pattern  on  the  way  from  stor¬ 
age  to  the  virtual  screen,  this  is  one 
case  where  the  REP  prefix  can’t  be 
used.  However,  the  loop  has  been  pared 
to  its  barest  essentials:  You  load  a  byte 
from  the  pattern  into  AL  (the  attribute 
is  already  loaded  into  AH)  and  then 
store  AX  to  the  virtual  screen  as  a  char¬ 
acter/attribute  pair.  The  LODSB  and 
STOSB  instructions  increment  the  SI  and 
DI  registers  after  each  pass  through  the 
loop,  relieving  your  own  code  from 
that  burden. 

From  The  Book  CASE 

If,  like  me,  you  have  a  fondness  for 
taking  your  machine  by  the  throat  and 
shaking  it,  do  not  fail  to  obtain  Ray 
Duncan’s  new  quick  reference  guide 
from  Microsoft  Press,  IBM  ROM  BIOS. 
I’ve  used  various  sources  of  informa¬ 
tion  on  ROM  BIOS  over  the  years,  start¬ 
ing  with  the  original  1981  IBM  PC  Tech¬ 
nical  Reference,  and  most  recently  Pe¬ 
ter  Norton’s  still  excellent  Programmer's 
Guide  to  the  IBM  PC.  Ray’s  new  book 
is  lean,  lucid,  and  eminently  thumbable. 
It  summarizes  all  BIOS  services  and  is 
current  through  the  PS/2.  Furthermore, 
it  includes  summaries  of  interrupt  and 
I/O  port  usage  on  all  machines  through 
PS/2.  My  only  gripe  is  that  it  doesn’t 
summarize  ROM  BIOS  memory  usage, 
but  that’s  a  small  matter.  For  $5. 95,  it’s 
a  must-have. 

One  of  the  multitude  of  little  stupidi¬ 
ties  that  has  kept  Microsoft  from  being 
richer  than  it  is  is  their  obsession  with 
keeping  Windows  and  PM  develop¬ 
ment  an  affair  for  C  programmers.  I 
don’t  use  an  environment  I  can’t  pro¬ 
gram,  and  the  C-flavored  Windows  API 
is  about  as  organized  and  easy  to  grasp 
as  a  gauze  curtain  in  a  Chicago  gale. 
Microsoft's  insistence  that  Windows  de¬ 
velopment  is  “not  for  beginners”  in¬ 
sults  me.  The  Windows  API  wastes  my 
time,  and  I  have  very  little  patience  with 
things  like  that.  Until  Whitewater  Group’s 
Actor  language  came  along,  Windows 
simply  gathered  dust  on  my  disk. 

If  for  whatever  reason  you  must  con¬ 
front  Windows  development  under  C 


(shudder),  you  could  do  worse  than 
pick  up  Introduction  to  Windows  Pro- 
grammingby  Guy  Quedens  and  Pamela 
Beason.  It’s  not  the  entire  story  by  any 
means,  but  it’s  as  good  an  entry  point 
into  the  chaos  of  the  Windows  API  as 
you’re  likely  to  find.  You’d  better  know 
C  before  opening  it,  but  if  you  do,  the 
rest  will  come  naturally.  The  treatment 
of  the  Windows  GDI  is  particularly 
good,  with  plenty  of  screen  shots  and 
figures  to  make  the  technical  prose  gel. 
And  even  if  you’re  using  Actor,  the 
background  on  the  Windows  environ¬ 
ment  is  well  worth  reading. 

OOPS! 

One  of  my  crustier  correspondents  sent 
me  a  letter  asking  (among  other  things) 
“Who  needs  OOPS?”  I’ve  been  soaking 
my  tail  in  object-oriented  programming 
miscellany  for  the  past  couple  of 
months,  and  my  response  is  this:  If 
you’ve  ever  said  it,  you  need  it. 

We’ll  begin  taking  a  look  at  your 
OOPS  options  in  my  next  column.  The 
best  OOP  tools  have  nothing  to  do 
with  C.  Nice  thought,  isn’t  it? 

Availability 

All  source  code  for  articles  in  this  issue 
is  available  on  a  single  disk.  To  order, 
send  $14.95  (Calif,  residents  add  sales 
tax)  to  Dr.  Dobbs  Journal,  501  Galves¬ 
ton  Dr.,  Redwood  City,  CA  94063;  or 
call  800-356-2002  (from  inside  Calif.) 
or  800-533-4372  (from  outside  Calif.). 
Please  specify  the  issue  number  and 
format  (MS-DOS,  Macintosh,  Kaypro). 

DDJ 

(Listings  begin  on  page  143.) 

Vote  for  your  favorite  feature/article. 

Circle  Reader  Service  No.  13. 
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Listing  One  (Text  begins  on  page  119.) 

/* - junehook.c - */ 

/* 

*  make  these  changes  to  smallcom.c  to  install  the  script 

*  processor  program 
*/ 

/* - making  logfp  external - */ 

FILE  * logfp; 

static  FILE  ‘uploadfp,  ‘downloadfp,  *cfg; 


/* - the  hook  to  script  processors - */ 

extern  void  script (void) ; 

void  (*script_processor) (void)  =  script; 


if  ((fp  =  fopen (scriptfile,  "r"))  !=  NULL)  { 
if  (set jmp (error jmp)  ==  0)  { 

loadsource () ; 
interpret () ; 

) 

fclose (fp) ; 
if  (prompt  !=  NULL) 

reset_prompt (prompt,  25); 
if  (tokenbf  !=  NULL) 
free (tokenbf) ; 

) 

1 

/*  -  syntax  error  in  script  language  -  */ 

void  sierror(enum  errs  erno,  char  *s,  int  line) 

( 

char  msg[80); 

sprintf(msg,  "SI  Error:  %s  %s  line  %d\n", s, ermferno] , line) ; 
error  message (msg) ; 
long jmp (error jmp,  1); 

) 


End  listing  One 


Listing  Two 

/* - script. c - */ 


/* 

*  The  SI  shell  to  implement  interpreted  scripts  in  SMALLCOM 
*/ 


♦include 

♦include 

♦include 

♦include 

♦include 

♦include 

♦include 

♦include 

♦include 

♦include 


<stdio.h> 
<conio.h> 
<stdlib.h> 
<ctype.h> 
<dos.h> 
<set jmp.h> 
"window. h" 
"serial. h" 
"interp.h" 
"modem. h" 


♦if  COMPILER  -=  MSOFT 

♦define  MK_FP(s,o)  ((void  far  *)  \ 

(((unsigned  long) (s)  «  16)  |  (unsigned) (o) ) ) 
♦endif 


void  upload_ASCII (FILE  ‘); 

void  download_ASCII (FILE  *); 

void  upload_xmodem(FILE  *); 

void  down load_xmodem (FILE  *); 

int  waitforstring(char  **,  int,  int); 

char  *prompt_line(char  *,  int,  char  *); 

void  reset_prompt (char  *,  int); 


/*  - 

static  int 
static  int 
static  int 
static  int 
static  int 
static  int 
static  int 
static  int 
static  int 
static  int 
static  int 
static  int 


-  intrinsic  interpreter  functions 

si_logon(int  *); 
si_logof f (int  *); 
si_upload(int  *); 
si_download(int  *); 
si_hangup(int  *); 
si_quit(int  *); 
si_sendstring(int  *); 
si_sendchar (int  *); 
si_waitforstrings (int  ‘); 
si_waitfor (int  *); 
si_system(int  *); 
si_message (int  *); 


INTRINSIC  ffs[]  =  { 
"logon", 

"logoff", 

"upload" , 

"download", 

"hangup", 

"quit", 

"sendstring", 

"sendchar", 

"waitforstrings", 

"waitfor", 

"system" , 

"message", 

NULL, 

I; 


si_logon, 

si_logof f , 

si_upload, 

si_download, 

si_hangup, 

si_quit, 

si_sendstring, 

si_sendchar, 

si_waitforst rings, 

si_waitfor, 

si_system, 

si_message, 

NULL 


extern  INTRINSIC  *infs  =  ffs; 
extern  FILE  ‘logfp; 


/* - 

char  *erm[)=( 


-  error  messages  — 

"Unexpected  end  of  file", 
"Duplicate  ident", 

"Out  of  heap  memory", 
"Syntax  Error", 

"Unmatched  ()", 

"Not  a  function", 

"Out  of  place", 

"Token  buffer  overflow", 


- ./ 

"Unrecognized" , 

"Symbol  table  full", 
"Undeclared  ident", 
"Unmatched  {)", 
"Missing", 

"Misplaced  break", 

"Too  many  strings", 
"Divide  by  zero"  I; 


static  FILE  ‘fp; 
static  char  ‘prompt  =  NULL; 
extern  char  scriptfile!); 
extern  char  ‘tokenbf; 
jmp_buf  errorjmp; 

/* - process  the  named  script  file - */ 

void  script () 


/* - get  a  character  of  script  source  code - */ 

int  getsource (void) 

{ 

return  getc(fp); 

) 


/* - unget  a  character  of  script  source  code - */ 

void  ungetsource (int  c) 

( 

ungetc(c,  fp); 

) 

/* - intrinsic  functions - */ 

/* - turn  logging  on -  */ 

static  int  si_logon(int  *ptr) 

{ 

si_logof f (ptr)  ; 

logfp  =  fopen ((char  »)  *ptr,  "ab"); 
return  0; 

} 


/*  - turn  logging  off - */ 

static  int  si_logoff (int  *ptr) 

( 

if  (logfp) 

fclose (logfp) ; 
logfp  =  NULL; 
return  0; 

) 


/* - upload  a  file -  */ 

static  int  si_upload (int  *ptr) 

I 

FILE  ‘up; 

int  x  =  wherexO; 

int  y  =  whereyO; 

if  ((up  =  fopen ((char  *)  ptr[0),  "rb"))  !=  NULL)  ( 
if  (toupper (pt r [ 1 ) )  ==  'A') 
upload_ASCII (up) ; 
else  if  (toupper (ptr (1) )  ==  'X') 
upload_xmodem (up) ; 
fclose (up) ; 

} 

gotoxy (x, y) ; 
return  0; 


/* - download  a  file - */ 

static  int  si_download (int  *ptr) 

I 

FILE  *dn; 

int  x  =  wherexO; 

int  y  =  whereyO; 

if  ( (dn  =  fopen((char  *)  pt r [ 0 ] ,  "wb"))  !=  NULL) 
if  (toupper (ptr ( 1 ) )  ==  'A') 
download_ASCII (dn) ; 
else  if  (toupper (ptr [ 1 ) )  ==  'X') 
download_xmodem (dn) ; 
fclose (dn) ; 

> 

gotoxy (x,y) ; 
return  0; 


/*  - hangup  the  call - */ 

static  int  si_hangup (int  *ptr) 

{ 

disconnect  0 ; 
return  0; 

) 


/* - terminate  the  program -  */ 

static  int  si_quit(int  *ptr) 

I 

int  far  *bp  =  MK_FP(0x40,  Oxla);  /*  BIOS  read-ahead  buff  */ 


if  (*ptr)  1 

*bp++  =  Oxle; 
*bp++  =  0x22; 
*bp++  =  27; 

*bp  =  'y'; 


/*  next  off  pointer  */ 
/*  next  on  pointer  */ 
/*  Esc  key  */ 
/*  'y'  for  Yes  */ 
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) 

long jmp (error jmp,  1); 


/*  - send  a  string  to  the  callee - */ 

static  int  si_sendstring(int  *ptr) 
f 

char  *cp  =  (char  *)  *ptr; 

while  (*cp) 

writecomm(*cp++) ; 
return  0; 

) 

/* - send  a  character  to  the  callee - */ 

static  int  si_sendchar (int  *ptr) 

1 

writecomm(*ptr) ; 
return  0; 


/*  —  wait  for  one  of  a  set  of  strings  from  the  callee  —  */ 
static  int  si_waitforstrings (int  *ptr) 

{ 

return  waitforstring ( (char  “)  ptr[0],  60,  0); 

} 

/* - wait  for  a  string  from  the  callee - */ 

static  int  si_waitfor (int  *ptr) 

{ 

static  char  *ws[]  =  (NULL,  NULL); 

ws[0]  =  (char  *)  *ptr; 

return  waitforstring (ws,  60,  0); 


/*  -  execute  a  system  (DOS)  command  -  */ 

static  int  si_system (int  *ptr) 

( 

char  cmd[80]; 

sprintf(cmd,  "%s  >nul",  (char  *)  *ptr); 
system (cmd) ; 
return  0; 

) 

/* - display  a  message  to  the  user - */ 

static  int  si_message (int  *ptr) 

{ 

int  x  =  wherex(); 
int  y  =  whereyO; 


prompt  =  prompt_line ( (char  *)  *ptr,  25,  prompt); 
gotoxy (x, y) ; 
return  0; 


Listing  Three 


End  Listing  Two 


/■ 


PROCOMM.SCR  :  A  SMALLCOM  script  that  calls  a  ProComm  system, 
downloads  a  file,  and  uploads  another  file 


/ 


/* - key  strings  that  ProComm  sends - */ 

char  *strs[)  =  ( 

"choice?", 

"Denied" 

) ; 

char  ‘Name  =  "Name:"; 
char  ‘Password  =  "Password:"; 
char  ‘choice  =  "choice?"; 
char  ‘procedure  =  "procedure."; 
char  ‘spec  =  "spec?"; 

/* - strings  that  SMALLCOM  sends - */ 

char  ‘name  =  "A1  StevensXr"; 

char  ‘password  =  "PASSWORD\r"; 
char  ‘filenamel  =  "testl.fil"; 
char  *filename2  =  "test2 . fil" ; 

/* - poor  man's  #def ine  or  enum - */ 


int 

CHOICE 

= 

0; 

int 

DENIED 

= 

1; 

int 

XMODEM 

= 

'X 

int 

UPLOAD 

= 

'  u 

int 

DOWNLOAD 

= 

'd 

int 

GOODBYE 

= 

'g 

/* - main  entrance  to  the  script - */ 

main  () 

{ 

message ("  — >  Signing  on  to  ProComm  < — "); 

if  (signonO)  { 
downloadops () ; 
uploadops () ; 
waitfor (choice) ; 
message("  Signing  Off"); 
sendchar (GOODBYE) ; 

I 

else 


Listing  Three  (Listing  continued,  text  begins  on  page  119  ) 

message ("  Not  allowed  access!  "); 
hangup ( ) ; 

) 

/ * - sign  on  and  send  the  password -  */ 

signon () 

f 

waitfor (Name) ; 
sendstring (name) ; 
waitfor (Password) ; 
sendstring (password) ; 
if  (waitforstrings (strs)  ==  CHOICE) 
return  1; 
return  0; 


/* - download  a  file - */ 

downloadops () 


message ("  Downloading"); 

sendchar (DOWNLOAD) ; 

waitfor (choice) ; 

sendchar (XMODEM) ; 

waitfor (spec) ; 

sendstring (filenamel) ; 

sendchar (' \r' ) ; 

waitfor (procedure) ; 

download (filenamel,  XMODEM); 

system ("del  download. fil") ; 

systemC’ren  testl.fil  download,  fil") ; 


/* - upload  a  file 

uploadops ( ) 


waitfor (choice) ; 
message  ( "  Uploading" ) ; 
sendchar (UPLOAD) ; 
waitfor (choice) ; 
sendchar (XMODEM) ; 
waitfor (spec) ; 
sendstring (filename2) ; 
sendchar (' \r' ) ; 
waitfor (procedure) ; 
upload (filename2,  XMODEM); 


End  Listings 
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Listing  One  (Text  begins  on  page  124.) 

EGAPIXEL. ASM:  Reads  EGA  pixel  value  directly  from  video  memory 
Returns  pixel  value  at  x,  y,  or  -1  if  outside  viewport 
Microsoft  MASM  5.1 
C  prototype  is 

int  far  egapixel  (int  x,  int  y) ; 

To  be  included  in  GRAFIX.LIB 

K.  Porter,  DDJ  ''Graphics  Programming''  column,  June  '89 


.MODEL  LARGE 

PUBLIC  _egapixel 
EXTRN  _vuport  :  WORD 

;  Arguments  passed  from  C 
x  EQU  [bp+6] 

y  EQU  [bp+8] 


;  Macro  to  build  pixel 
pixval  MACRO 
out 
mov 
and 
neg 
rol 
dec 
ENDM 


value  in  BL 

dx,  ax 

bh,  BYTE  PTR  es: [si] 
bh,  ch 
bh 

bx,  1 
ah 


.CODE 

_egapixel 

push 

mov 

push 


PROC  FAR 
bp 

bp,  sp 
si 


;  Point  ES : [ BX ]  to  vuport  structure 

mov  ax,  _vuport+2 

mov  es,  ax 

mov  bx,  _vuport 

;  Quit  if  coordinates  outside  viewport 
mov  al,  -1 

mov  cx,  y 

cmp  cx,  WORD  PTR  es:[bx+6] 

jge  exit 

mov  dx,  x 

cmp  dx,  WORD  PTR  es:(bx+4] 

jge  exit 


far  ptr  to  vuport  structure 
Arguments  passed  from  C 


set  6845  for  bit  plane 
get  byte  from  current  bit  plane 
mask  bit 
and  flip  it 

move  to  bit  0  in  accum  (BH) 
next  bit  plane 


Entry  processing 
Save  SI  (used  here) 

get  pointer  segment 
get  offset 


;  return  value  if  outside 
;  get  y 

;  is  y  within  viewport? 

;  quit  if  not 
;  get  x 

;  is  x  within  viewport? 

;  quit  if  not 


;  Map  pixel  coordinates  to  current  viewport 

add  dx,  WORD  PTR  es: [bx]  ;  offset  x  by  vuport. left 

push  dx  ;  save  remapped  X  (used  later) 

add  cx,  WORD  PTR  es: [bx+2]  ;  offset  y  by  vuport. top 


Point  ES  to 

video 

memory 

segment 

mov 

bx, 

OAOOOh 

mov 

es, 

bx 

Row  offset 

y  * 

80; 

push 

dx 

;  (modified  by  MUL) 

mov 

ax, 

cx 

;  get  y 

mov 

bx, 

80 

mul 

bx 

;  y  *  80 

mov 

bx, 

ax 

;  into  BX 

Column  offset  =  x 

SHR  3 

pop 

ax 

;  get  x  back 

mov 

cl. 

3 

;  shift  operand 

shr 

ax, 

cl 

;  column  offset 

Complete  address 

of  pixel 

byte 

add 

bx. 

ax 

;  BX  =  row  offset  +  col  offset 

mov 

si. 

bx 

;  ES:SI  =  address 

Build  bit  mask  for  pixel 

pop 

cx 

;  get  x  back 

and 

cl, 

7 

;  isolate  low-order  bits 

xor 

cl. 

7 

;  number  of  bits  to  shift 

mov 

ch, 

1 

;  start  bit  mask 

shl 

ch, 

cl 

;  shift  for  pixel 

xor 

bl, 

bl 

;  accumulator  for  pixel  value 

Set  graphics  controller  Read  Map 

Select  Register 

mov 

dx, 

03CEh 

;  6845  command  register 

mov 

ax, 

0304h 

;  first  bit  plane  =  3 

Read  bit  planes  3-0,  accumulating  bits  in  BL 
pixval 
pixval 
pixval 
pixval 


;  AX  = 

return 

value  for 

mov 

al,  bl 

;  Send 

pixel 

value  back 

exit : 

xor 

ah,  ah 

pop 

si 

mov 

sp,  bp 

pop 

retf 

bp 

_egapixel 

ENDP 

END 

End  Listing  One 


GRAPHICS  PROGRAMMING 


Listing  Two  (Listings  continued,  text  begins  on  page  124.) 

Listing  Three 

/*  RICOCHET. C:  A  line  moving  diagonally  "feels"  its  way  among  obstacles  */ 

/*  EGAFILL.C:  Line  adjacency  flood  fill  algorithm  for  EGA  */ 

/*  Illustrates  pixel-reading  with  egapixel ()  *f 

/*  For  inclusion  in  GRAFIX.LIB  */ 

/*  K.  Porter,  DDJ  "Graphics  Programming''  column,  June  '89  */ 

/*  K.  Porter,  DDJ  ''Graphics  Programming''  column,  June  '89  */ 

finclude  "grafix.h" 

linclude  <conio.h> 

finclude  "grafix.h" 

void  main  () 

extern  int  colorl;  /*  from  GRAFIX  library  */ 

{ 

int  border  =  15;  /*  border  for  floodfill  */ 

int  x  =  638;  /*  current  X  position  of  line  */ 

int  dir  =  -1;  /*  fill  direction  *7 

int  y  =  348;  /*  and  its  Y  */ 

int  xdir  =  -1;  /*  current  X  direction  (-1  =  left,  1  =  right)  */ 

void  far  setf illborder  (int  color) 

int  ydir  =  -1;  /*  and  Y  direction  (-1  =  up,  1  =  down  */ 

( 

border  =  color; 

if  (init_video  (EGA))  { 

i  /• - - - - - . */ 

/*  Draw  a  maze  and  border  */ 

int  far  floodfill  (int  sx,  int  sy)  /*  fill  bounded  region  */ 

set  colorl  (15); 

{ 

draw  rect  (0,  0,  639,  349); 

int  x;  /*  current  column  */ 

draw  line  (141,  40,  141,  119); 

int  left,  rite;  /*  ends  of  current  line  */ 

hline  (141,  119,  120); 

byte  pixel;  /*  detected  pixel  value  */ 

draw  line  (421,  0,  421,  100); 

int  near  leftborder  (int,  int,  byte),  /*  local  functions  */ 

hline  (540,  199,  80); 

near  rightborder  (int,  int,  byte); 

hline  (360,  160,  120); 

hline  (300,  261,  120); 

/*  find  ends  of  seed  row  */ 

draw  line  (200,  259,  200,  330); 

left  =  leftborder  (sx,  sy,  border); 

draw_line  (99,  24C,  99,  349); 

rite  =  rightborder  (sx,  sy,  border) ; 

/*  Send  the  line  bouncing  around  */ 

/*  fill  seed  row  */ 

set  colorl  (4); 

draw  line  (left  +  1,  sy,  rite-1,  sy) ; 

while  ( ! kbhit ( ) )  1 

if  (egapixel  (x+xdir,  y)  ==  15)  /*  feel  ahead  horizontally  */ 

/*  fill  adjacent  rows  in  same  direction  */ 

xdir  =  -xdir;  /*  reverse  if  obstacle  */ 

for  (x  =  left+1;  x  <  rite;  x++)  ( 

if  (egapixel  (x,  y+ydir)  ==  15)  /*  same  vertically  */ 

pixel  =  egapixel  (x,  sy+dir) ;  /*  inspect  adjacent  row  */ 

ydir  =  -ydir; 

if  ((pixel  !=  colorl)  &&  (pixel  !=  border)) 

x  +=  xdir;  /*  advance  position  */ 

x  =  floodfill  (x,  sy+dir) ; 

y  +=  ydir; 

1 

draw  point  (x,  y); 

) 

/*  fill  adjacent  rows  in  opposite  direction  */ 

getch();  /*  clear  keyboard  buffer  */ 

for  (x  =  left+1;  x  <  rite;  x++)  f 

) 

pixel  =  egapixel  (x,  sy-dir) ; 

1 

if  ((pixel  ! =  colorl)  &&  (pixel  !=  border)) 

x  =  floodfill  (x,  sy-dir) ; 

dir  =  -dir; 

} 

for  (x  =  left+1;  x  <  rite;  x++)  { 

End  Listing  Two 

pixel  =  egapixel  (x,  sy-dir) ; 

(continued  on  page  142) 
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Listing  Three  (Listing  continued ,  text  begins  on  page  124.) 


Listing  Five 


if  ((pixel  !=  colorl)  &&  (pixel  !=  border)) 
x  =  floodfill  (x,  sy-dir) ; 
dir  =  -dir; 

) 

return  rite; 

1  /* - */ 


/*  Following  are  local  routines  serving  floodfill ()  */ 

int  near  leftborder  (int  x,  int  y,  byte  border) 

( 

byte  pixel; 
do  ( 

pixel  =  egapixel  (x,  y) ; 


if  ({pixel  ==  border)  j|  (pixel  ==  colorl)) 
break; 

)  while  (x  >  0) ; 
return  x; 

1  /*  -  V 


int  near  rightborder  (int  x,  int  y,  byte  border) 
{ 

byte  pixel; 

do  ( 

++x; 

pixel  =  egapixel  (x,  y) ; 


if  ({pixel  ==  border)  ||  (pixel  ==  colorl)) 
break; 

1  while  (x  <  vp_width()); 
return  x; 

I  /*  — - - - */ 


Listing  Four 

/*  From  June,  '89  */ 

/*  - */ 

int  far  egapixel  (int  x,  int  y) ; 

void  far  setf illborder  (int  color) ; 


End  Listing  Three 

/*  get  pixel  value  at  x,  y  */ 

/*  border  for  floodfill  */ 


/*  FILLS. C:  Various  filled  figures  */ 

/*  K.  Porter,  DDJ  ''Graphics  Programming''  column,  June  '89  */ 

♦include  "grafix.h" 

♦include  <conio.h> 
int  triangle []  =  ( 

20,300,  120,300,  70,200,  20,300 

) ; 

int  star(]  =  ( 

60,  10,  120,80,  20,60,  100,140,  140,110, 

260,190,  220,70,  370,30,  180,  40,  60,  10 

}  ; 

int  house []  =  { 

400,200,  400,340,  600,340,  600,200, 

500,100,  400,200 

}; 


void  main()  { 
int  x,  y; 

if  (init_video  (EGA))  ( 
set_colorl  (15) ; 
polyline  (3,  triangle); 
set_colorl  (4); 
setfillborder  (15); 
floodfill  (70,  250); 

set_colorl  (14); 
polyline  (9,  star); 
set_colorl  (6); 
setfillborder  (14); 
floodfill  (140,  80); 

set_colorl  (15); 
polyline  (5,  house); 
for  (x  =  430;  x  <  560;  x  +=  60) 
for  (y  =  220;  y  <  300;  y  +=  60) 
draw_rect  (x,  y,  20,  35); 
set_colorl  (7); 
setfillborder  (15); 
floodfill  (500,  200); 
getch()  ; 

) 

1 


int  far  floodfill  (int  sx,  int  sy) ; 


/*  fill  bounded  region  */ 


End  Listing  Four 


End  Listings 
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STRUCJURED  PROGRAMMING 


listing  One  (Text  begins  on  page  130.) 

{  Calendar  unit  demo  program  1 
{  Jeff  Duntemann  —  2/3/89  } 


TYPE 

DaysOfWeek  =  (Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, Saturday) ; 
Months  =  (January, February, March,  April, May, June, July, 

August,  September, October, November, December) ; 


PROGRAM  CalTest; 


USES  DOS, Crt, 
Screens, 
Calendar, 


{  Standard  Borland  units  } 
{  Given  in  DDJ  4/89  ) 

{  Given  in  DDJ  6/89  ) 


CONST 

YellowOnBlue  =  $1E;  (  Text  attribute;  yellow  chars  on  blue  background  ) 
CalX  =  25; 

CalY  =  5; 


VAR 

MyScreen 

WorkScreen 

Ch 

Quit 

ShowFor 

I 


ScreenPtr;  (  Type  exported  by  Screens  unit  } 

Screen;  (  Type  exported  by  Screens  unit  } 

Char; 

Boolean; 

DateTime;  {  Type  exported  by  DOS  unit  ) 

Word;  (  Dummy;  picks  up  dayofweek  field  in  GetDate  ) 


BEGIN 

MyScreen  :=  @WorkScreen;  (  Create  a  pointer  to  WorkScreen  ) 
InitScreen (MyScreen, True) ; 

ClrScreen (MyScreen, ClearAtom) ;  (  Clear  the  entire  screen  ) 

Quit  :=  False; 


WITH  ShowFor  DO  (  Start  with  clock  date  ) 
GetDate (Year, Month, Day, I) ; 


ShowCalendar (MyScreen, ShowFor, CalX, CalY, YellowOnBlue) ; 


REPEAT  (  Until  Enter  is  pressed:  } 

IF  Keypressed  THEN  (  If  a  keystroke  is  detected  ) 

BEGIN 

Ch  :=  ReadKey;  (  Pick  up  the  keystroke  ) 

IF  Ord(Ch)  *  0  THEN  j  See  if  it's  an  extended  keystroke  ) 

BEGIN 

Ch  :=  ReadKey;  (  If  so,  pick  up  scan  code  ) 

CASE  Ord(Ch)  OF  (  and  parse  it  ) 

72  :  Pan (MyScreen, Up, 1) ;  (  Up  arrow  ) 

80  :  Pan (MyScreen, Down, 1) ;  (  Down  arrow  } 

75  :  BEGIN  (  Left  arrow;  "down  time"  ) 

WITH  ShowFor  DO 
IF  Month  =■=  1  THEN 
BEGIN 

Month  :=  12; 

Dec (Year) 

END 

ELSE  Dec (Month); 

ShowCalendar (MyScreen, ShowFor, CalX, CalY, YellowOnBlue) ; 
END; 

77  :  BEGIN  (  Right  arrow;  "up  time"  ) 

WITH  ShowFor  DO 

IF  Month  =  12  THEN 
BEGIN 

Month  :=  1; 

Inc (Year) 

END 


ELSE  Inc (Month); 

ShowCalendar (MyScreen, ShowFor, CalX, CalY, YellowOnBlue) ; 
END; 

END  (  CASE  ) 

END 

ELSE  (  If  it's  an  ordinary  keystroke,  test  for  quit:  ) 

IF  Ch  =  Chr  (13)  THEN  Quit  :=  True 

END; 

UNTIL  Quit; 

ClrScreen (MyScreen, ClearAtom)  (  All  this  stuff's  exported  by  Screens  ) 
END. 


End  Listing  One 


Listing  Two 


{ - , 

.{  CALENDAR  ) 
{  ) 
{  Text  calendar  for  virtual  screen  platform  ) 
{  ) 
{  by  Jeff  Duntemann  KI6RA  ) 
{  Turbo  Pascal  5.0  ) 
{  Last  modified  2/3/89  } 
I - ) 


UNIT  Calendar; 
INTERFACE 


USES  DOS, 

Textlnfo, 

Screens, 

CalCalc; 


{  Standard  Borland  unit  } 

(  Given  in  DDJ  3/89  ) 

(  Given  in  DDJ  4/89  ) 

{  Given  in  DDJ  6/89  courtesy  Michael  Covington  ) 


PROCEDURE  ShowCalendar (Target 
ShowFor 
CalX, CalY 
Attribute 


ScreenPtr; 

DateTime; 

Integer; 

Byte); 


IMPLEMENTATION 

TYPE 

StringlO  =  STRING [10]; 

CONST 

MonthNames  :  ARRAY [January . .December]  OF  StringlO  = 

('January' , ' February' ,  ' March' , ' April' , ' May' , ' June' , ' July' , 
'August' ,  ' September' , 'October' , ' November' , ' December' ) ; 

Days  :  ARRAY [January. . December ]  OF  Integer  = 

(31,28,31,30,31,30,31,31,30,31,30,31); 

( $L  CALBLKS) 

f  $F+ )  PROCEDURE  CalFrame;  EXTERNAL; 

PROCEDURE  Caldata;  EXTERNAL; 

( $F-) 

{ $L  BLKBLAST) 

{ $F+ ) 

PROCEDURE  BlkBlast (ScreenEnd, StoreEnd 
ScreenX, ScreenY 
ULX, ULY 
Width, Height 
Attribute 
DeadLines 
TopS top 

EXTERNAL; 

{ $F- 1 


:  Pointer; 
:  Integer; 
:  Integer; 
:  Integer; 
:  Byte; 

:  Integer; 
:  Integer) 


FUNCTION  IsLeapYear (Year  :  Integer)  :  Boolean; 
(  Works  from  1901  -  2199  ) 

BEGIN 

IsLeapYear  False; 

IF  (Year  MOD  4)  -  0  THEN  IsLeapYear  :=  True 
END; 


PROCEDURE  FrameCalendar (Target 

CalX, CalY 
Attribute 
StartDay 
DayCount 


ScreenPtr; 

Integer; 

Byte; 

DaysOfWeek; 
Integer) ; 


TYPE 

PointerMath  -  RECORD 

CASE  BOOLEAN  OF 
True  :  (APointer 
False  :  (OfsWord 
SegWord 

END; 


Pointer) ; 

Word; 

Word) 


VAR 

DataPtr  : 
Fudge It  : 
Daylnset  : 
DayTopStop  : 


Pointer; 

PointerMath; 

Word; 

Word; 


BEGIN 

(  Daylnset  allows  is  to  specify  which  day  of  the  week  the  first  of  the  } 
(  month  falls.  It's  an  offset  into  the  block  containing  day  figures  } 
Daylnset  :=  (7-Ord (StartDay) ) *4 ; 

(  DayTopStop  allows  us  to  specify  how  many  days  to  show  in  the  month.  ) 
DayTopStop  :=  28+ (DayCount*4) -Daylnset; 

BlkBlast (Target, SCalFrame,  (  Display  the  calendar  frame  ) 

{  Genned  screen  size  from  Textlnfo  unit  ) 

(  Show  at  specified  coordinates  ) 

(  Size  of  calendar  frame  block  ) 

(  Attribute  to  use  for  calendar  frame  ) 

{  No  interspersed  empty  lines  ) 

(  No  topstop;  show  the  whole  thing.  ) 


Vis ibleX, Visible Y, 
CalX, CalY, 

29,17, 

Attribute, 

0, 

0); 


WITH  Fudgelt  DO  {  Fudgelt  is  a  free  union  allowing  pointer  arithmetic  } 
BEGIN 

APointer  :=  @CalData;  (  Create  the  pointer  to  the  days  block  } 
OfsWord  :=  Of sWord+Daylnset;  {  Offset  into  block  for  start  day  } 


BlkBlast (Target, APointer, 

VisibleX, VisibleY, 
CalX+1, CalY+5, 

28,  6, 

Attribute, 

1, 

DayTopStop) 

END 

END; 


{  Blast  the  day  block  over  the  } 

(  calendar  frame  ) 

1  Pos.  of  days  relative  to  frame  } 

{  Size  of  day  block  ) 

{  Show  days  in  same  color  as  frame  } 

{  Insert  1  line  between  block  lines  ) 

{  Set  limit  on  number  of  chars  to  } 

{  be  copied  from  block  to  control  ) 

(  how  many  days  shown  for  a  month  } 


PROCEDURE  ShowCalendar (Target  :  ScreenPtr; 

(continued  on  page  148) 
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Listing  Two  ( Listing  continued,  text  begins  on  page  130.) 

end; 

ShowFor  :  DateTime? 

procedure  caldate (date : real;  var  year, month, day:integer) ; 

CalX,CalY  :  Integer; 

[  Inverse  of  DAYNUMBER;  given  date,  finds  year,  month,  and  day.  ) 

Attribute  :  Byte) ; 

{  Uses  real  arithmetic  because  numbers  are  too  big  for  integers.  ) 

CONST 

var 

a,aa,b,c,d,e, z:  real; 

NameOffset  :  ARRAY [January . .December)  OF  Integer  = 

y:  integer; 

(8,8,10,10,11,10,10,9,7,8,8,8) ; 

begin 

VAR 

z  :=  int (date  +  2444239.0); 
if  date  <  -145078.0  then 

StartDay  :  DaysOfWeek; 

{  Julian  calendar  ) 

TargetMonth  :  Months; 

a  :=  z 

TargetDay  :  Real; 

else 

DaysInMonth  :  Integer; 

(  Gregorian  calendar  ) 

BEGIN 

begin 

aa  :=  floor ( (z-1867216.25) /36524 .25) ; 

(  First  figure  day  number  since  1980:  ) 

a  :=  z  +  1  +  aa  -  f loor (aa/4 . 0) 

WITH  ShowFor  DO  TargetDay  :=  DayNumber (Year, Month, 1) ; 

end; 

{  Then  use  the  day  number  to  calculate  day-of-the-week:  ) 

b  :=  a  +  1524.0; 

StartDay  :=  DaysOfWeek (WeekDay (TargetDay) -1) ; 

c  :=  int ( (b-122 . 1) /365.2S) ; 

TargetMonth  :=  Months (ShowFor .Month-1) ; 

d  :=  int  (365.25*c) ; 

DaysInMonth  :=  Days [TargetMonth] ; 

e  :*  int ( (b-d) /30 . 6001) ; 

(  Test  and/or  adjust  for  leap  year:  ) 

day  :=  trunc(b  -  d  -  int (30. 6001*e) ) ; 

IF  TargetMonth  =  February  THEN 

if  e  >  13.5  then  month  :=  trunc(e  -  13.0) 

IF  IsLeapYear (ShowFor . Year)  THEN  DaysInMonth  :=  29; 

else  month  :=  trunc(e  -  1.0); 

{  Now  draw  the  frame  on  the  virtual  screen!  ) 

if  month  >  2  then  y  :=  trunc(c  -  4716.0) 

FrameCalendar (Target, 

else  y  :=  trunc(c  -  4715.0); 

CalX, CalY, 

if  y  <  1  then  year  :=  y  -  1 

Attribute, 

else  year  :=  y 

StartDay, 

end; 

DaysInMonth) ; 

(  Add  the  month  name  and  year  atop  the  frame:  ) 

function  weekday (date: real) :integer; 

GotoXY (Target, CalX+NameOf f set (TargetMonth) ,CalY+l) ; 

(  Given  day  number  as  used  in  the  above  routines,  ) 

WriteTo (Target , MonthNames [TargetMonth) +'  ' +IntStr (ShowFor .Year, 4) ) ; 

(  finds  day  of  week  (1  =  Sunday,  2  -  Monday,  etc.).  ) 

END; 

var 

END. 

dd:  real; 
begin 

dd  :=  date; 

while  dd  >  28000.0  do  dd: =dd-28000 . 0; 

End  Listing  Two 

while  dd  <  0  do  dd: =dd+28000 . 0; 
weekday  :-  ((trunc(dd)  +  1)  mod  7)  +  1 
end; 

function  julian (date:real) :real; 

{  Converts  result  of  DAYNUMBER  into  a  Julian  date.  } 
begin 

Listing  Three 

julian  :=  date  +  2444238.5 
end; 

END.  (  CalCalc  ) 

UNIT  CalCalc; 

(  —  Calendrics  —  ) 

End  Listing  Three 

(  Long-range  calendrical  package  in  standard  Pascal  ) 

{  Copyright  1985  Michael  A.  Covington  ) 

INTERFACE 

Listing  Four 

function  daynumber (year, month, day : integer) :real; 

procedure  caldate (date: real;  var  year, month, day : integer) ; 

function  weekday (date : real) :  integer; 

function  julian (date : real) :real; 

IMPLEMENTATION 

function  floor (x : real)  :  real; 

{  Largest  whole  number  not  greater  than  x.  ) 

BLKBLAST  -  Blast  2D  character  pattern  and  attributes  into  memory 

by  Jeff  Duntemann  3  February  1989 

BLKBLAST  is  written  to  be  called  from  Turbo  Pascal  5.0  using  the  EXTERNAL 
machine-code  procedure  convention. 

This  version  is  written  to  be  used  with  the  SCREENS. PAS  virtual  screens 

{  Uses  real  data  type  to  accommodate  large  numbers.  ) 

unit  for  Turbo  Pascal  5.0.  See  DDJ  for  4/89. 

begin 

if  (x  <  0)  and  (frac(x)  <>  0)  then 

Declare  the  procedure  itself  as  external  using  this  declaration: 

floor  :=  int(x)  -  1.0 
else 

PROCEDURE  BlkBlast (ScreenEnd, StoreEnd  :  Pointer; 

floor  :=  int (x) 

ScreenX, ScreenY  :  Integer; 

end; 

ULX, ULY  :  Integer; 

' 

Width, Height  :  Integer; 

function  daynumber (year, month, day: integer) :real; 

Attribute  :  Byte; 

DeadLines  :  Integer; 

TopStop  :  Integer) ; 

(  Number  of  days  elapsed  since  1980  January  0  (1979  December  31) .  ) 

EXTERNAL; 

{  Note  that  the  year  should  be  given  as  (e.g.)  1985,  not  just  85.  ) 

(  Switches  from  Julian  to  Gregorian  calendar  on  Oct.  15,  1582.  } 

The  idea  is  to  store  a  video  pattern  as  an  assembly-language  external  or 

var 

as  a  typed  constant,  and  then  blast  it  into  memory  so  that  it  isn't  seen 

y,m:  integer; 

to  "flow"  down  from  top  to  bottom,  even  on  8088  machines. 

a,b, d:  real; 
begin 

During  the  blast  itself,  the  attribute  byte  passed  in  the  Attribute 

if  year  <  0  then  y  :=  year  +  1 

parameter  is  written  to  the  screen  along  with  the  character  information 

else  y  :=  year; 

pointed  to  by  the  source  pointer.  In  effect,  this  means  we  do  a  byte-sized 

m  :=  month; 

read  from  the  source  character  data,  but  a  word-sized  write  to  the  screen. 

if  month  <  3  then 
begin 

The  DeadLines  parm  snecifies  how  many  screen  lines  to  skip  between  lines  of 

m  :=  m  +  12; 

the  pattern.  The  skipped  lines  are  not  disturbed.  TopStop  provides  a  byte 

y  y  -  1 

count  that  is  the  maximum  number  of  bytes  to  blast  in  from  the  pattern. 

end; 

If  a  0  is  passed  in  TopStop,  the  value  is  ignored. 

d  :=  floor (365 . 25*y)  +  int (30. 6001* (m+1) )  +  day  -  723244.0; 
if  d  <  -145068.0  then 

To  reassemble  BLKBLAST: 

[  Julian  calendar  ) 
daynumber  :=  d 

Assemble  this  file  with  MASM  or  TASM:  "OMASM  BLKBLAST;" 

else 

{  Gregorian  calendar  ) 

(The  semicolon  is  unnecessary  with  TASM.) 

begin 

No  need  to  relink;  Turbo  Pascal  uses  the  .OBJ  only. 

a  :=  floor (y/100.0) ; 
b  :=  2  -  a  +  floor (a/4.0) ; 

_ 

daynumber  :=  d  +  b 
end 

STACK  PROTOCOL 
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This  creature  puts  lots  of  things  on  the  stack.  Study  closely: 


;Caller's  BP  value  saved  on  the  stack 

;Full  32-bit  return  address.  (This  is  a  FAR  proc!) 

/•Maximum  number  of  chars  to  be  copied  from  block  pattern 
/•Number  of  lines  of  dead  space  to  insert  between  blasted  lines 
/•Attribute  to  be  added  to  blasted  pattern 
/Height  of  block  to  be  blasted  to  the  screen 
; Width  of  block  to  be  blasted  to  the  screen 
;Y  coordinate  of  upper  left  corner  of  the  block 
;X  coordinate  of  the  upper  left  corner  of  the  block 
;Genned  max  Y  dimension  of  current  visible  screen 
;Genned  max  X  dimension  of  current  visible  screen 
; 32-bit  pointer  to  block  pattern  somewhere  in  memory 
; 32-bit  pointer  to  an  array  of  pointers  to  screen  lines 
;Dummy  field  for  stack  struct  size  calculation 


SEGMENT  PUBLIC 
ASSUME  CS : CODE 
PUBLIC  BlkBlast 


source  block.  Also  note  the  addition  of  the  deadspace  adjustment  to 
BX  ‘before*  BX  is  copied  into  DI,  so  that  the  adjustment  will  be 
retained  through  all  the  rest  of  the  lines  moved.  Finally,  we  subtract 
the  number  of  characters  in  a  line  from  TopStop,  and  see  if  there  are 
fewer  counts  left  in  TopStop  than  there  are  characters  in  a  block  line. 
If  so,  we  force  BWidth  to  the  number  of  remaining  characters,  and 
BHeight  to  one,  so  that  we  will  blast  only  one  remaining  (short)  line. 


BlkBlast  PROC  FAR 
PUSH  BP 
MOV  BP, SP 

PUSH  DS 


;Save  Turbo  Pascal's  BP  value 
;SP  becomes  new  value  in  BP 
,*Save  Turbo  Pascal's  DS  value 


If  a  zero  is  passed  in  TopStop,  then  we  fill  the  TopStop  field  in  the 
struct  with  the  full  size  of  the  block,  calculated  by  multiplying 
BWidth  times  BHeight.  This  makes  it  unnecessary  for  the  caller  to 
pass  the  full  size  of  the  block  in  the  TopStop  parameter  if  topstopping 
is  not  required. 


[BP] .TopStop, 0  ;  See  if  zero  was  passed  in  TopStop 

GetPtrs  ;  If  not,  skip  this  operation 

AX, (BP) .BWidth  ;  Load  block  width  into  AX 
(BP) .BHeight  ;  Multiply  by  block  height,  to  AX 
[BP] .TopStop, AX  ;  Put  the  product  back  into  TopStop 


;  The  first  important  task  is  to  get  the  first  pointer  in  the  ShowPtrs 
;  array  into  ES:DI.  This  involved  two  LES  operations:  The  first  to  get 

;  the  pointer  to  ShowPtrs  (field  Screen  in  the  stack  struct)  into  ES.-DI, 

;  the  second  to  use  ES:DI  to  get  the  first  ShowPtrs  pointer  into  ES:DI. 

;  Remembering  that  ShowPtrs  is  an  ‘array*  of  pointers,  the  next  task  is 
;  to  index  DI  into  the  array  by  multiplying  the  top  line  number  (ULY) 

;  less  one  (because  we' re  one-based)  by  4  using  SHL  and  then  adding  that 
;  index  to  DI : 

GetPtrs:  LES  DI, [BP] .Screen  ;  Address  of  ShowPtrs  array  in  ES:DI 

MOV  CX, [BP] .ULY  ;  Load  line  address  of  block  dest .  to  CX 

DEC  CX  ;  Subtract  1  'cause  we're  one-based 

SHL  CX,  1  ;  Multiply  CX  by  4  by  shifting  it  lef-t... 

SHL  CX,1  ;  ...twice. 

ADD  DI,CX  ;  Add  the  resulting  index  to  DI. 

MOV  BX,DI  ;  Copy  offset  of  ShowPtrs  into  BX 

MOV  DX,ES  ;  Copy  segment  of  ShowPtrs  into  DX 

LES  DI , ES : [ DI ]  ;  Load  first  line  pointer  into  ES:DI 


The  inset  from  the  left  margin  of  the  block's  destination  is  given  in 
struct  field  ULX.  It's  one-based,  so  it  has  to  be  decremented  by  one, 
then  multiplied  by  two  using  SHL  since  each  character  atom  is  two  bytes 
in  size.  The  value  in  the  stack  frame  is  adjusted  (it's  not  a  VAR  parm, 
so  that's  safe)  and  then  read  from  the  frame  at  the  start  of  each  line 
blast  and  added  to  the  line  offset  in  DI. 


[BP] .ULX  ;  Subtract  1  'cause  we're  one-based 
[BP]. ULX, 1  ;  Multiply  by  2  to  cover  word  moves 
DI,[BP].ULX  ;  And  add  the  adjustment  to  DI 


One  additional  adjustment  must  be  made  before  we  start:  The  Deadspace 
parm  puts  1  or  more  lines  of  empty  space  between  each  line  of  the  block 
that  we're  blasting  onto  the  screen.  This  value  is  passed  in  the 
DEADLNS  field  in  the  struct.  It's  passed  as  the  number  of  lines  to  skip, 
but  we  have  to  multiply  it  by  4  so  that  it  becomes  an  index  into  the 
ShowPtrs  array,  each  element  of  which  is  four  bytes  in  size.  Like  ULX, 
the  value  is  adjusted  in  the  stack  frame  and  added  to  the  stored  offset 
value  we  keep  in  DX  each  time  we  set  up  the  pointer  in  ES:DI  to  blast  the 
next  line. 


SHL  [BP] .DEADLNS, 1  ;  Shift  dead  space  line  count  by  1. 

SHL  [BP] .DEADLNS, 1  ;  ...and  again  to  multiply  by  4 

LDS  SI, [BP] .Block  ;  Load  pointer  to  block  into  DS:SI 


This  is  the  loop  that  does  the  actual  block-blasting.  Two  counters  are 
kept,  and  share  CX  by  being  separate  values  in  CH  and  CL.  After 
each  line  blast,  both  pointers  are  adjusted  and  the  counters  swapped, 
the  LOOP  counter  decremented  and  tested,  and  then  the  counters  swapped 
again. 


MovEm:  MOV  CX,  [BP]  .BWidth  ,*  Load  atom  counter  into  CH 

MOV  AH, BYTE  PTR  [BP] .Attr  ;  Load  attribute  into  AH 

DoChar:  LODSB  ;  Load  char  from  block  storage  into  AL 

STOSW  ;  Store  AX  into  ES:DI;  increment  DI  by  2 

LOOP  DoChar  ;  Go  back  for  next  char  if  CX  >  0 


BX, [BP] .DeadLns 
DI,  ES : [BX] 

DI,  [BP] .ULX 

AX, [BP] .TopStop 
AX, [BP] .BWidth 
GoHome 

[BP] .TopStop,  AX 
AX, [BP] .BWidth 
MovEm 

[BP] .BWidth, AX 
MovEm 


Copy  ShowPtrs  segment  from  DX  into  ES 

Bounce  BX  to  next  pointer  offset 

Add  deadspace  adjustment  to  BX 

Load  next  pointer  into  ES:DI 

Add  adjustment  for  X  offset  into  screen 

Load  current  TopStop  value  into  AX 
Subtract  BWidth  from  TopSTop  value 
If  TopStop  is  <=  zero,  we're  done. 

Put  TopStop  value  back  in  stack  struct 
Compare  what  remains  in  TopStop  to  BWidth 
If  at  least  one  BWidth  remains,  loop  again 
Otherwise,  replace  BWidth  with  remainder 
and  jump  to  last  go-thru 


When  the  outer  loop  is  finished,  the  work  is  done.  Restore  registers 
and  return  to  Turbo  Pascal. 


GoHome:  POP 
MOV 
POP 
RET 


BlkBlast  ENDP 
CODE  ENDS 
END 


ENDMRK-RETADDR-4 


Restore  Turbo  Pascal's 

Restore  Turbo  Pascal's  stack  pointer... 

. . .and  BP 

Clean  up  stack  and  return  as  FAR  proc! 
(would  be  ENDMRK-RETADDR-2  for  NEAR...) 


End  Listing  Four 


Listing  Five 

TITLE  CalBlks  —  External  calendar  pattern  blocks 

;  By  Jeff  Duntemann  —  TASM  1.0  --  Last  modified  3/1/89 

;  For  use  with  CALENDAR. PAS  and  BLKBLAST. ASM  as  described  in  DDJ  6/89 

CODE  SEGMENT  WORD 

ASSUME  CS : CODE 


CalFrame  PROC  FAR 

PUBLIC  CalFrame 

DB  1  | - 


DB 

DB 

DB 

DB 

DB 

DB 

DB 

DB 

DB 

DB 

DB 

Calf rame  ENDP 


CalData  PROC  FAR 

PUBLIC  CalData 

DB  1  I  I 


2 

31 

4 

5 

6 

7 

9 

10 

11 

12 

13 

14 

16 

17 

18 

19 

20 

21 

23 

24 

25 

26 

27 

28 

30 

31 

End  Listings 


Immediately  after  a  line  is  blasted  from  block  to  screen,  we  adjust. 
First  we  move  the  pointer  in  ES:DI  to  the  next  pointer  in  the 
Turbo  Pascal  ShowPtrs  array.  Note  that  the  source  pointer  does  NOT 
need  adjusting.  After  blasting  through  one  line  of  the  source  block, 
SI  is  left  pointing  at  the  first  character  of  the  next  line  of  the 
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The  availability  of  an  ANSI  Fortran  77 
standard  compiler  for  FlexOS  386  — a 
real-time,  protected-mode  operating 
system  — has  been  announced  by  Digi¬ 
tal  Research.  Offered  by  TransWare 
Enterprises  of  San  Jose,  Calif.,  the 
Lahey  F77L  compiler’s  capabilities  in¬ 
clude  real-time  control  in  a  multiuser 
and  multitasking  environment,  and  For¬ 
tran  and  DOS  support. 

The  Lahey  F77L  for  FlexOS  386  sup¬ 
ports  the  functionality  of  FlexOS,  in¬ 
cluding  32-bit  protected-mode  code  gen¬ 
eration  for  Intel  80386  microprocessor- 
based  systems  and  the  mutiltasking/ 
multiuser  capabilities  of  FlexOS  386. 
Additionally,  F77L-386  provides  adher¬ 
ence  to  the  IEEE  standard  for  floating 
point  arithmetic.  Suggested  real  price 
is  $1,277.  Reader  Service  No.  20. 

Digital  Research,  Inc. 

Box  DRI 

Monterey,  CA  93942 
408-649-3896 

Abraxas  Software  has  announced  a 
new  software  development  tool  called 
CodeCheck,  which  analyzes  code  for 
portability,  maintainability,  and  style. 

CodeCheck  is  designed  to  target  code 
for  compatibility  among  PC  DOS, 
OS/2,  Unix,  VMS,  and  Macintosh  environ¬ 
ments.  According  to  Abraxas,  Code- 
Check  also  identifies  complex  code  as 
it  is  written. 

Selling  for  $295,  CodeCheck  supports 
C  compilers  from  major  vendors  and 
requires  512K  memory.  Reader  Service 
No.  21. 

Abraxas  Software,  Inc. 

P.O.  Box  19586 
Portland,  OR  97219 
503-244-5253 

Guidelines  Software  Inc.,  creator  of 
Guidelines  C++  for  MS-DOS,  has  re¬ 
leased  Guidelines  C++  for  Unix  V/386. 
C++  is  a  superset  of  the  C  language  and 
is  ANSI  C  compatible. 


C++  supports  object-oriented  program¬ 
ming  with  such  features  as  classes,  in¬ 
heritance,  member  functions,  construc¬ 
tors  and  destructors,  data  hiding,  and 
data  abstractions.  C++  is  implemented 
as  a  translator  and  requires  a  back-end 
C  compiler  to  produce  executable  code. 

Guidelines  C++  for  MS-DOS  sells  for 
$295  and  requires  640K  of  RAM,  a  hard 
disk,  and  Microsoft  C  3.0  or  later.  Guide¬ 
lines  C++  for  Unix  V/386  sells  for  $495 
and  works  with  standard  Unix  C  com¬ 
pilers;  it  also  supports  cross  translation 
with  MS-DOS  as  the  target  system. 
Reader  Service  No.  22. 

Guidelines  Software,  Inc. 

P.O.  Box  749 
Orinda,  CA  94563 
415-254-9183 

StarPath  Systems  has  released  Vmos/ 
3,  a  virtual  multitasking  operating  sys¬ 
tem  for  the  80386.  Vmos/3  supports 
multitasking  of  DOS  software  on  80386 
PCs,  using  demand  and  virtual  paging 
of  memory. 

Vmos/3  supports  multitasking  on  stan¬ 
dard  1 -Mbyte  DOS  systems;  it  also  man¬ 
ages  and  pages  memory  in  4K  por¬ 
tions,  rather  than  as  fixed  partitions  or 
virtual  machines.  Vmos/3  makes  use 
of  available  RAM  for  an  automatic  disk 
cache.  This  cache  memory  is  automati¬ 
cally  released  for  task  use,  as  required. 

Video  adapter  support  includes  all 
modes  of  MDA,  CGA,  EGA,  and  VGA 
in  background  and  foreground.  Graph¬ 
ics  tasks  running  in  background  auto¬ 
matically  have  their  screens  displayed 
when  brought  into  foreground;  there 
is  no  need  to  “repaint”  the  screen  to 
see  its  current  contents.  An  operator 
mode  provides  real-time  status  displays 
of  resource  usage.  A  running  system 
log  may  be  displayed  and  examined, 
and  is  stored  on  disk. 

Several  Vmos/3  supplemental  prod¬ 
ucts  are  in  development  at  StarPath, 
such  as  a  multiuser  that  supports  serial 
terminals  under  DOS,  and  a  32-bit  API, 
which  is  an  inegrated  LAN,  DOS,  and 
386  development  environment. 

Vmos/3  sells  for  $99;  the  multiuser 
option  is  $99.  Reader  Service  No.  23. 
StarPath  Systems 
4700  S  Hagadorn  Rd. 

East  Lansing,  MI  48823 
800-456-8667 

An  80386  native  mode  software  debug¬ 
ger,  which  will  be  available  by  year 
end,  has  been  introduced  by  Intel.  The 
debugger  features  a  windowed,  source- 
level  user-interface  technology  with 
drop-down  menus,  functions  keys,  and 
mouse  support. 

With  this  product,  users  can  scroll 
across  source  files,  “point  and  go”  to  a 


line  at  the  cursor,  and  use  drop-down 
menus  to  view  the  sequence  of  proce¬ 
dure  calls,  parameters,  and  local  vari¬ 
able  values. 

The  80386 software  development  pack¬ 
age  will  include  the  software  debugger 
feature  in  the  new  user  interface,  com¬ 
piler,  assembler,  linker,  locator,  and 
other  software  utilities.  The  single  unit 
price  of  the  package  will  be  $4,500. 
Reader  Service  No.  24. 

Intel  Corp. 

Literature  Dept.  BP  10 
3065  Bowers  Ave. 

Santa  Clara,  CA  95051 

800-548-4725 

800-874-6835 

Pascal-2  is  now  available  for  Xenix/386 
machines,  Oregon  Software  has  an¬ 
nounced.  In  addition  to  the  DEC  hosts, 
Pascal-2  is  available  for  Sun-3,  Motorola 
680x0,  and  Apollo  workstations,  as  well 
as  the  80286  running  MS-DOS. 

According  to  Oregon  Software,  it  has 
adhered  to  level  1  of  the  Pascal  lan¬ 
guage  standard  as  defined  by  the  Inter¬ 
national  Standards  Organization;  thus, 
users  of  Pascal-2  can  port  their  Pascal-2 
code  from  one  machine  to  another. 

The  80386  environment  can  address 
two  segments:  data  and  text.  Each  seg¬ 
ment  supports  up  to  1  gigabyte  of  mem¬ 
ory.  The  text  section  supports  32-bit 
addressing.  The  Pascal-2  Xenix/386  com¬ 
piler  is  accompanied  by  a  debugger, 
assembly  language  interface,  source 
code  formatter,  procedure  cross-refer- 
encer,  and  identifier  cross-referencer. 

Oregon  Software  also  provides  C++ 
and  Modula-2  compilers  on  the  Sun-3- 
Oregon  Modula-2  is  available  on  VAX/ 
VMS  and  Xenix/386.  Oregon  C++  will 
be  available  on  Xenix/386  in  June. 

Pascal-2  Xenix/386  lists  for  $995  for 
a  single  user  license,  and  $250  per  year 
for  support  services.  Network  licenses 
are  also  available.  Reader  Service  No.  26. 
Oregon  Software 
6915  SW  Macadam  Ave. 

Portland,  OR  97219-2397 
503-245-2202 

Parallel  Logic  Programming  (PLP) 
has  announced  the  launch  of  MacPar- 
log  and  PC-Parlog,  implementations  of 
Parlog  for  the  Macintosh  and  IBM  PC 
families  of  microcomputers. 

Parlog  (PARallel  LOGic)  is  a  logic 
programming  language  designed  at  Im¬ 
perial  College  in  London.  It  supports  a 
declarative  style  of  programming,  com¬ 
bined  with  an  execution  mechanism 
for  parallel  architectures.  On  sequen¬ 
tial  architectures,  Parlog  programs  are 
executed  by  timesharing  the  single  proc¬ 
essor  between  processes. 

(continued  on  page  155) 
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(continued  from  page  150) 

MacParlog  is  compatible  with  the  Macin¬ 
tosh  Plus,  SE,  and  II;  PC-Parlog  works 
on  IBM  PCs  and  compatibles.  These 
products  are  aimed  at  researchers  and 
product  developers  who  need  a  testbed 
environment  for  experiment  and  proto¬ 
type  construction  in  AI  and  parallel 
computing,  as  well  as  those  wishing  to 
learn  about  concurrent  logic  program¬ 
ming  and  fifth  generation  computing. 

MacParlog  and  PC-Parlog  feature  an 
incremental  compiler  for  Parlog,  a  con¬ 
current  debugger  with  dynamic  win¬ 
dow  tracing,  a  base  of  primitives,  and 
a  run-time  system  that  uses  a  “bounded 
depth-first”  scheduling  mechanism. 
MacParlog  is  integrated  into  the  Macin¬ 
tosh  WIMP  environment,  and  MacPar¬ 
log  programs  can  create  and  maintain 
windows,  menus,  and  dialogues. 

In  an  arrangement  with  Logic  Pro¬ 
gramming  Associates,  PLP  has  devel¬ 
oped  toolkit  versions  of  these  two  prod¬ 
ucts  that  coreside  with  LPS’s  products 
MacProlog  and  Prolog  Professional. 
These  versions  are  targeted  to  third- 
party  product  developers  seeking  to 
develop  mixed-language  stand-alone 
applications. 

The  single-machine  license  for  MacPar¬ 
log  or  PC-Parlog  sells  for  $250.  Reader 
Service  No.  25. 

Parallel  Logic  Programming  Ltd. 

P.O.  Box  49 
Twickenham 
England  TW2  5PH  UK 

PURART  has  released  Trapper,  a  de¬ 
bugger  board  that  assists  Borland’s 
Turbo  Debugger  by  watching  for 
memory  and  I/O  activity  from  the 
debugger’s  breakpoint  menu.  Trapper 
also  supports  an  optional  coprocessor 
pod  for  developers  who  want  to  trap 
program  instruction  accesses  to  the  math 
coprocessor  chip. 

With  Trapper,  developers  can  locate 
“memory  bashing”  bugs  by  providing 
breakpoints  whenever  a  program  ac¬ 
cesses  a  memory  address  or  range  of 
address;  code  in  ROM,  such  as  BIOS 
routines;  and  an  I/O  port  or  range  of 
ports. 

Additionally,  Trapper  provides  a  break¬ 
out  button,  allowing  developers  to  get 
back  into  the  debugger  even  if  a  pro¬ 
gram  has  disabled  interrupts.  Trapper 
sells  for  $195. 95.  Reader  Service  No.  27. 
PURART,  Inc. 

P.O.  Box  189 

Hampton  Falls,  NH  03844 

603-772-9907 

A  ROM-resident  operating  system,  ROM- 
DOS  has  been  launched  by  DataUght. 
It  will  boot  up  on  a  standard  PC,  oper¬ 
ate  from  within  ROM,  and  run  MS-DOS 


executable  (.EXE  and  .COM)  files. 

ROM-DOS  is  compatible  with  MS- 
DOS  and  runs  programs  such  as  Micro¬ 
soft  Word,  Turbo  C,  and  Lotus  123. 
Developers  can  write  code  using  Ba¬ 
sic,  C,  Pascal,  and  so  on;  compile  it 
with  their  compiler  for  MS-DOS  opera¬ 
tion  on  a  PC;  and  then  load  it  into  ROM 
along  with  ROM-DOS  to  run  in  the  target 
system  with  no  further  modification.  ROM- 
DOS  takes  about  29K  of  ROM  and  em¬ 
ploys  5K  of  RAM  when  running. 

In  addition,  Datalight  has  developed 
a  mini-BIOS  for  use  in  embedded  sys¬ 
tems.  Developers  may  choose  to  use  a 
full  standard  BIOS  or  the  Datalight  mini- 
BIOS  in  the  final  system.  The  mini- 
BIOS  provides  support  for  a  remote 
console  (via  a  serial  port),  hardware 
timer,  and  serial  ports.  The  mini-BIOS 
requires  less  than  3K  bytes  of  ROM  and 
uses  the  standard  for  BIOS  RAM  area. 

ROM-DOS  supports  memory  man¬ 
agement,  a  standard  file  system,  time 
functions,  and  installable  device  driv¬ 
ers.  The  32K  ROM  of  an  Intel  Wildcard 
can  hold  ROM-DOS  and  mini-BIOS. 

ROM-DOS  sells  for  $6  per  licensed 
copy  in  quantity  of  5,000.  A  ROM-DOS 
developer’s  kit  sells  for  $495,  and  a 
license  to  the  source  code  costs  $5,000. 
Reader  Service  No.  28. 

Datalight 

17505  68th  Ave.  NE,  Ste.  304 
Bothell,  WA  98011 
206-486-8086 

Compuquest  has  announced  its  fam¬ 
ily  of  data  communication  products  that 
corrrect  data  errors  without  retransmis¬ 
sion.  Included  is  a  4800-baud  cellular 
data  modem  that,  according  to  Com¬ 
puquest,  allows  users  to  transmit  error- 
free  data  via  cellular  telephone  at  high 
speeds.  The  modem  sells  for  $1,695. 

Compuquest  has  also  released  a  5- 
lb.  laptop  terminal  with  a  built-in  1200 
baud  cellular  data  modem  and  VT-220 
emulation.  The  terminal  is  priced  at 
$  1 ,798.  Other  members  of  the  new  prod¬ 
uct  line  include  a  V.33  leased  line  mo¬ 
dem  with  error-free  transmission  rates 
up  to  28000  baud  (selling  for  $3,490), 
and  a  9600  baud  V.32  modem  (selling 
for  $1,595). 

All  of  the  products  use  a  proprietary 
protocol  called  Compuquest  Commu¬ 
nications  Protocol  (CCP)  for  data  com¬ 
pression,  forward  error  correction,  and 
dynamic  data  management.  Reader  Serv¬ 
ice  No.  29. 

Compuquest,  Inc. 

801  Morse  Ave. 

Schaumburg,  IL  60193 
312-529-2552 
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(continued  from  page  75) 
you  might  expand  the  program  in  Ex¬ 
ample  1  to  that  in  Example  2. 

The  methods  of  attack  described  so 
far  are  often  termed  “Trojan  horse”  at¬ 
tacks.  There  are  general  search  tech¬ 
niques  that  might  be  used  to  search  for 
them.  The  code  example  in  Example  3 
seeks  to  eliminate  the  risk  of  a  Trojan 
horse  attack.  You  might  also  include  in 
your  examination  of  users’  home  direc¬ 
tories  a  search  for  possible  existing  Tro¬ 
jan  horses.  To  do  so,  you  need  to  know 
what  a  Trojan  horse  might  look  like. 

First,  you  know  that  to  be  useful,  a 
Trojan  horse  program  must  be  exe¬ 
cuted.  Because  users’  commands  are 
usually  limited  to  the  set  of  commands 
provided  by  the  system,  a  successful 
Trojan  horse  might  seek  to  masquer¬ 
ade  as  a  system  command.  The  sim¬ 
plest  method  of  achieving  this  is  to 
create  an  executable  file  with  the  same 
name  as  a  commonly  used  system  com¬ 
mand.  This  type  of  Trojan  horse  can 
be  placed  in  any  writable  directory  any¬ 
where  in  the  file  system. 

An  effective  method  of  searching  for 
existing  Trojan  horses  consists  of  two 
steps.  First,  define  a  list  of  “likely”  Tro¬ 
jan  horse  names  derived  from  com¬ 
monly  used  system  commands.  Then, 
search  the  entire  file  system  for  files 
having  these  names.  The  program  might 
look  like  that  in  Example  3. 

The  actual  implementation  might  be 
improved  by  including  a  mechanism 
for  defining  a  list  of  files  “authorized” 
to  have  a  given  name  and  ignoring 
those  files  in  the  search.  By  searching 
the  entire  file  system,  user  and  system 
areas  are  checked  for  the  existence  of 
potential  security  risks. 

Network  Security 

In  the  previous  section,  I  described 
some  tools  that  help  to  protect  users 
from  themselves  and  from  other  users. 
In  this  section,  I’ll  focus  more  on  out¬ 


side  threats  to  network  security. 

A  network  connection  should  be 
treated  as  a  doorway  to  the  world.  The 
security  considerations  center  on  two 
basic  issues:  1.  What  should  be  permit¬ 
ted  to  enter  the  system  via  the  network? 
2.  What  should  be  permitted  to  leave 
the  system  via  the  network? 

One  way  to  impose  security  on  a 
networked  system  is  by  controlling  the 
capabilities  of  the  network  software. 
This  feature,  if  available,  is  usually  pro¬ 
vided  through  some  sort  of  configura¬ 
tion  mechanism.  By  imposing  control 
over  the  network  configuration  you  can 
impose  some  level  of  control  over  net¬ 
work  security. 

A  brief  description  of  some  common 
network  threats  will  help  determine  what 
type  of  network  configuration  is  appro¬ 
priate.  Information  entering  your  sys¬ 
tem  may  pose  a  variety  of  threats.  If  a 
remote  user  or  site  can  arrange  for  an 
executable  file  to  be  placed  on  your 
system,  then  the  threat  of  a  Trojan  horse 
or  a  virus  attack  exists.  If  a  remote  user 
or  site  can  directly  execute  commands, 
then  the  threat  of  a  direct  attack  on  users 
or  resources  exists.  Similarly,  information 
leaving  your  system  may  divulge  infor¬ 
mation  useful  to  an  intruder  for  plan¬ 
ning  other  types  of  attacks.  In  general, 
your  network  configuration  should  be  as 
limited  as  possible  while  still  allowing 
a  reasonable  level  of  communication. 

Having  defined  an  acceptable  net¬ 
work  configuration,  the  next  step  is  to 
automate  the  process  of  verifying  the 
configuration.  By  way  of  example  I’ll 
describe  the  capabilities  of  a  common 
network  utility  and  show  how  such  a 
verification  program  might  be  written. 
The  example  I’ll  use  is  derived  from 
Unix  where  the  most  common  network 
connection  is  called  uucpi Unix  to  Unix 
copy). 

The  uucp  facility  is  controlled  by  a 
series  of  configuration  files  that  deter¬ 
mine  the  capabilities  of  each  remote 


FOR  (every  user's  home  directory)  DO 
checkdir (directory) 

DONE 

PROCEDURE  checkdir  (directory) 

IF  (directory  is  writable)  THEN  flag  this  directory 
FOR  (every  file  in  the  directory)  DO 

IF  ((file  is  executable)  AND  (file  is  writable))  THEN  flag  this  file 
IF  (file  is  writable)  THEN  maybe  flag  this  file 
ELSE  IF  (file  is  directory)  THEN  checkdir (file) 

DONE 

ENDPROCEDURE 

Example  2:  To  handle  the  more  general  issue  of  write  protection  you  might 
expand  the  code  in  Example  1  to  this. 


FOR  (every  file  in  the  file  system)  DO 
IF  (filename  is  in  likely-list)  THEN  flag  this  file 
DONE 


Example  3-'  This  code  presents  one  way  to  eliminate  the  risk  of  Trojan  horse 
attack. 
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system.  The  available  capabilities  in¬ 
clude  remote  file  copy  in,  local  file 
copy  out,  and  remote  command  exe¬ 
cution.  The  configuration  files  deter¬ 
mine  what  parts  of  the  local  file  system 
can  be  accessed  by  a  remote  machine 
and  what  commands  are  available  for 
remote  execution.  Thus,  for  the  uucp 
facility  the  configuration  files  determine 
the  network  capabilities.  The  verifica¬ 
tion  tool  will  examine  the  configura¬ 
tion  files  relative  to  the  predefined  level 
of  network  security  desired. 

Let’s  assume  that  some  remote  clients 
are  not  completely  trusted  and  a  reason¬ 
ably  controlled  network  environment 
is  called  for.  In  this  case,  you  might 
elect  to  limit  the  access  of  all  remote 
machines  to  one  single  directory.  Thus, 
any  information  entering  or  leaving  your 
system  must  be  copied  into  or  out  of  a 
single  location.  Similarly,  you  might  elect 
to  limit  the  remotely  executable  com¬ 
mands  to  those  that  are  designed  spe¬ 
cifically  for  remote  execution.  In  real¬ 
ity,  this  configuration  is  quite  reason¬ 
able  — users  can  send  and  receive  files, 
and  commands  designed  for  remote 
execution  are  made  accessible. 

The  next  step  is  to  create  a  software 
tool  that  checks  the  network  configura¬ 
tion  files,  and  ensures  that  the  network 
policy  decisions  are  reflected  in  the 
actual  configuration.  Using  the  policy 
described  earlier  you  can  construct  an 
example  of  such  a  program.  Let’s  fur¬ 
ther  assume  that  a  directory  named 
public  has  been  reserved  for  the  re¬ 
mote  machine  access  point,  and  that 
the  commands  available  for  remote  exe¬ 
cution  are  called  rmail  and  Ipr.  A  sim¬ 
ple  checking  program  would  look  like 
that  in  Example  4. 

For  those  of  you  familiar  with  uucp , 
this  example  may  seem  trivial.  And  in 
truth,  a  robust  uucp  checking  program 
would  perform  many  more  checks  than 
those  shown  here.  Nevertheless,  this 
program  is  effective  and  the  explana¬ 
tory  text  for  uucp  is  neatly  avoided. 
The  reason  the  approach  in  Example 
4  is  effective  is  because  it  automates 
the  task  of  maintaining  security.  Any 
time  you  can  incorporate  your  security 
policy  into  an  administrative  tool,  you 
have  succeeded  in  achieving  several 
goals.  First  of  all,  you  acquire  a  means 
by  which  your  administrator  can  audit 
the  current  state  of  the  system  against 
the  criteria  suggested  by  your  security 
policy.  Given  such  a  tool,  the  adminis¬ 
trative  overhead  of  maintaining  secu¬ 
rity  is  greatly  reduced.  Second,  your 
security  policy  is  no  longer  just  a  vir¬ 
tual  set  of  guidelines.  By  incorporating 
the  policy  into  your  software  tools,  the 
policy  itself  has  a  physical  representa¬ 
tion.  Given  this,  it  becomes  much  more 


likely  that  the  policy  will  be  adhered 
to.  By  externalizing  the  security  policy, 
the  effort  required  to  train  a  new  ad¬ 
ministrator  is  also  reduced. 

Conclusion 

Whether  your  concern  is  based  on  user 
vulnerability  or  attacks  from  remotely 
connected  network  sites  the  solution 
is  the  same.  A  good  security  policy  is 


made  much  more  effective,  simpler, 
and  easier  to  enforce  when  the  tasks 
are  automated.  After  all,  policy  without 
practice  is  no  policy  at  all. 

DDJ 

Vote  for  your  favorite  feature/article. 

Circle  Reader  Service  No.  2. 


FOR  (each  remote  host  that  is  defined)  DO 
IF  (directories  other  than  "public"  accessible)  THEN  flag  this  host 
FOR  (each  command  name  in  command  list)  DO 

IF  ((command  !=''rmail")  AND  (command ! ="lpr” ) )  THEN  flag  this  command 
DONE 
DONE 


Example  4:  One  approach  to  network  checking. 
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It’s  Not  Me,  Either 

Coming  out  of  a  screaming  six-G  dive,  Pilot  Spiff  unleashes  the  terrible  firepower  of  his 
P51  Mustang’s  six  .50-caliber  machine  guns.  Blam!  Blooey!  Two  critical  struts  weakened, 
the  Eiffel  Tower  totters  for  a  horrifying  second  and  then  crashes  to  the  Paris  streets  in 
a  heap  of  twisted  steel. 

Yep.  Donald  Hill’s  P51  Mustang  Flight  Simulator  is  a  fine  cathartic.  Now  on  to  the  mailbag. 
First,  a  big  thank  you  to  all  of  you  who  have  written  in  to  say  that  you  agreed  with  me 
about  writers’  responsibility  for  the  quality  and  accuracy  of  their  work.  I’m  especially  grateful 
for  all  those  examples  of  typos,  misspellings,  factual  errors,  and  general  evidence  of  senility 
that  you  found  in  my  recent  columns  and  were  kind  enough  to  send  along  for  my  edification, 
often  with  witty  annotations  of  your  own.  You  can  stop  now. 

Here  are  the  patches:  In  the  February  “Flames,”  replace  “Kerouak"  with  “Kerouac,” 
“National”  with  “Notional”  (the  National  Science  Foundation  does  not  in  fact  belong  to 
author  Nick  Herbert),  “Sometimes”  with  “Some  time,”  and  move  the  comma  after  “ecliptic” 
outside  the  parentheses.  In  the  March  “Programming  Paradigms,”  replace  “PC Magazin’’ 
with  “Design  Elektronik'  globally.  Ju  rgen  Fey  was  miffed  that  I  couldn’t  remember  what 
magazine  he  worked  for. 

“Typos  Hapen”  is  a  bumpersticker  I  haven’t  seen  but  would  gladly  buy.  In  fact,  I’d  buy 
two  and  give  one  to  an  editor  friend  of  mine  who  begged  me  not  to  mention  his  name  in 
my  column  this  month.  No,  it’s  not  Jurgen.  But  it  wasn’t  typos  that  I  had  in  mind  when  I 
announced  my  intention  a  few  months  ago  to  point  out  egregious  uses  of  words  and  figures 
in  the  computer  press,  but  bits  like  these  from  a  recent  Microsoft  Word  4.0  ad: 

“  . .  .  startling,  cutting-edge  technology.”  (And  it  holds  the  road  like  a  dream.) 

“  . . .  features  as  dynamic  and  diverse  as  its  users.”  (OK,  maybe  Microsoft  researched 
this  one.) 

“And,  software  fans.  ...”  (Oh,  you  crazy  word  processor  groupies.) 

“  . . .  practically  the  only  thing  it  can’t  do  for  you  is  think.  Yet.”  (Or  write.  Evidently.) 
Microsoft  wasn’t  so  funny  back  when  Tyler  Sperry  was  writing  copy  for  them.  Poor  Tyler. 
Last  I  heard  he  was  sleeping  in  the  streets  or  editing  Embedded  Systems  Programming, 
something  like  that. 

Speaking  of  embedded  things,  which  I  do  with  some  trepidation,  considering  the  keen 
linguistic  sensitivity  of  some  readers  of  this  column,  reminds  me  of  the  subject  still 
languishing  at  the  bottom  of  the  mailbag:  fighting  software  piracy  by  embedding  machine 
serial  numbers  in  ROM.  Several  readers  wrote  in  about  the  subject,  all  cogently  and  politely 
trashing  the  scheme. 

Peter  Aitkin  of  Durham,  North  Carolina,  stated  the  basic  objection:  “Each  software  package 
that  I  purchase  is  installed  on  all  of  my  computers;  the  manuals  are  schlepped  back  and  forth 
as  needed.  No  one  but  me  ever  uses  any  of  these  machines.  Surely  such  an  arrangement  is 
within  the  spirit,  if  not  the  letter,  of  software  licensing  agreements.”  After  all,  it  is  the  person, 
not  the  computer,  who  pays  for  the  software.  Shouldn’t  it  be  the  person,  rather  than  the 
computer,  to  whom  it  is  licensed? 

Aitkin  also  pointed  out  that  tying  the  software  to  a  serial  number  in  ROM  makes  it 
impossible  for  the  user  to  upgrade  the  hardware  while  keeping  the  old  software. 

Diehl  Martin  of  Huntsville,  Alabama,  sent  a  thoughtful  dissertation  on  the  two  issues  of 
copyright  protection  and  copy  protection.  Among  other  points,  he  opines  that  software 
developers  are  no  better  than  anyone  else  when  it  comes  to  copying  software.  “Since 
imitation  is  the  sincerest  form  of  flattery,"  Diehl  says,  “what  wonderful  things  we  must  be 
saying  about  each  others’  work!” 

Tim  Deardeuff  of  Provo,  Utah,  nicely  demonstrated  that  the  ROM  scheme  affords  no 
greater  protection  than  any  software  copy  protection  scheme,  since  all  the  user  has  to  do  to 
defeat  it  is  to  copy  the  disk  before  installing  the  software  on  the  target  machine.  The 
developer  could  always  make  the  disk  difficult  to  copy,  but  this  reduces  to  the  old  discredited 
scheme  of  software  copy  protection,  and  the  serial  number  in  ROM  buys  the  developer 
nothing  extra  while  inconveniencing  the  user. 

Did  the  critical  clause  of  the  non-competition  contract  between  Steve  Jobs  and  Apple 
Computer  expire?  The  machine  that  would  be  sold  Only  to  Higher  Education  can  now  be 
ordered  at  Businesslands  everywhere.  What  a  surprise. 

And  just  as  the  courts  informed  Microsoft  that  its  license  from  Apple  doesn’t  go  beyond 
Windows  1.0,  the  company  that  managed  the  Beatles  informed  Apple  that  its  agreement  on 
the  use  of  the  name  Apple  explicitly  excludes  use  in  any  music-related  activity.  I  dunno; 
maybe  litigation  is  funnier  than  publishing.  .  <  a  _ 

Michael  Swaine 
editor-at-large 
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Credit  Where 
Credit's  Due 


L 


In  May  1988,  we  published  what  turned  out  to  be  a  popular  article  on  TIFF,  the  tagged  image 
file  format  that’s  become  an  industry  standard  for  storing  bit-mapped  images.  In  classic  DDJ 
spirit,  Tony  Meadows  and  his  co-authors  said  that  DDJ  readers  could  receive  free  copies  of 
the  TIFF  Library  Package  from  one  of  two  sources:  A  PC  version  from  Dest  Corporation  and  a 
Mac  version  from  Tony’s  company,  Bear  River  Associates.  Thanks  to  Los  Angeles  reader  Don 
Black  (who  wanted  me  to  plug  “Eager,”  his  new  3-D  rendering  and  animation  software  —  but 
I  told  him  I  couldn’t  do  that),  we  found  out  that  this  policy  has  changed.  But  first,  a  little 
background.  .  .  . 

About  two  years  or  so  ago,  I  was  at  the  news  conference  where  Microsoft,  Aldus,  and 
Hewlett-Packard  introduced  the  TIFF  standard  and,  like  most  in  attendance,  I  was  impressed 
with  the  proposal  and  the  possibilities  that  it  suggested.  In  retrospect,  one  company  that  wasn’t 
mentioned  or,  at  least  to  my  mind  wasn’t  given  justifiable  credit,  was  Dest,  a  small  Silicon  Valley 
company  known  primarily  for  its  scanners  and  imaging  software.  As  it  turns  out,  it  was  the  R&D 
group  at  Dest  who  actually  did  a  lot  of  the  groundwork  for  the  TIFF  standard  and  it  was  the 
same  group  who  provided  the  PC-version  of  the  TIFF  Library  free  to  DDJ  readers. 

After  the  article  was  published,  Dest  was  deluged  with  requests  for  the  software.  Some 
months,  in  fact,  Dest  spent  more  than  $20,000  distributing  the  material  until  the  company  was 
eventually  forced  into  changing  its  policy  and  began  charging  $25  per  package.  Alas,  Dest  has 
since  run  upon  some  rocky  economic  shoals,  most  recently  going  into  reorganization  so  it  comes 
as  no  surprise  that  they’ve  discontinued  the  distribution  program  altogether.  I  don’t  know  how 
or  if  the  company  will  be  successful  in  its  reorganization,  but  I  do  think  DDJ ,  its  readers,  and 
the  industry-at-large  owe  Dest  a  special  thanks  for  getting  some  really  useful  software  into  the 
hands  of  programmers  —  and  free  at  that. 

If  you  need  the  TIFF  Library,  all  isn’t  lost.  You  can  now  get  both  the  PC  and  Mac  versions 
from  Image  Software  Associates.  For  $25  ($35  international)  you  get  documentation  (the  TIFF 
standard  and  a  programmer’s  reference  guide),  source  code,  object  files,  and  demonstration 
programs.  Make  checks  or  money  orders  payable  to  Image  Software  Associates,  Research  & 
Development,  P.O.  Box  1634,  Danville,  CA  94526.  Don’t  forget  to  specify  PC  or  Mac. 


If  you’re  a  telecommunications  kind  of  person,  you’ll  be  glad  to  know  that  we’ll  be  making 
DDJ  source  code  listings  available  via  an  additional  source.  Thanks  to  contributing  editor  David 
Betz  and  his  partner  in  programming  Bill  Garrison,  DDJ  listings  will  be  available  free  of 
charge  on  an  on-line  system  out  of  New  Hampshire.  For  the  time  being,  you  will  have  to  take 
care  of  the  long  distance  charges  yourself,  but  that  and  other  changes  may  be  in  the  offing. 

The  system  supports  300/1200/2400  baud,  uses  8-data  bits,  no  parity,  and  1-stop  bit.  To  access 
the  system,  dial  603-882-1599.  When  the  system  answers,  the  Unix  login  prompt  will  appear  and 
you  should  type  listings  (be  sure  to  use  lowercase)  and  press  Return.  You’ll  then  be  led  to  the 
listings.  This  month’s  listings  will  be  on-line  as  well  as  past  months,  at  least  through  the 
beginning  of  this  year. 


Finally,  new  applications  of  computer  software  continue  to  make  the  news  here  in  Northern 
California.  Most  recently,  an  “escort  service”  ring  was  rung  up  by  the  local  gendarmes.  It  seems 
that  some  iadies-of-the-night  were  allowing  their  clients  to  pay  up  using  credit  cards  and,  instead 
of  listing  the  charge  as  “services  rendered,”  they  were  filling  out  the  credit  slips  as  charges  for 
computer  software.  Hmmm  .  .  .  that  certainly  adds  a  new  dimension  to  the  concept  of  user 
friendly.  The  next  step  will  be  probably  sex-object-oriented  programming  (that’s  right,  SOOPs). 
Or  maybe  real  genetic  programming.  All  right,  if  you  can  do  any  better  let  me  know  but  keep 
it  clean,  okay? 


Jonathan  Erickson 
editor-in-chief 
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Crotchet  Contemplation 

Dear  DDJ, 

These  notes  were  prompted  by 
“Crotchet  No.  5:  The  Great  Debate”  in 
the  October  1988  DDJ  (“C  Program¬ 
ming”  by  Al  Stevens)  and  are  offered 
in  the  spirit  of  thoughtful  contempla¬ 
tion  as  to  what  the  hell  we’re  supposed 
to  be  doing  and  how  the  hell  we  should 
best  achieve  it.  Others  may  have  differ¬ 
ent  views! 

Systems  analysis  is  the  distillation  of 
a  user  requirement  into  a  programma¬ 
ble  specification.  In  my  experience,  the 
whole  process  seems  to  reduce  to  the 
following  two  fundamental  precepts: 
1 .  Derive  and  understand  the  concepts 
and  rules  by  which  data  objects  may 
attributed,  operated  on,  and  related  to 
other  objects  to  produce  a  meaningful 
end  result.  2.  Maintain  and  know  how 
to  use  a  set  of  tools,  libraries,  and  tech¬ 
niques  to  enable  the  crafting  of  the 
masterpiece. 

I  think  most  people  would  agree 
that  the  use  of  these  precepts  is  re¬ 
garded  as  a  skill.  These  precepts,  how¬ 
ever,  are  more  general  than  they  seem. 
With  suitable  generalizations  they  may 
be  applied  to  any  engineering  discipline 
and  indeed  to  any  traditional  art  form. 

My  dictionary  describes  “art”  as  “skill 
applied  to  imitation  and  design.”  Thus, 
a  program  does  not  need  aesthetic  qual¬ 
ity  to  be  art.  Assuming  the  above  pre¬ 
cepts  are  valid  and  that  a  program  is 
the  medium  of  an  analysis  much  as  a 
painting  is  the  medium  of  an  expres¬ 
sion,  then  programming  is  an  art. 

The  definition  given  for  “aesthetic” 
is  “appreciated  as  having  beauty.”  I 
regard  (nearly)  all  my  programs  as  things 
of  beauty!  More  importantly,  I  gener¬ 
ally  regard  other  programs  as  things  of 
beauty  if  well-crafted.  Thus,  programs 
have  aesthetic  appeal;  what  comprises 
that  appeal  in  a  program  could  be  (and 
has  been)  argued  over  at  length. 

Furthermore,  the  definition  given  for 
“science”  is  “the  pursuit  of  systematic 
and  formulated  knowledge.”  Program¬ 
ming,  being  the  application  of  defined 


knowledge,  is  thus  not  a  science.  The 
development  of  the  rules  of  program¬ 
ming,  however,  may  be  regarded  as 
such  by  this  definition.  Hence  the  apt 
term  “computer  science”  describing  the 
formulation  and  pursuit  of  program¬ 
ming  knowledge. 

Thus,  I  would  argue  that  computer 
science  is  a  true  science  that  involves 
the  formulation  and  pursuit  of  program¬ 
ming  knowledge  using  the  art  (appli¬ 
cation)  of  programming  (software  en¬ 
gineering)  to  help  develop  and  impart 
that  knowledge. 

Tomorrow  I  will,  as  Douglas  Adams 
said  (roughly),  “go  on  to  prove  that 
black  is  white  and  get  run  over  at  the 
next  zebra  crossing!”  This  argument  can 
be  generally  applied  to  other  disciplines, 
as  in  chemistry  as  a  science  and  chemi¬ 
cal  engineering  as  its  application.  And 
yes,  programming  is  a  discipline  even 
though  its  practitioners  may  not  be! 

Now  we  come  to  the  process  by 
which  the  analysis  may  be  turned  into 
a  useful  program.  To  this  end,  pro¬ 
grammers  will  have  at  their  disposal 
an  array  of  tools  and  libraries  that  im¬ 
plement  general  concepts  to  allow  con¬ 
struction  of  specific  code.  In  C  this  will 
typically  be  achieved  by  making  a  set 
of  structures  (objects)  with  sets  of  at¬ 
tributes  (fields)  and  writing/using  a  set 
of  routines  to  operate  on  and  relate  the 
objects. 

Object-oriented  programming  tools 
are  designed  to  partially  automate  and 
so  make  more  reliable  the  process  by 
which  the  analysis  is  turned  into  oper¬ 
ating  code.  C++  is  one  such  tool.  It 
attempts  to  allow  the  programmer  to 
think  and  work  in  the  context  of  ob¬ 
jects,  attributes,  and  operators  rather 


than  having  to  translate  them  mentally 
into  structures,  fields,  and  routines. 

Additionally,  maintenance  is  simpli¬ 
fied  because  object-oriented  program¬ 
ming  imposes  greater  control  over  the 
scope  of  the  code  and  the  type  of  the 
objects.  Interestingly,  this  is  exactly  what 
Pascal  attempts  to  do;  however,  its  scope 
and  type  rules  are  bound  into  the  lan¬ 
guage  thus,  severely  restricting  its  use¬ 
fulness.  A  language,  such  as  C++,  al¬ 
lows  programmers  to  define  a  set  of 
type  and  scope  rules  according  to  their 
applications.  The  compiler  then  enforces 
these  self-imposed  rules.  This  is  ex¬ 
actly  what  we  want! 

For  this,  programmers  have  to  think 
harder  and  more  clearly.  The  extra  ef¬ 
fort  pays  off  in  reduced  debug  and 
maintenance  time.  The  concept  of  in¬ 
creasing  abstraction  is  vital  to  code  gen¬ 
eration  and  maintenance  cost-effective¬ 
ness.  In  days  gone  by  the  simple  goto 
was  used  to  implement  all  sorts  of  won¬ 
derful  conceptual  constructs.  Structured 
programming  languages  evolved  to  for¬ 
malize  and  automate  some  of  the  more 
common  of  these  constructs  to  provide 
concepts  such  as  repeat,  while,  and  so 
on,  using  machine  code  gotos  for  their 
implementation.  Similar  arguments  ap¬ 
ply  to  every  keyword  that  any  language 
employs.  Ratfor  was  a  good  early  ex¬ 
ample:  Pascal  and  C  have  persisted 
longer  and  further. 

In  conclusion,  this  is  a  limited  dis¬ 
cussion  of  programming  issues,  but  I 
think  they  are  the  fundamental  points 
from  which  further  arguments  develop. 
C++  is  more  subtle  than  might  appear 
from  this  brief  summary.  I  have  just 
bought  Zortech’s  compiler  (three  cheers 
for  a  well-thought-out  system  at  a  rea- 


Errata 

Please  note  the  following  required  changes  to  the  TSRUnit  in  “Creating  TSRs 
Using  Turbo  Pascal”  by  Ken  L.  Pottebaum  (May  and  June,  1989). 

Line  87  Our26  =  Our25+27; 

88  Our09  =  Our26+27; 

The  INLINE  code  changes  are  to  byte  number  13  in  OurIntr25  and  OurIntr26, 
which  are  interrupt  intercept  routines  contained  in  PROCEDURE  Asm.  Change 
OurIntr25  to: 

{  13}  $68/>Our25+19/  {  PUSH  Our25+19  ; Clean  up  stack  with-  } 

$C2/$02/$00/  {RET  2  ;  out  changing  flags .  } 

Make  a  similar  change  in  OurIntr26  so  that  it  becomes: 

{  13}  $68/>Our26+19/  {  PUSH  Our26+19  ; Clean  up  stack  with-  } 

$C2/$02/$00/  {RET  2  ;  out  changing  flags .  } 

Also  in  June,  Jim  Mischel  reported  one  change  to  his  article  “Writing 
AWK-like  Extensions  to  C.”  In  Listing  Three,  page  94,  the  line  that  reads: 

if  (makepat  (f s_DEFAULT,  pat)  =  =  NULL) 

should  read: 

if  (makepat  (fs,  pat)  =  =NULL) 
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(continued  from  page  10) 
sonable  price)  and  have  yet  to  really 
make  it  sweat.  My  arguments  are  made 
from  the  “wants”  list,  rather  than  the 
“fully  implemented”  list. 

Guy  Mcllroy 
Norseman  Systems 
Australia 


Down  and  Dirty,  That’s  Us 

Dear  DDJ , 

I’ve  wanted  to  write  this  letter  for  a 
long  time,  but  haven’t  had  time  to  put 
printhead  to  paper.  It  seems  that  Dr. 
Dobb’s  is  getting  further  and  further 
away  from  the  kind  of  programming 
that  really  matters,  and  more  and  more 
into  obscure  research  topics  in  com¬ 
puter  science. 

Where  I  work,  milliseconds  are  im¬ 
portant.  What  matters  is  how  many  mes¬ 
sages  you  can  process  in  ten  millisec¬ 
onds.  And  it’s  never  enough,  so  you 
go  back  and  sweat  over  the  code.  Be¬ 
lieve  me,  all  those  object-oriented  para¬ 
digms  aren’t  worth  a  plugged  nickel  in 
the  real  world.  Ail  that  structured-pro¬ 
gramming  data  abstraction  is  the  wrong 
way  to  go,  too.  To  get  speed,  you  don’t 
distance  yourself  from  your  data  — 
you’ve  got  to  get  down  and  dirty  with 
your  data.  The  guys  who  are  fighting 
the  war  are  not  the  generals  in  the 
hotel  rooms  with  their  sparkling  white 
maps  and  military  icons,  sipping  tea 
from  Wedgewood  china.  No,  they’re 
the  guys  in  the  trenches,  with  their 
buffers  and  flags  and  registers. 

Now  what  audience  are  you  going 
to  write  for?  Do  you  want  to  be  the 
Vogue  of  programming?  The  National 
Enquired  Cosmopolitan ?  Gee,  you  used 
to  be  more  like  Popular  Mechanics. 
Just  remember,  there  are  a  lot  more 
privates  than  there  are  generals.  And 
Popular  Mechanics  had  Mimi,  too. 

Rick  Rodman 

Manassas,  Virginia 

DDJ:  Gosh  Rick,  we’ve  always  been  more 
comfortable  in  the  trenches  than  the 
hotel  rooms  and  our  approach  contin¬ 
ues  to  be  more  Popular  Mechanics  than 
Scientific  American.  We  write  for  the 
serious  programmer —  as  evident  by 
the  hundreds  of  lines  of  source  code 
we  publish  in  each  issue —  and.  by 
sharingfaster,  better,  smaller  program¬ 
ming  techniques  that  solve  today’s  prob¬ 
lems  today,  DDJ  unll  always  be  a  hotrod- 
ding  magazine  for  programmers.  But 
we  also  have  a  responsibility  to  lead  the 
way  as  technology  evolves.  Five  years 
from  now,  programming  won ’t  be  the 
same  as  today,  just  as  today’s  environ¬ 
ments  are  different from  those five  years 
in  the  past. 


Shakespeare  Said 
Something  Similar 

Dear  DDJ, 

I  just  received  my  second  copy  of  DDJ 
and  my  comment  on  memory  limita¬ 
tion  is  that  about  the  time  the  technical 
limitations  were  overcome,  they  were 
replaced  by  the  corporate  money-grub¬ 
bers  who,  with  the  wholehearted  co¬ 
operation  of  Congress,  replaced  the  tech¬ 
nical  barriers  with  a  cost  barrier.  I  am 
convinced  that  about  half  of  the  im¬ 
pediments  to  progress  could  be  cured 
by  shooting  all  corporate  accountants. 
Shooting  all  corporate  lawyers  wouldn’t 
hinder  solving  the  other  half  of  the 
problems,  either. 

I  am  not  (at  least  as  yet)  a  profes¬ 
sional  programmer.  I’m  just  a  hard¬ 
core  electronics  nut  just  getting  into  his 
second  half-century  of  obsessive  inter¬ 
est  in  the  field.  I  was  a  professionally 
trained  repair  technician  back  in  the 
40s  and  50s,  but  I  found  other  work 
when  transistors  and  PC  boards  came 
on.  What  I  know  about  computers  and 
programming  comes  from  self-educa¬ 
tion  and  I’m  still  learning.  Diving  into 
Dr.  Dobb ’s  Journal  was  a  little  like  wan¬ 
dering  onto  a  nude  beach  by  accident  — 
a  little  shocking  like  any  transition  to  a 
new  environment,  but  stimulating  and 
educational. 

Billy  R.  Pogue 

Lake  Havasu  City,  Arizona 


Superlinearity  Without  Mirrors 

Dear  DDJ, 

I  would  like  to  describe  a  case  of  su¬ 
perlinearity  in  a  computer  with  parallel 
architecture,  that  will  not  look  like  magic 
to  Michael  Swaine. 

We  need  to  search  a  disordered  space 
of  10  million  strings  to  see  whether  it 
contains  a  particular  string.  With  a  sin¬ 
gle  processor,  we  examine  string  1, 
then  string  2,  and  so  on,  until  we  find 
a  match  or  until  all  strings  have  been 
examined.  But  with  ten  parallel  pro¬ 
cessors,  we  conduct  ten  searches  simul¬ 
taneously,  with  the  i  -  th  processor  be¬ 
ginning  at  string  (i  -  l)*le6.  This  paral¬ 
lel  search  will  be  complete  in  one  mil¬ 
lion  steps. 

Now  let  j  be  a  multiple  of  one  mil¬ 
lion,  and  let  x  be  any  number  less  than 
one  million.  If  the  given  string  is  to  be 
found  at  location  j  +  x,  then  the  se¬ 
quential  search  would  take  j  +  x  steps, 
and  linearity  would  require  (j+x)/10 
steps.  The  parallel  search  would  take 
x  steps.  Clearly,  superlinearity  would 
raise  its  mystic  head  whenever  (j  +  x)/ 
10  >  x  (about  half  of  the  time). 

Phil  Geffe 

(Consulting  Engineer) 

Cincinnati,  Ohio 


It’s  A  Dirty  Job  But . . . 

Dear  DDJ, 

My  new  issue  of  DDJ  arrived  today  and 
it’s  the  first  really  good  programming 
related  thing  to  happen  in  a  week.  As 
usual  I  read  the  “Programming  Para¬ 
digms”  column  first.  Well,  Michael 
Swaine,  you  have  become  the  apple 
of  my  eye.  I  have  been  screwing  around 
with  a  major  database  crash  at  the  site 
I  contract  with.  The  reason  it  has  been 
a  problem  for  a  whole  week  is  that 
most  of  the  folks  involved  are  victims 
of  the  current  educational  system’s 
method  of  teaching  programming.  They 
are,  unlike  myself,  company  employ¬ 
ees  who,  if  they  can’t  find  some  techno 
jargon  to  hide  their  screw-ups,  will  face 
spending  the  rest  of  their  careers  in  a 
somewhat  lesser  department  without 
rapid  advancement,  but  not  termina¬ 
tion  by  any  means.  All  of  them  are  folks 
who  cannot  get  beyond  “what  de  book 
say,"  and  down  to  the  real  problem: 
Trouble  with  paradigms. 

Memo  writing  is  a  much  more  coveted 
skill  than  that.  I  will  go  one  step  be¬ 
yond  praising  your  idea  regarding  the 
proper  method  of  educating  program¬ 
mers,  and  say  that  anyone  who  thinks 
that  the  real  job  of  programming  is  to 
“write  a  little  code”  should  be  shot. 
The  second  course  the  people  will  need 
(CS102  I  guess),  is  healthy  skepticism. 
(Odd  that  you  should  have  mentioned 
that  in  your  column  also  .  .  .  everything 
seems  so  clear  at  3  a.m.,  ya  know?) 

There  is  an  absolute  need  for  more 
programmers,  but  not  for  more  folks 
who  are  seeking  “good  clean  work  with 
no  heavy  lifting.”  What  is  needed  is  a 
crop  of  grunts  who  really  love  this  crap. 

Robert  L.  Hume 

CompuServe:  71220,1066 


You  Asked  For  It,  You  Got  It 

Dear  DDJ, 

I  own  an  Amiga  and  was  wondering  if 
you  could  cover  this  computer  in  your 
magazine.  I  still  enjoy  reading  your 
magazine  (even  though  it  seems  to  be 
for  IBM  only).  If  you  started  covering 
the  Amiga,  I  would  subscribe  to  your 
magazine  in  a  second! 

Matt  Childress 
Holland,  Michigan 

DDJ:  We  hope  the  article  by  Chuck 
McManis  fills  the  bill,  Matt. 


Just  Say  No! 

Dear  DDJ, 

I  enjoyed  and  appreciated  your  edito¬ 
rial  in  the  March  ’89  issue  of  Dr.  Dobb’s. 
I  agree,  professionals  should  be  held 
(continued  on  page  1 50) 
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Putting  mouse  and  graphics  primitives  to  work  in 
the  Presentation  Managers  protected-mode  environment 


William  H.  Murray  and  Chris  H.  Pappas 


With  consistent  device-independent  programming 
environments  such  as  Microsoft  Windows  and 
OS/2  Presentation  Manager,  applications  can 
be  executed  and  results  ported  to  any  installed 
hardware  driver  accordant  with  Microsoft's  speci¬ 
fications.  This  consistent  environment  frees  you  from  the 
necessity  of  also  developing  software  drivers  for  zillions  (or 
at  least  'hundreds)  of  printers,  plotters,  and  graphics  display 
devices.  As  a  matter  of  fact,  the  latest  version  of  Windows 
(Version  3-0)  brings  the  Windows'  environment  in  much 
closer  alignment  with  the  OS/2  Presentation  Manager  (PM), 
making'  the  task  of  porting  programs  between  real  and 
protected ' modes  easier. 

The  price  you  pay  for  entering  into  this  consistent  user 
interface  is  a  rather  steep  learning  curve.  In  this  article,  we 
will  concentrate  on  a  PM  program  that  plots  points  on  the 


William  H  Murray  and  Chris  H  Pappas  are  professors  of 
Computer  Studies  at  Broome  Community  College.  Together 
they  have  written  several  books,  including  Presentation  Man¬ 
ager  Graphics:  An  Introduction  ( Oshorne/McGmw-Hill ,  1989) 
from  which  portions  of  this  article  were  adapted  Bill  and 
Chris  can  be  reached  at  Broome  Community  College,  Bing¬ 
hamton ,  NY  13902. 


screen  and  draw's  a  line  between  them  with  a  linear  least- 
squares-fit.  A  least-squares-fit  works  on  the  principle  that 
data  points,  collected  on  a  chart,  are  often  related  mathe¬ 
matically.  Because  of  this  relationship,  the  group  of  points 
takes  on  the  appearance  of  a  line  or  curve.  In  the  case  of  a 
linear  mathematical  relationship  between  point  values,  a 

single  line  (called  the  ltne-of-best . fit)  can  be  drawn  between 

all  points.  The  data  points  for  this  program  will  be  plotted 
by  moving  the  mouse  to  a  specific  region  on  the  screen  and 
clicking  the  left  button.  When  all  points  are  entered,  a  click 
of  the  right  mouse  button  will  end  data  entry  and  draw  a 
line-of-best-fit.  The  equation  for  that  line  w  ill  be  plotted  at 
the  bottom  of  the  screen  in  slope-intercept  form.  Among 
other  things,  this  example  illustrates  how  the  mouse  and 
other  graphics  primitives  can  lx-  utilized  under  the  protected- 
mode  environment. 

If  you  are  unfamiliar  with  Windows  or  the  PM  philoso¬ 
phy,  we  strongly  recommend  you  read  Herb  Schildts  article, 
A  Presentation  Manager  Application  Template,”  which  ap¬ 
peared  in  the  March  1989  issue  of  DDJ.  Herb  describes  one 
of  three  Presentation  Manager  “foundations’*  —  tbe’Cached- 
Presentation  Space.  (The  other  two  are  the  Micro-Presenta¬ 
tion  Space  and  the  Normal-Presentation  Space.)  Each  type 
offers  an  increasingly  greater  array  of  available  functions 


w 


and  unfortunately  larger  code  sizes.  For  this  reason,  it  will 

easiest  for  you  ro  Seam  simple  PM  programming  with  the 
Ctched-I’rcsenution  Space,  which  is  what  we  implemented 
tn  this  article.  From  there  you  can  move  to  the  other  two 
presentatu/n  spares  as  projects  demand. 

Tt:»  enpr  and  execute  the  code  you  will  need  the  PM 
(Versify!  1  or  later)  operating  on  a  80386/80286  computer. 
Additjrfmally,  you’ll  need  the  Microsoft  C  Compiler  (Version 
5. later),  the  Microsoft  OS/2  Software  Developer’s  Kit, 
at! ff  a  Microsoft  mouse.  The  program  for  this  article  was 
praeveloped  on  an  IBM  Model  80  with  VGA  display  and  6 
Mbytes  of  RAM 

The  Sum  of  the  Ports  Equals  the  Whole 

The  program  itself  is  called  MFIT  (for  mouse  fit).  MFITdoes 
Sot  consist  of  a  single  program  file,  but  a  group  of  files  that 
are  eventually  linked  together  As  a  matter  of  fact,  there  are  ten 
files  that  will  lx*  found  on  your  disk  after  a  successful  compila¬ 
tion:  MFIT  MFIT. DBF,  MFIT.EXE.  MFIT.H,  MFIT.ICO, 

•  MKH  OBJ.  MFIT. P  I  K,  MFIT.KC,  MFIT. RES,  and  MFIT.C. 

MFIT,  shown  in  Listing  One,  page  78  is  used  by  the  MAKE 
utility  and  is  responsible  for  the  compilation  of  the  C  code 
■  U  the  O'  compiler,  the  assembling  of  the  resource  code  by 
the  Resource  Compiler,  and  the  eventual  linking  of  this  code 
with  the  icon  and  pointer  information. 

MFH.DEF  (Listing  Two,  page  78)  is  the  definition  file  for 
the  Presentation  Manager,  Definition  files  are  used  by  both 
Windows  anti  the  Presentation  Manager.  The  DEF  file  is 
responsible  for  establishing  the  heap  and  stack  sizes,  identi¬ 
fy  trig  the  operating  mode  (real  or  protected),  and  naming 
exports.  For  our  example,  exports  are  the  individual  proce¬ 
dures  used  in  the  €  program 

MFIT  H  is  a  header  file  for  unique  identification  numbers 
that  will  be  used  by  the  resource  file  and  the  C  program. 
Listing  Three,  which  is  on  page  78.  shows  a  list  of  ^define 
statements.  Usually  the  * define  instruction  is  followed  by 
an  ID  name,  followed  by  a.  unique  integer  constant.  The 
names  and  the  constants  are  your  choice,  but  careful  plan¬ 
ning  will  sometimes  eliminate  later  problems,  such  as  the 
insertion  of  additional  ID  numbers. 

MFIT. ICO  is  a  file  containing  the  shape  of  the  minimum 
icon.  The  minimum  icon  is  displayed  at  the  bottom  of  the 
screen  if  that  sizing  option  is  chosen  from  the  main  menu 
of  the  PM.  The  icon  is  drawn  with  the  use  of  the  Icon  F.ditor, 
which  is  part  of  the  Microsoft  Toolkit.  (Because  MFIT. ICO 
is  not  a  text  file  that  can  be  listed,  it  is  only  available  on  an 
optional  diskette  or  on  line. ) 

MF1T.PTR  is  a  file  containing  the  shape  of  the  screen 
pointer.  The  screen  pointer,  by  default,  is  an  arrow.  The 
user  has  the  option  of  using  the  Icon  Editor  to  draw  a  new 


pointer.  This  pointer  will  tie  present  in  the  application 
window  and  can  be  used  to  make  selections.  In  this  case,  a 
miniature  line  chart  is  used  as  the  pointer.  When  the  left 
button  Ls  pushed  (in  the  example  program)  a  small  cross 
symbol  will  lie  plotted  on  the  screen  at  the  spot  pointed  to 
by  the  pointer.  Again,  the  file  returned  by  the  Icon  Editor  is 
not  a  text  file. 

MFIT.RC  is  the  resource  file  needed  for  describing  the 
Menu,  About  Box,  and  Dialog  Box  and  is  shown  In  listing 
Four  (page  78),  The  resource  file  is  a  can  of  worms  in  itself. 
First,  the  About  and  Dialog  Boxes  are  created  with  the 
Dialog  Box  Editor  provided  with  the  Microsoft  Toolkit, 
Once  created,  the  information  is  saved  in  a  file  with  the 
extension  RES,  which  is  not  a  text  file.  A  text  file  version 
can  be  selected.  We  use  the  .DLG  extension  for  this  option. 
Our  experience  is  that  the  text  file  is  important  for  touching 
up  the  Dialog  Box  information.  The  catch  is  that  this  .DLG 
file  cannot  lie  read  by  the  Dialog  Box  Editor.  You  will  not 
have  that  problem  with  this  example,  because  the  place¬ 
ment  of  the  Dialog  Box  and  all  controls  have  already  been 
worked  out.  You  will  simply  have  to  type  the  file  MFIT.RC. 
The  MAKE  utility  will  compile  that  file  into  a  .RES  file  and 
link  ii  to  the  final  executable  program  The  Vxxit  Box  is 
shown  in  Figure  1  and  the  Dialog  Box  in  Figure  2. 

MFIT.C  is  the  C  program  proper.  Listing  Five  (page  78) 
contains  all  the  necessary  PM  overhead  required  to  establish 
and  communk  ate  w  ith  an  application  program  specific  ally 
two  procedures  or  functions  are  required  to  process  the 
Dialog  Box  messages  for  the  About  md  LineDiaProc  Dialog 
Boxes.  A  final  procedure,  GrupbicProc,  handies  all  other  mrs 
sages  for  the  mouse  position,  buttons,  and  graphics  routines. 

Power  in  the  Loop 

PM  and  Window's  use  the  concept  of  a  message 'loop  or 

queue  for  receiving  and  sending  information  throughout 
an  application  program.  (Establishing  this  queue  is  the  job 
of  the  main! )  function  as  described  in  Schildt  s  article.) 
Once  the  message  queue  is  established,  it  is  your  responsi¬ 
bility  to  tap  into  the  queue  with  your  requests.  Our  program 
will  use  several  procedures  or  functions  One  procedure 
will  help  establish  an  About  Box  In  PM  and  '*  mdows  the 
About  Box  is  used  to  transmit  information  regarding  the 
program.  This  usually  consists  of  one  or  more  of  the  follow¬ 
ing:  the  program  name,  a  short:  description  of  the  program, 
the  developer's  name(s),  and  the  copyright  date.  The  About 
Box  is  usually  selected  (as  an  item)  from  a  program  menu. 
Another  procedure  will  establish  a  Dialog  Box.  Dialog  Boxes, 
also  selected  as  items  from  a  user  defined  menu,  establish 
a  sophisticated  means  of  data  input.  They  go  beyond  the 

(continued  on  page  18) 
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(continued  from  page  15) 

simple  buttons  and  check  boxes  of  menus  and  allow  the 
user  to  enter  string  or  numeric  data  from  the  keyboard.  The 
Dialog  Box  in  our  program  will  allow  the  entry  of  a  title,  x 
axis  and  y  axis  labels,  and  maximum  integer  values  for  both 
the  x and  y  axes.  Finally,  a  third  procedure  will  establish  the 
“core”  of  our  current  application.  It  is  within  this  procedure 
that  mouse  information  is  collected  on  coordinate  positions 
and  button  status.  It  should  be 
pointed  out  that  only  integers  can 
be  passed  through  the  message 
queue.  This  does  not  mean  that 
your  program  cannot  use  real  num¬ 
bers,  it  just  means  that  you  cannot 
pass  them  through  the  queue. 

There  is  a  similar  structure  for 
intercepting  messages  in  the  Line- 
DiaProc.  This  Dialog  Box  is  cre¬ 
ated  if  case  IDM_INPUTis  true  dur¬ 
ing  the  processing  of  the  WM_COM- 
MAND  function  in  the  procedure. 

This  is  the  Dialog  Box  that  queries 
the  user  for  labels  and  plotting 
ranges.  In  this  case,  information 
will  only  be  returned  from  the  Dia¬ 
log  Box  when  the  “Okay"  button 
is  selected.  If  the  “Cancel”  button 
is  selected,  the  Dialog  Box  will  be 
destroyed,  but  no  new  informa¬ 
tion  will  be  intercepted.  The  func¬ 
tions  WinQueryDlgltemText and  WinQueryDlgltemShort re¬ 
turn  the  string  information  for  the  labels  and  the  integer 
information  for  the  plotting  ranges,  respectively.  In  both 
cases,  the  final  outcome  of  selecting  either  push  button  is 
to  process  the  message,  destroy  the  Dialog  Box,  and  return 
to  the  application  program. 

Processing  the  GraphicProc  Information 

There  are  seven  switch-case  statements  in  this  procedure 
for  processing  message  information:  WMJ2REATE ,  WM_BVT 
TONI  DOWN,  WM_MO  USEMO  VE,  WM_BUTTON2DOWN, 
WM_SIZE,  WM_  COMMAND,  and  WM_PA1NT.  It  is  within 
these  cases  that  data  will  be  collected  and  processed. 

You  have  already  seen  that  WMjCOMMAND  is  responsi¬ 
ble  for  establishing  one  of  the  two  Dialog  Boxes  when 
requested.  WM_CREATEWi\\  replace  the  default  arrow  pointer 
with  the  pointer  created  in  the  Icon  Editor  by  calling  Win 


LoadPointer.  This  pointer  tracks  the  current  mouse  position 
with  WM_MOUSEMO  VE.  In  WM_MOUSEMO  VE,  the  WinSet- 
Pomterfunction  places  the  pointer  in  the  window.  WM_S1ZE 
processes  the  request  for  the  mouse  menu.  The  mouse 
menu  allows  the  selection  of  the  two  Dialog  Box  options 
mentioned  earlier. 

WM_BUTTONlDOWN  and  WM_BUTTON2DOWN  report 
on  the  status  of  the  two  mouse  buttons.  If  the  left  button  is 
pushed,  a  marker  is  placed  on  the 
screen  at  the  current  mouse  loca¬ 
tion.  Additionally,  if  the  left  button 
is  pushed,  that  coordinate  infor¬ 
mation  is  also  placed  in  two  global 
arrays:  ptxorgf]  and  ptyorgO.  This 
coordinate  information  will  be  used 
when  plotting  the  line-of-best-fit 
between  the  data  points.  Note  that 
during  WM_BUTTONlDOWN,  Gpi 
SetMarkeris  used  to  draw  a  system 
marker  symbol.  GpiSetColor  sets  the 
symbol  drawing  color  to  blue.  Mouse 
message  data  is  returned  through 
the  parml  parameter,  which  is  of 
type  MPA  PAM.  MPARAM  is  a 
pointer  to  this  additional  message 
information.  Up  to  100  points  can 
be  collected  in  this  manner.  When 
all  data  points  have  been  entered, 
the  user  can  push  the  right  mouse 
button  to  generate  a  line  of  best  fit 
and  the  corresponding  slope-intercept  equation. 

WM_BUTTON2DOWN  uses  the  information  returned  to 
the  global  arrays,  ptxorgfj and ptyorgl],  to  draw  the  line.  First, 
however,  this  information  is  processed  and  scaled.  When 
WM_BUTTON2DOWN  is  called,  the  slope  and  intercept  of 
the  line  are  used  to  establish  a  beginning  and  ending  point 
on  the  graph.  When  the  starting  point  is  found,  the  GpiMove 
function  places  the  cursor  at  that  position.  The  GpiLine 
function  then  draws  a  red  line  between  that  point  and  the 
final  point  on  the  screen.  Finally,  the  equation  is  drawn  to 
the  screen  with  a  series  of  GpiBox,  GpiColor,  GpiMove,  and 
GpiCharString  function  calls. 

Numerous  lines-of-best-fit  can  be  plotted  on  the  same 
graph.  Simply  plot  a  group  of  points  and  request  a  line,  then 
plot  another  group  and  request  another  line.  The  screen  can 
be  cleared  by  selecting  the  mouse  data  Dialog  Box  and 
selecting  either  push  button  option. 


Figure  2:  The  Dialog  Box 
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WM_PA1NT  is  responsible  for  setting  the  background 
color,  drawing  the  coordinate  axes,  plotting  tic  marks,  set¬ 
ting  the  character  mode  for  drawing  text  to  the  screen,  and 
plotting  axis  labels.  Lines  are  drawn  by  moving  the  cursor 
to  the  starting  point  of  the  line  with  the  GpiMove  function. 
The  coordinates  (ptl.x  and  ptl.y)  are  of  PM  type  POINTL. 
GpiLine  specifies  the  ending  point.  The  axes  and  tic  marks 
are  drawn  with  just  these  two  functions.  The  GpiCharString- 
At  function  is  used  to  draw  the 
various  labels.  GpiCharStringAt  re¬ 
quires  that  a  handle,  coordinate 
position,  length  of  string  parame¬ 
ter,  and  the  actual  label  be  pro¬ 
vided  for  the  function.  If  you  ex¬ 
amine  the  listing,  you  will  see 
how  this  is  done.  It  should  be 
noted  that  for  the  default  drawing 
mode,  used  by  PM,  the  screen 
coordinates  start  at  the  lower-left 
portion  of  the  screen  (0,0)  and 
extend  to  the  upper-right  portion 
of  the  screen.  For  the  VGA  moni¬ 
tor  the  upper-right  coordinates  are 
(639,479). 

Calculating  the  Line-of-Best-Fit 

When  WM_BUTTONlDO  WN  has 
completed  the  process  of  filling 
the  ptxorgO  and  ptyorgl]  arrays,  it 
will  be  possible  to  calculate  the 
line-of-best-fit.  Most  of  the  calculations  take  place  in  the 
GraphicProc  procedure,  immediately  after  the  data  declara¬ 
tions.  Two  groups  of  arrays  are  used:  ptxorgO  and  ptyorgO 
along  with  ptxscaledO  and  ptyscaledO.  The  arrays  ptxorgf] 
and  ptyorgO  are  used  to  determine  the  slope-intercept  data 
for  the  line  that  will  be  drawn  on  the  screen.  These  contain 
the  screen  coordinate  values  returned  by  the  mouse.  How¬ 
ever,  because  this  information  is  biased  by  the  starting, 
ending,  and  scaling  of  the  screen,  it  must  be  adjusted  in 
order  to  provide  “real  world”  values  for  the  line-of-best-fit 
equation  that  will  also  be  printed  to  the  screen.  Thus, 
ptxscaledO  and  ptyscaledO  are  arrays  that  hold  the  unbiased 
values.  The  screen  window  for  gathering  points  varies  from 
(100,100)  to  (500,400). 

Two  standard  equations  (shown  in  Figure  3)  are  used  for 
the  linear  curve  fitting  program.  They  are  derived  from  the 
calculus  and  give  the  slope  and  intercept  of  the  final  line  — 
the  line-of-best-fit.  More  information  on  general  curve  fitting 
can  be  found  in  Numerical  Recipes  in  C  (Press,  Flannery, 
Teukolsky,  and  Vetterling,  Cambridge  University  Press,  1988.) 

In  these  equations,  n  represents  the  number  of  data 
points  with  each  x(  and  y(  representing  the  individual  x  and 


Figure  3-'  Equations  used  for  a  linear  curve  fitting  program 
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y  values  for  each  data  point.  If  you  study  the  code  under  the 
comment  “/*  Calculate  values  for  screen  location  */”  you 
will  notice  that  two  numerators,  numl  and  num'2,  are 
calculated  along  with  one  denominator,  deno2.  If  numl  is 
divided  by  deno2  the  intercept  will  be  calculated.  If  num2 
is  divided  by  deno2,  the  slope  of  the  line  is  calculated.  This 
is  done  under  the  call  to  WM_BU'l '1 ON2DOWN.  A  similar 
technique  is  used  for  the  array  of  scaled  data  points. 

Running  the  Program 

If  you  have  entered  the  code  and 
compiled  the  program  give  it  a  try. 
Make  sure  you  have  a  Microsoft 
mouse  or  equivalent  connected  and 
installed.  Experiment  with  several 
lines.  Figure  4  shows  one  line¬ 
fitting  example. 

The  program  suffers  from  two 
weaknesses.  First,  it  only  allows 
you  to  plot  points  in  the  first  quad¬ 
rant.  Second,  it  will  fail  if  a  vertical 
line  (an  infinite  slope)  is  requested. 
Both  problems  are  relatively  easy 
to  solve.  Plotting  in  all  four  quad¬ 
rants  can  be  achieved  by  remap¬ 
ping  the  axes  and  adjusting  the 
scaling  factors.  The  vertical  line 
problem  is  even  easier  —  simply 
use  a  case  statement  to  capture  the 
request  and  then  use  the  GpiLine 
function  to  draw  a  vertical  line  at  the  current  x  position. 

Availability 

All  source  code  for  articles  in  this  issue  is  available  on  a 
single  disk.  To  order,  send  $14.95  (Calif,  residents  add  sales 
tax)  to  Dr.  Dobbs  Journal ,  501  Galveston  Dr.,  Redwood 
City,  CA  94063;  or  call  800-356-2002  (from  inside  Calif.)  or 
800-533-4372  (from  outside  Calif.).  Please  specify  the  issue 
number  and  format  (MS-DOS,  Macintosh,  Kaypro). 

DDJ 

(Listings  begin  on  page  78.) 

Vote  for  your  favorite  feature/article. 

Circle  Reader  Service  No.  1. 
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An  Icon  Editor 

Roll  your  own  icons  using  a  mouse  and  this  program 


Keith  Weiskamp  and  Loren  Heiny 


George  Orwell,  the  great  author 
and  futurist,  was  born  forty 
years  too  early  to  be  a  hacker, 
but  he  had  a  lot  to  say  about 
languages.  In  an  essay  he  pub¬ 
lished  in  1946  entitled  “Politics  and  the 
English  Language,"  he  introduced  his 
famous  principle  of  optimization:  “Never 
use  a  long  word  where  a  short  one  will 
do.”  Unfortunately,  George’s  crystal  ball 
wasn’t  fine-tuned  enough  to  predict 
the  Macintosh,  Windows,  and  Presen¬ 
tation  Manager  explosion.  If  it  were, 
he  could  have  taken  credit  for  the  rule 
that  all  serious  user  interface  designers 
have  posted  by  their  machines:  “Never 
use  a  word  where  a  picture  will  do.” 

Indeed,  these  little  pictures,  com¬ 
monly  called  icons,  have  invaded  our 
lives.  They’re  on  the  streets,  in  the  courts, 
and  now  they’re  on  our  screens.  And 
if  you’ve  ever  used  a  visually  oriented 
application,  such  as  a  painting  pro¬ 
gram,  you  probably  have  already  dis¬ 
covered  that  clicking  on  a  picture  of  a 
line  in  order  to  draw  a  line  is  much 
easier  than  having  to  type  a  command 
that  you  can’t  remember. 

In  this  article,  we’ll  show  how  to 
develop  an  icon  editor  in  Turbo  C  called 
“ICONED.”  With  this  editor  you  can 
use  a  mouse  to  create,  save,  and  edit 
icons.  The  icons  that  you  design  can  be 
read  from  files  and  then  displayed  in 
your  applications  to  enhance  your  user 
interfaces.  Our  application  has  two  parts: 
The  main  program,  which  contains  the 
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code  for  the  icon  editor  (see  Listing  One, 
page  84),  and  a  set  of  tools  that  are 
required  to  support  the  mouse  (see  List¬ 
ings  Two  and  Three,  pages  87  and  88). 

Supporting  Graphics  Devices 

In  the  past,  the  process  of  writing  a 
graphics-based  program  for  the  PC  was 
about  as  frustrating  as  cleaning  a  swim¬ 
ming  pool  in  a  dust  storm.  As  soon  as 
you  got  your  eye-catching  program  up 
and  running,  another  graphics  standard 
would  be  introduced.  Fortunately,  com¬ 
piler  vendors  such  as  Microsoft  and 
Borland  now  provide  device-indepen¬ 
dent  graphics  tools  with  their  language 
products.  This  means  that  you  can  write 
a  program  that  works  with  all  of  the 
major  graphics  adapters  including  the 
CGA,  EGA,  and  VGA. 

For  this  article,  we  decided  to  use 
Turbo  C  because  of  its  flexible  BGI 
(Borland  Graphics  Interface).  (After  mak¬ 
ing  some  minor  modifications  to  the 
code,  you  could  also  compile  it  with 
Microsoft’s  QuickC.)  The  BGI  tools  pro¬ 
vided  with  Turbo  C  (and  with  all  of  the 
other  Turbo  languages)  is  a  useful  graph¬ 
ics  package  because  it  lets  you  use  a 
variety  of  PC  graphics  hardware  de¬ 


vices,  from  CGA  to  VGA,  to  perform 
high-  and  low-level  graphics.  More  than 
70  graphics  routines  are  provided  for 
performing  tasks  that  range  from  de¬ 
tecting  graphics  adapters  to  drawing 
and  filling  polygons. 

Getting  to  Work 

The  BGI  provides  all  of  the  high-level 
graphics  support  tools  that  are  needed 
in  order  to  create  the  icon  editor.  To 
support  the  icon  editor,  a  graphics 
adapter  supported  by  the  BGI  plus  a 
Microsoft-compatible  mouse  are  re¬ 
quired.  Mouse  support  is  handled  by 
some  of  the  functions  that  we  present 
in  this  article.  These  functions  initialize 
the  mouse,  read  the  mouse  position, 
and  hide  and  display  the  mouse  cur¬ 
sor.  (We  won’t  spend  a  lot  of  time 
discussing  how  the  mouse  works.  For 
more  information  about  the  mouse,  see 
the  references  at  the  end  of  this  article.) 

A  sample  of  the  type  of  icons  gener¬ 
ated  by  the  icon  program  is  shown  in 
Figure  1.  The  functions  used  in  the 
main  program  are  listed  and  briefly 
described  in  Table  1 .  Essentially,  these 
functions  fall  into  two  categories:  “graph¬ 
ics  screen  processing”  and  “file  pro¬ 
cessing.”  The  graphics  screen  process¬ 
ing  functions,  such  as  init_bigbit( ) and 
init _graphics( ),  control  how  icon  im¬ 
ages  are  displayed.  The  file  processing 
functions,  such  as  read_icon( )  and 
save_icon( ),  are  used  to  read  and  save 
icon  images.  The  mouse  support  func¬ 
tions  are  listed  in  Table  2. 

The  Icon  Editor  in  Action 

The  icon  editor  is  shown  in  Figure  2. 
Notice  that  two  primary  regions  are 
displayed.  The  left  side  of  the  screen 
shows  an  enlarged  representation  of 
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the  icon  that  is  being  edited.  The  edit¬ 
ing  process  is  performed  within  this 
window.  The  right  side  of  the  screen 
displays  the  icon  pattern  in  the  pattern’s 
actual  size  while  the  pattern  is  being 
edited.  The  current  state  of  the  icon  is 
updated  after  every  mouse  action. 

To  edit  an  icon,  simply  click  the 
mouse  on  any  of  the  big  icon  bits  in  the 
enlarged  icon  window.  Each  time  you 
click  the  mouse  on  a  big  pixel,  the 
pixel’s  state  is  toggled  either  ON  or 
OFF.  To  exit  the  editing  process  and 
save  or  discard  your  work,  select  the 
Esc  key.  If  the  edited  icon  is  saved,  then 
it  can  be  read  in  later  and  edited  again. 

Representing  Icons 

Icons  can  be  represented  in  many  dif¬ 
ferent  ways.  Our  goal  is  to  develop  icons 
that  look  good  when  displayed  with  the 
different  graphics  modes  supported  by 
the  BGI.  An  icon  drawn  in  one  mode 
may  appear  quite  different  in  another 
mode  because  of  that  mode’s  different 
screen  resolution  and  aspect  ratio. 

We’ve  standardized  the  size  of  our 
icons  at  l6-by-l6  pixels.  This  size  works 
well  in  most  cases  (at  least  in  the  stan¬ 
dard  graphics  modes  supported  by  the 
CGA,  EGA,  and  VGA  adapters).  Inter¬ 
nally,  an  icon  pattern  is  represented  in 
the  editor  as  a  two-dimensional  array. 

Each  location  in  the  icon  array  corre¬ 
sponds  to  a  pixel  setting  in  the  icon 
pattern.  Because  our  icons  are  displayed 
in  a  single  color,  they  can  be  easily 
represented  by  storing  the  values  1  or 
0  in  each  location  of  the  icon  array.  If 
the  stored  value  is  1,  then  the  corre¬ 
sponding  icon  pixel  is  displayed.  If  the 
stored  value  is  0,  then  the  pixel  is  set 
to  the  current  background  color.  (If 
you  wanted  to  store  color  attributes, 
you  could  modify  the  icon  array  data 
structure.) 

Saving  Icons 

As  each  icon  is  created,  it  is  saved  in  its 
own  file.  This  file  consists  of  a  header 
and  a  body.  The  header  is  a  single  line 
that  specifies  the  icon’s  width  and 
height.  Because  the  size  of  each  newly 
created  icon  is  l6-by-l6  pixels,  each 
icon’s  header  will  always  start  with  those 
two  numbers.  (This  feature  lets  you 
easily  modify  the  program  to  work  with 
icons  of  different  sizes.)  The  remainder 
of  the  file  contains  the  icon  pattern, 
which  is  organized  in  a  row  and  col¬ 
umn  format.  A  l6-by-l6  icon  has  16 
numbers  per  line  where  each  pixel  of 
the  icon  image  is  represented  by  a  0 
or  a  1.  Figure  3  shows  a  sample  icon 
and  Figure  4  shows  the  file  that  stores 
the  icon  shown  in  Figure  3-  Compare 
the  two  figures  and  note  the  one-to- 
one  correspondence  between  each 


pixel  set  in  the  icon  and  each  value  of  Once  the  filename  is  specified,  read_ 
1  in  the  file.  icon( .)  attempts  to  open  the  correspond- 

The  function  used  to  save  an  icon  ing  file.  If  that  operation  succeeds,  then 

image  is  save_icon( ).  To  simplify  user  the  first  line  of  the  file,  which  contains 

input,  save_icon( )  is  designed  to  be  the  header,  is  read.  If  the  first  line  con- 

invoked  while  the  program  is  in  text  sists  of  two  values  that  are  equivalent 

mode.  The  process  of  saving  an  icon  to  ICONWIDTH  and  ICONHEIGHT, 

involves  several  steps.  First,  save_icon( )  read_icon( )  continues.  If  any  other 

prompts  you  to  enter  the  name  of  the  numbers  are  found,  then  the  file  is 

file  where  the  icon  is  to  be  stored,  invalid  and  read_icon( )  terminates  by 

Next,  fopen( )  is  called  to  open  and  returning  0. 

initialize  the  file.  Finally,  a  nested  for  The  icon  pattern  is  read  from  the 
loop  writes  the  icon  pattern  stored  in  file  into  the  array  icon  by  two  for  loops 
the  array  icon  to  the  file  and  calls  fclose( )  (like  those  used  in  save_icon( ),  which 
to  close  the  file.  write  the  icon  data  to  a  file.  In  this 

case,  the  for  loops  use  fscanf(  )to  read 
Reading  an  Icon  File  the  icon  pattern  from  the  file.  Once 

The  process  of  reading  an  icon  file  into  the  icon  pattern  has  been  read  into 

the  icon  editor  is  similar  to  the  process  the  array  icon,  the  pattern  can  be 

of  writing  a  file.  An  icon  file  is  read  into  displayed, 

the  icon  editor  by  the  function  read_ 

icon(  ),  which  is  designed  to  run  in  text  The  Core  of  the  Icon  Editor 
mode  in  order  to  simplify  text  input.  Now  that  we’ve  discussed  the  process 
read_icon( )  first  initializes  the  icon  of  representing  icons  and  saving  them 
pattern  so  that  the  pattern  contains  all  in  external  files,  let’s  jump  in  and  ex¬ 
zeros.  (This  step  ensures  that  the  icon  plore  the  main  program.  The  first  ten 
pattern  starts  as  a  “blank”  pattern.)  statements  in  ICONED  (Listing  One) 
read_icon( )  then  asks  if  you  wish  to  initialize  the  various  components  of 
edit  an  existing  icon  file.  If  your  re-  the  icon  editor.  The  process  of  initiali- 
sponse  is  affirmative  (you  type  any  char-  zation  consists  of  reading  an  icon  file, 
acter  except  the  letter  N),  read_icon( )  initializing  the  graphics  mode,  initializ- 

requests  the  name  of  the  icon  file.  Re-  ing  the  mouse,  generating  the  enlarged 

member  that  during  this  process,  the  icon  pattern,  and  displaying  the  initial 
data  entry  operations  are  performed  in  state  of  the  icon  pattern.  The  functions 
text  mode.  called  are: 


Figure  1:  Icons  that  are  typical  of  those  generated  by  the  icon  editor  program 


Function  Name 

Description 

draw_enlarged_icon( ) 

Draws  an  enlarged  view  of  an  icon 

init_bigbit( ) 

Initializes  a  single  big  icon  bit 

init__graphics( ) 

Initializes  the  graphics  hardware 

read_icon( ) 

Reads  an  icon  file 

save_icon( ) 

Saves  an  icon  image  to  a  file 

show_icon( ) 

Displays  the  icon  pattern  stored  in  the  icon  array 

toggle_bigbit( ) 

Turns  a  big  bit  on  or  off 

toggle_icons_bit( ) 

Turns  a  standard  size  icon  bit  on  or  off 

Table  1:  Functions  used  in  the  icon  editor 
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read_icon(  ); 
init_graphics(  ); 
initmouse(  ); 
draw_enlarged_icon(  ); 
show_icon(  ); 

These  statements  must  be  called  in  the 
order  shown  above.  In  particular,  read_ 
icon()  should  be  kept  in  text  mode 
(before  graphics  initialization  occurs) 
in  order  to  simplify  user  interaction.  In 
addition,  the  mouse  initialization  pro¬ 
cess  must  always  occur  after  the  graph¬ 
ics  initialization  process  is  completed. 

The  next  five  statements  print  a  se¬ 
ries  of  banners  to  the  screen  by  calling 
the  outtextxyO  function.  Notice  that  a 
pair  of  hidemouse(  Jand  showmouse( ) 
function  calls  surround  the  screen  out¬ 
put  statements.  These  calls  ensure  that 
the  mouse  cursor  is  turned  off  while 
the  screen  is  being  updated  with  the 
displayed  messages. 

After  the  screen  is  initialized,  the  icon 
editor  is  ready  for  business.  Two  types 
of  input  are  accepted  while  an  icon  is 
being  edited: 

1.  A  left  mouse  button,  which  toggles 
the  icon  pixel  that  is  being  pointed  to 
by  the  mouse  cursor; 

2.  The  Esc  key,  which  terminates  the 
program.  The  while  loop  in  the  func¬ 


tion  main( )  reads  and  processes  the 
user  inputs  as  shown  below: 

while  ((c=waitforinput(LEFT_ 

BUTTON))  !=  ESC)  ( 

if  (c  <  0)  ( 

getmousecoords(&x,  &y); 
toggle_bigbit(x,  y); 

1 

1  while  Odone); 

The  loop  uses  the  general  purpose 
mouse  input  function  waitforinput( ), 
(see  Listing  Two).  This  function  returns 
a  negative  value  if  the  specified  button 
(in  this  case,  the  left  mouse  button)  is 
pressed.  If  a  key  is  pressed,  then  wait- 
forprintC  )  returns  the  value  of  that  key. 
The  program  will  continue  until  the 
Esc  key  is  pressed.  If  the  left  mouse 
button  is  pressed,  the  body  of  the  while 
loop  is  entered.  At  this  point,  getmouse- 
coordsf )  retrieves  the  current  location 
of  the  mouse  cursor  and  passes  it  to  the 
function  toggle_bigbit( ),  which  changes 
the  setting  of  the  icon  pixel  that  the 
mouse  is  pointing  to. 

Creating  an  Enlarged  Icon 

The  function  draw_enlarged_icon( ), 
which  is  called  from  main( ),  displays 
an  editing  grid  on  the  left  side  of  the 
screen.  The  grid  consists  of  17  horizon- 


Figure  2:  The  icon  editor  screen 


'  Press  ESC  when  finished  , 


/  I 

CTTyrl  ■ . 
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Function  Name 


Description 


BIGICONLEFT 

BIGICONTOP 

BJGBITSIZE 

ICONWIDTH 

ICONHEIGHT 

DOTTED  LINE 


NORM  WIDTH 


The  column  where  the  big  icon  pattern  begins 

The  top  row  of  the  big  icon  pattern 

Size  of  the  big  pixels  in  the  enlarged  icon  pattern 

Width  of  an  icon 

Height  of  an  icon 

From  graphics. h;  specifies  the  line  type 
From  graphics. h;  pixel  width  of  lines 


Figure  3:  A  sample  icon. 

See  Figure  4 for  more  details. 


Figure  4:  The  contents  of  the  file  that 
make  up  the  icon  shown  in  Figure  3- 


Table3:  Macro  constants  used  in  drawing  the  enlarged  icon  pattern 
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tal  and  vertical  dotted  lines  that  desig¬ 
nate  a  l6-by-l6  grid  for  the  icon  pat¬ 
tern.  Before  anything  is  written  to  the 
screen,  the  mouse  cursor  is  turned  off 
by  a  call  to  hidemouse( ).  Later,  the 
mouse  cursor  is  restored  by  a  call  to 
shoumouseC  ).  This  technique  eliminates 
the  problem  of  overwriting  the  mouse 
cursor. 

Examine  the  code  in  draw_enlarged_ 
iconC )  and  note  that  this  function  re¬ 
lies  upon  numerous  macro  constants. 
A  list  of  these  macro  constants,  along 
with  a  description  of  their  meanings, 
is  shown  in  Table  3.  You  may  want  to 
refer  to  this  table  as  you  work  your  way 
through  draw_enlarged_icon(  ). 

The  last  line  in  draw_enlarged_ 
icon()  is  a  call  to  init_bigbit( ),  which 
creates  an  image  of  an  enlarged  icon 
pixel.  To  toggle  the  icon  pixels  in  the 
enlarged  icon  pattern,  we’ll  exclusive 
OR  the  image  created  by  init_bigbit( ) 
to  the  rectangular  regions  within  the 
enlarged  icon  pattern. 

A  nested  for  loop  is  used  to  create 
the  image  of  one  of  the  enlarged  bits 
at  the  beginning  of  init_bigbit( ),  as 
shown  below: 

for  (j=bby+l;  j<=bby+BIGBITSIZE; 

j++) 

for  (i=bbx+l;  i<=bbx+2*BIG 

BITS1ZE;  i++» 
putpixel(i,j,getmaxcolor( ); 

These  two  loops  paint  a  block  of  pixels 
in  the  top-left  corner  of  the  enlarged 
icon  pattern.  This  block  is  the  size  of 
BICBITS1ZE.  Notice  that  the  width  of 
the  enlarged  icon  is  drawn  to  be  twice 
the  width  of  BIGBITSIZE.  This  step  ad¬ 
justs  the  icon  image  to  the  aspect  ratio 
of  the  graphics  screen. 

After  the  enlarged  icon  pixel  is  cre¬ 
ated,  it  is  copied  into  the  array  bigbit. 
(Once  the  pixel  pattern  has  been  stored 
in  bigbit ,  an  image  of  the  pattern  can 
be  exclusive-ORed  later  during  the  ed¬ 
iting  process  in  order  to  toggle  one  of 
the  enlarged  icon  pixels.) 

Before  the  enlarged  icon  pixels’  im¬ 
age  can  be  copied  into  bigbit ,  space  for 
the  image  must  be  allocated  by  a  call 
to  malloc( ).  After  the  space  is  allo¬ 
cated,  getimageC )  is  called  to  copy  the 
image  of  the  big  pixel.  Next,  putimage( ) 
is  invoked  with  the  XOR_PUT replace¬ 
ment  in  order  to  remove  the  big  pixel 
from  the  top-left  corner  of  the  enlarged 
icon  pixel: 

putimage(bbx+ 1 ,  bby+1,  bigbit, 

XOR_PUT); 

Finally,  the  mouse  cursor  is  restored 
by  a  call  to  showmousej ),  and  then 
init_bigbit(  )  terminates. 


Displaying  the  Original  Icon 

The  next  step  in  the  screen  initializa¬ 
tion  process  is  to  display  the  icon  pat¬ 
tern  that  was  read  in  at  the  beginning 
of  the  program.  (Remember,  if  an  icon 


Each  location 
in  the  icon  array 
corresponds  to  a 
pixel  setting  in  the 
icon  pattern 


file  is  not  read  in,  then  read_icon( ) 
initializes  the  icon  array  to  zeros.)  The 
function  show_icon(  )  displays  the  cur¬ 
rent  state  of  the  icon  pattern.  This  func¬ 
tion  consists  of  two  nested  for  loops 
that  sequence  through  the  array  icon. 
For  each  byte  location  that  stores  the 
value  1,  a  corresponding  big  bit  is  tog¬ 
gled  in  the  enlarged  icon,  and  the  small 
icon  pattern  is  updated.  The  process  of 
setting  one  of  the  big  icon  pixels  is  a 
matter  of  exclusive-ORing  the  image  of 
the  big  icon  pixel  (as  discussed  earlier) 
at  the  appropriate  locations.  The  put- 
image(  )  function,  which  is  located  within 
the  inner  for  loop,  performs  this  step. 

The  call  to  toggle_icons_bit( )  is  re¬ 
quired  in  order  to  turn  on  the  appropri¬ 
ate  pixel  in  the  small  icon  pattern.  This 
function  accepts  the  index  of  a  pixel 
in  the  icon  array  as  an  argument,  and 
checks  the  corresponding  pixel  by  test¬ 
ing  whether  that  pixel  is  equal  to  the 
background  color.  Depending  upon  the 
pixel's  current  value,  the  small  icon’s 
pixels  are  toggled.  The  small  icon  is 
displayed  at  the  column  indicated  by 
ICONLEFT.  The  top  row  of  the  small 
icon  coincides  with  BIGICONTOP.  No¬ 
tice  that  although  the  icon  is  repre¬ 
sented  as  a  l6-by-l6  pattern,  the  small 
icon  is  displayed  in  a  32-by-l6  format. 
In  other  words,  each  column  of  pixels 
is  displayed  twice  — and  that’s  why  the 
multiplication  factor  of  2  in  the  x  coor¬ 
dinate  calculation  is  required. 

Toggling  an  Icon  Pixel 

The  process  of  toggling  a  pixel  in  an  icon 
that  is  being  edited  involves  three  steps: 


1.  The  pixel’s  value  in  the  icon  array 
must  be  changed; 

2.  The  big  pixel  image  in  the  enlarged 
icon  pattern  must  be  toggled;  and 

3.  The  icon’s  pixel  in  the  small  icon 
pattern  must  be  updated. 

Each  of  these  actions  is  set  in  motion 
by  invoking  toggle_bigbit( ).  This  func¬ 
tion  takes  two  arguments  that  corre¬ 
spond  to  the  screen  coordinates  of  the 
enlarged  icon  bit  that  is  to  be  changed. 
These  screen  coordinates  are  deter¬ 
mined  from  the  location  of  the  mouse 
cursor  at  the  time  of  the  button  press. 
The  mouse  coordinates  are  determined 
by  our  mouse  routine,  getmousecoords( ). 

The  bulk  of  toggle_bigbit( )is  involved 
in  deciding  which  icon  bit  (if  any) 
should  be  toggled.  This  decision  is  made 
by  the  two  for  loops  that  sequence 
through  the  locations  of  the  big  icon 
pattern  and  test  whether  the  coordi¬ 
nates  passed  to  toggle_bigbit( )  fall 
within  any  of  the  rows  or  columns  in 
the  big  icon  pattern.  If  the  passed  coor¬ 
dinates  fall  within  the  big  icon  pattern, 
putimage( )  is  used  to  exclusive-OR 
an  image  of  the  bigbit  image  that  was 
made  earlier  over  the  current  location 
in  the  icon  pattern.  This  step  toggles 
the  icon  pixel  in  the  large  icon  pattern. 
Because  the  corresponding  bit  in  the 
small  icon  pattern  must  be  changed, 
the  routine  is  designed  so  that  the  line 
number  and  the  column  number  deter¬ 
mined  by  the /orloops  will  correspond 
to  the  indices  that  can  access  the  same 
bit  in  the  icon  array.  These  values,  which 
are  stored  in  the  variables  i  and  j,  are 
passed  to  another  function,  toggle_icons_ 
bit( ).  This  step  changes  the  icon  array 
value  and  updates  the  small  icon  on 
the  screen. 

Exiting  the  Icon  Editor 

The  while  loop  (described  earlier)  that 
controls  user  interaction  continues  to 
loop  until  the  Esc  key  is  pressed.  Once 
the  Esc  key  is  pressed,  the  mouse 
cursor  is  disabled,  the  screen  is  re¬ 
turned  to  text  mode,  and  the  user  is 
prompted  to  save  the  icon  currently  in 
the  icon  editor.  If  the  user  responds 
with  anything  other  than  the  letter  N, 
the  program  enters  the  save_icon( )  func¬ 
tion  and  prompts  the  user  for  the  name 
of  the  file  in  which  the  icon  will  be 
stored. 

Putting  it  Together 

To  create  an  executable  version  of  the 
icon  editor,  compile  the  files  iconed.c 
and  mouse. c  (provided  in  Listings  One 
and  Two)  and  then  link  them  with 
Turbo  C’s  graphics  library  file,  graph¬ 
ics. lib.  To  use  the  icons  that  you  create 
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with  the  icon  editor  in  your  application 
programs,  include  the  read_icon(  Jand 
show_icon( )  functions.  You’ll  also  need 
to  write  a  routine  that  allows  the  user 
to  select  icons  by  clicking  on  them 
with  the  mouse. 

Enhancements 

There  are  a  number  of  enhancements 
that  you  can  make  to  the  icon  editor. 
For  instance,  we  have  designed  the 
icon  editor  to  work  with  fixed-size  icons. 
Because  of  the  flexibility  of  the  pro¬ 
gram,  you  can  change  the  default  icon 
size  or  include  an  option  that  lets  you 
design  and  store  icons  of  different  sizes. 

We’ve  already  pointed  out  some  of 
the  mouse  functions  used  in  the  icon 
editor,  such  as  hidemouse( ),  show- 
mousej  ),  getmousecoords( ),  and  wait- 
forinput( ).  All  of  these  functions  di¬ 
rectly  or  indirectly  invoke  the  main 
mouse  interface  function,  mouse( ).  This 
function  communicates  with  the  mouse 
software  drivers  by  invoking  interrupt 
33b  with  Turbo  C’s  int86( )  function. 
If  you  don’t  have  a  mouse  installed,  the 
main  program  will  terminate  after  call¬ 
ing  initmouse( ).  Alternatively,  you 
could  modify  the  mouse  support  rou¬ 
tines  so  that  they  support  the  keyboard 
if  a  mouse  is  not  available. 

These  suggestions  represent  the  tip 
of  the  iceberg.  The  icon  editor  can 
serve  as  the  first  of  a  series  of  tools  that 
will  help  you  design  more  flexible  user 
interfaces.  Because  icons  are  created 
and  stored  independent  of  the  appli¬ 
cation  program,  you  can  redesign  an 
interface  without  the  need  to  make  ma¬ 
jor  changes  to  the  program. 
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Multitasking 

OS  and 

Graphics  Coprocessors 


More  is  better  when  it  comes  to  graphics 


Chuck  McManis 


Graphics  coprocessors  have  tra¬ 
ditionally  been  used  only  on 
specialized  high-performance 
graphics  display  systems  run¬ 
ning  sophisticated  and  com¬ 
plex  graphics  applications.  Today,  how¬ 
ever,  the  trend  towards  window-based, 
graphical  user-interfaces  on  standard 
PCs  —  with  the  resulting  CPU  burdens 
and  performance  degradation  —  is  forc¬ 
ing  hardware  developers  to  begin  think¬ 
ing  of  coprocessors  as  standard  equip¬ 
ment  for  desktop  systems  as  well.  But 
graphics  coprocessors  are  only  half  the 
story:  The  development  of  multitasking 
operating  systems  (OSs)  has  also  played 
a  part  in  increasing  the  overall  CPU  use 
and  has  helped  make  more  powerful 
graphics  applications  more  of  a  reality 
instead  of  a  dream. 

In  this  article,  I’ll  examine  the  costs 
and  benefits  of  using  graphics  copro¬ 
cessors  in  a  multitasking  OS  environ¬ 
ment.  In  particular,  I’ll  focus  on  the 
hardware  and  software  architecture  of 
Commodore’s  68000-based  Amiga  per¬ 
sonal  computer,  which  combines  a  high- 
performance  multitasking  operating 
system  with  autonomous  graphics  copro¬ 
cessors.  Why  the  Amiga?  Because  it  is 
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the  only  mainstream  PC  that  comes 
with  a  multitasking  OS  as  standard  equip¬ 
ment.  This,  combined  with  the  innova¬ 
tive  use  of  dedicated  LSI  logic  to  offload 
CPU  tasks,  has  resulted  in  a  graphics 
platform  that  is  unique  among  PCs  in 
its  price  range.  The  Amiga’s  flexible 
architecture  and  modular  OS  allows 
programmers  legal  access  to  coproces¬ 
sors  so  they  can  be  used  to  their  fullest 
potential. 

Multitasking,  or  Who  Really  Has 
the  Coprocessor? 

When  a  program  running  a  single¬ 
tasking  OS  (like  MS-DOS)  asks  a  copro¬ 
cessor  to  draw  a  line  on  the  screen,  the 
CPU  waits  for  that  line  to  be  drawn 
while  (usually)  looping  on  some  sort 
of  status  bit  or  through  an  interrupt 
chain.  When  a  program  requests  a  line 
draw  with  a  multitasking  OS,  the  graph¬ 
ics  coprocessor  begins  the  drawing  pro¬ 
cess  and  the  task  requesting  the  line 
draw  is  dismissed;  another  task  that 
does  not  need  the  coprocessor  is  then 
allowed  to  use  the  CPU.  This  is  a  fun¬ 
damental  difference  in  behavior  be¬ 
tween  single-tasking  and  multitasking 
OSs.  Because  the  CPU  doesn’t  sit  idle 


until  the  coprocessor  finishes  its  task, 
there  is  an  increase  in  CPU  utilization. 

For  programmers,  one  drawback  of 
this  is  that  you  must  always  assume 
that  some  other  program  is  using  the 
coprocessor  or  the  display  and  you  can 
no  longer  simply  blast  away  at  the  hard¬ 
ware  and  expect  reliable  results.  In¬ 
stead,  arbitration  of  access  to  resources 
falls  under  the  domain  of  the  OS,  which 
in  turn  must  provide  the  mechanisms 
to  request  resources.  You  must  write 
programs  that  are  able  to  consider  if  a 
resource  is  available.  When  the  OS  in¬ 
terface  is  well-designed,  this  resource 
arbitration  is  handled  invisibly  and  you 
need  only  use  the  interfaces  provided 
to  guarantee  that  the  program  does  not 
interfere  with  other  tasks. 

The  Amiga  Hardware 

The  Amiga  system  architecture  includes 
a  generalized  coprocessor,  the  Cop¬ 
per,  and  a  dedicated  graphics  engine, 
the  Blitter.  These  peripherals  —  as  well 
as  four  D/A  channels,  four  A/D  con¬ 
verters,  the  system  control  functions, 
and  a  25-channel  DMA  controller  — 
are  implemented  in  a  set  of  three  cus¬ 
tom  chips  named  Agnus,  Denise,  and 
Paula.  These  chips  share  a  dedicated 
memory  bus  that  allows  them  to  access 
memory  without  interfering  with  the 
CPU.  The  custom  chips  can  only  ac¬ 
cess  memory  on  this  bus,  which  is  why 
this  memory  is  referred  to  as  Chip  Mem¬ 
ory.  As  Figure  1  shows,  the  custom 
chips  are  situated  on  the  chip  memory 
bus.  Although  the  architecture  sets  aside 
2  Mbytes  of  the  address  space  for  Chip 
Memory,  the  original  Amiga  chipset  only 
supported  512K,  and  a  recently  intro¬ 
duced  upgraded  chipset  supports  only 
1  Mbyte.  The  primary  benefit  of  this 
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extra  memory  is  that  the  CPU  can  exe¬ 
cute  code  in  memory  outside  of  this 
range  without  any  performance  degra¬ 
dation  resulting  from  contention  with 
the  custom  chips.  The  control  registers 
for  the  custom  chips  are  visible  to  the 
CPU  as  memory  addresses  in  the  range 
of  $DFF000  through  $DFFFFF. 

The  heart  of  the  coprocessor  group 
is  the  System  Controller.  It  is  here  that 
the  CPU  can  start  and  stop  the  DMA 
channels  that  feed  data  to  these  chips 
and  enable  or  disable  interrupts  from 
the  chips  to  the  CPU.  The  DMA  chan¬ 
nels  feed  data  to  various  peripherals 
such  as  the  D/A  converters.  The  four 
D/A  channels  on  the  Amiga  are  some 
of  the  simpler  peripheral  interfaces.  By 
adding  the  DMA  channel,  the  D/A  con¬ 
verter  is  elevated  to  the  status  of  a 
simple  coprocessor.  By  having  their 
waveforms  automatically  feed  into  them 
from  the  DMA  chips,  the  coprocessor 
can  output  a  digitized  waveform  with¬ 
out  any  intervention  from  the  CPU. 

The  most  sophisticated  peripheral  is 
the  Copper,  so  named  because  it  is  the 
traffic  cop  of  the  Amiga.  The  Copper  — 
with  three  instructions  (MOVE,  WAIT, 
and  SKIP)  that  allow  it  to  store  data  and 
provide  conditional  testing,  and  pro¬ 
grammatic  branching  — is,  in  some 
ways,  a  RISC  processor  in  its  own  right. 
The  Copper  is  able  to  write  to  any  of 
the  custom  chip’s  control  registers,  even 
its  own.  This  allows  the  Copper  to  be 
the  CPU’s  lieutenant  by  taking  over 
mundane  tasks  such  as  setting  up  the 
CRT  controller  (implemented  in  Den¬ 
ise)  to  build  on  the  display  every  frame. 
A  program,  called  the  Copper  List,  is 
started  at  every  vertical  blank  from  the 
start  address,  which  is  stored  in  the 
COP1LC  register.  The  Copper  is  syn¬ 
chronized  with  the  video  beam  so  that 
it  knows  where  the  beam  on  the  screen 
is  at  all  times  and  can  wait  for  it  to 
arrive  at  a  particular  position.  This  fea¬ 
ture  comes  in  handy  when  playing  with 
graphical  objects  called  sprites.  The  Cop¬ 
per  code  in  Example  1  could  be  used 
to  notify  the  CPU  that  video  frame  has 
ended.  The  Copper  is  built  to  use  alter¬ 
nate  clock  cycles  to  access  memory. 
This  allows  it  to  minimize  contention 
between  itself  and  other  coprocessors 
for  the  Chip  Memory  bus.  This  copro¬ 
cessor  is  half  of  the  equation  that  makes 
the  Amiga  such  an  effective  graphics 
platform. 

The  other  half  of  this  equation  is  the 
Blitter.  The  Blitter  is  a  graphics  compu¬ 
tation  unit  that  transfers  16-bit  words 
around  in  memory  while  performing 
bitwise  logical  operations  on  those 
words.  The  Blitter  is  capable  of  reading 
data  from  up  to  three  addresses,  per¬ 
forming  any  logical  operation  on  that 
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data,  and  then  optionally  storing  the 
result  at  a  fourth  address.  The  addresses 
are  automatically  updated  after  each 
operation  by  an  amount  you  specify. 
This  allows  the  Blitter  to  work  within 
a  programmed  area  of  a  larger  bitmap. 
Two  additional  functions  built  into  the 
Blitter  are  the  ability  to  draw  lines  be¬ 
tween  two  arbitrary  points  and  the  abil¬ 
ity  to  fill  in  an  area  with  an  arbitrary 
1 6-bit  binary  pattern. 

The  Blitter’s  contribution  to  the  Amiga 
is  the  ability  to  draw  lines  and  render 
filled  polygons  at  a  rate  that  is  equiva¬ 
lent  to  the  speed  that  the  68000  CPU 
could  if  it  were  rendering  them.  The 
key,  of  course,  is  that  the  68000  can 
now  be  off  doing  something  else.  Win¬ 
dow-based,  user-interface  operations 
often  map  a  sequence  of  commands 
directly  to  the  Blitter.  Because  of  this, 
operations  like  moving  windows,  ren¬ 
dering  menus,  and  scrolling  text  are 
completed  much  faster  on  the  Amiga 
than  on  other  68000-based  machines. 

The  Amiga  also  contains  a  sprite  en¬ 
gine  that  is  capable  of  overlaying  its 
contents  on  the  screen  at  an  internally 
specified  X  and  Y  coordinate.  The  sprite 
can  be  thought  of  as  a  self-contained 
mini-bitmap  that  is  independently  po¬ 
sitioned  on  the  screen  and  only  relies 
on  the  CPU  to  tell  it  where  and  when 
to  move.  This  activity  costs  very  little 


Example  1:  Sample  Copper  code 


in  terms  of  CPU  cycles.  The  Amiga  uses 
one  of  the  eight  available  sprites  as  the 
window  system  cursor. 

The  Amiga  Software 

The  Amiga’s  OS  has  three  major  parts: 
The  multitasking  kernel,  the  graphics 
interface,  and  the  disk  operating  sys¬ 
tem.  I’ll  discuss  the  first  two  here.  For 
further  information  on  the  DOS,  see 
the  The  AmigaDOS  Reference  Manual 
(Bantam  Books,  1987). 

The  software  foundation  of  the  OS 
is  the  multitasking  kernel,  Exec.  This 
kernel  provides  the  fundamental  con¬ 
trols  that  the  other  pieces  are  layered 
upon.  Exec  is  composed  of  several  com¬ 
ponent  parts.  The  basic  grouping  con¬ 
sists  of  the  list  management  routines, 
resident  library  support,  message  man¬ 
agement,  interrupt  handling,  task  man¬ 
agement,  resource  management,  and 
devices.  Completely  describing  Exec  is 
beyond  the  scope  of  this  article,  so  I 
will  only  describe  those  aspects  that 
support  the  coprocessors  and  graphics. 

To  prevent  processes  from  conflict¬ 
ing  with  each  other  when  they  attempt 
to  use  the  coprocessors,  Exec  must  keep 
those  processes  synchronized  to  the 
availability  of  the  resource;  Exec  uses 
messages  and  semaphores  to  accom¬ 
plish  this. 

A  message  port  is  a  rendezvous  point 


Figure  1:  The  coprocessor  situated  on  the  chip  memory  bus 
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(continued  from  page  37) 
where  many  competing  process  requests 
can  be  effectively  managed.  Exec 
queues  messages  to  a  port  using  a  first- 
in,  first-out  policy.  The  overhead  for 
this  synchronization  is  fairly  high  and 
is  generally  restricted  to  those  activities 
that  are  fairly  time-consuming  (device 
I/O,  for  instance).  The  task  that  owns 
a  resource  creates  a  message  port  upon 
which  it  receives  requests  to  use  its 
resource.  As  requests  arrive,  the  task 
removes  messages  one  at  a  time,  serial¬ 
izing  specific  requests  to  that  resource. 
A  significant  advantage  to  this  system 
is  that  the  interface  between  an  appli¬ 
cation  and  the  task  that  owns  a  re¬ 
source  is  defined  by  a  message  proto¬ 
col.  As  long  as  the  task  follows  this 
protocol,  it  may  be  replaced  by  a  new 
or  upgraded  equivalent  task  at  any  time 
without  effecting  users  of  the  resource. 
Some  resources  (such  as  the  Blitter)  can¬ 
not  be  used  simultaneously,  yet  the 
whole  reason  for  having  a  Blitter  is  to 
minimize  the  work  that  is  required  for 
the  CPU  to  render  graphics.  A  sema¬ 
phore  is  used  to  provide  a  simpler  and 
faster  method  to  ensure  exclusive  access 
to  the  Blitter  without  a  lot  of  overhead. 

A  semaphore  can  be  thought  of  as 
a  restroom  key  that  is  hanging  on  a 
hook  by  the  door.  People  wanting  to 


use  the  restroom  must  have  the  key  to 
open  the  door.  However,  because  ac¬ 
cess  is  only  allowed  if  you  have  the 

When  a  program 
requests  a  line  draw 
with  a  multitasking  OS, 
the  graphics  coprocessor 
begins  the  drawing 
process  and  the  task 
requesting  the  line  draw 
is  dismissed;  another 
task  is  then  allowed  to 
use  the  CPU 


key,  the  key  will  be  unavailable  when 
the  restroom  is  in  use  (exclusivity  is 
assured).  Because  the  key  is  available 
right  next  to  the  door  that  requires  it, 


you  are  not  needlessly  delayed  if  the 
restroom  is  free. 

Every  task  that  uses  the  screen  will 
require  the  use  of  the  Blitter.  A  sema¬ 
phore  is  maintained  by  Exec,  and  only 
the  task  that  is  currently  drawing  owns 
it.  A  library  function,  OwnBlitterf ),  is 
provided  in  the  graphics  library  to  ac¬ 
quire  this  semaphore.  This  function  re¬ 
quests  the  Blitter  semaphore  from  Exec. 
If  it  is  available,  it  is  immediately  granted, 
and  if  it  is  not  available  the  task  is 
placed  in  a  queue  for  Blitter  use  and 
dismissed.  When  the  Blitter  is  avail¬ 
able,  Exec  will  give  the  semaphore  to 
the  next  task  in  the  queue  and  resume 
it.  From  the  programmer’s  perspective, 
the  call  to  OwnBlitteif  )  will  simply 
return.  The  programmer  is  now  free  to 
use  the  Blitter  for  his  own  purposes 
because  no  one  else  will  be  granted 
access  until  he  gives  back  the  sema¬ 
phore  to  indicate  that  the  Blitter  is  no 
longer  needed.  This  is  accomplished 
with  DisownBlitter(  ). 

The  key  concept  is  one  of  owner¬ 
ship.  Because  a  program  may  not  be 
the  only  one  running,  it  cannot  assume 
it  owns  the  machine;  rather,  it  must 
synchronize  its  behavior  so  that  it  does 
not  interfere  with  another  process  that 
is  using  non-shareable  resources.  Even 
though  you  might  suspect  otherwise,  this 


additional  overhead  of  synchronization 
with  other  tasks  does  not  lead  to  slower 
or  to  unacceptable  performance. 

Another  one  of  the  kernel’s  jobs  is 
to  manage  resident  libraries  that  are 
different  from  the  libraries  you  would 
link  in  a  compiled  program.  The  differ¬ 
ence  is  that  while  there  may  be  several 
processes  using  routines  within  a  resi¬ 
dent  library,  there  is  only  one  copy  of 
that  resident  library  in  memory.  The 
graphics  library  mentioned  earlier  is 
one  such  library.  The  savings  in  mem¬ 
ory  is  tremendous  and  is  one  of  the 
reasons  that  the  Amiga  is  fully  multi¬ 
tasking  in  512K  bytes  of  RAM,  whereas 
you  would  probably  need  up  to  four 
to  eight  times  that  much  memory  to 
achieve  the  same  capabilities  on  other 
PCs.  It  is  also  another  way  of  providing 
transparent  layering  of  capabilities  to 
the  programmer. 

When  using  graphics  on  the  Amiga, 
three  libraries  make  up  the  layers  be¬ 
tween  an  application  and  the  hardware 
(from  highest  to  lowest):  Intuition  (the 
windowing  system);  Layers  (which  con¬ 
trol  clipping);  and  Graphics  (the  lower¬ 
most  layer  that  provides  the  primitives). 
These  three  layers  provide  progressively 
closer  access  to  the  hardware.  Intuition 
provides  the  highest-level  functions, 
most  of  which  are  designed  to  set  up 


the  window  system  environment  and 
to  facilitate  communication  with  the 
user.  Like  the  application  program,  In¬ 
tuition  is  a  user  of  the  Layers  and  Graph¬ 
ics  libraries. 

For  high-performance 
graphics  applications, 
coprocessors  and  a 
multitasking  OS  put  the 
Amiga  into  the 
performance  range  of 
32-hit  machines,  yet  at 
the  price  of  a  16-bit 
machine 


Where  Intuition  provides  the  win¬ 
dow  environment,  Layers  provides  the 
drawing  environment.  Rendering  com¬ 
mands  are  clipped  to  a  specified  region 


in  this  environment.  A  layer  appears 
to  a  program  as  a  contiguous  drawing 
surface.  The  actual  surface  (the  screen) 
may  actually  be  divided  into  several 
distinct  regions.  The  coprocessors  and 
the  OS  come  together  at  the  Graphics 
layer.  It  is  here  that  a  call  to  Draw( )  is 
converted  into  a  Blitter  operation. 

The  Graphics  Architecture 

The  primary  data  structure  of  Amiga 
graphics  is  the  Rastport,  which  con¬ 
tains  such  information  as  where  the 
memory  for  the  bitmaps  resides,  the 
current  text  font,  the  current  pen  col¬ 
ors,  the  coordinates  of  the  last  point 
drawn,  and  so  on.  Graphics  also  con¬ 
tains  a  Layerlnfo  structure  that,  when 
present,  is  used  by  the  layers  library  to 
determine  how  to  clip  graphics  and 
text  rendered  on  the  screen. 

The  Copper  and  the  Blitter  are  the 
main  tools  of  the  graphics  library.  The 
Copper  is  used  to  set  up  the  physical 
characteristics  of  the  display,  and  the 
Blitter  is  used  to  render  graphic  objects 
into  that  display  as  quickly  as  possible. 
Both  functions  have  a  data  structure 
that  provides  the  needed  information 
for  them  to  accomplish  what  is  required 
of  them.  For  the  Copper,  that  data  struc¬ 
ture  is  a  View. 

A  View  is  a  particular  display  mode 
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with  a  particular  set  of  colors  in  a  par¬ 
ticular  orientation  on  the  screen.  Typi¬ 
cally,  this  sort  of  thing  is  controlled  by 
the  CRT  controller  in  the  PC.  On  the 
Amiga  the  CRT  controller  is  imple¬ 
mented  in  Denise.  As  CRT  controllers 
go,  Denise  is  very  straightforward.  It 
fetches  data  from  the  bitplanes  in  chip 
memory,  feeds  this  to  a  set  of  32  color 
registers,  each  containing  a  12-bit  color 
triple:  four  bits  for  red,  four  for  green, 
and  four  for  blue.  This  triple  is  then 
input  into  three  D/A  converters  that 
convert  the  value  into  a  voltage  level 
that  goes  out  onto  the  video  connector. 
The  registers,  however,  that  control  cer¬ 
tain  processes  (where  the  data  for  dis¬ 
play  is  stored,  what  is  in  the  color  regis¬ 
ters,  and  so  on)  are  accessible  by  the 
Copper,  which  is  synchronized  to  the 
video  beam.  Thus,  a  specialized  Cop¬ 
per  List  could  be  constructed  to  control 
Denise  on  a  line-by-line  basis,  and  in 
fact  this  is  exactly  what  is  done  by  the 
graphics  library.  The  required  display 
is  described  by  filling  in  various  fields 
in  a  View  and  one  or  more  Viewport 
structures.  These  structures  are  passed 
along  to  the  graphics  library  that  con¬ 
structs  a  specialized  Copper  List  to  pro¬ 
vide  that  View.  If  the  View  is  fairly 
simple,  such  as  a  320  x  200  pixel  screen 
that  isn’t  interlaced,  the  Copper  List 
would  be  a  simple  set  of  initialization 
instructions  that  would  be  loaded  into 
the  CRT  controller  on  each  vertical 
blank.  The  power  of  this  combination 
becomes  evident  when  the  displays  be¬ 
come  more  complicated. 

Because  the  Amiga  is  capable  of  dis¬ 
playing  32  colors  when  in  the  320  pixel/ 


line  mode,  it  is  often  common  to  use 
this  mode  for  games,  paint  programs, 
and  other  applications  that  use  lots  of 
colors.  With  only  320  pixels  on  a  line, 
however,  a  program  is  limited  to  40 
characters  if  it  is  using  the  standard 
system  font.  As  a  status  line,  this  can 
be  very  limiting.  Using  the  Copper,  it’s 
possible  to  design  a  display  that  has  a 
320  x  180  pixel  screen  on  top,  and  a 
640  x  20  pixel  screen  on  the  bottom  of 
the  display.  These  two  areas  make  up 
one  complete  200  line  display.  The  Cop¬ 
per  is  required  to  switch  the  display 
mode  after  the  video  beam  has  drawn 
180  lines  on  the  monitor  in  low  resolu¬ 
tion.  Thus  the  last  20  lines,  which  are 
enough  for  two  lines  of  80  character 
text  in  the  standard  font,  can  be  used 
for  a  status  display.  Needless  to  say, 
this  is  not  an  easy  thing  to  do  with  a 
dedicated  CRT  controller,  but  with  the 
Amiga  this  is  fairly  simple.  Listing  One, 
page  90,  shows  an  example  of  setting 
up  a  View  like  the  one  described  ear¬ 
lier.  In  the  example,  the  Copper  changes 
not  only  the  resolution,  but  also  the 
values  of  the  colors  in  the  color  table. 
Listing  Two,  page  90,  shows  the  Cop¬ 
per  List  that  is  created  by  the 
MakeVPort(  )  and  MrgCop(  )  routines; 
Figure  2  illustrates  the  display  gener¬ 
ated  by  this  program. 

While  the  View  is  the  structure  that 
the  Copper  uses,  the  corresponding 
structure  for  the  Blitter  is  the  RastPort. 
This  structure  contains  information  such 
as  where  the  bitmap  data  can  be  found, 
what  logical  operation  the  Blitter  will 
perform,  what  pattern  to  use  for  pat¬ 
terned  lines,  and  what  font  to  use.  The 
graphics  library  takes  this  information 


(along  with  the  requested  operation) 
and  determines  the  values  needed  to 
execute  the  operation.  The  library  also 
acquires  the  Blitter’s  semaphore  and 
performs  the  function.  Once  the  Blitter 
has  been  started  the  library  returns  im¬ 
mediately.  Control  can  return  to  the 
current  program  or  any  other  program 
that  needs  the  CPU  while  the  Blitter  is 
drawing. 

To  demonstrate  the  accelerating  ef¬ 
fect  of  letting  the  Blitter  draw  the  lines 
instead  of  the  CPU,  I  wrote  a  simple 
benchmark  called  blit.c  (Listing  Three, 
page  90).  When  compiled  without 
WAIT_BL  IT  defined,  the  graphics  li¬ 
brary  will  start  a  line  draw  and  then 
return  to  allow  the  CPU  to  compute  the 
next  endpoint  while  the  Blitter  is  draw¬ 
ing.  With  WAIT__BL  IT  defined,  the  pro¬ 
gram  is  forced  to  wait  for  the  Blitter  to 
complete  each  line  before  beginning 
the  calculations  for  a  new  line.  The 
results?  About  a  12  percent  difference 
in  speed.  (Your  mileage  may  vary,  of 
course.) 

Conclusions 

The  Amiga  integrates  the  use  of  graph¬ 
ics  coprocessors  at  all  levels  of  its  op¬ 
eration.  The  results  are  a  noticeably 
faster  response  time  to  user  requests, 
especially  in  window  operations.  Bv 
using  those  coprocessors  efficiently,  the 
Amiga  can  do  such  things  as  display 
animations  while  playing  a  soundtrack. 
In  fact,  some  of  the  applications  that 
were  pioneered  on  the  Amiga  (desk¬ 
top  video  production,  for  example)  have 
only  recently  showed  up  on  some  of 
the  newer  32-bit  machines  (the  Macin¬ 
tosh  II  and  80386-based  MS-DOS  PCs) 
and  are  not  available  at  all  with  the 
current  set  of  8-  or  16-bit  processor- 
based  machines.  The  conclusion  I  draw 
from  this  is  that  for  high-performance 
graphics  applications,  the  implementa¬ 
tion  of  coprocessors  and  a  multitasking 
OS  puts  the  Amiga  into  the  perform¬ 
ance  range  of  the  32-bit  machines,  yet 
at  the  price  of  a  1 6-bit  machine. 

Availability 

All  source  code  for  articles  in  this  issue 
is  available  on  a  single  disk.  To  order, 
send  $14.95  (Calif,  residents  add  sales 
tax)  to  Dr.  Dobb's Journal ,  501  Galves¬ 
ton  Dr.,  Redwood  City,  CA  94063;  or 
call  800-356-2002  (from  inside  Calif.) 
or  800-533-4372  (from  outside  Calif.). 
Please  specify  the  issue  number. 
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Figure  2:  A  display  generated  by  the  Copper  List  program 
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Computer  scientists  and  users 
have  been  jealous  of  photogra¬ 
phers,  movie  makers,  and  tele¬ 
vision  producers  for  some  years 
because  computer  mono¬ 
chrome  images,  or  even  ones  with  256 
colors,  just  didn’t  compare  with  photo- 
graphic-quality  (true  color)  images.  Con¬ 
sequently,  computer  users  have  been 
forced  to  use  cartoon-like  animation 
and  imaging.  This  may  have  been  suffi¬ 
cient  for  adventure  games,  spreadsheets, 
and  low-end  word-processing  pro¬ 
grams,  but  it  just  wasn’t  good  enough 
for  image  processing  and  photogra¬ 
phy.  In  short,  without  true  color  capa¬ 
bilities,  the  dream  of  advanced  appli¬ 
cations,  such  as  on-line  encyclopedias 
that  provide  images  and  movie  clips, 
will  never  materialize. 

In  this  article  I’ll  discuss  some  basic 
functions  of  image  processing  and  dem¬ 
onstrate  one  possible  implementation 
of  arithmetic  functions  through  logical 
operations.  Then  I  will  use  these  arith¬ 
metic  functions  to  combine  and  en¬ 
hance  images. 

Imaging  and  Photography 

When  we  use  a  camera  to  take  a  pic¬ 
ture,  the  light  reflected  from  an  object 
passes  through  a  reducing  lens  and 
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exposes  the  film.  We  take  this  film  to  a 
photo  lab  which,  using  a  series  of  chemi¬ 
cal  processing  steps,  develops  the  film. 
Next,  photographic  paper  is  exposed 
by  shining  light  through  the  developed 
film  and  an  enlarging  lens.  Chemical 
processing  is  then  used  again  to  de¬ 
velop  the  photograph. 

In  the  electronic  version  of  photo¬ 
graphy,  we  can  use  an  electronic  “cam¬ 
era”  connected  to  image-capture  (frame 
grabber)  hardware  to  take  a  picture, 
and  we  can  use  a  color  printer  to  get  a 
paper  copy  of  the  picture.  In  this  pro¬ 
cess,  the  electronic  camera  serves  as  a 
reducing  lens  and  organizes  the  light 
intensity  and  color  information,  reflected 
from  an  object,  into  a  serial  stream.  The 
image  capture  hardware  converts  this 
stream  into  numbers,  which  are  then 
stored  in  the  computer’s  memory.  A 
monitor  or  a  printer  serves  as  an  en¬ 
larging  lens,  and  some  form  of  mag¬ 
netic  memory  medium,  such  as  disk 
or  tape,  is  used  to  store  the  captured 
image  for  later  recall. 

But  a  computer  is  much  more  than 
a  mere  storage  medium.  It  can  also  be 


used  as  a  processing  lab  because,  once 
an  image  has  been  captured  and  stored 
as  numbers,  that  image  can  be  enhanced 
or  changed  using  mathematical  manipu¬ 
lations  to  achieve  some  of  the  same 
tricks  of  the  trade  photographers  have 
used  for  years.  These  techniques  in¬ 
clude  the  use  of  filters  to  get  rid  of 
glare,  create  special  effects,  or  enrich 
certain  colors.  Other  techniques  include 
the  use  of  black  and  white  to  create  a 
mood,  the  use  of  zoom  lenses  to  cap¬ 
ture  only  the  interesting  sections  of 
images,  and  the  use  of  double  expo¬ 
sure  to  superimpose  several  images. 
What’s  significant  is  that  each  of  these 
techniques  can  be  accomplished  mathe¬ 
matically,  rather  than  chemically. 

Logical  Operations 

Graphics  and  image  manipulations  have 
traditionally  been  limited  to  logical 
(Boolean)  operations  —  XOR,  NOT, 
OR,  AND,  and  so  on  —  mostly  because 
of  inexperience,  simplicity,  and  the  domi¬ 
nance  of  monochrome  hardware.  Be¬ 
cause  our  goal  is  to  modify  an  image 
or  combine  two  images,  we  must  un¬ 
derstand  fully  how  picture  elements 
(pixels)  can  be  manipulated  or  com¬ 
bined.  The  simplest  case  is  monochrome 
graphics,  1  bit  per  pixel,  where  1  bit  in 
memory  corresponds  to  1  dot  on  the 
screen. 

A  single  memory  bit  can  hold  only 
two  possible  values  —  0  or  1.  These 
two  values  constitute  a  binary  (Boolean) 
set.  Two  bits  can  be  combined  in  only 
4  possible  ways  to  produce  a  single  bit 
(see  Table  1).  The  process  of  combin¬ 
ing  2  bits  to  generate  a  single  bit  is 
called  a  logical  operation.  There  are 
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(continued  from  page  45) 

16  possible  logical  operations  (see  Ta¬ 
ble  2).  Logical  operations  always  pro¬ 
duce  a  result  that  is  of  the  same  length 
as  the  original  elements.  In  other  words, 
if  two  1-bit  elements  are  combined,  the 
result  is  always  1  bit  long. 

Many  graphics  software  packages  al¬ 
low  programmers  to  set  a  “logical  op¬ 
eration  attribute”  and  then  draw  in  that 
mode.  This  means  that  in  XOR  mode, 
as  a  white  line  is  drawn  over  an  image, 
all  the  bits  along  the  path  of  that  line 
are  reversed.  This  is  a  useful  technique 
for  cursors  and  is  used  in  many  CAD 
packages. 

In  the  monochrome  world,  we  can 
emulate  arithmetic  operations  with  logic 
operations.  If  you  look  at  the  AND 
operation  you  can  quickly  recognize  a 
multiply,  and  the  OR  is  an  add  with 
saturate  (explained  later).  At  1  bit  per 
pixel,  logical  operations  do  the  job  per¬ 
fectly.  For  larger  pixel  depths  (multiple 
bits  per  pixel),  however,  logical  opera¬ 
tions  can  no  longer  serve  as  substitutes 
for  actual  arithmetic  operations. 

Arithmetic  Operations  and  Saturation 

Arithmetic  operations  on  two  operands 
have  a  nasty  habit  of  producing  a  result 
of  length  unequal  to  the  length  of  either 
operand.  Maybe  that  is  the  reason  why 
we  make  a  distinction  between  logical 
and  arithmetic  operations.  In  the  case 
of  addition,  if  the  first  operand  is  Ambits 
long  and  the  second  is  Mbits  long,  the 
result  can  be  up  to  ( max(N \  M)  +  1) 
bits.  For  example,  when  we  add  the 
binary  numbers  1  and  1  the  result  is  10. 
In  other  words,  for  addition  we  may 
require  one  more  bit  than  the  longest 
of  the  two  operands  to  store  the  result. 
Some  textbooks  call  the  generation  of 
this  extra  bit  a  “carryout”  or  an  over¬ 
flow  condition.  Multiplication  is  even 
worse  —  we  require  up  to  (7V+  M)  bits 
to  store  the  result.  For  example,  multi¬ 
plying  binary  11  (decimal  3)  by  11  (3) 
results  in  1001  (9),  which  requires  4  bits 
of  storage. 

By  this  time  you  are  probably  won¬ 
dering  why  we  are  going  through  this 
nonsense.  Well,  the  reason  is,  if  we 
add  two  pixels  that  are  each  8  bits  long 
and  get  a  9-bit  result,  how  do  we  dis¬ 
play  this  result?  If  we  have  only  8-bit 
numbers,  how  do  we  represent  a  9-bit 
number? 

The  fact  that  the  result  uses  more  bits 
than  either  of  the  operands  is  irritating 
even  in  microprocessors.  It  is  not  plea¬ 
sant  to  get  a  33-bit  result  when  adding 
two  32-bit  numbers.  How  do  you  put 
the  result  back  into  a  32-bit  register? 
Most  microprocessors  don’t  have  a  “crow¬ 
bar”  instruction.  And  how  do  you  deal 
with  the  result  of  multiplication? 


The  microprocessor  world  has  come 
up  with  a  simple  solution  —  let  the 
software  deal  with  it!  So  most  micro¬ 
processors  just  inform  the  software  that 
an  overflow  condition  has  occurred  by 
raising  a  flag.  The  software  must  then 
look  at  the  flag  and  do  something  about 
the  overflow.  In  the  case  of  multiplica¬ 
tion,  the  microprocessor  simply  stores 
the  result  in  two  registers  and,  once 
again,  leaves  it  to  the  software  to  figure 
out  how  to  fit  the  result,  which  now 
occupies  twice  as  many  bits,  into  a 
single  register. 

Most  programmers  don’t  concern 
themselves  with  overflow  conditions. 
If  they  have  even  a  small  inkling  that  a 
data  type  might  encounter  an  overflow 
condition,  they  simply  go  to  the  next 
larger  data  type.  For  example,  if  there 
was  a  possibility  that  an  array  would 
grow  beyond  64K  elements,  a  long( 32- 
bit)  data  type  would  simply  be  used  for 
the  array  index.  The  only  reasonable 
aid  that  most  high-level-language  com¬ 
pilers  give  us  is  that  if  two  operands 
of  different  size  are  being  combined, 
the  result  is  of  the  larger  size.  (I  hope 
this  is  sufficient  warning  to  computer 
scientists  to  make  sure  that  results  don’t 
overflow.) 

But  what  are  graphics  programmers 
to  do  when  they’ve  got  only  a  single 
data  type  that  we’ll  call  pixel.  They 
have  no  other  data  types  to  fall  back 
on.  The  result  must  fit  into  the  pixel 
data  type,  and  the  resulting  display  must 
make  sense  (the  greens  are  not  allowed 
to  spill  over  into  the  reds  and  so  on). 

The  solution  is  actually  quite  simple. 
We  represent  all  pixels  that  take  more 
bits  to  represent  than  the  pixel  data 
type  can  hold  by  the  largest  number 
that  a  pixel  data  type  will  hold.  For 
example,  suppose  we  have  a  24-bit-per- 
pixel  system  in  which  three  primary 
colors  (red,  green,  and  blue)  are  used 
to  make  up  each  pixel,  and  we  use  8 
bits  for  red,  8  bits  for  green,  and  8  bits 
for  blue.  Any  intensities  of  blue  that 
take  more  than  8  bits  to  represent  are 
represented  by  the  largest  value  that 
does  fit  into  8  bits  (255  decimal).  In 
other  words,  when  adding  two  pixels, 
if  the  blues  are  added  together  and  the 


result  is  greater  than  255,  then  the  re¬ 
sult  is  forced  to  be  equal  to  255.  Some 
books  call  this  technique  saturation. 
The  key  point  is  that  the  resultant  color 
is  always  brighter  (or  of  equal  bright¬ 
ness)  than  either  of  the  operand  pixels. 
If  saturation  isn’t  used,  it  is  possible  for 
the  resultant  pixel  to  be  dimmer  than 
either  of  the  operand  pixels  —  and  this 
makes  no  visual  sense. 

For  subtraction,  the  result  is  never 
allowed  to  go  negative.  If  subtraction 
of  two  pixels  results  in  a  negative  num¬ 
ber,  the  resultant  pixel  is  forced  equal 
to  zero.  This  is  called  starvation.  Thus, 
the  resultant  color  for  subtraction  is 
always  dimmer  (or  of  equal  brightness) 
than  the  brightest  operand  pixel.  Multi¬ 
plication  is  handled  in  the  same  way 
as  addition,  and  division  doesn’t  cause 
problems  (except  for  generating  a  non¬ 
integer  result). 

The  code  for  this  technique  is  simple 
and  is  shown  in  Listing  One,  page  92. 
Note  that  8-bit  color  values  are  first 
promoted  to  the  16-bit  integer  data  type 
and  then  added  together  to  ensure  no 
overflow.  The  resultant  pixel  value  is 
then  saturated,  as  discussed  earlier. 

A  more  mathematically  philosophi¬ 
cal  explanation  might  be  that  unsigned 
integer  arithmetic  must  be  used  and 
the  following  rules  obeyed: 

1.  When  adding  two  numbers,  the  re¬ 
sult  must  always  be  greater  than  or 
equal  to  either  operand,  but  less  than 
or  equal  to  the  maximum  possible  value. 

2.  When  subtracting  two  numbers,  the 
result  must  always  be  less  than  or  equal 
to  the  first  operand,  but  greater  than 
or  equal  to  zero. 

3.  When  multiplying  by  other  than  zero, 
the  result  must  always  be  greater  than 
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Table  2:  16 possible  logical  operations 
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or  equal  to  either  operand,  but  less 
than  or  equal  to  the  maximum  possible 
value. 

Bit  Block  Transfer 

A  Bit  Block  Transfer,  referred  to  as 
Bit_blt,  is  probably  the  most  useful  gra¬ 
phical  operation.  It  is  used  to  move  a 
rectangular  block  of  pixels  from  one 
position  within  an  image  to  another 
position  but  is  really  nothing  more  than 
a  fancy  DMA  (direct  memory  access). 
Bit_blt  is  a  bit  trickier  than  a  DMA  on 
two  counts,  however: 

1.  DMA  treats  memory  as  linear,  one¬ 
dimensional  space  and  moves  contigu¬ 
ous  memory  regions.  Bit_blt treats  mem¬ 
ory  as  a  two-dimensional  array  and 
moves  an  arbitrary-size  rectangle  from 
one  spot  to  another. 

2.  DMA  always  treats  memory  as  a  lin¬ 
ear  array  of  bytes,  words,  or  other  byte- 
divisible  elements.  Bit_blt  treats  mem¬ 
ory  as  a  two-dimensional  array  of  pix¬ 
els,  usually  of  1,  2,  4,  8,  16,  24,  32,  or 
even  48  bits  in  size.  This  implies  that 
Bit_blt  handles  boundary  conditions 
very  carefully,  as  it  may  need  to  modify 
a  part  of  a  byte  or  a  word  because  sev¬ 
eral  pixels  may  fit  into  a  byte  or  a  word. 


Bit_blt  is  used  extensively  for  scroll¬ 
ing  and  windowing  because  it  is  effi¬ 
cient  at  handling  rectangular  regions 
of  pixels. 

After  a  while,  merely  moving  pixels 
from  one  place  in  the  image  to  another 

By  adding  two 
images  together  —  with 
saturation  —  a 
double-exposure  effect 
is  created 


becomes  dreadfully  boring.  So,  graph¬ 
ics  programmers  decided  to  make 
Bitfblt  perform  logical  operations  as  it 
moves  pixels  of  a  rectangular  area.  For 
example,  an  XOR  Bit_blt  would  move 
a  rectangular  region  of  pixels  from  one 
location,  called  the  source,  to  another, 
called  the  destination.  As  it  moves  each 
pixel,  fift_W/would  read  both  the  source 


and  the  destination  pixel  and  combine 
every  bit  of  the  two  pixels  using  an 
XOR  logical  operation.  The  result  would 
be  placed  in  the  destination  pixel.  This 
would  be  done  on  all  pixels  of  the 
source  and  destination  rectangle.  Ob¬ 
viously,  the  source  and  the  destination 
have  to  be  of  the  same  size  for  this  to 
work  properly.  In  any  case,  with  an 
XOR  logical  operation,  the  result  is  more 
exhilarating  than  a  mere  movement  of 
a  rectangular  region. 

Because  a  Bit_blt  operation  is  a  popu¬ 
lar  way  of  manipulating  bit-map  graph¬ 
ics,  many  graphics  processors  and  copro¬ 
cessors  handle  it  with  great  efficiency, 
moving  pixels  at  rates  of  millions  per 
second.  But,  because  most  graphics 
programmers  are  satisfied  with  logical 
operations,  most  devices  limit  their  rep¬ 
ertoire  to  logical  operations  only. 

Being  able  to  manipulate  images  with 
only  logical  operations  is  fine  for  win¬ 
dowing  and  scrolling  but  is  not  enough 
for  image  processing  and  photogra¬ 
phy.  Somehow,  we  must  get  from  logi¬ 
cal  operations  to  arithmetic  operations. 

From  Logic  to  Arithmetic 

The  techniques  for  combining  logic  op¬ 
erations  to  make  other  useful  functions 
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(continued  from  page  48) 
are  well-established  in  the  field  of  logic 
design.  It  is,  for  instance,  possible  to 
combine  logic  operations/gates  to  make 
arithmetic  functions.  A  typical  adder 
logic  circuit  is  shown  in  Figure  1.  This 
circuit,  called  a  full  adder,  adds  two 
bits  and  a  carryout  from  the  addition 
of  the  lower  bits.  Several  single-bit  ad¬ 
ders  can  be  configured  together  to  make 
a  multiple-bit  adder;  Figure  2  shows 
an  8-bit  adder  configuration.  Other  use¬ 
ful  circuits,  such  as  a  full  subtracter  and 
a  half  adder,  are  shown  in  Figures  3 
and  Figure  4.  Several  full  subtracters 
can  be  cascaded  together  to  form  an 
8-,  16-,  or  even  32-bit  subtracter  circuit. 

A  modified  version  of  the  full  adder 
logic  circuit  is  shown  in  Figure  5.  Note 
the  subtle  difference  of  using  the  sum 
to  generate  the  carryout.  The  advan¬ 
tage  of  this  algorithm/circuit  is  that  it 
is  tuned  toward  serial  implementation, 
which  means  that  it  can  be  implemented 
in  software  more  readily.  The  algorithm 
uses  fewer  intermediate  results  (in  fact, 
it  uses  only  one),  as  this  is  very  costly 
in  graphics.  For  example,  a  single 
640  x  480  image,  at  24  bits/pixel  occu¬ 
pies  approximately  1  Mbyte  of  mem¬ 
ory.  Every  intermediate  result  of  an 


operation  also  takes  1  Mbyte  of  mem¬ 
ory,  so  it  is  costly  to  have  intermediate 
results.  And,  if  your  hardware  has  only 
3  Mbytes  total,  you  are  limited  to  one 
temporary  variable  when  combining 
two  640  x  480  images.  You  could  break 
the  image  up  into  smaller  pieces, 
thereby  reducing  the  amount  of  needed 
temporary  storage,  but  this  complicates 
things  and  makes  them  less  efficient. 

In  any  case,  the  main  message  is  that 
it  is  possible  to  combine  logic  opera¬ 
tions  in  some  fashion  to  come  up  with 
arithmetic  functions.  It  is  not  necessary 
to  use  standard  algorithms.  You  can 
modify  these  algorithms  to  tune  them 
for  a  specific  application,  to  squeeze 
more  performance  out  of  them. 


Figure  1:  A  typical  adder  logic  circuit 


Putting  the  Functions  to  Work 

Now  that  we  have  these  functions,  how 
can  we  use  them  to  perform  simple 
image-processing  and  photography 
tasks?  Simple!  By  adding  two  images 
together,  with  saturation,  a  double  ex¬ 
posure  effect  is  created.  Another  tech¬ 
nique  might  be  to  make  color  adjust¬ 
ments  by  setting  the  second  image  to 
a  constant  color  and  then  adding  or 
subtracting  it  to/from  the  first  image. 
You  can  create  the  effect  of  under¬ 
exposure  by  subtracting  some  constant 
value  from  all  reds,  greens,  and  blues, 
which  will  make  an  image  appear  darker 
or  underexposed.  For  overexposure, 
just  add  a  constant  value. 

Subtraction  of  two  images  can  be 
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(continued  from  page  50) 
useful  for  data  compression.  For  exam¬ 
ple,  when  compressing  a  movie,  frame- 
to-frame  differences  are  quite  small  most 
of  the  time.  Thus,  if  you  compress  only 
the  differences  between  the  frames,  you 
will  avoid  compressing  the  data  that 
has  not  changed.  Of  course,  you  can 
do  just  about  anything  by  directly  ma¬ 
nipulating  the  image  in  the  graphics 
memory  (bit  map). 

Benchmarks 

By  now  you  are  probably  wondering 
why  we  are  going  through  so  much 
pain.  The  reason  is  performance!  Be¬ 
cause  Bitfblt  with  logical  operations  is 
available,  why  not  use  it?  All  we  have 
to  do  is  combine  several  Bit_blts  with 
different  logic  operations  to  give  us  an 
arithmetic  function.  Of  course,  we  could 
also  write  our  own  Bit_blt  routine  that 
would  perform  arithmetic.  But,  you  shall 
see  that  this  is  not  as  efficient,  even 
when  using  a  20-MHz  80386. 

I  used  a  20-MHz  80386  IDR  PC  AT 
for  software  development  and  bench¬ 
marking.  I  also  used  Digihurst  image- 
capture  and  display-board,  along  with 
a  Sony  Multiscan  monitor.  The  Digihurst 
board  is  a  true  color  (24  bits/pixel) 
graphics  board  capable  of  image  cap¬ 
ture  from  an  NTSC  source  (TV).  You 
can  hook  it  up  to  a  VCR,  watch  a  movie 
on  the  monitor,  and  capture  any  frame. 
This  board  uses  three  Intel  82786  graph¬ 
ics  coprocessors,  one  for  each  primary 
color.  The  board  also  has  3  Mbytes  of 
graphics  memory  —  1  Mbyte  for  each 
color  —  and  is  capable  of  storing  three 
full  images.  After  the  images  have  been 
captured,  they  can  be  stored  on  disk. 

The  implementation  of  the  modified 
ADDer  algorithm  is  shown  in  Listing 


Two,  page  92.  As  you  can  see,  it  is 
nothing  more  than  a  series  of  logical 
Bit_blts  ( cmd_copy_image  procedure 
calls),  in  the  order  specified  in  Figure 
5.  The  cmd_copy_image  and  cmd_wm_ 
copy-  image  procedures  are  actually  di¬ 
rect  Intel  82786  Bit_blt  commands  (given 
to  all  three  82786s  simultaneously). 

Performance  benchmarks  were  done 
on  two  preloaded  640  x  480  true  color 
(24  bits/pixel)  images  using  the  code 
shown  in  Listing  One.  The  results  are 
shown  in  Table  3.  The  80386  program 
was  written  in  C  (see  Listing  One)  and 
used  pointers  and  registers  wherever 
possible.  The  Digihurst  board  ran  the 
82786s  at  12.5MHz,  which  is  below  the 
(continued  on  page  55) 
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Figure  2:  An  8-bit  adder  configuration 


Figure  3:  A  full  subtracter  circuit 
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(continued  from  page  52) 

20-MHz  top-speed  specification.  Run¬ 
ning  the  82786s  at  20MHz  will  double 
the  performance,  which  will  result  in 
close  to  a  5:1  performance  ratio. 

Conclusions 

The  benchmarks,  as  usual,  don’t  tell 
the  whole  story.  The  80386  performed 
poorly  mainly  because  of  graphics  mem¬ 
ory  bandwidth  limitations.  In  a  PC  AT, 
the  graphics  board  connects  to  the  80386 
through  the  PC  AT  bus,  which  runs  at 
10MHz  at  best  and  is  only  16  bits  wide. 
Thus,  the  PC  AT  bus  presents  a  bottle¬ 
neck  to  a  20-MHz  80386.  The  82786 
accesses  graphics  memory  directly,  with¬ 
out  bottlenecks,  plus  DRAM  tricks  such 
as  “page  mode”  accesses  are  used  to 
improve  graphics  memory  bandwidth 
even  further.  The  82786  graphics  mem¬ 
ory  bandwidth  peaks  at  40  Mbytes/sec. 

Using  a  graphics  coprocessor  can 
have  many  other  benefits.  Because  the 
graphics  coprocessor  possesses  smarts, 
it  can  share  the  processing  load.  The 
key  here  is  parallelism.  While  the  graph¬ 
ics  coprocessor  is  performing  a  task, 
the  CPU  can  be  doing  something  else 
in  parallel.  This  is  not  possible  with 
pure  display  devices  such  as  VGA,  EGA, 
CGA,  and  so  on,  where  the  CPU  must  do 
all  the  work.  This  leads  me  to  the  con¬ 
clusion  that  even  if  the  algorithm  runs 
slower  on  the  coprocessor,  it  may  still 
be  advantageous  to  use  the  coprocessor 
for  that  task  because  of  parallelism. 

In  any  case,  the  algorithm  discussed 
here  used  logical  operations  to  per¬ 
form  simple  arithmetic  functions  that 
can  be  used  to  add  and  subtract  ima¬ 
ges  with  and  without  saturation.  The 
performance  of  these  functions  exe¬ 
cuted  by  graphics  coprocessors  was 
dramatically  superior  to  that  of  the  CPU. 
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Figure  5:  A  modified  version  of  the  full  adder  logic  circuit 


80386 

82786 

Ratio 

Addition 

10.7  sec. 

4.4  sec. 

2.4:1 

Subtraction 

10.7  sec. 

4.4  sec. 

2.4:1 

Addition 

(with  saturation) 

12.7  sec. 

5.5  sec. 

2.3:1 

Subtraction 

(with  starvation) 

12.7  sec. 

5.5  sec. 

2.3:1 

Table  3:  Performance  results 
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Turbo  Pascal 

with  Objects 


Combining  the  OOP  approach  with  structured  concepts 
seems  only  natural 


If  artificial  intelligence  was  the 
buzzword  for  the  mid-1980s,  then 
its  equivalent  for  the  late  1980s 
(and  early  1990s)  must  be  object- 
oriented  programming  (OOP).  But 
instead  of  the  distant  promises  offered 
by  AI,  OOP  represents  a  superior  meth¬ 
od  for  the  design  and  construction  of 
today’s  software. 

Because  OOP’s  approach  encourages 
good  programming  practices  that  com¬ 
plement  structured  programming,  com¬ 
bining  Pascal  and  OOP  seems  a  natural 
evolutionary  step,  one  that  Borland  has 
taken  with  its  most  recent  release  of 
Turbo  Pascal.  In  this  article,  I’ll  explore 
the  major  features  that  have  been  added 
to  Turbo  Pascal  (TP)  5.5,  including  ob¬ 
ject-oriented  extensions  to  the  language 
and  to  the  debugger.  We’ll  also  examine 
TP’s  overlay  manager  and  take  a  look  at 
the  new  capabilities  of  the  Smart  Lin¬ 
ker.  Finally,  we’ll  provide  a  full-blown 
example  that  demonstrates  most  of  TP 
5.5’s  object-oriented  features. 

Language  Overview 

Turbo  Pascal  has  added  only  four  new 
keywords  to  the  language  set:  object, 
virtual,  constructor,  and  destructor.  With 
these  four  keywords,  you  can  declare 
objects  statically  within  your  program 
or  create  them  dynamically  at  run  time. 
These  objects  can  inherit  code  and  data 
from  a  parent  (or  ancestor)  object  type, 
and  you  can  override  any  inherited  meth¬ 
od.  Constructors  and  destructors  pro¬ 
vide  automated  initialization  and  cleanup 
of  objects.  In  addition,  constructors  and 
destructors  can  be  used  in  conjunction 
with  the  expanded  New  and  Dispose 
procedures  to  allocate  and  deallocate 
heap  storage  for  dynamic  objects. 
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Michael  Floyd 

TP  5.5  supports  the  notion  of  virtual 
methods  (as  does  C++).  Virtual  meth¬ 
ods  allow  you  to  implement  polymor¬ 
phism.  Both  TP’s  Integrated  Debugger 
and  Turbo  Debugger  1.5  provide  object 
support.  Additionally,  as  previously  men¬ 
tioned,  enhancements  have  been  made 
to  TP's  overlay  manager  and  the  Smart 
Linker  and  improvements  have  been 
made  to  speed  up  the  compiler. 

Syntax 

In  Turbo  Pascal,  objects  can  be  thought 


Example  3:  Code-fragment  to 
create  specialized  windows 


of  as  records  that  have  the  ability  to 
inherit  code  and  data  from  ancestor 
object  types.  The  generalized  form  for 
an  object  definition  is  shown  in  Exam¬ 
ple  1.  Defining  an  object  is  similar  to 
defining  a  record.  The  object  keyword 
replaces  the  record  keyword,  and  ob¬ 
ject  takes  an  optional  argument  —  the 
ancestor  that  this  new  object  will  in¬ 
herit  from. 

Methods  in  TP  are  simply  procedure 
and  function  headers  placed  directly 
(continued  on  page  60) 


Example  4:  The  DrawWindow 
method  for  the  Window  object 


type 

Ob jectName  =  object (Ancestor) 
variable  definitions; 
method  definitions;  (virtual) 
end; 


Example  1:  The  general  form  for  an  object  definition 

type 

Window  =  object 

WindowNo:  Integer; 

XI,  Yl,  X2,  Y2 :  Integer; 

constructor  Init (XA,  YA,  XB,  YB:  Integer); 
destructor  Done;  virtual; 
procedure  Show;  virtual; 
procedure  Hide;  virtual; 

end; 

Example  2:  Code  for  a  basic  window  object 


type 

MenuList  -  string[80]; 

MenuBar  =  object (Window) 

Menus:  MenuList; 

constructor  InitfM:  MenuList); 
procedure  Show;  virtual; 
procedure  Hide;  virtual; 
procedure  Highlight (Item:  Integer); 
procedure  Select (Item:  Integer) ; 

end; 

PullDown  =  object (Window) 
end; 


procedure  Window. Show; 
begin 

{  Draw  the  window  } 
end; 
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(continued  from  page  56) 
in  the  object  definition.  The  virtual 
keyword  (which  is  optional)  is  used  to 
define  a  virtual  method.  Methods  not 
using  the  virtual  keyword  are  static 
methods. 

As  an  example,  consider  a  window¬ 
ing  environment  that  contains  a  menu 
bar,  pull-down  menus  and  a  text 
window  that,  in  turn,  contains  other 
windows  such  as  scroll  bars  and 
resize  boxes.  Window  systems  are  a 
natural  for  an  object-oriented  pro¬ 


gramming  approach. 

First,  let’s  create  the  basic  window 
object  type  like  that  coded  in  Example 
2.  From  this  basic  window,  we  can 
create  an  object  hierarchy  of  more  spe¬ 
cialized  windows  like  the  MenuBar  and 
PullDown  object  types  shown  in  Ex¬ 
ample  3. 

Notice  that  MenuBar  inherits  three 
virtual  methods  (Done,  Show,  and  Hide) 
and  then  adds  two  static  methods  (High¬ 
light  and  Select).  Also  notice  that  the 
constructors  for  each  of  these  object 


types  are  different  as  well.  Each  method 
is  like  a  forward  declared  procedure 
that  must  be  defined  in  the  same  unit 
or  program  module.  The  syntax  for 
defining  a  method  is  ObjectType. Method 
and  is  illustrated  in  Example  4. 

You  invoke  an  object’s  method  in 
the  same  manner  that  you  would  refer¬ 
ence  the  fields  of  a  record  using  the 
familiar  dot  syntax.  Refer  to  Example  4 
for  an  example  of  how  to  call  the  Win¬ 
dow  object’s  Show  method. 

TP  objects  are  just  like  any  other 
variable  —  they  can  be  declared  stati¬ 
cally  in  a  VAR  declaration  or  dynami¬ 
cally  allocated  on  the  heap  and  refer¬ 
enced  via  pointers. 

I’ve  left  out  a  lot  of  the  details  in  this 
example  so  that  you  can  easily  see  the 
overall  structure  and  calling  sequence. 
I’ve  also  provided  an  example  program 
that  highlights  the  creation  and  use  of 
objects  in  TP  5.5.  FDEMO.PAS  (see  List¬ 
ing  One,  page  95)  implements  a  simple 
forms  editor. 

The  fact  that  objects  can  be  used 
across  units  is  important,  particularly 
as  you  begin  developing  your  own  li¬ 
braries.  Therefore,  the  example  con¬ 
sists  of  two  units  and  a  main.  FDEMO, 
as  previously  mentioned,  contains  the 
main  program.  FORMS. PAS  (see  List¬ 
ing  Two,  page  95)  is  a  unit  that  imple¬ 
ments  a  Form  object  and  its  associated 
Fields,  and  SLIDERS. PAS  (see  Listing 
Three,  page  97)  adds  a  graphic  counter 
feature. 

Because  of  space  considerations,  I 
won’t  go  into  detail  on  the  example. 
You  should,  however,  find  the  forms 
demo  instructive  as  you  read  through 
the  next  section. 

Virtual  Methods 

There  are  two  required  features  for  any 
object-oriented  programming  language 
and  TP  5.5  has  both.  The  first,  which 
you’ve  already  seen,  is  inheritance.  The 
other  is  support  for  late  binding  of 
virtual  methods  and  polymorphism. 

From  an  implementation  standpoint, 
the  major  difference  between  static  and 
virtual  methods  is  simple  when  they 
are  bound:  A  static  method  call  is  just 
a  special  procedure  call  that  can  be 
resolved  at  compile-time  for  maximum 
efficiency  (early  binding). 

A  virtual  method  call,  on  the  other 
hand,  requires  a  table  lookup  based 
on  the  RUN-TIME  identity  of  the  ob¬ 
ject.  This  table  lookup  gives  an  object 
the  ability  to  respond  appropriately  to 
a  requested  action  (late  binding). 

To  illustrate  this  important  idea,  con¬ 
sider  an  example  where  a  linked  list 
of  windows  can  contain  either  menu 
windows  or  text  windows.  This  allows 
a  display  routine  to  traverse  the  linked 


File  View  Rue  Breakpoints  Bate  Hindoo  Options’ 

Hndu  Is !  FGW  Ft  le:  ‘  C  i'vAHT  ICLESST P55\FGRNS .  PRS  B - — 

FStrinsftr  =  'FStrirq; 
fftoBf  *  string (791; 


FteldPtr  =  AFieid; 

Field  •  deject 
Next:  FieldPtr; 

X,  V,  Size:  Integer; 

Title:  FStringPtr: 

Value:  Pointer; 

constructor  init(PX,  PV,  PSize:  Integer,'  PTitle:  FString); 
I 


Figure  1:  Viewing  the  Field  object  in  the  hierarchy  browser 


Figure  2:  Viewing  the  Field  object  type  in  the  Object  Type  Inspector 
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list  and  send  a  “display  message”  to 
each  window: 

NextWin  :=  Head; 
while  NextWin  <  >  nil  do 
begin 

NextWin^. Show; 

NextWin  :=  NextWinA.Next; 
end; 

To  resolve  a  virtual  method  call  at  run¬ 
time,  TP  creates  one  Virtual  Method 
Table  (VMT)  in  the  data  segment  for 
each  object  type.  The  VMT  contains 
the  size  of  an  object  type,  and  a  pointer 
to  the  code  of  each  of  the  methods  for 
that  object.  An  instance  of  an  object  is 
linked  to  the  VMT  through  a  construc¬ 
tor  call. 

Defining  a  method  as  virtual  is  a 
simple  matter  of  appending  the  virtual 
keyword  to  the  method’s  header.  How¬ 
ever,  there  are  a  few  rules  to  keep  in 
mind. 

If  you  declare  a  method  as  virtual 
in  an  ancestor  type,  you  must  also  de¬ 
clare  any  overriding  methods  as  vir¬ 
tual.  In  addition,  the  parameters  for 
overriding  methods  must  be  exactly 
the  same,  including  the  number  of  pa¬ 
rameters  and  the  parameter  types.  This 
is  different  than  the  case  for  static  meth¬ 
ods,  which  can  vary,  both  the  number 
of  parameters  and  the  parameter  type. 

Also,  as  mentioned  earlier,  each  in¬ 
stance  of  an  object  must  be  linked  to  its 
VMT  so  every  newly  instantiated  object 
must  be  initialized  by  a  constructor 
call.  Failure  to  make  the  constructor 
call  can  result  in  a  system  crash.  You 
can  detect  this  error  by  setting  the  $R  + 
compiler  directive.  This  compiler  direc¬ 
tive  provides  range  checking  for  all 
virtual  methods  called  in  your  program, 
and  issues  a  run-time  error  if  the  ob¬ 
ject’s  VMT  pointer  has  not  been  initial¬ 
ized. 

Objects  are  structured  types  that  gen¬ 
erally  require  some  initialization  be¬ 
fore  they  are  used  and  some  cleanup 
before  they  are  disposed  of.  A  typical 
sequence  of  instructions  would  be 

1 .  Allocate  an  object  on  the  heap 

2.  Call  its  “initialization’’method  and  pass 
in  relevant  parameters  for  storage  or 
computation  inside  the  object 

3.  Use  the  object  (repeat  until  done 
with  object) 

4.  Call  its  “cleanup”  method  to  close 
files,  release  any  dynamic  memory 
used  by  the  object,  and  so  on 

5.  Deallocate  the  object 

The  standard  procedures  New  and  Dis¬ 
pose  already  perform  the  first  and  last 
operations  described  above.  TP’s  new 
constructor  and  destructor  methods  are 
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intended  to  perform  steps  2  and  4  re¬ 
spectively.  Because  the  ordering  of  these 
steps  is  important.  New  has  been  ex¬ 
tended  to  take  a  constructor  method 
call  as  an  optional  second  parameter. 
Similarly,  Dispose  accepts  a  destructor 
method  call  as  a  second  parameter. 

Debugger  Support 

Turbo  Pascal  provides  support  for  de¬ 
bugging  objects  as  well.  The  integrated 
debugger,  for  instance,  allows  you  to 
either  step  over  or  trace  through  method 
calls.  Because  the  debugger  is  actually 
executing  the  code  in  your  program, 
there’s  no  difference  between  tracing 
a  static  or  virtual  method. 

The  Integrated  Debugger  allows  you 
to  view  objects  using  the  Evaluate  Win¬ 
dow.  You  can  view  just  the  object's 
data  fields  or  you  can  view  the  address 
of  the  method’s  code.  In  addition,  an 
object  can  be  added  to  the  Watch 
window.  In  both  the  Watch  and  the 
Evaluate  windows,  all  expressions  that 
are  valid  for  records  are  also  valid  for 
objects. 

Finally,  the  Integrated  Debugger  al¬ 
lows  you  to  enter  expressions  into  the 
Find  Procedure  command  (available 
from  the  Debug  menu).  A  legal  expres¬ 
sion  must  evaluate  to  an  address  in  the 
code  segment. 

The  stand-alone  debugger,  Turbo  De¬ 
bugger  (TD)  1.5,  has  everything  in  the 
Integrated  Debugger  plus  an  object  in¬ 
spector  (for  both  object  types  and  in¬ 
stances)  and  a  hierarchy  browser.  Again, 
there's  no  difference  between  tracing 
a  static  or  virtual  method  because  the 
debugger  is  actually  executing  the  code 
in  your  program.  This  brings  up  an¬ 
other  important  point.  Methods  can  be 
executed  from  within  the  Turbo  De¬ 
bugger  environment. 

The  best  way  to  get  a  feel  for  the 
objects  in  your  program  and  explore 
the  features  of  TD  1.5  at  the  same  time 
is  to  load  your  program  up  into  TD  and 
crank  up  the  hierarchy  browser.  The 
hierarchy  browser  brings  up  a  two- 
paned  window  that  displays  an  alpha¬ 
betical  list  of  objects  used  in  the  left 
pane,  and  the  ancestor/descendent  re¬ 
lationships  between  objects  in  the  right 
pane.  The  hierarchy  browser  is  shown 
in  Figure  1. 

The  hierarchy  browser  allows  you 
to  scroll  through  a  graphical  represen¬ 
tation  of  the  hierarchy  and  highlight 
object  types.  TD  also  provides  an  in¬ 
cremental  search  feature  that  allows 
you  to  quickly  locate  object  types  in  a 
complex  hierarchy.  Once  you've  high¬ 
lighted  an  object  type,  you  can  select 
it  by  pressing  Enter,  which  brings  up 
the  Object  Type  Inspector. 

The  Object  Type  Inspector  (see  Fig¬ 


ure  2)  is  also  a  two-paned  window  that 
displays  the  data  fields  of  an  object 
type  in  the  upper  pane  and  its  associ¬ 
ated  methods  in  the  lower  pane.  High¬ 
lighting  and  selecting  a  data  field  brings 
up  another  Object  Type  Inspector  for 
browsing  complex  or  nested  object  struc¬ 
tures.  Highlighting  and  selecting  a 
method,  on  the  other  hand,  brings  up 
a  Method  Inspector. 

This  Method  Inspector  displays  the 
method’s  code  address,  the  names  and 
types  of  the  method’s  parameters,  and 
whether  it  is  a  procedure  or  a  function. 
Pressing  Enter  anywhere  in  the  Method 
Inspector  takes  you  to  the  source  code 
for  that  method. 

TD  also  provides  an  Object  Instance 
Inspector  that  allows  you  to  examine 
the  data  of  object  instances.  The  Object 
Instance  Inspector,  which  is  similar  to 
the  record  inspector,  adds  a  new  fea¬ 
ture  that  displays  an  instance’s  meth¬ 
ods  along  with  their  associated  code 
addresses.  Of  course,  these  addresses 
take  polymorphic  objects  and  their  VMT 
into  account. 

Overlay  Manager 

One  of  the  more  interesting  parts  of 
TP  is  the  overlay  manager.  Until  now, 
the  internals  of  the  overlay  manager 
have  largely  been  undocumented.  TP’s 
optimized  Least  Recently  Used  (LRU) 
algorithm  provides  a  major  step  in  op¬ 
timizing  the  way  overlays  are  loaded 
into  memory.  Before  describing  this  new 
optimization,  however,  let  s  take  a  look 
at  how  TP  5.0’s  overlay  manager  works. 

When  an  overlay  is  called,  it  is  loaded 
into  a  section  of  memory  between  the 
stack  segment  and  the  heap  called  the 
overlay  buffer.  This  buffer  can  be 
thought  of  as  a  “ring”  buffer  that  has 
two  pointers  —  one  pointing  to  the  be¬ 
ginning  of  the  buffer  (head  pointer) 
and  the  other  pointing  to  the  end  (tail 
pointer).  Figure  3  illustrates  the  behav¬ 
ior  of  the  ring  buffer  and  should  be 
referred  to  in  the  following  discussion. 

Initially,  the  head  and  tail  pointers 
point  to  the  same  address.  When  an 
overlay  is  loaded  into  the  overlay  buffer, 
the  head  pointer  advances  into  the  free 
memory  area  and  marks  the  beginning 
of  the  overlay.  As  more  overlays  are 
loaded  the  free  area  is  eventually  taken 
up.  Typically,  some  free  space  remains, 
but  not  enough  to  accommodate  the 
size  of  the  overlay. 

At  this  point,  when  another  overlay 
is  called,  the  head  pointer  wraps  around 
to  the  bottom  of  the  overlay  buffer 
keeping  the  free  area  between  the  head 
and  tail  pointers.  The  new  overlay  is 
then  loaded  at  the  head,  which  slides 
everything  up  in  the  buffer  and  bumps 
the  first  overlay  off  the  ring.  This  is 
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referred  to  as  the  least  recently  loaded 
method. 

One  possible  problem  with  the  least 
recently  loaded  method  is  that  the  ring 
buffer  doesn’t  take  frequency  of  use 
into  account.  So,  it  is  possible  for  a  less 
frequently  used  overlay  to  replace  one 
that  is  used  more  often  simply  because 
it  was  loaded  last.  TP  5.5  provides  an 
option  to  optimize  the  loading  of  over¬ 
lays  by  intelligently  selecting  which  over¬ 
lay  gets  bumped  off  the  ring. 

TP  accomplishes  this  selection  by 
placing  on  “probation"  overlays  near¬ 
ing  the  tail.  While  on  probation,  the 
overlay  manager  monitors  and  traps 
any  calls  made  to  the  overlay.  If  a  call 
is  made,  the  overlay  is  placed  at  the 
head  of  the  overlay  buffer  and  is  given 
a  free  ride  around  the  ring. 

The  overlay  manager  adds  two  new 
routines  to  get  and  set  the  size  of  the 
probation  area.  The  size  of  the  proba¬ 
tion  area  will  depend  largely  on  your 
application.  Therefore,  the  OvrLoad- 
Count and  OvrTrapCount  variables  are 
provided  to  monitor  how  often  an  over¬ 
lay  has  been  loaded  or  trapped.  By 
placing  these  variables  in  the  Watch 
window  of  the  debugger,  for  instance, 
you  can  monitor  the  effect  of  different 
probation  sizes  on  your  program. 

The  overlay  manager  provides  a  cou¬ 
ple  of  other  goodies,  such  as  OvrFile- 
Mode,  to  get  and  set  an  overlay’s  file 
mode.  This  is  particularly  useful  in  a 
network  environment.  Another  variable, 
OvrReadBuf  allows  you  to  intercept 
overlay  load  operations  for  error  han¬ 
dling,  or  to  check  for  a  removable  disk. 
Finally,  TP  5.5  allows  you  to  append 
overlays  to  the  end  of  your  .EXE  files. 

Smart  Linker 

TP  5.0  included  a  built-in  linker  that 
removes  code  and  data  not  actually  refer¬ 
enced  in  the  program.  In  building  an 
.EXE  file,  the  smart  linker  removed  code 
on  a  per  procedure  basis,  and  removed 
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data  on  a  per  declaration  basis. 

TP  5.5  extends  this  capability  to  ob¬ 
jects.  In  particular,  the  smart  linker  re¬ 
moves  code  for  static  methods  on  a  per 
method  basis,  meaning  that  if  your  pro¬ 
gram  never  calls  a  particular  static 
method,  the  code  for  that  method  will 
not  be  included  in  the  .EXE  file.  Virtual 
methods  of  a  given  object  type,  how¬ 
ever,  are  treated  as  a  single  group  by 
the  linker.  If  your  program  ever  instan¬ 
tiates  an  object  of  a  type  that  contains 
any  virtual  methods,  all  of  them  will 
be  linked  into  the  .EXE. 

The  benefits  of  the  smart  linker  with 
objects  will  become  particularly  appar¬ 
ent  as  you  build  your  own  libraries  of 
standard  objects.  You’ll  be  able  to  link 
these  object  libraries  (as  units)  with 
your  programs  knowing  that  the  smart 
linker  will  strip  out  any  unused  objects. 

Conclusion 

One  of  the  difficulties  with  AI  was  the 
tremendous  learning  curve  that  pro¬ 
grammers  had  to  go  through.  First  you 
had  to  learn  a  language  like  Lisp  or 
Prolog.  Next,  you  had  to  become  famil¬ 
iar  with  concepts  like  expert  system 
design,  neural  networks,  natural  lan¬ 
guage  processing,  and  the  like. 

TP  5.5,  on  the  other  hand,  provides 
an  excellent  migration  path  to  OOP. 
Old  code  runs  fine  under  the  new  com¬ 
piler,  and  the  OOP  approach  works 
well  with  structured  concepts.  You  can, 
therefore,  add  objects  as  you  need  them 
and  alleviate  the  need  to  learn  every¬ 
thing  at  once.  Ultimately,  you’ll  gain 
the  benefits  of  objects  including  flexi¬ 
bility,  reusability,  and  extensibility. 
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_ EXAMINING  ROOM _ 

Getting  the  Bugs  Out 

with 

Turbo  Debugger 


We  all  make  mistakes;  Borland’s  Turbo  Debugger  can  make 
finding  programming  mistakes  fast  and  almost  fun 

Bill  Catchings  and  Mark  L.  Van  Name 


The  T  urbo  Debugger  (TD)  instal¬ 
lation  program  is  easy  to  use, 
asks  few  questions,  and  is  al¬ 
most  foolproof.  The  first  thing 
you  notice  about  TD  is  its  at¬ 
tractiveness,  especially  on  a  VGA  moni¬ 
tor.  The  50-line  VGA  display  contains 
a  lot  of  information,  while  still  remain¬ 
ing  readable. 

What  It  Is  and  What  It  Isn't 

A  major  part  of  the  screen  displays  the 
source  code  of  your  assembler,  C,  or 
Pascal  main  routine.  You  can  debug 
the  source  code,  but  to  compile  or  edit 
it  you  must  leave  TD.  You  can  call  the 
editor  of  your  choice  from  within  TD 
as  long  as  the  editor  of  your  choice  fits 
into  the  memory  limitations  of  running 
TD.  We  called  Epsilon  while  debug¬ 
ging  a  30K-executable  file  with  6K  of 
source.  Larger  editors  might  not  fit  in 
the  remaining  memory  space. 

When  you  return  from  editing  a 
source  file,  TD  marks  the  file  as  modi¬ 
fied.  To  cause  the  object  code  to  reflect 
your  changes,  you  must  exit  TD  and 
recompile  the  source.  You  can’t  push 
to  DOS  and  recompile,  because  TD 
doesn’t  leave  enough  memory  to  hold 
any  of  Borland’s  compilers. 

Entering  Commands 

TD’s  interface  is  similar  to  that  of 
the  current  Turbo  languages.  Its  basic 
display  has  a  menu  bar  across  the  top 
of  the  screen  and  a  line  of  command 
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key  labels  across  the  bottom. 

You  can  get  to  the  menu  bar  by 
pressing  F10.  You  can  also  go  directly 
to  any  menu  by  pressing  the  Alt  key  in 
combination  with  the  first  letter  of  the 
chosen  menu.  Once  you’ve  entered  a 
menu,  you  can  choose  an  option  by 
pointing  to  it  or  by  entering  its  first 
letter. 

The  line  of  command  key  labels  in¬ 
itially  displays  TD’s  global  command 
key  assignments.  Some  of  these  key 
combinations  are  shortcut  equivalents 
to  menu  choices.  If  you  hold  down  the 
Alt  key  for  a  couple  of  seconds  the 
label  line  will  switch  to  a  second  line 
of  global  command  keys  that  can  be 
entered  by  pressing  Alt  plus  a  function 
key.  These  two  sets  of  command  keys 
are  available  in  any  TD  window. 

TD  also  has  local  key  assignments 
that  vary  between  windows.  To  see  the 
local  keys  that  are  currently  available, 
hold  down  Ctrl  for  a  couple  of  seconds 
and  the  bottom  label  line  will  change 
to  display  them.  You  can  trigger  these 
local  commands  by  pressing  Ctrl  plus 
a  single  mnemonic  character;  Ctrl-w, 
for  example,  is  the  watch  command. 

Many  of  these  commands  are  context- 
sensitive  and  follow  an  object/verb  meta¬ 
phor.  Move  the  cursor  to  an  object  on 
the  screen  and  then  enter  a  command. 
TD  will  perform  that  command  on  the 
selected  object.  This  “point-and-pick” 
approach  cries  out  for  a  mouse,  but 
TD,  somewhat  surprisingly,  will  not 
work  with  a  mouse. 

Some  of  TD’s  command-key  se¬ 
quences  will  be  familiar  if  you’ve  used 
either  Turbo  C  or  Turbo  Pascal.  Alt-F5, 
for  example,  will  switch  from  TD’s  dis¬ 


play  to  your  program’s  output  screen; 
Alt-X  will  exit  TD. 

Windows  and  Panes 

Between  the  menu  bar  and  the  key 
labels,  TD  displays  13  different  types 
of  windows,  although  it  initially  dis¬ 
plays  only  two  —  the  Module  and  Watch 
windows. 

Unlike  CodeView’s  limited,  tiled  win¬ 
dows,  TD’s  windows  are  the  “real  thing.” 
They  can  be  overlapped,  moved,  and 
resized,  although  each  window  has  a 
fixed  minimum  size.  The  active  win¬ 
dow  has  a  double-line  border  and  a 
highlighted  title  with  every  window  dis¬ 
playing  a  number  in  its  upper  border. 

TD  pushes  the  constraints  of  the  win¬ 
dow  concept  even  further  by  dividing 
some  windows  into  smaller  units  it  calls 
"panes.”  Panes  display  different  aspects 
of  a  single  window,  and  sometimes  even 
use  different  local  command  keys.  Panes 
cannot  be  rearranged  or  explicitly  re¬ 
sized,  but  TD  will  automatically  adjust 
them  when  the  window  size  changes. 

TD  can  also  automatically  track  your 
cursor  location.  All  of  the  functions  in 
TD  are  context-sensitive.  In  particular, 
pressing  the  FI  key  will  call  up  a  help 
message  relevant  to  the  cursor’s  cur¬ 
rent  location. 

The  Module  Window 

Typically,  the  largest  window  is  TD’s 
initial  Module  window,  which  will  dis¬ 
play  as  much  of  your  source  code  as  it 
can  hold.  You  can  move  around  in  the 
code  with  the  standard  arrow  and 
PageUp/PageDown  keys.  A  triangle  on 
the  left  border  will  mark  the  line  on 
which  execution  is  currently  paused. 
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(continued  from  page  64) 

Because  the  Module  window  is,  in 
many  ways,  TD’s  main  window,  it  gives 
you  access  to  quite  a  few  of  TD's  most 
powerful  features.  For  example,  you 
can  execute  your  program  in  several 
different  ways  via  command  keys. 

If  you  want  to  test  a  complete  run 
through  of  your  program,  press  F9  (Run) 
and  the  program  will  execute  until  it 
either  completes  successfully  or  bombs. 
A  more  cautious  approach  can  be  taken 
with  any  of  three  different  single-step 
commands. 

The  “trace  into”  command  (F7)  will 
run  your  program  one  source  line  at  a 
time.  If  a  line  is  a  call  to  another  rou¬ 
tine,  this  command  follows  that  branch 
into  the  new  routine  and  lets  you  single- 
step  through  the  code  there.  You  can 
also  single-step  through  a  routine  with¬ 
out  going  into  any  routines  it  calls  with 
the  step  over  command  (F8).  This  com¬ 
mand  treats  routine  calls  as  single  in¬ 
structions. 

Another  command,  animate  (Alt-F4), 
causes  TD  to  single-step  continuously, 
although  you  can  stop  execution  at 
any  time  by  pressing  any  key.  (One 
negative  note,  however,  is  that  TD  lacks 
an  undo  feature  like  that  of  the  debugger 
in  Microsoft  QuickC  2.0.  TD’s  undo 
command  (Alt-F6)  only  allows  you  to 
restore  a  window  you’ve  deleted,  not 
undo  the  effects  of  a  line  of  code.) 
After  it  has  read  each  line  of  code,  TD 
updates  all  of  its  windows,  and  you  can 
sit  back  and  watch  the  program  run. 

A  more  radical 
approach  is  to  use  TD’s 
remote  debugging 
abilities  — you  run  your 
program  on  one 
machine  and  TD  on 
another 


You  can  also  instruct  TD  to  run  until 
it  executes  a  return  with  the  until  return 
command  (Alt-F8).  This  command  is 
useful  when  you're  stuck  in  a  subrou¬ 
tine  and  want  to  get  out,  as  can  happen 
when  your  code  enters  a  library  routine 
for  which  you  don’t  have  source  code. 

You  can  stop  your  program  at  any 
time  by  entering  Ctrl-Break.  This  ap¬ 
proach  is  fine  as  long  as  your  program 
has  easily  identifiable  stopping  points, 
such  as  requests  for  input. 

Sometimes,  though,  the  finer  level 
of  control  found  with  breakpoints  is 
needed.  Although  the  terminology  dif¬ 
fers,  TD  offers  all  of  the  breakpoint 
facilities  of  CodeView. 

CodeView  gives  you  three  different 
breakpoint  options.  A  breakpoint  stops 
execution  at  a  given  code  location.  A 
watchpoint  stops  the  program  when 
an  expression  becomes  true.  Finally,  a 
tracepoint  stops  the  program  when  it 
modifies  a  specific  memory  location. 

TD  unites  these  three  mechanisms 
into  one  common  breakpoint  facility. 
A  TD  breakpoint  has  four  possible  parts. 
The  main  component  is  a  location.  The 
location  can  be  either  a  single  line  of 
code  (a  CodeView  breakpoint)  or  an 
indicator  that  it  is  global. 

The  next  component  is  a  condition 
that  must  be  true  for  execution  to  stop. 
For  breakpoints  with  single  locations, 
this  condition  can  only  be  “always.” 
For  global  breakpoints,  you  can  enter 
a  specific  condition. 

You  can  use  this  condition  to  stop 
execution  when  an  expression  becomes 
tme  (CodeView’s  watchpoint).  You  can 
write  the  expression  in  your  choice  of 
C,  Pascal,  or  assembler;  TD  supports 
full  expressions  in  any  of  these  lan¬ 
guages.  However,  caution  must  be  taken 
in  writing  these  expressions,  because 
serious  side  effects  can  be  caused  by 
the  use  of  such  items  as  i++. 

A  condition  can  be  used  to  tell  TD 
to  stop  when  a  memory  location 
changes  (CodeView’s  tracepoint). 

A  final  condition  feature  lets  you  stop 
program  execution  when  a  hardware 
interrupt  occurs.  This  is  a  nice  capabil¬ 
ity  if  you  want  to  use  TD  in  conjunction 
with  a  hardware  debugger  such  as 
Atron’s  386  Source  Probe. 

The  third  component  of  a  TD  break¬ 
point  is  a  count,  which  defaults  to  1 
This  count  tells  TD  how  many  times  it 
should  let  the  breakpoint  occur  before 
it  takes  over. 

You  can  control  the  action  that  TD 
takes  at  that  point  with  the  final 
breakpoint  component.  You  can  stop 
TD  execution,  log  the  value  of  an  ex¬ 
pression,  or  even  execute  another  piece 
of  code. 


All  of  the  breakpoints  that  occur  in 
your  program  and  the  types  of  each 
can  be  seen  in  the  Breakpoint’s  win¬ 
dow.  This  window  is  summoned  via 
the  View  menu  in  the  menu  bar,  which 
has  an  option  for  each  of  TD’s  windows. 

The  current  state  of  your  variables 
can  also  be  seen  by  using  one  of  three 
TD  windows.  The  first  of  these  is  the 
Watch  window,  another  initial  TD  win¬ 
dow.  Place  the  cursor  on  a  variable  and 
press  Ctrl-w  (watch),  and  the  variable 
will  appear  in  this  window.  You  can 
display  an  unlimited  number  of  vari¬ 
ables  here.  Any  time  the  value  of  a 
variable  in  this  window  changes,  the 
new  value  will  appear. 

The  Inspector  window  also  keeps 
track  of  variables,  but  a  separate  win¬ 
dow  must  be  used  to  display  each  vari¬ 
able.  You  can,  however,  have  many 
Inspector  windows  active  at  once.  To 
bring  up  an  Inspector  window,  place 
the  cursor  on  a  variable  and  press  Ctrl-i 
(inspect).  Once  this  has  been  done,  a 
single  command  (F3)  will  close  all  of 
the  active  Inspector  windows. 

The  main  difference  between  the  vari¬ 
able  displays  in  these  two  windows  is 
their  appearance.  The  single  Watch  win¬ 
dow  has  a  necessarily  crammed  dis¬ 
play,  while  each  Inspector  window  has 
more  room  for  its  one  variable.  The 
Watch  window  is  handy  for  simple  vari¬ 
ables,  while  an  Inspector  window’s  ad¬ 
ditional  space  is  better  for  complex 
structures. 

Both  window  types  understand  C 
structures  and  Pascal  records,  as  well 
as  other  variable  types.  This  is  a  defi¬ 
nite  improvement  over  CodeView, 
which  lacks  this  capability.  Consider, 
for  example,  the  pointers  in  a  linked 
list  of  structures.  Inspect  the  first  ele¬ 
ment.  To  see  the  next  element,  move 
the  cursor  to  the  next  structure  pointer 
and  press  the  Ctrl-i  again.  You  can 
easily  wander  through  a  linked  list. 

The  third  way  to  examine  variables  is 
through  the  two  panes  of  the  Variable’s 
window.  The  left  pane  displays  the 
global  variables,  while  the  right  shows 
your  current  routine’s  local  variables. 

In  any  of  these  three  windows  you 
can  change  the  value  of  a  variable.  Just 
position  the  cursor  on  the  variable,  enter 
Ctrl-c  (change),  and  type  a  new  value. 


66 

470 


Dr.  Dobb 's Journal,  July  1989 


Other  Key  Windows 

While  breakpoints  and  variables  are 
important,  it’s  TD’s  other  windows  that 
provide  the  necessary  information  about 
your  program’s  execution. 

The  Stack  window,  for  example, 
shows  the  routines  in  the  stack  form. 
Its  local  commands  let  you  examine 
any  routine  in  the  stack.  In  a  similar 
manner,  you  can  look  at  the  local  vari¬ 
ables  for  any  stack  frame. 

The  User  Screen  window  displays 
the  screen  output  of  your  program.  If 
you  have  a  color  monitor  that  supports 
multiple  pages,  TD  will  use  that  feature 
to  speed  switching  between  its  display 
and- your  program’s.  You  can  examine 
any  ASCII  file  via  TD’s  File  window. 

Getting  Down  to  Nuts  and  Bolts 

There  are  times  when  a  high-level  lan¬ 
guage  isn’t  enough.  To  get  to  the  as¬ 
sembly  code,  you  first  need  to  bring 
up  the  CPU  window.  This  complex 
window  has  five  panes. 

The  first  is  the  code  pane.  It  can 
display  code  in  any  of  three  ways:  by 
showing  only  assembler  and  no  source 
code;  a  display  of  each  source  line 
above  the  assembler  lines  that  it  gener¬ 
ated;  or  each  routine  in  the  language 
in  which  it  was  written. 

One  of  the  CPU  window’s  local  com¬ 
mands,  Ctrl-c  (caller),  takes  you  to  the 
line  of  code  that  called  the  current  rou¬ 
tine.  TD  gets  this  information  from  the 
stack.  If  the  right  stack  frame  isn’t  lo¬ 
cated,  TD  may  become  “confused”  and 
work  incorrectly, 
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Another  local  command,  Ctrl-n  (new) 
CS:IP,  lets  you  start  execution  at  any 
line  of  code,  which  is  a  handy  way  to 
skip  unwanted  code. 

The  second  pane  is  the  data  pane, 
which  looks  a  lot  like  the  old  DOS 
DEBUG  D  command.  It  displays  lines 
that  show  a  hex  address,  a  hex  data 
value,  and  the  ASCII  characters  for 
that  value.  TD  goes  a  step  further  than 
DEBUG,  providing  you  with  options 
that  display  values  as  eight  hex  bytes, 

Unlike  CodeView’s 
limited,  tiled  windows, 
TD’s  windows  are  the 
real  thing — they  can 
overlap,  and  you  can 
move  and  resize  them  — 
although  each  window 
has  a  fixed  minimum 
size 


four  hex  words,  two  hex  long  words, 
or  one  float.  These  options  can  save 
you  the  byte-swapping  hassles  that 
plague  DEBUG. 

TD  also  solves  another  of  DEBUG’s 
problems.  Because  DEBUG  is  the  cur¬ 
rently  executing  program,  the  screen 
addresses  and  interrupt  vectors  dis¬ 
played  always  show  information  about 
DEBUG  itself,  not  about  your  program. 
TD  shows  your  program’s  screen  val¬ 
ues  and  interrupt  vectors  in  its  data 
pane.  It  has  to  lie  to  do  this,  of  course, 
because  it  is  the  currently  executing 
program,  but  in  this  case  fiction  is  much 
more  useful  than  truth. 

Another  niffy  feature  of  the  data  pane 
is  its  local  command,  Ctrl-F  (follow). 
This  command  lets  you  “walk”  down 
a  chain  of  pointers. 

The  CPU  window’s  third  pane,  the 
Stack  pane,  displays  the  top  few  32-bit 
quantities  on  the  stack.  As  in  the  data 
pane,  you  can  follow  pointers  on  the 
stack. 

The  final  two  panes  are  the  Registers 
and  Flags  panes.  The  Registers  pane 
shows  all  of  the  registers  in  either  16- 
or  32-bit  format.  The  Flags  pane  dis¬ 
plays  all  of  the  flags. 

You  can  change  any  of  the  items, 


including  code,  in  any  of  these  panes. 
TD  contains  a  full  assembler  to  process 
code  that  you  enter  although,  as  we 
noted  earlier,  TD  does  not  allow  you 
to  save  code  changes. 

Two  more  of  TD’s  windows,  the  Reg¬ 
isters  and  Dump  windows,  are  basi¬ 
cally  equivalent  to  the  Registers  and 
Data  panes  of  the  CPU  window. 

Still  More  Windows 

TD  also  contains  a  Log  window,  which 
provides  a  handy  way  to  retrace  your 
steps.  The  log  contains  error  messages 
and  other  information,  such  as  the  out¬ 
put  of  any  breakpoint  actions.  The  log 
can  be  kept  in  this  window  or  stored 
in  a  log  file.  CodeView  lacks  such  a  log 
function. 

TD’s  final  window,  the  Numeric  Co¬ 
processor  window,  displays  the  full  state 
of  your  PC’s  math  coprocessor  chip  or 
emulator.  TD  will  automatically  detect 
whether  you’re  using  an  emulator  or  a 
chip.  If  you’re  using  a  chip,  it  will  tell 
you  which  kind.  This  window  is  great 
for  debugging  floating  point  assembler 
code,  which  is  another  feature  lacking 
in  CodeView. 

Wait,  There's  More! 

In  addition  to  all  of  its  windows  and 
commands,  TD  offers  many  other  use¬ 
ful  features,  several  of  which  make  it 
easier  for  you  to  perform  repetitive  tasks. 

For  example,  every  TD  menu,  unlike 
those  found  in  Turbo  C,  will  remember 
your  last  choice.  TD  also  compiles  a 
history  list  for  every  area  in  which  you 
can  type  data.  TD  will  remember  the 
last  ten  responses  for  most  prompt 
boxes.  You  can  move  to  the  one  you 
want,  edit  it  if  necessary,  and  then  press 
Enter  to  execute  it  again. 

TD  will  also  let  you  define  keystroke 
macros,  which  can  contain  as  many 
keystrokes  as  you  want. 

If  you  don’t  want  to  lose  your  care¬ 
fully  chosen  window  layouts  and  mac¬ 
ros,  this  information,  as  well  as  other 
settings,  can  be  saved. 

Advanced  Debugging 

In  addition  to  all  of  its  other  features, 
TD  also  offers  several  interesting  op¬ 
tions  for  more  advanced  debugging 
environments.  Two  displays  can  be 
hooked  to  your  PC,  allowing  you  to 
view  TD  in  one  and  display  your  pro¬ 
gram’s  output  in  the  other.  This  capa¬ 
bility  is  great  for  debugging  highly  in¬ 
teractive  applications. 

Because  TD.EXE  is  a  170K-execut- 
able  program,  TD  also  offers  many  ways 
to  conserve  memory. 

If  your  computer  has  EMS  memory, 
you  can  start  by  moving  TD’s  symbols 
into  EMS.  TD  saves  and  restores  the 


68 


Dr.  Dobb’s Journal,  July  1989 

471 


EXAMINING  ROOM 


EMS  driver’s  state  in  the  process,  so 
that  programs  that  use  the  driver  can 
still  take  advantage  of  this  memory¬ 
saving  feature.  This  technique  won’t 
recover  much  memory,  but  sometimes 
every  little  bit  helps. 

A  more  radical  approach  is  to  use 
TD’s  remote  debugging  capabilities.  To 
accomplish  this  you  must  run  your  pro¬ 
gram  on  one  machine  and  TD  on  an¬ 
other.  By  connecting  the  serial  ports 
of  the  two  PCs,  TD  can  “talk”  to  your 
program  over  that  connection  at  speeds 

Another  of  DEBUG’s 
problems  is  that  the 
screen  addresses  and 
interrupt  vectors  it 
displays  always  show 
information  about 
DEBUG  itself  not  about 
your  program,  because 
DEBUG  is  the  currently 
executing  program 


of  up  to  115K-bits  per  sec.  With  this 
approach,  the  only  memory  you  will 
lose  on  the  PC  with  your  program  is 
the  15K  that  TD’s  communication  pro¬ 
gram,  TDREMOTE.EXE.  requires.  You 
can  also  use  a  TD  program  called 
TDRF.EXE  on  the  debugging  PC  to  trans¬ 
fer  files  between  the  two  systems. 

If  you’ve  got  a  386,  TD  can  use  the 
386’s  virtual  mode.  TD’s  386  version, 
TD386.EXE,  is  a  standard  part  of  the 
package.  This  program  requires  700K 
of  extended  memory  and  loads  above 
the  1M  line.  The  program  you’re  de¬ 
bugging  loads  exactly  where  it  would 
during  normal  execution.  In  addition 
to  saving  memory,  this  approach  is  great 
for  finding  bugs  that  are  dependent 
on  the  program’s  position  in  memory. 

TD386.EXE  uses  a  device  driver, 
TDH386.SYS,  that  works  only  on  Real 
mode  programs.  TD  itself  offers  386 
instructions  beyond  those  restricted  to 
Protected  mode.  It  can  also  use  the 
386’s  hardware  debugging  registers  for 
greater  speed. 

If  your  program  is  close  to  fitting  into 
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memory,  but  can’t  quite  make  it,  the 
TDPACK.EXE  utility  may  do  the  trick. 
It  shrinks  the  debugging  information 
in  an  .EXE.  When  you’ve  finished  de¬ 
bugging,  that  information  can  be  re¬ 
moved  with  the  TDSTRIP.EXE  utility, 
which  allows  you  to  avoid  recompiling 
your  program  without  the  debug  switch. 

Working  with  the  Competition 

Two  other  useful  utilities  help  TD  to 
work  with  code  from  other  compilers. 
TDMAP.EXE  combines  a  program’s 
.EXE  and  .MAP  (output  from  Microsoft 
LINK)  files  so  that  you  can  do  symbolic 
debugging.  In  contrast,  CodeView  can’t 
use  .MAP  files,  and  forces  you  to  com¬ 
pile  with  full  debugging  on  (-v  for  C) 
for  source-level  debugging. 

TD  can  work  on  any  file  that  Code¬ 
View  can  handle,  courtesy  of  the 
TDCONVRT.EXE  utility  that  converts 
files  to  TD’s  format.  This  utility  will 
work  on  any  executable  program,  in¬ 
cluding  one  produced  by  Microsoft’s 
Fortran  or  Basic  compilers.  This  is  one 
instance  where  TD  falls  short  of  Code¬ 
View,  as  CodeView  can  accept  input 
in  either  language’s  syntax,  while  TD 
is  limited  to  assembler,  C,  and  Pascal 
syntax. 

A  Great  Product  at  a  Great  Price 

We’re  sold  on  TD  as  the  current  ideal 
debugging  environment  on  a  flat-screen 
VGA  monitor  in  50-line  mode,  with  a 
25-MHz  386,  with  4  Mbytes  of  extended 
memory  running  the  whole  show.  If 
you  do  much  programming,  TD  may 
represent  the  best  $149.95  you  can 
spend. 

Product  Information 

Turbo  Debugger  1.0.  Requirements:  100 
percent  IBM-compatible  and  IBM  PS/2- 
compatible  systems;  PC-DOS  or  MS- 
DOS  2.0  or  later,  384K  RAM  minimum; 
hard  disk  recommended  but  not  re¬ 
quired;  will  work  with  any  monitor. 
Price:  $149-95  (includes  Turbo  Assem¬ 
bler).  Available  options:  Comes  as  part 
of  the  Turbo  C  Professional  and  Turbo 
Pascal  Professional  packages,  each  of 
which  costs  $249-95.  Current  Turbo  C 
and  Turbo  Pascal  users  can  upgrade 
to  the  Professional  packages  for  $99.95 
each.  Company  information:  Borland 
International,  1800  Green  Hills  Road, 
P.O.  Box  660001,  Scotts  Valley,  CA 
95066-0001,  408-438-8400. 


DDJ 


Vote  for  your  favorite  feature/article. 
Circle  Reader  Service  No.  5. 


Dr.  Dobb's Journal,  July  1989 


Faster 

String  Searches 


Boyer-Moore  may  be  the  algorithm  you  need 


While  programming  several 
of  my  company’s  products, 
1  have  many  times  come 
across  the  need  to  perform 
a  string  search  to  accom¬ 
plish  a  certain  task.  A  string  search  is 
the  function  used  to  find  a  string  A  (the 
pattern)  in  a  string  B  (the  text)  and 
return  the  position  of  A  in  B. 

After  realizing  that  the  built-in  string 
search  functions  of  many  language  com¬ 
pilers  used  simple  brute-force  algo¬ 
rithms,  I  set  out  to  find  and  implement 
an  equivalent  string-search  function  that 
would  perform  at  a  fraction  of  the  speed 
of  the  built-in  function. 

The  Brute-Force  Method 

As  the  name  implies,  the  brute-force 
method  of  performing  a  string  search 
involves  an  exhaustive  search  from  the 
start  of  the  pattern  until  there  is  a  match 
or  the  end  of  the  string  is  reached. 

Each  character  in  the  pattern  is  com¬ 
pared  left  to  right  with  each  character 
in  the  string.  The  scanning  is  continued 
until  all  of  the  characters  in  the  pattern 
match  an  equivalent  length  in  the  string. 
If  no  match  occurs,  the  pattern  is  moved 
one  character  to  the  right  and  a  new 
search  is  begun. 

Assume  we  want  to  search  for  the 
pattern  HEAD  in  the  string  “MAXIMOOD- 
HEADROOM.”  The  search  is  shown  in 
Figure  1.  The  method  shown  is  time- 
consuming,  because  every  character  in 
the  string  must  be  compared  with  every 
other  character  until  a  final  match  is 
found.  Nine  steps  were  taken  to  dis¬ 
cover  the  sample  pattern.  Using  a  pro¬ 
gram  that  must  perform  thousands  of 
searches  is  a  time-consuming  way  of 
looking  up  a  pattern. 


Costas  Menico  is  a  senior  software  de¬ 
veloper  and  part  owner  of  The  Software 
Bottling  Company.  He  can  be  reached 
at  6600  Long  Island  Expressway,  Mas- 
peth,  NY  11378. 


Costas  Menico 

The  Boyer-Moore  Method 

After  looking  through  some  impressive 
(and  complex)  algorithms,  I  came  across 
an  elegant  and  easily  implemented 
algorithm  called  the  Boyer-Moore 
method,  named  for  the  pair  of  scien¬ 
tists  who  invented  it.  This  is  a  hybrid 
algorithm  that  uses  pattern  analysis  com¬ 
bined  with  brute  force. 

To  implement  the  algorithm  in  as¬ 
sembler,  I  used  MASM  and  linked  it 
into  Turbo  Pascal  4.0.  The  algorithm  is 
also  easily  converted  to  work  with  C 
and  Basic.  For  the  assembly  language 
program  (called  POSBM),  see  Listing 
One,  page  98;  for  the  benchmark  test 
program  see  Listing  Two,  page  99. 

The  basic  idea  behind  the  Boyer- 
Moore  technique  is  the  movement  of 
the  pattern  more  than  one  character  at 
a  time  during  the  search  for  a  matching 
character.  This  saves  search  steps, 
thereby  increasing  search  speed.  You 
may  wonder  how  a  whole  pattern  can 
be  moved  to  the  right  without  a  search 
through  any  of  the  characters  in  be¬ 
tween.  The  answer  is  simple.  All  that 
is  required  is  a  256-character  array  that 
defines  the  pattern.  This  array  (called 
a  SKIPARRAY)  is  built  every  time  the 
search  function  is  called.  Each  position 
corresponds  to  the  value  of  each  char¬ 
acter  in  the  ASCII  character  set. 

The  algorithm  is  simple.  A  SKIPAR¬ 


RAY  of  256  bytes  is  filled  with  the  length 
of  the  pattern.  Starting  from  the  right 
of  the  pattern,  each  character  is  read 
and  its  offset  placed  into  the  SKIPAR¬ 
RAY,  using  the  character’s  ASCII  value 
as  the  index  (see  Figure  2). 

The  pattern  is  then  placed  against 
the  string  for  the  search.  At  the  right¬ 
most  position  of  the  pattern  the  corre¬ 
sponding  character  in  the  string  is  read 
and  its  ASCII  value  used  as  an  index 
into  the  SKIPARRAY.  The  value  in  the 
SKIPARRAY  will  determine  how  far  to 
slide  the  pattern  to  the  right,  with  one 
exception.  A  value  of  0  means  that  the 
rightmost  character  in  the  pattern  is 
lined  up  with  an  exact  character  in  the 
string.  Because  this  is  a  possible  match, 
a  reverse  compare  is  performed  on  the 
remaining  characters  in  the  string  (that 
is,  a  reverse  brute-force  compare).  If 
the  pattern  matches,  the  offset  is  noted 
in  the  string.  Otherwise,  the  pattern 
slides  over  by  one  position  and  the 
process  is  repeated. 

To  better  explain  this  process  I  will 
use  as  an  example  the  pattern  HEAD. 
The  SKIPARRAY  is  first  filled  with  the 
length  of  the  pattern.  Once  this  is  com¬ 
pleted  the  SKIPARRAY  will  contain  4s 
in  all  256  positions. 

Next,  we  put  the  skip  value  for  each 
character  in  the  pattern  into  the  SKIPAR¬ 
RAY.  To  do  this,  the  offset  of  each 


Pattern=  HEAD 


String= 

1) 

2) 

3) 

4) 

5) 

6) 

7) 

8) 

9) 


A  X  I  MOODHEADROOM 


HEAD 


H  Does  not  match,  move  right. 
H  Does  not  match,  move  right. 
H  Does  not  match,  move  right. 
H  Does  not  match,  move  right. 
H  Does  not  match,  move  right. 
H  Does  not  match,  move  right. 
H  Does  not  match,  move  right. 
H  Does  not  match,  move  right. 
HEAD  finally  matches. 
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Figure  1:  Brute-force  search 
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character  is  taken  from  the  end  of  HEAD 
and  placed  at  the  ASCII  offset  position 
in  the  SKIPARRAY.  For  the  pattern 
HEAD,  the  SKIPARRAY  is  transformed 
by  putting  in  the  corresponding  values 
of  3,  2,  1,  and  0  at  the  72  (H),  69  (E),  65 
(A)  and  68  (D)  positions  (see  Figure  3). 

The  pattern  is  then  scanned  right  to 
left  to  determine  how  far  to  move  the 
pattern  for  each  character  in  the  string. 
To  find  the  pattern  HEAD  in  MAXI- 
MOODHEADROOM,  HEAD  is  posi¬ 
tioned  at  the  start  of  the  string.  This 
places  the  character  D  of  the  pattern 
HEAD  under  the  character  I  in  the  string 
(see  step  1  in  Figure  3). 

Because  there  is  no  match,  that  is,  D 
is  not  equal  to  I,  the  SKIPARRAY  is 
indexed  at  the  position  of  the  value  for 
I,  which  is  found  to  be  4.  As  I  is  not  in 
the  pattern,  HEAD  is  positioned  four 
characters  to  the  right  of  the  mismatched 
position. 

The  D  in  the  pattern  (see  step  2  in 
Figure  3)  is  now  positioned  under  the 
D  in  the  string.  This  indicates  that  the 
last  character  of  the  pattern  matches 
the  corresponding  character  in  the 
string.  We  therefore  proceed  to  match 
the  remaining  characters  by  using  a 
reverse  brute-force  method.  In  this  case, 
the  A  in  the  pattern  will  not  match  the 
O  in  the  string.  Because  this  was  a 
bmte-force  compare,  we  can  only  move 
the  pattern  one  character  to  the  right. 

The  D  (see  step  3  in  Figure  3)  is  now 
positioned  under  the  H  in  the  string. 
As  D  is  not  equal  to  H,  we  index  in  to 
the  SKIPARRAY  and  find  that  the  skip 
value  for  H  is  3-  HEAD  now  slides  to 
the  right  three  characters. 

The  D  in  the  pattern  (see  step  4  in 
Figure  3)  is  again  lined  up  under  the 
D  in  the  string.  Ely  comparing  the  re¬ 
maining  characters  of  HEAD  backwards 
from  the  D  position,  we  find  that  the 
pattern  matches  successfully  and  re¬ 
cord  the  starting  position  in  the  string. 

The  program  used  to  perform  the  Boyer- 
Moore  search  method  is  shown  in  List¬ 
ing  One.  It  is  assembled  using  MASM 
(or  TASM)  and  the  OBJ  file  is  linked  in 
to  the  Turbo  Pascal  program.  It  is  called 
by  using  the  name  POSBM  the  same 
way  you  would  call  the  POS(  )  function 
in  Turbo  Pascal.  The  way  this  is  set  up 
will  only  work  on  parameters  of  type 
STRING  (see  Listing  Two). which  limit 
the  search  to  255  characters.  You  can 
easily  modify  the  program  to  pass  ar¬ 
rays  the  same  way  they  are  passed  in  C. 

To  call  POSBM  from  C  you  must 
modify  the  structure  CSTK  to  conform 
to  the  C  calling  sequence.  You  must 
change  the  initial  code  to  copy  the 
addresses  of  the  PATADDR  and 
STRADDR  from  the  calling  stack,  to 
PATTXTand  STRTXT.  The  length  of  the 


strings  must  also  be  computed  (by  search¬ 
ing  for  a  0  using  a  SCASB  instruction) 
and  placed  in  the  variables  PATLEN 
and  STRLEN.  Last,  the  way  in  which 
you  return  from  the  function  should 
be  changed  to  leave  the  calling  values 
on  the  stack.  Note  that  the  function 
POSBM  is  declared  FAR. 

Limitations  to  the  Boyer-Moore  Method 

Some  patterns  may  not  be  suitable  for 
this  method.  If  your  pattern  has  repeat¬ 
ing  characters  matching  against  a  text 
of  repeating  characters,  the  Boyer- 
Moore  method  will  actually  be  slower 
than  brute  force.  For  example,  the  bit¬ 
map  pattern  01111111  in  a  bit-map  string 

of  all  1111111111 . would  require 

a  lengthy  search  because  the  0  in  the 
pattern  would  not  be  compared  until 
all  the  Is  have  been  matched  from  right 
to  left.  The  pattern  would  then  be 
moved  over  by  one  position  and  the 
search  tried  again,  thus  defeating  the 
algorithm’s  purpose. 

There  have  been  some  clever  ways 
to  avoid  this  problem  by  analyzing  the 
pattern  but,  for  all  intents  and  pur¬ 
poses,  the  simple  algorithm  works  very 
well  for  text  searches. 

Benchmarks 

To  illustrate  the  speed  difference  be¬ 
tween  brute  force  and  Boyer-Moore,  I 
have  put  together  a  small  test  program 
that  compares  the  speed  of  the  built-in 
function  POS( )  of  Turbo  Pascal  4.0 
(which  uses  the  brute-force  method) 
and  the  assembly  language  function 
POSBM(  )  presented  in  this  article. 

To  run  the  program,  you  must  first 
assemble  the  function  POSBM. ASM  in 
Listing  Two  with  MASM  or  TASM.  This 
will  create  an  .OBJ  module.  Next,  com¬ 
pile  the  Turbo  Pascal  program  in  List¬ 
ing  One.  The  function  will  be  linked 


in  when  the  l$L  POSBM I  directive  is 
encountered.  Because  the  function  is 
declared  as  FAR,  we  must  include  the 
directive  ISF+I  in  the  program  to  notify 
Pascal  that  the  function  should  be  called 
with  FAR  instructions. 

The  program  starts  out  by  generat¬ 
ing  a  random  string  255  characters  long 
and  uses  the  last  five  characters  of  the 
string  as  the  pattern.  The  pattern  is 
then  searched  in  string  using  POS( ) 
and  POSBM( )  by  putting  the  searches 
in  a  long  loop  to  emphasize  the  time 
difference.  You  may  want  to  increase 
the  value  of  longloop  if  you  have  a  fast 
machine  to  see  the  significantly  higher 
start  and  end  times.  The  POSBM( )  is 
usually  400  percent  faster  than  the 
POS(  )  function. 

Conclusion 

I  have  used  this  algorithm  in  a  number 
of  programs  with  impressive  results.  If 
you  are  looking  for  a  way  to  speed  up 
your  program,  check  to  see  if  the  bot¬ 
tleneck  is  your  string  search  functions. 
The  Boyer-Moore  algorithm  will  give 
immediate  results. 

Availability 

All  source  code  for  articles  in  this  issue 
is  available  on  a  single  disk.  To  order, 
send  $14.95  (Calif,  residents  add  sales 
tax)  to  Dr.  Dobb’s Journal ,  501  Galves¬ 
ton  Dr.,  Redwood  City,  CA  94063,  or 
call  800-356-2002  (from  inside  Calif.) 
or  800-533-4372  (from  outside  Calif.). 
Please  specify  the  issue  number  and 
format  (MS-DOS,  Macintosh,  Kaypro). 

DDJ 

(Listings  begin  on  page  98.) 
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Figure  3-'  Using  Boyer-Moore,  we  find  a  match  in  four  steps 
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LINE-OF-BEST-FIT 


Listing  One  (Text  begins  on  page  14.) 

WC  ENTRYFIELD, ES  LEFTIES  AUTOSCROLL  I ES  MARGIN 

IWS  TABSTOP | WS  VISIBLE 

mfit.obj  :  mfit.c  mfit.h 

CONTROL  "x  -  axis  label", DM  XAXIS, 54, 117, 89, 13, 

CL  /c  /Lp  /Zp  /Od  /G2sw  /W2  mfit.c 

WC  ENTRYFIELD, ES  LEFTIES  AUTOSCROLL | ES  MARGIN 

IWS  TABSTOP IWS  VISIBLE 

mfit.res  :  mfit.rc  mfit.ico  mfit.h  mfit.ptr 

CONTROL  "y  -  axis  label", DM  YAXIS, 54, 101, 89, 13, 

RC  -r  mfit 

WC  ENTRYFIELD, ES  LEFTIES  AUTOSCROLL  I ES  MARGIN 

IWS  TABSTOP |WS  VISIBLE 

mfit.exe  :  mfit.obj  mfit.def  mfit.res 

CONTROL  "  x:", 273, 25, 57, 20, 8, WC  STATIC, SS  TEXTIDT  LEFT! 

link  mfit,  /align: 16,  NUL,  0S2,  mfit 

DT  TOPIWS  GROUP IWS  VISIBLE 

rc  mfit.res 

CONTROL  "  y: ",  283, 75, 57, 20, 8, WC  STATIC, SS  TEXTIDT  LEFT! 

DT  TOPIWS  GROUP |WS  VISIBLE 

CONTROL  "500", DM  XI , 50, 57, 20, 1 5, WC  ENTRYFIELD, ES  LEFT 

1 ES  AUTOSCROLL | ES  MARGIN  I WS  TABSTOP | WS  VISIBLE 

End  listing  One 

CONTROL  "400", DM  Yl, 100, 57, 20, 15, WC  ENTRYFIELD, ES  LEFT 

I ES  AUTOSCROLL  1 ES  MARGIN IWS  TABSTOP IWS  VISIBLE 

CONTROL  "OK", ID  OK, 17 , 13, 24 , 1 4 , WC  BUTTON, BS  PUSHBUTTON 

IWS  TABSTOP IWS  VISIBLE 

CONTROL  "Cancel", ID  CANCEL, 101, 13, 34, 14, WC  BUTTON, 

Listing  Two 

BS  PUSHBUTTON IWS  TABSTOP IWS  VISIBLE 

END 

/MFIT.DEF  for  C  Compiling 

END 

End  Listing  Four 

NAME  mfit 

EXPORTS  About 

EXPORTS  LineDiaProc 

EXPORTS  GraphicProc 

PROTMODE 

HEAPSIZE  2048 

Listing  Five 

STACKS I ZE  9216 

/*  Cached-PS  Window  Platform  for  PM  Graphics  */ 

/*  (c)  William  H.  Murray  and  Chris  H.  Pappas,  1989  */ 

tdefine  INCL_PM 

End  Listing  Two 

tinclude  <os2.h> 
tinclude  <stddef.h> 
tinclude  <stdio.h> 
tinclude  <stdlib.h> 

Listing  Three 

tinclude  <string.h> 
tinclude  "mfit.h" 

#define  ID  RESOURCE  10 

MRESULT  EXPENTRY  About (HWND, USHORT, MPARAM, MPARAM) ; 

#def ine  ID  ABOUT  15 

MRESULT  EXPENTRY  LineDiaProc (HWND, USHORT, MPARAM, MPARAM) ; 

tdefine  ID  OK  20 

MRESULT  EXPENTRY  GraphicProc (HWND, USHORT, MPARAM, MPARAM) ; 

tdefine  ID  CANCEL  25 

tdefine  ID_INPUT  30 

tdefine  maxpts  100 

#define  I DM  ABOUT  40 

HPS  hps; 

tdefine  I DM  INPUT  45 

HWND  hfrm,hcnt; 

tdefine  I DM  LINEINPUT  55 

QMSG  qmsg ; 

long  ptxorg[maxpts] ; 

tdefine  DM  XAXIS  470 

long  ptyorg [maxpts] ; 

tdefine  DM  YAXIS  475 

long  xaxismax=500; 

tdefine  DM  TITLE  480 

long  yaxismax=400; 

tdefine  DM  XI  485 

char  title [80]="Mouse  Data  Points"; 

tdefine  DM  Y1  490 

char  xstring[80)="x  -  axis  label"; 

char  ystring[80]="y  -  axis  label"; 

POINTL  mousepos; 

End  listing  Three 

main  () 

Listing  Four 

static  CHAR  pszClassName[] ="FirstClass"; 

HAB  hab; 

HMQ  hmq ; 

HDC  hdc; 

SIZEL  page; 

tinclude  <os2.h> 

ULONG  f lFrameFlags=FCF  SYSMENU I FCF  TITLEBAR j 

tinclude  "mfit.h" 

FCF  SIZEBORDER 1 FCF  MINKAX; 

FCF  ICON  1 FCF  MENU; 

POINTER  ID  RESOURCE  mfit.ico 

ULONG  f lFrameStyle=WS  VISIBLE; 

POINTER  IDP  POINTER  mfit.ptr 

hab=WinInitialize (0) ; 

MENU  ID  RESOURCE 

hmq=WinCreateMsgQueue (hab, 0) ; 

BEGIN 

WinRegisterClass (hab, ps zCl as sName, GraphicProc, 

SUBMENU  "Mouse  Data", IDM  LINEINPUT 

CS  SIZEREDRAW, 0) ; 

BEGIN 

hf rm=WinCreateStdWmdow (HWND  DESKTOP,  f  lFrameStyle, 

MENU ITEM  "About...",  IDM  ABOUT 

&f lFrameFlags, pszClassName, 

MENU  ITEM  "Prognm  Data...",  IDM  INPUT 

"Cached-PS  PM  Graphics", 

END 

0L, NULL, ID  RESOURCE, ihcnt) ; 

END 

hdc=WinOpenWindowDC (hcnt); 

hps=GpiCreatePS (hab, hdc, Spage, PU  PELSIGPIA  ASSOC); 

DLGTEMPLATE  ID  ABOUT 

WinSetWindowPos (hf rm, NULL, 10, 10, 610,  470,  SWP  SIZE! 

BEGIN 

SWP  MOVE  I SWP  SHOW); 

DIALOG  " " , ID  ABOUT, 50, 300, 180, 80, FS  DLGBORDER 

while  (WinGetMsg (hab, &qmsg, NULL, 0,0)) 

BEGIN 

WinDispatchMsg (hab, &qmsg) ; 

CTEXT  "Mouse  Data  Input  Program", -1,2, 60, 176, 10 

WinDestroyWindow (hf rm) ; 

CTEXT  "by  William  H.  Murray  &  Chris  H.  Pappas", -1, 2, 45, 

WinDestroyMsgQueue (hmq) ; 

176, 10 

WinTerminate (hab) ; 

CONTROL  "OK", ID  OK, 75, 10, 32 , 1 4 , WC  BUTTON, BS  PUSHBUTTON 

return  0; 

] 

IBS  DEFAULT | WS  GROUP |WS  TABSTOP I WS  VISIBLE 

END 

END 

MRESULT  EXPENTRY  About (hwnd, messg, parml , parm2 ) 

HWND  hwnd; 

DLGTEMPLATE  ID  INPUT  LOADONCALL  MOVEABLE  DISCARDABLE 

BEGIN 

USHORT  messg; 

MPARAM  parml, pa rm2; 

( 

DIALOG  "Mouse  Program  Information", ID  INPUT, 76, 247, 148, 193, 

FS  NOBYTEALIGNIFS  DLGBORDER | WS  VISIBLE ! 

switch  (messg) 

( 

WS  CLIPSIBLINGS I WS  SAVEBITS,FCF  TITLEBAR 

BEGIN 

case  WM  COMMAND: 

CONTROL  "Mouse  Program  Labels" , 257, 2, 92, 145, 72, WC  STATIC, 

switch  (LOUSHORT (parml ) ) 

{ 

SS  GROUPBOX | WS  GROUP  I WS  VISIBLE 

CONTROL  "X  &  Y  Maximums", 259, 2, 42, 145, 42, WC  STATIC, 

SS  GROUPBOX I WS  GROUP |WS  VISIBLE 

WinDismissDlg (hwnd, TRUE) ; 

CONTROL  "Enter  Title: ",  260, 5,  133, 51, 8, WC  STATIC, SS  TEXT 

return  0; 

|DT  LEFT  IDT  TOPIWS  GROUP  I WS  VISIBLE 

CONTROL  "  x-axis: " ,261, 5, 118, 54,8, WC  STATIC, SS  TEXT 

break; 

IDT  LEFT |DT  TOPIWS  GROUP |WS  VISIBLE 

CONTROL  "  y-axis : ", 262, 5, 102, 50, 8, WC  STATIC, SS  TEXT 

return  (WinDefDlgProc (hwnd, messg, parml , parm2) ) ; 

CONTROL  "Mouse  Data  Points", DM  TITLE, 54, 132, 89, 13, 

(continued  on  page  80) 
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Listing  Five  (Listing  continued,  text  begins  on  page  14.) 

MRESULT  EXPENTRY  LineDiaProc (hwnd, messg, parml, parm2 ) 

1 

HWND  hwnd; 

dencl= (npts'sumxsqrl) - (sumxl *sumxl ) ; 

USHORT  messg; 

numal=(sumxsqrl* sumyl) - (sumxl ‘sumxyl ) ; 

MPARAM  parml; 

MPARAM  parm2; 

numbl=(npts*sumxyl) - (sumxl*sumyl) ; 

{ 

/*  Calculate  values  for  drawing  line  on  screen  */ 

short  XI; 

sumxsqr2=0; 

short  Yl; 

sumx2=0; 

switch  (messg) 

( 

sumy2=0; 

sumxy2=0; 

case  WM  COMMAND: 

for  (i=0;i<npts;i++) 

switch  (L0USH0RT  (parml)) 

1 

1 

sumxsqr2+=ptxorg(i] ‘ptxorg [i] ; 

case  ID  OK: 

sumx2+=ptxorg [ i  ] ; 

WinQueryDlgltemText (hwnd, 

sumy2+=ptyorg [ i ] ; 

DM  TITLE, 

sumxy2+=ptxorg [l] *ptyorg(i] ; 

80, 

1 

title) ; 

deno2=(npts*sumxsqr2) - (sumx2*sumx2i ; 

WinQueryDlgltemText (hwnd, 

numa2=(sumxsqr2*sumy2) - (surax2*sumxy2) ; 

DM  XAXIS, 

80, 

numb2= (npts*sumxy2) - (sumx2*sumy2) ; 

xstring) ; 

switch  (messg) 

WinQueryDlgltemText (hwnd, 

DM  YAXIS, 

( 

80, 

case  WM  CREATE: 

ystring) ; 

linePtr=WinLcadPointer (HWND  DESKTOP, 

WinQueryDlgltemShort (hwnd, 

NULL, IDP  POINTER) ; 

DM  XI, 

&X1, 

return  0; 

1); 

case  WM  BUTTON 1 DOWN : 

WinQueryDlgltemShort (hwnd. 

GpiSetMarker (hps, MARKSYM  PLUS); 

DM  Yl, 

GpiSetColor (hps, CLR  BLUE); 

4Y1, 

mousepos .x= (LONG)  LOUSHORT (parml ) ; 

1) ; 

mousepos . y= (LONG)  HIUSHORT (parml ) ; 

xaxismax= (long)  XI; 

if (mousepos .x>99  &  mousepos . x<500  & 

yaxismax= (long)  Yl; 

mousepos. y>99  &  mousepos . y<400) 

WinDismissDlg (hwnd,  TRUE) ; 

1 

return  0; 

ptxorg! 3]=mousepos.x; 
ptyorg ( j ] =mousepos . y ; 

case  ID  CANCEL: 

j++; 

WinDismissDlg (hwnd, TRUE) ; 

npts=j; 

return  0; 

) 

GpiMarker (hps, imousepos) ; 

break; 

return  TRUE; 

return  WinDefDlgProc  (hwnd, messg, parml , parm2) ; 

case  WM  MOUSEMOVE: 

) 

MRESULT  EXPENTRY  GraphicProc (hwnd, messg, parml , parm2 ) 

WinSetPointer  (HWND_DESKTOP,  lir.ePtr)  ; 
return  0; 

HWND  hwnd; 

case  WM  BUTTON 2 DOWN : 

USHORT  messg; 

GpiSetColor (hps, CLR  RED); 

MPARAM  parml, pa rm2; 

j=0;  /‘reset  pointer  */ 

( 

maxx=0; 

static  LONG  ColorDatalnfo [ ] =(CLR  NEUTRAL, 

/*  Slope  and  intercept  for  org.  and  scaled  */ 

RGB  BLACK, 

al= (double)  numal /denol; 

CLR  BACKGROUND, 

bl= (double)  numbl/denol; 

RGB  WHITE); 

a2= (double)  numa2/deno2; 

static  HPOINTER  linePtr; 

static  HWND  hmenu; 

b2= (double)  numb2/deno2; 

HPS  hgpi ; 

/*  Starting  point  for  line  of  best  fit  */ 

HDC  hdc ; 

for  (i=99; i<510;i++) 

POINTL  ptl; 

I 

GRAD I ENT L  gradl; 

y=a2+ (b2’i) ; 

RECTL  rcl; 

if(y>99.0  y<4 10.0) 

int  i,  alength,blength; 

f 

int  lenxstrmg,  lenystring,  lentitle, 

ptl .x=i; 

lenmaxxlabel, lenmaxylabel; 

ptl.y=(long)  y; 

long  ptxmax, ptymax, sumxl, sumyl, sumxyl, 

break; 

sumxsqrl,denol, numal,  numbl, 

) 

sumx2, sumy2, sumxy2,  sumxsqr2, 

1 

deno2 , numa2 , numb2 ; 

long  ptxscaled[maxpts] , ptyscaled'maxpts]  ,maxx; 

GpiMove(hps,&ptl) ; 

char  maxxlabel (4) ,maxylabel [4 ] , 

/*  Ending  point  for  line  of  best  fit  *7 

astring [10] .bstring [10] ; 

for  (i=510; i>99; i — ) 

double  al, bl, a2, b2, y; 

( 

static  int  j=0; 

y=a2+ (b2*i ) ; 

static  int  npts=0; 

if  (y>99 . 0  &&  y<4 10.0) 

/*  Length  of  various  strings  »/ 

ptl .x=i; 

lent itle=strlen (title) ; 

ptl . y= (long)  y; 

lenxstring=strlen (xstring) ; 

break; 

lenystring=strlen (ystring) ; 

) 

/*  Convert  maximum  x  value  to  a  string  */ 
itoa ( (int) xaxismax, maxxlabel, 10) ; 

GpiLine (hps, &ptl) ; 

lenmaxxlabel=strlen (maxxlabel) ; 

/*  Draw  the  equation  to  the  screen.  */ 

GpiSetColor (hps, CLR  WHITE); 

/*  Convert  maximum  y  value  to  a  string  */ 

ptl  .x=100; 

itoa ( (int) yaxismax,maxylabel, 10) ; 

ptl.y=80; 

lenmaxylabel=strlen (maxylabel) ; 

GpiMove (hps, &ptl) ; 
ptl  .x=500; 

/*  Scale  all  x  values  in  original  array.  */ 

ptl .y=55; 

for  (i=0; i<npts; i++) 

GpiBox (hps, DRO  FILL, &ptl, 0L, 0L) ; 

ptxscaled[i]  =  ( (ptxorg |i) -100) *xaxismax/400) ; 

GpiSetColor (hps, CLR  RED); 

/*  Scale  all  y  values  in  original  array.  */ 

gcvt (al, 7, astring) ; 

for  (i=0; i<npts; i++) 

alength=st  rlen (astring) ; 

ptyscaled[i]= ( (ptyorg [i] -100) *yaxismax/300) ; 

gcvt (bl, 7, bstring) ; 
biength=strlen  (bstrmg) ; 

/*  Calculate  values  for  screen  equation  */ 

ptl .x=300- (LONG) (aiength+blength+8)  *4; 

sumxsqrl=0; 

ptl .y=62; 

sumxi=0; 

GpiMove (hps,  &pti) ; 

sumyl=0; 

GpiCharSt  ring  (hps,  4L,  "y  =  ")-' 

sumxyl=0; 

GpiCharString (hps, (long)  alength, astring) ; 

for  (i=0; i<npts; i++) 

GpiCharString (hps, 3L, "  +  "); 

( 

GpiCharString (hps, (long)  blength, bstring) ; 

sumxsqrl+=ptxscaled[i] *ptxscalea(i] ; 

GpiCharString (hps, 3L,  " ( x ) ") ; 

sumxl+=ptxscaled [ i ) ; 
sumyl+=ptyscaled[i] ; 
sumxyl+=ptxscaled[i] *ptyscaled[i] ; 

return  TRUE; 
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Listing  Five  (Listing  continued,  text  begins  on  page  14.) 


case  WMSIZE: 
if  (hmenu==NULL) 

hmenu=WinWindowFromID (WinQueryWindow (hwnd, 

QW_PARENT, FALSE) , FID_MENU) ; 

return  0; 
case  WM_COMMAND : 

f 

switch  (COMMANDMSG (Smessg) ->cmd) 

{ 

case  I DM_ABOUT : 

if  ( WinDlgBcx ( HWND_DESKTOP , hwnd, About, 

NULL, ID_ABOUT, NULL) ) 
WinlnvalidateRect (hwnd, NULL, FALSE) ; 
return  0; 

case  IDM_INPUT: 

if  (WinDlgBox (HWND_DESKTOP, hwnd, LineDiaProc, 
NULL, ID_INPUT, NULL) ) 
WinlnvalidateRect (hwnd, NULL, FALSE) ; 
return  0; 

return  0; 

I 

break; 

case  WM_PAINT : 

hgpi=WinBeginPaint (hwnd, NULL,  NULL) ; 
GpiCreateLogColorTable (hgpi, LCOL_RESET, 

LCOLF_INDRGB, OL, 4L, ColorDatalnfo) ; 

GpiErase (hgpi ) ; 

/* - your  routines  below - * / 

GpiSetColor (hgpi, CLR_B LACK) ; 

/*  Draw  X  and  Y  coordinate  axis  */ 

ptl . x=99; 

ptl.y=41Q; 


GpiMove ( hgpi , &pt 1 ) ; 
ptl .y=99; 

GpiLine (hgpi, &ptl) ; 
ptl . x=510; 

GpiLine (hgpi, &ptl) ; 

/*  Draw  Y  axis  tic  marks  */ 

ptl .y=130; 

for  (i=0; i<10;i++) 

( 

ptl.x=95; 

GpiMove ( hgpi , &pt 1 ) ; 
ptl . x=99; 

GpiLine (hgpi, Sptl) ; 
ptl.y+=30; 

) 

/*  Draw  X  axis  tic  marks  */ 

ptl.x-140; 

for  (i=0;i<10;i++) 

( 

ptl.y=99; 

GpiMove (hgpi, &ptl) ; 
ptl .y=95; 

GpiLine (hgpi, &ptl) ; 
ptl.x+=40; 

) 

GpiSetCharMode(hgpi,CM_MODE3) ; 

/*  Center  and  print  line  chart  title  */ 
ptl . y=4 10; 

ptl. x=300-( (LONG)  (lentitle/2) *6) ; 
GpiCharStringAt (hgpi, &ptl, (LONG)  lentitle, title) 

/*  Center  and  print  horizontal  axis  label  */ 
ptl .y=40; 

ptl .x=300- ( (LONG)  (lenxstring/2) *6) ; 
GpiCharStnngAt  (hgpi,  &ptl,  (LONG)  lenxstring, 
xstring) ; 


/*  Print  horizontal  axis  maximum  value  */ 

ptl .y=82; 

ptl.x=490; 

GpiCharStringAt (hgpi, &ptl, (long)  lenmaxxlabel, 
maxx label) ; 

/*  Print  vertical  axis  maximum  value  */ 
ptl . y=400; 
ptl .x=70; 

GpiCharStringAt (hgpi, &ptl, (long)  lenmaxylabel, 
maxylabel) ; 

/*  Center  and  print  vertical  axis  label  */ 
ptl .y=240- ( (LONG)  (lenystring/2) *6) ; 
ptl . x=70; 
gradl.x=0; 
gradl .y=90; 

GpiSetCharAngle (hgpi,  &gradl)  ; 

GpiCharStringAt (hgpi, fcptl, (LONG)  lenystring, 
ystring) ; 

/* - your  routines  above - */ 

WinEndPaint (hgpi) ; 
break; 

default : 

return  WinDefWindowProc (hwnd, messg, parml , parm2 ) 

I 

return  0; 

l 


End  Listings 


ICON  EDITOR 


Listing  One  (Text  begins  on  page  24.) 


/*  iconed.c  —  a  special  purpose  icon  editor. 


This  program  allows  you  to  interactively  edit  icons  that 
can  be  used  in  a  graphics  program.  You  can  create  an  icon, 
edit  an  existing  one,  or  save  an  icon  pattern  to  a  file.  The 
program  requires  a  mouse.  The  icon  files  produced  are  of  the 
form: 

ICONWIDTH  ICONHEIGHT 
one  row  of  icon  pattern 
next  row  of  icon  pattern 

last  row  of  icon  pattern 


♦include  <stdio.h> 
#include  <stdlib.h> 
♦include  <conio.h> 
♦include  <graphics.h> 
♦include  <stdarg.h> 
♦include  <alloc.h> 
♦include  "mouse. h" 


/*  mouse  and  keyboard  routines  */ 


♦define  BIGICONLEFT  20 
♦define  BIGICONTOP  50 
♦define  BIGBITSIZE  8 
♦define  ICONWIDTH  16 
♦define  ICONHEIGHT  16 
♦define  ICONLEFT  400 
♦define  ESC  27 


/*  left  side  of  the  big  icon  pattern  */ 
/*  top  side  of  the  big  icon  pattern  */ 
/*  big  bits  are  8  pixels  in  size  */ 

/*  an  icon  is  a  16x16  pattern  */ 

/*  small  icon  pattern  located  here  */ 

/*  the  value  of  the  ESC  key  */ 


/*  Here  are  the  functions  used  in  iconed.c:  */ 


void  draw_enlarged_icon (void) ; 
void  toggle_bigbit (int  x,  int  y) ; 
void  toggle_icons_bit (int  x,  int  y); 
void  init_bigbit (void) ; 
void  toggle_cursor (int  x,  int  y) ; 
void  save_icon (void) ; 
int  read_icon (void) ; 
void  init_graphics  (void) ; 
void  show_icon (void) ; 


/*  The  global  variables  */ 

void  *bigbit;  /*  points  to  image  of  a  big  bit  */ 

/*  holds  icon  pattern  */ 
unsigned  char  icon [ICONHEIGHT] [ICONWIDTH]; 


read_icon();  /*  read  in  an  icon  file  */ 

init_graphics () ; 

/*  initialize  mouse  */ 

if  ( ! initmouse () )  (  /*  must  have  mouse  */ 

restorecrtmode () ; 
printf ("\nMouse  not  installed"); 
printf ("XnQuitting  the  Icon  Editor"); 
exit  (1)  ; 

) 

draw_enlarged_icon () ;  /*  an  empty  big  icon  pattern  */ 

show_icon();  /*  Draw  the  icon  */ 

hidemouseO;  /*  mouse  cursor  must  be  turned  off  */ 

/*  before  writing  to  screen  */ 
outtextxy (BIGICONLEFT,  10,  "Press  ESC  when  finished  ..."); 
outtextxy (BIGICONLEFT,  BIGICONTOP-20,  "Enlarged  Icon"); 
outtextxy (ICONLEFT,  BIGICONTOP-20,  "Actual  Icon"); 
showmouseO;  /*  redisplay  mouse  cursor  */ 

/*  get  input  from  nouse/keyboard  */ 
while  ( (c=waitforinput (LEFT_BUTTON) )  !=  ESC)  ( 

if  (c  <  0)  {  /*  if  true  mouse  button  pressed  */ 

getmousecoords (ix,  &y) ;  /*  get  current  position  */ 

toggle_bigbit (x,  y) ;  /*  toggle  big  bit  */ 

} 

) 

hidemouseO;  /*  turn  mouse  off  and  then  get  out  */ 

closegraph () ;  /*  of  graphics  mode  */ 

printf ("Do  you  want  to  save  this  icon  to  a  file?  (y)  "); 
if  (getchO  !=  'n' ) 
save_icon  () ; 


void  draw_enlarged_icon (void) 

I 

/* 

*  This  function  draws  an  enlarged  view  of  the  icon  pattern. 

*  You  can  click  a  big  bit  in  this  pattern  to  toggle  the 

*  corresponding  icons  on  and  off  in  the  actual  icon.  The 

*  icon  is  drawn  at  BIGICONLEFT,  BIGICONTOP,  to  right,  bottom. 

*/ 

int  i; 

int  right, bottom; 

setlinestyle (DOTTED_LINE,  0,  NORM_WIDTH) ; 
right  =  2  *  (BIGICONLEFT  +  ( ICONWIDTH- 1)  * 

(BIGBITSIZE  +  NORM_WIDTH) ) ; 

bottom  =  BIGICONTOP  +  ICONHEIGHT  *  (BIGBITSIZE  +  NORM_WIDTH) ; 


void  main ( ) 

{ 

int  x,  y; 
int  c; 


hidemouseO;  /*  draw  vertical  and  horizonatal  dashed  */ 
for  (i=0;  i<=ICONHEIGHT;  i++) 

line (BIGICONLEFT,  BIGICONTOP+i* ( BIGBITS I ZE+NORM_WIDTH) , 
right,  BIGICONTOP+i* ( BIGBITS I ZE+NORM_WIDTH) ) ; 
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for  (i=0;  i<=ICONWIDTH;  i++) 

line(BIGIC0NLEFT+2* (i* (BIGBITSIZE+NORM  WIDTH)),  BIGICONTOP, 

Listing  One  ( Listing  continued ,  text  begins  on  page  24.) 

BIGICONLEFT+2* (i* (BIGBITSIZE+NORM  WIDTH)),  bottom); 

showmouse ( ) ; 

pnntf  ("\nEnter  the  file  name  to  store  the  icon  in:  "); 

init  bigbit {);  /*  create  the  big  bit  image  */ 

) 

scanf ( "Is" , filename) ; 

if  ( (iconfile  =  f open ( filename, "w" ) )  ==  NULL)  { 

printf ( "Could  not  open  file.Nn"); 

return; 

void  init  bigbit (void) 

{ 

I 

/*  Write  the  header  to  the  file  */ 

/*  This  function  creates  the  image  of  a  single  big  bit.  This 
*  image  is  used  to  toggle  the  big  bits  whenever  the  user 

fprintf (iconfile,  "Id  %d\n",  ICONWIDTH,  ICONHEIGHT); 

*  clicks  on  the  big  icon  pattern. 

*/ 

for  ( j=0;  jcICONHEIGHT;  j++)  (  /*  Write  the  icon  */ 

for  (i=0;  idCONWIDTH;  i+  +  )  /*  pattern  to  a  file  */ 

int  bbx,  bby; 

fprintf (iconfile,  "%x  ",  icon [ j ] [ i ] ) ; 

int  i, j; 

fprintf (iconfile,  "\n"); 

bbx  =  BIGICONLEFT; 

bby  =  BIGICONTOP;  /*  corner  of  the  big  icon  */ 

fclose (iconfile) ; 

hidemousef);  /*  hide  the  mouse  before  drawing  */ 

for  (j=bby+l;  j<=bby+BIGBITSIZE;  j++)  ( 

mt  read  icon  (void) 

for  (i=bbx+l;  i<=bbx+2 +BIGBITSIZE;  i++)  ( 

1 

putpixel ( i , j , getmaxcolor ( ) ) ; 

) 

1 

/*  This  function  reads  an  icon  file  into  the  icon  array  and 

*  calls  show  icon ()  to  turn  the  appropriate  pixels  on.  If  the 

*  file  header  doesn't  match  ICONWIDTH  and  ICONHEIGHT,  the 

*  the  file  is  invalid  and  the  icon  is  not  read.  The  function 

/*  Set  aside  memory  for  the  big  bit  image  and  then  use 
getimageO  to  capture  its  image.  */ 

*  returns  a  0  if  a  file  is  not  read;  otherwise  1  is  returned. 

*/ 

char  filename [80] ; 

bigbit  =  malloc  (irragesize  (bbx,  bby,  bbx+2*BIGBITSIZE, 

FILE  ‘iconfile; 

bby+BIGBITSIZE) ) ; 

int  i,  j; 

get image (bbx+1, bby+1, bbx+2*BIGBITSIZE, bby+BIGBITSIZE, 

int  width,  height; 

bigbit) ; 

for  ( j=0;  j< ICONHEIGHT;  j++)  (  /*  Initialize  icon  array  */ 

/*  Erase  the  big  bit  by  exclusive  ORing  it  with  itself  */ 

for  (i=0;  KICONWIDTH;  i++)  /*  to  all  blanks  */ 

icon [ j]  [i]  =  0; 

putimage (bbx+1,  bby+1,  bigbit,  XOR  PUT); 
showmouseO;  /*  turn  the  mouse  back  on  */ 

} 

1 

printf  ("\n\n - -  ICON  EDITOR  - - \n\n"); 

printf ("Do  you  want  to  edit  an  existing  icon?  (y)  "); 

void  toggle  bigbit (int  x,  int  y) 

if  (getch ( )  ==  '  n' ) 

/* 

return (0) ; 

*  This  function  togqles  a  big  bit  and  the  corresponding  pixel 

printf ("\nEnter  name  of  the  file  to  read  the  icon  from:  ") ; 

*  in  the  icon  pattern.  The  x  and  y  coordinates  specify  the 

scanf ("%s", filename) ; 

*  mouse  position. 

if  ((iconfile  =  fopen (filename, "r") )  ==  NULL)  [ 

*/ 

printf ("Cannot  open  file.Nn”); 

int  i,  j; 

return(0);  /*  return  a  failure  flag  */ 

int  linel,  line2,  coll,  col2; 

1 

/*  Read  first  line  of  the  icon  file.  It  should  contain  two 

for  ( j=0;  j<ICONHEIGHT;  j++)  ( 

numbers  that  are  equal  to  ICONWIDTH  and  ICONHEIGHT. 

linel  =  BIGICONTOP+ j* (BIGBITSIZE+NORM  WIDTH); 
line2  =  BIGICONTOP+ (]+l) * (BIGBITSIZE+NORM  WIDTH); 

*  / 

fscanf (iconfile,  "Id  id",  &width,  sheight); 

if  (linel  <=  y  &&  y  <  line2)  ( 

if  (width  ! =  ICONWIDTH  II  height  !=  ICONHEIGHT)  ( 

for  ( i=0 ;  i<ICONWIDTH;  i++)  ( 

printf ("Incompatible  icon  file.Nn"); 

coll  =  BIGICONLEFT+2*  (l*  (BIGBITSIZE+NORM  WIDTH)); 
col2  =  BIGICONLEFT+2* ( (i+1) * 

return(0);  /*  return  a  failure  flag  */ 

1 

(BIGBITSIZE+NORM  WIDTH)); 

if  (C0_1  <=  x  &&  x  <  col2)  ( 

for  (g=0;  j<ICONHEIGHT;  j++)  ( 

hi demouse ( ) ; 

for  (i=0;  idCONWIDTH;  i  +  +  ) 

putimage (coll+1, linel+1, bigbit, XOR  PUT) ; 
showmouse ( ) ; 

fscanf (iconfile,  "lx",  &  icon [ j ] [ i ] ) ; 

1 

toggle_icons_bit ( i ,  j ) ; 
return; 

) 

) 

} 

1 

) 

fclose (iconfile) ; 

return (1);  /*  return  a  success  flag  */ 

] 

void  init  graphics (void) 

( 

/*  This  function  initializes  the  graphics  hardware. 

*/ 

int  gdnver  =  CGA; 

void  toggle  icons  bit (int  x,  int  y) 

( 

int  gmode,  gerror; 

*  This  function  toggles  a  single  pixel  in  the  icon  pattern. 

gmode  =4; 

*  The  pixel's  color  and  value  is  changed  in  the  icon  array. 

mitgraph  (igdnver,  igmode,  "") ; 

*  Arguments  x  and  y  are  between  0  and  ICONWIDTH  or  ICONHEIGHT. 

if  ((gerror  =  graphresult  ( ) )  <  0)  ( 

*  The  array  icon  saves  the  icon  pattern.  If  a  location  is  set 

printf ( "Failed  graphics  initialization:  gerror=ldNn" , 

*  to  1,  the  corresponding  pixel  in  the  icon  is  displayed. 

gerror) ; 

*/ 

exit  (1) ; 

hidemouse ( ) ; 

/*  if  pixel  is  not  black,  make  it  black  */ 
if  (getpixel (2*x+IC0NLEFT, BIGICONTOP+y)  !=  BLACK)  ( 

1 

1 

putpixel (2*x+IC0NLEFT, BIGICONTOP+y, BLACK) ; 

void  show  icon (void) 

putpixel (2*x+l+IC0NLSFT, BIGICONTOP+y, BLACK) ; 

i 

icon [y| [x]  =  0; 

) 

/*  This  function  displays  the  icon  pattern  stored  in  the 
*  icon  array. 

else  |  /*  draw  all  pixels  on  with  the  max  color  */ 

*/ 

putpixel (2‘x+ICONLEFT, BIGICONTOP+y, getmaxcolor () ) ; 
putpixel (2*x+l+ICONLSFT, BIGICONTOP+y, getmaxcolor ( ) ) ; 

int  x,  y; 

icon [y] [x]  =  1; 

) 

for  (y=0;  yCCONHEIGHT;  y+  +  ) 

showmouse ( ) ; 

for  (x=0;  x< ICONWIDTH;  x++)  ( 

1 

if  (icon [y] [x]  ==  1)  i 

putimage (BIGICONLEFT+2* (x* (BIGBITSIZE+NORM_WIDTH) ) +1, 

BIGICONTOP+y* (BIGBITSIZE+NORM  WIDTH) +1,  bigbit, 

void  save  icon (void) 

XOR  PUT) ; 

{ 

toggle  icons  bit (x,  y); 

/*  This  function  writes  the  icon  pattern  to  a  file.  The  user 

*  is  prompted  for  the  filename.  The  format  of  the  file  is 

*  presented  at  the  top  of  the  iconed.c  file. 

I 

) 

l 

char  filename [80] ; 

FILE  ‘iconfile; 
int  i,  j; 

End  Listing  One 
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Listing  Two 

/*  mouse. c  —  routines  to  support  a  Microsoft  compatible  mouse. 

*  This  package  assumes  that  you  are  running  under 

*  graphics  mode . 

*/ 

((include  <dos.h> 

♦include  <conio.h> 

♦include  "mouse. h" 

♦include  "graphics. h" 

♦define  TRUE  1 
♦define  FALSE  0 

int  mouseexists;  /*  internal  variable  set  true  if  a  */ 

/*  mouse  driver  is  detected  */ 


void  mouse (int  *ml,  int  *m2,  int  ‘m3,  int  *ta4) 

( 

/* 

*  This  function  provides  the  interface  between  the  mouse 

*  driver  and  an  application  program.  Several  predefined  mouse 

*  functions  supported  by  the  Microsoft  mouse  are  available. 

*  Parameters  are  passed  and  returned  with  the  ax,  bx,  cx  and 

*  dx  registers. 

*/ 

union  REGS  inregs,  outregs; 

inregs.x.ax  =  ‘ml; 
inregs. x.bx  =  ‘m2; 
inregs. x.cx  =  *m3; 
inregs. x.dx  =  *m4; 
int86(0x33,  Sinregs,  soutregs); 

*ml  =  outregs. x. ax;  /*  return  parameters  */ 

*m2  =  outregs .x.bx; 

*m3  =  outregs. x.cx; 

*m4  =  outregs .x.dx; 


Listing  Two  (Listing  continued,  text  begins  on  page  24.) 

if  (mouseexists)  { 

ml  =  GET_MOUSE_STATUS ; 
mouse (4ml,  4m2,  x,  y) ; 

/*  adjust  for  virtual  coordinates  */ 
if  (getmaxxl)  ==  319)  (*x)  /=  2; 


int  testbutton (int  testtype,  int  whichbutton) 

( 

/* 

*  This  function  tests  a  mouse  button  state.  It  returns  TRUE 

*  if  the  specified  mouse  button  (whichbutton)  meets  the 

*  specified  action  (as  indicated  by  testtype) ;  otherwise  the 

*  function  returns  FALSE. 

*/ 

int  ml,  m2,  m3,  m4; 
ml  =  testtype; 

if  (whichbutton  ==  LEFT_BUTTON  | I  whichbutton  == 
EITHER_BUTTON)  ( 
m2  =  LEFT_BUTTON ; 
mouse (4ml,  4m2,  4m3,  4m4); 

if  (m2)  return (TRUE) ;  /*  return  TRUE  if  action  ok*/ 

} 

if  (whichbutton  ==  RIGHT_BUTTON  | |  whichbutton  == 
EITHER_BU7T0N)  { 
ml  =  testtype; 
m2  =  RIGHT_BUTTON; 
mouse (4ml, -4m2,  4m3,  4m4) ; 

if  (m2)  return (TRUE) ;  /*  return  TRUE  if  action  ok  */ 

) 

return (FALSE) ;  /*  return  FALSE  as  a  catch  all  */ 


int  initmouse (void) 


/* 

*  This  function  initializes  the  mouse  and  displays 

*  the  mouse  cursor  at  the  top,  left  of  the  screen,  if  one 

*  is  present. 

*/ 

int  ml,  m2,  m3,  m4,  gmode; 

char  far  ‘memory  =  (char  far  *) 0x0G400O049L; 


mouseexists  =  TRUE; 
ml  =  RESET_MOUSE; 
mouse (4ml,  4m2,  4m3,  4m4); 
if  (ml)  |  /* 


gmode  =  getgraphmode () ; 
if  (gmode  ==  HERCMONOHI) 
‘memory  =  0x06; 

( 

ml  =  SET_MOUSE_COORD; 
mouse (4ml,  4m2,  4m3,  4m4), 
showmouseO;  / 


if  mouse  reset  okay,  assume  */ 


/*  mouse  exists  */ 
Test  for  Hercules  */ 


/*  mouse  exists  and  draw  the  */ 
cursor  on  the  screen  at  0,0  */ 
return  a  success  flag  */ 


else  ( 

mouseexists  =  FALSE; 
return  (0) ; 


/‘no  mouse  installed  */ 

/*  return  a  no-mouse  found  flag  */ 


int  waitforinput (int  whichbutton) 

{ 

/*  This  function  returns  a  character  if  a  key  has  been  pressed, 
*  -1  if  a  mouse  button  has  been  pressed;  otherwise  a  zero.  If 

a  mouse  exists,  this  routine  favors  any  keyboard  action. 

*/ 

int  c  =  0; 
while  (!c)  ( 

if  (kbhitO)  /*  check  if  a  key  has  been  pressed  */ 
c  =getch();  /*  return  the  character  */ 
else  { 

if  (testbutton (CHECK_BUTTON  PRESS,  whichbutton))  ( 
while  ( ! testbutton (CHECK_BUTTON_RELEASE, 
whichbutton) ) ; 

c  =  -1; 

) 

else  if  (testbutton (CHECK_BUTTON_RELEASE, 
whichbutton) )  ( 

c  =  -1; 

I 

I 

) 

return (c) ; 


End  Listing  Two 


void  hidemcuse (void) 

( 

/*  This  function  removes  the  mouse  cursor  from  the  screen.  It 

*  should  be  called  before  displaying  data  on  the  screen. 

*  Use  showmouseO  to  redisplay  the  mouse  cursor.  The  mouse 

*  cursor  still  moves  even  though  it  is  not  visible.  Don't 

*  call  hidemouseO  if  the  mouse  is  not  already  visible. 

*/ 

int  ml,  m2,  m3,  m4; 


if  (mouseexists)  ( 
ml  =  HIDE_MOUSE; 
mouse (4ml,  4m2,  4m3, 

) 


/*  check  for  mouse  */ 

/*  hide  the  mouse  cursor  */ 

4m4)  ; 


void  showmouse (void) 

{ 

/*  This  function  displays  the  mouse  cursor.  You  should  not  call 
*  this  function  if  the  mouse  is  already  visible. 

*/ 

int  ml,  m2,  m3,  m4; 

if  (mouseexists)  (  /*  make  sure  mouse  exists  */ 

ml  =  SHOW_MOUSE; 

mouse(4ml,  4m2,  4m3,  4m4);  /*  display  mouse  cursor  */ 

} 

) 


Listing  Three 


/*  mouse. h 


*/ 


—  this  file  includes  function  prototypes  and  macro 
constants  for  the  functions  in  mouse. c. 


/*  The  following  is  a  list  of  constants  that  correspond  to  the 
*  mouse  functions  supported  in  mouse. c. 

*/ 


♦define  RESET_MOUSE  0 

♦define  SHOW_MOUSE  1 

♦define  HIDE_MOUSE  2 

♦define  GET_MOUSE_STATUS  3 

♦define  SET_MOUSE_COORD  4 

♦define  CHECK_BUTTON_PRESS  5 

♦define  CHECK_BUTTON_RELEASE  6 

♦define  SET_MOUSE_HORIZ_RANGE  7 

♦define  SET_MOUSE_VERT_RANGE  8 

♦define  SET_GRAPHICS_CURSOR  9 

♦define  GET_MOUSE_MOVEMENT  11 

♦define  SET  MICKEY  RATIO  15 


/*  not  used  */ 
/*  not  used  */ 
/*  not  used  */ 

/*  not  used  */ 


♦define 

LEFT  BUTTON 

0 

/*  use 

left  button  * 

/ 

♦define 

RIGHT  BUTTON 

1 

/*  use 

right  button 

*/ 

♦define 

EITHER  BUTTON 

2 

/*  use 

either  button 

*/ 

/*  The  function  prototypes  for  the  functions  in  mouse. c 
*/ 


void  getmousecoords (int  *x,  int  *y) 

I 

/* 

*  This  function  returns  the  position  of  the  mouse  cursor. 
*/ 

int  ml,  m2; 


void  mouse(int  ‘ml,  int  ‘m2,  int  ‘m3,  int  *m4); 

int  initmouse (void) ; 

void  getmousecoords (int  *x,  int  *y) ; 

void  hidemouse (void) ; 

void  showmouse (void) ; 

int  testbutton (int  testtype,  int  whichbutton); 
int  waitforinput (int  whichbutton); 


End  Listings 
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AMIGA 


Listing  One  (Text  begins  on  page  36  ) 

Listing  Two 

/*  dualvp.c  -  Dual  Viewports  on  the  amiga 

000208a8 

2b01 : f ffe 

WAIT 

(0C,2b) 

;  (x  =  0,  y  =  43) 

*  Written  4/4/89  by  C.  McManis  using  Lattice  C  5.02 

—  load  color  table  — 

*/ 

000208bc 

008e : 0581 

MOVE 

0561 , diwstrt 

;  (left  =  129,  top  =  5) 

000208c0 

0100:0200 

MOVE 

02C0, bplconO 

linclude  <exec/types .h> 

000208c4 

0104:0024 

MOVE 

0024,bplcon2 

♦include  <exec/memory .h> 

000208c8 

0090 : 40cl 

MOVE 

40cl, diwstop 

;  (right  =  449,  bottom  = 

320) 

linclude  <graphics/gfx.h> 

000208cc 

0092:0038 

MOVE 

0038, ddfstrt 

;  pixel  val  =  112 

linclude  <graphics/view . h> 

000208d0 

0094 : OOdO 

MOVE 

OOdO, ddf stop 

;  pixel  val  =  416 

linclude  <graphics/gfxbase.h> 

000208d4 

0102:0000 

MOVE 

0000, bplconl 

linclude  <graphics/rastport .h> 

000208d8 

0108:0028 

MOVE 

0028, bpllmod 

extern  struct  GfxBase  *GfxBase; 

000208dc 

010a :  0028 

MOVE 

0028, bpl2mod 

char  *TextString  =  "Amiga  Graphics  Example"; 

000208e0 

OOeO : 0002 

MOVE 

0002, bpllpth 

000208e4 

00e2 : 86e8 

MOVE 

86e8, bpllptl 

/*  Viewport  0  colors  */ 

000208e8 

00e4 : 0002 

MOVE 

0002, bpl2pth 

DWORD  colorsO (4 J  =  (Oxccc,  0x000,  OxOfO,  0x00f], 

000208ec 

00e6 : c568 

MOVE 

c568, bpl2ptl 

/*  Viewport  1  colors  */ 

000208f 0 

2c01 : ff fe 

WAIT 

(00,2c) 

;  (x  =  0,  y  =  44) 

colorsl[4]  =  (OxOfO,  OxcOc,  OxfOO,  Oxfff); 

000208f 4 

0100:2200 

MOVE 

2200, bplconO 

void 

000208  f  8 

dbOl : f f fe 

WAIT 

(00, db) 

;  (x  =  0,  y  =  219) 

main  () 

000208fc 

0100:0200 

MOVE 

0200, bplconO 

{ 

00020900 

deOl : f ffe 

WAIT 

'00, de) 

;  (x  =  0,  y  =  222) 

struct  View  MyView,  ‘OldView; 

—  load  color  table  — 

struct  Viewport  VpO,  Vpl; 

00020914 

008e: 0581 

MOVE 

0581, diwstrt 

;  (left  =  129,  top  =  5) 

struct  BitMap  Bits; 

00020918 

0100:0200 

MOVE 

0200, bplconO 

struct  Raslnfo  MyRaster; 

0002091c 

0104:0024 

MOVE 

0024, bplcon2 

struct  RastPort  rp; 

00020920 

0090 : 40cl 

MOVE 

40cl, diwstop 

;  (right  =  449,  bottom  = 

320) 

int  i; 

00020924 

0092:003c 

MOVE 

003c, ddf strt 

;  pixel  val  =  120 

00020928 

0094:0030 

MOVE 

OOdO, ddfstop 

;  pixel  val  =  416 

/*  Open  the  resident  craphics  library  */ 

0002092c 

0102:0000 

MOVE 

0000, bplconl 

GfxBase  =  (struct  GfxBase  *)OpenLibrary( "graphics. library", 0L) ; 

00020930 

0108:0000 

MOVE 

0000, bpllmod 

if  ( (GfxBase) 

00020934 

010a : 0000 

MOVE 

0000, bpl2mod 

exit (1) ; 

00020938 

OOeO : 0002 

MOVE 

0002, bpllpth 

OldView  =  GfxBase->ActiView;  /*  Save  this  away  */ 

0002093c 

00e2 : 86e8 

MOVE 

86e8, bpllptl 

00020940 

00e4 : 0002 

MOVE 

0002, bpl2pth 

/*  Initialize  the  View  structures  */ 

00020944 

00e6 :c568 

MOVE 

c568, bpl2ptl 

InitView (SMyView) ; 

00020948 

df 01 : f ffe 

WAIT 

(00, df) 

;  (x  =  0,  y  =  223) 

InitVPort (&Vp0) ; 

0002094c 

0100:a200 

MOVE 

a200, bplconO 

InitVPort (&Vpl ) ; 

00020950 

f  30 1 : f ffe 

WAIT 

(00, f 3 ) 

;  (x  =  0,  y  =  243) 

Vpl. Next  =  NULL; 

00020954 

0100:0200 

MOVE 

0200, bplconO 

VpO. Next  =  &Vpl;  /*  create  a  linked  list  of  viewports  */ 

MyView. Viewport.  =  &VpO;  /*  With  the  first  one  being  VpO  */ 

00020958 

ffff :fffe 

WAIT 

(7f,ff) 

;  (x  =  127,  y  =  255) 

/*  Set  up  some  display  memory  */ 

Init3itMap (&Bits,  2,  640,  200); 

Bits. Planes [0]  =  (PLANEPTR) 

AllocMem (2*RASSIZE (640,  200),MEMF  CHIP+MEMF  CLEAR); 

Bits. Planes [1]  =  Bits. Planes (0)  +  RASSIZE(640,  200); 
if  (! Bits .Planes [0] ) 

goto  cleanup; 

MyRaster .BitMap  =  SBits; 

End  Listing  Two 

MyRaster .RxOff set  =  0; 

MyRaster .RyOffset  =  0; 

MyRaster. Next  =  NULL; 

/*  Both  viewports  are  looking  at  the  same  display  memory  but  have 

*  different  sets  of  colors 
*/ 

Listing  Three 

VpO. Raslnfo  =  ^MyRaster; 

VpO.DWidth  =  .320; 

/*  blit.c  -  Demonstrates 

the  benefit  of 

the  blatter. 

VpO.DHeight  =  175; 

*  Written  4/9/89  by  C. 

McManis  using  Lattice  C  5.02 

VpO.ColorMap  =  (struct  ColorMap  * ) GetColorMap (4) ; 

*  The  difference  on  my 

machine  between 

waiting  for  the  blitter 

LoadRGB4 (&Vp0,  colorsO,  4); 

*  to 

complete  before  calculating  the  next  set  of  draw  parameters 

Vpl. Raslnfo  =  SMyRaster; 

*  is 

1.6  vs  1.4  seconds,  about  a  12.5% 

increase  in  speed. 

Vpl.DWidth  =  640; 

Vpl .DHeight  =  20; 

*/ 

Vpl.DyOffset  =  179; 

linclude  <exec/types.h> 

Vpl. Modes  =  HIRES; 

linclude  <exec/memory .h> 

Vpl. ColorMap  =  (struct  ColorMap  * (GetColorMap (4 ) ; 

linclude  <intuition/intuition 

.h> 

LoadRGB4 (SVpl,  colorsl,  4); 

linclude  <graphics/gf x . h> 
extern  struct  IntuitionBase  * 

IntuitionBase; 

/*  Initialize  a  RastPort  so  that  we  can  draw  into  that  memory.  */ 

extern  struct  GfxBase 

* 

GfxBase; 

InitRastPort (4  rp) ; 

struct  NewScreen  NS  =  ( 

rp. BitMap  =  4Bits; 

0,  0, 

/*  Position  on  the  display  */ 

SetAPen(4rp,  1);  /*  Foreground  color  */ 

320,  200,  4, 

/*  Attributes 

(Width,  Height,  Depth)  */ 

SetBPen(4rp,  0);  /*  Background  color  */ 

1,0, 

/*  Detail  and 

Block  pens  */ 

Move(4rp,  3,  12);  /*  Move  the  graphics  cursor  to  (3,  12)  */ 

c, 

/*  ViewModes 

nothing  special  */ 

/*  Write  sometning  */ 

CUSTOMSCREEN, 

/*  It  is  our 

own  screen  we  want  */ 

Text(4rp,  Textstring,  strlen (Textstring) ) ; 

c, 

/*  Using  the 

Default  font  */ 

MakeVPort (4MyView,  4Vp0);  /*  Build  the  copper  iist  for  Viewport  0  */ 

"Blitter 

Test",  /*  With  a  simple  title.  */ 

MakeVPort (4MyView,  4Vol);  /*  Build  the  copper  list  for  Viewport  1  */ 

C, 

/*  No  special 

gadgets  */ 

MrgCop (4MyView) ;  /*  Merge  it  into  the  final  list  */ 

c 

/*  And  no  special  bitmap  */ 

LoadView (4MyView) ;  /*  Show  it  off  */ 

1; 

struct  Screen  ‘MyScreen; 

/*  SPIN  FOR  A  WHILE  */ 

struct  RastPort  ‘RPort; 

for  (i=0;  i<1000000;  i++) 

void 

cleanup (n) 

LoadView (OldView) ;  /*  Return  to  the  old  view  */ 

int  n; 

cleanup; 

I 

if 

(GfxBase) 

/*  Now  give  back  the  memory  other  tasks  may  need  it  */ 

CloseLibrary (GfxBase) ; 

if  (! VpO. ColorMap) 

if 

(MyScreen) 

FreeColorMap (VpO .ColorMap) ; 

CloseScreen (MyScreen) ; 

if  (! Vpl .ColorMap) 

if 

(IntuitionBase) 

FreeColorMap (Vpl .ColorMap) ; 

CloseLibrary (IntuitionBase) ; 

FreeVPortCopLists ( & VpO )  ; 

exit  (n) ; 

FreeVPortCopLists (4Vpl)  ; 

FreeCprList (MyView. LOFCprList) ; 

) 

void 

if  ( (Bits. Planes [0] ) 

main ( ) 

FreeMem(Bits. Planes  r 0 1 .  2*RAS.c;t7:F  (640.  200)); 

( 

in 

i, 

/*  Loop  counter  */ 

CloseLibrary (GfxBase) ; 

exit (0) ; 

x,  y,  c, 
t0. [2] , 

/*  some  random  draw 
/*  Start  Time  */ 

parameters  */ 

1 1  [  2  ] 

/*  End  time  */ 

In 

iuitionBase  = 

(struct  IntuitionBase 

*) 

OpenLibrary ("intuition . library" , 0L) ; 

if 

( !  IntuitionBase) 

cleanup (1) ; 

End  Listing  One 
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GfxBase  =  (struct  GfxBase  *) 

OpenLibrary ( "graphics . library" ,  OL) ; 

if  (!  GfxBase) 

cleanup (1) ; 

/*  This  does  all  of  the  view  construction  for  us  */ 

MyScreen  =  (struct  Screen  *)  OpenScreen (&NS) ; 
if  (IMyScreen) 

cleanup (1) ; 

timer(tO);  /*  Start  the  clock  running  */ 


/*  Get  the  RastPort  of  this  screen  */ 

RPort  =  & (MyScreen->RastPort)  ; 

SetAPen (RPort,  1);  /*  Foreground  pen  =  1  */ 

SetBPen (RPort,  0);  /*  Background  pen  =  0  */ 

srand(42);  /*  set  the  seed  */ 

Move (RPort,  160,  100);  !*  Move  to  the  moiddle  of  the  screen  */ 


/* 

*  Note  we  generate  psuedo  random  numbers  (eg  the  same  set  of 

*  random  numbers  every  time. 

*/ 

for  (i=0;  i<1000;  i++)  ( 

x  =  (rand()  %  300)  +  10; 
y  =  (rand()  %  180)  +  10; 
c  =  rand()  %  16; 

SetAPen (RPort,  c) ; 

Draw (RPort,  x,  y) ; 

#ifdef  WAIT_BLIT 

WaitBlitO;  /*  Simulate  non-coprocessor  */ 

tendif 

) 

timer (tl);  /*  stop  the  clock  */ 

fifdef  WAIT_BLIT 

printfC'With  waiting  for  the  blitter,  we  took  %d  microseconds . \n", 

(tl [0]  -  to (0] )  *  1000000  +  (tl [1]  -  to [1] ) ) ; 

#else 

printf ("Without  waiting  for  the  blitter,  we  took  %d  microseconds. \n", 

(tl [0)  -  t0[0])  *  1000000  +  (tl [1 ]  -  toil])); 

#endif 

cleanup (0) ; 

} 


End  Listings 


IMAGE  MATHEMATICS 


Listing  One  (Text  begins  on  page  45.) 

/*  Created  by  Victor  J.  Duvanenko  10-17-88 

Image  addition  using  the  CPU/80386.  The  program  reads  a  buffer  full  of 
pixels  from  two  images,  adds  their  pixels  together  and  stores  the  result 
back  into  the  second  image. 

*/ 

tinclude  "cmdtypes.h" 
tinclude  <stdio.h> 
tinclude  <setjmp.h> 
tinclude  "const. h" 
tinclude  <fcntl.h> 

extern  int  _fmode;  /*  file  mode  */ 

/*  Digihurst  board  configuration  parameters:  */ 
unsigned  memseg  =  OxDOOO;  /*  memory  segment  */ 

int  pbase  =  0x0208;  /*  port  base  */ 

/*  entire  bitmap  expressed  as  a  RECT:  */ 

RECT  screen  =  {  0,  0,  XRES  -  1,  YRES  -  1  }; 

POINT  vertices!  3  ]; 


extern  jmp_buf  errjmp; 

int  frame_grab  =  0;  /*  frame/field  grab  */ 

int  hiquality  =  0;  /*  use  high  quality  image  reduction  routines?  */ 


/*  current  video  parameters  */ 

int  hue  =  101; 

int  sat  =  111; 

int  con  =  123; 

int  bri  =  40; 


/*  Red,  green  and  blue  buffers 
unsigned  char  red_l [  640  * 

red_2 [  640  * 

green_l (  640  * 
green_2 [  640  * 
blue_l [  640  * 

blue_2 [  640  * 


-  all  buffers  fit 
13  ), 

13  ], 

13  ], 

13  ], 

13  ), 

13  ] ; 


within  one  64K  segment 


*/ 


main (argc, argv) 
int  argc; 
char  *argv[); 


register 

i,  tmp,  line; 

/*  use  registers  for 

speed 

*/ 

RECT 

image 1 ; 

*/ 

int 

saturate; 

/*  saturation  flag 

unsigned  char 

* r l_p ,  *r2_p. 

/*  pointers  to  red 

pixel 

values 

*/ 

*gi_p,  *g2_p, 

/*  pointers  to  green 

pixel 

values 

*/ 

*bl  p,  *b2  p; 

/*  pointers  to  blue 

pixel 

values 

*/ 

/*  initialize  the  board  */ 
/*  display  image  two  */ 


/*  ADD  with  saturate 


*/ 


cmd_init (  OxDOOO,  0x208  ); 
cmd_di splay (  2  )  ; 

saturate  =  TRUE; 

/*  ADD  two  images  using  the  CPU  (80386) .  */ 

/*  Do  it  in  13  line  chunks,  to  be  able  to  fit  all  of  the  buffers  */ 

/*  in  one  64K  memory  segment.  */ 

for(  line  =  0;  line  <  480;  line  +=  13  ) 

( 

/*  initialize  image  pointers  */ 

rl  p  =  red  1;  /*  red  pixel  portion  of  image  1  */ 

r2~p  =  red~2;  /*  red  pixel  portion  of  image  2  */ 

gl_p  =  greenl; 

g2  p  =  green_2; 

bl_p  =  blue_l; 

b2_p  =  blue_2; 

/*  read  13  lines  of  images  1  and  2  */ 

imagel.llx  =  0; 

imagel.lly  =  line; 

imagel.urx  =  639; 

imagel.ury  =  line  +  12; 

cmd  read  area(  1,  Simagel,  red_l,  green_l,  blue_l  ); 

cmd_read_area (  2,  simagel,  red_2,  green_2,  blue_2  ); 

/*  Add  the  pixel  values  of  image  1  to  image  2.  */ 

/*  Use  unmodified  addition  if  saturation  effect  is  not  requested.  */ 
/*  If  saturation  is  requested  promote  pixels  to  integer  data  type,  */ 
/*  add  two  integer  values  (guarantees  no  overflow),  saturate,  */ 

/*  demote  back  to  pixel  data  type,  and  place  the  result  in  image  2.  */ 
if  (  ! saturate  ) 


for(  i  =  0;  i  <  640  *  13;  i+ 

{ 

*r2_p++  +=  *rl_p++; 
*g2_p++  +=  *gl_p++; 
*b2_p++  +=  *bl_p++; 


) 


) 


640 


for(  i  =  0; 

{ 

tmp  =  (int) (  *r2_p  )  +  (int)  ( 
if  (  tmp  >  255  )  tmp  -  255; 
*r2_p++  =  (unsigned  char) (  tmp  ) 


13;  i++,  rl_p++,  gl_p++,  bl_p++  ) 

1_P  )  t 

/*  saturate  */ 


tmp  =  (int) (  *g2_p  )  +  (int) (  *gl_p  ); 

if  (  tmp  >  255  )  tmp  =  255;  /*  saturate  */ 

*g2_p++  =  (unsigned  char) (  tmp  ) ; 

tmp  =  (int) (  *b2_p  )  +  (int)  (  *bl_p  ); 

if  (  tmp  >  255  )  tmp  =  255;  /*  saturate  */ 

*b2_p++  =  (unsigned  char) (  tmp  ) ; 

) 

/*  Place  the  result  (buffer  2)  back  into  image  2  */ 
cmd_write_area (  2,  Simagel,  red_2,  green_2,  blue_2,  0  ); 


return (  0  ) ; 
/*  end  main  */ 


End  Listing  One 


Listing  Two 

- - - - - 

Procedure  to  ADD  two  preloaded  images  together. 

Procedure  that  is  an  extension  to  ' cmd_copy_image' .  It  performs 
the  image  copy  with  an  ADD  operation. 

This  procedure  figures  out  which  of  the  3  bitmaps  is  not  being  used 
for  the  operation  and  uses  it  for  scratch  space.  The  effected  area 
is  at  the  same  location  as  the  destination.  The  user  has  to  be  aware 
of  this. 


static  void  add_blt (  from_bm,  image,  to_bm,  to_x,  to_y,  saturate  ) 
int  from_bm; 

RECT  ‘image; 

int  to_bm, 

to_x, 
to_y, 

saturate;  /*  1  -  saturate,  0  -  don't  saturate  */ 

{ 

register  i; 

int  scratch_bm,  one_used,  two_used,  three_used; 

unsigned  int  mask; 

RECT  to_image, 

to_imagel;  /*  1  bpp  coordinates  */ 

/*  Figure  out  which  bitmap  is  not  used  in  the  operation  and  use  it  */ 
/*  for  scratch  space.  */ 

one  used  =  two_used  =  three_used  =0; 


if 

{  from  bm  ==  1  1 ! 

to  bm  ==  1 

one  used  =  1; 

if 

(  from  bm  ==  2  ! | 

to  bm  ==  2 

two  used  =  1; 

if 

(  from  bm  ==  3  ! ! 

to  bm  ==  3 

three  used  =  1; 

if 

(  lone  used  ) 
scratch  bm  =  1; 

else  if  (  !two  used  ) 
scratch  bm  =  2; 

els 

scratch  bm  =  3; 
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to_image.llx  =  to_x; 
to_image.lly  =  to_y; 

to_image.urx  =  to_x  +  (  image->urx  -  image->llx  ); 
to_image.ury  =  to_y  +  (  image->ury  -  image->lly  ); 

/*  Adjust  X  only  for  8  bpp  to  1  bpp  conversion  */ 
tO_imagel . llx  =  to_x  «  3; 
to_imagel . lly  =  to_y; 

to_imagel . urx  =  ((  to_image.urx  +  1  )  «  3)  —  1 ; 
to_imagel . ury  =  to_image.ury; 


/*  Place  a  copy  of  the  destination  image  in  scratch  space  */ 
cmd_copy_image {  to_bm,  &to_image,  scratch_bm,  to_x,  to_y,  0  ); 

/*  Form  the  XOR/SUM  result,  in  the  destination  bitmap  */ 
cmd_copy_image (  from_bm,  image,  to_bm,  to_x,  to_y,  1  ); 

/*  Form  the  AND/CARRY  result,  in  the  scratch  bitmap  */ 
cmd_copy_image {  from_bm,  image,  scratch_bm,  to_x,  to_y,  2  ); 


/*  Now  bit  0  of  all  pixels  is  done  */ 

/*  The  sum  0  is  already  in  destination  bitmap  and  carry  0  is  in  AND  */ 


/*  We  now  need  to  form  the  sum  1,  which  is  the  XOR  of  bit  1  and  carry  0*/ 
/*  This  requires  bit  1  of  destination  bitmap  to  be  XOR'ed  with  bit  0  of*/ 
/*  the  AND/CARRY  bitmap.  The  result  is  placed  in  the  destination.  */ 


/*  This  can  not  be  accomplished  at  8  bpp,  as  all  operations  happen  on  */ 
/*  pixel  boundaries  -  8  bits.  Therefore,  from  this  point  forward  we  */ 
/*  must  treat  our  bitmap  as  1  bpp,  since  this  allows  single  bit  */ 
/*  manipulation.  */ 


for(  i  =  1,  mask  =  0x0202;  i  <  8;  i++,  mask  «=  1  ) 

{ 

/*  Form  the  sum  of  bit  i.  */; 

cmd_wm_copy_image (  scratch_bm,  sto_imagel,  to_bm,  to_imagel . llx  -  1, 
to_imagel . lly,  1,  mask,  1  ); 

if  ({  mask  ==  0x8080  )  &&  (  (saturate  )) 

break;  /*  don't  form  the  cary  -  done!*/ 

/*  Form  the  carry  bit  i  by  first  using  the  carry  in  and  AND'ing  */ 

/*  it  with  ! SUM  */ 

cmd_wm_copy_image (  to_bm,  &to_imagel,  scratch_bm,  to_imagel . llx  +  1, 
to_imagel . lly,  6,  mask  »  1,  1  ); 


} 

#if  0 
/* 
/* 
if 


/*  Form  the  OR  part  of  the  carry  bit  i.  */ 
cmd_wm_copy_image (  scratch_bm,  &to_imagel,  scratch_bm, 

to_imagel .llx  -  1,  to_imagel .lly,  3,  mask,  1  ); 


the  old  method  -  took  8  blits  */ 

Saturate  the  color  based  on  the  carry(7).  */ 

(  saturate  ) 

for  (  i  ■  7,  mask  =  0x0101;  i  >=  0;  i — ,  mask  «=  1  ) 

cmd_wm_copy_image (  scratch_bm,  &to_irnagel,  to_bm,  to_imagel . llx  +  i, 


#endif 

/* 

if 


to_imagel . lly,  3,  mask,  1  ); 

new  and  faster  algorithm  -  takes  only  4  blits  */ 

(  saturate  ) 


/*  replicate  carry[7]  throughout  the  whole  pixel  of  scratch  space  */ 
cmd_wm_copy_image (  scratch_bm,  &to_imagel,  scratch_bm, 

to_imagel . llx  +  1,  to_imagel . lly,  0,  0x4040,  1  ); 
cmd_wm_copy_image (  scratch_bm,  &to_imagel,  scratch_bm, 

to_imagel .llx  +  2,  to_imagel . lly,  0,  0x3030,  1  ); 
cmd_wm_copy_image (  scratch_bm,  &to_imagel,  scratch_bm, 

to_imagel . llx  +  4,  to_imagel . lly,  0,  OxOfOf,  1  ); 


} 


/*  saturate  the  image  all  bits  at  once  */ 

cmd_wm_copy_image (  scratch_bm,  &to_imagel,  to_bm,  to_imagel . llx, 
to_imagel.lly,  3,  Oxffff,  1  ); 


/*  Restore  modified  bitmaps  to  8  bpp  */ 
set_gpbitmap_bpp(  to_bm,  8  ); 

set_gpbitmap_bpp (  scratch  bm,  8  ); 

} 

/* - - - - - 

Procedure  that  subtracts  two  preloaded  images. 

Procedure  that  is  an  extension  to  ' cmd_copy_image' .  It  performs 
the  image  copy  with  an  SUB  operation. 

This  procedure  figures  out  which  of  the  3  bitmaps  is  not  being  used 
for  the  operation  and  uses  it  for  scratch  space.  The  effected  area 
is  at  the  same  location  as  the  destination.  The  user  has  to  be  aware 
of  this. 

- */ 

static  void  sub_blt (  from_bm,  image,  to_bm,  to_x,  to_y,  saturate  ) 
int  from_bm; 

RECT  * image; 

int  to_bm, 

to_x, 
to_v, 

saturate;  /*  1  -  saturate,  0  -  don't  saturate  */ 


register  i; 

int  scratch_bm,  one_used,  two_used,  three_used; 

unsigned  int  mask; 

RECT  to_image, 

to_imagel;  /*  1  bpp  coordinates  */ 


/*  Figure  out  which  bitmap  is  not  used  in  the  operation  and  use  it  */ 
/*  for  scratch  space.  */ 

one_used  =  two_used  =  three_used  =  0; 
if  (  from_bm  ==  1  | |  to_bm  ==  1  ) 

one_used  =  1; 

if  (  from_bm  ==  2  ! ;  to_bm  ==  2  ) 

two_used  =  1; 


if  (  from_bm  ==  3  | !  to_bm  ==  3  ) 

threeused  =  1; 
if  (  !one_used  ) 
scratch_bm  =  1; 
else  if  (  Itwoused  ) 
scratch_bm  =  2; 

else 

scratch_bm  =  3; 

to_image.llx  =  to_x; 
to_image.lly  =  to_y; 

to_image.urx  =  to_x  +  (  image->urx  -  image->llx  ); 
to_image.ury  =  to_y  +  (  image->ury  -  image->lly  ); 

/*  Adjust  X  only  for  8  bpp  to  1  bpp  conversion  */ 
to_imagel . llx  =  to_x  «  3; 
to_imagel . lly  =  to_y; 

to_imagel.urx  =  ((  to_image.urx  +  1  )  «  3  )  -  1; 
to_imagel .ury  =  to_image .ury; 

/*  Place  a  copy  of  the  destination  image  in  scratch  space  */ 
cmd_copy_image (  to_bm,  &to_image,  scratch_bm,  to_x,  to_y,  0  ); 

/*  Form  the  XOR/SUM  result,  in  the  destination  bitmap  */ 
cmd_copy_image (  from_bm,  image,  to_bm,  to_x,  to_y,  1  ); 

/*  Form  the  AND/CARRY  result,  in  the  scratch  bitmap  */ 
cmd_copy_image (  from_bm,  image,  scratch_bm,  to_x,  to_y,  6  ); 


/*  Now  bit  0  of  all  pixels  is  done  */ 

/*  The  sum  0  is  already  in  destination  bitmap  and  carry  0  is  in  AND  */ 
/*  We  now  need  to  form  the  sum  1,  which  is  the  XOR  of  bit  1  and  carry  0*/ 
/*  This  requires  bit  1  of  destination  bitmap  to  be  XOR'ed  with  bit  0  of*/ 
/*  the  AND/CARRY  bitmap.  The  result  is  placed  in  the  destination.  */ 

/*  This  can  not  be  accomplished  at  8  bpp,  as  all  operations  happen  on  */ 
/*  pixel  boundaries  -  8  bits.  Therefore,  from  this  point  forward  we  */ 
/*  must  treat  our  bitmap  as  1  bpp,  since  this  allows  single  bit  */ 
/*  manipulation.  */ 


for(  i  =  1,  mask  =  0x0202;  i  <  8;  i++,  mask  «=  1  ) 


/*  Form  the  sum  of  bit  i.  */; 

cmd_wm_copy_image (  scratch_bm,  &to_imagel,  to_bm,  to_imagel . llx  -  1, 
to_imagel . lly,  1,  mask,  1  ); 

if  ((  mask  ==  0x8080  )  &&  (  ! saturate  )) 

break;  /*  don't  form  the  cary  -  done!  */ 


/*  Form  the  carry  bit  i  by  first  using  the  carry  in  and  AND'ing  */ 

/*  it  with  ! SUM  */ 

cmd_wm_copy_image (  to_bm,  &to_imagel,  scratch_bm,  to_imagel . llx  +  1, 
to_imagel . lly,  2,  mask  »  1,  1  ); 

/*  Form  the  OR  part  of  the  carry  bit  i.  */ 
cmd_wm_copy_image (  scratch_bm,  &to_imagel,  scratch_bm, 

toimagel . llx  -  1,  to_imagel . lly,  3,  mask,  1  ); 

) 

♦  if  0 

/*  Saturate  the  color  based  on  the  borrow (7).  */ 
if  (  saturate  ) 

for  (  i  =  7,  mask  =  0x0101;  i  >=  0;  i — ,  mask  <<=  1  ) 
cmd_wm_copy_ image (  scratch_bm,  &to_imagel,  to_bm, 

to_imagel . llx  +  i,  to_imagel . lly,  6,  mask,  1  ); 

♦endif 

/*  new  and  faster  algorithm  -  takes  only  4  blits  */ 
if  (  saturate  ) 


/*  replicate  carry (7)  throughout  the  whole  pixel  of  scratch  space  */ 
cmd_wm_copy_image (  scratch_bm,  &to_imagel,  scratch_bm, 

to_imagel .llx  +  1,  to_imagel . lly,  0,  0x4040,  1  ); 
cmd_wm_copy_image (  scratch_bm,  &to_imagel,  scratch_bm, 

to_imagel . llx  +  2,  to_imagel . lly,  0,  0x3030,  1  ); 
cmd_wm_copy_image (  scratch_bm,  Sto_imagel,  scratch_bm, 

to_imagel . llx  +  4,  to_imagel . lly,  0,  OxOfOf,  1  ); 


/*  saturate  the  image  all  bits  at  once  */ 
cmd_wm_copy_image (  scratch_bm,  &to_imagel,  to_bm, 
to_imagel . lly,  6,  Oxffff,  1  ); 


to_imagel . llx, 


/*  Restore  modified  bitmaps  to  8  bpp  */ 
set_gpbitmap_bpp (  to_bm,  8  ); 

set_gpbitmap_bpp (  scratch_bm,  8  ); 


End  listings 
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Listing  One  (Text  begins  on  page  56.) 

program  FDemo; 

uses  Grt,  Forms,  Sliders; 

type 

Person  =  record 
Firstname:  string [30); 

Lastname:  string [30]; 

Address:  string [32]; 

City:  string(16]; 

State:  string [2]; 

Zipcode:  Longint; 

Counter:  array[1..3]  of  Longint; 

Slider:  array [1.. 2]  of  Integer; 
end; 

const 

Frank:  Person  =  ( 

Firstname:  'Frank'; 

Lastname:  'Borland'; 

Address:  '1800  Green  Hills  Road'; 

City:  'Scotts  Valley'; 

State:  'CA'; 

Zipcode:  95066; 

Counter:  (10,  1000,  65536); 

Slider:  (85,  25)); 


F:  Form; 

P:  Person; 

begin 

Color (BackColor) ; 

ClrScr; 

Color (ForeColor) ; 

GotoXY (1,  1);  ClrEol; 

Write('  Turbo  Pascal  5.5  Object  Oriented  Forms  Editor'); 

GotoXY (1,  25);  ClrEol; 

Write ('  F2-Save  Esc-Quit'); 

F.Init(10,  5,  54,  16); 

F. Add (New (FStrPtr,  Init(3,  2,  '  Firstname  ',  30))); 

F. Add (New (FStrPtr,  Init(3,  3,  '  Lastname  ',  30))); 

F.Add(New(FStrPtr,  Init  ( 3,  5,  '  Address  ',  32))); 

F . Add ( New (FStrPtr,  Init  (3,  6,  '  City  ',  16))); 

F. Add (New (FStrPtr,  Init  (25,  6,  '  State  ',  2))); 

F .Add (New (FZipPtr,  Init  (34,  6,  '  Zip  ' ) ) ) ; 

F.Add(New(FIntPtr,  Init (3,  8,  '  Counter  1  ' ,  0,  99999999))); 

F .Add (New (FIntPtr,  Init  (22,  8,  '  2  ' ,  C,  99999999))); 

F .Add (New (FIntPt r,  Init (33,  8,  '  3  ',  0,  99999999))); 

F .Add (New (FSliderPtr,  Init  (3,  10,  '  Slider  One  ',  0,  100,  5))); 

F . Add (New (FSliderPtr,  Init  (3,  11,  '  Slider  Two  ',  0,  100,  5))); 

P  :=  Frank; 

F .Put (P) ; 

F  .Show; 

if  F . Edit  =  CSave  then  F.Get(P); 

F  .Done; 

NormVideo; 

ClrScr; 

WriteLn (' Resulting  Person  record:'); 

WriteLn; 
with  P  do 
begin 

WriteLn('Firstname:  ',  Firstname); 

WriteLn ('  Lastname:  ',  Lastname); 

WriteLn ('  Address:  ',  Address); 

WriteLn ('  City:  ',  City); 

WriteLn('  State:  ',  State); 

WriteLn ('  Zipcode:  ',  Zipcode); 

WriteLn('  Counters:  ',  Counter(l),  '  ',  Counter[2],  '  ',  Counter[3]); 
WriteLn  ('  Sliders:  ',  Slider [1],  '  ',  Slider [2]); 
end; 
end. 


End  Listing  One 


Listing  Two 

unit  Forms; 

($S-> 

interface 
uses  Crt; 
const 

CSkip  =  A@; 

CHome  =  AA; 

CRight  =  AD; 

CPrev  =  AE; 

CEnd  =  AF; 

CDel  =  AG; 

CBack  =  AH; 

CSave  =  AJ; 

CUndo  =  AR; 

CLeft  =  AS; 

CClear  =  AY; 

CNext  =  AX; 

CQuit  =  A[; 

type 

FStringPtr  =  AFString; 
FString  =  string [79]; 


FieldPtr  =  AField; 

Field  =  object 
Next:  FieldPtr; 

X,  Y,  Size:  Integer; 

Title:  FStringPtr; 

Value:  Pointer; 

constructor  Init (PX,  PY,  PSize:  Integer;  PTitle:  FString); 
destructor  Done;  virtual; 
procedure  Beep;  virtual; 
function  Edit:  Char;  virtual; 
function  ReadChar:  Char;  virtual; 
procedure  Show;  virtual; 
function  Prev:  FieldPtr; 
end; 

FTextPtr  =  AFText; 

FText  =  object (Field) 

Len:  Integer; 

constructor  Init(PX,  PY,  PSize:  Integer;  PTitle:  FString; 

PLen :  Integer) ; 
function  Edit:  Char;  virtual; 
procedure  GetStr(var  S:  FString);  virtual; 
function  PutStr(var  S:  FString):  Boolean;  virtual; 
procedure  Show;  virtual; 
procedure  Displaytvar  S:  FString); 
end; 

FStrPtr  =  AFStr; 

FStr  =  object (FText) 

constructor  Init(PX,  PY :  Integer;  PTitle:  FString;  PLen:  Integer); 
procedure  GetStr(var  S:  FString);  virtual; 
function  PutStr(var  S:  FString):  Boolean;  virtual; 
end; 

FIntPtr  =  AFInt; 

FInt  =  object (FText) 

Min,  Max:  Longint; 

constructor  Init  (PX,  PY:  Integer;  PTitle:  FString; 

PMin,  PMax:  Longint); 

procedure  GetStr(var  S:  FString);  virtual; 
function  PutStr(var  S:  FString):  Boolean;  virtual; 
end; 

FZipPtr  =  AFZip; 

FZip  =  object (FInt) 

constructor  Init  (PX,  PY:  Integer;  PTitle:  FString); 
procedure  GetStr(var  S:  FString);  virtual; 
function  PutStr(var  S:  FString):  Boolean;  virtual; 
end; 

FormPtr  =  "Form; 

Form  =  object 

XI,  Yl,  X2,  Y2:  Integer; 

Last:  FieldPtr; 

constructor  Init(PXl,  PY1,  PX2,  PY2 :  Integer); 
destructor  Done;  virtual; 
function  Edit:  Char;  virtual; 
procedure  Show;  virtual; 
procedure  Add(P:  FieldPtr); 
function  First:  FieldPtr; 
procedure  Get(var  FormBuf); 
procedure  Put(var  FormBuf); 
end; 

Colorlndex  =  (BackColor,  ForeColor,  TitleColor,  ValueColor) ; 
procedure  Color (C:  Colorlndex); 
implementation 
type 

Bytes  =  array [0. .32767]  of  Byte; 

procedure  Abstract (Method:  String); 
begin 

WriteLn ('Error:  Call  to  abstract  method  ',  Method); 

Halt  (1)  ; 
end; 

(  Field  ) 

constructor  Field. Init  (PX,  PY,  PSize:  Integer;  PTitle:  FString); 
begin 
X  :=  PX; 

Y  :=  PY; 

Size  :=  PSize; 

GetMem(Title,  Length  (PTitle)  +  1); 

TitleA  :=  PTitle; 

GetMem(Value,  Size) ; 

FillChar (ValueA,  Size,  0); 
end; 

destructor  Field. Done; 
begin 

FreeMem (Value,  Size) ; 

FreeMem (Title,  Length(TitleA)  +  1); 
end; 

procedure  Field. Beep; 
begin 

Sound (500);  Delay (25);  NoSound; 
end; 

function  Field. Edit:  Char; 
begin 

Abstract (' Field. Edit' ) ; 
end; 


(continued  on  page  96) 
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listing  Two  (Listing  continued,  text  begins  on  page  56.) 

function  Field. ReadChar:  Char; 
var 

Ch:  Char; 
begin 

Ch  :=  ReadKey; 
case  Ch  of 
#0: 

case  ReadKey  of 


#15, 

#72 

Ch  :=  CPrev; 

(  Shift-Tab,  Up 

#60 

Ch 

=  CSave; 

(  F2  } 

#71 

Ch 

=  CHome; 

(  Home  ) 

#75 

Ch 

=  CLeft; 

(  Left  ) 

#77 

Ch 

=  CRight; 

(  Right  ) 

#79 

Ch 

=  CEnd; 

(  End  ) 

#80 

Ch 

=  CNext; 

(  Down  ) 

#83 

Ch 

=  CDel; 

{  Del  | 

else 

Ch 

=  CSkip; 

end; 

#9,  #13: 

Ch 

=  CNext; 

(  Tab,  Enter  ) 

end; 

ReadChar 

=  Ch; 

end; 


procedure  Field. Show; 
begin 

Abstract (' Field. Show' ) ; 
end; 

function  Field. Prev:  FieldPtr; 
var 

P:  FieldPtr; 
begin 

P  :=  0Self; 

while  P*.Next  <>  @Self  do  P  :=  P*.Next; 

Prev  :=  P; 
end; 

1  FText  } 

constructor  FText . Init (PX,  PY,  PSize:  Integer;  PTitle:  FString; 

PLen:  Integer); 
begin 

Field. Init  (PX,  PY,  PSize,  PTitle); 

Len  :=  PLen; 
end; 

function  FText. Edit:  Char; 
var 

P:  Integer; 

Ch:  Char; 

Start,  Stop:  Boolean; 

S:  FString; 
begin 
P  :=  0; 

Start  :=  True; 

Stop  :=  False; 

GetStr(S) ; 
repeat 
Display (S) ; 

GotoXY (X  +  Length (Title*)  +  P,  Y); 

Ch  :=  ReadChar; 
case  Ch  of 
132.  .#255: 
begin 

if  Start  then  S  :=  " ; 
if  Length (S)  <  Len  then 
begin 
Inc (P) ; 

Insert (Ch,  S,  P); 
end; 
end; 

CLeft:  if  P  >  0  then  Dec(P); 

CRight:  if  P  <  Length (S)  then  Inc(P)  else; 

CHome:  P  :=  0; 

CEnd:  P  :=  Length  (S); 

CDel :  Delete (S,  P  +  1,  1); 

CBack: 

if  P  >  0  then 
begin 

Delete  (S,  P,  1); 

Dec  (P) ; 
end; 

CClear : 
begin 

S  :=  "; 

P  :=  0; 
end; 

CUndo : 
begin 

GetStr(S) ; 

P  :=  0; 
end; 

CSave,  CNext,  CPrev: 
if  PutStr (S)  then 
begin 
Show; 

Stop  :=  True; 
end  else 
begin 
Beep  ; 

P  :=  0; 
end; 


CQuit:  Stop  :=  True; 
else 
Beep; 
end; 

Start  :=  False; 
until  Stop; 

Edit  :=  Ch; 
end; 

procedure  FText .GetStr (var  S:  FString); 
begin 

Abstract (' FText .GetStr' ) ; 
end; 

function  FText. PutStr (var  S:  FString):  Boolean; 
begin 

Abstract (' FText .PutStr' ) ; 
end; 

procedure  FText. Show; 
var 

S:  FString; 
begin 

GetStr (S) ; 

Display (S) ; 
end; 

procedure  FText .Display (var  S:  FString); 
begin 

GotoXY (X,  Y); 

Color (TitleColor) ; 

Write (Title*) ; 

Color (ValueColor) ; 

Write  (S,  Len  -  Length  (S)); 
end; 

(  FStr  ) 

constructor  FStr . Init (PX,  PY:  Integer;  PTitle:  FString;  PLen:  Integer); 
begin 

FText. Init (PX,  PY,  PLen  +  1,  PTitle,  PLen) ; 
end; 

procedure  FStr .GetStr (var  S:  FString); 
begin 

S  :=  FString (Value*) ; 
end; 

function  FStr. PutStr (var  S:  FString):  Boolean; 
begin 

FString (Value*)  :=  S; 

PutStr  :=  True; 
end; 

(  FInt  ) 

constructor  FInt . Init (PX,  PY:  Integer;  PTitle:  FString; 

PMin,  PMax:  Longint) ; 
var 

L:  Integer; 

S:  string(15]; 
begin 

Str(PMin,  S) ;  L  :=  Length (S); 

StrfPMax,  S) ;  if  L  <  Length (S)  then  L  :=  Length (S); 

FText. Init  (PX,  PY,  4,  PTitle,  L) ; 

Min  :=  PMin; 

Max  :=  PMax; 
end; 

procedure  FInt .GetStr (var  S:  FString); 
begin 

Str (Longint (Value*) ,  S) ; 
end; 

function  FInt. PutStr (var  S:  FString):  Boolean; 
var 

N:  Longint; 

E:  Integer; 
begin 

Val(S,  N,  E); 

if  (E  =  0)  and  (N  >=  Min)  and  (N  <=  Max)  then 
begin 

Longint (Value*)  :=  N; 

PutStr  :=  True; 
end  else  PutStr  :=  False; 
end; 

(  FZip  ) 

constructor  FZip. Init (PX,  PY:  Integer;  PTitle:  FString); 
begin 

FInt. Init (PX,  PY,  PTitle,  3,  99999); 
end; 

procedure  FZip. GetStr (var  S:  FString); 
begin 

FInt. GetStr (S) ; 

Insert (Copy (' 0000' ,  1,  5  -  Length (S) ) ,  S,  1); 
end; 

function  FZip. PutStr (var  S:  FString):  Boolean; 
begin 

PutStr  :=  (Length (S)  =  5)  and  FInt .PutStr (S) ; 
end; 

(  Form  ) 
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constructor  Form. Init (PX1,  PY1,  PX2,  PY2:  Integer); 
begin 

XI  :=  PX1; 

Y1  :=  PY1; 

X2  :=  PX2; 

Y2  :=  PY2; 

Last  :=  nil; 
end; 

destructor  Form. Done; 
var 

P:  FieldPtr; 
begin 

while  Last  <>  nil  do 
begin 

P  :=  Last ".Next; 

if  Last  =  P  then  Last  :=  nil  else  Last". Next  :=  P".Next; 

Dispose (P,  Done); 
end; 
end; 

function  Form. Edit:  Char; 

P:  FieldPtr; 

Ch:  Char; 
begin 

Window (XI,  Yl,  X2,  Y2); 

P  :=  First; 
repeat 

Ch  :=  PA .Edit; 
case  Ch  of 

CNext:  P  :=  P".Next; 

CPrev:  P  :=  PA  .Prev; 
end; 

until  (Ch  *  CSave)  or  (Ch  =  CQuit); 

Edit  :=  Ch; 

Windowfl,  1,  80,  25); 
end; 

procedure  Form. Show; 
var 

P:  FieldPtr; 
begin 

Window (XI,  Yl,  X2,  Y2); 

Color (ForeColor) ; 

ClrScr; 

P  :=  First; 
repeat 
PA .Show; 

P  :=  PA .Next; 
until  P  =  First; 

Windowfl,  1,  80,  25); 
end; 

procedure  Form.Add(P:  FieldPtr); 
begin 

if  Last  =  nil  then  Last  :=  P  else  PA.Next  :=  Last". Next; 

Last A. Next  :=  P; 

Last  :=  P; 
end; 

function  Form. First:  FieldPtr; 
begin 

First  :=  Last". Next; 
end; 

procedure  Form. Get (var  FormBuf ) ; 
var 

I:  Integer; 

P:  FieldPtr; 
begin 
I  :  =  0  ; 

P  :=  First; 
repeat 

Move (PA .ValueA,  Bytes (FormBuf) (I) ,  P".Size); 

Inc(I,  PA.Size); 

P  :=  PA.Next; 
until  P  =  First; 
end; 

procedure  Form. Put (var  FormBuf); 
var 

I:  Integer; 

P:  FieldPtr; 
begin 
I  :=  0; 

P  :=  First; 
repeat 

Move (Bytes (FormBuf) [I] ,  PA. Value",  P".Size); 

Inc(I,  P".Size); 

P  :=  PA.Next; 
until  P  =  First; 
end; 

procedure  Color(C:  Colorlndex) ; 
type 

Palette  =  array [Colorlndex]  of  Byte; 
const 

CP:  Palette  =  ($17,  $70,  $30,  $5E) ; 

MP:  Palette  =  ($07,  $70,  $70,  $07); 
begin 

if  LastMode  =  CO80  then  TextAttr  :=  CP [C J  else  TextAttr  :=  MP[C]; 
end; 

end. 


Listing  Three 

unit  Sliders; 
l$S-} 

interface 

uses  Crt,  Forms; 

type 

FSliderPtr  =  "FSlider; 

FSlider  =  object (Field) 

Min,  Max,  Delta:  Integer; 

constructor  Init(PX,  PY:  Integer;  PTitle:  FString; 

PMin,  PMax,  PDelta:  Integer); 
function  Edit:  Char;  virtual; 
procedure  Show;  virtual; 
procedure  Display (I:  Integer); 
end; 

implementation 

constructor  FSlider . Init (PX,  PY:  Integer;  PTitle:  FString; 

PMin,  PMax,  PDelta:  Integer); 
begin 

Field. Init (PX,  PY,  2,  PTitle); 

Min  :=  PMin; 

Max  :=  PMax; 

Delta  :=  PDelta; 
end; 

function  FSlider. Edit:  Char; 
var 

I:  Integer; 

Ch:  Char; 

Stop:  Boolean; 
begin 

I  :=  Integer (Value") ; 

Stop  :=  False; 
repeat 

Display (I)  ; 

GotoXY (X  +  Length (Title")  +  1,  Y); 

Ch  :=  ReadChar; 
case  Ch  of 

CLeft:  if  I  >  Min  then  Deed,  Delta); 

CRight:  if  I  <  Max  then  Inc (I,  Delta); 

CHome:  I  :=  Min; 

CEnd:  I  :=  Max; 

CUndo:  I  :=  Integer (Value") ; 

CSave,  CQuit,  CNext,  CPrev:  Stop  :=  True; 
else 
Beep; 
end; 

until  Stop; 

if  Ch  <>  CQuit  then  Integer (Value")  :=  I; 

Edit  :=  Ch.- 
end; 

procedure  FSlider .Show; 
begin 

Display (Integer (Value") )  ; 
end; 

procedure  FSlider. Display (I:  Integer); 
var 

Steps:  Integer; 

S:  FString; 
begin 

Steps  :=  (Max  -  Min)  div  Delta  +  1; 

S [0]  :=  Chr (Steps) ; 

FillChar (S[l] ,  Steps,  #176); 

S [ (I  -  Min)  div  Delta  +  1]  :=  #219; 

GotoXY (X,  Y); 

Color (TitleColor)  ; 

Write (Title") ; 

Color (ValueColor) ; 

Write ('  ',  Min,  '  ' ,  S,  '  ' ,  Max,  '  '); 
end; 

end. 


End  Listing  Two 


End  Listings 
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Listing  One  (Text  begins  on  page  74.) 


Faster  string  search  routine  to  substitute  the  POS() 
function  in  Turbo  Pascal  4  or  5.  Based  on  the  Boyer-Moore 
algorithm. 

Program  author:  Costas  Menico. 

Declare  as  follows: 

<$F+) 

{$L  search. obj) 

function  posbm(pat,str:string) :  byte;  external; 

Call  as  follows  from  Turbo  4  or  Turbo  5 
location  : =  posbm(pat,  str) ; 


skiparrlength 

equ  256  ; 

Length  of  the  skip  array 

;  Function  work  stack 

dstk  struc 

patlen  dw 

?  ; 

pattern  length  (also  BP  base  work  a 

strlen  dw 

•5  ; 

string  length 

skiparr  db 

skiparrlength  dup(?)  ;  skip  array 

pattxt  dd 

0 

pattern  address 

strtxt  dd 

0 

string  text  address 

dstk  ends 

;  Total  stack 

(Callers  plus  work 

stack) 

cstk  struc 

ourdata  db 

size  dstk  dup(?); 

work  stack  size 

bpsave  dw 

0 

save  bp  here 

retaddr  dd 

0 

points  to  return  address 

straddr  dd 

0 

points  to  string  address 

pataddr  dd 

0 

points  to  pattern  address 

cstk  ends 

paramsize  equ 

size  pataddr  +  size 

straddr  ;  Size  of  parameter  list. 

Dublic  posbm 

Function  name  declaration 

code  segment  para  public  'code 

assume 

cs :code 

;  -  Entry  point  to  POSBM  function. 

posbm  proc 

far 

push 

bp 

Save  BP 

sub 

sp,  size  dstk  ; 

Create  work  area 

mov 

bp,  sp 

Adjust  our  base  pointer 

push 

ds  ; 

Save  callers  data  segment 

xor 

ah,  ah  ; 

Clear  register  and 

cld 

Set  direction  flag 

;  Get  and  save 

the  length  and  address  of  the  pattern 

Ids 

si,  (bp. pataddr] ; 

mov 

word  ptr  [bp. pattxt] [2] ,  ds 

lodsb 

Get  length  of  pattern  (1  byte) 

or 

al,  al 

If  pattern  length  is  null  then  exit 

jne 

notnullp 

jmp 

nomatch 

notnullp: 

mov 

cx,  ax  ; 

Save  length  to  check  if  1  later. 

mov 

[bp. patlen],  ax  ; 

Save  length  of  pattern 

mov 

word  ptr  [bp. pattxt),  si;  Save  address 

Get  and  save 

the  lenath  and  address  of  the  string  text 

Ids 

si,  [bp. straddr] 

mov 

word  ptr  [bp. strtxt] [2] ,  ds 

lodsb 

Get  length  of  string 

or 

a  1 ,  a  1  ; 

If  string  text  is  null  then  exit 

jne 

notnulls 

jmp 

nomatch 

notnulls : 

mov 

[bp. strlen],  ax  ; 

Save  length  of  string 

mov 

word  ptr  [bp. strtxt],  si;  Save  address 

cmp 

cx,  1  ; 

Is  length  of  pattern  1  char? 

jne 

do  boyer  moore  ; 

No  -  Do  Boyer-Moore. 

Ids 

si,  [bp. pattxt]  ; 

Yes  -  Do  a  straight  search. 

lodsb 

Get  the  single  character  pattern. 

les 

di,  [bp. strtxt]  ; 

Get  the  address  of  the  string. 

mov 

cx,  [bp. strlen]  ; 

Get  length  of  string. 

repne 

scasb 

Search. 

jz 

matchl  ; 

Found  -  Adjust  last  DI  pos. 

jmp 

nomatch  ; 

Not  Found  -  Exit. 

matchl : 

mov 

si,  di  ; 

Transfer  DI  pos  to  SI. 

sub 

si,  2  ; 

Adjust  SI  position. 

jmp 

exactmatch  ; 

Determin  offset 

do_boyer_moore : 

;  Fill  the  ascii  character  skiparray  with  the 
;  length  of  the  pattern 

lea  di,  [bp.skiparr]  ;  Get  skip  array  address 


SEARCHES 


mov 

dx,  ss 

mov 

es,  dx 

mov 

al,byte  ptr  [bp. patlen]  ;  Get  size  of  pattern 

mov 

ah,  al 

;  Put  in  to  AH  as  well 

mov 

cx,  skiparrlength 

/  2  ;  Get  size  of  array 

rep 

stosw 

;  Fill  with  length  of  ] 

;  Replace  in  the  ascii  skiparray 

the  corresponding 

;  character  offset  from  the  end  of  the  pattern  minus  1 

Ids 

si,  [bp. pattxt]  ; 

Get  pattern  address 

lea 

bx,  [bp.skiparr]; 

Get  skip  array  address 

mov 

cx,  [bp. patlen]  ; 

Get  length  minus  one. 

dec 

cx 

mov 

bx ,  bp  ; 

save  BP 

lea 

bp,  [bp.skiparr]; 

Get  skip  array  address 

xor 

ah,  ah 

fill  skiparray: 
lodsb 

Get  character  from  pattern 

mov 

di,  ax 

Use  it  as  an  index 

mov 

[bp+di],  cl 

Store  its  offset  in  to  skip 

loop 

f ill_skiparray 

lodsb 

mov 

di,  ax 

mov 

[bp+di],  cl  ; 

Store  the  last  skip  value 

mov 

bp,  bx  ; 

Recover  BP 

;  Now  initialize  our  pattern  and 

string  text  pointers  to 

;  start  searching 

Ids 

si,  [bp. strtxt] 

Get  the  string  address. 

lea 

di,  [bp.skiparr] 

Get  the  skip  array  address. 

mov 

dx,  [bp. strlen] 

Get  the  string  length. 

dec 

dx 

minus  1  for  eos  check. 

mov 

ax,  [bp. patlen] 

Get  the  pattern  length. 

dec 

ax 

Starting  skip  value. 

xor 

bh,  bh 

Zero  high  of  BX. 

std 

Set  to  reverse  compare. 

Get  character  from  text.  Use  the  character  as  an  index 
in  to  the  skip  array,  looking  for  a  skip  value  of  0  . 
If  found,  execute  a  brute  force  search  on  the  pattern. 


searchlast : 

sub 

dx,  ax 

Check  if  string  exhausted. 

jc 

nomatch 

Yes  -  no  match. 

add 

si,  ax 

No  -  slide  pattern  with  skip  value. 

mov 

bl,  [si] 

Get  character,  use  as  an  index 

mov 

al,  ss: [di+bx] 

and  get  the  new  skip  value. 

or 

al,  al 

If  0,  then  possible  match 

jne 

searchlast 

try  again  by  sliding  to  right. 

;  We  have  a  possible  match,  therefore 


;  do  the  reverse  Brute-force  compare 


mov 

bx, 

si 

Save  string  address. 

mov 

cx, 

[bp. patlen] 

Get  pattern  length. 

les 

di, 

[bp. pattxt ] 

Get  pattern  address 

dec 

di 

adjust 

add 

di, 

cx 

and  add  to  point  to  eos. 

repe 

cmpsb 

Do  reverse  compare. 

je 

exactmatch 

If  equal  we  found  a  match 

mov 

ax, 

1 

else  set  skip  value  to  1. 

lea 

di, 

[bp.skiparr] 

Get  address  of  skip  array. 

mov 

si, 

bx 

Get  address  of  string. 

xor 

bh, 

bh 

No  -  Zero  high  of  BX. 

jmp 

short  searchlast 

Try  again. 

exactmatch: 

mov 

ax, 

si 

Save  current  position  in  string. 

Ids 

si, 

[bp. strtxt ] 

Get  start  of  strtxt. 

sub 

ax, 

si 

Subtract  and  add  2  to  get  position 

add 

ax. 

2 

in  strtxt  where  pattern  is  found 

jmp 

short  endsearch 

Exit  function 

nomatch: 

xor 

ax. 

ax 

No  match,  return  a  0 

endsearch: 

cld 

pop 

ds 

Recover  DS  for  Turbo  Pascal 

mov 

sp, 

bp 

Recover  last  stack  position. 

add 

sp, 

size  dstk 

Clear  up  work  area. 

pop 

bp 

Recover  BP 

ret 

paramsize 

Return  with  ax  the  POSBM  value. 

posbm  endp 


code  ends 
end 


End  Listing  One 
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Listing  Two 

{  —  Benchmark  program  to  demonstrate  the  speed  difference 

—  between  the  POS()  in  Turbo  Pascal  4  or  5  brute-force 

—  and  the  Boyer-Moore  Method  function  POSBM() 

—  Program  Author:  Costas  Menico 

} 

program  search; 
uses  dos,crt; 

{  —  Link  in  the  POSBM  Boyer-Moore  function  —  } 

($F+) 

{ $L  POSBM} 

function  posbm(pat, stristring) :byte;  external; 

{  Prints  bencmark  timing  information  } 
procedure  showtime(s:string;  t:  registers); 
begin 

writeln(s,'  Hrs:',t.ch,'  Min:', t. cl,'  Sec:',t.dh,'  Milsec: ' , t . dl ) ; 
end; 

var 

pat,str:  string; 
i: integer; 
j : integer; 

start,  finish:  registers; 
const 

longloop  =  2000; 
begin 
clrscr; 

(  —  Create  a  random  string  of  length  255  —  } 
randomize; 

for  i:=l  to  255  do  str [i] :=chr (random(255) +1) ; 
str [0] :=chr (255) ; 

(  --  Initialize  a  pattern  string  with  the  last  five  characters 
—  in  the  random  string  as  the  pattern  to  search  for.  —  } 
pat :=copy (str, 251,5); 

(  --  First  do  a  search  with  the  regular  POS  function  —  ) 
writeln(' Search  using  Brute-Force  Method'); 
start. ah  :=  $2c; 

msdos (start) ;  (  —  Get  start  time  —  } 

for  j:=l  to  longloop  do 

i :=pos (pat, str) ;  (  —  Do  search  a  few  times  Brute-Force  —  ) 

finish. ah  :=  $2c;  {  —  Get  finish  time  —  ) 

msdos (finish) ; 

showtime ('Start  ', start);  |  --  Show  start  time  --  ) 
showtime ('Finish' , finish) ;  (  —  Show  finish  time  —  } 

writeln (' Pattern  found  at  =',i);  (  —  Print  string  position  —  ) 
writeln; 

f  —  Now  do  search  with  the  POSBM ()  (Boyer-Moore)  function  —  ) 
writeln (' Search  using  Boyer-Moore  Method'); 
start. ah  :=  $2c; 

msdos (start) ;  (  —  Get  start  time  —  ) 

for  j:=l  to  longloop  do 

i :=posbm (pat, str) ; {  —  Do  search  a  few  times  Boyer-Moore  —  ) 

finish. ah  :=  $2c;  (  —  Get  finish  time  —  ) 

msdos (finish)  ; 

showtime (' Start  '.start);  (  —  Show  start  time  —  ) 
showtime (' Finish' , finish) ;  {  —  Show  finish  time  —  ) 

writeln ('Pattern  found  at  =',i);  (  —  Print  string  position  —  ) 

writeln; 

writeln (' DONE. .  PRESS  ENTER'); 
readln; 
end. 


End  Listings 
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IMMAILMM  ?kUQ\GMS 


How  a  No-Nonsense 
Hardware  Engineer 
came  to  Embrace  the 
Parapsychology  of 
Artificial  Intelligence 


“Paradigm  is  a  rather  unlovely  word, 
which  is  commonly  used  in  technical 
writings  when  the  author  wants  to  ob¬ 
scure  the  fact  that  there  are  no  facts  in 
his  writings.  Psychologists  and  psychia¬ 
trists  and  M&T Publishing ’s  writers  are 
especially  fond  of  the  word.  ” 

—  Hal  Hardenbergh 

Hal  Hardenbergh’s  writing  is  gen¬ 
erally  strong  on  factual  content 
or  at  least  on  empirical  content. 
He  is  wont  to  speak  in  what 
philosophers  of  science  call  “highly  falsifi- 
able  assertions.”  He'll  make  an  outra¬ 
geously  bold  claim  and  phrase  it  in 
such  specific  terms  that  it  is  empirically 
testable  on  several  grounds.  Hence  fal- 
sifiable,  though  not  necessarily  false. 

Rarely  false,  in  fact.  When  you  press 
him  on  one  of  his  points  —  or  some¬ 
times  even  without  pressure  —  he  trots 
out  facts  and  figures,  names  and  dates 
to  support  his  position.  When  Harden¬ 
bergh  fingers  his  culprit,  he  usually  has 
a  Zapruder  film  in  his  pocket. 

He’s  also  wont  to  pounce  on  errors 
or  excesses  in  the  use  of  the  English 
language,  as  I  observed  with  chagrin 
the  last  time  I  used  the  word  “wont” 
in  print.  Gremlins  had  slipped  an  apos¬ 
trophe  into  the  word  as  it  went  to  press, 
and  it  was  Hal  Hardenbergh  who  called 
the  error  to  my  attention.  And  he  has 
suggested  that  I  use  the  word  “para¬ 
digm”  too  much.  I  think  he’s  had  his 
eye  on  me  since  I  misspelled  his  name 
some  years  back. 

His  own  publication,  DTACK  GROUND- 


Michoel  Swaine 


ED,  was  always  good  reading  and  em¬ 
bodied  Hardenbergh’s  philosophy  of 
no-nonsense,  pedal-to-the-metal,  get- 
the-HLL-out-of-my-machine  computing. 
He  wrote  and  produced  that  newsletter 
continuously  from  July  1981  to  Sep¬ 
tember  1985  (and  occasionally  thereaf¬ 
ter  with  the  byline  “The  Junk  Mail 
Flyer”).  It  went  out  mainly  to  custom¬ 
ers  of  his  company,  Digital  Acoustics, 


and  carried  twenty-some  pages  a  month 
of  incisive  industry  analysis  and  juicy 
gossip,  tightly-reasoned  technical  dis¬ 
cussions,  and  code.  The  magazine’s 
bias  was  speed;  it  was  a  computer  hard¬ 
ware  hacker’s  hot-rodding  magazine, 
and  Hardenbergh’s  pet  peeve  was  ap¬ 
plication  programs  written  in  high- 
level  languages.  DTACK  GROUNDED 
was  a  far  cry  from  this  column,  and 
while  writing  DTACK  GROUNDED,  Har¬ 
denbergh  would  no  doubt  have  scoffed 
at  the  inefficiency  of  Smalltalk  and 
Prolog  and  at  many  of  the  other  topics 
discussed  in  this  space.  Digital  Acous¬ 
tics  and  DTACK  GROUNDED,  alas,  are 
history,  but  Hardenbergh  has  been  gain¬ 
fully  employed  for  the  past  year  at  Vi- 
com  Systems,  an  image-processing  com¬ 
pany  in  San  Jose,  Calif. 

When  I  heard  that  Hardenbergh  had 
got  into  neural  networks  I  was  sur¬ 
prised.  Neural  networks  represent  a 
branch  of  artificial  intelligence  work 
that  some  might  consider  antithetical 
to  the  hard-nosed  and  the  hands-on. 
The  whole  point  of  neural  nets  was  to 
remove  from  human  hands  a  great  deal 
of  the  control  over  what  the  machine 
was  doing.  And  demonstrable,  practi¬ 
cal  results  of  neural  network  research 
were  hard  to  find.  Furthermore,  exist¬ 
ing  neural  net  implementations  are  slow. 
Agonizingly  slow.  It  seemed  anything 
but  an  area  in  which  you’d  expect  to 
find  an  inveterate  bit-twiddler.  I  de¬ 
cided  to  go  see  Hardenbergh  and  find 
out  what  the  attraction  was. 

The  plan,  as  usual  in  this  column, 
was  to  explore  a  new  paradigm  by 
examining  the  thinking  that  led  one 
computer  professional  to  embrace  that 
paradigm.  Be  forewarned  that  you  will 
probably  not  agree  with  everything  Hal 
Hardenbergh  says.  But  there  is  usually 
much  to  be  learned  from  watching  a 
sharp  mind  slice  through  an  interesting 
problem.  Hardenbergh’s  view  of  the 
history  and  present  value  of  neural  net 
paradigms  is  worth  examining. 

When  I  arrived  at  Vicom,  Hardenbeigh 
led  me  to  a  conference  room  and  of¬ 
fered  me  the  choice  of  an  interview  or 


a  dissertation.  I  told  him  to  start  rolling 
and  that  I’d  break  in  when  I  got  lost. 
In  translating  the  resulting  discussion 
to  the  pages  of  DDJ  I  have  found  it 
desirable  to  break  in  a  little  more  often 
than  was  actually  the  case  during  the 
interview.  Or  dissertation.  But  to  the 
best  of  my  transcriptive  ability,  Harden- 
bergh’s  words  are  Hardenbergh’s  words. 

Cutting  Through  the  Crap 

Swaine:  What’s  the  attraction  of  neu¬ 
ral  networks  for  a  hardware  engineer? 

Hardenbergh:  I  can’t  say  that  what 
I’m  doing  here  at  Vicom  is  dull.  Real¬ 
time  video  processing  is  hardly  boring. 
But  neural  nets  let  me  feel  like  I’m 
pushing  the  envelope  a  little. 

Swaine:  But  how  did  you  settle  on 
neural  nets,  rather  than  some  other 
envelope-pushing  paradigm? 

Hardenbergh:  When  it  comes  to  AI 
and  machine  learning,  you  have  four 
paradigms.  One  is  the  symbolic  ap¬ 
proach  using,  typically,  Lisp,  that  Minsky 
and  Papert  championed  out  of  the  MIT 
AI  Lab.  A  lot  of  money  has  gone  down 
that  rat  hole,  and  now  people  have 
stopped  pouring  because  they  noticed 
that  it  wasn’t  coming  back  up.  The 
second  is  expert  systems.  If  you  want 
to  invest  some  money  in  AI  and  have 
a  reasonable  expectation  of  getting  some¬ 
thing  back,  that’s  where  you  invest  it. 
The  third  paradigm  is  both  very  old 
and  very  new,  and  that’s  neural  net¬ 
works.  And  the  fourth  is  fuzzy  logic. 
To  the  best  of  my  knowledge,  these  are 
the  four;  if  you’re  going  into  AI,  you’ll 
have  to  tackle  one  of  them.  What  the 
three  (that  are  not  neural  networks) 
have  in  common  is  that  they  require 
an  enormous  amount  of  programming 
to  do  anything.  The  potential  advan¬ 
tage  of  neural  networks  is  that  they 
program  themselves. 

Swaine:  How  did  you  first  get  into 
neural  nets? 

(continued  on  page  107) 
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(continued  from  page  100) 
Hardenbergh:  [Vicom  co-worker]  Tom 
Waite  was  looking  into  neural  nets  and 
one  day  I  asked  Tom  to  teach  me  about 
them.  He  put  some  equations  with  in¬ 
tegrals  in  front  of  me.  For  an  engineer 
I’m  a  pretty  decent  mathematician,  but 
I  told  Tom,  “I  know  how  to  add  and 
subtract  and  multiply  and  divide  with 
a  computer,  but  I  don’t  know  what  to 
do  with  this.”  But  eventually  I  got  the 
equations  into  pseudo-Basic  so  I  could 
understand  them. 

Swaine:  You’ve  been  at  it  less  than  a 
year,  then.  But  you 've  done  more  than 
code  some  integrals. 

Hardenbergh:  I’ve  been  taking  classes, 
reading  books,  and  Tom  and  I  have 
submitted  an  article  on  neural  networks 
to  one  of  your  competitors.  (At  the  time 
of  the  interview,  the  Hardenbergh  and 
Waite  article  was  scheduled  for  the  June 
issue  of  Programmer's  Journal ,  a  maga¬ 
zine  that  Hardenbergh  often  writes  for.) 

Swaine:  Neural  networks  is  an  explod¬ 
ing  area  of  research  and  development. 
There’s  a  lot  of  information  to  wade 
through:  1  have  several  rather  thick 
books  on  neural  nets,  and  there  are 
different  models —  the  relationships 
among  which  I  frankly  don’t  under¬ 
stand.  You’ve  apparently  found  a  path 
through  it  all  to  the  information  you 
want. 

Hardenbergh:  I  recommend  an  arti¬ 
cle  by  Lippmann  in  the  April  1987  ASSP 
Magazine  —  that’s  the  IEEE  acoustics 
and  signal  processing  publication  — 
it’s  a  tutorial  on  neural  nets  that  by¬ 
passes  all  the  associative  memory  crap. 

Swaine:  “ Associative  memory  crap”? 

Hardenbergh:  Some  of  what  people 
talk  about  when  they  talk  about  neural 
networks  is  of  interest  from  a  historical 
viewpoint,  but  not  from  the  viewpoint 
of  artificial  intelligence  as  I  understand 
it.  One  of  these  things  is  associative 
memory.  Associative  memory  maps 
ones  and  zeros  into  ones  and  zeros, 
and  it  doesn’t  even  do  that  reliably.  If 
you  think  ones  and  zeros  have  a  lot  of 
intelligence,  you’ll  love  associative  mem¬ 
ory.  Then  there’s  adaptive  bidirectional 
associative  memory,  or  adaptive  reso¬ 
nance  theory  (ART),  by  Grossberg,  who 
has  a  patent  in  this  area.  There’s  a  story 
about  why  he’s  working  on  ART,  rather 
than  something  useful  like  a  multilevel 
perceptron. 

Swaine:  I  gather  that  you ’ve  concluded 
that,  for  your  purposes  at  least,  the 


multilevel  perceptron  is  the  only  ap¬ 
proach  worth  pursuing. 

Hardenbergh:  Multilevel  perceptions  are 
my  idea  of  a  real-world  neural  network. 

Multilevel  Perceptrons 

Swaine:  Tell  me  about  how  you  nar¬ 
rowed  your  own  search  down  to  per¬ 
ceptrons. 

Hardenbergh:  Lippmann  does  a  tax¬ 
onomy.  He  talks  about  Hopfield  nets 
and  Hamming  nets  and  ART,  which, 
like  the  other  two,  is  of  historical  inter¬ 
est  only.  And  he  describes  the  single- 
level  perceptron. 

Swaine:  That  would  be  Rosenblatt’s 
perceptron,  from  back  in  the  late  1950s. 

Hardenbergh:  The  perceptron  was  the 
start  of  all  the  neural  network  work. 
In  1958  Rosenblatt  was  doing  research 
on  natural  neural  nets,  the  wet  stuff, 
and  he  developed  a  model  of  a  simpli¬ 
fied  neuron.  There  were  certain  things 
that  it  could  do.  There  are  still  certain 
things  that  it  can  do.  And  it  generated 
a  lot  of  interest  in  AI  in  1958.  The 
people  in  the  MIT  AI  Lab  became  dis¬ 
turbed  about  funding  moving  over  to 
perceptrons,  and  Minsky  and  Papert 
decided  to  do  something  about  it.  What 
they  did  was  to  start  writing  papers, 
culminating  in  a  book  called  Per¬ 
ceptrons,  with  a  copyright  date  of  1969. 
The  book  demonstrated  that  there  were 
certain  things  that  a  single  perceptron 
cannot  do.  One  of  the  things  that  a 
single  perceptron  cannot  do  is  the  ex- 
clusive-OR  problem. 

Swaine:  That's  not  a  trivial  limitation. 
Back  when  I  was  doing  research  in 
cognitive  psychology,  studying  the  pro¬ 
cess  of  concept  formation,  we  found 
that  modeling  the  human  ability  to form 
concepts  of  the  nature  of  ‘  A  or  B  but 
not  both  ”  was  very  difficult,  but  we  felt 
that  we  didn ’t  have  a  model  of  concept 
formation  without  that  exclusive  OR. 

Hardenbergh:  Oh,  the  difficulties  were 
real  ones.  In  the  meantime  Rosenblatt 
had  suggested  that  one  solution  would 
be  to  use  many  perceptrons,  perhaps 
arranged  in  layers,  but  it  was  only  a 
suggestion,  because  in  1969  a  mathe¬ 
matical  method  of  adjusting  the  weights 
did  not  exist. 

Swaine:  Explain  about  adjusting  the 
weights. 

Hardenbergh:  You  have  the  desired 
output,  call  it  the  target.  You  compare 
the  actual  output  to  the  target  and  mea¬ 


sure  the  error.  Then  you  propagate  the 
error  up  through  the  net  and  use  it  to 
adjust  the  weights  [on  the  connections]. 

Swaine:  So  certain  connections  get 
stronger  over  time,  and  the  network 
responds  more  and  more  appropriately 
as  this  training  proceeds. 

Hardenbergh:  But  you  couldn’t  train 
the  damn  thing,  so  nobody  built  one, 
or  if  they  did,  it  didn’t  work,  so  they 
didn’t  write  about  it.  Minsky  and  Pa- 
pert’s  book  Perceptrons  was  then,  and 
is  today,  highly  regarded,  except  for 
the  last  chapter.  Because  they  had 
proven  that  perceptrons  could  not  solve 
certain  real-world  problems,  they  con¬ 
cluded  that  nothing  along  this  line 
would  ever  be  useful.  The  book  crush- 
ingly  discredited  neural  nets  and  fund¬ 
ing  dried  up  completely. 

The  Politics  of  Discovery 

Swaine:  What  happened  next? 

Hardenbergh:  The  next  events  gener¬ 
ally  known  occurred  in  the  1980s,  but 
in  1974  an  event  occurred  that  was 
known  only  to  two  people.  As  part  of 
his  Ph.D.  research  a  Harvard  graduate 
student,  Paul  Werbos,  developed  the 
mathematical  technique  required  to  train 
multilevel  perceptrons.  His  adviser  was 
Steven  Grossberg. 

Swaine:  This  must  be  the  Grossberg  story. 

Hardenbergh:  Right.  Grossberg  was 
well  aware  of  Minsky  and  Papert’s  work 
on  perceptrons,  and  he  told  this  student 
that  his  work  was  of  no  value.  And 
indeed  it  proved  of  no  value,  because 
it  was  pigeonholed  and  that  was  it. 

Swaine:  That  was  the  technique  of  back 
propagation? 

Hardenbergh:  Yes,  I  guess  it  would 
be  hard  to  do  work  on  multilevel  per¬ 
ceptrons  after  derailing  the  discovery 
of  the  technique  that  makes  them  feasi¬ 
ble.  But  back  propagation  is  known 
now,  and  people  are  doing  work  on 
multilevel  perceptrons. 

Swaine:  What  happened? 

Hardenbergh:  In  the  1980s,  about  a 
dozen  years  later,  things  began  to  hap¬ 
pen.  One  of  the  things  that  happened 
was  Hopfield  nets.  Another  was  that 
Rumelhart  and  others  formed  the  PDP 
group  (at  the  Institute  for  Cognitive 
Science  at  the  University  of  California 
at  San  Diego).  The  PDP  group  attracted 
some  interesting  people  to  work  with 
them,  including  [DNA  co-discoverer] 
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Francis  Crick.  But  in  1982,  another  event 
took  place  that  nobody  knew  about.  A 
22-year-old  Stanford  student  indepen¬ 
dently  invented  the  mathematical  the¬ 
ory  of  back  propagation. 

Swaine:  That  would  be  David  Parker. 
I  interviewed  him  last  year,  but  Pm 
planning  to  talk  with  him  again  soon. 

Hardenbergh:  Parker  discovered  the 
theory  and  went  to  people  who  were 
funding  AI  activities  and  asked  for  fund¬ 
ing.  They  asked,  “Is  this  an  expert  sys¬ 
tem?”  He  didn’t  get  the  funding  and 
eventually  went  off  on  his  own. 

Swaine:  And  then ? 

Hardenbergh:  In  1984  there  was  the 
Hopfield  net,  and  in  1985  there  was  the 
first  public  report  of  a  neural  net  that 
worked  —  barely.  That  was  the  Boltz¬ 
mann  machine  and  its  author  was  G.E. 
Hinton,  and  it  was  slow  even  for  a 
neural  net,  and  neural  nets  have  a  de¬ 
served  reputation  for  being  slow.  Then 
in  1986  there  was  the  publication  by 
Rumelhart,  et  al.  of  “Learning  Internal 
Representations  by  Error  Propagation,” 
the  third  invention  of  back  propagation. 
This  one  led  to  the  current  explosion 
of  interest  in  neural  nets.  Since  then 
there’s  been  a  tremendous  amount  of 
activity. 

Swaine:  So  back  propagation  was  in¬ 
dependently  discovered  three  different 
times ?  What  made  the  difference  the 
third  time  around? 

Hardenbergh:  Rumelhart  was  well 
known;  Parker  wasn’t. 

Smoke  Without  Fire 

Swaine:  There  certainly  has  been,  as 
you  put  it,  an  explosion  of  interest  in 
neural  nets,  but  to  date  it  looks  like  a 
lot  of  smoke  and  very  little  fire.  Expert 
systems  really  are  making  money  for 
people  and  solving  real-world  problems. 

' That  particular  AI  technology,  while  it 
may  not  deserve  all  the  hype  it’s  re¬ 
ceived,  does  have  unarguable  success 
stories  to  tell.  Why  haven ’t  we  seen  any 
breakthrough  practical  applications  of 
neural  net  technology? 

Hardenbergh:  Unfortunately,  neural 
nets  are  slow.  You  can’t  do  neural  nets 
on  a  PC.  And  nobody’s  doing  the  $4,000 
parts-cost  solution.  So  you  need  to  get 
Uncle  Sugar  to  give  you  the  latest  Cray 
full-time  for  a  month. 

Swaine:  Your  mention  of  a  $4,000 
parts-cost  solution  sounds  like  Vicom 
has  a  neural  net  board  in  the  works. 


Hardenbergh:  There’s  interest,  but  no 
commitment  to  a  product  yet.  This  is 
something  Tom  and  I  are  pursuing 
on  our  own.  But  management  doesn’t 
object  to  my  meeting  with  an  editor 
in  the  conference  room  on  company 
time  to  discuss  neural  nets.  They’re 
supportive. 

Swaine:  What  are  the  hardware  issues? 

Hardenbergh:  Floating-point  chips 
these  days  are  so  good  the  real  prob¬ 
lem  is  the  memory  system.  You  can’t 
use  static  RAM.  You  need  to  interleave 
DRAM,  use  multiported  memory.  All 
the  hardware  cards  for  neural  nets  are 
from  software  companies  trying  to  do 
neural  net  work.  None  of  them  are  very 
good  designs. 

Swaine:  What  do  you  think  of  the 
Transputer? 

Hardenbergh:  It’s  fundamentally  flawed 
as  a  concept.  It  has  no  register-to- 
register  add.  It  has  only  three  regis¬ 
ters,  arranged  in  a  stack.  Floating  Point 
Systems  and  the  British  government 
lost  a  lot  of  money  on  the  Transpu¬ 
ter;  Thorne  EMI  went  through  about 
$300,000,000. 

Swaine:  And  the  Occam  programming 
language  developed for  concurrent  pro¬ 
gramming  of  networks  of  Transputers? 

Hardenbergh:  Occam  is  a  failure. 

Swaine:  I’ll  be  talking  to  an  Occam 
programmer  in  a  few  weeks,  so  I’ll  let 
him  defend  the  language  then.  But  is 
there  no  good  work  going  on  in  neural 
nets?  Are  there  no  success  stories? 

Hardenbergh:  All  the  good  stuff  is 
classified.  Chevron  owns  the  seismic 
research.  Parker  may  be  doing  some¬ 
thing  interesting,  but  he  is  not  publish¬ 
ing. 

Swaine:  But  you  think  there  are  things 
that  you  could  do  with  neural  nets, 
given  the  right  hardware? 

Hardenbergh:  In  combination  with 
image-processing  methods.  You  pre- 
process  with  DSP  or  whatever,  and  don’t 
overload  the  network.  Don’t  make  it  do 
what  we  already  have  good  algorithms 
for.  The  company  is  very  interested  in 
the  possibilities.  I’m  enjoying  myself. 

Joke  or  Not,  I  Kept  the  Money 

Swaine:  The  Lippmann  article  says  that 
three  levels  of  perceptrons  not  only 


solve  the  exclusive-OR problem  but  are 
sufficient  for  any  arbitrary  classifica¬ 
tion  problem.  But  you  said  there  were 
certain  things  that  single  perceptrons 
could  do. 

Hardenbergh:  One  spinoff  of  Rosen¬ 
blatt’s  work  was  the  adaptive  linear 
filter.  That  was  a  success,  and  all  of  the 
high-speed  modems  use  it.  The  reason 
the  Telebit  modem  is  so  successful  is 
ALFs.  ALFs  are  used  in  phone  lines  to 
cancel  noise.  An  ALF  is  just  a  single 
perception.  Wait  here.  [Haidenbeigh  got 
up  and  left  the  room.  A  moment  later 
he  returned  and  put  twenty  cents  into 
my  hand.]  It’s  pair  of  dimes.  I’ve  been 
wanting  to  do  that  for  a  long  time. 

Toward  the  end  of  the  interview, 
Tom  Waite  came  into  the  room.  Waite 
and  Hardenbergh  told  me  how  they 
thought  neural  nets  could  supplement 
existing  image-processing  techniques, 
and  Waite  shared  some  ideas  about 
neural  net  algorithms.  It  was  Tom  Waite 
who  gave  me  the  characterization  of 
neural  nets  as  the  parapsychology  of 
artificial  intelligence,  a  characterization 
that  he  does  not  agree  with.  I  will  look 
at  some  of  the  algorithms  next  month. 
I’ll  also  be  talking  with  neural  net  algo- 
rist  David  Parker  again  soon,  and  within 
the  next  two  months  I  hope  to  report 
on  that  discussion,  as  well. as  on  a 
follow-up  interview  with  Jurgen  Fey 
regarding  the  transputer  board  he  has 
designed  specifically  to  support  neural 
networks. 
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There’s  One  Born 
Every  Minute 


It  is  now  time  to  put  the  SMALLCOM 
project  into  the  cask  and  let  it  age. 
Some  of  you  are  using  it  and  send¬ 
ing  in  comments,  suggestions,  and 
problems.  The  project  has  spanned  ten 
months,  and  newer  readers  are  finding 
it  necessary  to  get  back  issues  to  catch 
up.  I  might  update  the  project  in  a 
future  column  and  add  more  functions 
to  it.  For  now,  though,  vacation  is  upon 
us,  and  time  has  come  to  reveal  our 
hidden  hedonism  with  a  trip  to  the 
islands  and  the  tables  of  chance. 

Rodney  Dangerfield  says  that  he  went 
to  Las  Vegas  in  a  $25,000  automobile 
and  came  home  in  a  $200,000  bus.  I 
went  to  Puerto  Rico  to  build  an  income 
tax  system  and  came  home  with  a  Black¬ 
jack  simulation  program. 

San  Juan,  Puerto  Rico  has  gambling 
casinos.  My  pal  Fast  Eddie  Dwyer  lives 
there,  deals  with  the  Puerto  Rican  ver¬ 
sion  of  the  IRS  by  day,  and  pokes 
around  the  casinos  by  night.  Armed 
with  a  book  on  how  to  win  at  Black¬ 
jack,  he  has  planned  an  early  retire¬ 
ment.  With  luck,  however,  he  will 
merely  have  a  lot  of  fun  spending  (los¬ 
ing)  not  a  lot  of  money.  Notice  the 
operative  word  —  luck. 

I’m  no  gambler,  but  I’m  drawn  to 
a  challenging  problem.  I  decided  to 
test  Fast  Eddie’s  Blackjack  systems  with- 


Al  Stevens 


out  risking  any  of  my  own  dough. 
What  better  way  than  with  computer 
simulation  in  a  C  program?  The  pro¬ 
gram  in  Listing  One,  page  136,  is  bj.c, 
and  it  models  the  game  and  some  of 
the  strategies  being  taught  by  the  self- 
proclaimed  masters.  My  conclusions 
about  the  viability  of  these  strategies 
can  be  seen  in  the  results  delivered  by 
the  program.  In  the  long  haul,  you 


cannot  win.  Not  everyone  will  agree. 

There  was  a  time  when  you  could 
find  a  Blackjack  game  at  some  casinos 
that  used  one  deck.  If  you  were  able 
to  mentally  master  all  the  strategies, 
you  could  win  consistently.  The  casi¬ 
nos  learned  this  and  changed  some  of 
the  rules,  one  of  them  being  the  num¬ 
ber  of  decks  in  the  play.  Now  they  use 
six  decks,  and  the  strategies,  even  if 
you  can  execute  them  flawlessly,  which 
no  one  can,  do  not  work.  Fast  Eddie 
still  has  a  day  job. 

The  casinos  all  have  signs  that  forbid 
the  use  of  personal  computers  and  other 
electronic  aids.  The  signs  are  there  to 
convince  you  that  “systems”  can  work, 
to  make  you  want  to  try,  to  get  you  to 
play,  to  get  your  money.  You  could 
take  all  the  electronic  help  you  wanted. 
You’d  still  lose. 

There  are  three  fundamental  strate¬ 
gies  touted  to  make  you  a  Blackjack 
winner.  The  first  strategy  involves  ob¬ 
serving  your  hand  and  the  dealer’s  up 
card.  Based  on  a  chart  (provided  in 
Fast  Eddie’s  how-to  book)  you  decide 
whether  to  hit  or  stand.  If  your  first  two 
cards  are  the  same  denomination,  an¬ 
other  chart  tells  you  whether  you  should 
split  the  hand.  When  you  get  the  sec¬ 
ond  card,  a  third  chart  tells  you  if  you 
should  double-down  the  hand.  The  trick 
is  memorizing  all  three  charts  and  be¬ 
ing  able  to  implement  them  instantly 
during  the  fast  pace  of  the  deal.  To 
complicate  matters,  the  charts  are  dif¬ 
ferent  depending  on  whether  you  are 
playing  in  Nevada,  Atlantic  City,  or  the 
Caribbean. 

The  second  strategy  involves  count¬ 
ing  cards.  You  keep  a  running  count 
of  two  groups  of  cards.  The  first  group 
is  the  good  group,  and  it  consists  of  the 
face  cards,  tens,  and  aces.  The  second 
group  is  bad.  It  is  made  up  of  all  the 
other  cards,  deuces  through  nines.  You 


have  to  watch  all  the  cards  that  were 
dealt  to  you,  the  dealer,  and  all  the 
other  players.  You  have  to  mentally 
compute  a  running  balance  of  the  two 
groups  to  know  what  ratio  of  good 
to  bad  cards  are  left  in  the  undealt 
portion  of  the  deck.  The  more  good 
cards,  the  better  your  chances  of  win¬ 
ning.  The  more  bad  cards,  the  more 
likely  you  are  to  lose.  When  the  ratio 
gets  to  a  certain  level  in  your  favor, 
you  increase  your  bet.  When  the  ratio 
goes  far  enough  against  you,  you  stop 
playing.  The  ratio  you  apply  is  a  func¬ 
tion  of  the  total  number  of  cards  in 
play.  As  play  proceeds  you  add  one  to 
a  running  total  each  time  you  see  a 
good  card.  You  subtract  one  each  time 
you  see  a  bad  card.  You  apply  this 
running  total  to  the  total  number  of 
cards  to  figure  the  ratio  of  good  to  bad 
cards  left  in  the  deck.  That  is  the  es¬ 
sence  of  card  counting.  I  no  longer 
have  the  specifics  because  Fast  Eddie 
kept  the  book  when  I  left  San  Juan. 
He’s  still  trying. 

The  third  strategy  is  called  money 
management.  You  change  your  bets 
based  on  your  recent  win/loss  ratio.  I 
never  understood  this  one,  and  could 
not  simulate  it  properly.  Fast  Eddie  and 
I  have  a  pal  who  believes  in  it  fer¬ 
vently.  The  last  time  he  was  in  San 
Juan,  he  borrowed  money  to  get  home. 

I  simulated  both  of  the  first  two  strate¬ 
gies  for  a  while.  Only  the  first  is 
included  in  bj.c,  however,  because  I 
neglected  to  bring  the  card-counting 
algorithm  back  into  the  States.  No  mat¬ 
ter,  card-counting  had  no  measurable 
impact  on  the  model’s  outcome  unless 
the  deal  was  a  one-deck  game,  some¬ 
thing  you  cannot  find  any  more  in  the 
big  gambling  houses.  If  you  have  a 
card-counting  algorithm  that  you  think 
might  work,  you  can  add  it  to  the  pro¬ 
gram.  But  if  you  let  all  your  simulated 
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players  count  cards,  they  all  drop  out 
when  the  ratio  gets  too  unfavorable, 
and  the  game  grinds  to  a  halt. 

Bear  in  mind  that  the  techniques  prac¬ 
ticed  by  the  gamblers  and  simulated 
by  bj.c  require  perfect  concentration 
and  a  near-photographic  memory. 
Those  who  hawk  the  methods  insist 
that  with  practice  the  necessary  skills 
can  be  mastered,  and  that  might  be 
true.  But  when  a  student  fails  to  make 
money,  the  teachers  usually  blame  the 
student’s  inability  to  correctly  admini¬ 
ster  the  procedures  rather  than  the  meth¬ 
ods.  The  truth  seems  to  be  that  the 
methods  do  not  work.  The  computer 
does  not  make  any  of  those  mistakes 
(unless,  of  course,  the  mistakes  are  in 
the  code),  and  even  though  it  plays 
flawlessly,  the  computer  cannot  win 
either. 

The  BJ.C  Program 

The  bj.c  program  is  written  mostly  in 
generic  ANSI  C.  I  compiled  it  with  Turbo 
C  2.0.  The  program  uses  two  macros 
that  assume  the  ANSI. SYS  driver  is  in¬ 
stalled  in  a  PC.  These  two  macros  are 
clr_scrn  and  cursor.  If  you  are  using  a 
different  system  you  will  need  to  change 
these  macros  to  clear  the  screen  and 
position  the  cursor  with  the-  protocols 
of  your  system. 


There  are  two  global  variables  you 
can  change  to  modify  the  game.  One 
is  PLAYERS,  which  defines  how  many 
players  are  in  the  game.  The  other 
is  DECKS,  which  defines  how  many 

I  am  not  interested 
in  tales  of  success  at 
the  tables  or  the 
specifications  for 
Blackjack  systems 
that  are  guaranteed 
to  work 


decks  the  game  uses.  I  used  a  much 
more  complicated  version  of  the  pro¬ 
gram  in  San  Juan,  and  you  can  add  the 
features  it  had  if  you  wish.  It  let  me 
select  the  deck  size  and  player  count 


at  run  time.  I  could  choose  a  chair  and 
play  along,  too. 

The  program  uses  the  IBM  PC  graph¬ 
ics  character  set  to  display  the  cards 
on  the  screen.  If  your  terminal  cannot 
support  these  characters,  remove  the 
#define  IBMPC statement,  and  the  pro¬ 
gram  will  use  ASCII  characters  to  rep¬ 
resent  the  cards. 

Between  deals  in  a  Blackjack  game, 
the  cards  are  divided  between  the 
“shoe,”  a  box  that  holds  the  undealt 
cards  and  the  “discards,”  a  stack  of  the 
cards  that  have  already  been  used. 
When  the  shoe  runs  out  of  cards,  the 
dealer  re-shuffles  the  cards  and  puts 
them  back  in  the  shoe.  You  will  see 
both  terms  throughout  the  program. 

The  program  uses  a  typedef  for  the 
CARD,  which  contains  a  value  (ace, 
deuce,  trey .  .  .  king)  and  a  suit.  The 
suit  is  not  relevant  to  the  simulation 
but  I  included  it  to  make  the  program 
more  realistic  and  more  interesting. 
There  is  an  array  of  CARDs  called  shoe 
and  one  called  discards. 

The  PLAYER  typedef  contains  every¬ 
thing  about  a  player  including  an  array 
of  the  CARDs  in  the  current  hand,  the 
amount  of  money  in  the  player’s  bank, 
the  amount  the  player  is  betting,  a 
pointer  to  the  player’s  hit/stand  strat¬ 


egy  function,  and  some  other  opera¬ 
tional  variables  that  tell  the  program 
what  the  player  is  doing  at  a  given 
place  in  the  deal.  There  is  an  array  of 
PLAYERs  named  players.  The  array  has 
two  PLAYER  entries  for  each  actual 
player.  The  second  entry  is  set  aside 
for  that  time  when  a  player  decides  to 
split  the  hand.  The  last  PLAYER  entry 
is  the  dealer. 

When  you  run  the  program,  it  dis¬ 
plays  each  hand  being  dealt  and  the 
outcome.  Each  player’s  bank  is  dis¬ 
played.  You  can  run  the  program  so 
that  it  stops  after  each  hand  to  let  you 
look  at  the  results,  or  you  can  have  it 
run  continuously  without  intervention. 
You  can  run  the  program  to  bypass  the 
displays,  showing  the  banks  only.  This 
runs  the  simulation  a  lot  faster  and  gets 
the  same  results. 

Each  player  and  the  dealer  start  with 
a  bank  value  of  zero.  When  a  player 
wins,  the  player’s  bank  is  increased  by 
the  amount  of  the  bet  and  the  dealer’s 
bank  is  decreased  by  the  same  amount. 
When  the  player  loses,  the  reverse  oc¬ 
curs.  A  negative  bank  means  the  player 
is  losing.  A  positive  bank  means  the 
player  is  winning. 

A  player  can  “double-down”  a  hand 


after  the  second  card.  This  means  the 
player  doubles  the  bet  but  can  get  no 
more  than  one  additional  card.  A  player 
can  split  a  hand  if  the  first  two  cards  are 
the  same  denomination.  For  example, 
if  you  get  two  fives,  you  can  play  them 
as  two  independent  hands  with  the 
same  bet  on  each.  You  can  double¬ 
down  on  either  or  both  of  the  split 

If  you  let  the  program 
run  long  enough,  the 
dealer  wins  big  and  the 
players  lose  big 


hands.  You  can  win  one  of  the  hands, 
both  of  them,  or  neither. 

If  a  player’s  hand  ties  with  the  dealer, 
the  player  wins,  but  not  the  full  amount. 
In  theory,  you  win  half  of  what  you 
bet.  But  because  the  chips  do  not  come 


in  denominations  evenly  divisible  by 
two,  a  tie  is  called  a  “push.”  Your  bet 
stays  up,  and  to  keep  it,  you  have  to 
win  the  next  hand,  too. 

There  is  something  in  Blackjack  called 
“insurance”  that  I  never  understood.  It 
is  not  in  the  bj.c  program.  Detractors 
of  my  conclusions  can  point  to  this 
deficiency  if  it  helps  their  argument. 

The  shuffle  is  done  by  computing  a 
random  subscript  into  the  discards,  mov¬ 
ing  the  card  at  the  offset  into  the  shoe, 
and  moving  all  the  following  discards 
down  one  position.  This  procedure  con¬ 
tinues  until  all  the  cards  are  in  the  shoe. 
When  the  program  begins,  all  the  cards 
are  in  the  discards  ready  for  the  first 
shuffle.  Each  time  the  deck  is  shuffled, 
the  first  card  is  “buried,”  that  is,  moved 
to  the  discard  pile. 

The  dealer’s  hit/stand  strategy  is  a 
simple  one.  The  rules  say  the  dealer 
must  hit  if  the  hand  value  is  16  or 
below  and  stand  if  the  hand  value  is 
17  or  above.  Dealers  cannot  split  a 
hand.  The  dstrategy  function  imple¬ 
ments  the  dealer’s  strategy. 

Players  do  not  have  the  restrictions 
imposed  on  dealers,  and  the  essence 
of  the  simulation  is  in  the  two  func¬ 
tions  named  split  and  pstrategy.  These 
functions  decide  what  a  player  is  going 
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to  do  with  the  hand  and  are  designed 
to  use  the  strategies  of  the  three  charts 
given  in  Fast  Eddie’s  book  for  Carib¬ 
bean  casinos. 

The  split  decision  is  based  on  what 
your  identical  cards  are  and  what  the 
dealer’s  up  card  is.  The  switch  state¬ 
ment  in  the  split  function  makes  the 
decision. 

The  pstrategy  function  decides 
whether  to  double-down  or  not  and 
whether  to  take  a  hit  or  not.  It  looks  at 
the  value  of  the  player’s  hand  and  the 
dealer’s  up  card.  If  either  of  the  first 
two  cards  is  an  ace,  the  third  card  strat¬ 


egy  is  different  than  otherwise.  These 
switch  statements  are  based  on  the 
charts. 

You  can  run  the  bj.c  program  and 
draw  your  own  conclusions.  Often  a 
player  will  have  a  long  run  of  luck. 
Often  you  will  see  the  dealer  losing  for 
an  extended  time.  But  if  you  let  the 
program  run  long  enough,  the  dealer 
wins  big  and  the  players  lose  big. 

This  month’s  column  was  fun  but  it 
might  raise  some  controversy.  It  has 
concluded  with  computer  simulation 
that  you  cannot  consistently  win  at  Black¬ 
jack.  Some  people  do  not  want  to  be¬ 


lieve  that.  There  is  a  dominant  trait  of 
character  common  in  most  gamblers. 
They  do  not  want  to  believe  that  win¬ 
ning  is  a  matter  of  luck,  losing  is  a 
function  of  odds,  and  the  systems  do 
not  work.  Anyone  who  doubts  these 
arguments  is  welcome  to  find  the  flaws 
in  my  model  and  correct  them.  But  if, 
on  the  other  hand,  they  are  that  sure 
that  I  am  wrong,  they  are  too  busy 
winning  money  to  mess  with  a  trifling 
computer  program. 

Those  who  write  or  send  a  Compu¬ 
Serve  message  to  disagree  with  these 
conclusions  are  requested  to  restrict 
their  criticisms  to  the  accuracy  of  the 
code  and  the  degree  to  which  they 
think  the  simulation  reflects  the  real 
world.  I  am  not  interested  in  tales  of 
success  at  the  tables  or  the  specifica¬ 
tions  for  Blackjack  systems  that  are  guar¬ 
anteed  to  work.  Books  and  seminars 
on  how  to  beat  the  Blackjack  tables 
abound.  They  are  almost  as  plentiful 
as  the  books,  home  study  cassette 
courses,  and  seminars  on  how  to  get 
rich  in  real  estate.  It  makes  you  wonder 
where  the  real  money  is.  If  the  systems 
work,  one  might  ask,  how  come  their 
promoters  are  in  the  seminar  and  book 
business? 

The  code  in  bj.c  is  tossed  out  for 
those  of  you  who  would  care  to  try  it 
and  maybe  tweak  it.  I  doubt  that  you’ll 
ever  get  it  to  win.  If  you  do,  I  doubt 
that  you’ll  ever  be  able  to  take  its  skill 
to  the  tables  yourself.  The  program  con¬ 
vinced  me  to  stay  away  from  the  Black¬ 
jack  tables.  I  watched  it  consistently 
lose  simulated  money  for  its  simulated 
players,  and  I  stood  in  casinos  and 
watched  real  people  lose  real  money. 
If  the  program  can  convince  you  the 
same  way  it  convinced  me,  then  it 
is  a  public  service  and  has  served  its 
purpose. 

Spend  your  money  instead  going  to 
see  Wayne  Newton. 

Availability 

All  source  code  for  articles  in  this  issue 
is  available  on  a  single  disk.  To  order, 
send  $14.95  (Calif,  residents  add  sales 
tax)  to  Dr.  Dobb’s Journal ,  501  Galves¬ 
ton  Dr.,  Redwood  City,  CA  94063,  or 
call  800-356-2002  (from  inside  Calif.) 
or  800-533-4372  (from  outside  Calif.). 
Please  specify  the  issue  number  and 
format  (MS-DOS,  Macintosh,  Kaypro). 


DDJ 


(Listing  begins  on  page  136.) 
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Do-It-Yourself 

Coordinates 


This  marks  what  my  wife  would 
call  the  “six-month-aversary"  of 
the  “Graphics  Programming”  col¬ 
umn.  There's  something  about 
years  that  are  multiples  of  five  and 
months  occurring  on  even  boundaries 
of  six  that  summon  up  the  tendency  to 
assess  The  Situation.  A  further  spur  is 
the  increasing  amount  of  mail  and 
CompuServe  traffic  we’ve  received  at 
DDJ concerning  this  column.  Most  like 
it.  A  few  hate  it.  One  fellow  even  can¬ 
celed  his  subscription  because  of  it.  I’m 
sorry  he  did.  On  the  other  hand,  sev¬ 
eral  thousand  new  members  have  mar¬ 
ried  into  the  DDJ  family  during  the 
past  six  months.  Certainly,  I  don’t  take 
all  the  credit  for  that,  but  I’d  like  to 
think  this  column  had  something  to 
do  with  it.  Still,  I  feel  compelled  to 
answer  a  few  criticisms  and  let  you  in 
on  the  grand  strategy.  And  then  we'll 
get  down  to  this  month’s  advancement 
of  computer  graphics,  which  is  pretty 
significant. 

Okay,  critics,  here’s  the  Q&A: 

Q:  Why  do  I  concentrate  on  the  EGA/ 
VGA,  excluding  all  others? 

A:  Because  that’s  the  configuration  I 
have,  and  most  readers  have  as  well. 
Admittedly  there’s  also  the  Atari,  Amiga, 
Mac  II,  TMS  34010,  DGIS,  Nth,  Sun, 


Kent  Porter 


Apollo.  .  .  .  You  name  it,  and  all  wonder¬ 
fully  capable  of  graphics.  And  if  I’d 
tried  to  serve  every  one  of  them,  it 
would  have  taken  a  year  to  get  past 
writing  a  single  pixel,  by  which  time 
99  percent  of  the  readership  would 
have  died  of  boredom.  We  have  to 
make  some  progress  here,  and  we  do 
that  by  rallying  around  the  common 
denominator.  According  to  DDJ  reader 


surveys,  that’s  the  EGA/VGA  on  a  PC. 
All  graphics  rests,  ultimately,  on  pixel¬ 
writing.  If  you  have  developed  other 
machine  solutions  to  the  GRAFIX  li¬ 
brary,  you’re  more  than  welcome  to 
post  them  on  CompuServe. 

Q:  Why  C  and  assembly  language? 

A:  Why  not?  Once  again,  we  must  have 
some  common  basis  on  which  to  pro¬ 
ceed.  C  is  used  by  75  percent  of  DDJ 
readers,  and  it's  the  pre-eminent  sys¬ 
tem’s  programming  language.  Most  C 
programmers  recognize  that  assembler 
is  the  alternative  for  writing  high-per¬ 
formance  subroutines.  Certainly  other 
languages  are  graphics  capable  as  well. 
Prime  examples  are  Pascal  and  Modu¬ 
la-2,  for  which  I  have  a  distinct  and 
public  fondness.  A  reader  has  offered 
to  translate  the  GRAFIX  library  into 
Turbo  Pascal  and  I’m  all  for  it.  But 
again,  we  must  have  a  common  point 
of  reference.  It’s  not  hard  to  translate 
C  code  into  other  languages. 

Q:  Why  don 't  I  worry  more  about  per¬ 
formance?  For  example,  why  is  theBre- 
senham  line-drawing  algorithm  writ¬ 
ten  in  C  instead  of  assembly  language? 

A:  Because  the  purpose  of  this  column 
is  to  see  how  it’s  done.  It’s  easier  to 
understand  C  than  assembler.  Optimi¬ 
zation  — particularly  in  assembly  lan¬ 
guage  — obscures  the  underlying  algo¬ 
rithm.  Performance  issues  are,  how¬ 
ever,  addressed.  That’s  why  hline( ) 
exists  and  why  some  other  low-level 
routines  are  coded  in  assembly  lan¬ 
guage.  We’re  not  developing  a  com¬ 
mercial  graphics  package  here,  but  in¬ 
stead  exploring  the  hows  and  whys. 
All  of  us  — myself  included  and  espe¬ 
cially  — are  learning  as  we  go  along. 
You  read  a  magazine  that  clearly  states 
on  its  cover  “for  the  professional  pro¬ 


grammer.”  That  suggests  a  certain  sa- 
voir  faire,  and  I  assume  you’re  capable 
of  rising  to  the  occasion  if  you  want 
more  performance. 

So  much  for  the  critics,  whose 
wounds  I  have  hopefully  salved.  Where 
are  we  going?  Right  now  we’re  concen¬ 
trating  on  the  EGA,  which  is  easier  to 
understand  than  the  VGA  and  produces 
acceptable  graphics  for  most  purposes. 
You’ll  note  that  some  functions  include 
“ega”  in  their  names,  as  in  egapixelj ), 
set_ega _palreg( ),  and  so  on.  Later  we’ll 
add  functions  with  “vga"  as  part  of 
their  identifiers,  and  atop  that  we’ll  pile 
a  set  of  bindings  that  select  the  appro¬ 
priate  function  based  on  the  current 
video  mode. 

In  the  long  run  we’re  headed  for  the 
VGA.  It’s  the  only  commonly  available 
and  affordable  PC  video  adapter  capa¬ 
ble  of  producing  subtle  shading  and 
other  visual  effects  that  characterize  high- 
level  graphics. 

Meanwhile,  there’s  a  lot  of  ground 
to  cover.  It  would  be  wise  to  put  a 
math  coprocessor  into  your  hardware 
budget,  because  by  the  end  of  the  year 
we’re  going  to  be  heavily  into  the  float¬ 
ing  point  matrix  operations  that  are 
inevitable  in  3-D  graphics. 

In  fact,  if  you  don’t  have  an  ’87  now, 
you’ll  begin  this  month  to  experience 
some  of  the  performance  degradation 
that  floating  point  emulation  introduces. 
For  July  is  the  month  in  which  we  enter 
the  mystical  realm  of  .  .  . 

Virtual  Coordinates 

All  display  devices  have  some  sort  of 
fixed  coordinate  system.  In  EGA  graph¬ 
ics  it’s  640  x  350;  for  VGA  it’s  640  x  480. 
Others  of  less  interest  here  might  have 
a  resolution  of  1024  x  768  or  320  x  200 
or  whatever.  This  fixed  system  is  gener¬ 
ally  referred  to  as  the  device  coordi¬ 
nate  space. 
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There  are  some  problems  with  de¬ 
vice  coordinates.  For  one  thing,  the 
origin  is  (on  the  PC,  at  least)  always  in 
the  upper  left  corner,  which  means 
that  the  Y  value  increases  downward. 
That’s  counterintuitive,  the  reverse  of 
graphing  techniques  taught  from  grade 
school  onward.  For  another  thing,  the 
origin  is  not  relocatable.  What  if  you 
want  the  zero  point  in  the  middle  of 
the  screen  with  positive  and  negative 
coordinates?  Yet  another  problem  is 
distortion;  pixels  are  not  square  in  EGA 
graphics,  yielding  vertically  elongated 
circles  and  other  visual  oddities.  And 
finally,  data  values  seldom  map  neatly 
into  the  device  coordinate  space.  For 
example,  how  do  you  fit  30  data  points 
evenly  across  640  pixels? 

The  LINEGRAF.C  program  presented 
back  in  May  dealt  with  some  of  these 
issues,  but  not  in  a  very  satisfying  way. 
That’s  because  it  necessarily  included 
a  number  of  extraneous  calculations 
required  to  convert  the  program’s  in¬ 
ternal  data  representation  into  device 
coordinates. 

Certainly  it’s  necessary  to  perform 
these  calculations,  but  there  ought  to 
be  a  better  way:  A  way  in  which  the 
programmer  can  define  the  screen  co¬ 
ordinate  space  in  terms  of  the  data  to 
be  displayed,  and  then  concentrate  on 


the  problem  without  worrying  about 
the  mechanics  of  mapping  values  to  a 
specific  display  device. 

And  indeed  there  is.  That’s  what  vir¬ 
tual  coordinates  are  all  about. 

The  word  virtual  is  so  overworked 
in  our  industry  that  I  hesitate  to  use  it 
yet  again.  However,  it’s  appropriate  in 
this  context.  According  to  good  old 
Webster,  virtual  means  “denoting  in 
essence  or  effect,  without  being  so  in 

You  can  define  screen 
coordinates  in  terms  of 
the  data.  Each  axis  is 
scaled  independently 


fact.”  If  you  declare  an  effective  dis¬ 
play  width  of,  say,  100  units  when  its 
actual  width  is  640,  you’ve  defined  a 
virtual  space.  The  same  is  of  course  true 
in  the  vertical  (Y)  space,  which  you 
might  describe  as  something  besides 
the  EGA's  0  -  349  working  downward. 

The  ability  to  redefine  the  screen 


dimensions  in  any  terms  you  like  greatly 
simplifies  graphics  programming.  Your 
programs  can  then  work  with  intuitive 
units  as  their  internal  data  representa¬ 
tion:  dollars,  percentages,  months,  data 
points,  whatever.  You  can  scale  each 
axis  independently,  and  also  use  dif¬ 
ferent  data  types  in  the  X  and  Y  direc¬ 
tions.  For  example,  in  plotting  trigono¬ 
metric  functions  you  might  assign  the 
integral  angles  -360  to  +360  as  units 
along  the  X  axis  and  floating-point  in¬ 
crements  from  +1.0  at  the  top  to  —1.0 
at  the  bottom  along  the  Y.  We’ll  do 
something  like  this  later. 

Virtual  coordinates  solve  a  number 
of  graphics  problems.  The  example  just 
given  “flips”  the  Y  axis  to  correspond 
with  the  normal  mathematical  practice 
of  increasing  the  Y  value  upward.  Note 
also  that  it  relocates  the  origin  to  the 
center  of  the  physical  screen. 

Another  vexing  problem  overcome 
by  virtual  coordinates  is  the  “un-square¬ 
ness”  of  pixels,  a  phenomenon  often 
referred  to  in  graphics  literature  as  as¬ 
pect  ratio  or  orthogonal  distortion.  The 
normal  display  area  has  a  height  that 
is  75  percent  of  its  width.  If  you  divide 
height  by  width,  the  result  is  0.75  if  the 
pixels  are  square,  or  in  other  words  if 
the  vertical  and  horizontal  units  of  meas¬ 
urement  are  equal.  That  works  out  to 


be  true  for  the  VGA  in  640  x  480  graph¬ 
ics,  but  not  for  the  EGA’s  640  x  350 
mode.  The  result  is  about  0.547,  mean¬ 
ing  that  the  physical  height  of  a  pixel  is 
greater  than  its  width.  Some  correction  is 
therefore  necessary  on  the  EGA  to  pro¬ 
duce  round  circles  and  square  squares 
and  other  figures  of  consistent  dimen¬ 
sions  along  both  axes.  Virtual  coordi¬ 
nates  let  you  make  these  corrections. 

VCOORDS.C  in  Listing  One,  page 
142,  performs  the  necessary  magic  to 
implement  virtual  coordinates.  Your  pro¬ 
gram  defines  the  virtual  space  it  wants 
by  calling  setcoords( ).  The  arguments 
are  the  left,  top,  right,  and  bottom  of 
the  display  area,  expressed  in  virtual 
units.  For  example,  to  set  the  trigono¬ 
metric  plot  area  mentioned  earlier,  write 

setcoords  (-360,  1.0,  360,  —1.0); 

If  you  want  a  conventional  (Y  down¬ 
ward)  plot  area  with  virtually  square 
pixels,  write 

setcoords  (0,  0,  639,  479); 

With  this  virtual  space,  the  EGA  emu¬ 
lates  the  VGA’s  coordinate  space,  and 
it  will  produce  images  of  dimensions 
identical  to  those  drawn  in  native  VGA 
mode. 


The  arguments  are  of  type  double. 
Because  of  the  function  prototype  given 
in  this  month’s  additions  to  GRAFIX.H 
(Listing  Two,  page  142),  the  compiler 
automatically  casts  integral  arguments 
to  doubles,  thus  allowing  you  to  pass 
any  numeric  data  type  to  setcoords( ) 
with  the  expectation  of  reliability. 

The  secret  of  virtual  coordinates  lies 
in  the  four  variables  at  the  top  of  the 
VCOORDS  compile  unit:  xf,  yf  ox,  and 
oy.  The  first  two  are  conversion  factors, 
which  are  multiplied  by  virtual  coordi¬ 
nates  to  derive  the  corresponding  de¬ 
vice  coordinates.  By  default  these  val¬ 
ues  are  1.0,  yielding  a  1-for-l  mapping 
of  virtual  to  device  units.  If  you  set  a 
virtual  width  of  320,  however,  xf  be¬ 
comes  2.0,  meaning  there  are  two  de¬ 
vice  X  units  per  virtual  X. 

The  other  two  variables,  ox  and  oy, 
represent  the  virtual  origin  in  terms  of 
device  coordinates.  They  give  the  off¬ 
sets  to  be  added  to  converted  virtual 
coordinates  in  order  to  map  a  virtual 
point  to  its  specific  device  location. 
These  values  are  normally  zero,  which 
initializes  the  virtual  coordinate  system 
to  an  origin  in  the  upper-left  corner.  If 
you  set  up  a  virtual  space  with  a  call 
such  as 

setcoords  (-160,  -120,  159,  119); 


then  after  setcoords!  )  executes,  ox  and 
oywill  contain  values  close  to  the  physi¬ 
cal  center  of  the  screen. 

The  discussion  so  far  assumes  that 
you’re  operating  in  full-screen  mode. 
However,  the  virtual  coordinate  sys¬ 
tem  is  relative  to  the  current  view¬ 
port.  If  the  viewport’s  proportions  dif¬ 
fer  from  those  of  the  full  screen,  the 
virtual  space  assumes  a  mapping  that 
distorts  accordingly.  That  is,  when  the 
current  viewport  has  a  physical  height 
twice  its  width,  a  4-to-3  ratio  in  the 
virtual  space  will  yield  “square”  virtual 
pixels  that  are  twice  as  high  as  wide. 
This  characteristic  produces  infinite  pos¬ 
sibilities  for  scaling  graphics  output  to 
suit  your  needs.  We’ll  see  an  example 
shortly. 

But  first  it’s  necessary  to  incorporate 
the  virtual  coordinate  package  into  your 
copy  of  GRAFIX.LIB.  Append  the  con¬ 
tents  of  Listing  Two  to  GRAFIX.H,  then 
compile  VCOORDS.C.  Add  the  ob¬ 
ject  module  to  the  library  with  the 
command 

LIB  grafix  +  vcoords; 

Having  defined  a  virtual  space  with 
setcoords! ),  your  program  can  work 
internally  with  intuitive  virtual  units. 

(continued  on  page  124) 
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An  example  is  graphing  budgeted 
amounts  by  quarter.  The  X  axis  can 
represent  quarters  1-4,  while  the  Y 
axis  represents  millions  of  dollars.  At 
output  time,  the  program  calls  upon 
the  VCOORDS  routines  to  map  the  vir¬ 
tual  values  to  device  coordinates  by 
calling  dx( )  and  dy( ).  Similarly,  if  the 
program  wants  to  translate  a  virtual 
distance  into  device  units,  as  in  calling 
hlineC ),  draw_rect( ),  and  so  on,  it  can 
call  dxunits(  )and  dyunits( ). 

Let’s  see  how  it  works  to  use  virtual 
coordinates.  The  first  example  is 


The  vertical  and 
horizontal  virtual 
spacing  automatically 
adjust  to  the  viewport 
dimensions 


TRIGPLOT.C  in  Listing  Three,  page  142. 
This  program  plots  the  sine,  cosine, 
and  their  sum  through  two  full  circles 
(-360  to  +360  degrees).  The  X  axis  is 
thus  subdivided  into  720  virtual  units 
corresponding  to  integral  degrees.  The 
sine  and  cosine  never  exceed  an  abso¬ 
lute  magnitude  of  1 .0,  and  so  the  Y  axis 
uses  floating  point  units.  Addition  of 
the  curves,  which  have  different  peri¬ 
ods,  results  in  a  fluctuation  of  about 
plus  and  minus  1.4,  so  the  Y  axis  is 
scaled  from  +1.5  on  top  to  -1.5  below. 
The  virtual  origin  is  at  the  center  of  the 
screen. 

The  program  begins  by  scaling  the 
axes  with  a  call  to  setcoords( ),  and 
then  it  draws  the  registration  lines.  The 
major  axes  appear  in  green,  and  refer¬ 
ence  lines  in  blue  at  virtual  distances 
of  +1.0  and  —1.0  vertically.  Three  suc¬ 
cessive  loops,  stepping  conveniently 
by  degrees,  control  the  drawing  of  the 
curves.  The  plot( )  routine  does  the 
real  work,  finding  the  virtual  elevation 
of  the  point  by  calling  the  parametric 
function  ( cos( ) ,  sin( ),  or  sum( ))  and 
then  advancing  the  curve  to  that  point 
from  the  elevation  of  the  previous  angle. 

The  next  example  is  LENDIST.C,  List¬ 
ing  Four,  page  142.  This  is  a  very  differ¬ 
ent  application  of  virtual  coordinates. 
The  program  displays  a  histogram  — 
that  is,  a  horizontal  bar  chart  — show¬ 
ing  the  distribution  of  line  lengths  in  a 
text  file.  Lines  are  grouped  by  multi¬ 
ples  of  five  characters:  0  -  4,  5  -  9,  etc. 


The  longest  possible  line  is  assumed 
to  be  80  characters.  If  yours  are  longer, 
modify  MAXLEN  at  the  top  of  the  list¬ 
ing  accordingly. 

The  program  passes  through  the  file 
named  on  the  command  line,  counting 
the  number  of  text  lines  within  each 
grouping.  It  then  finds  the  group  with 
the  highest  count  and  normalizes  all 
lines  to  that  value,  using  100  as  the 
reference.  That  is,  if  maxcount  is  86, 
the  normalized  value  for  the  group  con¬ 
taining  86  lines  is  100.  If  another  group 
contains  43  lines,  its  normalized  value 
is  50,  or  half  as  many  as  the  largest 
group. 

Normalization  is  useful  in  this  case 
because  the  graph  must  accommo¬ 
date  a  wide  range  of  potential  values 
while  setting  aside  a  fixed  amount  of 
space  for  the  bar  legends.  By  nor¬ 
malizing  the  largest  value  to  100,  we 
know  how  much  space  to  leave  for 
text:  22  virtual  X  units.  And  because 
there  are  25  text  rows  on  the  screen, 
we  can  also  establish  the  virtual  Y 
axis  as  25  units,  with  a  range  of  -2 
through  23  to  leave  room  at  the  top  for 
a  label.  Hence  the  values  passed  to 
setcoords( )  and  the  newlines  in  the 
printfC  )  statements. 

The  rest  is  fairly  obvious  from  the 
listing.  The  graph  area  setup  entails 
drawing  a  rectangle  around  the  whole 
works  and  marking  registration  lines 
at  normalized  intervals  of  10  across  the 
region  where  the  bars  will  occur.  Be¬ 
cause  of  the  virtual  Y  spacing,  whose 
origin  is  two  text  lines  down  from  the 
top,  each  bar  lines  up  with  its  legend. 
Its  height  is  75  percent  of  a  single  Y 
unit  to  provide  cosmetic  spacing. 

Hey,  we’re  starting  to  produce  use¬ 
ful  graphics  applications! 

The  final  example  considers  the  ef¬ 
fect  of  the  viewport  shape  on  the  scal¬ 
ing  of  the  virtual  coordinate  space.  A 
“square"  space  with  a  4-to-3  ratio  turns 
out  not  to  be  square  if  the  containing 
viewport  isn’t  of  the  same  ratio  as  the 
device.  Instead,  the  vertical  and  hori¬ 
zontal  virtual  spacing  automatically  ad¬ 
just  to  fit  the  viewport  dimensions. 

The  case  in  point  is  RESIZE. C,  Listing 
Five,  page  148.  This  program  displays 
a  four-pointed  star  in  each  of  three 
viewports.  The  same  routine  —  draw- 
starf )  —  draws  and  fills  the  figure  each 
time  using  identical  virtual  coordinates, 
which  assume  a  square  space  with  its 
origin  at  the  center.  However,  because 
set_vp(  )  establishes  different  viewport 
dimensions,  the  lengths  of  the  X  and 
Y  units  change.  The  first  viewport  is 
square,  with  a  4-to-3  ratio.  The  other 
two,  however,  are  tall  and  skinny,  and 
short  and  fat.  The  star  in  each  main¬ 


tains  its  spatial  relationship  to  the 
viewport,  but  the  shape  is  dramatically 
different. 

The  ability  to  redefine  the  display’s 
coordinate  system  opens  the  door  to 
great  possibilities  for  data  representa¬ 
tion  in  graphics.  Now  that  we  know 
how  to  do  it,  we’ll  use  virtual  coordi¬ 
nates  often  as  we  move  onward. 

Happy  six-month-aversary. 

Availability 

All  source  code  for  articles  in  this  issue 
is  available  on  a  single  disk.  To  order, 
send  $14.95  (Calif,  residents  add  sales 
tax)  to  Dr.  Dobb’s  Journal ,  501  Galves¬ 
ton  Dr.,  Redwood  City,  CA  94063;  or 
call  800-356-2002  (from  inside  Calif.) 
or  800-533-4372  (from  outside  Calif.). 
Please  specify  the  issue  number  and 
format  (MS-DOS,  Macintosh,  Kaypro). 
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STRUCTURED  PROGRAMMING 


Dodging 

Steamships 


When  it’s  time  to  build  steam¬ 
ships,  everybody  builds  steam¬ 
ships  —  or  so  the  chestnut 
goes.  It  must  be  steamship 
time,  then,  because  lately  I’ve  been 
dodging  them  left  and  right. 

The  steamships  in  question  are  Object- 
Oriented  Programming  systems  (OOPs). 
That  acronym  may  be  the  most  unfor¬ 
tunate  or  perhaps  the  most  deliciously 
ironic  one  ever  used  in  our  industry. 
Laugh  if  you  must  (I  do,  regularly)  but 
OOPs  are  coming  of  age,  and  you  owe 
it  to  yourself  to  spend  a  little  time  in 
understanding  them. 

In  a  handful  of  words,  object  ori¬ 
ented  programming  is  the  next  genera¬ 
tion  of  structured  methods  —  code  has 
married  data,  and  the  offspring  are  Some¬ 
thing  Else  Entirely.  In  keeping  with  the 
mission  of  “Structured  Programming,"  my 
next  several  columns  will  be  devoted 
to  object-oriented  languages,  with  an 
emphasis  on  how  you  can  get  involved. 

The  Steam  Whistle  Bloweth 

I  first  heard  the  steamship  whistles  last 
year  at  Software  Development  ’88,  a 
show  devoted  utterly  to  (hallelujah!) 
programmers  and  their  craft.  There 
wasn’t  much  in  the  line  of  products  on 
the  show  floor,  but  the  OOPs  sessions 
were  SRO.  I  knew  what  OOPs  were, 
having  worked  at  Xerox  through  most 
of  the  time  that  PARC’s  seminal  OOPs 
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research  was  going  on.  I  programmed 
in  Smalltalk  on  an  Alto  workstation  in 
1979,  an  experience  that  led  me  to 
write  OOPs  off  as  costing  more  in  ma¬ 
chine  performance  than  it  was  worth. 
I  was  dead  wrong  there,  having  shot  the 
marathon  runner  for  riding  his  little 
brother’s  tricycle. 

At  Software  Development  '89,  I  saw 
real  OOPs  code  steaming  along  at  flank 


speed.  The  code  was  written  in  a  vari¬ 
ant  of  (arrgh)  C,  but  the  point  was  not 
lost  on  me:  Taken  together,  object- 
oriented  methods  are  a  way  of  thinking 
about  programming  that  are  tied  to  no 
particular  language.  With  minimal  syn¬ 
tactic  extension,  any  language  at  all 
can  be  object-oriented  .  .  . 

...  as  we’re  beginning  to  find  out. 

Structure  of  Structures 

Object  orientation  is  extremely  difficult 
to  define.  Most  people  don’t  try  to  de¬ 
fine  it;  they  simply  start  by  saying,  “Ob¬ 
ject-oriented  programming  allows  you 
to  create  easily  reusable  software  com¬ 
ponents  ...”  or  “Object-oriented  pro¬ 
gramming  allows  you  to  extend  exist¬ 
ing  modules  without  requiring  source 
code  .  .  .  ,”  or  something  else.  This  isn’t 
explaining  what  object-oriented  program¬ 
ming  is,  this  only  tells  you  what  it  does — 
and  only  part  of  what  it  does,  at  that. 

Let  me  be  glib  and  hand  you  my 
own  definition,  which  (like  most  very 
high-level  definitions)  needs  some  ex¬ 
pounding:  Object-oriented  program¬ 
ming  is  structured  structured  program¬ 
ming.  It’s  the  second  derivative  of  soft¬ 
ware  development,  the  Grand  Unifying 
Theory  of  program  structure.  Choose  your 
metaphor,  I  got  a  million  of  ’em.  What 
you  must  understand  is  that  object  ori¬ 
entation  is  no  single  technique,  no  sin¬ 
gle  language,  and  no  single  approach. 
It  is  many  techniques  bound  together 
in  synergistic  fashion  to  produce  nu¬ 
merous  benefits,  under  the  guidance 
of  a  very  high-level  mindset  that  Mike 
Swaine  would  call  a  paradigm  shift. 

For  this  reason,  it’s  a  little  scary,  and 
as  with  all  scary  things  like  sex,  death, 
or  steam  locomotives  there’s  a  tendency 
to  make  it  all  mystical  and  legendary. 
Resist  —  and  relax.  Rather  than  a  fount 
of  mystical  wisdom,  object-oriented  tech¬ 
niques  are  more  like  modern  sanita¬ 
tion:  A  way  of  living  that  combines 
numerous  small  elements  —  indoor 


plumbing,  running  water,  regular  bath¬ 
ing,  washing  of  food,  refrigeration,  child¬ 
hood  inoculation,  and  so  forth  —  into 
an  easy  regimen  that  has  nearly  doubled 
the  human  lifespan  in  the  last  hundred 
years.  That’s  not  immortality,  but  it’s  a 
helluva  step  in  the  right  direction. 

Which  is  how  one  should  feel  about 
OOP:  Not  instantaneous  bug-free  pro¬ 
gramming,  but  still  a  helluva  step  in  the 
right  direction.  Over  the  next  several 
columns  I’ll  be  gradually  defining  object- 
oriented  programming,  and  showing 
the  tools  you  can  use  to  learn  it  and 
benefit  from  it.  I’ll  have  to  beg  your 
patience  —  the  subject  is  such  that  you 
won’t  catch  the  essence  in  200  words 
or  less.  There  is  no  single  good  place 
to  begin,  so  let’s  catch  the  first  steam¬ 
ship  that  happens  by. 

Catching  the  NeXT  Steamship 

I  throw  regular  parties  down  here,  and 
I  exhort  the  invitees  to  bring  wives,  hus¬ 
bands,  or  Significant  Others.  Bruce  Web¬ 
ster  took  me  at  my  word  about  a  month 
ago.  He  has  a  perfectly  wonderful  wife, 
but  instead  he  brought  his  current  Sig¬ 
nificant  Other:  A  NeXT  workstation. 

So  significant  was  NeXT  that  the  party 
goers  forgot  all  about  the  pool,  the  hot 
tub,  and  even  my  copy  of  Tetris.  What 
might  have  been  an  academic  curiosity 
or  (my  own  view)  a  dazzling  way  to 
waste  several  hundred  million  dollars 
has  been  turned  into  a  killer  product 
by  the  simple  decision  to  market  the 
unit  to  ordinary  people,  through  the 
Businessland  retail  chain.  $10,000  may 
seem  like  a  lot  of  money,  but  most  new 
cars  cost  more  than  that,  and  if  you’re 
a  front-line  knowledge  worker,  your 
machine  may  mean  far  more  to  your 
bottom  line  than  your  car. 

But  I’ll  leave  that  decision  to  you. 
NeXT  interests  me  because  its  operat¬ 
ing  environment  is  object-oriented,  from 
top  to  bottom.  Some  say  Jobs  was  fish¬ 
ing  for  publicity  and  hooking  into  a  fad 
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when  he  made  NeXT  an  object-ori¬ 
ented  machine.  No  way — Jobs  used 
OOP  techniques  because  he  simply  had 
no  choice.  It  was  that  or  drown  in 
complexity. 

Which  brings  me  to  the  #1  raison 
d’etre  for  OOPs:  The  management  of 
complexity.  Some  of  you  may  well  have 
tried  developing  for  the  Mac.  Fewer  of 
you  (I  suspect)  have  taken  a  stab  at 
Windows  development,  and  almost  no 
one  in  the  civilized  galaxy  has  both¬ 
ered  to  crack  the  OS/2  Presentation 
Manager  documentation. 

The  problem  in  all  cases  is  the  com¬ 
plexity  of  the  API.  DOS  presents  us 
with  a  few  dozen  function  calls,  most 
of  them  independent  and  taking  at  best 
three  or  four  parameters.  Full-blown 
operating  environments  like  the  Mac, 
Windows,  or  PM  contain  hundreds  of 
function  calls,  many  of  them  needing 
a  dozen  or  more  parameters  that  inter¬ 
lock  with  other  function  calls  and  other 
parameters  in  ways  that  make  your  head 
spin.  It  is  the  nature  of  the  human  mind 
to  focus  on  one  or  two  things  at  once. 
(Close  your  eyes  and  try  to  clearly  imag¬ 
ine  a  field  of  more  than  four  abstract 
items  and  see  how  easy  it  is.)  Develop¬ 
ing  for  one  of  the  operating  environ¬ 
ments  requires  that  you  float  that  whole 
interlocking  mess  in  front  of  your  mind 
from  the  word  go. 

A  couple  of  years  ago,  Apple  pro¬ 
duced  an  object-oriented  wrapper  for 
the  Mac  API  called  MacApp.  It  imposed 
a  structure  on  the  Mac  API  by  identify¬ 
ing  the  elements  of  the  interactive  en¬ 
vironment  as  quasi-independent  com¬ 
ponents.  Windows,  menus,  scroll  bars, 
buttons,  all  of  these  were  set  out  in  a 
hierarchy  looking  a  lot  like  a  taxonomy 
chart.  Each  type  of  element  was  called 
a  class,  and  to  create  and  use  a  win¬ 
dow,  you  simply  created  an  instance 
of  the  window  class.  This  window  in¬ 
stance  was  an  object,  and  it  contained 
an  interface  to  only  that  code  and  data 
needed  to  create  and  use  a  window. 
You  might  think  of  objects  as  halfway 
between  code  and  data,  or  as  a  larger 
concept  that  embraces  both  code  and 
data.  But  never  forget  that  code  and 
data  must  be  considered  together  in 
OOPs,  and  nevermore  put  asunder. 

Each  Object  in  its  Place 

I’ve  drawn  up  a  simple  object  hierar¬ 
chy  chart  in  Figure  1.  It’s  not  intended 
to  represent  MacApp  specifically,  but 
could  apply  to  nearly  any  windowing 
environment.  Each  of  the  boxes  repre¬ 
sents  an  object  type  or  class.  Each  class 
has  a  specific  role  in  life,  which  I’ve 
written  near  each  box.  The  Screen  type 
is  a  full  screen,  and  models  the  rela¬ 


tionship  between  an  abstract  display 
and  the  real  physical  display  controller 
board.  If  you  send  a  character  to  a 
Screen  object,  it  will  pass  those  charac¬ 
ters  along  to  the  display  controller.  That’s 
about  all  Screen  can  do. 

Windoiv  adds  a  little  pizzazz  to  Screen 
by  being  a  rectangular  chunk  of  the 
screen,  perhaps  with  a  border.  A  Win¬ 
dow  has  a  size  and  a  position  within  a 
Screen ,  and  may  be  dragged  around 
the  screen  with  the  mouse  or  cursor 
pad,  and  enlarged  or  reduced  in  size. 
That’s  about  all  that  a  Window  object 
can  do. 

Note,  however,  that  if  you  send  char¬ 
acters  to  Window ,  it  will  pass  them 
onto  the  display  controller.  It  does  this 
using  the  same  mechanisms  built  into 
type  Screen.  Window  inherits  every¬ 
thing  that  Screen  is,  by  virtue  of  being 
beneath  Screen  in  the  object  hierarchy. 

Beneath  Window  are  two  different 
classes:  Field  and  Menu.  A  Field  has 
the  power  to  display  and  edit  a  value 
of  some  kind.  A  Menu  displays  several 
items  and  chooses  one  from  the  group. 
Field  and  Menu  are  distinct  from  one 
another,  but  they  inherit  everything  that 
both  Screen  and  Window  have  within 
them:  Both  menus  and  fields  have  a 
size  and  a  position  and  can  be  dragged 
around  the  screen,  and  both  send  char¬ 
acters  to  the  display  controller. 

At  each  level  in  the  chart,  the  objects 
get  a  little  more  powerful,  a  little  more 
specific  —  and  a  little  more  useful.  Be¬ 
neath  Menu  are  two  real  varieties  of 
menu,  Popup  and  Matrix.  Both  inherit 
the  essence  of  a  menu  —  to  display 
several  items,  then  accept  input  from 
the  user  to  choose  one  of  those  items  — 
but  each  does  the  actual  work  in  its 
own  way. 


Figure  1:  A  hierarchy  of  objects 


The  huge  mass  of  detail  of  a  win¬ 
dowing  environment  API  is  distributed 
across  the  hierarchy  in  a  rational,  grasp- 
able  manner.  Direct  control  of  the  dis¬ 
play  hardware  is  gathered  behind  class 
Screen.  Sizing  and  dragging  of  win¬ 
dows  is  gathered  behind  class  Window 
and  so  on. 

In  short,  to  use  a  pop-up  menu  ob¬ 
ject  in  this  scheme,  you  narrow  your 
attention  to  one  item,  a  software  model 
of  a  real  menu  that  draws  together 
all  the  disparate  function  calls  and 
data  items  that  you  would  otherwise 
have  to  hunt  up  and  pull  together  on 
your  own  from  that  mess  of  an  API.  I 
should  point  out  that  there  are  other 
ways  to  simplify  an  API,  but  object- 
orientation  provides  additional  bene¬ 
fits  related  to  the  inheritance  concept 
that  I  will  touch  on  in  future  columns. 

There’s  a  lot  more  to  both  MacApp 
and  object-oriented  programming  than 
just  this,  of  course.  Managing  complex¬ 
ity  is  a  major  benefit  of  OOPs,  but  not 
the  only  one,  and  inheritance  is  one 
mechanism  within  OOPs,  but  again, 
there  are  more.  If  you  want  to  know 
more  from  a  Macintosh  perspective, 
get  the  superb  Object-Oriented  Program¬ 
ming  for  the  Macintosh ,  by  Kurt  J. 
Schmucker  (Hayden  Books,  1986.)  The 
point  I’m  making  is  that  objects  are  one 
way  of  managing  complexity  by  hiding 
details  behind  a  software  model  that 
relates  to  the  problem  at  hand  and  no 
more.  The  hierarchy  of  MacApp  allows 
a  programmer  to  see  only  what  he  needs 
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to  see  at  any  given  time  in  the  develop¬ 
ment  process  without  tripping  over  un¬ 
related  details.  It  was  Mr.  Structure  him¬ 
self,  Niklaus  Wirth,  who  defined  struc¬ 
tured  programming  as  the  artful  hiding 
of  details.  Object-oriented  programming 
is  a  world-class  method  of  hiding  un¬ 
necessary  details,  and  it’s  about  as  art¬ 
ful  as  they  come. 

Which  is  fortunate,  because  the  Pres¬ 
entation  Manager  API  makes  the  Macin¬ 
tosh  look  elegant  and  obvious  by  com¬ 
parison.  We  may  never  really  know 
how  difficult  the  NeXT  machine  would 
be  to  program  in  the  absence  of  an 
OOPs,  because  the  operating  system 
is  the  OOPs,  and  what  structure  MacApp 
imposes  on  the  underlying  Mac  API,  Next- 
Step  imposes  on  itself.  All  the  compo¬ 
nents  of  the  operating  system  and  the 
elegantly-designed  (and  monochrome, 
hurrah!)  user  interface  are  objects. 

NextStep  incorporates  a  new  lan¬ 
guage  called  Objective  C.  Objective  C 
represents  an  opinion  watershed  for 
me  —  allowing  me  to  believe  that,  by 
gully,  this  object  stuff  may  civilize  C 
yet.  Still,  this  is  the  un-C  column,  and 
I’ll  leave  it  to  my  cohorts  here  to  fill  you 
in  on  the  details  of  both  Objective  C 
and  NextStep.  To  get  a  flavor  for  Ob¬ 
jective  C  and  OOPs  at  the  same  time, 
read  Object-Oriented  Programming:  An 
Evolutionary  Approach  by  Brad  Cox. 
Cox  defined  Objective  C,  and  he  has 
an  intriguing  metaphor  for  objects:  Soft¬ 
ware  IC’s,  plugable  modules  that  may 
be  considered  “black  boxes”  and  used 
without  alteration  in  many  diverse  ap¬ 
plications.  This  is  an  important  facet 
of  any  OOPs,  but  by  no  means  the  only 
or  even  the  most  important  one. 

The  point  to  carry  away  from  the 
NeXT  steamship  is  this:  By  the  artful 
hiding  of  details,  NextStep  makes  the 
NeXT  API  much  easier  to  grasp  and 
manipulate  than  Mac,  Windows,  or  PM. 
The  component-modelling  nature  of 
OOP  makes  such  detail  hiding  easy.  If 
the  OOPs  paradigm  shift  does  nothing 
else,  it  will  have  earned  its  keep  for 
that  alone. 

Steamship  Seen  Through 
Windows,  Darkly 

Neither  Windows  nor  PM  have  any¬ 
thing  resembling  MacApp  yet ...  or  do 
they?  I  have  fielded  some  tantalizing 
rumors  indicating  that  Microsoft  is  about 
to  go  head-to-head  with  Borland  with 
an  environment-based  Pascal  compiler. 

If  it’s  true,  it  will  be  an  intriguing 
mix:  An  object-oriented  Turbo  Pascal 
compatible  Pascal  compiler  that  (gasp) 
generates  Windows  applications. 

Back  in  my  PC  Tech  Journal  days  I 
told  Microsoft  that  Windows  would  not 


hit  the  big  time  until  there  were  a  de¬ 
velopment  environment  for  it  that  in¬ 
telligently  managed  the  complexity  of 
the  API.  That  advice  sank  like  a  stone, 
as  did  my  editorship  at  PC  Tech  Jour¬ 
nal ,  as  eventually  did  PC  Tech  Journal 
itself.  In  the  intervening  years  we’ve 
seen  a  handful  of  solid  applications 
appear  for  Windows  —  and  handfuls 
are  emphatically  not  the  big  time.  The 
Windows  API  is  daunting,  and  the  Win- 

If  you  need  to  gussy 
up  the  text  editor 
window  a  little ,  you 
don ’t  have  to  start  from 
scratch 


dows  Software  Development  Toolkit 
(SDK)  is  chaotic.  Something  needs  to 
bring  order  to  the  Windows  and  PM 
APIs,  and  it  would  be  just  too  deli¬ 
ciously  ironic  if  Microsoft,  the  C-Is-The- 
Only-Way-To-Go  (except  maybe  for  Ba¬ 
sic)  company  decided  to  use  a  Pascal 
compiler  to  do  the  job. 

By  the  time  you  read  this,  we  should 
know  the  truth. 

Board  the  SS  Turbo! 

By  the  time  I  heard  the  Microsoft  ru¬ 
mor,  the  steamships  were  already  get¬ 
ting  pretty  thick  around  here.  Then  an¬ 
other  mast  heaved  over  the  horizon, 
with  Philippe  Kahn  tooting  the  whistle. 
This  one  is  for  real:  In  May  Borland 
released  Turbo  Pascal  5.5,  with  new 
technology  making  Turbo  Pascal  fully 
object-oriented  in  some  interesting  and 
innovative  ways. 

Contrary  to  conventional  wisdom,  it 
doesn’t  take  a  whole  new  and  exotic 
language  specification  to  support  object- 
oriented  programming.  Borland  did  it 
by  adding  only  four  new  reserved  words 
to  Turbo  Pascal:  OBJECT,  VIRTUAL, 
CONSTRUCTOR,  and  DESTRUCTOR. 
If  your  existing  source  code  does  not 
use  those  four  reserved  words,  all  object- 
oriented  extensions  will  be  completely 
transparent  to  you.  You  can  use  objects 
or  ignore  them;  it’s  your  choice.  (If  you 
ignore  them,  however,  you’re  nuts.) 

There  is  no  genuine  standard  for  object- 
oriented  Pascal,  so  Borland  drew  on 
numerous  existing  languages:  C++, 
Macintosh  Object  Pascal,  and  Oberon, 
the  latest  language  concocted  by  Niklaus 
Wirth.  Unlike  C++,  the  object  exten¬ 


sions  are  not  a  separate  module  or 
some  sort  of  preprocessor.  And  unlike 
the  older  OOPs  like  Smalltalk  and  Actor, 
you  can  choose  the  degree  to  which  a 
program  will  be  object-oriented.  In  Turbo 
fashion  there  are  mainstream  objects 
and  optimized  objects,  and  you  the  pro¬ 
grammer  get  to  decide  which  sort  of 
object  is  the  best  for  a  given  application. 

Welding  code  to  data  presents  some 
novel  problems  in  debugging,  so  Turbo 
Debugger  was  upgraded  simultane¬ 
ously,  with  new  inspectors  built  in  spe¬ 
cifically  to  poke  around  inside  objects. 
One  nice  touch  is  a  hierarchy  inspec¬ 
tor,  which  shows  a  little  taxonomy  chart 
of  all  object  types  present  in  the  mod¬ 
ule  being  debugged. 

I  haven’t  had  enough  time  yet  to 
write  any  significant  code  in  object- 
style  Turbo  Pascal,  but  what  I’ve  seen 
so  far  is  clean  to  the  point  of  being 
elegant.  I’ll  be  spending  a  lot  more 
time  on  Turbo  Pascal  objects  in  future 
columns.  Right  now,  I’d  say,  Upgrade. 
Without  hesitation. 

Already  at  the  Dock 

With  all  the  steamships  steaming  into 
shore,  it’s  easy  enough  to  ignore  the 
ones  that  have  been  at  the  dock  for 
some  time.  Apart  from  Zortech  C++ 
(which  I’ll  let  the  C  folks  discuss)  there 
are  two  longstanding  reasonably  priced 
OOPs  for  DOS:  Smalltalk/V  and  Actor. 
Both  have  been  around  since  ’85  or  ’86, 
and  I  have  been  using  both  off  and  on 
since  that  time.  Both  are  solid  products, 
well-documented,  and  a  lot  of  fun. 

Smalltalk/V,  at  $100,  is  the  cheapest 
OOPs  you  can  buy  right  now,  and  if 
you  have  a  disposable  $100  it’s  one  of 
the  best  ways  to  get  comfortable  with 
the  concepts  of  object-oriented  pro¬ 
gramming.  The  reasons  are  two:  Small¬ 
talk  is  totally  object-oriented,  in  a  way 
that  permeates  every  corner  of  the  lan¬ 
guage.  If  you  understand  Smalltalk,  you 
have  OOPs  in  your  hip  pocket.  Also, 
Smalltalk  is  certainly  the  best  docu¬ 
mented  OOPs  in  history,  due  to  a  su¬ 
perb  line  of  books  from  Addison- Wesley 
that  came  out  of  Xerox  in  the  early  1980s. 
Digitalk’s  own  documentation  is  excel¬ 
lent,  and  with  the  Addison- Wesley 
books  you  have  everything  you  need. 

Space  is  short,  so  I’ll  leave  Smalltalk 
for  the  time  being.  My  next  column  will 
focus  on  Smalltalk,  and  I’ll  provide  the 
whole  list  of  Smalltalk  titles,  along  with 
information  on  the  various  versions  of 
Smalltalk  on  the  market  right  now. 

The  Pioneers  and  the  Arrows 

Actor  is  a  bit  of  a  nonesuch.  I’ve  often 
felt  that  the  old  saw  “Pioneers  get  ar¬ 
rows”  applies  with  considerable  force 
to  The  Whitewater  Group.  They  had 
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the  vision  to  provide  an  easy-to-use 
development  environment  for  Micro¬ 
soft  Windows  back  in  1986,  while  Mi¬ 
crosoft  still  forces  developers  to  slog 
through  the  swamp  of  their  intolerable 
SDK.  Yet  for  all  that,  Actor  hasn't  taken 
over  the  Windows  world  as  I  was  sure 
it  would  two  years  ago. 

Unlike  Smalltalk  (with  which  it  is 
often  unfairly  compared)  Actor  creates 
stand-alone  programs  that  do  not  re¬ 
quire  the  presence  of  the  Actor  product 
to  execute.  (All  generated  programs, 
however,  are  WinApps  and  require  Mi¬ 
crosoft  Windows.)  The  code  is  fast,  the 
manual  is  very  good,  and  aftermarket 
books  are  beginning  to  appear.  I’ve 
seen  the  manuscript  for  Object-Oriented 
Programming  With  Actor  by  Marty 
Franz,  and  it  will  be  well  worth  its 
cover  price  both  as  a  tutorial  for  Actor 
users  and  as  a  preview  for  those  who 
want  to  see  what  the  language  is  like 
before  they  buy  the  product.  Expect 
the  book  to  appear  in  October. 

Apart  from  being  the  only  rational 
development  environment  Windows 
has  ever  had,  much  of  Actor’s  value  lies 
in  the  object  hierarchy  they  give  you, 
out  of  the  box,  for  managing  Windows 
complexity.  The  leverage  of  the  pack¬ 
age  has  to  be  experienced  to  be  be¬ 
lieved.  You  really  can  write  a  text  edi¬ 
tor  window  in  two  Actor  statements, 
just  as  their  ads  say,  because  Whitewa¬ 
ter  has  already  created  the  text  editor 
class.  All  you  need  to  do  is  create  an 
instance  variable  of  that  class,  and  you 
have  a  text  editor  window.  Like  so: 


MyEditor  :=  New(EditWindow, 

ThePort,"editmenu" 
"Editor",  nil); 

Show(My  Editor,  1 ); 

If  you  need  to  gussy  up  the  text  editor 
window  a  little,  you  don’t  have  to  start 
from  scratch.  You  just  hang  a  new  class 
beneath  the  editor  window  class  on  the 
hierarchy,  and  add  what  needs  adding. 
Inheritance  allows  your  new  editor  class 
to  be  everything  Whitewater’s  canned 
editor  class  is,  with  your  own  custom 
extensions  melted  seamlessly  in. 

Any  user  interface  component  that 
you  might  want  to  put  in  a  Windows 
application  is  represented  on  the  Actor 
object  hierarchy.  They’re  like  templates: 
You  grab  a  template  off  the  hierarchy 
and  whack  out  a  new  copy  of  an  object 
for  your  use.  The  tangled  web  of  the 
Windows  API  is  way  back  there  some¬ 
where,  so  far  back  you  can  forget  about 
it  and  get  the  real  work  of  writing  your 
application  done. 

This  is  amazing  stuff.  Why  then  hasn’t 
Actor  gotten  the  recognition  it  deserves? 
As  much  as  I  like  Actor  (and  in  many 
ways  I  like  it  better  than  Smalltalk,  with 
which  I  have  been  acquainted  for  al¬ 
most  ten  years)  I  see  two  serious  prob¬ 
lems:  First  of  all,  Actor  is  a  whole  new 
language  spec.  It’s  something  like  Pas¬ 
cal,  a  little  like  C,  a  very  little  like  Forth, 
and  quite  a  bit  like  Smalltalk.  These  are 
strange  bedfellows  indeed,  and  while 
it’s  a  perfectly  reasonable  language  spec, 

I  have  found  no  compelling  reason 
why  it  had  to  be  as  different  as  it  is  from 
Pascal  or  C.  Life  is  too  short  to  get  really, 
really  good  at  more  than  one  or  two 
languages,  and  I  think  the  learning  curve 


has  driven  away  many  potential  users. 

Second,  and  related  to  the  first  prob¬ 
lem,  is  that  Actor  costs  $500.  This  is 
cheap  if  you  want  to  develop  for  Win¬ 
dows,  but  if  you  want  to  see  if  a  new 
language  spec  is  worth  learning,  there’s 
no  inexpensive  way  to  try  it  out  short 
of  stealing  a  copy  somewhere.  Baskin- 
Robbins  makes  those  teeny  spoons  for 
giving  away  samples  of  Garlic  Avocado 
ice  cream  because  most  people  are  not 
going  to  spend  a  buck-fifty  on  a  cone 
full  of  stuff  that  they  might  or  might 
not  want  to  swallow.  If  Actor  were  a 
WinApp-generating  implementation  of 
Pascal  or  C  this  would  not  be  the  case. 
Alas,  Actor  needs  a  cheap  version  of 
itself  for  the  language  tire-kickers. 

I’ll  have  more  to  say  about  Actor  in 
a  future  column,  particularly  if  rumors 
of  a  Windows  version  of  Quick  Pascal 
turn  out  to  be  true.  If  you  have  any 
need  to  develop  for  Windows,  trust 
me:  The  $500  price  tag  is  cheap  com¬ 
pared  to  the  time  and  torn  hair  that  you 
will  save  over  using  the  SDK.  Learning 
it  takes  a  week  or  so,  but  what’s  learned 
is  learned  —  and  you  will  pick  up  plenty 
of  OOPs  savvy  along  the  way  for  free. 

Steaming  for  Home 

Last  night  I  heard  that  a  friend  of  mine 
had  kicked  off  a  cold  fusion  reaction 
in  a  pickle  jar  full  of  laboratory-purity 
heavy  water.  Chemical  reaction?  Kind 
of  hard  when  there’s  only  one  chemi¬ 
cal  in  the  jar.  (He  washed  the  dill  resi¬ 
due  out  before  using  it,  trust  me.)  OK, 
but  is  it  fusion? 

Who  knows?  But  hey,  who  cares?  If 
more  energy  is  coming  out  of  the  jar 
than  is  going  in,  it  could  be  angels  on 
treadmills  and  it  wouldn’t  matter.  If  the 
process  is  perfectible  and  scalable,  this 
could  be  Year  One  of  the  Millennium. 
My  swimming  pool  contains  about  three 
gallons  of  heavy  water  (all  water  on 
Earth,  in  fact,  contains  one  part  in  7000 
of  heavy  water)  which  would  heat  my 
house  and  run  my  car  for  about  ten 
thousand  years.  Separating  ordinary  and 
heavy  water  can  be  done  with  solar 
energy  and  requires  no  exotic  materi¬ 
als  or  equipment  and  does  not  involve 
radioactivity. 

The  point  is  this:  You  don’t  need 
Lawrence  Livermore  Labs  to  change 
the  world.  No  sir.  You  don’t  need  a 
supercomputer  to  change  the  world. 
Uh-uh.  The  age  of  Desktop  Physics  has 
returned,  after  a  70-year  hiatus. 

No,  all  you  need  is  a  pickle  jar,  a  PC 
clone,  and  Turbo  Pascal. 

DDJ 
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C  PROGRAMMING 


Listing  One  ( Text  begins  on  page  113J 

/* - b j  . c - */ 

/* 

*  A  Blackjack  Simulation 
*/ 


void  cleargame (void) ; 
void  nohand(CARD  *lst,  int  x,  int  y) ; 
void  nocardf rame (int  x,  int  y) ; 
int  handvalue (int  pi); 
void  stat  (int  p,  char  *s); 


♦include  <conio.h> 

♦include  <stdio.h> 

♦include  <stdlib.h> 

♦include  <ctype.h> 

♦include  <time.h> 

♦define  TRUE  1 
♦define  FALSE  0 
♦define  IBMPC 

/*  -  ANSI. SYS  screen  controls  -  */ 

♦define  clr_scrn()  puts ("\033 [2J") 

♦define  cursor <x,y)  printf ("\033 [%02d;%02dH", y+1, x+1) 

/* - for  display  purposes -  */ 

♦define  CARDWIDTH  5 
♦define  CARDHEIGHT  4 

♦define  PLAYERS  7  /*  number  of  players  (not  incl  dealer)  */ 
♦define  DECKS  6  /*  number  of  decks  to  play  */ 

♦define  CARDS  (52*DECKS) 


void  main (void) 

( 

int  i,  s,  v; 
clr_scrn () ; 

/*  —  build  the  decks  of  cards  in  the  discard  pile  —  */ 
for  (i  =  0;  i  <  DECKS;  i++) 
for  (s  =0;  s  <  4;  s++) 

for  (v  =  0;  v  <  13;  v++)  ( 

discards [nextdisc] .value  =  v; 
discards [nextdisc++] . suit  =  suits [s]; 

I 

/* - initialize  the  players - */ 

for  (i  =  0;  i  <  NBRP LAYERS- 1 ;  i++)  ( 

players ( i ] .bet  =  1; 
players [i] .strat  =  pstrategy; 

/*  —  every  other  player  is  a  split  -  */ 

players [i] .playing  =  ! (i  6  1) ; 

1 

players (dealer] .playing  =  TRUE; 
play  ()  ; 
clr  scrn  () ; 


the  card  display  characters 


♦define 

UL  218 

/*  IBM  Graphics 

upper  left  box  corner 

*/ 

void  play(void) 

♦define 

HZ  196 

/* 

box  horizontal  line 

*/ 

{ 

♦define 

UR  191 

/* 

upper  right  box  corner 

*/ 

int  c; 

♦define 

VT  179 

/* 

box  vertical  line 

*/ 

while  (TRUE)  | 

♦define 

LL  192 

/• 

lower  left  box  corner 

*/ 

if  (stopping  kbhitO)  ( 

♦define 

LR  217 

/* 

lower  right  box  corner 

*/ 

if  ((stopping  I!  NBRPLAYERS 

♦define 

HEARTS 

3 

c  =  getchO ; 

♦define 

DIAMONDS 

4 

else  ( 

♦define 

CLUBS 

5 

c  =  stopper; 

♦define 

SPADES 

6 

stopper  =  FALSE; 

♦else 

) 

♦define 

UL  '  .' 

/*  ASCII 

upper  left  box  corner 

*/ 

if  (c  ==  27) 

♦define 

HZ  '-' 

/* 

box  horizontal  line 

*/ 

break; 

♦define 

UR  '  .' 

/* 

upper  right  box  corner 

*/ 

if  (tolower (c)  ==  'd' ) 

♦define 

vt  ' :' 

/* 

box  vertical  line 

*/ 

display  A=  TRUE; 

♦define 

LL  'V' 

/* 

lower  left  box  corner 

*/ 

if  (c  ==  ' s' ) 

♦define 

LR  '\" 

/* 

lower  right  box  corner 

*/ 

stopping  A=  TRUE; 

♦define 

HEARTS 

'h' 

1 

♦define 

DIAMONDS 

'd' 

playahand ( ) ; 

♦define 

CLUBS 

'  c' 

> 

♦define 

SPADES 

'  s' 

) 

♦endif 

/*  - play  one  hand  of  blackjack 

void  playahand(void) 

/* - 

- the 

card  display  values 

- */ 

1 

char  topline[]  = 

(UL,  HZ,  HZ, 

HZ, 

UR,  0); 

int  p,  i,  bnk; 

char  midline  [  ]  = 

(VT, 

*  ' 

VT,  0); 

CARD  *cd; 

char  botline[)  = 

(LL,  HZ,  HZ, 

HZ, 

LR,  0); 

/* - deal  everyone  one  card 

int  suits []  =  (HEARTS, DIAMONDS, 

CLUBS 

, SPADES } ; 

for  (p  =  0;  p  <  NBRPLAYERS;  p++) 

char  *vals[]  =  ( 

A", "2", "3", "4' 

,  "5", 

"6", "7", "8", "9", "10", 

if  (players [p] .playing  ==  TRUE) 

/*  - a  card  — 

typedef  struct  crd  { 
int  value; 
int  suit; 

)  CARD; 

/* - a  player 

typedef  struct  ply  { 
CARD  phand[10]; 
int  playing; 
int  cards; 
int  bank; 
int  bet; 
int  mode; 
int  pushing; 
int  ( * st rat ) ( int ) ; 

}  PLAYER; 


*/ 


/*  the  player's  hand  */ 
/*  true  if  the  player  is  playing  */ 
/*  the  card  count  in  the  hand  */ 
/*  player's  bank  account  */ 
/*  player's  bet  amount  */ 
/*  D  =  double-down  */ 
/*  true  =  player  tied  last  hand  */ 
/*  pointer  to  hit/pass  strategy  */ 


/*  -  i  per  player,  1  per  split, 

♦define  NBRP LAYERS  (PLAYERS*2+1) 
int  hands; 

♦define  dealer  (NBRPLAYERS-1) 

PLAYER  players  [NBRP LAYERS +1 ] ;  / 

CARD  shoe [CARDS];  / 

CARD  discards [CARDS] ; 


int  next shoe; 
int  inshoe; 
int  nextdisc; 
int  display=TRUE; 
int  stopping=TRUE; 
int  stopper; 


the  players  */ 
the  shoe  */ 
the  discards  */ 

/*  shoe  subscript  *7 

/*  #  cards  in  the  shoe  */ 

/*  discard  subscript  */ 

/*  true  if  hands  are  being  displayed 

/*  true  if  display  stops  at  every  hand 
/*  the  key  that  restarts  the  display 


} 


nextcard (players [p] .phand) ; 
players [p] .cards++; 
showhand (p) ; 


/*  -  deal  each  of  the  players  a  second  card  - 

for  (p  =  0;  p  <  dealer;  p++)  ( 

if  (players [p] .playing  ==  TRUE)  ( 
nextcard (players [p] .phand+1) ; 
players [p] .cards++; 

/*  —  test  to  see  if  this  player  should  split 
if  (split (p) )  ( 

/* - split  the  hand - */ 

players [p] .cards  =  1; 
players [pj .phand[l] . suit  = 

playersfp] .phand[l] .value  =  0; 
bnk  =  players [p+1] .bank; 
players [p+1]  =  players [p]; 
players [p+1 j .bank  =  bnk; 
stat (p,  "SPLT”); 

) 

showhand (p)  ; 


/*  deal  the  rest  of  the  hand  for  each  player  in  turn  */ 
for  (p  =  0;  p  <  NBRPLAYERS-1;  p++)  ( 

if  (players [p] .playing  ==  TRUE)  { 

while  (!bj_bust(p)  (‘players [p] . strat) (p) ) 

nextcard (players [p] .phand+ (players [p] .cards++) ) ; 
showhand (p) ; 

} 


/* - prototypes - *  / 

void  shuffle (void) ; 
void  bury (void); 

void  hand(CARD  *lst,  int  x,  int  y) ; 

void  card (int  sut,  int  val,  int  x,  int  y) ; 

void  cardf rame (int  x,  int  y) ; 

void  play (void); 

void  playahand (void) ; 

int  split (int  p) ; 

void  discs (void); 

int  pstrategy (int  p) ; 

void  doubledown (int  p) ; 

int  bj_bust(int  p) ; 

int  dstrategy (int  p) ; 

void  winlose(int  p) ; 

void  won (int  p) ; 

void  lost (int  p) ; 

void  push (int  p) ; 

void  post (int  p,  char  *s); 

void  nextcard (CARD  *cd); 

void  shoes (void); 

void  showhand(int  pi); 


/* - see  if  all  the  players  went  bust - */ 

for  (p  =  0;  p  <  NBRPLAYERS-1;  p++) 

if  (players [p] .playing  ==  TRUE  &&  handvalue(p)  <=  21) 
break; 

/*  -  if  so,  the  dealer  doesn't  have  to  play  -  */ 

if  (p  <  NBRPLAYERS-1)  ( 

/* - <jeal  the  rest  of  the  dealer's  hand - */ 

while  ( !bj_bust (dealer)  &&  dstrategy (dealer) ) 
nextcard (players [dealer] .phand+ 

(players [dealer] .cards++) ) ; 
showhand (dealer) ; 

) 

/* - post  players'  wins  and  losses - */ 

for  (p  =  0;  p  <  NBRPLAYERS-1;  p++)  ( 

if  (players [p] .playing  ==  TRUE) 
winlose (p) ; 

players [p] .mode  =  FALSE; 

) 

post (dealer,  "DEAL"); 
cursor (0,  1); 

(continued  on  page  140) 
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C  PROGRAMMING 


Listing  One  (Listing  continued,  text  begins  on  page  1  IJ.) 

for  (i  =  0;  i  <  NBRPLAYERS+1;  i  +=  2) 

prin'tf("%5d  ",  players [i]  .bank+players ( l  +  l  1  .bank)  ; 

/*  —  gather  the  players'  cards  into  the  discard  pile  —  */ 
for  (p  =  0;  p  <  NBRP LAYERS;  p++)  ( 

cd  =  players [pj .phand; 
for  (i  =  0;  i  <  players [p] .cards;  i++) 
discards [nextdisc++]  =  *cd++; 

} 

/*  -  if  display  stops  on  every  hand,  read  a  key  -  */ 

if  (  opping) 

stopper  =  getch ( ) ; 
cleargame ( )  ; 
discs  () ; 

++hands; 

if  (display)  1 
cursor (40,  0)  ; 

printf I "HANDS :  %d  ",  hands); 

1 

I 

/*  -  test  to  see  if  a  player  should  split  the  hand  -  */ 

int  split (int  p) 

{ 

int  a,  b; 

a  =  players [p] .phand(0) .value  +  1; 
b  =  players [dealer) . phand [0] .value  +  1; 
if  (b  >  10) 
b  =  10; 

if  (a  ==  players ( p ] .phand[l) .value  +  1)  ( 


switch  (a) 

( 

case 

1 

return 

TRUE; 

case 

2 

case 

3 

return 

(b  >  1  44 

b  < 

8)  ; 

case 

4 

return 

(b  ==  5  : 

b 

=  6); 

case 

5 

return 

FALSE; 

case 

6 

return 

(b  >  1  44 

b  < 

7); 

case 

7 

return 

(b  >  1  44 

b  < 

8) ; 

case 

8 

return 

TRUE; 

case 

9 

return 

! (b  ==  7 

!  b 

==  10 

case 

10:  return 

FALSE; 

I 

) 

return  FALSE; 


/* - display  the  discards  pile  count  -  */ 

void  discs (void) 

1 

if  (display)  ( 
cursor (20, 0) ; 

printf ("DISCARDS:  *d  ",  nextdisc); 

) 

) 

/*  -  test  if  a  player  has  blackjack  or  went  bust  -  */ 

int  bj_bust(int  p) 

f 

int  rtn; 

if  ((rtn  =  (players(p) .cards  ==  2  44  handvalue(p)  ==  21)) 
==  TRUE) 

stat(p,  "*BJ*");  /*  player  has  blackjack  */ 

else  if  ((rtn  =  (handvalue (p)  >  21))  ==  TRUE) 

stat(p,  "BUST");  /*  player  went  bust  */ 

return  rtn; 

) 

/*  -  player  strategy  (true  =  hit,  false  =  stand)  -  */ 

int  pstrategy (int  p) 

{ 

int  b,  h; 

/*  -  smart  player  watches  dealers  up  card  -  */ 

b  =  players (dealer] .phand[0] .value+1; 
h  =  handvalue (p) ; 
if  (players [p] .mode  ==  'D') 
return  0; 

if  (players [p] .cards  ==  2  44 

players [p] .phand[0] .value+1  ==  1  ;; 
players [pj .phand[lj .value+1  ==  1)  | 

switch  (h)  ( 

case  3: 

case  4 :  if  (b  ==  5  :  ;  b  ==  6) 
doubledown (p) ; 
return  TRUE; 

case  5: 

case  6:  if  (b  >  3  Si  b  <  7) 
doubledown (p) ; 
return  TRUE; 

case  7:  if  lb  >  2  44  b  <  7) 
doubledown (p) ; 
return  TRUE; 

case  8:  if  (b  >  3  44  b  <  7) 
doubledown (p) ; 

if  (b  ==  2  : ;  b  ==  7  ; ;  b  ==  8) 
return  FALSE; 
return  TRUE; 
default:  break; 

) 

1 

switch  (h)  { 

case  4: 
case  5: 
case  6: 
case  7: 

case  8:  return  TRUE; 

case  9:  if  (b  >  2  44  b  <  7) 

doubledown (p) ; 
return  TRUE; 

case  10:  if  (b  >  1  44  b  <  10) 

doubledown (p) ; 
return  TRUE; 
case  11:  if  (b  !=  1) 

doubledown (p) ; 
return  TRUE; 

case  12:  return  !(b  >  3  &&  b  <  7); 


case  13: 
case  14: 
case  15: 

case  16:  return  ! (b  >  1  44  b  <  7); 

case  17: 

case  18: 

case  19: 

case  20: 

case  21:  return  FALSE; 

I 

return  FALSE; 

) 

/*  - double  down  the  hand - */ 

void  doubledown (int  p) 

( 

players [pi .mode  =  'D'; 
stat (p,  "DBDN" ) ; 

1 

/* - the  dealer  strategy -  */ 

int  dstrategy (int  p) 

I 

/*  -  dealer  hits  on  16  or  below,  stands  on  17  or  above  -  */ 
return  (handvalue (p)  <  17); 

) 

/* - test  if  a  hand  wins  or  loses - */ 

void  winlose(int  p) 

{ 

/*  —  doubled-down  hand  bets  twice  as  much  —  */ 
if  (players [p] .mode  ==  'D') 
players [pj .bet  *=  2; 

/* - value  >  21  is  a  bust - */ 

if  (handvalue (p)  >  21) 
lost (p) ; 

/*  -  blackjack  wins  if  dealer  does  not  have  blackjack  -  */ 
else  if  (handvalue (p)  ==  21  44  players [p] . cards  ==  2  44 
! (handvalue (dealer)  ==  21  44 
players [dealer] .cards  ==  2)) 
won  (p)  ; 

/* - value  greater  than  dealer  wins - */ 

else  if  (handvalue (p)  >  handvalue (dealer) ) 
won (p) ; 

/* - if  dealer  busts,  player  wins - */ 

else  if  (handvalue(dealer)  >  21) 
won (p) ; 

/*  —  if  dealer's  hand  >  player's  hand,  player  loses  --  */ 
else  if  (handvalue (p)  <  handvalue (dealer) ) 
lost (p) ; 

/*  -  tied  hand  (push)  if  none  of  the  above  —  */ 

else 

push(p) ; 

/* - reset  bet  for  doubled-down  hand - */ 

if  (players [p] .mode  ==  'D') 
players [pj .bet  /=  2; 

) 

/* - compute  the  value  of  a  hand - */ 

int  handvalue(int  pi) 

( 

CARD  *hd; 

int  vl  =  0,  cd,  aces  =  0; 


hd  =  players [pi] .phand; 
while  (hd->suit)  ( 

cd  =  hd->value+l; 
if  (cd  >  10) 
cd  =  1C; 

if  (cd  ==  1)  f 

cd  =  11; 
aces++; 

I 

vl  +=  cd; 
hd++; 

) 

while  (vl  >  21  &&  aces — ) 
vl  -=  10; 

return  vl; 


/*  point  to  1st  card  in  hand  */ 


/*  value  of  the  card  V 

/*  jack,  queen,  king  =  10  */ 

/*  ace  =  11  */ 

/*  count  aces  in  the  hand  */ 

/*  accumulate  hand  value  */ 

/*  point  to  next  card  */ 

/*  adjust  for  aces  if  >  21  */ 

/*  ace  =1  */ 


/* - the  player  won  the  hand  :-)  - *1 

void  won (int  p) 

( 

players [p] .bank  +=  players [p] .bet  +  players [ p] .pushing; 

players [p] .pushing  =  0; 

players [dealer ) .bank  -=  players ( p ] .bet; 

postfp,  "WIN  "); 

) 

/* - the  player  lost  the  hand  :-( - */ 

void  lost (int  p) 

( 

players [p] .bank  -=  players [p] .bet  +  players [p] .pushing; 

players [p] .pushing  =  0; 

players [dealer ]. bank  +=  players [p] .bet; 

post(p,  "LOSS"); 

) 

/* - the  player  tied  -  */ 

void  push(:nt  p) 

I 

players [p] .pushing  =  players [p] .bet ; 
postfp,  "PUSH"); 

» 

/* - post  the  WIN/LOSS/PUSH - */ 

void  post (int  p,  char  *s) 

( 

if  (display)  ( 

cursor (l+p*5,  24) ; 
printf ("%s",  s); 

) 

I 

/* - get  the  next  card  from  the  shoe - */ 

void  nextcard (CARD  *cd) 

f 

if  (nextshoe  ==  inshoe)  ( 

shuffled;  /*  time  to  reshuffle  */ 

bury();  /*  bury  one  */ 
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} 

*cd  =  shoe ( next shoe++ ] ; 

(Cd+'l)  ->suit  =  FALSE; 
shoes ( ) ; 

) 

/* - shuffle  the  discards  into  the  shoe - */ 

void  shuffle (void) 

{ 

int  cdp,  nd; 

if  (display)  ( 
cursor (0,0); 
printf ("SHUFFLE") ; 

) 

randomize ( ) ; 
nd  =  nextdisc; 

for  (nextshoe  =  0;  next shoe  <  nd;  nextshoe++)  [ 
cdp  =  random (nextdisc) ; 
shoe [nextshoe]  =  discards [cdp] ; 
while  (cdp  <  nextdisc)  ( 

discards [cdp]  =  discards [cdp+1] ; 
cdp++; 

1 

— nextdisc; 

1 

discs  () ; 

inshoe  =  nextshoe; 
nextshoe  =  0; 
if  (display)  I 
cursor (0, 0) ; 
printf  ("  "); 

) 

) 

/*  - bury  the  first  card - */ 

void  bury (void) 

I 

CARD  cd[2] ; 
nextcard (cd)  ; 

discards [nextdisc++]  =  *cd; 
if  (display)  ( 

card (cd [0] . suit,  cd[0]. value,  1,  16); 
cursor (1,  15); 
printf ("BURIED") ; 
if  (stopping) 

stopper  =  getchO; 
nocardframe (1,  16); 
cursor (1,  15); 
printf ("  "); 

} 


/*  -  display  the  number  of  cards  left  in  the  shoe  -  ' 

void  shoes (void) 

{ 

if  (display)  ( 

cursor (10,  0); 

printf ("SHOE:  %d  ",  inshoe-nextshoe) ; 

I 

I 

/* - display  the  hand  and  the  player's  money - */ 

void  showhand(int  pi) 

,( 

if  (display)  ( 

cursor (l+pl*5,  3); 

printf ("%d",  handvalue (pi) ) ; 

hand(players [pi] .phand,  pi ‘CARDWIDTH,  4); 

I 

) 

/*  - display  a  hand - */ 

void  handfCARD  ‘1st,  int  x,  int  y) 

I 

while  (lst->suit)  ( 

card (lst->suit,  lst->value,  x++,y); 

lst++; 
y  +-  2; 

) 

1 

/* - display  a  card - */ 

void  card(int  sut,  int  val,  int  x,  int  y) 

t 

cardframe(x,  y) ; 

cursor (x+1,  y+1) ; 

printf ("  \b\b\b"); 

printf ("%s%c”,  vals[val],  sut); 

) 

/*  - display  the  card  frame - */ 

void  cardf rame (int  x,  int  y) 

{ 

int  yl; 

cursor  (x,  y) ; 
printf (topline) ; 

for  (yl  =  y+1;  yl  <  y+CARDHEIGHT-1 
cursor (x, yl) ; 
printf (midline) ; 

1 

cursor (x, yl) ; 
printf (botline) ; 

) 

/* - clear  the  game  display  -- 

void  cleargame (void) 

f 

int  i; 

for  (i  =  0;  i  <  NBRP LAYERS;  i++)  { 

if  (players [i] .playing  ==  TRUE)  { 
if  (display)  ( 

cursor (l+i*5,  3); 
printf ("  "); 

nohand (players [i] .phand,  i* CARDWIDTH,  4) ; 

) 

players [i] .cards  =  0; 


;  yl++)  ( 


*/ 


players [i] .playing  =  ! ( i  &  1 ) ; 
stat  (i,  "  "); 

post(i,  "  "); 

I 

} 

) 

/*  -  display  a  null  hand  to  erase  the  hand  -  */ 

void  nohand (CARD  *lst,  int  x,  int  y) 

{ 

while  (lst->suit)  { 
nocardframe (x++, y) ; 
y  +=  2; 
lst++; 

} 

) 

/* - null  card  frame - */ 

void  nocardframe (int  x,  int  y) 

I 

int  yl; 

for  (yl  =  y;  yl  <  y+CARDHEIGHT;  yl++)  { 

cursor (x, yl) ; 
printf ("  "); 

) 

} 

/*  -  print  the  status  *BJ*,  BUST,  DBLD,  SPLT,  etc.  -  */ 

void  stat (int  p,  char  *s) 

( 

if  (display)  ( 

cursor (p*CARDWIDTH,  2) ; 
printf  (s) ; 

I 

I 


End  Listing 
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Listing  One  ( Text  begins  on  page  119.) 

/*  VCOORDS.C:  Implements  virtual  coordinates  in  GRAFIX  library  */ 

/*  K.  Porter,  DDJ  Graphics  Programming  Column,  July  '89  */ 

#include  <math.h> 

♦include  "grafix.h" 

/*  Variables  for  this  compile  unit  */ 

double  xf  =  1.0,  yf  =  1.0;  /*  x,  y  conversion  factors  */ 

double  ox  =  0.0,  oy  =  0.0;  /*  virtual  x,  y  origin  */ 

I*  - - -  */ 

/*  set  virtual  coordinate  space  */ 

void  far  setcoords  (double  left,  double  top,  double  right,  double  bottom) 

{ 

xf  =  (double)  vp_width()  /  (right  -  left);  /*  conversion  factors  */ 
yf  =  (double)  vp_height()  /  (bottom  -  top); 

ox  =  (double)  vp_width()  -  (right  *  xf ) ;  /*  origin  */ 

oy  =  (double)  vp_height()  -  (bottom  *  yf); 

)  /* - - - - - - - - -  */ 

int  far  dx  (double  vx)  /*  convert  virtual  x  to  device  x  */ 

( 

return  (xf  *  vx)  +  ox; 

I  /*  - - - */ 

int  far  dy  (double  vy)  /*  convert  virtual  y  to  device  y  */ 

f 

return  (yf  *  vy)  +  oy; 

)  /*  - - - - */ 


/*  Plot  the  sum  of  sine  and  cosine  */ 
set_colorl  (15); 
px  =  999; 

for  (angle  =  -360;  angle  <=  360;  angle++) 
plot  (angle,  sum) ; 

/*  Wait  for  keypress  and  quit  */ 
getch  () ; 

} 


double  sum  (double  theta) 

I 

return  (sin  (theta)  +  cos  (theta)); 

void  plot  (int  angle,  double  (*fcn) (double  theta) ) 

I 

double  theta,  y; 

theta  =  (double)  angle  *  DEG2RAD;  /*  convert  to  radians  */ 

y  =  (*fcn)  (theta);  /*  derive  value  */ 

if  (px  !=  999)  /*  if  not  first  point  */ 

draw_line  (px,  py,  dx  (angle),  dy  (y) ) ; 
px  =  dx  (angle);  /*  save  current  point  */ 

py  =  dy  (y) ; 

)  /.  -  */ 


/*  white  ’/ 
./*  new  */ 


int  far  dxunits  (double  vx)  /*  device  x  units  for  vx  */ 

{ 

return  (int) (fabs) (xf  *  vx) ; 

(  /* . - - - - -  */ 

int  far  dyunits  (double  vy)  /*  device  y  units  for  vy  */ 

I 

return  (int) (fabs) (yf  *  vy) ; 

I  /* - - -  */ 

End  Listing  One 


Listing  Two 

Caption:  Add  this  to  your  copy  of  GRAFIX.H 


/*  From  July,  '89  */ 

/* . . */ 

void  far  setcoords  /*  set  virtual  coordinate  space  */ 

(double  left,  double  top,  double  right,  double  bottom); 


int  far  dx  (double  vx) ;  /*  convert  virtual  x  to  device  x  */ 

int  far  dy  (double  vy) ;  /*  convert  virtual  y  to  device  y  */ 


End  Listing  Three 


Listing  Four 

/*  LENDIST.C:  Produces  a  histogram  of  line  lengths  in  a  text  file  */ 
/*  Illustrates  integral  virtual  coords,  self-scaling  bar  chart  */ 


♦include  <stdio.h> 

♦include  <string.h> 

♦include  <conio.h> 

♦include  <stdiib.h> 

♦include  "grafix.h" 

♦define  MAXLEN  80  /*  max  length  of  a  line  */ 

♦define  MAXCAT  MAXLEN  /  5  /*  number  of  categories  *7 


void  mam  (int  argc,  char 
{ 

double  group  [MAXCAT]; 
int  category; 
double  maxcount  =  0; 
int  color  =  1; 

char  buf  [MAXLEN]; 

TILE  *  fp; 


’argv( ] ) 

/*  results  array  */ 

/*  grouping  by  length  (0-4,  5-9,  etc) 
/*  highest  count  for  any  category  */ 
/*  color  of  histogram  bar  */ 

/*  receiving  buffer  */ 

/*  text  file  pointer  */ 


*/ 


int  far  dxunits  (double  vx); 
int  far  dyunits  (double  vy) ; 


Listing  Three 


/*  device  x  units  for  vx  */ 

/*  device  y  units  for  vy  */ 

End  Listing  Two 


/*  check  command  line  for  a  filename  */ 
if  (argc  <  2)  ( 

puts  ("Usage:  LENDIST  <f ilename.ext>") ; 
exit  (EXIT_FAILURE) ; 


/*  clear  the  length  array  */ 

for  (category  =  0;  category  <  MAXCAT;  category++) 
group  [category]  =  0.0; 


/*  TRIGPLOT.C:  Plot  sine,  cosine,  and  their  sum  */ 

/*  X  axis  is  integral,  t  axis  is  floating-point  */ 

♦include  <math.h> 

♦include  <conio.h> 

♦include  "grafix.h" 

♦define  DEG2RAD  3.1415927  /  180.0  /*  degiees  to  radians  */ 

int  px  =  999,  py;  /*  previous  point  */ 

void  main  () 
f 

void  plot  (int  angle,  double  (*fcn) (double  theta)); 
double  sum  (double) ; 
int  angle; 

if  (init_video  (EGA))  { 

/*  Scale  the  axes  */ 
setcoords  (-360,  1.5,  360,  -1.5); 


/*  pass  thru  the  file  getting  lengths  of  lines  */ 
if  ((fp  =  fopen  (argv[lj,  "r"))  ==  NULL)  ( 
pnntf  ("Unable  to  open  ^s\n",  argv[l]); 
exit  (EXIT_FAILURE) ; 

}  else  ( 

while  (fgets  (buf,  MAXLEN,  fp))  [ 

category  =  strlen  (buf)  /  5;  /*  group  0-4,  5-9,  etc.  */ 

++group  [category];  /*  count  */ 

I 

fclose  (fp); 


/*  find  highest  count  of  any  group  */ 
for  (category  =  0;  category  <  MAXCAT;  category++) 
if  (group  [category]  >  maxcount) 
maxcount  =  group  [category]; 

/*  Normalize  groupings  to  100  */ 
for  (category  =  0;  category  <  MAXCAT;  category++) 
group  [category]  /=  (maxcount  /  100); 


/*  Draw  the  registration  lines  */ 
set_colorl  (2); 

hline  (dx ( - 360) ,  dy ( 0 ) ,  dxunits  (720)); 
draw_line  (dx(0),  dy(1.3),  dx(0),  dy (—1.3)); 
set_colorl  (1); 

hline  (dx ( - 360 ) ,  dy ( 1 ) ,  dxunits  (720)); 
hline  (dx (-360) ,  dy (-1) , dxunits  (720)); 


/ *  green  * / 
/ *  x  axis  */ 
/*  y  axis  */ 
/*  blue  */ 
/*  +1.0  */ 
/*  -1.0  */ 


/*  Plot  the  sine  curve  V 

set_colorl  (3);  /*  cyan  */ 

for  (angle  =  -360;  angle  <=  360;  angle++) 
plot  (angle,  sin) ; 


/*  Plot  the  cosine  curve  */ 
set_colorl  (5); 
px  =  999; 

for  (angle  =  -360;  angle  <=  360;  angle++) 
plot  (angle,  cos); 


/*  magenta  */ 

/*  new  curve  */ 


/*  enter  graphics  mode  */ 
if  (init_video  (EGA))  ( 

/*  scale  the  histogram  width  */ 

/*  leave  space  on  top  and  left  for  text  */ 
setcoords  (-22,  -2,  100,  23) ; 

/*  label  the  histogram  */ 

pnntf  ("Distribution  of  line  lengths  in  !s\n\n",  argv[l]); 
for  (category  =  0;  category  <  MAXCAT;  category++) 

printf  (”  Length  t2d-%2d:\n",  category*5,  (category*5) +4) ; 

/*  set  up  the  graph  area  */ 
draw_rect  (dx (—22) ,  dy  (-1),  dxunits  (122), 
dyunits (MAXCAT  +  2) ) ; 
set_colorl  (1);  /*  blue  */ 

for  (category  =  0;  category  <  100;  category+=10) 

draw_line  (dx (category) ,  dy (—0.5) ,  dx (category) ,  dy (MAXCAT) ); 

/*  draw  the  histogram  bars  */ 

for  (rat-pgnry  =  0:  category  <  MAXCAT;  category++)  [ 
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set_colorl  (color); 
if  (++color  ==  16)  color  =  1; 

fill_rect  (dx  (0),  dy  (category),  dxunits  (group  [category]). 


/*  hold  for  keypress,  then  quit  */ 
getch  () ; 
pc_textmode  ( )  ; 

)  else 

puts  ("Unable  to  enter  EGA  graphics"); 


End  listing  Four 


Listing  Five 

/*  RESIZE. C:  Effects  of  resizing  virtual  coords  to  fit  viewports  */ 

linclude  "grafix.h" 

((include  <conio.h> 

((include  <stdio.h> 

((define  BORDER  15 


void  main  ( ) 

( 

void  set_vp  (int,  int,  int,  int); 
if  (init_video  (EGA))  { 

/*  Set  colors  for  shading  */ 

set_ega_palreg  (1,  ega_blend  (RED3,  GRN1,  BLUO)); 
set_ega_palreg  (2,  ega_blend  (RED2,  GRN1,  BLUO) ) ; 
set_ega_palreg  (3,  ega_blend  (RED2,  GRNO,  BLUO)); 

l*  Draw  4-pointed  star  in  variously-sized  viewports  */ 
set_vp  (1,  1,  160,  120);  /*  square  */ 

set_vp  (200,  1,  120,  347);  /*  tall  and  skinny  */ 

set_vp  (360,  270,  238,  78);  /*  short  and  fat  V 

/*  Wait  for  keypress  and  quit  */ 
cetch ( ) ; 
pc_textmode () ; 

)  else 

puts  ("Unable  to  enter  EGA  graphics"); 

}  /. - - - - */ 

void  set_vp  (int  left,  int  top,  int  width,  int  height) 

( 

VP_HAN  vp; 

void  drawstar  (void) ; 

vp  =  vp_open  (left,  top,  width,  height); 
set_colorl  (BORDER) ; 
vp_outline  (vp) ; 

setcoords  (-120,  120,  120,  -120);  /*  constants  scale  to  vp  size  */ 

drawstar ( ) ; 
vp_close  (vp) ; 

1  /*  . - . - . V 

void  drawstar  (void) 


set  colorl  (BORDER) ;  /*  border  color  */ 

setf illborder  (BORDER); 

draw_rect  (dx ( —  30) ,  dy (—30) ,  dxunits  (60),  dyunits (60) ) ; 
set_colorl  (3);  /*  center  of  star  */ 

floodfill  (dx(0),  dy ( 0 ) ) ; 


set  colorl  (BORDER) ; 

draw_lme  (dx  (-30) ,  dy  (30),  dx(0),  dy  (100) ) ;  /*  top  ray  */ 

draw_line  (dx ( 0 ) ,  dy (100) ,  dx(30),  dy (30) ) ; 
draw_line  (dx ( 0 ) ,  dy(100),  dx < 0 ) ,  dy ( 3D ) ) ; 


draw_line  (dx ( -30 ) ,  dy(30),  dx(-100),  dy ( 0 ) ) ;  /*  left  ray  */ 

draw_line  (dx(-100),  dy(0),  dx ( - 30 ) ,  dy (—30) ) ; 
draw_line  (dx(-100),  dy ( 0 ) ,  dx ( - 30 ) ,  dy ( 0 ) ) ; 

draw_line  (dx(-30),  dy (—30) ,  dx(0),  dy (-100) ) ;  /*  bottom  ray  */ 

draw_line  (dx(0),  dy(-100),  dx ( 30 ) ,  dy ( -30 ) ) ; 
draw_line  (dx ( 0 ) ,  dy (-100 > ,  dx(0),  dy (—30) ) ; 

draw  line  (dx ( 30 ) ,  dy(-30),  dx(100),  dy ( 0 ) ) ;  /*  right  ray  */ 

draw_line  (dx(100),  dy ( 0 ) ,  dx(30),  dy (30) ) ; 
draw_line  (dx(100),  dy(0),  dx(30),  dy(0)); 


set_colorl  (1); 
floodfill  (dx (10) ,  dy ( 4 0 ) ) ; 
floodfill  (dx (-40) ,  dy (20) ) ; 
floodfill  (dx(10),  dy ( -40 ) ) ; 
floodfill  (dx (40) ,  dy (20) ) ; 


set_colorl  (2); 
f locdf ill  (dx (-10) ,  dy (40) ) ; 
floodfill  (dx(-40),  dy (—20) ) ; 
floodfill  (dx (-10) ,  dy (-40) ) ; 
floodfill  (dx(40),  dy(-20)); 


End  listings 
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OF  INTERES  T 


Microsoft  began  recently  shipping  its 
QuickPascal  Compiler,  a  Pascal  im¬ 
plementation  that  the  company  claims 
is  Turbo  Pascal  source-code  compat¬ 
ible.  The  compiler  is  built  around  Mi¬ 
crosoft’s  Quick-family  technology  (an 
integrated  compiler/ editor/ debugger  en¬ 
vironment)  while  further  supporting  ob¬ 
ject-oriented  extensions  as  defined  by 
Object  Pascal. 

QuickPascal  (QP)  provides  a  window- 
based  editor  that  supports  multiple 
views  into  a  source  file  or  simultane¬ 
ous  editing  of  multiple  files.  Windows 
can  be  resized  and  overlap  with  up  to 
nine  text-editing  windows  opened  at 
one  time.  QP  also  provides  mouse  sup¬ 
port.  The  QP  debugger  supports  single¬ 
stepping  into  and  around  procedures 
and  object  methods.  Microsoft  claims 
that  QP  is  the  first  Pascal  compiler  to 
support  integrated  debugging  of  as¬ 
sembler  routines  from  within  the  envi¬ 
ronment,  allowing  the  display  and  modi¬ 
fication  of  CPU  registers  and  flags.  Like 
other  Quick-family  compilers,  QP  of¬ 
fers  on-line  hypertext  reference  for  con¬ 
text-sensitive  help. 

QP  uses  four  non-standard  Pascal 
key  words:  the  object-oriented  exten¬ 
sions  of  Object,  Override,  and  Inher¬ 
ited  and  the  non-OPP  keyword  Cstring. 
(Note  that  the  four  keywords  new  to 
Turbo  Pascal  5.5  are  different.)  Except 
for  the  BGI,  QP  is  100  percent  compat¬ 
ible  with  Turbo  Pascal;  QP  does  have 
its  own  graphics  library  that  mimics  the 
BGI.  QP  requires  512K  of  memory  and 
DOS  2.1  or  higher  and  retails  for  $99- 

In  conjunction  with  Microsoft’s  QP 
announcement,  several  developers 
announced  third-party  support.  Turbo- 
Power  Software  says  its  Turbo  Pro¬ 
fessional  5.0  (a  library  of  general 
purpose  procedures  and  functions) 
and  B-Tree  Filer  5.0  (database-related 
procedures)  are  QP-compatible.  Like¬ 
wise,  Blaise  Computing  said  that 
its  Power  Tools  Plus  5.0  (general-pur¬ 
pose  library  of  interrupt  and  screen 
control  procedures),  Asynch  Plus  (com¬ 
munications  routines),  and  Power 
Screen  (screen  management  library)  also 
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supports  QP.  Reader  Service  No.  20. 
Microsoft  Corporation 
16011  NE  36th  Way 
Box  97017 

Redmond,  WA  98073-9717 
206-882-8080 

The  recently  announced  Intel  80486  is 
essentially  a  souped-up  80386,  deliv¬ 
ering  2X-5X  the  performance  at  equiva¬ 
lent  MHz.  To  support  on-chip  cache 
and  multiprocessing,  the  486  has  six 
new  instructions,  otherwise  the  486  is 
chiefly  a  tweak  of  the  386.  According  to 
Intel,  the  company  studied  all  available 
pure-386  software  and  optimized  the 
most  often-used  instructions  to  make 
them  one-cyclers  to  boost  performance. 
The  486  has  an  on-chip  80387  and  cache 
memory/control  with  8K  and  five-level 
pipelining.  Intel  has  working  silicon 
and  expects  production  quantities  by 
fall  of  this  year.  The  first  486  machines, 
which  should  be  available  by  winter, 
are  expected  to  be  file/database  ser¬ 
vers  and  other  high-performance  boxes. 

At  the  same  time,  Intel  announced  a 
C  compiler  for  the  486  (along  with  other 
software  development  tools),  a  386SX,  a 
k  w-power-consumption  cliip  for  laptops 
that  increases  battery  life  by  30  percent 
and  33-MHz  80386  availability.  Other 
announcements  included  a  32-bit  LAN 
coprocessor,  EISA  and  MCA  chip  sets, 
and  a  new  programmable  logic  device. 

Initial  pricing  for  the  80486  will  be 
$950,  which  is  about  $50  more  than  the 
cost  of  a  80386,  80387,  and  supporting 
chips.  Intel  hinted  about  a  price  drop 
in  the  386  but  didn’t  say  when.  The  486 
is  100  percent  binary  compatible  with 
all  previous  Intel  CPUs.  Reader  Service 
No.  23. 

Intel  Corporation 
3065  Bowers  Ave. 

Santa  Clara,  CA  95052-8065 

A  new  set  of  routines  designed  to  help 
in  the  development  of  user-interfaces 
has  been  released  by  Maxx  Data  Sys¬ 
tems  Inc.  The  routines,  called  Creative 
Interface  Tools,  allow  programmers  who 
use  any  of  Borland’s  Turbo  languages 
(C,  Pascal,  Basic,  and  Prolog)  to  create 
bit-mapped  screen  fonts,  bit-mapped 
icons,  graphic  mouse  cursors,  and  multi¬ 
level  menus.  Among  the  specific  tools 
are  a  Graphic  Symbol  Designer,  Menu 
System,  and  Keyboard  Processor  with 
mouse  support.  The  complete  package 
sells  for  $69-95.  Reader  Service  No.  22. 
Maxx  Data  Systems,  Inc. 

1126  S.  Cedar  Ridge,  Ste.  115 
Duncanville,  TX  75137 

Logitech  Inc.,  a  company  usually  as¬ 
sociated  with  mice  and  Modula-2,  has 
started  shipping  a  sophisticated  source- 


level  debugger  for  OS/2  environments 
named  the  MultiScope  Debugger.  The 
program  allows  you  to  debug  programs 
written  in  Microsoft  C,  Pascal,  MASM, 
Logitech  Modula-2,  and  IBM  C/2,  Pas¬ 
cal/2,  and  Macro  Assembler/2.  You  can 
use  MultiScope  under  either  Presenta¬ 
tion  Manager  or  OS/2  text  mode  and 
debug  at  run-time  (using  conditional 
or  unconditional  breakpoints  and  mem¬ 
ory  or  symbolic  watchdogs  to  monitor 
program  execution)  or  in  a  post-mortem 
mode  (to  examine  programs  after  a 
run-time  error). 

One  of  MultiScope’s  unique  features 
is  a  graphical  representation  of  a  pro¬ 
gram’s  data  structure.  This  lets  you  ex¬ 
plore  dynamically  allocated  data  struc¬ 
tures  and  their  internal  relationships. 
The  debugger  also  allows  you  to  look 
at  your  program  from  13  different  si¬ 
multaneous  views,  including  views  from 
the  perspective  of  the  source,  data,  mem¬ 
ory,  register,  threads,  breakpoints,  and 
so  on.  The  debugger  lets  you  evaluate 
expression,  execute  function  calls,  de¬ 
bug  child  processes  and  dynamic  link 
libraries,  and  perform  remote  debug¬ 
ging.  Although  DDJ  editors  have  not 
yet  had  the  opportunity  to  perform 
hands-on  testing  of  the  debugger,  the 
demonstration  provided  for  us  was  very 
impressive.  The  debugger  sells  for  $299. 
Reader  Service  No.  25. 

Logitech,  Inc. 

6505  Kaiser  Dr. 

Fremont,  CA  94555 

PHIGS  is  available  on  PCs  with  the 
release  of  Template  Graphics  Soft¬ 
ware’s  Figaro/386.  Figaro/386  is  a  ver¬ 
sion  of  its  Figaro  graphics  software  de¬ 
signed  for  80386-based  PCs.  The  Figaro/ 
386  offers  standard  PHIGS  (Program¬ 
mer’s  Hierarchical  Interactive  Graphics 
System)  features  such  as  hierarchical 
data  structures,  geometric  modeling,  and 
interactive  input.  The  Figaro  toolset 
gives  programmers  the  ability  to  ren¬ 
der  and  update  2-D  and  3-D  graphics 
objects  in  one  or  more  views,  deal  with 
trivial  and  incremental  updates  to  the 
display,  and  to  develop  programs  that 
use  advanced  input  functions  (full  event 
input,  programmable  triggers,  and  soft 
input  devices  like  screen  buttons  and 
sliders).  To  use  the  Figaro  system,  de¬ 
velopers  simply  relink  their  applications 
to  a  resident  Figaro  library.  Figaro/386 
sells  for  $1,595.  Reader  Service  No.  26. 
Template  Graphics  Software 
9685  Scranton  Rd. 

San  Diego,  CA  92121-9810 

Fortran  programmers  may  find  a  new 
publication,  The  Fortran  Journal,  of  par¬ 
ticular  interest.  According  to  editor  Walt 
Brainerd,  the  journal  contains  articles 
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about  people  and  organization  involved 
with  Fortran,  product  announcements, 
product  reviews,  book  reviews,  program¬ 
ming  hints  and  routines,  and  reports 
on  Fortran  88.  The  Fortran  Journal  is 
published  six  times  per  year  at  the  sub¬ 
scription  rate  of  $28/year  in  the  US  and 
$36  elsewhere.  Reader  Service  No.  27. 
Fortran  Users  Group 
P.O.  Box  4201 
Fullerton,  CA  92634 

The  Open  Software  Foundation  (OSF) 
has  released  to  its  membership  for  re¬ 
view  a  complete  set  of  specifications 
and  plans  for  its  OSF/1  offering,  which 
combines  the  OSF  operating  system  and 
OSF/Motif.  (See  “The  OSF  Windowing 
System”  by  Kee  Hinckley,  DDJ ,  March 
1989.)  The  operating  system  architecture 
provides  a  portable  and  interoperable 
applications  platform  that  supports  in¬ 
dustry  standards  and  specifications  such 
as  POSIX  and  the  X/Open  Portability 
Guide  3.  And  it  provides  a  smooth  up¬ 
grade  path,  allowing  for  the  addition 
of  extensions  with  minimal  disruption 
to  the  existing  kernel.  OSF  is  waiting 
for  member  feedback  on  the  specifica¬ 
tions  before  it  prepares  the  final  ver¬ 
sion,  which  will  be  released  in  four 
stages:  The  Vendor  Kit,  the  Application 
Kit,  the  University  Platform,  and  the 
Commercial  Platform.  The  OSF  is  an 
international,  not-for-profit  organization 
dedicated  to  the  development  and  de¬ 
livery  of  an  open,  portable  software 
environment.  Reader  Service  No.  32. 
Open  Software  Foundation 
1 1  Cambridge  Center 
Cambridge,  MA  02142 

XVT,  a  cross-platform  software  devel¬ 
opment  tool  that  allows  programmers 
to  develop  and  maintain  one  set  of 
application  source  code,  now  supports 
Presentation  Manager  in  addition  to  Win¬ 
dows  and  the  Macintosh.  (For  an  in- 
depth  description  of  XVT,  see  “The 
Portability  Dream”  by  Margaret  Johnson, 
DDJ  March,  1989.)  Also,  XVT  (which 
is  short  for  “Extensible  Virtual  Toolkit,”) 
is  now  available  from  Graphic  Soft¬ 
ware  Systems.  The  tool  creates  100 
percent  portability  between  the  three 
graphical  user-interface  environments. 
Additionally,  the  XVT  enhances  pro¬ 
grammer  productivity  because  of  the 
increased  capacity  for  native  toolkit  calls 
and  programming  details.  We  recently 
spent  some  more  hands-on  time  with 
XVT  and  continue  to  be  impressed  with 
this  package.  The  XVT  version  for  Win¬ 
dows  supports  the  Microsoft  Windows/ 
286  and  Windows/386  software  devel¬ 
opment  kits  (SDKs),  including  Micro¬ 
soft  C.  XVT  for  Presentation  Manager 
supports  Microsoft  C  and  the  Microsoft 


or  IBM  OS/2  1.1  Toolkits.  XVT  for  Macin¬ 
tosh  supports  Think  C  or  the  MPW 
compiler.  A  Unix-based  X  Window  Sys¬ 
tem  version  is  planned  for  later  this 
year.  Each  package  costs  $595.  Reader 
Service  No.  31. 

Graphic  Software  Systems 
9590  SW  Gemini  Drive 
Beaverton,  OR  97005 
503-641-2200 

Alcyon  Corporation  has  announced 
that  its  new  software  development  utili¬ 
ties  package,  the  Regulus-386  Tool-Kit, 
fully  automates  the  management  of 
80386-based  real-time  applications  soft¬ 
ware  development.  The  Regulus-386 
Tool-Kit  supposedly  brings  most  Unix 
System  V  utilities  to  Alcyon’s  Regulus- 


386  operating  system,  a  real-time  Unix- 
compatible  operating  system  for  the 
80386.  This  means  PC-based  real-time 
application  developers  can  take  advan¬ 
tage  of  the  standard  Unix  tools  to  speed 
up  the  program  development  cycle.  The 
Tool-Kit  provides  such  utilities  as:  source 
code  control  system ,  make ,  vi  screen 
editor.  Bourne  shell,  C  shell,  and  more. 
The  cost  is  $800.  Perpetual  upgrades 
are  available  at  additional  cost.  Reader 
Service  No.  30. 

Alcyon  Corporation 
6888  Nancy  Ridge  Drive 
San  Diego,  CA  92121 
800-748-5858 

619-587-9968  (from  inside  California) 

DDJ 
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LETTER  S 


(continued  from  page  12) 
responsible  for  the  precise  sculpting 
of  their  product.  However,  I  don’t  agree 
that  education  is  not  the  solution  to  the 
pirating  problem. 

Mr.  Gillette’s  idea  of  embedding  a 
serial  number  in  the  bios  of  each  ma¬ 
chine  is  a  good  one  and  one  I’ve  won¬ 
dered  about  myself.  Why  don’t  manu¬ 
facturers  do  that?  The  problem  is  that 
even  if  a  serial  number  was  available, 
any  software  protection  scheme  would 
add  another  layer  of  complexity  to  the 
development  and  support  of  a  soft¬ 
ware  product.  For  example,  how  do 
you  handle  hardware  upgrades  where 
the  serial  number  would  have  changed? 

This  complexity  ‘buys”  the  developer 
very  little  protection  against  even  a  mod¬ 
erately  experienced  computer  user.  All 
that  needs  to  be  done  to  subvert  the 
protection  is  copy  the  original  disks 
before  installing  on  the  target  machine. 

As  Nancy  Reagan  discovered  in  her 
work  against  drug  abuse,  jailing  the 
distributor  isn’t  completely  effective.  As 
with  drugs,  the  way  to  stop  software 
pirating  is  to  make  it  unpopular  to  do. 
Maybe  we  can  license  their  slogan,  “Soft¬ 
ware  pirating.  .  .  .  Just  say  no!” 

Tim  Deardeuff 

Provo,  Utah 
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The  Serial  *  Scheme 

Dear  DDf 

I  want  to  pass  along  a  couple  of 
thoughts  I  had  regarding  your  March 
[Paradigms]  column.  Writers  should  in¬ 
deed  be  held  to  high  standards.  All  too 
much  writing  in  the  computer  field  is 
turgid,  hackneyed,  rambling  —  you 
name  it!  I  too  am  a  writer,  and  always 
strive  (with  varying  degrees  of  success) 
to  produce  work  that  is  clear,  concise, 
and  literate.  Knowing  how  difficult  the 
task  can  be,  I  am  doubly  appreciative 
when  I  find  those  qualities  in  the  work 
of  others. 

Copyright  protection  for  software 
does  remain  a  problem,  but  the  serial 
number  technique  that  you  mention 
has  at  least  two  serious  flaws.  For  one, 
it  makes  no  provision  for  people  or 
businesses  that  upgrade  their  comput¬ 
ers  while  keeping  old  software.  Nor 
would  it  be  acceptable  for  people  like 
myself,  who  use  different  computers 
in  different  locations.  Each  software 
package  that  I  purchase  is  installed  on 
all  of  my  computers;  the  manuals  are 
schlepped  back  and  forth  as  needed. 
No  one  but  me  ever  uses  any  of  these 
machines.  Surely  such  an  arrangement 
is  within  the  spirit,  if  not  the  letter,  of 
software  licensing  agreements.  The  se¬ 


rial  number  scheme,  by  tying  a  pro¬ 
gram  to  a  single  computer,  would  pre¬ 
vent  me  from  using  my  software  in  this 
fashion. 

Software  copyrights  need  to  be  pro¬ 
tected,  but  serial  number  keying  is  not 
the  way. 

Peter  G.  Aitken 
Durham,  North  Carolina 


More  on  RLE 

Dear  DDJ, 

Let’s  not  overstate  the  usefulness  of  run 
length  encoding.  Robert  Zigon  is  cor¬ 
rect  in  pointing  out  (“Run  Length  En¬ 
coding,”  February  1989)  that  RLE  is 
simple,  fast,  and  elegant,  and  I  have 
no  doubt  it  works  magic  on  Mr.  Zigon’s 
frame-grabber  data,  a  type  of  data  for 
which  it  is  ideally  suited.  But  RLE  will 
not  work  on  English  text,  and  its  use¬ 
fulness  in  compacting  object  files  is 
next  to  nil. 

Don’t  get  me  wrong;  the  article  itself 
was  good.  The  author  did  give  the  im¬ 
pression,  however,  that  RLE  will  com¬ 
press  a  wide  variety  of  file  types  by 
20  percent  or  more.  In  fact,  it  will 
make  most  files  grow,  and  any  file 
(such  as  an  .EXE  file)  that  contains  all, 
or  nearly  all,  256  ASCII  byte  values 
will  need  switchout  codes  and  excep¬ 
tion-handling  to  account  for  switch¬ 
out  codes,  over  and  above  Zigon’s  sim¬ 
ple  routine. 

Kas  Thomas 

Stamford,  Conn. 

Dear  DDJ , 

The  article  by  Robert  Zigon,  (February 
1989,  page  126),  caught  my  eye,  but 
unfortunately  I  cannot  use  it.  The  prob¬ 
lem  lies  in  the  fact  that  the  English 
language  has  very  few  “double”  letters 
in  the  words.  1  went  through  some 
200,000  bytes  of  English  prose  to  find 
out  how  many  characters  are  the  same 
right  after  each  other.  The  average  is 
about  2  percent.  Some  other  languages 
like  Dutch  or  Finnish  have  a  much 
higher  value,  e.g.  Dutch  about  5  per¬ 
cent,  and  Finnish  also  about  5  percent. 
In  any  event,  even  for  those  languages 
the  output  file  would  about  double, 
rather  than  be  compressed. 

Paul  A.  Elias 

Fountain  Hills,  Arizona 

Eds:  RLE  is  applicable  chiefly  to  the 
compression  of  data  that  has  a  high 
degree  of  redundancy.  RLE  works  great, 
for  instance,  with  graphics  data  where 
there  are  many  consecutive  bytes,  all 
having  the  same  value. 

DDJ 
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The  Information  Revolution  and  the  Morning  News 

Years  ago,  when  I  worked  for  a  company  whose  name  need  not  be  mentioned,  we  had  a  visit 
from  a  man  with  a  thick  accent.  He  would  be  returning  to  his  country  shortly,  he  said,  and 
wished  us  to  sell  him  a  certain  item  of  computer  equipment  to  take  back  with  him.  There 
were  some  legal  problems,  yes,  involved  in  taking  such  equipment  from  our  country  to  his,  but 
he  told  us  not  to  worry  about  that.  And  the  less  we  said  about  the  transaction,  he  let  us  understand, 
the  better  it  would  be  for  all  concerned.  I  believe  he  paid  in  cash. 

Yes,  I’m  confessing  to  taking  part  in  a  smuggling  operation,  but  before  you  turn  me  in,  let  me 
plead  the  extenuating  circumstances.  The  computer  was  an  Exidy  Sorcerer,  the  country  to  which 
the  computer  was  going  was  Brazil,  the  law  being  violated  was  Brazil’s,  and  the  smuggler  only 
wanted  to  use  the  computer  for  bookkeeping  in  his  small  business. 

Brazil’s  protectionism  laws,  intended  to  stimulate  the  growth  of  an  indigenous  computer  industry, 
have  rather  held  up  the  computerization  of  the  Brazilian  economy,  according  to  Louis  Rossetto  in 
his  non-editorial  in  the  April  Language  Technology.  Smuggling  and  the  black  market  are  becoming 
necessary  evils  in  the  face  of  $2,000  Rio  de  Janeiro  street  prices  for  XT  clones.  Rossetto  cites 
evidence  that  the  protectionism  is  crumbling,  including  Brazil’s  decision  to  consider  an  Olivetti 
subsidiary  “national.”  The  damage  it  has  done,  of  course,  won’t  go  away  quickly. 

But  Brazil’s  travail  doesn’t  amount  to  a  hill  of  coffee  beans  in  the  crazy  world  of  Pacific  rim 
economics  as  described  by  James  Fallows  in  the  May  Atlantic. 

Fallow  describes  a  condition,  one  of  whose  syndromes  is  protectionism  and  one  symptom  is  the 
47th  Street  Photo  paradox:  if  47th  Street  Photo  in  Manhattan  could  export  to  Japan  the  Japanese- 
made  goods  it  sells  to  New  Yorkers,  it  could  make  a  fortune.  Charges  of  protectionism  fly  in  both 
directions,  usually  couched  in  the  polite  terms  that  characterize  U.S.-Japan  relations.  But  the  facts 
are  pretty  one-sided.  “How  protectionistic  can  a  country  with  a  $10-billion  monthly  trade  deficit 
really  be?”  Fallows  asks.  Japan,  on  the  other  hand,  is  keeping  its  people  relatively  poor  to  compete 
economically  in  the  world  market.  Fallows  says  that  Japan’s  policies  are  ultimately  ruinous  for 
everyone,  including  Japan,  but  sees  little  evidence  that  Japan  will  change  its  ways  soon. 

As  I  was  writing  this  column,  I  heard  on  National  Public  Radio  of  the  suicide  of  one  Japanese 
bureaucrat  involved  in  the  corruption  that  is  bringing  down  the  government.  It’s  dramatic  news, 
but  even  the  fall  of  the  government  is  not  expected  to  affect  Japan’s  economic  policy.  Another  story 
I  heard  on  NPR  while  writing  this  column  concerned  the  possibility  of  the  Supreme  Court’s 
reconsidering  Roe  vs.  Wade,  the  decision  that  legalized  abortion.  Whatever  your  feelings  about  the 
legality  of  abortion,  you  should  consider  the  implications  of  a  side  issue  that  is  also  being  brought 
before  the  Court,  an  issue  that  touches  on  the  relationship  between  information  and  power.  The 
issue  is  whether  or  not  restrictions  should  be  placed  on  access  to  abortion  information. 

Everyone  reading  this  magazine  is  intimately  involved  in  a  technological  revolution,  one  of  the 
most  radical  effects  of  which  will  be  a  redistribution  of  access  to  information  of  all  sorts,  combined 
with  an  increased  dependence  on  information  in  society.  The  fact  that  purchasing  power  now  rests 
on  the  ability  to  provide  an  acceptable  credit  card  number  and  expiration  date  is  just  one  example 
of  the  “informatizing”  of  society.  Those  of  us  who  are  in  the  vanguard  of  the  revolution  should  be 
especially  sensitive  to  attempts  to  redefine  access  to  information.  If  knowledge  is  power,  then 
access  to  information  is  enfranchisement. 

If  the  Supreme  Court  should  decide  to  overturn  Roe  vs.  Wade  the  decision  may  be  made  out  of 
strong  moral  convictions  regarding  abortion.  But  it  is  also  true  that  the  most  effective  way  to  stifle 
dissent  is  to  keep  the  dissenters  ignorant.  If  access  to  information  is  enfranchisement,  then 
restriction  of  access  to  information  is  tyranny. 


On  the  lighter  side  of  tyranny,  in  the  May  Lotus  magazine,  Lindsy  van  Gelder  examines 
groupware,  a  software  category  some  detractors  have  labelled  fascist.  “Groupware,”  she  quotes 
Institute  for  the  Future  fellow  Paul  Saffo  as  saying,  is  software  that  “can  be  used  effectively  only 
by  two  or  more  people."  Is  it  a  real  opportunity  for  developers  or  just  a  buzzword?  Van  Gelder  paints 
an  unpromising  picture  of  an  ill-researched  concept  ill  suited  to  the  way  people  work  today  —  but 
that  picture  would  also  have  fit  the  personal  computer  a  decade  ago.  One  working  model  of 
groupware  is  the  CASE  model,  without  which  some  large  software  projects  would  never  get  done. 


Shopping  for  exotic  fauna  for  my  garden  of  typos,  I  recently  unearthed  “terrabyte  WORMs” 
in  a  computer  magazine  editorial.  It  should  be  “terrabite  worms,”  of  course,  an  allusion  to  the 
appetites  of  annelids. 

'J/M t 

Michael  Swaine 
editor-at-large 
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One  of  DDJ  s  more  unique  and  endearing  qualities  is  the  affinity  that  exists  between  the 
magazine’s  readers,  writers,  and  editors.  This  kindred  spirit  is  one  of  the  things  that  makes 
DDJ  special.  But  the  downside  of  a  relationship  like  this  is  that  we’re  all  touched  much 
more  deeply  by  any  loss.  Such  is  the  case  with  the  death  of  Kent  Porter,  our  senior  editor  who 
passed  away  the  first  week  in  June.  His  unexpected  death  leaves  all  of  us  —  those  who  were 
used  to  seeing  him  every  day  and  those  of  you  who  had  grown  used  to  hearing  from  him  every 
month  —  with  an  empty  feeling. 

Kent  was  a  special  person  whose  association  with  DDJ  goes  back  many  years  —  first  as  a 
reader,  then  as  a  contributor,  and  finally  as  a  staff  editor.  Most  recently,  Kent  wrote  about 
graphics  programming,  an  area  that  was  a  particular  interest  of  his.  Before  that,  he  authored  the 
“Structured  Programming”  column  where  he  became  known  as  an  advocate  for  Modula-2, 
Pascal,  and  clear  thinking  in  general.  And,  over  the  years,  he  wrote  dozens  of  articles  for  DDJ 
and  just  about  every  technical  magazine  in  the  programming  field.  Add  his  more  than  20  books 
(most  of  them  on  various  aspects  of  programming,  although  his  first  book  was  entitled  Building 
Model  Ships  From  Scratch)  and  you  begin  to  see  just  how  prolific  and  disciplined  he  was.  To  a 
great  extent,  Kent’s  technical  prowess,  sense  of  humor,  and  clarity  of  expression  embodied  the 
notion  of  what  DDJ  is  all  about. 

Programming  was  just  one  of  Kent’s  many  interests.  He  could  speak  six  or  seven  languages 
(nope,  not  programming  languages,  he  started  learning  Italian  shortly  before  his  death)  and, 
believe  it  or  not,  he  was  an  accomplished  “needlepointer”  who  made  up  his  own  designs.  As 
lucky  as  we  were  to  know  and  work  with  Kent,  he  felt  he  was  lucky  too.  He  recently  told  former 
DDJ  editor  Ron  Copeland  that  he  was  doing  what  he  had  always  dreamed  of  when  he  was 
growing  up  —  writing  books  and  magazine  articles.  He  added  that  working  at  DDJ  was  the 
most  satisfying  job  he’d  ever  held.  While  that  certainly  makes  us  feel  better  now,  it’s  more 
gratifying  to  know  that  Kent  was  happy  and  satisfied  with  what  he  was  doing. 

Although  his  column  will  end  with  this  month’s  issue,  Kent  had  a  couple  of  articles  we  hadn’t 
gotten  around  to  publishing,  and  those  will  see  the  light  of  day  over  the  coming  months.  He’d 
also  just  finished  updating  his  excellent  book  on  Stretching  Turbo  Pascal ,  and  I  hope  you’ll  be 
seeing  it  in  the  bookstores  before  long. 

As  a  lasting  memorial  to  our  friend,  we’re  in  the  process  of  setting  up  a  scholarship  fund  in 
Kent’s  name.  It  will  be  an  annual  award  to  a  deserving  computer  science  student,  and  I’ll  be 
providing  more  details  on  it  in  a  future  issue. 


In  last  month’s  editorial,  I  mentioned  that  we’re  providing  listings  via  an  on-line  service  built 
by  David  Betz  and  Bill  Garrison.  The  response  was  great,  with  several  hundred  of  you  using 
the  service  to  download  files  throughout  the  month  and  we're  continuing  to  expand  the 
available  material.  Again,  the  number  is  603-882-1599.  Dial  it  up  and  send  us  some  e-mail  with 
your  comments. 


Those  Macintosh  aficionados  among  us,  like  John  Kirkpatrick  of  Houston  and  Grant  Schampel 
of  St.  Paul,  have  commented  that  it’s  been  a  couple  of  months  or  so  since  we  ran  a  Mac  article. 
The  reason  for  the  dearth  is  that  we've  been  stockpiling  Mac  articles  for  another  special  issue 
named  Dr.  Dobb’s  Macintosh  Journal ,  which  is  due  out  next  month.  The  first  thing  you’ll  notice 
about  the  issue  is  that  it  is  packed  with  code.  One  article,  in  fact,  has  over  1800  lines  of  code 
while  another  has  about  1000  lines.  The  articles  range  from  discussions  of  device  drivers  and 
memory  management  to  object-oriented  and  32-bit  color  programming.  In  the  process  of  putting 
the  special  issue  together,  we’ve  also  been  able  to  assemble  a  good  selection  of  additional 
code-intensive  Mac  articles  that  we’ll  be  running  in  the  regular  DDJ  just  about  every  month. 


Jonathan  Erickson 
editor-in-chief 
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More  on  Superlinearity  — 
and  More 

Dear  DDJ, 

I  am  writing  in  reference  to  Michael 
Swaine’s  column  “Programming  Para¬ 
digms,”  in  the  April  1989  issue  of  Dr. 
Dobb's Journal.  I  have  always  enjoyed 
reading  Swaine’s  columns  and  I  am 
pleased  to  be  writing  to  him. 

I  wanted  to  comment  on  his  discus¬ 
sion  of  superlinearity.  I  share  his  skep¬ 
ticism  about  the  results  of  Rao  and 
Kumar  about  superlinear  speedups  with 
parallel  processing.  I  feel  that  their  ex¬ 
ample  (in  fact  any  example)  of  super¬ 
linearity  falls  into  Swaine’s  first  case, 
that  is,  of  a  better  algorithm  being  used 
in  the  parallel  case. 

Nine  processors,  each  running  a 
depth-first  search  on  a  part  of  the  search 
tree,  are  not  together  doing  a  depth- 
first  search.  They  are  running  a  similar 
(but  different)  algorithm  that  samples 
each  part  of  the  tree  for  solutions. 

Suppose  we  wanted  to  run  exactly 
the  same  algorithm  on  a  sequential  pro¬ 
cessor.  First  we  implement  a  simple 
light-weight  process  (or  thread)  system 
with  nine  threads.  Each  thread  simu¬ 
lates  one  of  the  nine  processors  run¬ 
ning  in  parallel  in  the  parallel  solution. 
This  method  will  exactly  track  the  par¬ 
allel  algorithm  at  one-ninth  the  speed 
(plus  a  small  constant  factor  for  the 
multiprogramming).  The  constant  fac¬ 
tor  for  the  thread  switching  only  re¬ 
quires  handling  the  timer  interrupt  and 
swapping  register. 

The  exact  value  of  the  thread-switch¬ 
ing  overhead  is  not  important  anyway 
because  we  know  it  will  be  a  constant 
factor  and  we  can  make  it  arbitrarily 
small  by  increasing  the  time  slice  value 
and  considering  larger  trees.  This 
method  will  approach  exact  linearity 
in  the  limit  and  it  is  only  the  large 
problems  that  one  would  benefit  from 
using  parallelism  any  way. 

There  are  other  ways  to  look  at  the 


same  idea.  We  could  dispense  with 
actual  multiprogramming  and  instead 
just  sequentialize  the  parallel  algorithm. 
That  is,  have  the  algorithm  keep  nine 
stacks  and  service  them  in  rotation. 

The  reason  that  their  solution  seems 
to  produce  superlinearity  is  (as  Swaine 
mentioned)  that  there  are  several  solu¬ 
tions  and  the  depth-first  search  method 
always  goes  left  to  right  and  will  lose 
out  to  the  parallel  algorithm  if  the  solu¬ 
tions  tend  to  cluster  elsewhere.  An¬ 
other  solution  would  be  to  modify  the 
depth-first  algorithm  to  randomly  de¬ 
cide  to  explore  either  the  left  or  right 
subtree  first  and  stack  the  other  sub¬ 
tree.  This  method  would  visit  a  random 
leaf  node  first  and  then  spread  out  on 
both  sides  of  that  node  (randomly  spread¬ 
ing  left  or  right  at  each  step)  until  it 
reached  both  sides  of  the  tree. 

If  it  turned  out  that  it  would  be  better 
to  visit  leaf  nodes  randomly  (and  not 
spread  out  from  a  randomly  selected 
left  node)  you  could  pick  randomly 
from  the  stack  rather  than  always  tak¬ 
ing  the  most  recent  inserted  element 
(which  would  make  it  a  list,  I  guess). 

As  long  as  I  am  writing,  I  thought  I 
might  comment  on  Swaine’s  ideas  for 
a  first  course  in  computer  science.  1 
am  interested  in  this  because  I  am  an 
associate  professor  in  the  computer  sci¬ 
ence  department  at  the  University  of 
New  Mexico  (although  I  am  currently 
on  paternity  leave). 

First,  I  might  mention  that  we  just 
added  a  course  called  “Programming 
Paradigms”  although  at  the  senior  level. 
The  thing  I  liked  best  about  Swaine’s 
proposal  is  the  emphasis  on  reading 
programs  rather  than  writing  them.  If 
the  analogies  to  reading  and  writing 
natural  language  or  learning  Morse  code 
hold,  then  it  would  be  much  easier  to 
learn  to  read  a  program  than  to  learn 
to  write  one.  As  a  result  you  could 
cover  much  more  interesting  and  com¬ 
plex  programs  in  the  first  course.  In 
addition,  learning  program  reading 
would  help  later  in  doing  program  main¬ 
tenance,  which  we  know  is  a  major 
activity  of  working  programmers. 

A  related  proposal  I  have  been  hear¬ 
ing  for  a  while  is  that  the  first  course 
in  computer  science  should  (like  the 
first  course  in  other  sciences)  survey 
all  the  important  parts  of  the  field  rather 
than  just  teach  programming.  I  would 
tend  to  merge  Swaine’s  proposal  into 
that  one  since  computer  science  is  much 
more  than  programming  and  even  the 
more  general  area  of  programming  para¬ 
digms  is  just  a  part  of  the  whole  of 
computer  science. 

I  do  not  see  changes  coming  soon, 


however.  I  have  been  trying  for  several 
years  to  get  our  department  to  teach 
Scheme  in  the  first  programming  class. 
(Scheme,  rather  than  Lisp,  so  we  can 
use  Abelson  and  Sussman’s  book.)  Then 
the  students  could  be  writing  interest¬ 
ing  programs  (like  Eliza  or  symbolic 
differentiation)  rather  than  worrying 
about  the  problems  of  non-conditional 
ANDs  in  Pascal. 

Let  me  close  by  saying  again  how 
much  I  enjoy  Michael  Swaine’s  col¬ 
umns.  Keep  them  coming. 

Charles  Crowley 
Albuquerque,  New  Mexico 


Reading,  Writing, 
and  New  Technologies 

Dear  DDJ, 

Contrary  to  what  editors  of  PC  rags 
think,  reading  skill  in  many  languages 
and  (I  groan  at  the  use  of  this  too  hip 
word)  paradigms  is  not  the  most  im¬ 
portant  skill  that  one  can  and  should 
learn  from  one’s  first  CS  course.  True, 
reading  is  a  useful  skill  and  one  should 
learn  it  but  it  is  hardly  the  most  impor¬ 
tant  thing  to  learn  about  computers 
and  computer  languages.  I  think  that 
if  you  have  to  rank  the  items  that  you 
would  most  like  your  students  to  walk 
away  with  from  a  programming  class 
they  would  be: 

1.  Learn  to  type  —  this  skill  can  be 
used  for  many  wonderful  things  and 
can  even  be  used  in  areas  of  life  having 
nothing  to  do  with  computers. 

2.  Learn  to  read  obtuse  dreck  out  of 
manuals  —  this  skill  helps  one  not  only 
over  and  over  in  CS,  but  also  in  the 
home  when  attempting  to  assemble  a 
Japanese  bicycle,  or  Sears  parapherna¬ 
lia. 

3.  Learn  to  pay  attention  to  detail  — this 
skill  is  co-titled  “get  the  semi-colons  in 
the  right  place”  but  again  it  transfers 
to  painting;  writing  specs;  designing 
automobiles;  managing  people,  money, 
or  time;  playing  piano  or  video  games. 
If  you  want  to  do  any  of  these  right  you 
must  be  concerned  with  detail. 

4.  Leam  responsibility  —  the  computer 
does  exactly  what  you  tell  it,  no  more, 
no  less.  If  you  want  it  to  do  the  right 
thing,  you  alone  are  responsible  for  the 
product  of  your  code. 

You  can  get  all  of  this  by  teaching 
any  computer  language,  however,  the 
emphasis  is  on  writing,  not  on  reading. 
When  reading  you  can  skip  over  de¬ 
tails,  when  writing  you  can’t.  Reading 
is  lazy  in  comparison  to  writing. 

By  the  way,  are  high-level  languages 
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(continued  from  page  10) 
like  Fortran  a  different  paradigm  from 
assembly  code?  Is  Quicksort  a  different 
sorting  paradigm  from,  say,  bubble  sort? 
Is  OOP  with  multiple  inheritance  a  dif¬ 
ferent  paradigm  from  the  traditional 
single  inheritance  OOP?  Were  big  tail 
fins  on  cars  the  new  paradigm  in  car 
design  or  just  style?  Is  the  word  para¬ 
digm  coming  to  mean  anything  that  is 
a  little  different  from  something  else 
but  you  want  to  emphasize  how  hard 
it  was  for  you  to  learn  the  new  thing 
by  claiming  that  the  new  thing  is  revo¬ 
lutionary  or  radical?  This  hardly  matches 
Khuns’  [sic]  use  (yes,  I  know  he  used 
the  word  in  187  different  ways  in  the 
203  uses  in  his  book)  where  he  refers 
to  one  common  mindset  (Newtonian 
mechanics)  that  had  to  be  replaced  in 
light  of  new  knowledge  (relativity).  Note 
the  words  “common"  and  “replaced.” 
OOP  is  not  replacing  assembler  and 
neither  is  parallel  computing  replacing 
sequential  computing.  They  have  all 
been  around  for  years  and  are  different 
fields  of  endeavor,  they  are  not  alter¬ 
nate  views  of  one  reality.  The  way 
Swaine  uses  the  word  paradigm  is  cute, 
adds  zest  to  his  articles  (which  I  enjoy 
quite  a  bit,  don’t  misunderstand  me), 
and  sparks  controversy  because  it  is 
fundamentally  wrong,  but  somewhat 
defensible  due  to  the  vagueness  of  the 
word  to  begin  with.  It’s  a  good  way  to 
spark  reader  feedback  but  is  on  the 
same  level  as  using  cheesecake  photos 
to  spark  sales. 

If  I  may  render  the  opinion  of  an  old 
computer  hack,  message  passing,  event- 
driven  windows  systems  are  new  and 
an  exciting  territory  to  someone  from 
the  Hi-Level  App  school  but  is  just  busi¬ 
ness  as  usual  to  us  ASM  systems  hacks 
who  have  been  writing  interrupt  driven 
(message  from  the  data  unit  #4  just 
came  in  at  a  higher  priority  than  the 
disk,  right  when  we  were  in  the  middle 
of  ...  )  device  handlers  since  the  early 
50s.  We  just  wanted  to  share  the  joy  of 
systems  hacking  to  all  the  Apps  writers. 
Yes,  it  is  graphical  and  sexy  and  new 
and  different  from  what  you  are  used 
to,  but  revolutionary?  Was  structured 
programming  and  indenting  revolution¬ 
ary?  Yes,  people  wrote  spaghetti  code 
with  gotos  but  others  of  us  felt  is  was 
unreadable  and  developed  styles  to  limit 
the  code  flow  so  we  could  understand 
what  was  going  on.  When  those  be¬ 
came  standardized  and  were  given 
names  in  high-level  languages  was  that 
the  revolution?  And  now  OOPs  are  the 
great  new  snake  oil  of  the  90s.  Boy, 
when  you  get  objects  you  will  really 
be  set  free!  No  more  hard  code  to  write. 

12 


You  want  to  print  a  floating  point  num¬ 
ber  you  just  tell  it  DISPLAY  YOURSELF 
and  it  knows  what  to  do.  The  fact  that 
Basic  has  kept  track  of  strings  and  inte¬ 
gers  and  floats  and  printed  them  ap¬ 
propriately  for  years  is  not  germain. 
The  fact  that  for  years  people  have 
kept  fields  in  records  to  identify  what 
type  of  record  it  is  so  that  they  can 
CASE  to  the  right  code  is  beside  the 
issue.  In  OOPs  it  is  all  automatic.  All 
your  CASES  are  hidden  from  view,  the 
code  writes  itself!  Well,  actually  you 
do  have  to  write  all  the  separate  cases, 
but  instead  of  keeping  them  in  one  file 
of  subroutines  you  can  keep  them  in 
separate  little  files  with  the  object  classes! 
And  you  can  inherit  from  one  class  to 
another,  that  was  when  it  is  appropri¬ 
ate  to  reuse  it  without  even  rewriting 
it!  Radical!  Of  course,  if  the  record  is 
really  different  you  have  to  write  some¬ 
thing  new,  but  hey,  you  can  use  any 
of  the  other  subroutines  that  you’ve 
already  written  to  make  it  really  easy! 
Of  course,  if  there  are  bugs  you  still 
have  to  go  find  them. 

Fortunately,  since  you  are  reusing  all 
these  wonderful  already  debugged  meth¬ 
ods,  the  problem  is  always  in  the  code 
you’ve  just  written,  unless,  of  course, 
you  made  a  mistake  in  one  of  the  old 
methods  that  you  just  never  exercised 
until  just  now.  Also,  if  you  design  it 
wrong  from  the  start,  you  may  not  know 
it  until  you  finish  because  you  start  at 
the  bottom  with  simple  classes  and  build 
your  way  up  (as  opposed  to  top  down) 
and  you  may  have  to  rebuild  the  whole 
thing  anyway,  but  we’ll  fix  that  in  our 
next  paradigm  shift,  eh?  In  short,  my 
impression  of  the  great  progress  in  com¬ 
puter  software  in  the  last  decade  is  that 
we  have  discovered  some  important 
things: 

1.  There  is  a  lot  of  money  to  be  made 
in  software.  You  make  more  money 
selling  Barbie’s  clothes  than  you  make 
selling  Barbie  dolls. 

2.  Software  is  a  fashion  market.  You 
must  convince  the  user  that  if  he  doesn’t 
have  fins  on  his  machine  he  is  just  not 
where  it  is  at.  His  old  software  just  isn’t 
as  cool  as  the  new  stuff. 

3.  Your  look  must  be  coordinated.  That 
is,  the  jacket  alone  won’t  do  it.  You 
have  to  have  the  Object-Oriented  Com¬ 
piler,  and  the  OODebug,  and  the  OOEdi- 
tor,  and  the  OOFileSystem. 

4.  OO  la  la,  look  at  the  money  just 
waiting  to  be  made. 

5.  Mostly,  we  need  lots  of  hype  in  the 
press,  preferably  of  the  type  that  tells 
people  the  new  stuff  is  magic  —  that 
is,  cures  everything,  is  new,  revolution¬ 


ary,  very  technical,  and  hard  to  under¬ 
stand.  You’ll  have  to  change  your  whole 
outlook  cause  this  is  one  of  those  mind- 
bending  paradigm  shifts. 

Marlin  Eller 
Seattle,  Wash. 


CRC  Algorithms 

Dear  DDJ 

In  A1  Stevens’  column  “C  Programming” 
in  the  April  1989  issue  of  the  magazine, 
while  discussing  the  compute_crc  func¬ 
tion,  he  stated  that  he  did  not  know 
how  the  algorithm  worked.  I  published 
a  “Design  Idea”  in  EDN  magazine  on 
October  31,  1984,  which  may  help  to 
clarify  the  function  of  the  bitwise  CRC 
algorithm.  This  Design  Idea  was  voted 
“best  of  issue,”  so  there  must  be  many 
people  out  there  who  found  the  appli¬ 
cation  of  software-generated  CRCs  in¬ 
teresting. 

The  basis  of  the  algorithm  is  a  simu¬ 
lation  of  the  hardware  tapped  shift- 
register  used  to  generate  CRCs.  I  show 
the  registers  shifting  right  while  your 
implementation  shifts  left.  Your  feed¬ 
back  constant  0x1021  is  the  CCITT  value 
0x8408  bit-reversed.  Your  version  of 
the  implementation  stores  the  data  byte 
into  the  lower  8  bits  of  the  left-shifted 
CRC  in  order  to  affect  the  data  input 
which  I  show  as  a  single  bit  input  to 
the  accum_crc  function.  My  CRC  is 
16-bits,  while  your  implementation  re¬ 
quires  a  24-bit  CRC  variable,  of  which 
the  high-order  1 6-bits  match  my  CRC 
variable. 

I  hope  that  this  helps  to  clarify  the 
CRC  algorithm  Al  showed  in  his  article. 
Considering  the  amount  of  interest  I 
found  when  1  published,  you  will  prob¬ 
ably  get  a  number  of  letters  from  read¬ 
ers  concerning  the  CRC  function.  There 
are  much  faster  CRC  algorithms  which 
use  small,  precomputed  tables  to  do 
the  CRC  calculation  for  an  entire  data 
byte  at  a  time,  eliminating  the  for  loop 
required  in  the  bit-by-bit  algorithms  I 
have  devised. 

Meanwhile,  keep  the  articles  com¬ 
ing!  You  do  the  readership  a  great  serv¬ 
ice  by  publishing  source  code  listings 
in  the  magazine.  I’ve  been  a  reader 
(and  occasional  contributor)  for  over 
12  years  now. 

Robert  D.  Grappel 

Concord,  Mass. 


Mapping  DOS  Memory  Revisited 

Dear  DDJ, 

I  am  writing  in  response  to  a  letter  from 
Bruce  Koivu  that  appeared  in  your  April 
(continued  on  page  1 73) 
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Smalltalk + C 

The  Power  of  Two 

Is  Smalltalk  +  C  >  C++9 


SMplusiK^ioi.ipplit.-iuiiv.  require 

the  integral  if  m  of  m any  software 
<  ompowms  and'  «  has  .recently 
been  argued  that,  object-oriented 
technology  is  nm  <4  (he  roost 
effective  ways  u>  deal  with  this  <nm 
plextty  Although  many  programmers 
flvt  -i  ait-  extending  *n  existing  tan 
guagt  such  o  c  into  a  hybrid  lan¬ 
guage,  such  as  O*  or '  Objective  €, 
‘he si  svsiems  lack  the  flexibility.  li¬ 
brary  .  ■\unnjnmr.i  j  memory  man 
ugvment  of  pur*-  ■  ihjeet  < .« lented  lan¬ 
guages  like  Smalltalk. 

In  this  article,  we  describe  t  prag¬ 
matic  appro*.  h  w  inch  we  cat!  'Small 
talk  i  i  that  allow, s  each  language  to 
tn  used  w  here  appropriate.  'mull?  ilk 
tor  example,  is  used  to  represent  and 
manipulate  high-level  infonnatten  whik 
€  is  used  to  implement  small,  time-' 
resource  critical  km -level  facilities  — - 
an  approach  we’ve  found  to  be  effec¬ 
tive.  First,  well  illustrate  the  power  o' 
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talk's  Smalltalk  V.  Second,  well  exam¬ 
ine  an  embedded  TCP/IP  network  ap¬ 
plication  written  in  Smalltalk,  V286 

The  Strength  of  C 

The  major  i  tenefits  and  weaknesses  of 
C  are  well  known  to  most  readers  of 
ODJ.  C  is  a  low-level  language  for  sys¬ 
tems  programming  such  as  device  driv¬ 
ers.  it  is  portable,  and  in  most  cases,  is 
the  most  efficient  language  available 
on  a  given  hardware  platform.  Unfor¬ 
tunately.  when  C  is  used  in  a  large 
project,  its  power  leads  to  problems  of 
reliability,  (The  market  for  hardware 
debuggers  is  testimony  to  the  prob¬ 
lems  of  debugging  huge  C  applications.  ) 
We  use  €  lor  the  necessary  low  -level 
routines  for  our  applications.  Because  j 
these  routines  typically  have  a  single 
e.v  -an  la-  wri  t<  in  a  small 
number  of  lines,  they  are  readily  un¬ 
derstood  and  tested .  Often  these  small 
modules  can  be.- reused  in  several  quite 
different  applications. 


Smalltalk  provides  all  of  the  facilthes 
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least  access  •<>  a,  program  written  m 

another  language  There  are  nvo  ways 
to  do  this  in  Smailtalk/V,  by  “using  the 

l)f)>  shell'  and  through  “user  prim¬ 
itives'  in  Smaiit.uk. a  more  so¬ 
li  .!K  -I  inn  h  Ilia  h-t  '  interrupt 
strategy  is  available. 

The  dbPUBUSHE#  Challenge 

Jigs  abase  publishing  requires  complete 
'report  generation ,  data  cop version,  for- 
tnaU  :ug.  .uni  tight  :v  1 1  >n fili-d  page  com- 
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In  general,  the  solution  is  to  move 
the  offending  objects  to  low  memory 
where  they  can  be  protected  by  the 
primitive,  or  (in  the  case  of  unwanted 
asynchronous  events  such  as  the  mouse 
event  handler)  be  masked,  disabled, 
or  replaced,  as  appropriate.  Smalltalk 
parameters  and  the  DTA  pointer  can 
be  moved  into  low  memory,  but  asyn¬ 
chronous  interrupt  service  routines 
(ISRs)  are  not  easily  detached  and 
moved  about.  Thus,  the  only  solutions 
available  are  to  either  disable  them,  or 
to  replace  the  offending  ISRs  with 
dummy  code  that  prevents  the  system 
from  crashing. 

It  is  not  acceptable,  however,  to  ar¬ 
bitrarily  re-vector  the  entire  interrupt 
vector  table,  nor  is  it  acceptable  to  dis¬ 
able  essential  hardware  interrupts  (that 
is,  diskette,  keyboard,  real-time  clock, 
and  so  on).  Actually,  the  only  inter¬ 
rupts  that  need  to  be  re-vectored  are 
those  that  might  get  clobbered  when 
the  application  is  executed.  In  other 
words,  if  an  interrupt  vector  currently 
points  into  the  region  of  memory  that 
we  are  about  to  make  available,  we 
should  first  point  that  vector  to  a  dummy 
ISR’  then  restore  it  when  we  are  through. 

The  source  code  in  Listing  Two  (page 
94)  illustrates  the  primitive  implemen¬ 
tation  for  an  interface  to  DOS,  special 
purpose  dbPUBLISHER  primitives,  and 
running  external  C  and  Pascal  programs. 

A  TCP/IP  Ethernet  Application 

However  unlikely  it  may  seem,  we  used 
SmalltalkA'286  in  a  TCP/IP  application. 
It  provided  split  execution  of  the  gra¬ 
phical  human  interface  on  an  IBM  AT, 
with  a  specialized  Smalltalk/V286  em¬ 
bedded  virtual  machine  running  on  a 
VME  bus  Unix  system.  This  application 
proved  that  the  speed  of  the  byte  code 
interpreter  was  up  to  the  task. 

This  application  required  the  pro¬ 
cessing  of  interrupts  from  an  external 
hardware  and  software  source.  Digi- 


Figure  1:  dbPUBLISHER  architecture 


talk  provided  virtual  machine  interrupts 
for  this  application.  Listings  Three  and 
Four  show  source  code  that  illustrates 
the  interface  between  a  TCP/IP  Ether¬ 
net  resident  driver  (that  runs  in  Real 
mode)  and  Smalltalk/V286.  (Listing 
Three,  page  95,  shows  a  sample  Small- 
talk/V286  calling  method,  while  Listing 
Four,  page  96,  provides  the  Smalltalk/ 
V286  assembly  language  primitive  in- 

Smalltalk  is  used  to 
represent  and 
manipulate  high-level 
information,  and  C  is 
used  to  implement 
small,  time/resource 
critical  low-level 
facilities 


terface.)  This  interface  allows  a  host 
PC  to  talk  to  an  embedded  target  real¬ 
time  system. 

One  Smalltalk  user  primitive  is  pro¬ 
vided:  socketPrimitive  dispatches  the 
appropriate  code  based  on  an  opcode 
parameter.  The  arguments  are  passed 
in  a  Smalltalk  Array.  The  primitive  runs 
in  protected  mode,  sets  up  the  parame¬ 
ter  block  the  installed  driver  expects, 
and  switches  to  real  mode  ( CALL_ 
NETWORK  macro  in  sockprim.inc)  us¬ 
ing  the  INT50H call.  This  call  then  runs 
the  doEthernetlnt  { in  sockprim.asm)  in 
real  mode  which  does  the  INT 68H  call 
to  the  installed  driver  as  would  any 


other  application.  On  return,  the  error 
code  is  extracted  from  the  parameter 
block  and  returned  as  an  instance  field 
of  the  receiver  (the  object  to  which  the 
message  causing  the  primitive  was  sent). 
This  illustrates  mode  switching. 

As  part  of  initialization,  the  Smalltalk 
primitive  calls  the  installed  driver  (us¬ 
ing  the  procedure  described  earlier) 
with  the  address  of  a  small  routine 
(socket_event_handler) .  This  address  is 
in  the  segment  of  the  primitive  that  is 
to  be  called  when  a  Smalltalk  VM  Inter¬ 
rupt  should  be  generated.  Any  hard¬ 
ware  interrupts  cause  an  automatic 
switch  to  real  mode  and  a  call  to  the 
handler  that  was  installed  before  Small¬ 
talk  was  invoked.  Thus,  upon  servicing 
an  interrupt  from  the  Ethernet  card,  the 
installed  driver  can  call  socket_event_ 
handler  in  real  mode  to  cause  a  Small¬ 
talk  VM  Interrupt.  Virtual  Machine  In¬ 
terrupts  can  be  generated  from  either 
real  or  protected  mode;  both  are  han¬ 
dled  by  different  Digitalk  macros. 

Conclusion 

These  examples  illustrate  how  two 
proven  programming  languages  can  be 
combined  into  a  single  application.  This 
approach  enabled  us  to  get  a  new  prod¬ 
uct  into  production  quickly,  in  spite  of 
a  small  engineering  budget.  We  now 
have  time  to  do  the  OS/2  Presentation 
Manager  version  by  re-directing  Small- 
talk/V286  primitives  to  the  appropriate 
PM  calls,  and  to  improve  performance 
with  multitasking  techniques.  We  can 
port  the  application  to  the  Macintosh 
II  with  less  trauma  than  typical  Mac 
ports  and  with  a  guaranteed  reliability 
factor.  Smalltalk’s  inherent  object  pro¬ 
tection  yielded  a  bullet-proof  applica¬ 
tion  program  for  first  release. 

The  success  of  HyperCard  and  Hy¬ 
perCard  Xcommands  (primitives)  is  an¬ 
other  convincing  example  of  the  bene¬ 
fits  of  small,  single-function  primitives 
combined  with  a  flexible  user-program¬ 
mable  interpreter.  The  point  is  simple  — 
use  the  right  language  for  the  right  job. 

Availability 

All  source  code  for  articles  in  this  issue 
is  available  on  a  single  disk.  To  order, 
send  $14.95  (Calif,  residents  add  sales 
tax)  to  Dr.  Dobb’s Journal ,  501  Galves¬ 
ton  Dr.,  Redwood  City,  CA  94063,  or 
call  800-356-2002  (from  inside  Calif.) 
or  800-533-4372  (from  outside  Calif.). 
Please  specify  the  issue  number  and 
format  (MS-DOS,  Macintosh,  Kaypro). 

DDJ 

(Listings  begin  on  page  94.) 

Vote  for  your  favorite  feature/article. 

Circle  Reader  Service  No.  1. 
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C-to 


Making  the 

_  o 


Connection 

No  matter  which  camp  you  re  from,  the  C-to- Fortran 
connection  can  add  functionality  to  your  programs 


If  you  ve  ever  had  to  tna|te  a  con¬ 
necting  Rigid  to  gei  to  your  final 
<.ic&knatton,  >ou  know  it  takes  more 
than  getting  off  one  plane  am! 
onto  another.  Among  other  things, 
someone  has  to  check  that  your  bag- 
gfgt  follows  your  irriving  flight  has 
to  be  on  time,  and  you  have  to  get  to 
the  right  gate  at  the  right  time. 

Making  the  C-to  Fortnan  connection 
is  much  the  same.  As  a  programmer, 
you  must  ensure  that  arguments  ’'get 
from  one  language  m  die  next  and 
that  any  excess  baggage  is  handled, 
r’timatdv,  you  gain  the  benefits  of  both 
languages.  With  huge  Fortran  libraries 
such  as  IMSL  and  the  wealth  of  avail¬ 
able  third-party  C  tools,  there’s  no  tell¬ 
ing  how  far  you’ll  be  able  to  take  it. 

ih.-.  article  sin  ws  you  hov  to  tali  a 
hahey  •  i  RTKAN  subprogram  from  a 
C  mam  pnigum.  and  how  to  call  a  C 
function  from  a  Fortran  program  For 
the  purposes  of  ibis  article  l*m  using 
Borland-  Turbo  C  1 .5  with  Lahey  s  F7?L. 
1 1  s*  inta  i1k.ii  vi irk> eqttalh  weii  with 
odie  r  C  <  omjaters,  including  Microsoft  C 

Coifing  Fortron  from  C 

The  procedure  for  calling  Fortran  sub¬ 
program#  varies  slightly  between  the 
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Michael  A.  Floyd 

different  versions  of  C.  In  particular, 
Microsoft  C  main  programs  cannot  call 
F7T  subroutines  and  functioas  directly. 

Instead,  you  must  create  a  main  pro¬ 
gram  in  FTT.  that  immediately  calls  the 
MSC  mainC  las  if  it  was  a  subprogram. 
Once  loaded,  main( yean  call  the  ap¬ 
propriate  Fortran  subprograms.  Turbo 
C  and  lattice  C,  on  the  other  hand,  can 
call  F771  subprograms  directly. 

Because  F77L  references  data  by  ad¬ 
dress,  all  arguments  passed  by  the  0 
program  must  be  pointers.  In  the  case 
of  numerical  constants,  few  instance,  it 
is  necessary  to  assign  the  constant's 
value  to  a  C  variable  and  reference  the 
variable’s  address.  Table  1  provides  a 
list  of  C  data  types  that  may  be  passed 
to  F77L  along  with  their  corresponding 
Fortran  data  types. 

In  addition,  Fortran  handles  strings 
differendy  than  C  does.  In  F77L,  CHAR- 
ACrER’C*/  refers  to  a  descriptor  struc¬ 
ture  that  contains  the  address  <  4  bytes  > 
and  size  (2  bytes)  of  the  string.  The 
string  size,;  howe'er,  -run  or  may  rv 
be  specified  at  compile  time.  There¬ 
fore,  the  CHARACTBRXV  declaration 
must  indicate  that  a  variable-length 
string  is  being  passed,  the  length  of 
which  is  determined  by  the  caller  E\ 
ample  i  shows  how  to  pas#  a  string 
as  well  as  an  integer  and  a  reed,  from 
C  to  F7?L. 

!  )n  ire  Fortran  sic;  of  lb  mpie  1 
nonce  .he  HCl'X'n.RS  St.  ~  ittrne:-  ire 
following  the  subroutine 
b  ,idc.  Lahey  provides  three  exu-rn  d 
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for  some  confusion.  In  particular,  C  and 
Fortran  treat  array  subscripting  and  se¬ 
quential  order  differently.  C  begins  its 
subscripting  at  element  0  while  Fortran 
normally  begins  subscripting  at  element 
1.  F77L,  however,  allows  you  to  create 
arrays  that  are  0  relative.  Therefore, 
you  must  remember  to  declare  all  ap¬ 
propriate  arrays  to  begin  at  element  0. 

In  addition,  arrays  in  F77L  behave 
much  like  the  pointers  in  a  parameter 
list.  For  example,  consider  the  follow¬ 
ing  code  fragment: 

BCEXTERNAL 

INTEGER*2  1(0:9) 

CALL  C_FUNCnON(I,  1(3)) 

In  C,  the  corresponding  definition  is 
as  follows: 


void  c_function(i,  i3) 
int  i[10],  *i3; 


C  and  Fortran  also  handle  multi¬ 
dimensional  arrays  differently.  Fortran 
stores  arrays  in  column-major  format 
while  C  stores  arrays  in  row-major  for¬ 
mat.  The  solution  is  to  simply  reverse 
the  subscripts  in  one  of  the  two  lan¬ 
guages.  For  example,  consider  the  fol¬ 
lowing  two-dimensional  array  declared 
in  Fortran: 

integer*2  A(3:0,  4:0) 

The  array  is  sequentially  referenced  as 
A(0,0),  A(1,0),  A(2,0 ),  A(0, 1),  A(l,l), 
A(2,l),  and  so  on.  To  ensure  compati¬ 
bility,  the  corresponding  C  definition 
must  be  as  follows: 

int  A[4][31; 


Obviously,  the  language  you  choose 
to  reverse  subscripts  in  is  not  impor¬ 
tant.  To  avoid  confusion,  however,  you 
may  wish  to  choose  one  language  to 
consistently  switch  subscripts  through¬ 
out  all  of  your  programs.  That  way  you 
will  never  doubt  whether  your  arrays 
are  row-major  or  column-major. 

File  I/O 

You  must  also  be  aware  of  differences 
in  the  way  files  are  handled  between 
the  two  languages.  F77L,  in  particular, 
adds  header  and  indexing  information 
to  a  file.  Normally  this  information  is 
transparent  to  the  programmer.  C,  on 
the  other  hand,  adds  no  such  header 
nor  indexing  information.  In  addition, 
F77L  uses  unit  numbers  to  access  files, 
while  C  uses  file  handles  and  stream 
pointers.  The  heuristic,  then,  is  to  open, 
read,  write,  and  close  a  file  all  from 
within  the  same  language.  The  excep¬ 
tion,  of  course,  is  the  standard  device 


CType  . . 

Fortran  Type 

int  * 

INTEGER*2 

long  int  * 

INTEGER*4 

float  * 

REAL*4 

double  * 

REAL*8  (double  precision) 

float[2]  (real  portion  is  stored  in  the  first  array 
element) 

COMPLEX 

Struct  Complex  * 

COMPLEX 

double[2]  (real  portion  is  stored  in  the  first 
array  element) 

COMPLEX*  16 

Struct  DoubleComplex* 

COMPLEX*16 

char* 

LOGICAL‘1 

struct  CHARACTER  { 
char  'text; 
int  length; 

i 

CHARACTER'D 

Table  1:  Data  types  that  can  be  passed  from  C functions  to 
Lahey  FORTRAN  subprograms 


/*  Shows  how  to  pass  integer,  float,  and  string  parameters 
from  C  to  F77L. 

*7 

typedef 
struct  { 
char  *text; 
int  length; 

}  Str; 

extern  void  fortran_sub (int  *,  float  *,  Str  *); 

main  () 

{ 

int  number; 
float  realNumber; 

Str  charStr; 

number  =  20; 
realNumber  =  23.9; 

charStr. text  =  "Passing  a  text  string"; 
fortran_sub (& number,  SrealNumber,  ScharStr) ; 

) 

c 

c  Fortran  subroutine  to  take  three  arguments  (integer,  real, 
c  and  character  string)  passed  from  C,  and  print  the  results, 
c 

SUBROUTINE  FORTRAN_SUB (IntVal,  RVal,  CharStr) 

BCEXTERNAL  FORTRAN_SUB 
INTEGER*2  IntVal 
REAL  RVa.L 

CHARACTER* (*)  CharStr 

PRINT  *,  IntVal,  RVal,  CharStr 

_ END _ 

Example  1:  Passing  a  string  from  C  to  F77L 


/*  Shows  how  to  access  the  return  value  of  a  Fortran  function.  */ 

extern  void  cube  (int  *,  int  *); 

main  () 

{ 

int  InVal,  ReturnVal; 

InVal  =  2; 

cube (&ReturnVal,  &InVal); 


c  Fortran  function  to  caluclate  the  cube  of  a  given  number, 
c 

FUNCTION  CUBE (X) 

BCEXTERNAL  CUBE 

INTEGER*2  X,  CUBE 
CUBE  =  X*X*X 

END 


Example  2:  Accessing  the  return  value  of  an 
F77L  function 


Fortran  Type 

C  Type 

INTEGERS 

int  * 

CARG(INTEGER*2) 

int 

INTEGER*4 

long  int  * 

CARG(INTEGER*4) 

long  int 

REAL*4 

float  * 

CARG(REAL*4) 

float  (double  pushed  on  stack) 

REAL*8  (double  precision) 

double  * 

CARG(REAL*8) 

double 

COMPLEX 

struct  complex* 

COMPLEX 

float[2]  (real  portion  stored  in  first 
array  element) 

COMPLEX*16 

struct 

COMPLEX*16 

double[2] 

LOGICAL*  1 

char  *  (Boolean  value) 

LOGICAL’4 

— 

CHARACTER 

char[  ] 

CARG(CHARACTER) 

char[  ]  (null-terminated) 

label 

— 

EXTERNAL 

Table  2:  Data  types  that  can  be  passed  from  Lahey 
FORTRAN  subprograms  to  C  functions 
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I/O  performed  on  unformatted  files. 
In  this  case,  it  is  important  to  remem¬ 
ber  that  a  given  file  cannot  be  opened 
simultaneously  by  both  languages. 

Who's  the  Boss? 

When  it’s  time  to  compile  and  link  your 
modules  together,  the  first  question  you 
should  ask  yourself  is  “who’s  the  boss?” 

The  language  in  which  the  main  pro¬ 
gram  is  written  is  the  boss.  The  boss 
controls  the  environment  that  your  pro¬ 
gram  will  run  in.  Environmental  con¬ 
siderations  include  how  memory  is  man¬ 
aged  and  language  calling  conventions. 
When  the  main  program  is  written  in 
C,  all  of  the  F77L  runtime  routines  are 
available  except  SYSTEM  and  CHAIN. 
Of  course,  all  of  the  C  runtime  routines 
are  available.  When  the  main  is  written 
in  F77L,  all  of  the  Fortran  run-time  rou¬ 
tines  are  available.  On  the  C  side,  func¬ 
tions  not  requiring  the  C  environment 
are  accessible.  Some  memory  manage¬ 
ment  functions  such  as  malloc ,  calloc, 
and  free  are  supported.  Many  others, 
including  farmalloc  and  sbrc,  are  not. 

Now  it’s  time  to  bring  the  compo¬ 
nents  of  your  program  together  into 
an  executable  file.  F77L  uses  the  large 
memory  model,  so  remember  to  com¬ 
pile  your  C  modules  under  the  large 
model  as  well.  This  also  means  that  far 
pointers  are  always  used.  And  be  sure 
that  stack  checking  is  turned  off  when 
compiling  on  the  C  modules.  On  the 
Fortran  side,  use  the  /NI  switch  to  turn 
off  interface  checking.  And  because 
floating-point  calculations  are  handled 
by  C,  the  NDP  compiler  option  is  un¬ 
necessary.  If  you  need  floating-point 
emulation,  select  the  /E  option. 

For  the  link  step,  Lahey  provides  a 
set  of  interface  routines  in  two  object 
modules  that  coordinate  the  different 
language  environments.  BCF77L  is  used 
when  C  is  the  boss,  and  F77LBC  is 
used  when  Fortran  is  the  boss.  In  addi¬ 
tion,  you’ll  have  to  include  C’s  initiali¬ 
zation  module,  COL,  when  C  is  the  boss. 
No  matter  who  the  boss  is,  you’ll  al¬ 
ways  include  both  languages’  run-time 
libraries.  The  connection  relies  on  C’s 
libraries  for  floating-point  calculations, 
so  you’ll  either  use  C’s  floating  point 
or  emulation  library.  I’ve  included  the 
link  command  line  for  the  C  to  F77L 
connection  at  the  top  of  Listing  One 
(see  page  102),  and  the  F77L  to  C  con¬ 
nection  at  the  top  of  Listing  Three  (see 
page  104). 

Graphically  Speaking 

DOT.C  (Listing  One)  is  a  Turbo  C  pro¬ 
gram  that  uses  the  Borland  Graphics 
Interface  (BGI)  routines  to  randomly 
plot  pixels  on  the  screen.  The  C  mod¬ 
ule  calls  FRAND.FOR  (Listing  Two,  page 
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104)  to  generate  the  random  locations. 

The  BGI  initialization  routine  Initial- 
ize( )  was  taken  directly  from  Borland’s 
BGIDEMO  program,  and  demonstrates 
an  easy  method  for  supporting  multi¬ 
ple  hardware  configurations. 

Specifically,  RANDDOT  performs 
hardware  detection  and  supports  Her¬ 
cules  graphics,  CGA,  EGA,  and  VGA 
hardware.  The  interface  demonstrates 
how  both  a  Fortran  subroutine  and  a 
function  can  be  called  from  C. 

After  initializing  the  system  to  graph¬ 
ics  mode,  RandomDotj )  is  called  and 
the  viewport  settings  [established  by 
Initialize^  J\  are  retrieved.  Next,  the  For¬ 
tran  subroutine  SEED_RAND  is  called 
to  get  the  initial  seed  value  that  will  be 
used  by  F77L’s  random  number  gener¬ 
ator.  SEED_RAND  calls  RRAND,  which 
references  the  system  clock  to  generate 
the  initial  pseudorandom  value.  RRAND 
also  generates  and  stores  the  seed  value, 
which  the  random  number  generator 
function  RND  will  later  use.  The  initial 
value  generated  by  RRAND  is  returned 
to  the  caller  in  RandomDotj  ). 

Next,  a  for  loop  is  used  to  generate 
and  plot  500  randomly  placed  (and 
colored)  dots  on  the  screen.  The  ran¬ 
dom  values  are  gotten  from  the  Fortran 
function  FRAND  which,  in  turn,  calls 
RND.  RND  retrieves  the  seed  value  gen¬ 
erated  by  RRAND.  This  process  of  seed¬ 
ing  RND  is  completely  transparent  to 
the  programmer,  and  is  one  of  the  side 
benefits  of  using  the  Fortran  RND  func¬ 
tion  as  opposed  to  C’s  randomC /func¬ 
tion.  It  is  also  worth  noting  that,  from 
the  C  side,  it  is  difficult  to  distinguish  a 
subroutine  from  a  function  because  the 
Fortran  function  must  return  its  value  as 
the  first  argument  in  the  parameter  list. 

Sorted  Partners 

As  a  final  example,  consider  SORT.FOR 
(see  Listing  Three).  SORT  uses  RND  to 
generate  an  array  of  random  integer 
values  that  are  then  passed  to  C’s  qsort 
routine  (see  Listing  Four,  page  104)  for 
sorting  in  ascending  and  descending 
order.  Once  sorted,  the  values  are  dis¬ 
played  and  the  user  is  prompted  for  a 
value  to  search  for.  The  input  value  is 
passed  to  C’s  bsearch  function  and  the 
results  of  the  search  are  displayed.  The 
sort  could  have  been  done  using  a 
bubble  sort  in  Fortran,  but  a  quick  sort 
is  much  faster.  C’s  bsearch  function  is 
used  for  similar  reasons.  Add  to  that  C’s 
ability  to  manipulate  pointers,  and  things 
start  moving  significantly  faster.  Finally, 
qsort  and  bsearch  are  part  of  the  run¬ 
time  library,  so  there’s  no  need  to  rein¬ 
vent  the  wheel. 


Final  Nofe  on  Versions 

As  mentioned  at  the  beginning  of  this 
article,  I  used  Borland’s  Turbo  C  1.5. 
TC  2.0  was  not  supported  at  the  time 
of  this  writing,  although  Lahey  plans 
to  release  a  new  version  of  F77L  by  the 
time  this  article  reaches  print.  Lahey 
also  supports  Microsoft  C  3.2  and  up, 
although  there  are  problems  passing 
character  lengths  in  MSC  4.0.  The  con¬ 
nection  also  works  with  early  versions 
of  Lattice  C,  but  Lahey  no  longer  sup¬ 
ports  that  compiler.  On  the  Fortran  side, 
Lahey  provides  a  32-bit  version  of  F77L 
(F77L-EM/32)  that  is  compatible  with 
Metaware’s  High  C  386.  On  the  low 
end,  Lahey  provides  a  student  version, 
LP77,  that  is  compatible  with  the  C 
compilers  mentioned  earlier.  LP77,  how¬ 
ever,  requires  routines  from  the  LP77 
toolkit,  which  is  available  separately 
from  Lahey  Computer  Systems. 

Author’s  Note:  I  want  to  thank  every¬ 
one  on  the  Lahey  technical  staff  for  their 
assistance  while  preparing  this  article. 
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All  source  code  for  articles  in  this  issue 
is  available  on  a  single  disk.  To  order, 
send  $14.95  (Calif,  residents  add  sales 
tax)  to  Dr.  Dobb’s Journal ,  501  Galves¬ 
ton  Dr.,  Redwood  City,  CA  94063,  or 
call  800-356-2002  (from  inside  Calif.) 
or  800-533-4372  (from  outside  Calif.). 
Please  specify  the  issue  number  and 
format  (MS-DOS,  Macintosh,  Kaypro). 

DDJ 
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makes  it  ideal  for  use  in  a  .printer,  winch 
typically  has  a  unidirectional  connec¬ 
tion  to  a  computer.  PostScript  is  prob¬ 
ably  the  most  powerful  way  currently 
available  for  specifying  the  description 
of  an  output  page  in  a  printer. , 

The  problem  with  PostScript  is  that 
everything  a  printer  does  has  to  be 
written  in  PostScript.  You  can’t  send  it 
straight  text  (PrintScteen  doesn’t  work 
at  all),  and  you  certainly  can't  send  it 
an  image  without  working  pretty  hand. 

So  how  do  you  print  an  image  in 
PostScript?  Using  the  image  operator 
is  most  common  I 'his  function  takes  a 
stream  of  data  and  converts  it  to  a 
i  octangular  bitmap  of  arbitrary  si2e,  with 
1,  2, 4  ,  or  8  bits  per  pixel.  But  PostScript 
can't  accept  binary  data  tit  nsenes  and 
traps  iiiiS-tm  ASCII  i-ontroS  charai  tens), 
so  alt  it,  input  must  he  converted  to 
Ik  x  or  .-amt-  othei  pnntabk  t<  m  w  ha  1 
then  has  to  lave  PostScript  code  added 
to  it  to  make  it  print. 

In  the  course  at  my  work,  I  rseecW 
a  prog  -.’.  .  ■  perform  a  PUX-tt*- Post¬ 
Script  iransfaaon,  Because  C  is  my  lam 
■  g-.  of  choice  for  most  prefects,  I 

is  idee  low  me  the  program,  PKH  \ 
in  ,  to  a  *  pr>  e|  writing  PSPQC 
I  Uvmcc.  a  lot  '■  ut  PCX  files  and 
so  i'r.-C'ciuu  aa4< «<bfieas.nnc 
me  Stinking  jtlxwt  € 

C  Idioms 

.  my  .wet  years  ■  i!  s  i  sfl 

.  ,  ■ 

•i>. hi  Hh-  •  1  o  »<V  e  iuili  faktv  n  pc  i!h-!c 


i  3  *  sUn<k*rd  these  days.  Devel- 

jkjr  oped  by  ZSofi.  (Marietta,  Geor- 
'  S  gial  for  use  With  their  PC  PajftC 
JL  brush  graphics  editor,  PCX  is  a 

neat'  >rubly  <  i  impact ,  yet  simple,  method 
of  storing  giapliw  -  data  i  he  PCX  file 
lot  mat  gamed  popularity  because  P< 
Paintbrush  it  as  pat  fc.gcd  with  the  Mi 
i_rr»soft  Moum’,  .«k!  most  mouse  users 
tinkeretl  with  it.  Nowadays,  a  seems 
roost  scanners,  fax  boards.  and  desk 
fnp  publishing  ft -rein1  }>ro<  ess  PCX 
files  3  found  however  that  i  had  no 
bandy  way  of  printing  these  linages 
on  a  PostScript  pnntei  except  by  read 
mg  them  into  lot  .is  Manuscript  first 

tic  ttlarfy  when  the  image  <.  ante  to  >m  a 
fax  card). 

~ 

page  (iettnirii  m  language  tPDlh  a  pro¬ 
gramming  language  enhanced  with  a 
h*i  cH  ,i|N  that  allow  *hc  -pettfi 

cation  ot  trunks  on  :  page,  including 
images  line-drawing  and  text.  It  &  a 
.-..riur1  I  language  whose  most 
salient  land  mreceamgS  lecture  is  that 
it  can  is  read  and  processed  in  linear 
order  vtl.  s-  ever  oe.  kinj  up  :  ■ 


to  \  I  h-  .  \J  1  ■  i  ]  MVi-fUng !  .iiU  t  -*:n 

Ci  there  art-  usually  sever*!  different  1  tm  th«  fiy,  couki  speed  uhihe  p&v^. 
u  m  jH-rloisn  ,1  gives  ia*k  f  ha-  I  greadr  bus  would  complicate  matters 
been  art  treed  ...f  being  4  write  only  |  unnCcere,uniy  fon'urpurptrees  Michael 

programmers  who  i,«i  i»  develop  and  f  Paradigm  Fm  gv*  it  nght  then  gel  a 
follow  the  particular  idioms  of  the  fan-  j  fast,  Although  there  are  exceptions  to 
gnasre  O.antx-  •.votfenthadlj.xit  k«>k  ?  any  nile,  ft  certainly,  applies  in  this  case; 
life  P:«.w.  •  :i  or  any  of  j  number  of  other 
languages  A  good  programmes  teams 
••  develops  a  *'€-i$h  programming 
style,  that  becomes  a  standard  code 
that  requires  litte*  effort  to  write  or  un¬ 
derstand.  A  ibss.'i.  example  is  the  tradi¬ 
tional  counting  loop: 


A  PCX  file  has  a  128-byte  header  that 
ctescrihes  Ae ;  onients  of  the  rest  of  the 

ftie.  ZSoft  has  not  been  lazy  — •  there 
have  been  at  least  five  versions  of  PC 
Paintbrush,  and  PCX  files  have  changed 
to  keep  up.  What's  good  is  that  the  same 
header  format  applies  to  all  PCX  versions 
to  date.  What's  bad  is  that  the  data  for¬ 
mats  that  follow  the  header  vary  wildly  — 
unfortunately  for  portability,  PCX  files 
are  tied  fairly  closely  to  the  video  board 
on  which  they  were  created. 


multiple  byte- 1  if  data  Xe«F,tng*ng these 
brt  planes  ifit*  •  single  pixel  values  then 
cross-referencing  them  so  they  can  he 
printed  sensibly  on  a  monot  hiome 

printer  might  be  an  interesting  exer¬ 
cise,  but  is  beyond  the  scope  of  this 
article. 

Monochrome  boards  (or  mono¬ 
chrome  modes  on  color  boards.)  just 
store  the  data  as  a  stream  of  bits.  Since 
the  printer  is  monochrome  anyway,  J 
chose  to  limit  PRPCX  to  using  only  files 
created  in  monochrome  mode. 

The  first  routine  (pcx_read_header) 
reads  the  PCX  header  into  a  data  mu 
It  allocates  a  data  area  if  one  is  not 
specified.  Here’s  the  first  idiom:  When 
passing  a  pointer  to  a  structure  as  an 
atgurrtcni  to  a  subroutine,  Ituke.i  NHLL 
pointer  to  mean  that  the  uw  js  n 
questing  automate  allocation  of  the 
data  area. 

The  pc.x_  header  fields  include  infor¬ 
mation  on  the  version  ot  PCX  used  1. 
create  .Ac  fife,  the.  daf  •  1  , wfsion 

method  (only  RLE w  -n  p:*  i  to  date  J. 

and  tire  numlx-r  <>  1  u  pe-  pixel  r  the 
image  1  he  Pt.X  ilk.  defines  a  rectangie 
of  data  which  always  >  an  even 
number  of  hvtcs  per  line  and  a  itombu 
t«l  Hnc-  that  o  a  multifile  of  eight  fire 
:  s  ■■  tee- 

define  ih-  actual  ,uzt  and  p> ettfon  o* 

:  ■  \ 

-!  :e  1  m  !i  ■  palette  :i  :  if  it  fits  tit  his 

Sur  up  to  Vi  colors!  If  it  doesn’t  fit,  >1 
ii  stored  at  the  end  of  die  fife?,  w  tfh  the 
type  of  palette  indicated  by  ftaktuinfo. 

The  '  » ’  J-  1  n  h  •  .  .  prints, 

are  data  a  given  file  tn  user-readable 
form.  For  someone  e  vint;  tt>  use  -1/  -r : . 
and  ■-  .in',;,  to  'i?w.  ;i.  unage  tk. 

I  ■  >•..  out  she  ,te  to  .  !  tu  -  itnu- 
t«re  Irei  sure  ft  seen  ire  desimbte  to 


tor  I  red,  .  1  ■  *) 
d<y,minult«ngi  t,: 


t  re  A  Mtfk  pt\i  fcuger  ktoms  as  well,  sev- 
1  nil  1  if  which  appear  in  she  program. 

i  (ll  1  ,'•»!  pi  ihtCDl  " 


1 

ton  j 

key  to  the  whole  process.  It  reads  the 
next  line  from  the  PCX  file  and  returns 
it,  in  unpacked  raw  data  form,  to  the 
caller.  Understanding  it  requires  an  un¬ 
derstanding  of  the  PCX  file  format  and 
its  method  of  data  compression. 

PCX  files  use  run  length  encoding 
(RLE)  for  compression  —  basically,  any 
consecutive  data  bytes  which  have  the 
same  value  are  replaced  by  a  count 
byte  followed  by  the  value.  Count  bytes 
are  distinguished  from  data  bytes  by 
setting  the  top  two  bits;  the  bottom  six 
bits  represent  the  number  of  repeti¬ 
tions,  from  0  to  63.  If  a  data  byte  needs 
to  use  a  value  with  data  in  this  range, 
it  can  do  so  by  specifying  a  repeat 
count  of  1. 

RLE  is  sometimes  an  excellent  way 
to  store  image  data,  especially  if  (like 
most  pictures  generated  with  PC  Paint¬ 
brush)  the  image  contains  large  areas 
of  solid  colors.  However,  on  random 
data  or  gray  scale  images,  where  there 
are  few  repeated  data  bytes,  the  PCX 
format  is  likely  to  be  some  25  percent 
larger  than  raw  data  size  because  of  the 
escape  code  necessary  for  data  bytes 
with  the  top  two  bits  set.  For  more 
information  on  RLE,  see  “Run  Length 
Encoding”  by  Robert  Zigon  ( DDJ ,  Feb¬ 
ruary  1989)  and  “RLE  Revisited”  by  Phil 
Daley  {DDJ,  May  1989). 

The  file  PRPCX.C  (Listing  Three,  page 
106)  contains  the  rest  of  the  code  while 
Listing  Four  (page  108)  is  the  Make  file. 
The  general  flow  is  to  first  initialize  the 
map  structure  to  default  values.  This 
structure  is  used  to  contain  the  scaling 
and  positioning  data  for  placing  the 
PCX  image  on  the  PostScript  page.  Next, 
process  the  command  line  and  set  up 
the  values  for  scaling  and  sizing.  The 
.PS  file  is  then  copied  to  the  output. 
The  scaling  and  sizing  variables  are 
emitted,  and  finally  the  .PCX  file  is  read 
and  emitted  as  hex  data. 

The  command  line  parser  is  another 
idiom  that  just  flies  from  my  fingertips 
whenever  I  need  it.  Basically,  it’s  a 
simple  checker  that  looks  for  a  leading 
hyphen  (-)  or  slash  (/)  in  each  argu¬ 
ment.  If  it  sees  either  one,  it  does  a 
switch  on  the  second  character.  Matches 
generate  either  string  assignments  or  a 
conversion,  as  in  x  =  atoi(argv[i]+2);. 

If  no  leading  slash  is  seen,  assume 
that  the  argument  is  a  filename  and 
assign  the  filename  variable  to  it.  This 
is  easy,  but  limits  the  program  to  one 
filename  per  run.  Because  there  are 
good  reasons  not  to  generate  more  than 
one  image  per  PostScript  file,  this  isn’t 
really  a  problem. 

I’ve  used  this  command  line  parser 
so  often  that  it  just  writes  itself,  with 
no  concentration  required  to  make  it 


work.  Although  it’s  not  as  flexible  as  a 
general-purpose  parsing  subroutine,  it’s 
small,  fast  and  easy.  Only  rarely  have  I 
had  to  get  more  sophisticated. 

Normally,  this  program  sends  its  out¬ 
put  to  STDOUT,  so  it  can  be  piped  to 
a  disk  file,  another  filter,  or  directed  to 
the  printer.  Direct  to  the  printer,  how¬ 
ever,  may  be  the  most  commonly  used 
form.  Because  people’s  printers  don’t 
change  names,  it  made  sense  to  allow 
the  user  to  put  the  printer  name  in  the 
environment.  Once  set,  it  stays  set  until 
a  reboot  or  it  is  explicitly  changed.  This 
is  ideal  for  a  utility  likely  to  use  the 
same  arguments  over  and  over.  Those 
of  you  who  prefer  to  use  the  command 
line  can  redirect  the  output,  or  use  the 
-o  switch  (which  makes  the  most  sense 
in  batch  files). 

If  no  arguments  are  specified,  there’s 
nothing  to  do,  so  a  usage  message  is 
printed.  This  too  is  important.  I  believe 
that  a  user  should  always  be  able  to 
figure  out  something  about  what  the 
program  does  and  how  to  get  started 
without  having  to  read  the  manual  (or 
the  article).  Now  that  everything  is  set 
up,  the  program  calls  dofilej ),  which 
does  the  rest  of  the  job. 

The  first  function  dofilej )  does  is 
open  the  PCX  file.  Another  idiom:  If 
the  filename  doesn’t  contain  a  period, 
concatenate  PCX  to  the  end  of  the 
name.  This  way  the  user  doesn’t  have 
to  type  the  obvious,  but  can  override 
any  assumptions. 

Because  of  the 
expressive  power  of  C, 
there  are  usually  several 
different  ways  to 
perform  a  given  task 


dofilej )  opens  the  file,  and  if  the 
user  asks  for  it,  dumps  the  header  and 
returns  without  doing  further  work.  Next 
read  the  PostScript  prologue  file.  Many 
programmers  aren’t  aware  that  the  first 
element  in  the  argv  array  (for  DOS 
versions  later  than  3  0)  is  a  pointer  to 
the  complete  path  and  filename  of  the 


program.  For  earlier  versions  of  DOS, 
the  program  name  is  available  (put  there 
by  the  compiler),  but  the  path  from 
which  it  is  run  is  not.  Use  this  informa¬ 
tion  to  find  the  prologue  file  — 
and  simply  require  it  to  have  the  same 
path  and  name  as  the  executable  file, 
but  with  the  .PS  extension.  Again  a 
simple  rule  that  doesn’t  restrict  the  user. 

The  PostScript  Code 

I'm  using  a  fairly  standard  PostScript 
technique.  First,  create  a  prologue  file 
PRPCX.PS  (Listing  Five,  page  108)  that 
contains  PostScript  code  that  defines 
all  the  functions  needed  to  handle  the 
image  generation.  Copy  this  file  to  the 
beginning  of  the  output  file.  This  way, 
the  C  program  doesn’t  have  to  know 
much  about  PostScript,  and  an  experi¬ 
enced  user  can  modify  the  prologue 
to  do  a  different  job  without  having  to 
recompile  the  software. 

The  prologue  in  this  case  contains 
functions  for  building  the  transform  ma¬ 
trix,  reading  the  image  data  from  the 
file,  doing  scaling  and  image  genera¬ 
tion,  and  printing  the  page  after  the 
image  is  complete. 

Adobe  (Mountain  View,  Calif.)  has 
defined  a  comment  convention  for  Post¬ 
Script  files.  Files  conforming  to  the  speci¬ 
fication  can  be  specially  handled  by 
print  servers,  or  read  into  desktop  pub¬ 
lishing  programs  as  Encapsulated  Post¬ 
Script  (EPS)  files.  The  specification  is 
laid  out  in  Adobe’s  Red  Book,  Appen¬ 
dix  C.  Basically,  minimally  conforming 
programs  contain  information  that  de¬ 
fines  the  fonts  used  and  image  size. 

Normally,  this  information  is  placed 
at  the  beginning  of  the  file.  However, 
Adobe  allowed  the  instruction  ( atend) 
to  mean  that  the  actual  data  is  found  at 
the  end  of  the  file.  My  original  inten¬ 
tion  for  PRPCX  was  to  place  the  Bound- 
ingBox  item  (which  describes  the  bound¬ 
aries  of  all  the  black  marks  on  a  page) 
at  the  end  of  the  file.  Unfortunately,  I 
discovered  that  Ventura  Publisher,  in 
violation  of  the  EPS  specifications,  re¬ 
quires  BoundingBox  to  be  placed  at 
the  beginning  of  the  file. 

So  for  ease  of  programming,  PRPCX 
is  limited  to  processing  one  file  at  a 
time,  and  there  is  a  special  hack  to  fill 
in  the  BoundingBox  entry  in  PRPCX.PS. 
The  file  is  copied  to  the  output  until 
it  sees  the  line  containing  Bounding¬ 
Box.  It  then  generates  a  new  Bounding¬ 
Box  line  based  on  the  header  read 
from  the  data  file,  and  continues  with 
the  file  copy. 
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The  calculations  used  are  the  same 
as  those  used  by  PostScript’s  image 
operator,  which  is  capable  of  scaling 
and  flipping  bitmaps.  The  syntax  of  the 
image  operator  is  as  follows: 

width  height  bpp  transform  readproc 

image 

For  those  who  don’t  know  PostScript, 
the  first  thing  to  learn  is  that  it’s  a 
stack-oriented  language.  Any  operator 
takes  its  arguments  on  the  stack,  so 

PCX  is  a  reasonably 
compact ,  yet  simple, 
method  of  storing 
graphics  data 


they  come  before  the  operator  does. 
In  this  case,  the  width  and  height  op¬ 
erators  are  found  deepest  on  the  stack; 
they  are  the  width  and  height  of  the 
bitmap  in  pixels.  The  bpp  operand  tells 
the  number  of  bits  per  pixel  in  the 
image.  1,  2,  4,  and  8  are  allowed;  this 
program  only  handles  images  with  1 
bit  per  pixel. 

PostScript  allows  objects  of  any  type 
on  the  stack.  The  [  ]  (mark)  operators 
define  an  array,  which  (like  lists  in 
Lisp)  simply  collect  everything  between 
them  into  a  single  object.  In  the  case 
of  the  transform  operand,  image  ex¬ 
pects  a  six-element  array  containing 
the  transform  matrix,  which  is  used  as 
a  multiplier  to  convert  the  image  into 
the  output  area. 

Finally,  image  accepts  a  procedure 
(again  on  the  stack)  which  it  calls  to 
get  image  data.  Each  time  this  proce¬ 
dure  is  called  it  should  return  a  string 
containing  image  data.  When  width  * 
height  data  elements  have  been  con¬ 
sumed,  image  is  finished  processing. 
Returning  a  zero-length  string  aborts 
images arly.  Use  the  readhexstring  op¬ 
erator  (see  the  readproc  function  in 
PRPCX.PS)  to  read  a  hex  string  of  data 
from  the  input  and  convert  it  to  binary. 

The  Adobe  Red  Book  talks  of  a  con¬ 
vention  that  speeds  up  the  generation 
of  an  image;  if  the  image  conversions 
yield  one  input  pixel  per  device  pixel, 
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all  scaling  and  transforming  is  turned 
off,  for  a  large  increase  in  speed.  The 
default  behavior  of  PRPCX  is  to  gener¬ 
ate  the  bitmap  at  this  size. 

Adobe  recommends  handling  the 
transformation  in  two  parts.  First,  use 
the  transform  matrix  operand  (part  of 
the  image  operator)  to  convert  the  im¬ 
age  to  a  lxl  unit  square  with  the 
image  upright.  Then  use  translate  and 
scale  to  move  the  image  to  the  shape 
and  location  desired. 

Translating  to  the  unit  square  is 
slightly  complicated  by  the  fact  that  a 
PostScript  is  measured  from  the  bot¬ 
tom  of  the  page,  while  a  PCX  image 
starts  at  the  top.  Fortunately,  the  trans¬ 
form  matrix  takes  care  of  this  neatly.  A 
normal  transformation  to  the  unit  square 
uses  the  following  matrix: 

[width  0  0  height  0  0] 

The  transform  to  invert  the  Taxis  is: 

[width  0  0  -height  0  height] 

In  PostScript,  that  last  matrix  is  written: 

[width  0  0  height  neg  0  height] 

The  neg  (negate)  operator  inverts  the 
sign  of  the  object  on  top  of  the  stack 
(which  is  height,  in  this  case).  The  next 
step  is  to  convert  to  device  resolution. 
This  requires  that  you  first  translate 
the  coordinate  axes  to  the  desired  posi¬ 
tion  using  standard  resolution,  which 
is  72  dpi  (one  point).  This  way  the 
position  of  the  image  is  independent 
of  its  size. 

Next,  make  the  image  its  original 
shape  (assuming  square  pixels).  To  do 
this,  scale  the  unit  square  to  the  width 
and  height  of  the  image  in  pixels.  Then 
scale  the  coordinate  system  to  device 
resolution,  using  the  command 

72  res  div  72  res  div  scale 

The  scale  operator  takes  two  operands, 
the  scale  factor  in  X  and  Y.  Divide  72 
by  the  actual  resolution  of  the  device. 
This  makes  one  unit  in  device  space 
equivalent  to  one  unit  in  user  space. 
Finally,  to  allow  the  user  to  change 
the  scaling,  add  one  more  scale  fac¬ 
tor.  All  of  these  transformations  take 
place  in  the  scaleit  routine  within  the 
prologue. 

The  image  operator  takes  an  argu¬ 
ment  which  is  a  procedure  to  supply  it 


with  data.  Because  the  PostScript  data 
stream  has  certain  reserved  characters, 
use  the  readhexstring  operator  to  ac¬ 
cept  hex  data.  This  doubles  the  num¬ 
ber  of  bytes  sent  to  the  printer,  but 
that’s  the  way  it’s  generally  done;  it’s 
certainly  the  easiest  to  code.  The  read¬ 
hexstring  operator  fills  a  string  with 
data  from  the  input  file.  In  order  to 
ensure  that  it  doesn’t  read  past  the  end 
of  the  file,  you  have  to  build  a  string  just 
large  enough  to  hold  one  line  of  input. 
The  imagedata  routine  in  PRPCX.PS 
contains  code  to  do  this. 

Now  we  start  generating  PostScript 
code.  First  define  and  give  values  to  all 
the  variables  used  by  the  prologue. 
Then  tell  PostScript  to  actually  do  the 
scaling  and  translation  calculations.  Fi¬ 
nally,  tell  it  to  start  accepting  an  image. 

The  image  is  processed  by  expand¬ 
ing  each  line  to  raw  data  using  the  PCX 
routines,  inverting  it  if  necessary,  then 
emitting  the  data  as  a  stream  of  hex 
bytes.  Each  line  of  input  data  is  sepa¬ 
rated  by  a  newline  in  the  output  file. 

At  the  end  of  the  file,  emit  the  code 
to  get  PostScript  to  generate  the  image 
(the  single  operator  showpage ),  and 
you’re  done.  The  grestore  operator  re¬ 
stores  the  image  context  that  existed 
before  you  started  this  whole  process. 
This  is  simply  good  manners;  a  good 
idea  when  generating  EPS  files. 

The  result  of  all  this  work  has  been 
the  conversion  of  a  PCX  file,  a  useful 
and  standard  data  format  for  images, 
into  PostScript,  another  useful  and  stan¬ 
dard  format,  with  C  as  the  medium  of 
exchange.  In  the  process,  we’ve  learned 
to  make  efficient  use  of  all  three. 
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Building  Your  Own 

C  Interpreter 

Here’s  the  source  code  for  an  interpreter  of  your  own 


In  this  article,  I  develop  a  C  inter¬ 
preter  that  can  execute  a  subset  of 
K&R  ANSI  C.  The  interpreter  not 
only  is  functional  as  presented,  but 
is  designed  so  that  you  can  easily 
enhance  and  extend  it.  In  fact,  you  can 
even  add  features  not  found  in  ANSI  C 
if  you  choose.  By  the  time  you  finish 
reading  this  article,  you’ll  have  a  C  in¬ 
terpreter  you  can  use  and  enlarge,  and 
you  will  have  gained  considerable  in¬ 
sight  into  the  structure  of  the  C  lan¬ 
guage  itself. 

Although  ANSI  C  has  only  32  key¬ 
words,  it  is  a  rich  and  powerful  lan¬ 
guage.  It  would,  of  course,  take  far 
more  than  a  single  article  to  fully  de¬ 
scribe  and  implement  an  interpreter  for 
the  entire  C  language.  Instead,  this  C 
interpreter  understands  a  fairly  narrow 
subset  of  the  language.  Table  1  lists  the 
features  that  are  implemented  in  it. 

In  order  to  simplify  and  shorten  the 
source  code  to  the  interpreter,  I  have 
imposed  one  small  restriction  on  the  C 
grammar:  The  targets  of  the  if,  while, 
do,  and  for  must  be  blocks  of  code 
surrounded  by  beginning  and  ending 
curly  braces.  You  may  not  use  a  single 
statement.  For  example,  my  interpreter 
will  not  correctly  interpret  code  in  Ex¬ 
ample  1;  instead,  you  must  write  code 
like  that  in  Example  2.  Because  the 
objects  of  the  program  control  state¬ 
ments  are  often  blocks  of  code  any¬ 
way,  this  restriction  does  not  seem  too 
harsh.  (With  a  little  effort,  though,  you 
can  remove  this  restriction.) 


Herb  is  the  author  of  more  than  two 
dozen  computer  books,  with  topics  rang¬ 
ing  from  C  to  Modula-2.  This  article  is 
based  on  his  book  Bom  to  Code  in  C 
(Osborne/McGraw-Hill).  He  can  be 
reached  at  RR  # 1 ,  Box  130,  Mahomet, 
IL  61853- 


Herbert  Schildt 

Reducing  the  Source  Code 
to  its  Components 

To  create  the  C  interpreter,  we  first 
construct  the  expression  evaluator  and 
the  piece  of  code  that  reads  and  ana¬ 
lyzes  expressions,  the  expression  parser. 

There  are  several  different  ways  to 
design  an  expression  parser  for  C.  Many 
commercial  compilers  use  a  table-driven 
parser  that  is  generally  created  by  a 
parser-generator  program.  While  table- 
driven  parsers  are  usually  faster  than 
other  methods,  they  are  hard  to  create 
by  hand.  For  this  C  interpreter  I  will  use 
a  recursive-descent  parser,  which  is  es¬ 
sentially  a  collection  of  mutually  recur¬ 
sive  functions  that  process  an  expres¬ 
sion.  If  the  parser  is  used  in  a  compiler, 
then  its  function  is  to  generate  the 
proper  object  code  that  corresponds 
to  the  source  code.  In  an  interpreter, 
however,  the  object  of  the  parser  is  to 
evaluate  a  given  expression. 


Parameterized  functions  with  local 
variables 
Recursion 
The  //statement 

The  do-while,  while,  and  for  loops 

Integer  and  character  variables 

Global  variables 

Integer  and  character  constants 

String  constants  (limited  implementation) 

The  return  statement,  both  with  and 
without  a  value 

A  limited  number  of  standard  library 
functions. 

These  operators:  +,  *,  /,  %,  <,  >, 

<=,  >=,==,  i=,  unary-,  and  unary +. 

Functions  returning  integers 
Comments 

Table  1:  Features  provided  by  this  C 
interpreter 


Fundamental  to  all  interpreters  (and 
compilers,  for  that  matter)  is  a  special 
function  that  reads  the  source  code 
and  returns  the  next  logical  symbol 
from  it.  For  historical  reasons,  these 
logical  symbols  are  generally  referred 
to  as  tokens,  and  computer  languages 
in  general  (and  C  in  particular)  define 
programs  in  terms  of  tokens.  This  C 
interpreter  categorizes  tokens  as  shown 
in  Table  2.  The  function  that  returns 
tokens  from  the  source  code  for  the  C 
interpreter  is  called  get_token( )  and  is 
shown  in  Listing  One  (page  110),  lines 
313  through  423.  The  get_token(  ^func¬ 
tion  uses  the  global  data  and  enumera¬ 
tion  types  in  Figure  1. 

The  current  location  in  the  source 
code  is  pointed  to  by  prog.  The  p_buf 
pointer  is  unchanged  by  the  interpreter 
and  always  points  to  the  start  of  the 
program  being  interpreted.  The  get_ 
token( )  function  begins  by  skipping 
(continued  on  page  42) 


for(a*0;  a<10;  a=a+l) 
for  (b=0;  b<10;  b=b+l) 
for(c=0;  c<10;  c=c+l) 
puts ("hi") ; 


Example  1:  This  C  interpreter  will  not 
interpret  this  code 


for(a=0;  a<10;  a=a+l)  { 
for (b=0;  b<10;  b=b+l)  { 
for(c=0;  c<10;  c=c+l)  ( 
puts ("hi") ; 

) 

j5  (T 


Example  2:  This  C  interpreter  will  in¬ 
terpret  this  code 
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(continued  from  page  38) 
over  all  white  space,  including  carriage 
returns  and  line  feeds.  Because  no  C 
token  (except  for  a  quoted  string  or 
character  constant)  contains  a  space, 
spaces  must  be  bypassed.  The  get_ 
token( )  function  also  skips  over  com¬ 
ments.  Next,  the  string  representation 
of  each  token  is  placed  into  token,  its 
type  (as  defined  by  the  tokjtypes  enu¬ 
meration)  is  put  into  token_type,  and, 
if  the  token  is  a  keyword,  its  internal 
representation  is  assigned  to  tok via  the 
look_up( )  function  (shown  in  the  full 
parser  listing,  Listing  One).  You  can 
see  by  looking  at  get_token( )  that  it 
converts  C’s  two-character  relational  op¬ 
erators  into  their  corresponding  enu¬ 
meration  value.  Although  not  techni¬ 
cally  necessary,  this  step  makes  the 
parser  easier  to  implement.  Finally,  if 
the  parser  encounters  a  syntax  error,  it 
calls  the  function  sntx_err( )  with  an 
enumerated  value  that  corresponds  to 
the  type  of  error  found.  The  sntx_err( ) 
function  is  also  called  by  other  routines 
in  the  interpreter  whenever  an  error 
occurs.  The  sntx_err( )  function  is 
shown  here  in  Listing  One,  lines  274 
through  311. 

The  entire  code  for  the  C  interpreter 
recursive  descent  parser  is  shown  in 
Listing  One  (PARSER. C),  along  with 
some  necessary  support  functions,  global 
data,  and  data  types.  As  listed,  this  code 
is  designed  to  go  into  its  own  file. 

The  atom( )  function  and  the  func¬ 
tions  that  begin  with  eval_exp  imple¬ 
ment  the  production  rules  for  C  ex¬ 
pressions.  To  verify  this,  you  might 
want  to  mentally  execute  the  parser 
using  a  simple  expression. 

The  atom( )  function  finds  the  value 
of  an  integer  constant  or  variable,  a 
function,  or  a  character  constant.  The 
two  kinds  of  functions  that  may  be 
present  in  the  source  code  are  user- 
defined  or  library.  If  a  user-defined  func¬ 
tion  is  encountered,  its  code  is  exe¬ 
cuted  by  the  interpreter  in  order  to 
determine  its  value.  (The  calling  of  a 
function  will  be  discussed  in  the  next 


Token 

Type 

Includes 

delimiters 

punctuation  and 
operators 

keywords 

keywords 

strings 

quoted  strings 

identifiers 

variable  and  function 
names 

number 

numeric  constant 

block 

{ or} 

Table  2:  The  interpreter’s  token 
categories 


section.)  If  the  function  is  a  library  func¬ 
tion,  however,  then  its  address  is  first 
looked  up  by  the  intemal_func( )  func¬ 
tion  and  is  then  accessed  via  its  inter¬ 
face  function.  The  library  functions  and 
the  addresses  of  their  interface  func¬ 
tions  are  held  in  the  internal_func 
array  in  lines  56  through  73- 

The  C  Interpreter 

The  heart  of  the  C  interpreter  is  devel¬ 
oped  in  this  section.  Before  the  inter¬ 
preter  can  actually  start  executing  a 

The  C  interpreter 
presented  here  was 
designed  with 
transparency  of 
operation  in  mind 


program,  however,  a  few  clerical  tasks 
must  be  performed.  Some  method  must 
be  devised  to  allow  execution  to  begin 
at  the  right  spot,  and  all  global  vari¬ 
ables  must  be  known  and  accounted 
for  before  main( )  begins  executing. 
It  is  important,  though  not  technically 
necessary,  that  the  location  of  each 
function  defined  in  the  program  be 
known  so  that  a  call  to  a  function  can 


be  as  fast  as  possible.  If  this  step  is  not 
performed,  a  lengthy  sequential  search 
of  the  source  code  will  be  needed  to 
find  the  entry  point  to  a  function  each 
time  it  is  called. 

The  solution  to  these  problems  is  the 
interpreter  prescan.  Prescanners  (or  pre¬ 
processors,  as  they  are  sometimes  called, 
though  they  have  little  resemblance  to 
a  C  compiler’s  preprocessor)  are  used 
by  many  commercial  interpreters  re¬ 
gardless  of  what  language  they  are  in¬ 
terpreting.  A  prescanner  reads  the 
source  code  to  the  program  before  it 
is  executed  and  performs  whatever  tasks 
can  be  done  prior  to  execution.  In  this 
C  interpreter,  the  prescanner  performs 
two  important  jobs:  First,  it  finds  and 
records  the  location  of  all  user-defined 
functions  including  main( ).  Second, 
it  finds  and  allocates  space  for  all  global 
variables.  Here,  the  function  that  per¬ 
forms  the  prescan  is  called  prescan( ) 
and  is  shown  in  Listing  Two,  LITTLEC.C 
(see  page  116),  lines  190  through  228. 

Global  variables  are  stored  in  a  global 
variable  table  called  global_vars  by 
decl_global( ),  lines  43  through  50  and 
lines  240  through  253.  The  integer 
gvar_index( line  76)  holds  the  location 
of  the  next  free  element  in  the  array.  The 
location  of  each  user-defined  function 
is  put  into  the  func_table  array,  shown 
in  lines  52  through  55.  The  func_index 
variable  (line  75)  holds  the  index  of  the 
next  free  location  in  the  table. 

The  main( )  function  to  the  C  inter¬ 
preter,  shown  in  lines  92  through  118, 
(continued  on  page  45) 


char  *prog;  T  points  to  current  location  in  source  code  7 
extern  char  ’p_buf ;  T  points  to  start  of  program  buffer  7 

char  token[80);  /*  holds  string  representation  of  token  7 

char  token_type;  /*  contains  the  type  of  token  7 

char  tok;  /*  holds  the  internal  representation  of  token  if  it  is  a  keyword  7 

enum  tokjypes  {DELIMITER,  IDENTIFIER,  NUMBER,  KEYWORD, 
TEMP,  STRING,  BLOCK}; 

enum  double_ops  {LT=1 ,  LE,  GT,  GE,  EQ,  NE}; 

T  These  are  the  constants  used  to  call  sntx_err( )  when  a  syntax  error 
occurs.  Add  more  if  you  like. 

NOTE:  SYNTAX  is  a  generic  error  message  used  when  nothing 
else  seems  appropriate. 

7 

enum  error_msg 

{SYNTAX,  UNBAL_PARENS,  NO  EXP,  EQUALSJEXPECTED, 
NOT_VAR,  PARAM_ERR,  SEMI_EXPECTED, 
UNBAL_BRACES,  FUNCJJNDEF, TYPE_EXPECTED, 
NEST_FUNC,  RET_NOCALL,  PAREN_EXPECTED, 
WHILE_EXPECTED,  QUOTE_EXPECTED,  NOTJEMP, 
TOO_MANY_LVARS} ; 


Figure  1:  The  get_token( )  function  uses  the  global  data  and  enumeration 
types  as  shown  here 
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loads  the  source  code,  initializes  the 
global  variables,  calls  prescan( ),  primes 
the  interpreter  for  the  call  to  main( ), 
and  then  executes  call( R,  which  be¬ 
gins  execution  of  the  program. 

The  interp_block( )  function  is  the 
heart  of  the  interpreter.  This  function 
decides  what  action  to  take  based  upon 
the  next  token  in  the  input  stream.  It  is 
designed  to  interpret  one  block  of  code 
and  then  return.  The  interp_block(  )  func¬ 
tion  is  shown  in  lines  119  through  174. 

Ignoring  calls  to  functions  like  exit( ), 
a  program  ends  when  the  last  curly 
brace  (or  a  return)  in  main(  )  is  encoun¬ 
tered.  It  does  not  necessarily  end  with 
the  last  line  of  source  code.  This  is  one 
reason  that  interp_block(  )  executes  only 
a  block  of  code,  and  not  the  entire 
program.  Another  reason  is  that,  con¬ 
ceptually,  C  consists  of  blocks  of  code. 
Therefore,  interp_block( )  is  called  each 
time  a  new  block  of  code  is  encoun¬ 
tered.  This  includes  both  function  calls 
and  blocks  begun  by  various  C  state¬ 
ments,  such  as  an  t/block.  This  means 
that  the  interpreter  may  call  interp 
_block( R  recursively  in  the  process  of 
executing  a  program. 

When  the  interpreter  encounters  an 
int  or  char  keyword,  it  calls  decl_local(  ) 
to  create  storage  for  a  local  variable. 
Each  time  a  local  variable  is  encoun¬ 
tered,  its  name,  type,  and  value  (in¬ 
itially  zero)  are  pushed  onto  the  stack 
using  local _push(  R.  The  global  vari¬ 
able  Ivartos  indexes  the  stack.  (There 
is  no  corresponding  “pop”  function. 
Instead,  the  local  variable  stack  is  reset 
each  time  a  function  returns.)  The 
decl_local  and  local _pushC  R  functions 
are  shown  in  lines  254  through  353- 

All  function  calls  (except  the  initial 
call  to  main( R)  take  place  through  the 
expression  parser  from  the  atom(  )  func¬ 
tion  by  a  call  to  call( R.  It  is  the  call( ) 
function  that  actually  handles  the  de¬ 
tails  of  calling  a  function.  The  call( ) 
function  is  shown  in  Listing  Two,  lines 
269  through  337,  along  with  two  sup¬ 
port  functions. 


Example  3:  Assigning  values  to  a 
variable 


Let’s  return  to  the  expression  parser 
for  a  moment.  When  an  assignment 
statement  is  encountered,  the  value  of 
the  right  side  of  the  expression  is  com¬ 
puted  and  assigned  to  the  variable  on 
the  left  using  a  call  to  assignC ).  Given 
a  program  like  the  one  in  Example  3, 
how  does  the  assign( R  function  know 
which  variable  is  being  assigned  a  value 
in  each  assignment?  The  answer  is  sim¬ 
ple:  First,  in  C,  local  variables  take  pri¬ 
ority  over  global  variables  of  the  same 
name.  Second,  local  variables  are  not 
known  outside  their  own  function.  To 
see  how  we  can  use  these  rules  to 
resolve  the  above  assignments,  exam¬ 
ine  the  assignC )  function  shown  in 
lines  369  through  388. 

Executing  Statements  and  Loops 

Now  that  the  basic  structure  of  the  C 
interpreter  is  in  place,  it  is  time  to  add 
some  control  statements.  Each  time  a 
keyword  statement  is  encountered  in¬ 
side  of  interp_block( R,  an  appropriate 
function  is  called,  which  processes  that 
statement.  One  of  the  easiest  is  the  if. 
The  if  statement  is  processed  by  exec_ 
if( ),  shown  in  lines  419  through  438. 

Like  the  if  it  is  easy  to  interpret  a 
while  loop.  The  function  that  actually 
performs  this  task  is  called  exec_while( ) 
and  is  shown  in  lines  439  through  454. 

A  do/while  loop  is  processed  much 
like  the  while.  When  interp_block( ) 
encounters  a  do  statement,  it  calls  exec_ 
do( R,  shown  in  lines  455  through  469. 

The  main  difference  between  the  do/ 
while  and  the  while  loops  is  that  the 
do/while  always  executes  its  block  of 
code  at  least  once  because  the  condi¬ 
tional  expression  is  at  the  bottom  of 
the  loop.  Therefore,  ex ec_do( )  first 
saves  the  location  of  the  top  of  the  loop 
into  temp  and  then  calls  interp_block( ), 
recursively,  to  interpret  the  block  of 

This  interpreter  is 
designed  so  that  you 
can  easily  enhance  and 
extend  it 


code  associated  with  the  loop.  When 
interp_block( )  returns,  the  correspond¬ 
ing  while  is  retrieved  and  the  condi¬ 
tional  expression  is  evaluated.  If  the 
condition  is  true,  prog  is  reset  to  the 
top  of  the  loop;  otherwise,  execution 
continues. 


The  interpretation  of  the  for  loop 
poses  a  more  difficult  challenge  than 
the  other  constructs.  This  is  partly  be¬ 
cause  the  structure  of  the  C  for  is  defi¬ 
nitely  designed  with  compilation  in 
mind.  The  main  trouble  is  that  the  con¬ 
ditional  expression  of  the  for  must  be 
checked  at  the  top  of  the  loop,  but  the 
increment  portion  occurs  at  the  bottom 
of  the  loop.  Therefore,  even  though 
these  two  pieces  of  the  for  loop  occur 
next  to  each  other  in  the  source  code, 
their  interpretation  is  separated  by  the 
block  of  code  being  iterated.  With  a 
little  work,  however,  the  for  can  be 
correctly  interpreted. 

When  interpjblockC  Rencounters  a  for 
statement,  exec_  for(  Ris  called.  This  func¬ 
tion  is  shown  in  lines  482  through  514. 

Library  Functions 

Because  the  C  programs  executed  by 
the  interpreter  are  never  compiled  and 
linked,  any  library  routines  they  use 
must  be  handled  directly  by  the  inter¬ 
preter.  The  best  way  to  do  this  is  to 
create  an  interface  function,  which  the 
C  interpreter  calls  when  a  library  func¬ 
tion  is  encountered.  This  interface  func¬ 
tion  sets  up  the  call  to  the  library  func¬ 
tion  and  handles  any  return  values. 

Due  to  space  limitations,  the  inter¬ 
preter  contains  only  five  library  func¬ 
tions:  getcheC  ),putch(  ),puts(  ),print(  R, 
and  getnumC ).  Of  these,  only  puts(  ) 
is  described  by  the  ANSI  standard,  and 
it  outputs  a  string  to  the  screen.  The 
putch(  R  function  is  a  common  exten¬ 
sion  to  C  for  interactive  environments. 
It  waits  for  and  returns  a  key  struck  at 
the  keyboard.  Unlike  most  implemen¬ 
tations  of  putcharC R  it  does  not  line- 
buffer  input.  This  function  is  found  in 
many  compilers,  such  as  Turbo  C, 
QuickC,  and  Lattice  C.  The  putchC )  is 
also  defined  by  many  compilers  de¬ 
signed  for  use  in  an  interactive  envi¬ 
ronment.  It  outputs  a  single  character 
argument  to  the  console  and  does  not 
buffer  output. 

The  functions  getnumC  Rand  printC  R 
are  my  own  creations.  The  getnumC ) 
function  returns  the  integer  equivalent 
of  a  number  entered  at  the  keyboard. 
The  printC )  function  is  a  handy  func¬ 
tion  that  can  output  either  a  string  or 
an  integer  argument  to  the  screen.  It  is 
an  example  of  a  function  that  would 
be  difficult  to  implement  in  a  compiled 
environment,  but  is  easy  to  create  for 
an  interpreted  one.  The  five  library  func¬ 
tions  are  shown  in  Table  3  in  their 
prototype  forms.  The  C  interpreter  li¬ 
brary  routines  are  listed  in  Listing  Three 
(LCLIB.C),  page  120. 

To  add  additional  library  functions, 
first  enter  their  names  and  addresses 
of  their  interface  functions  into  the  in- 
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ternal Junc( )  array.  Next,  following 
the  lead  of  the  functions  shown  here, 
create  appropriate  interface  functions. 

Compiling  and  Linking  the  C  Interpreter 

Once  you  have  compiled  all  three  files 
that  make  up  this  interpreter,  compile 
and  link  them  together.  If  you  use  Turbo 
C,  you  can  use  a  sequence  like  this: 

tcc  -c  parser.c 

tcc  -c  lclib.c 

tcc  littlec.c  parser.obj  lclib.obj 
If  you  use  Microsoft  C,  use  this  sequence: 

cl  -c  parser.c 

cl  -c  lclib.c 

cl  littlec.c  parser.obj  lclib.obj 

If  you  use  a  different  C  compiler,  fol¬ 
low  the  instructions  that  come  with  it. 

The  program  in  Listing  Four  (page 
121)  demonstrates  the  various  features 
of  my  C. 

Improving  and  Expanding 
the  C  Interpreter 

The  C  interpreter  presented  here  was 
designed  with  transparency  of  opera¬ 
tion  in  mind.  The  goal  was  to  develop 
an  interpreter  that  could  be  easily  un¬ 
derstood  with  the  least  amount  of  ef¬ 
fort,  and  to  design  it  so  that  it  could  be 
easily  expanded.  As  such,  the  interpreter 
is  not  particularly  fast  or  efficient.  The 
basic  structure  of  the  interpreter  is  cor¬ 
rect,  however,  and  you  can  increase  its 
speed  of  execution  in  the  following  ways. 

One  potential  improvement  is  with 
the  lookup  routines  for  variables  and 
functions.  Even  if  you  convert  these 
items  into  integer  tokens,  the  current 
approach  to  searching  for  them  relies 
upon  a  sequential  search.  You  could, 
however,  substitute  some  other,  faster 
method,  such  as  a  binary  tree  or  some 
sort  of  hashing  method. 

Two  general  areas  in  which  you  can 
expand  and  enhance  the  C  interpreter 
are  C  features  and  ancillary  features. 
Among  the  C  statements  you  can  add 
to  the  interpreter  are  additional  action 
statements,  such  as  the  switch,  the  goto, 
and  the  break  and  continue  statements. 


Another  type  of  C  statement  you  can 
add  is  new  data  types.  The  interpreter 
already  contains  the  basic  hooks  for 
additional  data  types.  For  example,  the 
var_type  structure  already  contains  a 
field  for  the  type  of  variable.  To  add 
other  elementary  types  (that  is,  float, 
double,  long),  increase  the  size  of  the 
value  field  to  the  size  of  the  largest 
element  you  wish  to  hold. 

Supporting  pointers  is  no  harder  than 
supporting  any  other  data  type;  how¬ 
ever,  you  will  need  to  add  support  for 
the  pointer  operators  to  the  expression 
parser.  This  will  involve  some  look¬ 
ahead.  Once  you  have  implemented 
pointers,  arrays  will  be  easy.  The  space 
of  an  array  should  be  allocated  dy¬ 
namically  using  malloc(  ),  and  a  pointer 
to  the  array  should  be  stored  in  the 
value  field  of  var_type. 

The  addition  of  structures  and 
unions  poses  a  more  difficult  problem. 
The  easiest  way  to  handle  them  is  to 
use  malloc(  tto  allocate  space  for  them, 
and  to  use  a  pointer  to  the  object  in  the 
value  field  of  the  var_type  structure. 
(You  will  also  need  special  code  to 
handle  the  passing  of  structures  and 
unions  as  parameters.)  To  handle  dif¬ 
ferent  return  types  for  functions,  add  a 
type  field  to  the  func_type  structure, 
which  defines  what  type  of  data  a  func¬ 
tion  returns. 
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C  Multidimensional 
Arrays  at  Run  Time 

Organizing  the  heap  for  run-time  multidimensional  arrays 
isn’t  easy,  but  it  is  possible 


Paul  Anderson 


When  you  declare  arrays  in 
C,  their  sizes  remain  fixed. 
You  have  to  decide  before 
your  program  runs  how 
large  an  array  will  be,  re¬ 
gardless  of  whether  you  declare  it  as 
automatic  or  static.  What  about  declar¬ 
ing  arrays  at  run  time?  In  this  case,  you 
need  to  call  the  C  library  routine  mal- 
loc( )  or  calloc( )  to  build  dynamic  ar¬ 
rays  from  memory  (called  the  heap). 
This  approach  eliminates  anticipating 
array  bounds  at  compile  time  and  makes 
programs  allocate  only  as  much  mem¬ 
ory  as  they  need. 

One-dimensional  arrays  are  easy  be¬ 
cause  a  call  to  malloc( )  or  calloc( ) 
returns  a  pointer  to  a  chunk  of  heap 
memory  that  you  may  use  as  a  one¬ 
dimensional  array.  You  cast  the  heap 
pointer  to  an  appropriate  data  type  and 
use  either  array  notation  or  pointers  to 
reference  the  allocated  elements. 

Multidimensional  arrays,  however,  are 
more  difficult.  There’s  no  standard  C 
library  routine  that  sets  up  the  heap  so 
that  you  may  use  it  as  a  multidimen¬ 
sional  array.  To  the  heap  manager,  heap 
storage  is  merely  a  block  of  consecu¬ 
tive  bytes  with  no  notion  of  rows,  col¬ 
umns,  and  so  on.  You  need  a  way  to 
organize  the  heap  for  run-time  multidi¬ 
mensional  arrays.  Moreover,  it  would 
be  nice  to  retain  the  concepts  of  rows 
and  columns  so  that  heap  memory  ap¬ 
pears  like  a  multidimensional  array  to 
your  programs. 


Paul  is  a  consultant  and  co-author  of 
Advanced  C  Tips  and  Techniques,  pub¬ 
lished  by  Howard  W.  Sams,  from  which 
this  article  was  adapted.  Paul  can  be 
reached  at  1212  Eolus  Ave.,  Leucadia, 
CA  92024. 


In  this  article,  I’ll  discuss  C  functions 
that  create  run-time  two-dimensional 
and  three-dimensional  arrays  of  any 
data  type  (including  arrays  of  struc¬ 
tures  and  unions).  I’ll  also  discuss  a 
technique  to  mimic  the  subroutine  call¬ 
ing  conventions  of  Basic  and  Fortran 
with  two-dimensional  arrays.  Along  the 
way,  I’ll  review  two-dimensional  and 
three-dimensional  arrays  and  the  rela¬ 
tionships  between  pointer  expressions 
and  array  references.  This  should  give 
you  the  information  you  need  to  im¬ 
plement  these  concepts  in  your  own  C 
programs. 

The  Basic  Rule 

Let’s  start  with  how  C  views  arrays.  For 
a  one-dimensional  array  of  any  data 
type,  the  following  equivalence  exists 
between  an  array  reference  and  a 
pointer  expression: 

a[i]  =  (*(a  +  i)) 

I  call  this  the  basic  rule  because  it  ap¬ 
plies  to  many  complicated  pointer  ex¬ 
pressions,  as  you  will  see  later  on.  Note 
that  you  may  omit  the  outer  parenthe¬ 
ses  most  of  the  time  except  for  expres¬ 
sions  where  C’s  precedence  rules  re¬ 
quire  them.  The  basic  rule  helps  ex¬ 
plain  simple  relations  such  as  &a[i]  =  a 


+  i,  where  I  apply  C’s  address  operator 
(&)  to  both  sides  of  the  relation  and  use 
C’s  precedence  rules  to  simplify  the 
result.  Using  the  same  method,  the  ba¬ 
sic  rule  helps  derive  the  relations  a[0] 
=  *< a  and  &a[0]  =  a. 

One  of  the  surprising  things  about 
C  arrays  is  that  array  references  don’t 
really  exist.  If  you  don’t  believe  this,  try 
running  the  portable  program  in  Exam¬ 
ple  1,  which  compiles  without  error. 
You’ll  discover  the  program  displays  5 
(the  sixth  element  of  the  array)  four 
times.  Despite  the  fact  that  the  last  two 
array  references  must  be  the  ultimate  in 
job  security,  C  translates  the  array  ref¬ 
erences  to  pointer  expressions  accord¬ 
ing  to  the  basic  rule.  Although  no  one 
(hopefully)  would  use  expressions  such 
as  these  in  programs,  they’re  conclusive 
proof  that  C  handles  arrays  differently 
from  the  way  other  languages  do. 

Now  let’s  move  on  to  multidimen¬ 
sional  arrays.  Two-dimensional  arrays 
are  easy  because  you  can  visualize  them 
as  grids  with  rows  and  columns.  (By 
the  way,  I’ll  use  the  term  grid  for  a 
two-dimensional  array  from  now  on. 
Think  of  it  as  a  checkerboard  in  which 
rows  and  columns  locate  unique  ele¬ 
ments.)  In  C,  the  declaration  double 
mintf 31151  allocates  storage  for  15  dou¬ 
bles,  arranged  as  3  rows  by  5  columns. 


linclude  <stdio.h> 
main  ( ) 

1 

static  char  a [ ]  =  "0123456789"; 
int  i  =  5; 

printf("%c  %c  %c  %c\n",  a[i],  a[5],  i { a] ,  5 [a] ) ; 


1 


Example  1:  A  portable  program  that  compiles  without  error 
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Figure  1  shows  how  to  visualize  the 
array  mint.  Array  references  have  the 
format  mint[row][col].  Once  again,  C 
allows  you  to  use  expressions  with 
pointer  indirection  and  array  reference 
notation  that  are  not  immediately  obvi¬ 
ous.  mintll],  for  instance,  is  a  pointer 
to  a  double  located  in  the  first  column 
of  the  second  row.  Likewise,  * mint  is 
a  pointer  to  a  double  in  the  first  row 
and  first  column.  The  name  of  the  array 
(mint)  is  a  pointer  to  an  array  of  five 
doubles,  located  in  the  first  row.  The 
expression  mint  +  1,  therefore,  is  a 
pointer  to  the  array  of  five  doubles  in 
the  second  row. 

The  basic  rule  comes  in  handy  for 
deciphering  two-dimensional  array  ref¬ 
erences.  The  notation  mint[l][2],  for 
example,  is  equivalent  to  '(mintll]  + 
2),  according  to  the  following  derivation. 
Let: 

p  =  mintll] 

Then: 

mint[l][2]  =  p[2] 

Marking  mintll]  as  p  makes  it  easier  to 
apply  the  basic  rule: 


p[2]  =  (*(p  +  2)  ) 


[01  [1]  [2]  [3]  [4] 

mint[0] 

mint[1] 

mint[2] 

Figure  1:  double  mint[3H5] 
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[01  [11  [2]  [3] 
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[0] 

[1] 

[2] 

visionfl:] 

Figure  2:  double  vision[2][3][5] 


Now  substitute  mintll]  for  p  in  both 
sides  of  the  previous  expression: 

mint[l][2]  =  (*(mint[l]  +  2)  ) 
mint[l][2]  =  *(mint[l]  +  2) 

(Here  I  drop  the  outer  parentheses  be¬ 
cause  they’re  unnecessary.) 

mint[l][2]  '\s  also  equivalent  to  ( '(mint 
+  1))[2],  although  this  is  considerably 
more  obscure.  Here  are  the  substitu¬ 
tions  with  the  basic  rule: 

mintll]  =  (*(mint  +  1)  ) 
mint[l][2]  =  (‘(mint  +  1)  )[2] 

This  time,  however,  you  cannot  remove 
the  outer  parentheses  because  C’s  prece¬ 
dence  rules  require  them  (f  7has  higher 
precedence  than  *).  Without  the  paren¬ 
theses,  the  expression  '(mint  +  1)[2] 
evaluates  to  "(mint  +  3)-  (Can  you 
derive  this  with  the  basic  rule?)  Both 
expressions  are  wrong  because  they 
locate  an  element  outside  the  bounds 
of  the  mint  array. 

Three-dimensional  arrays  add  another 
level  to  the  same  concept.  The  C  decla¬ 
ration  double  vision[2][3][5],  for  exam¬ 
ple,  allocates  storage  for  30  doubles, 
arranged  as  two  grids  of  3  rows  and  5 
columns.  Think  of  it  as  a  stack  of  two- 
dimensional  arrays  on  top  of  each  other. 
Figure  2  shows  how  to  visualize  the 
array  vision.  Array  references  have  the 
format  visionlgridllrowllcol],  C  permits 
pointer  expressions  for  arrays  in  three 
dimensions  as  well  as  it  does  for  two 
dimensions,  but  their  meanings  are  dif¬ 
ferent.  visionfl ]  is  now  a  pointer  to 


double  mint[3][5] 


an  array  of  five  doubles  located  at  the 
first  row  of  the  second  grid.  Likewise, 
vision[l][l]  is  a  pointer  to  a  double  in 
the  second  grid,  second  row,  first  col¬ 
umn.  The  name  of  the  array  (vision)  is  a 
pointer  to  a  3  by  5  array  of  doubles  (the 
first  grid),  and  vision  +  1  is  a  pointer 
to  the  second  grid.  I’ll  return  to  these 
types  of  pointer  expressions  when  I 
apply  them  later  on  to  run-time  arrays. 

Storage  Map  Equations 

Viewing  multidimensional  arrays  as 
grids  with  rows  and  columns  is  for  our 
benefit.  Unfortunately,  the  compiler  has 
a  harder  job  than  we  do  making  the 
connection  between  arrays  and  grids. 
Physical  memory  is  accessed  as  a  one¬ 
dimensional  array,  so  the  compiler  maps 
multidimensional  arrays  to  blocks  of 
memory.  Each  time  you  reference  a 
multidimensional  array  element,  the  com¬ 
piler  calculates  an  address  in  the  mem¬ 
ory  block. 

Figure  3  shows  the  memory  layout 
for  the  declaration  double  mint[3][5l  C 
stores  two-dimensional  arrays  in  mem¬ 
ory  by  rows  (this  is  called  row  major 
form).  The  second  subscript  varies  faster 
than  the  first  one.  Therefore,  mintlO] 
points  to  the  first  double  in  the  first 
row,  mintll]  points  to  the  first  double 
in  the  second  row,  and  so  forth.  The 
compiler  calculates  the  address  for  an 
array  reference  by  locating  the  appro¬ 
priate  row  and  accessing  the  correct 
column  within  that  row. 

When  you  use  the  array  reference 
mint! i][ j]  in  a  C  program,  the  compiler 
implements  the  following  pointer  ex¬ 
pression:  *(&mint[0][0]  +5*i  +j).  Sub¬ 
script  i  is  the  row  number,  subscript  j 
is  the  column  number,  and  &mint[0][0] 
is  the  base  address  of  the  array.  I  call 
this  above  expression  a  storage  map 
equation.  Every  multidimensional  ar¬ 
ray  declaration  in  a  program  has  one. 
This  particular  storage  map  equation 
is  for  the  two-dimensional  array  double 
mint[3][5l 

Note  that  the  number  of  rows  in  a 
two-dimensional  array  declaration  is  not 
used  in  the  storage  map  equation.  This 
helps  explain  why  the  declarations  in 
Example  2  are  legal  in  C. 

To  generate  the  storage  map  equa¬ 
tion  for  a[i][j]  inside  f( ),  the  compiler 
requires  the  number  of  columns  but 
not  the  number  of  rows.  Likewise,  the 
extern  statement  provides  the  compiler 
with  the  necessary  information  to  ref¬ 
erence  mint[i][j],  even  though  the  array 
is  declared  in  another  file. 

Storage  map  equations  apply  to  three- 
dimensional  arrays  as  well.  Figure  4 
shows  the  memory  layout  for  the  dec¬ 
laration  double  vision[2][3][5].  The  sec¬ 
ond  3  by  3  grid  follows  the  first.  Mem- 
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ory  layout  within  each  grid  has  the 
same  organization  as  in  the  two-di¬ 
mensional  example. 

When  you  use  the  array  reference 
vision[i][jj[k],  the  C  compiler  uses  the 
following  storage  map  equation:  *(&vi- 
sion[0][0][0]  +  15  '  i  +  5  *  j  +  k).  Sub¬ 
scripts  i,  j,  and  k  are  the  grids,  rows, 
and  columns,  respectively,  and  Gvision 
[0][0][0] is  the  base  address  of  the  array. 
The  number  15  is  the  product  of  the 
number  of  rows  (3)  and  the  number  of 
columns  (5).  The  storage  map  equation 
for  a  three-dimensional  array  reference 
does  not  use  the  number  of  grids. 

Why  be  concerned  with  storage  map 
equations,  anyway?  It  turns  out  that 
many  C  compilers  generate  multiply 
instructions  in  assembly  code  for  mul¬ 
tidimensional  array  references.  Depend¬ 
ing  on  the  compiler  you  use,  this  may 
affect  performance  of  a  running  C  pro¬ 
gram.  Suppose,  for  example,  you  de¬ 
clare  mint  as  follows:  double  mint[3]l4] 
The  storage  map  equation  for  mintlillj] 
is  now  *(&mint[0][0]  +  4  *  i  +  j).  Some 
compilers  generate  shift  instructions  in 
place  of  multiplies.  Multiplying  an  inte¬ 
ger  by  a  power  of  2,  for  instance,  is  the 
same  as  shifting  the  bits  left  by  the 
value  of  the  power.  In  this  example,  a 
compiler  could  shift  i  left  by  2  bits 
instead  of  multiplying  it  by  4.  If  the 
number  of  columns  is  not  a  power  of 
2  (like  our  original  declaration  of 
mint[3Jl5D ,  some  compilers  may  even 
generate  a  set  of  “shift-and-add”  in¬ 
structions.  In  other  words,  shifting  i 
left  by  2  bits  and  adding  i  is  the  same 
as  multiplying  i  by  5.  In  the  following 
sections,  I’ll  create  two-  and  three- 
dimensional  arrays  that  don’t  use  stor¬ 
age  map  equations  to  access  array  ele¬ 
ments.  In  many  cases,  this  improves  a 
program’s  performance. 

Two-Dimensional  Arrays  at  Run  Time 

Now  let’s  put  all  this  information  to  work 
and  create  a  function  that  allocates  two- 
dimensional  arrays  at  run  time.  Sup¬ 
pose  you  need  a  2  by  3  array  of  integers 


main ( ) 

( 

extern  double  mint[][5]; 

/*  OK  */ 

.  .  .  mint [i] [ j]  .  .  . 

f (mint) ; 

} 

f  (a) 

double  a [ ] [5] ; 

/*  OK  */ 

.  .  .  a  t i ]  [  j]  .  .  . 

1 

Example  2:  The  number  of  rows  in  a 
two-dimensional  array  declaration  is 
not  used  in  the  storage  map  equation 


in  a  program.  Instead  of  declaring  int 
a[2][3l ,  let’s  allocate  memory  from  the 
heap  with  the  statements  in  Example  3- 

Figure  5  shows  the  memory  arrange¬ 
ment.  There  are  two  pointers  to  heap 
storage.  The  first  pointer  (p)  points  to 
the  array  of  data  (six  integers).  The 
second  pointer  ( a )  points  to  a  pointer 
array  containing  the  addresses  of  the 
rows  of  the  data  array.  Note  that  p  is  a 
pointer  to  an  int  and  a  is  a  pointer  to 
a  pointer  to  an  int.  I  use  calloc( )  to 
zero  fill  the  data  array  and  mallocf )  to 
allocate  heap  storage  for  the  row  array. 

With  the  pointer  array  a ,  you  may 
now  use  two-dimensional  array  refer¬ 
ences  in  a  program.  a[l][2],  for  instance, 
refers  to  the  last  data  item,  or  the  third 
column  of  the  second  row  of  the  two- 
dimensional  array.  From  the  basic  rule, 
it’s  as  if  you  typed  fall]  +2).  However, 
all]  is  now  a  pointer  to  the  first  integer 
in  the  second  row,  and  all]  +2  is  a 
pointer  to  the  third  column  in  the  same 
row.  The  compiler  uses  pointer  indi¬ 
rection  in  place  of  a  storage  map  equa¬ 
tion  to  access  array  elements. 

Listing  One,  page  124,  contains  the 
C  source  code  for  two  functions  based 
on  this  technique.  Function  dim2(  )  cre¬ 
ates  two-dimensional  arrays  of  any  data 
type  at  run  time  and  function  free2( ) 
frees  them.  Example  4  shows  how  to 
create  a  3  by  5  array  of  integers  and  a 
4  by  6  array  of  structures.  The  state¬ 
ments  free2( a)  and  free2(s)  release  the 
heap  memory  allocated  for  each  array. 

Function  dim2( .)  allocates  heap  mem¬ 
ory  for  the  row  pointer  array  (pointed 
to  by  prow)  and  the  data  array  (pointed 
to  by  pdata).  The /orloop  connects  the 
row  pointer  array  to  the  data  array. 
Function  free2( )  makes  two  calls  to 
free()  to  release  heap  memory.  The 
first  call  frees  the  data  array  and  the 
second  call  releases  the  row  pointer 
array.  Note  that  the  order  for  the  calls 
to  free(  )  is  significant! 


Figure  5:  Run-time  allocation 
for  al 21131 


vision 

[0][0](0] 

- vision[0], 

[0][0][1] 

[0][0][2] 

[0][0][3] 

[0][0][4] 

vision[Q][0] 

[0][1][0] 

-«• - -vision[0][1] 

[0][1][1] 
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[0][1][4] 
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[0][2][0] 

**— — vision[0][2] 

[0][2][1] 
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— 

[0][2][4] 

[1][0][0] 

-M- — vision[1], 

— 

^  vision[1][0] 

Figure  4:  Memory  block  for  double 
visionf2]f3Jf5J 


Example  3-'  Allocating  memory  from  the  heap 


Example  4:  Creating  two-dimensional  arrays  of  integers  and  structures 
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Three-Dimensional  Arrays  at  Run  Time 

Three-dimensional  arrays  at  run  time 
extend  the  same  concepts.  Implement¬ 
ing  the  compile  time  declaration  of  int 
a[2][3][2],  for  instance,  requires  two 
pointer  arrays  in  addition  to  the  data 


array.  One  pointer  array  contains  point¬ 
ers  to  the  rows  of  heap  data  and  the 
other  one  contains  pointers  to  the  grids. 
Figure  6  shows  the  memory  arrange¬ 
ment.  Pointer  a  points  to  the  grid  pointer 


array,  p2  points  to  the  row  pointer  ar¬ 
ray,  and  p  points  to  the  data.  Once  you 
initialize  the  grid  and  row  pointer  ar¬ 
rays,  you  access  the  data  with  a.  Here 
are  the  declarations  for  the  three  point¬ 
ers:  int  ma,  **p2,  and  *p.  Note  that 
three-dimensional  array  references  with 
a  use  pointers  with  triple  indirection. 
The  array  reference  al0][2][l],  for  exam¬ 
ple,  becomes  *(*(*a  +  2)  +  1),  accord¬ 
ing  to  the  basic  rule.  As  with  the 
two-dimensional  technique,  three-dimen¬ 
sional  array  references  use  pointer  in¬ 
direction  in  place  of  a  storage  map  equa¬ 
tion  with  multiplies  or  shifts  and  adds. 

Listing  Two,  page  124,  contains  the 
C  source  code  for  two  functions  based 
on  the  three-dimensional  technique. 
Function  dim3( )  creates  three-dimen¬ 
sional  arrays  of  any  data  type  at  run 
time  and  free3( )  frees  them.  Example 
5  shows  how  to  create  a  3  by  4  by  5 
array  of  integers  and  a  4  by  6  by  8  array 
of  structures.  Function  calls  free3(a) 
and  free3(s)  release  the  heap  memory 
allocated  for  each  array. 

Function  dim3( ^allocates  heap  mem¬ 
ory  for  the  grid  pointer  array  (pointed 
to  by  pgrid),  the  row  pointer  array 
(pointed  to  by  prow),  and  the  data  ar¬ 
ray  (pointed  to  by  pdata).  Two  for 
loops  connect  the  grid  pointer  array  to 
the  row  pointer  array  and  to  the  data 
array.  Function  free3()  makes  three 
calls  to  free(  )  to  release  heap  memory 
for  the  data  array,  the  row  pointer  array, 
and  the  grid  pointer  array,  respectively. 

Function  Calling  Conventions 

Languages  such  as  Fortran  and  Basic 
allow  you  to  pass  different-size  multi¬ 
dimensional  arrays  as  arguments  to  the 
same  function  and  use  array  notation 
to  reference  elements.  In  Fortran,  for 
example,  the  statements: 

SUBROUTINE  FUNC(A,  M,  N) 

DIMENSION  A(M,  N) 

END 

allow  a  subroutine  called  FUNCC )  to 
access  a  two-dimensional  array  called 
A  with  run-time  values  for  M  rows  and 
Af  columns.  Programs  call  FUNCC  j  with 
different-size  arrays.  Fortran  libraries 
use  subroutines  such  as  FUNCC )  to 
invert  matrices  or  calculate  mathemati¬ 
cal  items,  such  as  determinants  and 
eigenvalues.  This  convention  is  useful 
because  subroutines  may  reference  ele¬ 
ments  by  rows  and  columns. 

C  doesn’t  provide  such  a  built-in  fea¬ 
ture.  Consider  what  happens,  for  ex¬ 
ample,  when  you  pass  the  address  of 
a  multidimensional  array  to  a  function. 
Inside  the  function,  the  compiler  uses 


Figure  6:  Run-time  allocation  for  a[2][3H2] 


int  ***a;  /*  3D  array  of  integers  */ 

struct  something  ***s;  /*  3D  array  of  structures  */ 

a  ■  (int  ***)  dim3(3,  4,  5,  sizeof (int) ) ; 

s  =  (struct  something  ***)  dim3(4,  6,  8,  sizeof  (struct  something)); 


Example  5:  Creating  three-dimensional  arrays  of  integers  and  of  structures 


funcfdata,  5,  9); 

Inside  func(),  you  have  the  following: 

func(a,  rows,  cols) 
int  a[][9J; 
int  rows,  cols; 

( 

register  int  i,  j; 

for  (i  =  0;  i  <  rows;  i++) 
for  (j  -  0;  j  <  cols;  j++) 

.  .  .  a  I i] (jj  .  .  .  /*  array  references  OK  */ 

)  _ 

Example  6:  Passing  the  address  of  a  two-dimensional  array 


func(a,  rows,  cols) 
int  *a; 

int  rows,  cols; 

{ 

register  int  *p  »  a, 

*end  =  a  +  row  *  cols; 

while  (p  <  end)  ( 

.  .  .  *p++  .  .  . 

> 

) 

/*  Can't  use  a(i] [j]  references  */ 

Example  7:  The  effect  of passing  the  first  address  of  an  element  of  a 
two-dimensional  array 
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a  storage  map  equation  with  fixed  sizes. 
To  illustrate,  suppose  you  declare  the 
following  two-dimensional  array  of  in¬ 
tegers:  int  data[5][91. 

The  statements  in  Example  6  call  a  C 
function,  func(  ),  to  pass  the  address  of 
the  two-dimensional  array  along  with 
the  number  of  rows  and  columns.  The 
compiler  requires  9  in  the  declaration  for 
a  to  properly  address  elements  of  the 
array  with  the  storage  map  equation. 

Suppose  you  have  another  two- 
dimensional  array  called  int  moredata 
1 4][10 1;  You  can’t  use  func( )  to  access 
data  in  this  array.  The  function  call 
func(more  data,  4,  10)  won’t  work 
because  func( )  is  compiled  with  the 
number  of  columns  set  to  9  and  not  10. 
Attempts  to  use  it  make  func( )  refer¬ 
ence  memory  incorrectly. 

Another  alternative  is  to  pass  the  ad¬ 
dress  of  the  first  element  of  the  two- 
dimensional  array.  The  statements: 

func(&data[0][0],  5,  9); 

func(&moredata[0][0],  4,  10); 

make  func( )  access  the  two-dimen¬ 
sional  arrays  as  a  one-dimensional  ar¬ 
ray.  The  code  inside  func( )  changes, 
however.  Now  you  have  the  code 
shown  in  Example  7. 

Here,  parameter  a  is  a  pointer  to  an 
integer  (previously,  it  was  a  pointer  to 


an  array  of  integers).  This  allows  you 
to  use  compact  pointer  expressions  such 
as  *p  ++  to  access  memory  as  a  series 
of  rows'cols  integers.  Although  this  is 
relatively  fast,  the  concept  of  rows  and 
columns  disappears.  Functions  that  com¬ 
pute  matrix  inversions  and  determinants 
need  this  information,  though. 

In  situations  such  as  this,  we’d  like 
to  have  C  behave  like  Fortran  or  Basic. 
This  would  help  us  translate  Fortran 
and  Basic  subroutines  to  C  more  easily. 
Let’s  apply  the  previous  techniques  to 
solve  this  problem. 

Suppose  you  want  to  pass  the  ad¬ 
dress  of  different-sized,  two-dimensional 
arrays  to  a  function  that  calculates  a 
mathematical  quantity  called  a  deter¬ 
minant.  The  details  of  how  you  calcu¬ 
late  determinants  do  not  concern  us 
here,  but  this  problem  serves  as  a  good 
example  of  an  algorithm  that  requires 
rows  and  columns  for  the  calculation. 
Listing  Three,  page  124,  is  a  C  program 
that  calculates  determinants  for  two- 
dimensional  arrays  of  doubles. 

Function  det()c alls  sdim2(  )  to  con¬ 
struct  pointer  arrays  to  the  data  using 
the  two-dimensional  technique  pre¬ 
sented  earlier.  Function  sdim2( )  is  simi¬ 
lar  to  dim2( ),  except  that  it  doesn’t 
have  to  create  the  data  array.  Instead, 
it  allocates  heap  memory  for  the  row 


pointer  array,  connects  it  to  the  data 
array  (pointed  to  by  pdata)  and  returns 
the  heap  memory  address.  This  allows 
the  det( )  function  to  access  the  array 
elements  of  the  different  size  arrays 
passed  to  it  using  array  notation  with 
rows  and  columns.  Before  det( )  re¬ 
turns,  it  calls  free( )  to  release  heap 
memory  for  the  pointer  array. 

Performance  Pointers 

What  about  performance  issues?  The 
techniques  I've  shown  you  for  run¬ 
time  multidimensional  arrays  substitute 
pointer  indirections  for  storage  map 
equations.  (Remember,  storage  map 
equations  typically  generate  integer  mul¬ 
tiplies  or  shifts  and  adds  in  assembly 
code.)  I’ve  benchmarked  these  programs 
and  others  using  Microsoft’s  C  com¬ 
piler  (under  DOS  and  Xenix  for  286 
and  386  machines)  and  discovered  that 
pointer  indirections  are  no  worse  in 
execution  time  than  integer  multiplies 
(and  often  execute  faster).  In  the  two- 
dimensional  case,  the  overhead  of  allo¬ 
cating  heap  memory  for  the  row  pointer 
array  isn’t  too  bad,  but  remember  that 
three-dimensional  arrays  require  two 
pointer  arrays.  This  approach  uses  more 
heap  memory  and  can  take  more  time 
to  set  up.  It’s  also  possible  to  eliminate 
function  call  overhead  by  using  mac¬ 
ros  to  generate  the  arrays  (the  solu¬ 
tions  are  in  the  bibliography).  Ultimately, 
you’ll  have  to  judge  whether  the  over¬ 
head  of  setting  up  run-time  multidi¬ 
mensional  arrays  is  worth  the  effort  for 
your  application. 
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Randall  Merilatt 


A  gas  is  defined  as  a  substance 
capable  of  expanding  to  com¬ 
pletely  fill  a  container  and  take 
on  the  shape  of  the  container. 
When  you  consider  software 
and  a  computer’s  memory  in  light  of 
this  definition,  it  is  only  reasonable  to 
conclude  that  software  is  a  gas.  The 
situation  has  always  been  that  no  mat¬ 
ter  how  large  a  container  you  make 
(that  is,  how  much  memory  your  com¬ 
puter  has),  software  expands  to  fill  it 
completely.  We’ve  been  increasing  the 
size  of  our  containers  for  more  than 
40  years  now,  and  it  still  seems  as  though 
we  never  have  enough.  Because  of 
this,  we  have  had  to  be  quite  miserly 
in  our  use  of  memory  just  to  get  the 
most  out  of  what  has  always  been  and, 
apparently,  always  will  be  a  precious 
commodity. 

Memory  is  used  to  store  a  program’s 
executable  code  and  the  data  that  is 
manipulated  by  that  code.  Overlays  are 
one  method  used  to  limit  the  amount 
of  memory  used  for  storage  of  execut¬ 
able  code.  A  program  can  store  its  data 
in  static  or  dynamic  memory.  Static  mem¬ 
ory  is  allocated  at  the  time  the  program 
is  first  loaded  into  memory  by  the  op¬ 
erating  system,  and  the  amount  of  static 
memory  used  by  a  program  is  fixed. 
Dynamic  memory,  on  the  other  hand, 
is  allocated  as  needed  at  the  request 
of  the  program  during  execution.  Dy- 
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namic  memory  is  assigned  from  a  pool 
of  available  memory  managed  by  the 
operating  system  that  is  often  referred 
to  as  the  heap.  When  the  program  fin¬ 
ishes  using  a  block  of  dynamic  mem¬ 
ory,  it  can  return  the  memory  to  the 
heap.  Note  that  static  and  dynamic  mem¬ 
ory  are  strictly  software  differentiations 
based  on  how  memory  is  used.  The 
kind  of  physical  memory,  be  it  stan¬ 
dard  RAM,  extended,  or  expanded,  is 
immaterial. 

Prudent  use  of  memory  is  enhanced 
by  minimizing  the  software’s  reliance 
on  static  memory  and  maximizing  its 
use  of  dynamic  memory.  The  choice 
of  programming  language  can  have  an 
important  impact  on  the  ability  to  do 
this,  and  C  is  particularly  well  suited 
for  extensive  use  of  dynamic  memory. 
“Gas”  is  also  defined  as  “any  substance 
that  produces  a  poisonous,  irritating, 
or  asphyxiating  atmosphere.”  Software 
does  not  match  this  definition  because 
it  actually  seems  to  create  an  atmos¬ 
phere  in  which  bugs  thrive.  Which  takes 
me  to  the  primary  subject  of  this  article  — 
bugs,  specifically  the  kind  that  result 
from  the  use  of  C’s  dynamic  memory 
features,  and  how  to  find  and  extermi¬ 
nate  them. 

C's  Dynamic  Memory  Capabilities 

The  standard  C  library  provides  four 
functions  for  managing  dynamic  mem¬ 
ory:  malloc,  calloc,  realloc,  and  free.  A 
summary  of  the  use  of  these  functions 
is  provided  in  Table  1.  These  functions 
are  roughly  equivalent  to  those  pro¬ 
vided  in  other  languages  (for  example, 


Pascal/Modula-2’s  new  and  dispose). 
The  real  power  comes  from  C’s  pointer 
and  array  concepts. 

In  C,  arrays  can  be  either  static  or 
dynamic.  Static  arrays  are  declared  with 
a  constant  size;  dynamic  arrays  are  de¬ 
clared  as  pointer  variables.  The  size  of 
the  array  is  specified  at  run  time  when 
the  memory  for  the  array  is  allocated 
(using  either  malloc  or  calloc).  In  C, 
both  static  and  dynamic  arrays  can  be 
referenced  using  exactly  the  same  syn¬ 
tax,  so  there  is  no  requirement  to  stati¬ 
cally  define  array  sizes.  The  specifica¬ 
tion  of  the  size  of  a  needed  array  can 
be  deferred  until  program  execution 
time,  when  the  program  has  suitable 
information  regarding  the  intended  use. 

Languages  without  this  capability 
force  you  to  impose  arbitrary  limits  on 
the  user  because  of  the  need  to  fix 
array  sizes  at  compile  time.  The  end 
result  is  a  large  program  with  table 
sizes  set  up  to  accommodate  extreme 
usage  situations. 

Types  of  Dynamic  Memory  Misuse  in  C 

The  danger  inherent  in  C’s  dynamic 
memory  and  pointer  manipulation  fea¬ 
tures  comes  from  the  possibility  that 
pointers  can  be  assigned  errant  values 
without  detection  by  the  compiler  or 
run-time  system.  Errant  pointers  often 
result  in  an  address  reference  outside 
the  limits  of  the  memory  space  assigned 
to  the  program.  In  protected  environ¬ 
ments,  such  as  Unix  and  OS/2,  this 
results  in  an  error  called  a  segmenta¬ 
tion  violation,  which  is  detected  by  the 
use  of  a  debugger  that  can  easily  reveal 
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(continued  from  page  62) 
the  location  of  the  offending  statement. 
Both  MS-DOS  and  the  Macintosh’s  OS, 
however,  are  unprotected  environments 
that  allow  programs  to  address  any  part 
of  memory.  In  these  environments,  an 
errant  pointer  could  do  anything  from 
causing  no  damage  at  all  to  destroying 
the  entire  file  system!  Debugging  in 
these  environments  can  be  a  most  pains¬ 
taking  experience,  even  with  the  use 
of  a  debugger. 

The  insidious  nature  of  another  type 
of  problem  that  can  occur  is  alluded 
to  in  the  following  warnings: 

“  .  .  .  any  program  that  changes  mem¬ 
ory  that  is  not  allocated  to  it  stands  a 
chance  of  destroying  a  DOS  memory 
management  control  block.  This  causes 
unpredictable  results  that  don’t  show 
up  until  an  activity  is  performed  where 
DOS  uses  its  chain  of  control  blocks 


(the  normal  result  is  a  memory  alloca¬ 
tion  error,  for  which  the  only  correc¬ 
tive  action  is  to  restart  the  system).”  — 
From  page  11-3  of  the  DOS  Version 
3.30  Technical  Reference. 

“Attempting  to  free  an  invalid  pointer 
may  affect  subsequent  allocation  and 
cause  errors.”  —  From  page  290  of  the 
Microsoft  C  5.1  Run-Time  Library  Ref¬ 
erence. 

These  comments  refer  to  a  common 
manifestation  of  an  errant  pointer  bug 
that  results  in  the  system  “hanging”  on 
an  ensuing  call  to  malloc.  The  specific 
call  that  reveals  the  problem  may  actu¬ 
ally  occur  after  many  other  malloc  calls 
have  succeeded,  compounding  the  de¬ 
bugging  problem. 

In  my  experience,  the  list  in  Table  2 
identifies  some  of  the  most  common 
programming  errors  that  lead  to  these 
dynamic  memory  corruption  problems. 


Management  and  Debugging  of 
Dynamic  Memory 

The  need  for  the  use  of  dynamic  mem¬ 
ory  in  Raima’s  database  software, 
db_  VISTA  and  db_QUERY,  is  particu¬ 
larly  acute.  Both  packages  are  C  link¬ 
able  libraries  providing  full-featured  da¬ 
tabase  management  and  query  engines. 
As  such,  they  need  to  use  as  little  mem¬ 
ory  as  possible  while  still  providing  the 
flexibility  needed  to  support  a  wide 
variety  of  applications.  Yet,  because 
of  the  dangers  inherent  in  C’s  dynamic 
memory  capabilities,  and  the  critical 
need  for  reliability  in  a  DBMS,  a  disci¬ 
plined  approach  to  dynamic  memory 
usage  had  to  be  developed  so  that  this 
insidious  class  of  bugs  could  be  easily 
detected  and  corrected. 

Because  most  C  implementations  of 
malloc  and  free  provide  little,  if  any, 
error  checking,  it  was  necessary  to  build 
our  own  extended  dynamic  memory 
control  module,  which  we’ve  dubbed 
Xmem  and  which  is  shown  in  Listing 
One,  page  125.  Xmem  keeps  track  of 
all  pointers  to  dynamically  allocated 
memory  and  performs  checks  for  the 
four  errors  delineated  in  Table  2.  De¬ 
fined  in  the  module  are  functions  x_mal- 
loc,  x_calloc,  and  x_free,  which  are  to 
be  called  instead  of  malloc ,  calloc,  and 
free.  One  additional  function,  called 
x_chkfree,  checks  to  ensure  that  all 
blocks  allocated  using  x_malloc  and 
x_calloc  have  been  freed  and,  reports 
and  frees  any  that  have  not  been  freed. 

A  global  ml  variable,  memtrace,  can 
be  set  to  determine  the  type  of  dy¬ 
namic  memory  control  to  be  used.  If 
memtrace  is  0,  no  error  checking  is 
performed  —  that  is,  x_malloc,  x_cal- 
loc ,  and  x  Jree  simply  call  malloc ,  cal 
loc,  and  free.  A  memtrace  value  of  1 
enables  pointer  tracking  and  checking 
for  errors  1,  2,  and  3-  Setting  memtrace 
to  2  additionally  checks  for  error  4. 

Xmem  maintains  two  global  tong  vari¬ 
ables  that  can  be  referenced  by  the 
application  program  when  memtrace 
is  nonzero.  Variable  tot_memory  con¬ 
tains  the  total  amount  of  dynamic  mem¬ 
ory  that  is  currently  allocated;  variable 
tot_alloc  contains  the  total  number  of 
calls  to  x_malloc  and  x_calloc. 

A  table  of  all  allocated  pointers  is 
maintained  by  Xmem.  When  a  request 
for  a  block  of  memory  is  made  through 
a  call  to  x_malloc,  a  gap  of  extra  space 
is  allocated  at  the  end  of  the  block  to 
be  used  to  check  for  overwrites.  The 
extra  space  is  filled  with  some  prede¬ 
fined  character  (FIU.CHAR)  and  checked 
for  changes  when  the  block  is  freed 
(error  1).  The  size  of  the  allocated  block 
and  the  pointer  are  stored  in  the  table. 

The  memory  allocation  tracking  ta¬ 
ble  simplifies  checking  for  an  invalid 


C  Declaration 

Function  Description 

char  *malloc  (size) 
unsigned  int  size; 

Allocates  a  block  of  size  bytes  of  memory  returning  a 
pointer  to  the  start  of  the  block  or  NULL  if  there  is  not 
enough  memory  available. 

char ‘calloc  (num,  size) 
unsigned  int  num.- 
unsigned  int  size; 

Allocates  and  clears  num  contiguous  blocks  of  mem¬ 
ory  each  size  bytes  in  length  returning  a  pointer  to  the 
start  of  the  block  or  NULL  if  there  is  not  enough 
memory  available. 

char ‘realloc  (ptr,  size) 
char  *ptr; 
unsigned  int  size; 

Adjusts  size  of  allocated  block.  Returns  a  pointer  to  the 
block  of  size  bytes  or  NULL  if  there  is  not  enough 
memory  available.  The  original  block  may  need  to  be 
moved  to  accommodate  the  new  size. 

free (ptr) 
char  *ptr; 

Frees  a  block  of  dynamic  memory  pointed  to  by  ptr 
and  allocated  by  a  previous  call  to  malloc  or  calloc. 

Table  1:  C’s  dynamic  memory  allocation  functions 

1 .  Writing  beyond  the  end  of  an  allocated  block  of  memory. 

Atypical  example  is  calling  function  strcpy with  a  source  string  that  is  missing  the 
sentinel  NULL  byte.  It  can  also  occur  from  an  "off  by  one"  subscripting  error. 

2.  Freeing  a  pointer  to  unallocated  memory. 

Have  you  ever  tried  freeing  static  memory?  Sometimes,  it  is  not  that  unusual  to 
assume  a  character  pointer  points  to  a  dynamic  string  when,  in  fact,  it  points  to  a 
string  constant. 

3.  Freeing  a  pointer  to  a  previously  freed  block  of  memory. 

Often,  a  system  has  a  variety  of  dynamic  data  structures,  such  as  inverted  lists, 
containing  pointers  to  the  same  dynamic  memory.  This  error  happens  when  an 
attempt  is  made  to  free  the  common  memory  pointer  from  multiple  locations. 

4.  Continued  use  of  freed  dynamic  memory. 

Some  dynamic  structures  are  allocated  and  freed  as  needed  during  execution. 
The  need  for  allocation  is  often  determined  by  whether  or  not  a  particular  pointer 
is  NULL.  This  error  occurs  when  you  forget  to  assign  a  NULL  to  that  pointer  when 
the  structure  is  freed  so  that  a  later  allocation  that  should  occur,  in  fact,  doesn't. 


Table  2:  Common  dynamic  memory  programming  errors  in  C 
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(continued  from  page  64) 
pointer.  When  x_free  is  called,  if  the 
pointer  is  in  the  table,  the  space  is 
freed  and  the  pointer’s  entry  is  removed. 
If  the  pointer  is  not  in  the  table,  then  it 
is  either  invalid  or  it  has  already  been 
freed  (errors  2  and  3). 

Setting  memtrace  to  2  enables  check¬ 
ing  for  changes  to  a  freed  block  of 
memory  (error  4).  Instead  of  actually 
freeing  the  block,  x_free  allocates  a 
copy  of  the  block  (if  the  copy  already 
exists,  then  we  know  that  the  block  has 
been  previously  freed  —  error  3).  Func¬ 
tion  x_chkfree  compares  the  copy  with 
the  original  and  reports  any  changes. 
Note  that  this  option  does  not  free  any 
memory  but  uses  virtually  twice  as 
much.  The  errors  detected  by  this 
method  are  particularly  treacherous,  how¬ 
ever.  Note  that  it  is  not  really  necessary 
to  maintain  a  copy  of  the  block  in  order 
to  detect  changes.  A  cyclic  redundancy 
check  (CRC)  value  (for  example,  check¬ 
sum)  could  be  used  instead.  This  would 
indeed  identify  that  a  change  has  oc¬ 
curred.  The  disadvantage  of  using  a 
CRC,  however,  is  that  you  do  not  know 
what  was  changed.  With  a  copy,  you 
can  know  the  exact  location  of  the 
changes  and  use  a  debugger  (for  ex¬ 
ample,  Microsoft’s  CodeView,  placing 
a  trace  point  on  the  changed  location) 
to  find  the  offending  code. 

The  memory  allocation  tracking  ta¬ 
ble  is  constructed  as  a  hash  table.  A 
hash  table  is  a  structure  that  stores  an 
item  in  a  location  in  the  table  that  is 
computed  based  on  the  value  of  the 
item.  In  our  case,  a  hash  index  is  com¬ 
puted  from  the  value  of  the  pointer  by 
casting  the  pointer  to  a  long  and  com¬ 
puting  its  modulo  based  on  the  size  of 
the  hash  table  array.  A  hash  table  was 
chosen  because  of  the  amount  and  fre¬ 
quency  of  needed  allocations  in  db_ 


QUERY.  Depending  on  the  complexity 
of  the  query,  as  few  as  ten  but  up  to 
as  many  as  several  hundred  allocations 
can  occur  during  the  setup  and  pro¬ 
cessing  of  a  query.  Thus,  it  is  important 
to  be  able  to  locate  a  pointer’s  position 
in  the  table  quickly. 

The  hash  table  consists  of  an  array 
of  pointers  to  buckets.  A  bucket  stores 
information  about  each  allocated  pointer. 
Lines  39  through  55  in  Listing  One  con¬ 
tain  the  hash  table  declarations.  Field 
alloc  in  struct  bucket  is  a  dynamic  array 

Prudent  use  of  memory 
is  enhanced  hy 
minimizing  the 
software’s  reliance  on 
static  memory  and 
maximizing  its  use  of 
dynamic  memory 


of  struct  alloc_entry.  This  array  will 
store  up  to  bucketsize  (line  28)  allo¬ 
cated  pointer  entries.  Each  alloc  entry 
contains  the  size  of  the  allocated  block, 
the  pointer  ( ptr )  to  the  allocated  block, 
and  a  pointer  to  the  copy  of  the  bldck 
allocated  when  the  block  is  freed.  The 
size  of  the  hash  table  is  specified  by  a 
global  int  variable  hashsize  (line  27). 
This  value  must  be  odd  (preferably 
prime)  or  the  odd-numbered  buckets 
will  never  be  used. 

The  hash  table  is  a  dynamic  array  of 


bucket  pointers  called  ptrhash  (line  55). 
Because  more  than  bucketsize  pointers 
could  have  the  same  hash  value,  the 
buckets  contain  a  next  pointer  to  allow 
additional  buckets  to  be  allocated  and 
chained  to  the  same  ptrhash  entry.  Fig¬ 
ure  1  illustrates  the  structure  of  the 
memory  allocation  tracking  table. 

Xmem  defines  two  local  functions 
that  manage  the  hash  table  and  report 
errors.  Function  sto_  ptr  stores  the  speci¬ 
fied  pointer  and  the  size  in  the  hash 
table.  This  function  allocates  the  dy¬ 
namic  memory  for  ptrhash  the  first  time 
it  is  called.  Line  75  computes  the  hash 
table  index,  which  is  used  in  line  78  to 
subscript  the  ptrhash  array.  Any  buck¬ 
ets  that  exist  for  the  computed  ptrhash 
entry  are  searched  in  lines  77  -  80  for 
an  available  alloc  array  entry.  If  there 
is  no  available  space,  a  new  bucket  is 
allocated  and  connected  to  the  linked 
list  (lines  82  -  102).  The  pointer  infor¬ 
mation  is  then  stored  into  the  next  avail¬ 
able  alloc  array  slot  in  the  bucket  (lines 
103  -  107).  Function  del_  pfrdeletes  the 
specified  pointer  from  the  hash  and 
frees  the  dynamic  memory  referenced 
by  it.  When  the  pointer  is  located  (lines 
131  -  134),  the  gap  is  checked  and,  if 
changed,  the  error  is  reported  (line  139). 
If  memtrace  is  1,  the  pointer  is  re¬ 
moved  from  the  bucket  and  the  dy¬ 
namic  memory  is  freed  (lines  145  - 
161).  If  memtrace  is  2,  a  copy  of  the 
allocated  memory  is  made,  unless  one 
already  exists,  for  comparison  by  func¬ 
tion  x_chkfree  (lines  164  -  171). 

When  memtrace  is  nonzero,  func¬ 
tion  x_malloc  calls  malloc  to  allocate 
the  requested  memory,  augmented  by 
the  extra  gap  space.  It  then  calls  sto_  ptr 
to  store  the  pointer  and  size  in  the 
hash.  Function  x_calloc  calls  x_malloc 
to  allocate  the  requested  memory  and 
then  calls  the  standard  C  function  mem- 
set  to  clear  the  allocated  block. 

Function  x_free  checks  for  a  NULL 
pointer  (something  that,  for  some  un¬ 
known  reason,  many  implementations 
of  free  do  not  do),  and  if  memtrace  is 
nonzero,  it  calls  del_  ptr  to  remove  the 
pointer  from  the  hash  and  free  the  space. 
If  memtrace  is  0,  x_free  simply  calls  free. 

Function  x_chkfree  searches  the  hash 
table,  reporting  and  freeing  any  point¬ 
ers  that  remain.  If  memtrace  is  2,  it 
checks  for  any  changes  to  freed  blocks. 
The  hash  table  itself  is  also  freed  by 
x_chkfree. 

When  errors  are  reported,  a  debug¬ 
ger  is  needed  to  track  down  the  spe¬ 
cific  source  of  the  problem.  For  the 
case  in  which  the  gap  has  been  over¬ 
written,  you  can  record  the  value  of  the 
pointer  and  rerun  the  exact  test  sce¬ 
nario,  setting  a  breakpoint,  for  exam¬ 
ple,  at  line  211  in  x_malloc  to  find  out 


Figure  1:  Memory  allocation  tracking  table 
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when  and  where  that  particular  alloca¬ 
tion  occurred.  You  can  discover  how 
the  memory  is  to  be  used  from  the 
function  calls  stack.  This  will  often  be 
sufficient  to  reveal  the  problem. 

You  could  also  use  the  debugger  to 
break  whenever  the  gap  is  modified, 
which  would  reveal  the  specific  state¬ 
ment  that  is  causing  the  problem.  Un¬ 
fortunately,  this  kind  of  operation  is 
very  slow  in  most  debuggers,  primarily 
because  of  the  lack  of  good  hardware 
support  for  debugging. 

Setting  a  breakpoint  at  line  184  in 
function  del_  ptr  and  then  inspecting 
the  function  calls  stack  when  the  break¬ 
point  occurs  will  often  explain  why  a 
pointer  to  be  freed  is  not  in  the  table. 
Perhaps  it  has  already  been  freed,  or 
you  see  that  the  space  being  freed  is 
actually  static. 

Enhancements 

Many  enhancements  could  be  made 
to  the  functionality  presented  here.  For 
example,  it  is  often  valuable  to  be  able 
to  free  not  only  a  single  pointer  but 
also  all  other  dynamic  memory  that 
was  since  allocated.  This  could  be  accom¬ 
plished  by  adding  an  allocation  num¬ 
ber  to  the  alloc,  entry  struct  that  is  as¬ 
signed  the  current  tot_allocv alue  when 
stored  in  the  table.  A  new  function 


called  x_release  could  be  added  that 
would  free  all  pointers  in  the  table  with 
an  allocation  number  greater  than  that 
associated  with  the  specified  pointer. 

The  CRC  method  of  detecting  changes 
to  allocated  memory  described  earlier 
could  form  the  basis  of  a  change-track¬ 
ing  system  whereby  those  dynamic  vari¬ 
ables  that  had  been  modified  by  a  given 
function  could  be  reported.  This  could 
be  implemented  by  adding  a  string  ar¬ 
gument  to  x_malloc  and  x_calloc  that 
contained  the  name  of  the  pointer  vari¬ 
able  being  allocated.  The  alloc_entry- 
struct  would  store  this  string  as  well  as 
the  current  CRC  value.  A  function  that 
would  be  called  as  desired  (for  exam¬ 
ple,  on  exit  from  each  function  in  the 
application  program)  would  report  the 
names  of  all  variables  that  had  different 
CRC  values.  If  the  application’s  func¬ 
tion  name  were  printed  first,  then  the 
list  could  be  inspected  to  ensure  that 
the  proper  variables  were  modified. 

Conclusion 

Because  memory  has  always  been  and 
still  is  a  precious  commodity,  we  have 
had  to  be  frugal  in  our  use  of  memory 
in  the  development  of  our  programs. 
The  ability  in  C  to  maximize  the  use  of 
dynamic  memory  has  allowed  us  to 
develop  sophisticated  software  systems 


to  run  on  small  computers.  C  has  often 
been  criticized,  however,  for  the  ease 
with  which  catastrophic  errors  can  oc¬ 
cur  resulting  from  the  very  use  of  these 
powerful  features.  Some  people  have 
even  written  off  the  use  of  C  because 
of  these  problems. 

This  article  has  presented  proven  tech¬ 
niques  to  detect  and  identify  errors  in 
the  use  of  dynamic  memory  in  C.  As  C 
and  its  supporting  cast  of  development 
tools,  particularly  debuggers,  continue 
to  evolve,  there  is  no  doubt  in  my  mind 
that  these  problems  will  be  much  more 
easily  avoided. 
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C  Procedure 
Tables 

Calling  functions  by  the  number 


The  first  time  I  heard  of  storing 
data  in  tables,  it  seemed  com¬ 
pletely  unnecessary.  Drawing 
on  my  full  two  weeks  of  pro¬ 
gramming  experience,  I  came 
to  the  conclusion  that  arrays  were  just 
too  much  work. 

Since  that  rather  premature  conclu¬ 
sion,  I  have  found  arrays  to  be  one  of 
the  most  useful  tools  for  handling  large 
quantities  of  data.  I  remember  drawing 
a  similarly  premature  conclusion  when 
I  first  heard  about  an  underused  fea¬ 
ture  of  the  C  language  —  arrays  of  point¬ 
ers  to  functions. 

A  pointer  to  a  function  contains  the 
starting  address  of  a  subroutine.  Just 
like  a  character  pointer  points  to  a  char¬ 
acter  in  memory,  a  function  pointer 
points  to  a  function,  which  can  be  exe¬ 
cuted  using  the  pointer.  A  function  exe¬ 
cuted  in  this  way  performs  exactly  the 
same  as  a  function  executed  using  a 
standard  call.  Arguments  can  be  passed 
to  it,  and  a  value  can  be  returned  from  it. 

A  function  pointer  by  itself  can  be  a 
handy  tool,  but  it  takes  on  a  great  deal 
more  significance  when  stored  with 
others  in  an  array.  We  call  such  an 
array  a  “procedure  table.” 

A  procedure  table  is  a  powerful  tool 
for  software  design.  It  is  a  method  of 
storing  procedures  (functions  and  sub¬ 
routines)  in  a  table  so  that  the  stored 
data  can  be  accessed  by  using  a  nu¬ 
meric  offset.  This  gives  you  a  method 
for  systematically  controlling  proce¬ 
dures,  as  in  a  loop,  for  example. 

To  illustrate  the  use  of  procedure 
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tables,  I  have  chosen  a  task  that  I  have 
had  to  tackle  in  many  systems  and  one 
that  I  have  always  found  particularly 
cumbersome.  At  some  point,  a  pro¬ 
gram  usually  prompts  the  user  for  a 
series  of  responses  in  order  to  gather 
parameters.  These  parameters  may  be 
used  as  query  criteria  for  a  report,  for 
narrowing  down  a  potential  problem, 
as  input  for  a  graph,  and  so  on. 

Gathering  these  parameters  is  com¬ 
plicated  by  the  validation  of  the  re¬ 
sponses,  and  by  multiple  possible  paths 
through  the  prompts.  For  example,  if 
the  first  prompt  asks  the  user  if  a  report 
is  to  be  printed  for  a  single  account,  a 
range  of  accounts,  or  all  accounts,  the 
second  prompt  depends  on  the  user’s 
response.  If  the  second  and  third  prompts 
get  the  starting  and  ending  account  num¬ 
bers  for  a  range,  the  program  must 
validate  that  the  ending  account  num¬ 
ber  is  larger  than  the  starting  account 
number.  This  goes  on  ad  nauseam. 

It  always  bothered  me  to  take  the 
obvious  approach  to  this  problem.  Gath¬ 
ering  the  parameters  in  this  manner 
resulted  in  a  mass  of  nested  if/else 
phrases.  This  type  of  code  is  difficult  to 
read  and  maintain  and  is  not  reusable. 
Procedure  tables  provide  a  better  way. 

prompter/) 

Listings  One  and  Two,  on  pages  128  and 
130,  illustrate  prompter/  ).  The  goal  of 
prompter/ )  was  to  develop  a  reusable 
routine  that  prompts  a  user,  validates 
responses,  and  performs  actions  based 
on  those  responses,  prompter/ )  must 
be  able  to  handle  unique  validations 
and  multiple  paths  through  the  dialog. 
It  does  this  by  executing  functions  stored 
in  a  procedure  table,  which  is  imple¬ 
mented  as  an  array  of  data  structures. 


The  basic  building  block  of  promp¬ 
ter/  )  is  the  data  structure  question, 
which  is  declared  as: 

struct  question  ( 
char  *  text; 
char  *  response; 
int  ("validateX  ); 
int  (*doit)(  ); 
int  (*set)( ); 


The  application  that  calls  prompter/) 
defines  one  or  more  arrays  of  this  struc¬ 
ture.  prompter/ )  loops  through  the  ar- 
ray(s)  of  structures  according  to  the 
algorithm  shown  in  Example  1.  Let’s 
look  at  each  member  of  question  in 
detail. 

•  question. text  is  the  text  of  the 
prompt,  such  as  “Do  you  want  this 
report  for  one  account,  a  range  of  ac¬ 
counts,  or  all  accounts?” 

•  question.response  is  a  pointer  to 
the  variable  that  receives  the  user’s  re¬ 
sponse.  This  allows  prompter/ )  to 
gather  the  parameters  needed  by  the 
application.  If  question.response  is 
set  to  NULL,  prompter/ )  assumes  the 
application  no  longer  needs  the  re¬ 
sponse  and  throws  it  away. 

•  question. validate  is  the  address  of 
the  routine  that  validates  the  response. 
For  example,  it  may  check  to  see  that 
the  account  number  entered  is  valid. 
If  an  error  occurs,  the  function  returns 
a  unique  non-zero  code,  and  the  error 
is  handled  downstream  by  the  handle_ 
error/ )  routine. 

•  question.doit  is  the  address  of  the 
routine  that  will  perform  the  action,  if 
any,  associated  with  this  question.  For 
example,  it  might  convert  an  ASCII  ac- 
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(continued  from  page  68) 

count  number  to  an  integer  and  store 

it  in  the  appropriate  variable. 

•  question.set  is  the  address  of  a  rou¬ 
tine  that  determines  what  the  next  ques¬ 
tion  will  be.  It  can  tell  prompter p )  to 
go  on  to  the  next  question  in  the  array 
or  to  jump  to  a  new  array  of  questions, 
depending  on  the  response  given  by 
the  user.  For  example,  if  the  user  re¬ 
quests  a  report  for  a  range  of  accounts, 
this  routine  will  tell  prompterp )  to  ask 
the  questions  stored  in  the  range_of_ 
accounts  array .  If  an  error  was  encoun¬ 
tered,  the  routine  can  tell  prompterp ) 
to  ask  the  current  question  again,  or 
to  back  up  and  restart  the  questions  at 
a  previous  point  in  the  array. 

The  prompterp )  routine  is  itself  quite 
small.  It  is  nothing  more  than  a  trigger¬ 
ing  mechanism  for  the  functions  stored 
in  procedure  tables,  that  is,  a  routing 
control  to  the  proper  routine. 

After  each  function  executes,  it  re¬ 
turns  a  status  code  that  indicates  if  it 
was  successful,  prompterp )  uses  this 
value  to  route  control  to  the  error  han¬ 
dler  if  an  error  is  encountered. 

prompterP  J  makes  no  decisions  about 
which  question  structure  to  use  as  its 
basis  for  prompting  the  user.  The  ap¬ 
plication  defines  the  arrays  of  question 
structures,  and  it  is  responsible  for  de¬ 
ciding  what  their  contents  are  and  the 
order  they  will  be  in. 

Several  routines  are  provided  to  sim¬ 
plify  this  job.  These  routines  are  called 
by  the  set  member  of  question  (ques- 
tion.set(  )),  which  decides  what  the  next 
question  will  be  based  on  the  response 
given  by  the  user. 

The  prcontro I  Structure 

The  prcontrol  structure  is  the  master 
control  structure  for  prompterp ).  It  con¬ 
tains  all  information  regarding  the  cur¬ 
rent  state  of  the  prompting.  A  pointer 
to  this  structure  is  passed  to  every  func¬ 


Example  1:  Looping  through  an  array 


tion  called  from  prompterp ).  This  al¬ 
lows  the  functions  to  examine  and  mod¬ 
ify  the  current  state  of  prompterp ). 

The  prcontrol  structure  is  declared: 

struct  prcontrol  ( 

int  current_question; 

struct  question  *  current_group; 

int  group_stack_ptr; 

char  response[121]; 

int  errstat; 

struct  errormess  *  errormess; 

1 

Let’s  look  at  each  member  in  detail: 

•  prcontrol.current_question  is  the 

offset  of  the  current  question  in  the 
array  of  question-data  structures  pointed 
tobyprcontroLcurrent_group.prcon- 
troLcurrent_question  is  set  to  zero  on 
entry  to  prompterp)  and  is  typically 
incremented  by  question.set  in  order 
to  go  on  to  the  next  question. 

•  prcontroLcurrent_group  is  a  point¬ 
er  to  an  array  of  question  structures. 
This  is  the  group  of  questions  that  is 
currently  being  asked. 

•  prcontrol.group_stack_ptr  is  a  part 
of  the  mechanism  that  allows  promp¬ 
terp  )  to  jump  easily  from  one  array  (or 
group)  of  questions  to  the  next.  This 
permits  prompterp )  to  follow  multiple 
paths  through  the  prompts.  See  the 
discussion  of  multiple  paths  later  in 
this  article. 

•  prcontrol.response  is  a  buffer  for 
holding  the  response  entered  by  the 
user. 

•  prcontrol.errstat  is  the  error  status 
returned  from  question. validate(  )  or 
question.doit(  ).  Typically  this  value 
is  examined  by  question.set(  )  before 
deciding  what  route  to  tell  prompterp  )to 
take.  It  is  also  passed  to  handle_error(  ) 
to  display  the  proper  error  message. 

•  prcontrol.errormess  is  a  pointer  to 
an  array  of  errormess  structures.  This 
pointer  is  passed  to  handle_errorp ) 


when  an  error  is  encountered  so  it  can 
display  the  proper  error  message. 

Multiple  Paths 

The  ability  to  follow  multiple  paths  is 
handled  through  the  use  of  a  stack, 
which  is  implemented  as  an  array  of 
group_stack  structures. 

The  group  stack  enables  prompterp ) 
to  jump  to  another  group  of  questions 
without  losing  its  place.  It  operates  in 
a  way  similar  to  the  stack  in  a  C  or 
assembler  program. 

When  a  question.set(  )  routine  de¬ 
cides  it  must  jump  to  another  array  of 
questions,  it  calls  the  routine  start_ 
group( ).  start _group( )  calls  push_ 
groupP )  to  push  prcontrol.current_ 
group  and  prcontrol.current_ques- 
tion  onto  the  group  stack. 

When  this  group  of  questions  is  fin¬ 
ished  executing,  a  question.set(  )  rou¬ 
tine  calls  end_group( ).  end_group( ) 
calls  pop_group( ),  which  pops  prcon- 
troLcurrent_groupa  nd  prcontroLcur- 
rent_question  off  of  the  group  stack. 
end _group( )  then  increments  prcon- 
troLcurrent_questionto  continue  at  the 
next  question,  past  the  point  where  the 
other  group  of  questions  was  called. 

This  method  allows  a  group  of  ques¬ 
tions  to  start  another  group  of  ques¬ 
tions,  which  can  start  another  group 
of  questions,  and  so  on,  and  prompterp ) 
can  still  easily  return  to  the  point  at 
which  it  started. 

Error  Handling 

Wouldn’t  computer  programs  be  much 
easier  to  write  if  we  could  assume  that 
users  never  make  mistakes?  But  of  course 
we  cannot  assume  this,  so  prompterp ) 
has  an  error  handling  mechanism. 

Any  time  an  error  is  encountered  by 
question.validate(  )  or  question.do- 
it(),  the  routine  that  detects  the 
error  returns  a  unique,  non-zero  value 
to  prompterp ).  This  value  is  saved  in 
prcontrol.errstat( ).  The  routine  in 
question.set(  )  then  decides  how  this 
error  will  effect  the  direction  of  the 
questions. 

This  error  status  is  then  passed  to  the 
routine  handle_errorp ),  whose  respon¬ 
sibility  is  to  build  and  display  the  proper 
error  message.  handle_errorp )  works 
with  an  array  of  struct  errormess.  This 
array  is  declared: 

struct  errormess! 
int  errstat; 
char  *  message; 
int  (*build)(  ); 

1; 

errormess.errstat  is  the  value  that  iden¬ 
tifies  the  error,  and  errormess.mes- 
sage  is  the  message  that  appears 


loop) 

display  current  question->text 

get  response  from  user 

execute  current  question->validate 

if (no  error  on  validate) { 

execute  current  question->doit 

) 

copy  response  to  current_question->response 

execute  current_question->set 

i 

if (error  from  validate) { 

call  error  handler 

} 
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(continued  from  page  70) 
when  this  error  is  encountered,  error- 
mess.build  is  the  address  of  the  func¬ 
tion  that  will  perform  any  extra  format¬ 
ting  of  errormess. message.  For  ex¬ 
ample,  if  the  error  ACCOUNT_NOT_IN_ 
FILE  is  encountered,  this  routine  might 
turn  the  message  Account  %s  not  in 
file  into  “Account  101  not  in  file.” 

The  application  program  defines  an 
array  of  these  structures.  When  han- 
dle_error(  jis  called,  it  searches  through 
this  array  until  it  finds  a  match.  When 
a  match  is  found  it  executes  error- 
mess.build  if  errormess.build  is  not 
NULL.  Then  it  displays  the  message. 

Is  This  Too  Much  Work? 

Before  we  dig  into  a  specific  example, 
let  me  try  to  address  a  question  that 
many  will  have.  Yes,  this  is  too  much 
work  to  go  through  to  ask  two  ques¬ 
tions.  But  this  is  not  too  much  work 
to  go  through  to  ask  200  or  even  20 
questions. 

A  method  like  this  produces  real  sav¬ 
ings  in  development  time.  The  reason 
is  that  system  prompts  occur  in  pat¬ 
terns.  For  example,  a  system  we  re¬ 
cently  developed  had  about  20  reports. 
Each  report  required  that  the  user  speci¬ 
fied  an  output  destination:  printer, 
screen,  or  disk.  The  disk  selection  re¬ 
quires  additional  entry  of  a  filename. 
If  the  file  exists,  the  user  has  the  option 
of  overwriting  that  file,  choosing  a  new 
file  or  appending  the  report  to  the  file. 

The  savings  in  development  time  is 
realized  after  the  printer,  screen,  or  file 
procedure  tables  have  been  built  and 
the  routines  coded  for  the  first  time.  At 
this  point,  all  routines  become  data 
that  is  fed  to  prompter! ).  Any  program 
that  needs  to  access  this  particular  se¬ 
ries  of  questions  as  a  part  of  its  prompts 
simply  calls  start_group( )  from  one  of 
its  question.set  routines  to  start  this 
group  of  questions.  The  printer,  screen, 
or  file  prompts  appear  on  the  screen 
and  when  they  have  completed,  the 
prompts  go  on  from  where  they  left 
off.  The  programmer  never  again  has 
to  worry  about  this  series  of  prompts. 

As  the  number  of  this  type  of  pattern 
of  prompts  increases,  the  value  of 
prompter ( )  as  a  development  tool  in¬ 
creases.  prompter ( )  can  be  even  used 
to  do  a  rudimentary  form  of  reasoning 
by  having  it  chew  its  way  through  a 
series  of  prompts  from  a  user.  It  will 
eventually  reach  a  conclusion. 

A  Specific  Example 

The  example  I  have  chosen  to  illustrate 
prompter!  )  is  a  series  of  prompts  that 
gathers  parameters  for  a  mythical  ac¬ 
count  report.  The  parameters  that  must 
be  gathered  are: 


•  The  account  query  criteria  —  the  ac¬ 
count  number  or  range  of  accounts  to 
be  included. 

•  The  display  parameter’s  record  that 
is  to  be  used. 

•  Should  the  Over/Short  report  be 
printed  automatically? 

•  The  report  destination:  printer,  screen, 
or  disk. 

Refer  to  Listing  Three,  page  130,  for 
the  code  that  handles  this  set  of  prompts. 

The  savings  in 
development  time  is 
realized  after  the 
printer,  screen,  or  file 
procedure  tables 
have  been  built  and 
the  routines  coded  for 
the  first  time 


account jparms  is  the  array  of  struct 
question  that  provides  the  main  flow 
of  prompts.  Its  address  goes  into  the 
prcontrol  structure  from  main( )  be¬ 
fore  the  call  to  prompted ). 

You  can  see  the  flow  of  the  prompts 
by  reading  the  initialization  of  this  ar¬ 
ray.  Let’s  look  at  the  initialization  of  the 
first  member  in  detail: 
account_parms[0].text  points  to  “Do 
you  want  this  report  for  a  single  ac¬ 
count  or  a  range  of  accounts?  (S  or  R).” 
This  text  will  be  displayed  when  the 
user  is  being  prompted. 
account_parms[0].response  points  to 
single_or_range  (which  is  an  array  of 
char).  The  response  entered  by  the 
user  will  be  copied  here  so  the  report 
program  knows  if  the  report  is  to  be  for 
a  single  account  or  a  range  of  accounts. 
account_parms[0].vaUdate  is  set  to 
the  address  of  the  routine  account_ 
or_range_val(  ).  This  routine  will  make 
sure  that  the  response  is  S  or  R.  If  not, 
account_or_range_val(  )  returns  the 
error  status  ENTER_S_OR_R  and  han- 
dle_error(  )  prints  the  appropriate  er¬ 
ror  message. 

account_parms[0].doit  is  set  to  the 

address  of  no_op( ).  This  routine  does 
nothing  but  retum(O);.  no_op( is  used 
as  a  place  holder,  because  no  doit 
action  is  required  for  this  prompt.  It  is 
necessary  because  prompter ( )  will  exe- 
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cute  the  function  specified  in  account_ 
parms[0].doit,  so  a  function  address 
must  be  stored  there. 
accoimt_parms[0].set  points  to  ac- 
count_or_range_set(  )TTiisfunctionde- 
termines  if  the  user  entered  S,  R,  or  an 
erroneous  response.  If  an  error  occurred, 
account_or_rainge_set(  )  does  noth¬ 
ing.  This  will  cause  the  question  “Do 
you  want  this  report  for  a  single  ac¬ 
count  or  a  range  of  accounts?  (S  or  R)” 
to  be  asked  again.  If  the  user  entered 
S,  account_or_range_set(  )  starts  the 

A  procedure  table  is  a 
powerful  tool  for 
software  design 

group  that  requests  the  single  account 
number.  If  the  user  entered  R,  account_ 
or_range_set(  )  starts  the  group  that 
requests  the  range  of  account  numbers. 

As  you  look  through  the  code  in 
Listing  Two,  you  will  see  calls  to  sev¬ 
eral  functions  that  assist  with  control 
of  flow.  These  functions  include: 

•  start_group( ),  which  starts  a  new 
group  of  questions. 

•  end_group( ).  which  ends  the  cur¬ 
rent  group  of  questions.  It  calls  pop_ 
group( )  to  restore  the  prompting  to  its 
previous  state. 

•  checkerror_next_question( ),  which 
causes  prompter f  )  to  go  on  to  the  next 
question  unless  an  error  was  encoun¬ 
tered. 

•  checkerror_end _group( ),  which  ends 
the  current  group  of  questions  unless 
an  error  was  encountered. 

•  restart_group( ),  which  restarts  the  cur¬ 
rent  group  of  questions. 

Notice  that  checkerror_next_ques- 
tion(  )and  checkerror_end_group(  )can 
be  used  as  a  question. set( )  routine 
in  many  cases  (look  at  account, 
parms[l].set).  It  is  precisely  this  type 
of  function  reuse  that  saves  develop¬ 
ment  time  over  the  long  run. 

As  you  develop  more  and  more  code 
that  uses  prompter J ),  you  begin  to  no¬ 
tice  patterns.  Once  a  pattern  has  been 
discovered,  you  write  a  generalized  rou¬ 
tine  to  handle  the  pattern,  and  this 
routine  can  be  used  over  and  over. 

I  suggest  that  the  simplest  way  to  get 
a  clear  picture  of  how  prompter if  )  works 
its  way  through  the  procedure  tables 
is  to  single-step  your  way  through  promp- 
ter( )  with  a  debugger  like  CodeView. 


Suggestions  for  Improving  prompter () 

The  first  step  to  improve  prompter J ) 
is  to  remove  the  printff  )/gets( )  inter¬ 
face,  and  attach  a  windowing-type 
interface.  To  do  this,  I  suggest  that 
you  add  an  element  to  the  question 
data  structure.  This  element  (question, 
form)  is  a  pointer  to  a  function  that 
formats  the  output.  Its  job  is  to  place 
the  question  text  on  the  screen  in  its 
proper  position,  adjusting  such  attrib¬ 
utes  as  color.  If  you  are  careful  to  iso¬ 
late  all  screen  positioning  to  only  the 
question.form  routines,  you  can  later 
port  the  system  to  a  different  display 
by  just  rewriting  these  functions. 

Next,  add  a  better  keyboard  input 
routine.  Most  production  systems  do 
not  use  gets( )  for  input. 

Finally,  as  you  use  prompter! ),  you 
will  notice  that  there  is  room  for  im¬ 
provement  in  the  area  of  moving  back¬ 
wards  in  the  prompts.  You  can  de¬ 
velop  a  more  elegant  approach  by  hav¬ 
ing  the  routine  prompted  )  automatically 
call  pop_group(  )  when  it  is  at  the 
end  of  a  group. 

Back  to  Procedure  Tables 

The  point  of  this  article  was  not  to 
demonstrate  how  to  prompt  users  for 
input  but,  to  demonstrate  the  use  of 
procedure  tables.  Procedure  table  tech¬ 
niques  that  are  similar  to  those  used  in 
prompter ( )  can  be  applied  to  a  wide 
variety  of  tasks.  We  have  used  these 
techniques  for  the  development  of  file 
maintenance  programs,  communica¬ 
tions  programs,  parsers,  menus,  report 
generators,  keyboard  input  validation 
routines,  and  others. 

We  have  found  procedure  tables  to 
be  extremely  helpful  for  developing 
software  that  is  flexible,  bug  free,  and 
highly  maintainable.  Using  procedure 
tables  allows  us  to  treat  functions  as  if 
they  were  data,  and  this  opens  up  a 
new  world  to  system  design. 
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Going  From  K&R 

To  ANSI  C 


Extending  and  codifying  the  C  language 


Last  September,  the  ANSI  X3J11 
committee  finalized  the  ANSI  stan¬ 
dard  for  C  and  sent  it  up  one 
level  for  final  approval  (which 
should  occur  this  year).  Culmi¬ 
nating  five  years  of  study  and  discus¬ 
sion,  the  standard  is  becoming  the  ba¬ 
sis  for  C  compilers  on  many  hardware 
platforms.  In  the  MS-DOS  world,  every 
compiler  has  incorporated  at  least  some 
of  the  ANSI  features  and  many  are  com¬ 
ing  close  to  full  compliance  with  the 
standard. 

The  committee  began  with  the  clas¬ 
sic  “White  Book”  of  C,  Brian  Kernighan 
and  Dennis  Ritchie’s  The  C  Program¬ 
ming  Language,  also  known  by  the 
author’s  initials  of  K&R.  This  thin  white 
book  defined  the  C  language  and  was 
used  by  both  implementors  and  users 
of  C.  Unfortunately,  it  was  an  incom¬ 
plete  standard.  Many  decisions  about 
the  language’s  facilities  were  left  up  to 
the  compiler  implementor.  As  C  be¬ 
came  more  popular,  it  became  clear 
that  certain  aspects  of  the  language 
caused  problems  when  debugging  or 
porting  programs.  Because  of  these  fac¬ 
tors,  different  C  compilers  included  dis¬ 
parate  extensions  and  features. 

In  designing  a  standard  for  C,  the 
ANSI  committee  had  several  goals  in 
mind.  First,  they  wanted  to  maintain 
compatibility  with  K&R.  This  meant  mini¬ 
mizing  changes  that  would  invalidate 
existing  K&R-compatible  programs.  In 
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addition,  they  wanted  to  codify  and 
include  common  language  extensions 
and  programming  practices.  Finally,  they 
wanted  to  improve  the  utility  and  port¬ 
ability  of  the  language.  This  was  not 
an  easy  task. 

In  the  end  they  did  an  admirable 
job.  While  some  old-line  C  program¬ 
mers  may  grumble  about  having  “their” 
language  changed,  the  end  result  is 
that  the  ANSI  standard  is  compatible 
with  K&R  and  it  enhances  the  language. 

This  article  is  not  designed  to  be  a 
complete  tutorial  on  ANSI  C.  Its  goal  is 
to  explain  how  ANSI  has  added  to  C, 
and  what  changes  may  affect  existing 
programs  and  programming  practices. 
Several  new  facilities  have  been  added 
to  the  language  and  can  be  exploited 
to  improve  program  functionality,  read¬ 
ability,  and  maintainability.  In  spite  of 
the  committee’s  best  efforts,  there  are 
some  subtle  changes  that  may  occa¬ 
sionally  catch  the  programmer  who  is 
unaware  of  them. 

The  article  is  divided  into  three  sec¬ 
tions  that  focus  on  the  preprocessor, 
the  language,  and  the  standard  library. 
In  each  section  I’ll  discuss  subtle 
changes  and  additions  to  that  part  of 
the  language.  Subtle  changes  are  those 
that  may  “sneak”  up  on  the  unsuspect¬ 
ing  programmer.  Additions  are  new 
ANSI  features  that  the  programmer 
should  be  aware  of. 

Preprocessor 

The  preprocessor  was  changed  signifi¬ 
cantly,  and  some  of  these  changes  can 
lead  to  problems  when  porting  code 
between  ANSI  and  K&R  compilers.  Many 
compiler  vendors  have  not  yet  fully 
implemented  the  ANSI  changes  for  fear 


that  they  would  break  existing  code. 

A  new  preprocessor  operator  has 
been  added:  defined(name).  Supplied 
with  the  name  of  a  macro,  defined( ) 
returns  a  true  value  if  that  macro  has 
been  defined,  or  false  if  it  has  not.  This 
duplicates  the  function  of  the  ifdef  di¬ 
rective  but  allows  for  the  use  of  Boolean 
operators  for  checking  the  definition 
of  multiple  macros. 

Two  more  preprocessor  operators 
are  new  with  ANSI:  #  and  ##  which 
affect  the  replacement  of  tokens  in  the 
replacement  lists  of  macros.  When  a 
parameter  in  the  replacement  list  of  a 
function-like  macro  is  preceded  by  a  * 
operator,  the  corresponding  argument 
is  inserted  at  that  point  as  a  string  lit¬ 
eral.  The  ##  operator  concatenates  ad¬ 
jacent  tokens  in  the  replacement  list; 
these  newly-built  tokens  are  then  avail¬ 
able  for  further  macro  replacement. 

Due  to  operating  system  differences, 
the  ANSI  standard  does  not  define  a 
specific  search  method  for  a  file  speci¬ 
fied  in  a  #include  directive.  K&R  used 
Unix-style  directory  structures  and  file 
names  when  specifying  how  files  were 
located,  but  many  operating  systems  do 
not  have  similar  or  equivalent  facilities. 

Under  K&R  it  was  possible  to  define 
the  same  macro  in  several  places.  How 
this  was  handled  was  implementation- 
dependent  —  most  compilers  merely 
used  the  last  definition  encountered. 
This  practice  can  lead  to  problems,  es¬ 
pecially  when  the  definitions  are  stored 
in  header  files.  ANSI’s  solution  was  to 
disallow  any  macro  redefinitions,  un¬ 
less  they  were  identical. 

K&R  allowed  for  recursive  macros 
that  contained  their  own  names  in  their 
expansion.  This  was  a  dangerous  prac- 
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tice,  leading  to  run-away  preprocessing 
and  logic  problems.  ANSI  has  made 
recursive  macros  illegal;  the  macro’s 
own  definition  is  ignored  while  it  is 
being  expanded.  This  change  can  cause 
problems  in  code,  which  relied  upon 
recursive  macros. 

Two  new  directives  were  added:  #er- 
ror  is  used  to  output  an  error  message 
during  preprocessing.  The  standard 
strongly  suggests  that  #errorshould  also 
halt  compilation.  To  pass  configura¬ 
tion  information  to  the  compiler  the 
#pragma  directive  was  invented.  What¬ 
ever  follows  the  *pragma  is  interpreted 
in  an  implementation-defined  manner. 
Any  # "pragmas  that  are  not  understood 
by  the  compiler  are  ignored. 

Another  facility  added  was  the  *elif 
(for  else  if)  directive.  It  eliminates  many 
of  the  massive  if.  .  .  endif  structures 
found  in  some  programs. 

Some  compilers  allowed  white  space 
around  the  #,  introducing  a  preproces¬ 
sor  statement,  but  others  did  not.  ANSI 
determined  that  the  white  space  didn’t 
interfere  with  anything,  so  they  decided 
to  allow  it.  This  means  that  white  space 
can  exist  on  either  side  of  the  #and  can 
be  used  to  format  nested  preprocessor 
statements. 

Language 

The  C  language  itself  has  undergone 
many  changes.  Most  of  the  changes  are 
additions,  but  some  are  clarifications 
of  ambiguities  in  K&R  or  changes  that 
may  affect  programming  practices. 

The  keywords  entry,  fortran ,  and 
asm  have  been  deleted  by  ANSI.  No 
one  ever  used  entry,  and  both  fortran 
and  asm  were  considered  non-port- 
able.  ANSI  does  list  fortran  and  asm 
in  the  common  extensions,  though. 

An  ANSI-conformant  compiler  must 
allow  for  case-sensitive  internal  identi¬ 
fiers,  which  can  be  unique  through  their 
31st  character.  The  original  C  compilers 
could  only  handle  six  to  eight  charac¬ 
ter  identifiers.  Because  of  linkages  to 
other  languages  and  older  hardware 
architectures,  however,  external  names 
are  only  required  to  be  six  characters 
long  and  are  not  case  sensitive.  In  a 
future  ANSI  standard,  the  restriction  on 
external  names  will  be  lifted.  Program¬ 
mers  should  be  aware  of  this  change 
because  some  older  programs  may  rely 
upon  a  lesser  number  of  significant 
characters  in  an  internal  identifier. 

One  area  in  which  several  changes 
have  occurred  is  the  declaration  and 
definition  of  functions.  Using  a  con¬ 
cept  from  C++,  the  ANSI  committee 
added  function  prototypes  to  C.  A  pro¬ 
totype  is  a  function  declaration  that 
defines  the  types  of  parameters  for  a 
function.  For  example 


int  funclfchar  *  str,  unsigned  int 

lamount); 

This  statement  declares  that  the  func¬ 
tion  funcl(  0  returns  an  int  and  accepts 
two  parameters:  a  char  pointer  and  an 
unsigned  integer.  The  identifiers  sir  and 
amount  are  optional;  their  inclusion 
can  improve  the  understanding  of  the 
nature  of  the  function.  When  the  com¬ 
piler  processes  a  call  to  fund  (  ),  it  can 
check  to  see  if  the  types  of  the  actual 
arguments  match  those  specified  in  the 
prototype.  This  check  prevents  many 
common  C  errors,  which  occur  when 
incorrect  data  types  are  passed  to  func¬ 
tions.  It  should  be  noted  that  this  type 
checking  can  be  circumvented  through 
the  use  of  proper  casts. 

Prototypes  have  made  minor  changes 
in  how  some  parameters  work.  In  K&R 
C,  float  values  were  automatically  pro¬ 
moted  to  doubles  when  passed  as  pa¬ 
rameters.  Function  prototypes  can  be 
used  to  force  a  float  to  be  passed  as  a 
float.  With  the  new  rules  that  allow 
floats  to  be  used  in  calculations  with¬ 
out  being  promoted  to  doubles,  library 
functions  can  be  created  to  work 
entirely  with  floats.  This  eliminates 
the  possible  overhead  of  doubles  when 
the  extra  precision  is  not  needed. 

The  prototype  style  can  also  be  used 
in  function  definition  headers.  This 
makes  the  headers  resemble  those  from 
a  Pascal  or  Modula-2  program.  Under 
the  new  style  funclC )  would  be  de¬ 
fined  as 

int  funclfchar  *  str,  unsigned  int 

amount) 

( 

/*  program  code  V 

) 

whereas  under  the  old  style  (still  ac¬ 
ceptable  under  ANSI)  it  would  have 
been  written  as 

int  funclfstr,  amount) 

char  *  str; 

unsigned  int  amount; 

I 

/*  program  code  */ 

I 

Under  ANSI,  if  the  parameter  list  in  a 
function  prototype  ends  with  ellipses, 
that  function  can  accept  a  variable  pa¬ 
rameter  list.  This  function 

int  func2(int  val,  .  .  .); 

accepts  one  int  parameter  (type- 
checked)  and  an  implementation-de¬ 
fined  number  of  untyped  parameters. 
The  macros  defined  in  stdarg.b  are  used 
to  extract  the  untyped  parameters. 

A  function  prototyped  with  an  empty 


parameter  list  can  accept  any  number 
of  parameters  of  any  type,  and  calls  to 
it  are  not  type-checked.  You  should 
be  aware  that  many  ANSI  compilers 
enforce  proper  prototyping  through 
warnings  and  errors.  It  is  to  your  ad¬ 
vantage  to  use  the  type-checking  capa¬ 
bilities  found  in  ANSI  C. 

ANSI  has  added  some  new  types. 
The  most  significant  of  these  additions 
is  the  void  type,  void  represents  the 
NULL  set,  in  other  words,  an  object  of 
type  void  has  no  values.  While  this 
might  seem  to  be  a  rather  senseless 
type  it  does  have  some  important  uses. 

For  example,  a  function  that  does 
not  return  a  value  can  be  defined  with 
a  return  value  of  void.  This  eliminates 
the  old  problem  in  K&R  where  these 
functions  implicitly  returned  a  random 
int,  the  value  of  which  was  meaning¬ 
less.  Also,  a  function  can  be  proto¬ 
typed  with  void  in  its  parameter  list, 
indicating  that  the  function  does  not 
accept  any  parameters. 

A  void  pointer  is  a  pointer  to  any¬ 
thing.  K&R  C  used  char  pointers  for 
generic  pointers.  Any  type  of  pointer 
can  be  assigned  to  a  void  * —  and  vice 
versa  —  without  a  cast,  void  pointers 
can  be  used  to  make  functions  that 
access  generic-area  memory  more  con¬ 
veniently.  Under  K&R  C,  mallocC )  re¬ 
turned  a  char  *  pointer,  which  then 
needed  to  be  cast  to  the  pointer  type  it 
was  assigned  to.  The  ANSI  version  of 
malloc( )  returns  a  void  ‘thereby  elimi¬ 
nating  the  need  for  a  cast. 

The  keyword  signed  has  been  added 
by  ANSI.  This  was  in  response  to  the 
need  to  explicitly  declare  a  signed  char 
(or  in  this  case,  a  very  small  integer) 
type  on  implementations  where  the  de¬ 
fault  char  type  was  unsigned.  To  keep 
the  language  consistent,  signed  is  now 
allowed  as  a  qualifier  for  all  integral 
types.  ANSI  also  made  official  the  abil¬ 
ity  to  apply  the  unsigned  qualifier  to 
long  and  short  types. 

A  new  floating-point  type  is  the  long 
double.  It  must  be  at  least  as  precise  as 
a  double.  Some  MS-DOS  implementa¬ 
tions  have  already  included  this  type 
in  10-byte  IEEE  format,  long  float  is, 
however,  no  longer  a  valid  synonym 
for  double. 

const  and  volatile  are  two  new  quali¬ 
fiers.  Adopted  from  C++,  the  const  quali¬ 
fier  locks  in  the  value  of  a  data  item, 
preventing  its  value  from  being  modi¬ 
fied.  For  example, 

const  double  pi  =  3-1415927; 
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would  prevent  the  value  of  pi  from 
being  changed.  When  used  in  a  func¬ 
tion  prototype  and  definition,  the  const 
qualifier  prevents  the  function  from 
changing  that  argument.  Several  ANSI 
prototypes  use  const  to  safeguard 
the  data  accessed  through  pointer 
arguments. 

Under  some  circumstances,  a  data 
item  may  be  changed  by  forces  outside 
the  scope  of  a  program.  The  volatile 
keyword  was  invented  to  inform  the 
compiler  that  a  value  may  change  asyn¬ 
chronously.  This  is  required  for  opti¬ 
mizing  C  compilers  that  can  make  as¬ 
sumptions  about  the  value  of  a  data 
item;  volatile  prevents  these  assump¬ 
tions  from  being  made. 

The  enumeration  type  has  been  in 
common  use  for  years  in  some  C  dia¬ 
lects.  Designated  by  the  enum  key¬ 
word,  an  enumerated  type  defines  a 
special  set  of  related  integer  values. 
For  example 

enum  rank  (first,  second,  third); 

enum  rank  my_rank; 

my_rank  =  first; 

The  value  of  type  rank  can  be  one  of 
three  possible  values,  first,  second ,  and 
third,  first  has  an  integral  value  of  0 , 
second  a  value  of  1 ,  and  third  a  value 
of  2.  An  enumerated  value  can  be  used 
anywhere  an  m/can.  The  compiler  can 
make  checks  to  be  sure  that  a  value  of 
type  rank  is  assigned  only  those  values 
listed  in  the  definition  of  rank  (known 
as  enumeration  constants). 

By  default,  enumeration  constants  are 
assigned  consecutive  integral  values  be¬ 
ginning  with  zero.  Explicit  assignments 
can  be  made,  however,  to  preset  the 
values  of  the  constants.  The  enumera¬ 
tion  type  coin  shows  this  facility: 

enum  coin  (penny=l,  nickel=5, 

dime=10,  quarter=25); 

Several  changes  have  been  made  in 
numeric  constants.  Integral  constants 
are  automatically  stored  as  int,  long , 
or  unsigned  long  values.  The  smallest 
integral  type  that  can  hold  the  constant 
is  used.  A  new  constant  suffix,  t/( or  u), 
can  be  used  to  specify  that  a  constant 
is  unsigned.  As  in  K&R,  a  suffix  of  L  (or 
l)  can  be  used  to  force  the  constant  into 
a  long  value. 

Floating  point  constants  are  auto¬ 
matically  stored  as  doubles ,  unless  the 
constant  has  an  F  (or  j)  suffix.  The  F 
suffix  forces  the  constant  to  be  stored 
as  a  float. 

Many  pre-ANSI  implementations  of 
C  extended  the  uses  of  structured  types. 
These  additions  have  been  adopted  in 


the  ANSI  standard,  and  structures  may 
now  be  passed  in  function  parameters 
by  value.  K&R  did  not  allow  this,  and  all 
structures  had  to  be  referenced  by  pointer 
parameters.  In  addition,  ANSI  allows 
functions  to  have  structures  as  return 
values,  and  assignments  can  be  made 
between  structures  of  the  same  type. 

Early  C  compilers  allowed  both  the 
<operator>=  and  =  <operator>  forms  of 
the  short-cut  assignment  operators.  The 
latter  form  is  somewhat  ambiguous  be¬ 
cause,  for  example,  the  —  operator 
may  indicate  either  subtraction  or  the 
assignment  of  a  negative  value.  There¬ 
fore,  the  ANSI  committee  has  specified 
the  <operator>=  format  as  the  only  valid 
forms  of  these  operators. 

You  will  find  that  there  are  several 
defined  types  in  ANSI  C.  These  types 
were  created  to  aid  in  portability.  The 
K&R  version  of  the  sizeof  operator  re¬ 
turned  an  int ;  ANSI’s  sizeof  returns  a 
value  defined  as  sizejt.  size_t  is  de¬ 
fined  as  an  implementation-specific  in¬ 
tegral  type. 

K&R  defined  a  loose  relationship  be¬ 
tween  pointers  and  integers.  Pointer 
values  could  be  assigned  to  integers 
and  back  again.  Comparisons  between 
pointers  and  integers  were  allowed  but 
the  results  from  such  comparisons  var¬ 
ied  from  implementation  to  implemen¬ 
tation. 

The  ANSI  standard  no  longer  defines 
integers  and  pointers  as  interchange¬ 
able.  The  only  integral  value  that  has 
any  validity  when  compared  to  a  pointer 
is  0.  In  fact,  the  standard  explicitly  de¬ 
fines  a  NULL  pointer  as  having  an  inte¬ 
gral  value  of  0.  Programs  that  rely  upon 
pointer  arithmetic  and  point  integer  con¬ 
versions  may  not  be  ANSI  compatible. 

The  const  qualifier  can  be  used  to 
control  changes  to  the  pointer  and  the 
data  it  points  to.  A  const  int  *  for  exam¬ 
ple,  would  be  a  pointer  to  a  constant 
integer.  The  pointer  can  be  changed 
but  not  the  value  it  points  to.  The  dec¬ 
laration  int  'const denotes  an  unmodi- 
fiable  pointer  to  a  changeable  integer 
value. 

The  only  significant  change  made 
by  ANSI  to  executable  statements  af¬ 
fects  the  switch  statement.  Under  K&R, 
only  int  values  were  allowed  for  the 
controlling  expression,  and  now  they 
may  be  of  any  integral  type,  including 
long  and  unsigned  values. 

Library 

K&R  did  not  specify  a  complete  library 
for  C.  It  discusses  the  standard  I/O  func¬ 
tions  commonly  found  in  stdio.h  and 
several  functions  from  the  Unix  library. 
The  latter  primarily  consists  of  low-level 
I/O  functions,  which  have  been  dropped 
from  the  ANSI  standard  for  portability 


reasons.  An  example  of  a  dynamic  mem¬ 
ory  allocator  is  included  but  malloc( ) 
and  company  are  absent.  No  math  or 
string  functions  are  discussed. 

In  order  to  promote  portable  pro¬ 
grams,  ANSI  created  a  standard  library 
and  a  standard  set  of  headers  to  go 
with  it.  There  are  a  total  of  15  ANSI 
headers.  Some  functions  that  were  de¬ 
fined  by  K&R  in  stdio.h  are  now  found 
in  other  headers  like  stdlib.h.  The  fol¬ 
lowing  is  a  list  of  the  headers  and  a 
short  description  of  the  functions  found 
in  them. 

assert. h  —  Diagnostics  macro 
The  assert  macro  is  commonly  defined 
for  most  existing  C  implementations. 
It  is  used  to  place  diagnostic  tests  in 
programs,  assert  accepts  a  single  pa¬ 
rameter.  When  the  parameter  is  false 
(a  zero  value),  assert  displays  the  name 
of  the  source  file  and  the  current  line 
number  to  the  standard  error  device. 
The  abort( )  function  is  then  called. 

ctype.h  —  Character  handling 
These  functions  not  only  test  charac¬ 
ters  to  see  if  they  are  in  a  certain  range 
but  also  change  the  case  of  certain 
characters.  For  example,  the  isalpha( ) 
function  tests  to  see  if  its  parameter  is 
an  alphabetic  character,  toupperf )  con¬ 
verts  a  lowercase  letter  to  an  uppercase 
one.  The  locale  (see  locale. h  later  in 
this  text)  setting  can  affect  how  these 
functions  work.  In  K&R,  these  facilities 
were  defined  in  stdio.h. 

ermo.h  —  Standard  errors 
Several  library  functions  return  error 
code  in  a  value  called  ermo,  which  is 
defined  in  this  header  along  with  its 
possible  values.  These  error  values  are 
highly  implementation-dependent. 

float. h  —  Floating-point  limits 
There  are  several  macros  in  this  header 
that  expand  to  values  for  limits  and 
ranges  for  floating-point  values. 

limits,  h  —  Integer  limits 
This  header  is  similar  to  float. h  but 
defines  limits  and  ranges  for  integral 
values. 

locale,  h  —  Localization 
In  making  C  an  international  language, 
it  became  clear  that  a  mechanism 
was  needed  to  allow  country-  or  loca¬ 
tion-specific  information  to  be  set. 
Things  such  as  decimal  point  charac¬ 
ters  and  currency  characters  change 
from  place  to  place.  The  macros,  struc- 
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tures,  and  functions  found  in  locale,  h 
help  make  writing  portable  programs 
easier. 

math.h  —  Mathematics 
Mathematical  functions  have  always 
been  a  part  of  C  but  until  ANSI  they 
were  largely  implementation-defined. 
This  header  declares  functions  for  trigo¬ 
nometric,  hyperbolic,  logarithmic,  and 
utility  operations. 

setjmp.h  —  Non-local  jumps 
Using  the  setjmp( )  macro  and  the 
longjmp( )  function,  a  program  can  lit¬ 
erally  jump  from  any  location  within 
itself  to  any  other.  While  the  capability 
may  violate  the  principles  of  structured 
program  design,  it  can  be  useful  when 
an  exception  condition  occurs  in  a 
deeply-nested  portion  of  a  program. 

signal  h  —  Signal  handling 
A  signal  is  an  exception  condition.  The 
functions  signal(  )  and  raise(  )  provide 
a  portable  method  for  handling  excep¬ 
tions,  such  as  program  breaks  and  float¬ 
ing-point  errors.  These  ANSI  functions 
are  based  on  those  defined  for  Unix. 
raise( )  replaces  the  Unix  kill( )  and 
eliminates  the  latter’s  support  for 
multiprocessing.  ANSI  implemented  a 
subset  of  the  signals  defined  for  Unix 
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and  allows  each  implementation  to  de¬ 
fine  signals  of  their  own. 

stdarg.h  —  Variable  arguments 
Defined  in  this  header  are  a  set  of 
macros  that  can  be  used  to  write  port¬ 
able  functions  accepting  variable  num¬ 
bers  of  parameters.  Many  compilers  pro¬ 
vide  a  different  set  of  macros  based 
on  the  Unix  V  compile.  In  my  experi¬ 
ence,  the  ANSI  macros  are  clearer  and 
easier  to  use  than  the  Unix  macros. 

stddef.h  —  Common  definitions 
ANSI  defined  a  number  of  standard 
types  and  macros  most  of  them  are 
here  and  some  may  be  repeated  in 
other  headers  as  well.  Among  the  defi¬ 
nitions  in  stddef.h  are:  NULL,  size_t(. the 
return  value  type  of  the  sizeof  opera¬ 
tor),  and  the  offsetof  macro.  An  inven¬ 
tion  of  ANSI,  offsetof  is  a  macro  that 
determines  the  byte-offset  of  a  member 
within  a  structure. 

stdio.h  —  output 

This  header  defines  and  prototypes  most 
of  the  functions  listed  in  Chapter  7  of 
K&R.  Few,  if  any,  changes  were  made 
in  the  definitions  found  in  K&R  but 
several  new  functions  have  been  added. 
There  are  now  functions  for  working 
with  temporary  files  (with  random, 


unique  names).  remove( )  deletes  files 
and  replaces  the  Unix-specific  unlink( ). 
Using  setvbuf( )  (borrowed  from  Unix 
V),  the  programmer  can  control  the 
buffering  of  I/O  streams.  Two  new  file 
positioning  functions,  fgetpos( )  and  fset- 
pos( ),  have  been  added  to  handle  files 
longer  than  fseek( )  can  cope  with. 

stdlib.h  —  General  utilities 
This  is  the  “kitchen  sink”  header,  con¬ 
taining  definitions  and  prototypes  for 
a  wide  variety  of  unrelated  functions. 
Included  are  numeric-to-string  conver¬ 
sions:  the  malloc( )  family  of  memory 
allocation  functions,  random  number 
functions,  abort  and  exit  facilities,  bi¬ 
nary  search  and  quicksort  functions, 
multibyte  character  functions  (for  work¬ 
ing  with  foreign  alphabets),  and  mis¬ 
cellaneous  integer  functions.  Many  ex¬ 
isting  compilers  have  their  own  head¬ 
ers  for  these  functions,  and  you  may 
need  to  determine  how  many  of  the 
non-standard  headers  are  still  required. 

string. h  —  String  handling 
Here  is  where  you’ll  find  the  functions 
for  manipulating  strings.  Most  of  these 
functions  have  been  around  as  long  as 
C  has,  and  several  are  defined  in  K&R. 
Also  included  in  the  header  are  proto¬ 
types  for  the  memory  functions,  which 
work  similar  to  the  string  copy/move/set 
functions.  The  memory  functions  are 
designed  for  modifying  memory  through 
generic  (non-character)  pointers. 

time.h  —  Date  and  time 
While  date  and  time  functions  exist  in 
most  C  libraries,  there  is  almost  no 
standardization  between  implementa¬ 
tions.  ANSI  designed  the  functions  de¬ 
clared  in  this  header  to  provide  a  full 
spectrum  of  date  and  time  facilities. 
Conversion  functions  are  provided  to 
convert  integral  times  to  structures  to 
text  strings. 

Converting  to  ANSI  may  mean  mak¬ 
ing  minor  changes  in  the  library  facili¬ 
ties  you  use  and  how  you  use  them. 

Conclusions 

I  hope  that  this  overview  gives  you  a 
sense  of  the  effects  the  ANSI  standard 
will  have  on  your  programming  style 
and  existing  applications.  Converting 
old  programs  to  ANSI  C  should  not  be 
an  arduous  task.  We  should  all  be  grate¬ 
ful  to  the  X3J1 1  committee  for  the  work 
that  they  have  done;  their  standard  will 
help  move  C  into  the  1990s. 
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A  Generic  Heapsort 
Algorithm  in  C 

Heapsort  is  an  excellent  sorting  algorithm  for 
many  applications 


Stephen  Russell 


When  faced  with  the  prob¬ 
lem  of  sorting  data,  many 
programmers  choose  a  sim¬ 
ple  algorithm,  such  as  in¬ 
sertion  or  selection  sort,  or 
maybe  Shellsort.  Quicksort  is  another 
common  choice,  at  least  for  languages 
that  support  recursion:  The  qsort  li¬ 
brary  function  makes  this  choice  par¬ 
ticularly  easy  for  C  programmers.  Sur¬ 
prisingly  few  programmers  choose  the 
Heapsort  algorithm,  perhaps  because 
it  is  not  an  intuitive  algorithm:  The 
other  algorithms  are  certainly  easier  to 
understand.  Heapsort,  however,  has 
some  advantages  over  its  competitors. 

With  Heapsort,  the  time  taken  to  sort 
n  items  is  proportional  to  n  log  n ,  re¬ 
gardless  of  the  initial  order  of  the  data. 
In  comparison,  although  Quicksort  has 
an  average  performance  of  n  log  n, 
some  data  cause  it  to  execute  in  time 
proportional  to  n2.  The  other  algorithms 
also  have  a  worst-case  performance  of 
n2.  When  sorting  large  amounts  of  data, 
the  difference  between  a  guaranteed 
speed  of  n  log  n  versus  a  worst-case 
of  n2  is  significant. 

In  addition,  Heapsort  is  not  a  recur¬ 
sive  algorithm,  making  it  suitable  for 
languages  — such  as  Basic  and  Fortran  — 
that  do  not  support  recursion.  Even  for 
languages,  such  as  Pascal  and  C,  elimi¬ 
nating  the  recursion  may  lead  to  a  faster 
algorithm,  depending  on  the  cost  of 
procedure  calls.  The  cost  of  saving  and 
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restoring  registers  for  each  call  may  be 
significant  on  some  machines. 

Heapsort,  however,  has  its  disadvan¬ 
tages.  For  small  sets  of  data,  the  sim¬ 
pler  algorithms  may  actually  perform 
better,  due  to  their  lower  overheads. 
Choosing  the  right  algorithm  for  a  par¬ 
ticular  application  requires  careful  analy¬ 
sis  and  knowledge  of  the  tradeoffs  in¬ 
volved.  Books  on  algorithm  design,  such 
as  Sedgewick’s  Algorithms  (Addison- 
Wesley,  1983)  and  Gonnet’s  Handbook 
of  Algorithms  and  Data  Structures  (Ad- 
dison-Wesley,  1984),  provide  useful 
guides  to  help  make  the  right  choice. 

Even  with  these  caveats,  Heapsort 
is  a  strong  candidate  for  inclusion  in  a 
programmer’s  library  of  standard  tools. 


Figure  1:  Construction  of  a  heap 


The  rest  of  this  article  describes  a  ge¬ 
neric  Heapsort  function,  modelled  on 
the  C  qsort  function.  This  function  al¬ 
lows  an  arbitrary  array  of  data  to  be 
sorted,  when  provided  with  a  function 
to  compare  elements  of  the  array. 

How  Heapsort  Works 

The  Heapsort  algorithm  is  based  on 
an  interesting  data  structure  — the  heap. 
Heaps  are  typically  used  for  applica¬ 
tions  in  which  the  maximum  or  mini¬ 
mum  value  is  needed  from  a  changing 
collection  of  data.  When  an  item  is 
added  to  or  removed  from  a  heap,  the 
heap  can  be  rearranged  to  find  the  new 
maximum  (or  minimum)  value  in  log 
n  steps.  This  process  is  a  very  efficient 
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way  to  implement  priority  queues,  and 
it  forms  the  basis  of  Heapsort. 

A  heap  is  a  partially  ordered  array 
of  data,  organized  as  a  special  form  of 
binary  tree,  with  the  following  proper¬ 
ties.  First,  for  each  node  in  the  tree,  the 
node’s  value  is  greater  than  the  values 
of  either  of  its  child  nodes,  which  im¬ 
plies  that  the  root  of  the  tree  contains 
the  maximum  value  of  all  the  nodes.  If 
the  minimum  value  is  needed  instead, 
each  node  must  have  a  lesser  value 
than  its  children.  Second,  the  tree  is 
fully  balanced,  and  each  level  of  the 
tree  is  filled  from  left  to  right.  This 
property  allows  the  tree  to  be  con¬ 
structed  using  an  array,  rather  than  ex¬ 
plicit  pointers.  If  the  first  item  of  a  heap 
His  H[l],  then  its  two  children  are  H[2] 
and  H/3/  Similarly,  the  children  of  H[2] 
are  H[4]  and  H[5].  In  general,  the  chil¬ 
dren  of  H[i]  are  H[2i]  and  H!2i+1],  and 
the  parent  of  H[k] is  H[k/2], 

Converting  an  array  of  arbitrary  data 
to  a  heap  involves  rearranging  the  val¬ 
ues  in  the  array  until  the  ordering  prop¬ 
erty  of  a  heap  is  satisfied.  This  conver¬ 
sion  is  usually  realized  by  working 
through  the  tree  from  the  bottom  up. 
For  array  H  containing  n  items,  start 
by  considering  the  last  item  that  could 
have  children  — H[k],  where  k  is  n/2. 
H[k]  is  compared  to  its  children  H[2k] 
and  H[2k+1],  If  H[k]  is  less  than  one  or 
both  of  its  children,  it  is  swapped  with 
the  greater  child,  say  H[j],  Then  com¬ 
pare  the  new  value  in  H[j]  with  its  two 
children,  and  perform  another  swap  if 
needed.  Eventually,  you  will  reach  a 
node  that  has  no  children,  or  a  spot 
where  no  swap  is  needed.  At  this  point, 
the  subtree  starting  at  H[k]  is  organized 
as  a  heap.  This  process  is  performed 
for  all  values  of  k  from  n/2  to  1.  After 
the  last  iteration,  the  array  is  a  heap, 
and  H[l]c ontains  the  maximum  value. 
Figure  1  shows  the  process  of  con¬ 
structing  a  heap  from  a  collection  of 
numbers.  The  tree  structure  of  the  heap 
is  shown  in  Figure  2. 

The  Heapsort  Algorithm 

Heapsort  works  in  two  phases.  In  the 
first  phase,  the  data  is  rearranged  in  the 
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Figure  2:  The  tree  structure  of  the  heap 


array  to  form  a  heap;  this  moves  the 
maximum  data  value  to  the  first  posi¬ 
tion  of  the  array.  In  the  second  phase, 
the  maximum  value  is  swapped  with 
the  last  element  in  the  heap,  and  the 
size  of  the  heap  is  reduced  by  one. 
This  phase  puts  the  maximum  data  value 
in  its  final  position  in  the  array.  How¬ 
ever,  the  element  now  occupying  the 
first  position  may  not  be  the  next  maxi¬ 
mum:  The  next  maximum  is  found  by 
rearranging  the  remaining  elements  of 
the  heap.  The  process  of  finding  the 

Heapsort  is  not  a 
recursive  algorithm. 
This  makes  it  suitable 
for  languages,  such  as 
Basic  and  Fortran  that 
do  not  support 
recursion 


maximum  value  in  the  heap,  and  mov¬ 
ing  it  to  its  final  position,  continues 
until  the  heap  is  reduced  to  a  single 
element.  Figure  3  shows  Heapsort  in 
operation  for  the  heap  constructed  in 
Figure  1. 

Listing  One  (page  86)  shows  an  im¬ 
plementation  of  the  Heapsort  algorithm 
for  sorting  an  array  of  integer  values. 
Most  of  the  work  is  performed  by  the 
function  call  fixheap(h,  i,  n),  which  en¬ 
sures  that  the  subheap  starting  at  posi¬ 
tion  h[il  is  correctly  ordered.  As  I  de¬ 
scribed  previously,  the  value  of  i  goes 
from  n/2  to  1  while  constructing  the 
heap.  In  the  second  phase,  the  value 
of  i  is  always  1,  with  the  value  of  n 
decreasing  as  each  maximum  value  is 
extracted  from  the  heap. 

The  fact  that  arrays  in  C  are  indexed 
from  0,  rather  than  7,  is  adjusted  for  in 


Element 

Address 

h[0] 

baseO 

h[1] 

baseO  +  size 

h[i] 

baseO  +  gap 

h[2i] 

baseO  +  gap  +  gap 

h[2i+1] 

baseO  +  gap  +  gap  +  size 

Table  1:  The  relationship  between  the 
heap  elements  and  expressions 
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(continued  from  page  82) 
the  first  statement  in  hsort( )  by  de¬ 
crementing  the  pointer  to  the  base  of 
the  array.  This  adjustment  allows  the 
rest  of  the  algorithm  to  consider  the 
array  as  starting  at  h[l], 

A  Generic  Heapsort 

The  hsort( )  function  in  Listing  One 
can  be  easily  changed  to  sort,  for  ex¬ 
ample,  arrays  of  float  or  char  values. 
With  a  little  extra  effort,  hsort( )  can 
also  sort  data  that  are  accessed  indi¬ 
rectly  through  an  array  of  pointers,  or 
data  with  multiple  sort  keys.  Having  to 
modify  the  algorithm  each  time  a  par¬ 
ticular  sort  is  needed,  though,  is  incon¬ 
venient  and  error-prone.  A  generic  Heap- 
sort  is  needed  that  can  sort  arbitrary 
data  when  provided  with  an  appropri¬ 
ate  function  to  compare  values.  Such 
a  function  is  shown  in  Listing  Two 
(page  86). 

Modelled  on  the  C  qsort( )  library 
function,  the  version  of  hsortC )  shown 
in  Listing  Two  sorts  an  array  of  n  items, 
with  each  element  “size”  bytes  in  length. 
The  cmp  argument  is  a  pointer  to  a 
comparison  function.  Each  time 
fixheapC Sneeds  to  compare  elements, 
it  calls  this  function,  passing  the  ad¬ 
dresses  of  the  two  items  as  arguments. 
The  function  then  returns  a  value  less 
than,  equal  to,  or  greater  than  zero, 
depending  on  whether  the  first  item  is 
less  than,  equal  to,  or  greater  than  the 
second. 


The  version  of  hsort( )  in  Listing  Two 
is  derived  directly  from  the  simple  ver¬ 
sion  in  Listing  One.  Unfortunately,  each 
calculation  of  the  address  of  an  ele¬ 
ment  involves  a  multiplication  by  the 
size  of  the  elements.  On  many  comput¬ 
ers,  multiplication  instructions  are  slow. 
It  is  possible,  however,  to  rewrite  the 
algorithm  to  eliminate  these  multiplica¬ 
tions  completely.  This  leads  to  a  sig- 

Heapsort  is  a  strong 
candidate  for  inclusion 
in  a  programmer’s 
library  of  standard  tools 


nificant  speed  improvement.  A  further 
increase  in  speed  can  be  gained  by 
expanding  the  calls  to  fixheapC )  and 
swap( )  inline. 

The  final  version  of  Heapsort  is  given 
in  Listing  Three  (page  86).  It  is  derived 
from  the  algorithm  in  Listing  Two  by 
performing  induction  variable  elimina¬ 
tion,  as  might  be  done  by  an  optimiz¬ 
ing  compiler.  The  critical  optimization 
is  calculating  the  distance  in  bytes  be¬ 
tween  the  addresses  of  the  elements 
h[0],  hfij,  and  h[2il  For  a  given  value 
of  i,  the  distance  is  i  *  size ,  where  size 


is  the  size  of  each  element.  Table  1 
shows  the  relationship  between  the 
heap  elements  and  expressions  for  their 
addresses.  The  variable  gap  is  the  cal¬ 
culated  distance,  and  baseO  is  the  ad¬ 
dress  of  the  element  h[0]. 

The  next  step  is  to  note  that  as  i 
decreases  during  the  heap  construction 
phase,  the  value  of  gap  is  reduced  by 
size  for  each  iteration.  The  initial  value 
for  gap  is  n  *  size  /  2,  and  it  is  the  only 
step  where  multiplication  is  required. 
The  address  of  h[n]  is  also  calculated 
and  stored  in  the  variable  hi.  During 
the  second  phase  of  the  sort,  the  value 
of  hi  is  decreased  by  size  for  each 
iteration,  which  corresponds  to  decre¬ 
menting  n.  Although  these  optimizations 
result  in  a  more  complex  algorithm, 
they  are  worthwhile  given  its  intended 
use  as  a  standard  library  function. 

Using  hsort() 

Listing  Four  (page  88)  shows  an  exam¬ 
ple  that  uses  hsort( )  to  sort  an  array  of 
strings,  which  are  read  from  input.  Each 
element  of  the  array  is  of  type  char  *. 
The  cmp( )  function  is  passed  two 
char  **  pointers  and  uses  strcmp( )  to 
compare  the  strings.  After  the  strings 
are  sorted,  they  are  written  to  standard 
output. 

Conclusion 

The  algorithms  presented  in  this  article 
cover  a  range  of  complexity  and  versa¬ 
tility.  For  some  applications,  the  simple 
algorithm  given  in  Listing  One  may 
perform  best,  and  it  provides  a  skele¬ 
ton  that  can  be  extended  for  special 
purposes.  The  generic  Heapsort  given 
in  Listing  Three  provides  a  useful  li¬ 
brary  function,  which  can  be  used  at 
any  time  data  need  sorting.  Its  general¬ 
ity,  however,  does  incur  a  small  cost 
in  performance  compared  to  a  special- 
purpose  sort.  This  cost  will  be  accept¬ 
able  for  most  applications.  Choosing 
the  right  approach  is,  of  course,  part 
of  the  craft  of  programming. 

Availability 

All  source  code  for  articles  in  this  issue 
is  available  on  a  single  disk.  To  order, 
send  $14.95  (Calif,  residents  add  sales 
tax)  to  Dr.  Dobbs  Journal ,  501  Galves¬ 
ton  Dr.,  Redwood  City,  CA  94063;  or 
call  800-356-2002  (from  inside  Calif.) 
or  800-533-4372  (from  outside  Calif.). 
Please  specify  the  issue  number  and 
format  (MS-DOS,  Macintosh,  Kaypro). 

DDJ 

(Listings  begin  on  page  86.) 

Vote  for  your  favorite  feature/article. 
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Listing  One  (Text  begins  on  page  81.) 

Listing  Three 

/* 

/* 

*  Generic  Heapsort . 

*  Use  Heapsort  to  sort  an  array  of  n  integers. 

*  Synopsis: 

*/ 

*  hsort (char  ‘base,  unsigned  n,  unsigned  size,  int  (*fn)()) 

static 

*  Description: 

fixheapfh,  i,  n) 

*  Hsort  sorts  the  array  of  'n'  items  which  starts  at  address  'base' . 

int  *h; 

*  The  size  of  each  item  is  as  given.  Items  are  compared  by  the  function 

unsigned  i,  n; 

*  'fn',  which  is  passed  pointers  to  two  items  as  arguments.  The  function 

( 

*  should  return  <  0  if  iteml  <  item2,  ==  0  if  iteml  ==  item2,  and  >  0 

unsigned  k; 

*  if  iteml  >  item2 . 

int  tmp; 

*  Version: 

*  1988  April  28 

while  ( (k  =  2  *  i)  <=  n)  /*  h [ k ]  =  left  child  of  h[i]  */ 

*  Author: 

{ 

/*  Find  maximum  of  left  and  right  children  */ 

*  Stephen  Russell,  Department  of  Computer  Science, 

*  University  of  Sydney,  2006 

if  (k  !=  n  &&  h [k+1]  >  h[k] ) 

*  Australia. 

++k;  /*  right  child  is  greater  */ 

*/ 

/*  Compare  greater  of  children  to  parent  */ 
if  (h [ i ]  >-  h [k] ) 

#ifdef  INLINE 

return; 

♦define  swap (pi,  p2,  n)  {\ 

register  char  *  pi,  *  p2;\ 
register  unsigned  n;Y 

/*  Parent  is  less  than  child,  so  swap  */ 

tmp  =  h[k];  h[k]  =  h [ i] ;  h[i]  =  tmp; 

register  char  tmp;\ 

i  =  k;  /*  move  down  tree  */ 

\ 

} 

} 

for  (  pi  =  pi,  p2  =  p2,  n  =  n;  n —  >0;  )\ 

[\ 

hsort(h,  n) 

tmp  =  *  pi;  *  pl++  =  *  p2;  *  p2++  =  tmp;\ 

)\ 

int  *h; 
unsigned  n; 

}\ 

f 

♦  else 

unsigned  i; 
int  tmp; 

/* 

— h;  /*  adjust  for  zero-origin  arrays  in  C 

*  Support  routine  for  swapping  elements  of  the  array. 

*/ 

*/ 

for  (i  *  n/2;  i  >  1;  — i) 

fixheap(h,  i,  n);  /*  build  heap,  exceDt  for  h [ 1 ] 

*/ 

static 

while  (n  >  1) 

{ 

fixheap(h,  1,  n);  /*  move  max  to  h[l]  */ 

swap(pl,  p2,  n) 
register  char  *pl,  *p2; 

register  unsigned  n; 

< 

tmp  =  h [ 1 ] ;  /*  move  max  to  final  position  */ 

h[l]  =  h[n] ; 
h[n]  =  tmp; 

register  char  ctmp; 

— n;  /*  reduce  size  of  heap  */ 

/* 

} 

} 

*  On  machines  with  no  alignment  restrictions  for  int's, 

*  the  following  loop  may  improve  performance  if  moving  lots 

*  of  data.  It  has  been  commented  out  for  portability. 

register  int  itmp; 

End  listing  One 

for  (  ;  n  >  sizeof(int);  n  -=  sizeof(int)) 

Listing  Two 

itmp  =  *  (int  *) pi; 

Mint  *)pl  =  Mint  *)p2; 
pi  +=  sizeof  (int) ; 

/* 

Mint  *)p2  =  itmp; 

*  Generic  Heapsort,  derived  from  Listing  One. 

p2  +=  sizeof (int) ; 

) 

♦define  H{k)  (h  +  k  *  size) 

*/ 

while  (n —  !=  0) 

static 

{ 

swap (pi,  p2,  n)  /*  swap  n  bytes  */ 

char  *pl,  *p2; 
unsigned  n; 

ctmp  =  *pl ;  »pl++  =  *p2;  *p2++  =  ctmp; 

) 

} 

char  tmp; 

♦endif 

while  (n —  !=  0) 

/* 

{ 

tmp  =  *pl;  *pl++  =  *p2;  *p2++  =  tmp; 

} 

*  To  avoid  function  calls  in  the  inner  loops,  the  code  responsible  for 

*  constructing  a  heap  from  (part  of)  the  array  has  been  expanded  inline. 

*  It  is  possible  to  convert  this  common  code  to  a  function.  The  three 

*  parameters  baseO,  cmp  and  size  are  invariant  -  only  the  size  of  the 

*  gap  and  the  high  bound  of  the  array  change.  In  phase  1,  gap  decreases 

) 

static 

*  while  hi  is  fixed.  In  phase  2,  gap  ==  size,  and  hi  decreases.  The 

fixheap(h,  size,  cmp,  i,  n) 

*  variables  p,  q,  and  g  are  only  used  in  this  common  code. 

char  *h; 

*/ 

unsigned  size,  i,  n; 
int  (*cmp)(); 

( 

hsort (base,  n,  size,  cmp) 
char  ‘base; 

unsigned  n; 

unsigned  k; 

unsigned  size; 

while  ( (k  =  2  *  i)  <=  n) 

int  (*cmp)(); 

if  (k  ! =  n  &S  (*cmp) (H (k+1) ,  H(k))  >  0) 

register  char  *p,  *q,  ‘baseO,  ‘hi; 

++k; 

register  unsigned  gap,  g; 

if  ((‘cmp)  (H  (i) ,  H  (k)  )  >=  0) 

if  (n  <  2) 

return; 

swap(H(i),  H(k),  size); 
i  =  k; 

) 

return; 

baseO  =  base  -  size;  /*  set  up  address  of  h [ 0 ]  */ 

/* 

*  The  gap  is  the  distance,  in  bytes,  between  h[0]  and  h[i], 

) 

*  for  some  i.  It  is  also  the  distance  between  h[i]  and  h[2*i]; 

*  that  is,  the  distance  between  a  node  and  its  left  child. 

hsort (h,  n,  size,  cmp) 

*  The  initial  node  of  interest  is  h [ n/2 ]  (the  rightmost 

char  *h; 

*  interior  node),  so  gap  is  set  accordingly.  The  following  is 

unsigned  n,  size; 

*  the  only  multiplication  needed. 

int  (*cmp)(); 

{ 

*/ 

gap  =  (n  »  1)  *  size;  /*  initial  gap  is  n/2*size  */ 

unsigned  i; 

hi  =  baseO  +  gap  +  gap;  /*  calculate  address  of  h[n]  */ 

h  -=  size; 

if  (n  &  1) 

for  (i  =  n/2;  i  >  1;  — i) 

hi  +=  size;  /*  watch  out  for  odd  arrays  */ 

fixheap(h,  size,  cmp,  i,  n) ; 

/* 

while  (n  >  1) 

{ 

*  Phase  1:  Construct  heap  from  random  data. 

*  For  i  =  n/2  downto  2,  ensure  h[i]  is  greater  than  its 

fixheap(h,  size,  cmp,  1,  n) ; 
swap(H(l),  H(n),  size); 

— n; 

*  children  h ( 2 * i ]  and  h[2*i+l).  By  decreasing  'gap'  at  each 

*  iteration,  we  move  down  the  heap  towards  h(2] .  The  final  step 

*  of  making  h [ 1 ]  the  maximum  value  is  done  in  the  next  phase. 

) 

} 

End  Listing  Two 

(continued  on  page  88) 
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listing  Three  (Listing  continued,  text  begins  on  page  81.) 

swap (base,  hi,  size);  /*  move  largest 

) 

) 

item  to  end  */ 

for  (  ;  gap  !=  size;  gap  -=  size) 

1 

End  Listing  Three 

/*  fixheap (baseO,  size,  cmp,  gap,  hi)  */ 

for  (p  =  baseO  +  (g  =  gap);  (q  =  p  +  g)  <=  hi;  p  =  q) 

Listing  Four 

{ 

g  +=  g;  /*  double  gap  for  next  level  */ 

/* 

/* 

*  Find  greater  of  left  and  right  children. 

*  Use  hsortO  to  sort  an  array  of  strings  read  from  input. 

*/ 

♦include  <stdio.h> 

if  (q  !=  hi  &&  (*cmp)  (q  +  size,  q)  >  0) 

{ 

♦define  MAXN  500 

♦define  MAXSTR  1000 

q  +=  size;  /*  choose  right  child  */ 

cmp (pi,  p2) 

g  +=  size;  /*  follow  right  subtree  */ 

} 

/* 

*  Compare  with  parent. 

char  **pl,  **p2; 

return  strcmp(*pl,  *p2); 

if  { (*cmp) (p,  q)  >=  0) 

break;  /*  order  is  correct  */ 

static  char  *string [MAXN] ; 

static  char  buf [MAXSTR) ; 

swap(p,  q,  size);  /*  swap  parent  and  child  */ 

) 

extern  char  *gets(); 

) 

extern  char  *malloc(); 

/* 

main () 

*  Phase  2:  Each  iteration  makes  the  first  item  in  the 

{ 

*  array  the  maximum,  then  swaps  it  with  the  last  item,  which 

char  *p; 

*  is  its  correct  position.  The  size  of  the  heap  is  decreased 

int  i,  n; 

*  each  iteration.  The  gap  is  always  "size",  as  we  are  interested 

for  (n  =  0;  gets (buf);  ++n) 

( 

*  in  the  heap  starting  at  h[l]. 

*/ 

if  (n  ==  MAXN) 

for  (  ;  hi  !■  base;  hi  -=  size) 

fprintf (stderr,  "Too  many  strings\n"); 

( 

exit  (1) ; 

/*  fixheap (baseO,  size,  cmp,  gap  (==  size),  hi)  */ 

) 

p  *  base;  /*  ==  baseO  +  size  */ 

p  =  malloc(strlen(buf)  +  1); 

for  (g  =  size;  (q  =  p  +  g)  <=  hi;  p  =  q) 

if  (p  ==  (char  *)NULL) 

g  +=  g; 

fprintf (stderr,  "Out  of  memory\n"); 

if  (q  !-  hi  &&  (*cmp)  (q  +  size,  q)  >  0) 

exit  (2) ; 

q  +=  size; 

g  +=  size; 

strcpy (string [n]  =  p,  buf); 

if  ( (*cmp)  (p,  q)  >=  0) 

hsort (string,  n,  sizeof  string [0],  cmp); 

break; 

for  (i  =  0;  i  <  n;  ++i) 
puts (string[i) ) ; 

swap(p,  q,  size); 

) 

exit (0) ; 

) 

End  Listings 

88 


Dr.  Dobb’s Journal,  August  1989 

551 


This  month  Scott  Ladd  re¬ 
ports  the  benchmark  results 
as  part  of  a  follow-up  on  the 
review  he  presented  in  the 
May  issue:  “QuickC  versus 
Turbo  C.  ”  In  addition,  the 
Doctor  examines  Compu- 
View’s  “VEdit  Plus,  ”  Magna 
Carta ’s  “C  Windows  Toolkit,  ” 
and  Genus’s  “PCX Program¬ 
ming  Toolkit.  ” 


Benchmarking 
Turbo  C  and 
QuickC 


Wrapping  up  the 
comparison 


Scott  Robert  Ladd 

This  benchmark  report  is  a  follow¬ 
up  to  the  comparative  review 
of  Microsoft’s  QuickC  2.0  and 
Borland's  Turbo  C  2.0  that  ap¬ 
peared  in  the  May  issue.  That 
article  was  a  qualitative  comparison. 
This  one  is  quantitative  and  measures 
the  performance  of  the  two  under  simi¬ 
lar  conditions.  As  I’ve  said  before  and 
I’ll  say  again,  no  set  of  benchmarks  can 
truly  reveal  how  good  a  product  is.  The 
only  purpose  benchmarks  serve  is  to 
give  a  general  idea  of  how  well  a  given 
compiler  performs  on  certain  types  of 
code.  (And  speaking  of  code,  because 
of  space  constraints,  I’m  not  including 
the  programs  used  to  generate  the  re¬ 
sults.  If  you’d  like  to  see  them,  though, 
they’ll  be  posted  on  DDJ s  CompuServe 
forum  and  are  available  through  the 
DDJ  editorial  offices.) 

For  this  comparison,  I  used  five  tests 
whose  results  appear  in  Table  1.  Dhry- 

Scott  Ladd  is  a  full-time,  free-lance 
computer  journalist.  You  can  reach 
him  at  705  W  Virginia,  Gunnison, 
CO  81230. 
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stone  2  is  an  updated  version  of  the 
famous  Dhrystone  benchmark,  which 
represents  the  statistical  "average”  pro¬ 
gram.  Because  Dhrystone  comes  in 
three  files,  it  made  an  excellent  test  for 
the  make  facilities. 

FXREF  is  a  filter.  It  reads  in  a  text  file 
from  standard  input,  and  builds  a  bi¬ 
nary  tree  of  the  text  tokens  and  their 
line-number  references.  Once  the  file 
has  been  read  and  displayed,  a  cross 
reference  is  printed  from  the  binary 
tree.  I  have  used  FXREF  in  the  past  as 
a  useful  benchmark  of  I/O  and  dy¬ 
namic  memory  allocation  speed. 

Both  compilers  provide  a  graphics 
library,  and  thus  was  born  the  GRAPH 
benchmark.  It  is  actually  a  simple,  three- 
part  test.  Part  one  tests  line-drawing 
speed,  part  two  looks  at  the  quickness 
of  drawing  ellipses,  and  part  three  times 
the  rapidity  of  filling  an  irregular  area 
with  a  solid  color.  Two  separate  pro¬ 
grams  were  created,  one  for  each  com¬ 
piler,  due  to  the  differences  in  initiali¬ 
zation  code  and  function  names. 

GRIND  is  a  report  program.  It  reads 
1000  floating  point  numbers  from  disk 
and  sorts  them,  then  calculates  a  table 


of  values,  which  it  writes  to  disk. 

Many  floating  point  benchmarks  test 
the  speed  of  library  functions  more 
than  the  quality  of  floating  point  code 
generated.  DMATH  solves  this  prob¬ 
lem  by  avoiding  the  use  of  any  library 
functions.  All  variables  in  the  program, 
including  loop  counters,  are  doubles. 
DMATH  calculates  the  sines  of  all  of 
the  angles  from  0  to  359  degrees,  using 
a  simple  series. 

The  benchmarks  were  conducted  on 
an  Intel-motherboard  80386  machine 
running  at  16  MHz.  The  computer  was 
equipped  with  an  80387  coprocessor, 
2  Mbytes  of  memory,  and  an  EGA  card 
and  monitor.  Timing  was  performed 
by  a  program  that  resets  the  interrupt 
timer  to  l/100th  of  a  second  of  accu¬ 
racy,  and  each  timed  test  result  is  the 
average  of  five  iterations.  Tests  were 
run  for  both  the  emulator  and  copro¬ 
cessor  floating-point  packages,  when¬ 
ever  possible.  All  times  for  compiles 
and  links  are  for  the  command-line  ver¬ 
sions.  QuickC's  incremental  compilation 
and  linking  would  speed  it  up  immensely 
on  developmental  program  builds.  Com¬ 
pile  speeds  were  tested  with  all  debug 


Benchmark  Test 

Borland 

Turbo  C  2.0 

Microsoft 

QuickC  2.0 

timings  (seconds) 

compile 

11.80 

12.42 

link 

5.28 

9.56 

run 

19.45 

18.67 

Dhrystones/second 

2,571 

2,678 

.EXE  size  (bytes) 

9,692 

11,405 

DMATH 

timings  (seconds) 

compile 

7.31 

9.28 

link 

7.90 

10.82 

run 

emulator 

170.21 

194.76 

coprocessor 

5.44 

5.38 

.EXE  size  (bytes) 

emulator 

20,546 

1 7,578 

coprocessor  only 

10,706 

9,786 

FXREF 

timings  (seconds) 

compile 

9.81 

11.54 

link 

5.16 

9.84 

overall  run 

31.47 

26.90 

.EXE  size  (bytes) 

8,710 

9,461 

GRAPH 

timings  (seconds) 

compile 

9.28 

11.59 

link 

10.16 

23.20 

emulator  run 

158.85 

53.61 

coprocessor  run 

158.52 

53.28 

.EXE  size  (bytes) 

emulator 

38,720 

43,312 

coprocessor 

28,864 

35,520 

GRIND 

timings  (seconds) 

compile 

9.10 

11.26 

link 

7.91 

15.38 

run 

emulator 

28.10 

30.43 

coprocessor 

17.74 

15.00 

.EXE  size  (bytes) 

emulator 

25,976 

27,340 

coprocessor 

16,136 

19,548 

Table  1:  QuickC  versus  Turbo  C  benchmark  results 
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options  and  warnings  turned  off. 

The  command-line  options  used  for 
QuickC  were  -Ox  -FPi.  For  Turbo  C, 
the  options  were  -Z  -O  -G  -d.  The 
-FPi87  flag  was  used  with  QuickC  to 
generate  the  coprocessor  tests,  and  the 
-f87  flag  was  used  for  the  same  pur¬ 
pose  with  Turbo  C. 

Some  immediate  trends  can  be  seen 
by  looking  at  the  benchmark  table.  The 
compile  times  for  QuickC  and  Turbo 
C  are  very  close  together,  but  the  Turbo 
C  linker  runs  much  faster  by  far.  It’s 
important  to  note  that  these  compiles 
are  for  the  entire  modules;  using 
QuickC’s  incremental  compilation  and 
linking  features  make  it  considerably 
faster  than  Turbo  C. 

The  most  surprising  run-time  result 
is  Turbo  C’s  poor  performance  on  the 
GRAPH  test.  The  ellipse( )  and  flood 
fill( )  functions  perform  more  than  twice 
as  slowly  as  their  Microsoft  counter¬ 
parts.  Borland  claims  that  “professional 
programmers”  use  polyfill( ) — which 
draws  an  automatically-filled  polygon  — 
rather  than  floodfill( ),  but  I  don’t  agree 
with  that  logic.  Most  filling  is  done  in 
regions  bounded  by  objects  that  may 
or  may  not  be  drawn  in  one  piece. 

Drawing  conclusions  from  these  tests 
can  be  risky.  In  general,  Turbo  C’s  com- 
pile/link  cycle  is  shorter  than  QuickC’s 
(although,  use  of  QuickC’s  incremental 
compile/link  would  probably  reverse 
this  trend),  but  QuickC  programs  tend 
to  run  a  little  faster.  Nevertheless,  the 
overall  performance  of  the  two  C  com¬ 
pilers  in  these  benchmarks  is  too  close 
to  reveal  any  clear  winner. 

And  that’s  good  news  for  the  ven¬ 
dors  and  —  even  more  important  — 
for  us  programmers.  No  matter  which 
product  you  choose,  you  can  be  as¬ 
sured  that  it  is  of  excellent  quality. 


EXAMINING  ROOM 


VEdit  Plus 

Professor  T.A.  Elkins 


Product  Information 

VEdit  Plus,  Version  3,  CompuView  Prod¬ 
ucts,  Inc.,  1955  Pauline  Blvd.,  Ann  Ar¬ 
bor,  MI  48103;  313-996-1299.  Require¬ 
ments:  156  Kbytes  of  RAM,  hard  disk 
not  required.  Supports:  IBM  PC,  XT, 
AT,  PS/2,  and  compatibles  running  un¬ 
der  MS-DOS,  CP/M-86,  FlexOS,  Xenix, 
and  OS/2.  Also  DESQview,  MS  Win¬ 
dows,  PC-MOS/386,  and  Concurrent 
DOS.  Price:  $185. 


VEdit  Plus,  Version  3,  can  deal 
simultaneously  with  up  to  37 
files  in  multiple  windows,  and 
can  exchange  material  between 
all  of  the  files  and  windows.  It 
provides  multiple  views  of  a  single  file, 
and  a  full-fledged  text-programing  lan¬ 
guage  which  includes  macros.  VEdit 
Plus  can  record  hundreds  of  undo  lev¬ 
els,  provide  on-line  help  for  itself  and 
a  compiler  or  a  collateral  program,  run 
a  compiler  with  hooks  for  competent 
error  matching  or  run  another  child 
process,  check  structure  for  items,  such 
as  the  proper  nesting  of  brackets,  auto¬ 
mate  graphic  character  drawings  or  illus¬ 
trate  the  screen  character  set,  and  pro¬ 
vide  a  middling  integer  calculator  — 
all  EXE.PAC  in  less  than  68  Kbytes  of 
disk  space. 

The  program  has  always  set  a  stan¬ 
dard  for  configurability  —  the  entire  key¬ 
board  can  be  internally  reassigned  and 
a  number  of  keyboard  macros  car.  be 
built  into  VEdit  Plus.  In  Version  3,  all 
the  functional  keyboard  reassignments 
are  dynamically  detected  by  the  help 
system,  which  reports  the  current  com¬ 
mand  keys.  Multiple  copies  of  the  pro¬ 
gram  can  be  configured  with  individ¬ 
ual  sign-on  messages;  extremely  com¬ 
plex  key  redefinitions  and  macros  can 
be  automatically  loaded  by  a  separate 
initiation  file;  scores  of  tab  locations 
can  be  assigned,  control  characters  can 
be  shown  graphically  or  as  control  char¬ 
acters;  and  all  of  the  system  defaults 
for  switches,  colors,  cursor  operation 
(including  blink  rate  and  line-ending 
characters)  can  be  individually  set  for 
each  VEdit  Plus  configuration. 

For  several  popular  word  processors, 
VEdit  Plus  provides  a  partial  emulation 
through  preset  key  sequences  that  ap- 
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proximate  many  individual  word  pro¬ 
cessor  commands  or  key  stroke  se¬ 
quences.  These  emulations  do  not  alter 
VEdit  Plus’s  operation  or  its  display 
screen,  nor  do  they  add  to  or  change 
text  manipulations.  Accordingly,  the  emu¬ 
lations  are  a  convenience  feature  to 
bring  certain  word  processor  opera¬ 
tions  into  a  familiar  context,  but  even 
this  much  help  will  be  important  to 
some  users. 

VEdit  Plus  offers  three  user  modes 
of  operation,  starting  as  a  full-screen 
editor  or  starting  in  command  mode. 
The  modes  are  user  selectable,  with 
the  screen-edit  mode  accepting  abbre¬ 
viated  commands  or  providing  com¬ 
plete  menus.  Screen  mode  also  offers 
auto-indenting  and  other  programmer 
aids,  the  usual  block  operations  sup¬ 
plemented  by  helpful  column-block  op¬ 
erations,  horizontal  scrolling  for  spread¬ 
sheet  and  other  long  line  files,  and 
blinding  speed  for  55-Kbyte  or  smaller 
files.  Finally,  there  is  the  command  macro 
mode  in  which  several  self-running 
macros  are  supplied  for  activities  such 
as  mailing  list  sorts  and  search  and 
replace  operations. 

VEdit  Plus  is  available  for  a  variety 
of  operating  systems;  1  examined  only 
MS-DOS.  The  DOS  system  comes  with 
a  preconfigured  .EXE  file  that  is  ready 
to  run,  but  VEdit  Plus  includes  an  in¬ 
stall  program  that  will  allow  easy  set¬ 
up  and  customization  as  well  as  a  re¬ 
configuration  program  that  provides  for 
very  minute  control  of  the  system’s  op¬ 
erations.  For  my  operation,  I  inhibited 
the  sign-on  message,  relocated  the  help 
files  to  another  drive,  turned  on  insert 
mode,  set  block  operations  to  column 
mode,  changed  the  tabs  to  every  five 
spaces,  and  altered  the  page  buffer  size 
to  improve  performance.  All  of  these 
adjustments  were  straightforward  and 
well  documented. 

Adding  keyboard  macros  is  also  easy, 
and  it  should  be  noted  that  each  of 
these  changes  goes  into  the  VEdit  Plus 
.COM  file.  (One  simple  macro  I  added 
provides  for  the  command  Alt-Q  to 
instantly  quit  the  program.)  Far  too  often 
a  system  generates  a  host  of  tiny  collat¬ 
eral  files  to  set  various  internal  matters, 
disregarding  the  fact  that  each  of  these 
files  requires  a  full  disk  cluster  of  stor¬ 
age  space.  Because  my  system  is  per¬ 
petually  full,  I  am  grateful  to  Compu¬ 
View  for  this  nice  touch.  The  need  for 
numerous  small  files  was  one  of  my 
main  objections  to  BRIEF,  a  major  com¬ 
petitor  to  VEdit  Plus. 

The  HELP  system  provides  two  more 
nice  touches.  As  mentioned,  the  cur¬ 
rent  keyboard  control  key  assignments 
are  sensed  by  the  HELP  system  so  that 
any  assignment  changes  a  user  may 
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make  are  automatically  reflected  when 
the  HELP  screen  displays.  This  proce¬ 
dure  has  decided  advantages  over  the 
templates  used  by  the  generality  of  pro¬ 
grams  because  it  is  always  up-to-date, 
never  bent,  dirty,  lost,  or  in  the  way! 

The  rest  of  the  optional  HELP  system 
employs  three  ASCII  files  with  some 
well-documented,  intelligent  indexing 
commands.  Any  of  these  files  can  be 
edited  to  add  notes  that  users  find  nec¬ 
essary.  With  a  bit  more  sophistication, 
two  or  more  of  the  standard  or  modi¬ 
fied  HELP  files  can  be  merged  and  an 
entirely  new  help  file  can  be  written 
for  anything  that  might  be  run  with 
VEdit  Plus  and  that  needs  on-line  help. 
A  fairly  remarkable  amount  of  intelli¬ 
gence  can  be  built  into  this  new  HELP 
file,  allowing,  for  example,  the  auto¬ 
mated  look-up  of  a  host  of  sub-pro- 
gram  command  switches.  As  a  top  pro¬ 
grammer’s  text  editor,  VEdit  Plus  natu¬ 
rally  has  internal  support  for  compilers, 
but  the  addition  of  on-line  compiler 
help  is  frosting  indeed. 

Column  mode  operation  has  begun 
to  creep  into  more  systems,  but  for 
those  who  don’t  know  this  wonderful 
option,  I’ll  illustrate.  Consider  the  fol¬ 
lowing  characters: 

qwertyuiop 

asdfghjkl 

zxcvbnm 

Suppose  that  the  er,  df  and  cv  all  needed 
to  be  removed.  With  Column  mode, 
this  task  is  trivial;  just  Block  the  rectan¬ 
gle  from  the  e  to  the  v  and  delete. 
Column  mode  is  slower  to  execute  than 
normal  Block  operations,  but  the  con¬ 
venience  is  obvious.  I’ve  used  Column 
mode  to  remove  entire  segment  refer¬ 
ences  from  ,LST  files  in  seconds  —  an 
activity  that  would  take  hundreds  or 
even  thousands  of  manual  keystrokes. 

Finally,  the  VEdit  Plus  menu  opera¬ 
tion  is  utterly  easy.  The  command  to 
bring  up  the  menus  is  not  shown  on 
the  screen  as  it  really  should  be,  but  I'll 
concede  that  anyone  can  remember 
FI  after  only  minutes  of  work  with 
VEdit  Plus. 

Not  much  is  wrong  with  VEdit  Plus, 
but  the  menu  system  leads  me  to  one 
set  of  oddities.  On  a  monochrome  moni¬ 
tor,  the  menus  are  pleasantly  shown 
in  inverse  video,  but  the  item  selected 
is  then  shown  in  normal  video.  I  found 
two-item  menus  disconcerting  because 
I  am  accustomed  to  the  highlight  indi¬ 
cating  selection,  and  decided  to  recon¬ 
figure  the  program  for  normal  video 
and  pull-down  menus,  a  standard  al¬ 
ternative  on  the  configuration  list.  When 
I  did  this,  nothing  happened. 

After  a  goodly  amount  of  work,  and 


more  than  a  reasonable  amount  of  head 
scratching,  I  called  CompuView.  After 
some  checking,  I  was  told  that  when 
the  attribute  for  normal  video  was  set 
at  2  it  inhibited  all  other  changes.  Make 
this  value  7,  they  told  me,  and  all  would 
be  well.  But  all  was  not  well.  With  this 
value  set  at  7  the  cursor  disappeared! 
Finally,  we  learned  that  the  screen  erase 
setting  had  to  be  changed  as  well.  At 
last  I  could  reconfigure  the  pull-down 
menus  to  normal  video,  and  the  prob¬ 
lem  was  solved. 

Another  minor  matter  concerns  file 
size.  VEdit  Plus’s  .EXE  file  can  be 
EXEPACKed  to  save  4  Kbytes  of  disk 
space.  But  the  packed  version  can  no 
longer  be  changed  by  the  configured 
program.  I  recommend  a  well-docu¬ 
mented  archive  copy  for  a  VEdit  Plus 
file  that  is  packed. 

Finally,  the  only  authentic  problem 
with  VEdit  Plus  concerns  the  edit  buff¬ 
ers  it  assigns  and  its  internal  virtual 
memory  system.  With  CP/M  antece¬ 
dents,  VEdit  Plus  never  uses  more  than 
one  memory  segment  for  any  single 
activity.  This  limits  the  largest  buffer 
space  to  about  55  Kbytes,  and  other 
buffers  may  get  less  if  memory  is  short. 
On  a  positive  note,  the  system  simply 
dumps  to  disk  any  part  of  a  file  it  can’t 
fit  into  the  RAM  buffer  space.  VEdit 
Plus  can,  accordingly,  deal  with  multi¬ 
megabyte  files.  Unfortunately,  even 
when  memory  is  available,  the  virtual 
system  still  operates  under  the  single 
segment  limitation,  and  the  “Wait  for 
File”  message  can  quickly  become  both¬ 
ersome.  Even  when  running  on  a  RAM 
disk,  the  delays  for  virtual  activity  are 
long  enough  to  provoke  resentment. 

Of  course,  the  payoff  comes  when 
huges  files  are  being  edited.  Then  the 
smaller  VEdit  Plus  printers  allow  vastly 
superior  speed  in  such  routine  activi¬ 
ties  as  search-and-replace.  On  1  Mbyte 
or  larger  files  VEdit  Plus  flies,  while 
other  text  editors  I’ve  seen  creep  if  they 
can  run  at  all. 

C  Windows 
Toolkit 

Tom  Castle 

Product  Information 

C  Windows  Toolkit,  Version  2.0;  Magna 
Carta  Software,  PO  Box  475594,  Gar¬ 
land,  TX  75047,  214-226-6909.  FAX  214- 
226-0386.  BBS  (for  downloading  demo 
and  examples  of  applications)  214-226- 
8088.  Requirements:  IBM  PC,  XT,  AT, 
PS2,  or  compatible.  Compilers:  Turbo 


C  2.0,  Microsoft  C  5.0,  MS  QuickC,  and 
Mix  Power  C.  Price:  $99.95  (includes 
source  code). 

There  are  quite  a  few  window¬ 
ing  toolboxes  available  to  C  pro¬ 
grammers.  One  kit  in  particu¬ 
lar,  C  Windows  Toolkit  from 
Magna  Carta,  is  an  exceptional 
value.  Aside  from  a  generous  library, 
the  package  includes  a  font  editor,  a 
pop-up  ruler  for  window  alignment, 
the  library  source  code,  and  a  359-page 
manual  with  a  tutorial  covering  video 
architectures  and  the  toolbox  functions. 

The  guts  of  C  Windows  Toolkit,  of 
course,  is  window  management.  The 
toolbox  separates  the  creation  of  a  win¬ 
dow  from  its  presentation  so  that  con¬ 
struction  is  transparent  and  the  display 
event  is  instantaneous.  Many  of  the 
window  attributes,  such  as  colors,  size, 
location,  borders,  and  shadowing,  are 
set  by  individual  functions,  so  you  may 
have  quite  a  bit  of  code  after  building 
a  window  with  all  the  works.  Also,  you 
may  wind  up  with  a  fairly  hefty  header 
file  because  all  the  information  used 
to  construct  windows  and  menus  is 
kept  in  a  series  of  data  structures. 

By  assigning  priorities  to  your  win¬ 
dows,  the  active  (highest  priority)  win¬ 
dow  will  be  in  the  foreground  —  over¬ 
lapping  the  underlying  elements.  If  you 
bring  a  window  to  the  foreground,  the 
priorities  of  the  other  windows  will  be 
adjusted  automatically. 

You  can  settle  for  writing  formatted 
output  to  windows,  but  the  Toolkit  also 
includes  facilities  for  virtual  screens.  With 
virtual  screens,  limited  in  size  only  by 
free  memory,  your  window  can  act  like 
a  viewing  port  for  the  underlying  text. 

The  Toolkit  contains  some  nice  sur¬ 
prises  for  window  handling.  You  have 
the  ability  to  load  and  store  windows 
on  disk,  zoom  and  contract  windows 
from  various  vantage  points  and  speeds, 
and  even  produce  an  opening  curtain 
presentation. 

The  Toolkit  provides  all  the  neces¬ 
sary  functions  to  display  and  make  se¬ 
lections  from  pop-up  menus.  You  cre¬ 
ate  scrolling  menus  by  defining  a  menu 
box  of  a  certain  size  and  then  using  a 
virtual  screen  to  hold  the  actual  text  of 
the  menu  items.  Pretty  slick.  As  an¬ 
other  option,  menus  can  be  sized  auto¬ 
matically  by  not  specifying  any  dimen¬ 
sions.  Functions  for  the  creation  of  line 
menus  or  the  top  bars  of  pulldown 
menus  aren't  included  in  this  version 
of  the  Toolkit.  Those  functions,  how- 
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ever,  can  be  downloaded  from  Magna 
Carta’s  BBS. 

Menu  selection  can  be  accomplished 
by  scrolling  highlight  bars,  or  option¬ 
ally  by  key  press  of  a  designated  high¬ 
lighted  letter  in  the  menu  name.  The 
mouse  isn’t  supported  yet.  Because  sepa¬ 
rate  functions  are  available  for  adding 
and  removing  highlighting  from  a  menu 
item,  multiple  selections  are  possible 
from  your  menus. 

Magna  Carta  probably  felt  a  need  to 
round  out  the  package,  so  they  threw 
in  the  kitchen  sink.  Several  keyboard 
input  routines  are  available.  They  also 
threw  in  all  sorts  of  system  and  hard¬ 
ware  detection  functions:  Enhanced  key¬ 
boards,  Hercules  RAMfont  support, 
video  adapters,  EGA  ROM  parameters, 
and  active  ANSI. SYS  files.  There  is  also 
a  lot  of  support  for  EGA  and  VGA  op¬ 
tions  like  the  number  of  lines  per  screen, 
palette  selection,  split  screens,  smooth 
scrolling  and  panning,  and  ROM  fonts. 

In  addition,  they  give  you  TSR  clocks, 
stopwatches,  and  alarm  clocks  you  can 
display.  Speaker  control  and  delay  tim¬ 
ers  are  also  squeezed  into  the  library. 

There  are  two  major  new  additions 
to  the  library  in  version  2.0.  One  set  of 
functions  is  for  data  entry  fields,  in¬ 
cluding  parsing  and  validation.  The 
other  set  is  a  collection  of  functions  for 
building  a  text  editor. 

Two  considerations,  in  addition  to 
the  function  library  and  documenta¬ 
tion,  make  C  Windows  Toolkit  very 
attractive.  First,  Magna  Carta  doesn’t 
require  royalties  on  the  run-time  pack¬ 
age  or  any  example  code  included  in 
your  application.  Second,  at  no  extra 
cost,  they  include  the  source  code  to 
the  entire  library  —  of  which  about  98 
percent  is  written  in  C  for  easy  inspec¬ 
tion  and  modification.  Like  it  or  not, 
windows  are  with  us.  With  that  stark 
fact  in  mind,  you  have  a  choice  to 
make;  your  time  or  your  money.  Magna 
Carta’s  C  Windows  Toolkit  makes  that 
choice  a  little  easier. 


PCX 

Programmer’s 

Toolkit 

Tom  Castle 


Product  Information 

PCX  Programmer’s  Toolkit,  Version  3. 52; 
Genus  Microprogramming,  11315  Mead¬ 
ow  Lake,  Houston,  TX  77077;  713-870- 
0737  or  800-227-0918.  Requirements: 
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IBM  PC,  XT,  AT,  PS2,  or  compatible; 
DOS  2.1  or  higher;  128K  RAM.  Sup¬ 
ported  Compilers:  Microsoft  C,  MS 
QuickC,  Turbo  C,  Lattice  C,  Turbo  Pas¬ 
cal,  Microsoft  Pascal,  Microsoft  Basic, 
QuickBasic,  Microsoft  Fortran,  Clipper, 
Microsoft  ASM,  (soon  Turbo  ASM). 
Video  Adapters:  Hercules,  CGA,  EGA, 
VGA,  Paradise  Professional  VGA,  Or¬ 
chid  ProDesigner,  Video  7  VRAM,  STB 
Extra/EM.  Also  supports:  Expanded  mem¬ 
ory  conforming  to  LIM  4.0.  Price:  $195. 
Source  code  available  for  $300. 


In  my  opinion,  there  is  an  overabun¬ 
dance  of  bit-mapped  graphics  file 
formats  for  MS-DOS  machines.  All 
too  often  for  the  user,  files  created 
by  one  program  won’t  be  usable 
by  another  program.  From  a  program¬ 
mer’s  vantage,  we  have  to  deal  with  all 
these  different  beasties. 

Fortunately,  a  ubiquitous  bit-mapped 
image  file  format  has  emerged  from  the 
mire,  ZSoft’s  PCX  format.  Almost  every 
drawing  and  desktop  publishing  pro¬ 
gram,  along  with  FAX  and  scanner  soft¬ 
ware,  uses  or  translates  PCX-format  files. 

A  PCX  file  consists  of  a  128-byte 
header  section  followed  by  a  com¬ 
pressed  data  section.  By  using  run- 
length  encoding  (RLE)  to  compress  the 
data,  bit-mapped  graphics  files  can  be 
squeezed  to  a  small  fraction  of  their 
original  size.  This  is  obviously  impor¬ 
tant  when  you  get  up  into  extended 
VGA  with  resolutions  of  800  x  600  pix¬ 
els  in  16  colors  (240  Kbytes)  or  even 
EGA  640  x  350  pixels  in  16  colors  (112 
Kbytes). 

The  first  part  of  the  PCX  Program¬ 
mer’s  Toolkit  is  a  collection  of  stand¬ 
alone  programs  that  include  the  screen 
capture,  display,  clip,  print,  and  library 
utilities.  Other  programs  locate  pixel 
coordinates,  retrieve  the  PCX  header 
information,  translate  captured  text 
screens  to  a  bit-mapped  graphics  im¬ 
age,  and  fix  older  versions  of  PCX  files 
to  conform  to  the  latest  specification 
set  by  ZSoft. 

The  second  part  of  the  Toolkit  is  a 
collection  of  function  libraries  to  in¬ 
clude  in  your  applications.  There  are  a 
total  of  61  functions,  and  the  libraries 
can  be  used  with  a  wide  array  of  lan¬ 
guages  and  compilers  (see  product  box). 

This  Toolkit  lets  you  do  much  more 
than  display  and  save  PCX  files.  A  num¬ 
ber  of  the  library  functions  deal  with 
transferring  a  file  from  a  storage  loca¬ 
tion  to  either  another  storage  area  or  to 
an  output  device.  You  also  have  func- 


Tom  Castle  is  a  chemist  who  frequently 
writes  programming  articles.  He  can 
be  reached  at  8734  Merrimac,  Rich¬ 
land,  MI 49083,  or  on  MCI  Mail:  tcastle. 


tions  to  query  about  file  types,  headers, 
palettes,  and  hardware.  Two  functions 
directly  display  bit-mapped  images  on 
the  display  with  logical  operations  for 
animation  or  superimposing  images. 

The  Toolkit  includes  library  manage¬ 
ment  routines  that  let  you  manipulate 
entire  image  libraries  and  extract  single 
images  for  presentation.  By  using  li¬ 
braries  of  images  instead  of  individual 
PCX  files,  your  graphics  images  are  less 
available  for  scrutiny  or  hazard  from 
the  end  user. 

The  Toolkit  lets  you  use  two  differ¬ 
ent  types  of  image  buffers  when  work¬ 
ing  with  PCX  files.  The  traditional  buffer 
is  used  for  storing  compressed  PCX 
image  files.  A  second  type,  a  virtual 
buffer,  stores  the  entire  uncompressed 
bit  image. 

There  are  two  advantages  to  using 
virtual  buffers.  First,  images  larger  than 
the  screen  can  be  stored  in  a  virtual 
buffer.  The  image  then  can  be  quickly 
panned  or  scrolled  by  scanning  the 
virtual  buffer.  The  virtual  buffer  is  lim¬ 
ited  in  size  only  by  free  memory,  and 
can  be  placed  in  expanded  memory  if 
available.  Second,  displaying  or  print¬ 
ing  an  image  from  a  virtual  buffer  are 
about  five  to  ten  times  faster  than  the 
same  operations  from  a  conventional 
buffer  containing  a  compressed  PCX 
image  file.  The  Toolkit,  Version  3-52, 
supports  printing  to  a  Hewlett-Packard 
LaserJet  II.  This  is  true  both  for  the 
stand-alone  print  utility  and  for  the  print 
functions  in  the  programmer’s  library. 
Support  for  Epson/IBM  dot-matrix  print¬ 
ers  is  scheduled  for  the  next  release, 
but  Genus  has  voiced  reluctance  about 
becoming  too  bogged  down  with  printer 
driver  support.  This  could  be  a  weak 
point  in  an  otherwise  excellent  pack¬ 
age.  You’ll  probably  need  to  buy  an 
additional  graphics  print  driver  toolkit. 

The  software  comes  with  an  indexed 
manual  contained  in  a  sturdy  three- 
ring  binder.  In  the  reference  section  of 
the  manual,  example  code  for  each 
function  is  given  in  each  of  the  six 
languages  supported  by  the  toolkit.  The 
disks  also  include  example  code  and 
a  few  test  images.  Genus  doesn’t  re¬ 
quire  licensing  on  usage  of  the  library 
functions,  but  the  stand-alone  programs 
are  for  your  use  only  and  can’t  be 
distributed.  Genus  seems  bent  on  sup¬ 
porting  their  product,  and  improvements 
have  steadily  rolled  off  the  assembly 
line  over  time.  If  you  are  involved 
in  graphics  programming  at  all,  PCX 
Programmer’s  Toolkit  is  well  worth  the 
investment. 
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listing  One  (Text  begins  on  page  16.) 

/  This  macro  must  be  used  when  the  primitive  must  be  exited  and  the 

/  primitive  FAILED.  The 

macro  will: 

Object  subclass:  #Dos 

/  -  restore  all  saved 

registers 

instanceVariableNames : 

/  -  set  AH  to  1  indicating  failure  condition  and  AL  to  the  number 

'  registers  tempi  temp2 

z  of  arguments  passed  to  the  primitive 

classVariableNames :  '' 

/  -  and  the  IRET  instruction  is  executed 

poolDictionaries :  "  ! 

exitWithFailure  MACRO 

numOfArgs 

! Dos  methods  ! 

POP 

BP  /restore  all  saved  registers 

doDCSPrimitive:  opcode 

POP 

BX 

"PRIVATE  -  Call  the  DCS  Primitives  using  an  interrupt" 

POP 

DI 

<primitive:  96> 

POP 

SI 

getEnvironmentValue :  anEnvironmentString 

POP 

DS 

"Private-  This  is  a  method  for  getting  the 

MOV 

AX, 256  +  numOfArgs  /AH  to  1  (prim  failed) 

value  of  an  environment  variable (string) .  Answers 

IRET 

/interrupt  return 

the  value  if  anEnvironmentString  is  valid  or  nil 

ENDM 

if  not  found. 

Here  the  instance  variables  are 

/  This  macro  will  return 

the  address  of  the  object  with  object  pointer 

used  as  follows: 

/  in  objectReg.  The  address  will  be  returned  in  the  register  pair 

tempi  =  the  name  of  the  environment  variable  wanted 

/  segmentReg:offsetReg. 

segmentReg  must  be  a  segment  register. 

temp2  =  the  value  of  the  environment,  if  the 

environment  variable  exists.  " 

getOb jectAddress  MACRO 

objectReg, of fsetReg, segmentReg 

tempi  :=  anEnvironmentString  asAsciiZ. 

temp2  :  =  String  new:  128. 

/  All  the  arguments  must 

be  different  registers. 

(self  doDcsPrimitive:  -11) 

;  BP  must  not  have  changed  from  the  value  it  was 

ifTrue:[  Atemp2  trimBlanks  ) 

Z  set  to  in  the  enterPrimitive  macro. 

ifFalse:  [  A"  ] . ! 

MOV 

segmentReg,  [BP+12] 

ROR 

objectReg,  1 

End  Listing  One 

MOV 

of fsetReg, segmentReg: [objectReg) 

ROL 

objectReg, 1 

MOV 

segmentReg, SS: [objectReg] 

AND 

of fsetReg, MASK  offsetMask 

Listing  Two 

ENDM 

;  This  macro  will  mark  the  object  whose  object  pointer  is  in  objectReg 

***************************************************************************** 

;  so  the  garbage  collector  will  not  collect  as  garbage.  It  is  to  be  used 

ACCESS. USR  -  PRIMITIVE  ENTRY  MACRO  -  SMALLTALK/V 

/  whenever  an  object  pointer  is  stored.  If  the  object  in  objectReg  is 

Copyright  (C)  1986  -  Digitalk,  Inc.  -  Reprinted  by  Permission 

;  a  small  integer,  no  marking  occurs. 

***************************************************************************** 

It  is  essential  that  this  macro  appear  at  the  beginning  of 

markPtr  MACRO 

objectReg, segmentReg 

the  primitive  in  that  it  saves  certain  registers.  Some  of 

LOCAL 

done 

the  registers  may  or  may  not  have  to  be  restored  depending  on 

whether  or  not  the  primitive  is  successful,  and  some 

;  BP  must  not  have  changed  from  the  value  it  was 

must  be  restored  before  exiting  the  primitive. 

l  set  to  in  the  enterPrimitive  macro. 

enterPrimitive  MACRO 

ROR 

objectReg, 1 

JNC 

done 

At  the  end  of  this  macro  the  stack  will  appear  as  below: 

MOV 

segmentReg,  [BP+12] 

SP — >  BP — >  -  saved  BP  -  must  be  restored  on  exit 

OR 

BYTE  PTR  segmentReg: [objectReg] , MASK  grayMask 

+2  -  saved  BX  -  must  be  restored  in  case  of  failure 

done :  ROL 

objectReg, 1 

+4  -  saved  DI  -  must  be  restored  in  case  of  failure 

+6  -  saved  SI  -  must  be  restored  on  exit 

ENDM 

+8  -  saved  DS  -  must  be  restored  on  exit 

+10  -  IP 

/  This  macro  will  get  the  class  (pointer)  of  the  object  whose  pointer 

+12  -  CS 

;  is  in  objectReg.  If  the  object  in  objectReg  is  a  small  integer  then 

+14  -  FLAGS 

;  the  class  pointer  is  set  to  ClassSmalllnt . 

if  there  are  any  argument  passed  to  the  primitive  they  are  found  here 

+16  -  last  argument  to  primitive 

getClass  MACRO 

objectReg, classReg, segmentReg 

+18  -  second  last  argument  to  primitive 

LOCAL 

done 

-  etc. . . 

/all  the  arguments  must 

be  different  registers 

high  address  - 

Note:  some  of  the  following  macros  use  BP  assuming  the  value  has  not 

MOV 

classReg, ClassSmalllnt 

changed  from  what  this  macro  sets  it  to.  If  you  use  BP  be  sure 

TEST 

objectReg, 1 

to  restore  it  before  using  the  macros  that  make  use  of  BP. 

JZ 

done 

MOV 

classReg, SS 

PUSH  DS  ;set  up  stack  as  shown  above 

SHR 

classReg, 1 

PUSH  SI 

MOV 

segmentReg, classReg 

PUSH  DI 

MOV 

classReg, segmentReg: [objectReg] 

PUSH  BX 

done: 

PUSH  BP 

ENDM 

MOV  BP, SP  ;set  BP  to  Top  of  Stack 

ENDM 

;  This  macro  will  set  the  zero  condition  flag  as  to  whether  the  object  size 

;  is  an  even  or  odd  number  of  bytes.  This  test  should  be  performed  on 

This  macro  must  be  used  when  the  primitive  must  be  exited  and  the 

/  byte-addressable  objects.  A  zero  condition  means  that  the  object  is  an 

primitive  was  SUCCESSFUL.  The  resulting  pointer  or  small  integer 

;  even  number  of  bytes  (actual  size  =  object  header  -  2) .  A  non-zero 

must  be  in  BX  before  invoking  this  macro.  The  macro  will: 

;  condition  means  that  the  object  is  an  odd  number  of  bytes 

-  mark  the  object  (pointer)  in  BX  so  that  the  garbage  collector 

;  (actual  size  =  object 

header  -  3) . 

will  not  collect  it  as  garbage 

-  .certain  registers  are  restored 

isSizeEven  MACRO 

objectReg, workReg, segmentReg 

-  the  return  address  and  flags  are  popped  into  temporary  registers 

-  the  arguments  are  flushed  and  replaced  with  the  result  in  BX 

;  BP  must  not  have  changed  from  the  value  it  was 

-  the  return  address  and  flags  are  put  back  on  the  stack 

/  set  to  in  the  enterPrimitive  macro. 

-  AX  is  set  to  zero  (AH=0  indicates  that  the  primitive  was  successful) 

-  and  the  IRET  instruction  is  executed 

MOV 

workReg, objectReg 

ROR 

objectReg, 1 

exitWithSuccess  MACRO  numOfArgs 

MOV 

segmentReg, [BP+12] 

TEST 

BYTE  PTR  segmentReg: [objectReg] , MASK  oddMask 

;  On  entry  BX  must  contains  the  result  to  be  pushed 

MOV 

objectReg, workReg 

/  on  the  stack. 

ENDM 

markPtr  BX,ES  ;mark  result  object  in  BX 

.*********************** 

****************************************************** 

POP  BP  /restore  BP 

Z  PRIMITIVE  ENTRY  POINT 

SAMPLE  CODE  FRAGMENTS 

ADD  SP, 4 

.*********************** 

****************************************************** 

POP  SI  /restore  DS:SI  pair 

DW 

getCountryEnt 

POP  DS 

DW 

getEnvironEnt 

POP  CX  /pop  the  of f set, segment  and 

DW 

exeApplicEnt 

POP  DX  /flags  into  temp  registers 

DW 

exeProgramEnt 

POP  AX 

DW 

setNoXlatEnt 

IF  numOfArgs 

DW 

setXlatEnt 

ADD  SP, numOfArgs  *2+2  /flush  all  args  of  primitive 

DW 

atEndEnt 

END  IF 

DW 

buf FlushEnt 

PUSH  BX  /push  result  on  stack 

DW 

bufWriteEnt 

PUSH  AX  /push  flags,  segment  and 

DW 

bufReadEnt 

PUSH  DX  /offset  back  onto  stack 

DW 

initOutputEnt 

PUSH  CX 

DW 

initlnputEnt 

XOR  AX, AX  /AH  to  0  (prim  was  success- 

jumpTable  DW 

interrupt Ent 

ful) 

DW 

inWordEnt 

IRET  /interrupt  return 

ENDM 
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DW  inByteEnt 

Ids  dx,cs:dtaPtr 

DW  outWordEnt 

int  21h 

DW  outByteEnt 

DW  peekEnt 

cli  /and,  restore  the  Smalltalk  stack  with 

DW  pokeEnt 

mov  ss, cs : stackseg  /  the  saved  pointer. 

DW  blockMoveEnt 

mov  sp, cs : stackofs 

sti 

* 

mov  ax, retCode  /convert  the  errorlevel  to  a  Smalltalk 
shl  ax, 1  /  integer  format,  and  return  it  in  the 
les  bx, receiverPtr  /  fifth  instance  variable  of  receiver 

dcsPrims 

proc  far 

mov  es: [bx+12] , ax  /  object. 

/  This  is  code 

that  will  be  executed  everytime  this  primitive 

mov  bx, retVal  /the  Smalltalk  convention  is  to  put  the 

/  is  invoked  from  "Smalltalk/V" 

jmp  successl  /  answer  for  this  obj  in  bx,  and  call 

/  the  "leavePrimitive"  macro,  a  jump 

enterPrimitive 

/enter  primitive  macro 

/  to  success  will  do  this  quite  nicely 

/  thank  yew ! 

mov 

bx, [bp+16] 

/get  function  code  from  first  instance 

test 

bl,  1 

/  variable  of  receiving  object,  if  it 

End  Listing  Two 

jnz 

failure 

isn't  a  number  then  something's  very 
rotten  in  the  state  of  Denmark. 

cmp 

bx,  16 

/the  function  code  is  already  shifted 

jge 

cmp 

failure 
bx, -26 

left  by  one  (courtesy  of  Smalltalk's 
way  of  identifying  integers),  so  do 

Listing  Three 

jle 

failure 

some  range  checks  and  abort  if  the 

value  is  out  of  bounds. 

/queue  an  interpreter  interrupt  (in  protected  mode) 

/  AL=interrupt  number  to  queue 

jmp 

cs: [bx+ jumpTable] 

/otherwise,  jump  to  the  code  associated 

interruptVM  MACRO 

* 

with  this  function  number. 

CALL  DWORD  PTR  SS : [queueVMinterrupt ] 

ENDM 

l 

/queue  an  interpreter  interrupt  (in  real  mode) 

ISVinterruptVM  MACRO 

MOV  ES,CS: [realParmSeg] 

mov 

cs:stackOfs, sp 

•save  the  current  Smalltalk  stack,  and 

CALL  DWORD  PTR  ES : [ ISVqueueVMinterrupt ] 

mov 

csrstackSeg, ss 

replace  it  with  a  local  stack  in  low 

ENDM 

mov 

ax,  cs 

(protected  memory) . 

The  code  to  call  the  socket  primitive  in  Smalltalk  is: 

cli 

socketPrimitiveOpcode:  opcode  withArguments :  argument Array 

mov 

ss,  ax 

"PRIVATE:  Call  the  socket  primitive." 

lea 

sp,cs:  stack 

&lt / primit ive :  socketPr imitive&gt / 

sti 

Aself  error:  'Network  Primitive  failed  -  is  sockprim.bin  loaded?' 

mov 

ah,2fh 

save  the  DOS  DTA  pointer,’  just  in  case 

int 

21h 

it  gets  clobbered  by  the  application. 

mov 

cs:dtaOfs,bx 

mov 

cs:dtaSeg,es 

call 

exec 

load  and  execute  the  program 

End  Listing  Three 

mov 

bx, truePtr 

the  errorlevel 

jnc 

execOl 

code  is  returned  in  "retCode".  If  the 

mov 

bx, falsePtr 

carry  was  set,  then  an  error  occurred 

execOl:  mov 

retVal,  bx 

and  we  answer  "false",  otherwise  we 
answer  "true". 

mov 

ah, lah 

restore  the  DOS  DTA  pointer. 

SMALLTALK 


listing  Four  (Listings  continued,  text  begins  on  page  16.) 


FIXDPTRS.USR 


/fixed  segments 

plusSmallSeg 

= 

6 

nilSegment 

= 

106H 

minusSmallSeg 

= 

116H 

booleanSeg 

= 

10EH 

characterSeg 

= 

11EH 

fixedPtrSeg 

= 

126H 

/fixed  offsets 

nilOffset 

106H 

trueOf fset 

= 

Of f f 3H 

falseOf fset 

= 

OffflH 

firstCharOf fset 

= 

2 

/segment  of  small  positive  integers 
/segment  of  nil  object 
/segment  of  small  negative  integers 
/segment  for  true  and  false 
/segment  for  all  character  objects 
/segment  for  all  fixed  ptr  objects 


/offset  of  nil  object 
/offset  of  true  object 
/offset  of  false  object 
/offset  of  ascii  char  0 


/Character  Object 
charObj  STRUC 

DB  size  objectHeader  DUP  (?) 
asciiValue  DD  ?  /ascii  value 

charObj  ENDS 

/Note  that  this  is  16  bytes  in  size 

/  Association  Object 
assoc  STRUC 

DB  size  objectHeader  DUP  (?) 
assocKey  DD  ? 

assocValue  DD  ? 

assoc  ENDS 

/  Point  object 
pointObj  STRUC 

DB  size  objectHeader  DUP  (?) 
pointX  DD  ? 

pointY  DD  ? 

pointObj  ENDS 


/all  of  the  following  objects  are  in  the  segment  fixedPtrSeg 
/what  is  given  below  are  their  offsets 

/array  of  classes  in  system 
classArrayOf fset  equ  nilOf fset+size  objectHeader 

Smalltalk  equ  classArrayOffset  +  size  assoc 

ErrorCode  equ  Smalltalk  +  size  assoc 
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/Object  header  structure 


z  Hash  values  for  classes 


SmalllntegerHash  equ 
emptySlotHash  equ 
StringHash  equ 

MessageHash  equ 

SymbolClassHash  equ 
LargePosIntHash  equ 
HomeContextHash  equ 
LargeNeglntHash  equ 


ContextHash  equ 
PointHash  equ 
ArrayHash  equ 
LinkHash  equ 


0 

SmalllntegerHash  +  8 
emptySlotHash  +  8 
StringHash  +  8 
MessageHash  +  8 
SymbolClassHash  +  8 
LargePosIntHash  +  8 
HomeContextHash  +  8 
LargeNeglntHash  +  8 
ContextHash  +  8 
PointHash  +  8 
ArrayHash  +  8 


objectHeader  STRUC 


ClassPtrHash 
ObjectPtrHash 
GCreserved 
NumberFixed 
Ob jectSize 

ObjectFlags 

objectHeader 


DW  ? 

DW  ? 

DW  ? 

DW  ? 

DB  3  DUP (?) 

DB  ? 

ENDS 


/see  below  for  values  for  fixed  classes 
/usually  contains  object  hash 

/number  of  named  instance  variables 
/stored  as  low, middle, high  order 
/  size  is  stored  as  #  of  instance  variables 
/defined  below 


/object  flags  (contained  in  objectFlag  byte  of  objectHeader) 
PointerBit  EQU  10H  /Object  contains  pointers 

IndexedBit  EQU  8  /Object  has  indexed  instance  variables 

/other  bits  in  byte  are  reserved 


/  This  is  a  useful  struc  for  accessing  arguments  in  primitives 
/  For  example,  to  load  the  receiver  into  DS:SI 
;  LDS  SI, [BP+receiverPtr] 

/stack  after  enterPrimitive  macro 
primitiveFrame  STRUC 


savedBP  DW  ? 

returnAddr  DD  ? 

receiverPtr  DD  ? 

arglPtr  DD  ? 

arg2Ptr  DD  ? 

arg3Ptr  DD  ? 


primitiveFrame  ENDS 


/Array  Object 
arrayObj  STRUC 

DB  size  objectHeader  DUP  (?) 
arrayObj  ENDS 


/This  struc  defines  the  beginning  of  a  user  primitive  load  module 
primLoadModule  STRUC 

installEntry  DW  ?  ;  0  entry  point  for  installation  routine 

reservedl  DW  0  ;  2 

DW  0  /  4 

realCodeSeg  DW  ?  ;  6  after  loading,  will  contain  real  mode  addr 
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primTableOffset  DW  ?  ;  8  offset  of  table  of  primitive  subroutines 

/  This  macro  must  be  used  when  the  primitive  must  be  exited  and  the 

realParmSeg  D  Z  ?  /  A  after  loading,  will  contain  real  mode  addr 

/  of  virtual  machine  communication  area. 

;  primitive  FAILED. 

reserved2  DW  0  ;  C 

DW  0  ;  E 

exitWithFailure  MACRO 

primLoadModule  ENDS 

XOR  AX, AX  / AX=DX=0 ,  for  failure  return 

XOR  DX.DX 

***************************************************************************** 

MOV  SP , BP 

*  ACCESS. USR  -PRIMITIVE  ENTRY  MACRO  -  SMALLTALK/V2 8 6 

POP  BP  /restore  BP 

*  Copyright  (C)  1988  -  Digitalk,  Inc.  -  Reprinted  by  Permission 

RETF  /far  return 

**.***********************************,*************************,,,********** 

ENDM 

It  is  essential  that  this  macro  appear  at  the  beginning  of 

/Object  testing  macros 

the  primitive  in  that  it  saves  certain  registers.  Some  of 

the  registers  may  or  may  not  have  to  be  restored  depending  on 

;in  the  following  testing  macros, 

whether  or  not  the  primitive  is  successful,  and  some 
must  be  restored  before  exiting  the  primitive. 

/the  result  is  returned  in  the  zero  flag  as  follows:  z=no,  nz=yes 

/Object  has  pointers??  jz=no,  jnz=yes 

enterPrimitive  MACRO 

isPointerObject  MACRO  objSeg, objOf f 

TEST  objSeg: [ob jOf f+ob jectFlags) , PointerBit 

At  the  end  of  this  macro  the  stack  will  appear  as  below: 

ENDM 

SP — >  BP— >  -  saved  BP 

/Object  is  indexable??  jz=no,  jnz=yes 

+2  -  return  addr  (offset) 

isIndexedObject  MACRO  objSeg, objOf f 

+4  -  return  addr  (segment) 

TEST  objSeg: [objOf f+objectFlags] , IndexedBit 

If  there  are  any  argument  passed  to  the  primitive  they  are  found  here. 

All  arguments  and  the  receiver  are  passed  as  32  bit  pointers 

ENDM 

+6  -  receiver  of  primitive  (offset) 

/Object  is  contained  in  single  segment??  jz=no,  jnz=yes 

+8  -  receiver  of  primitive  (segment) 

isSmallOb ject  MACRO  objSeg, objOf f 

+10  -  first  argument  to  primitive  (offset) 

OR  objOff, objOf f 

+12  -  first  argument  to  primitive  (segment) 

ENDM 

high  address  -  : 

;****  size  extraction  macros  **** 

/Object  size  is  expressable  in  elements  or  bytes. 

Note:  some  of  the  following  macros  use  BP  assuming  the  value  has  not 

/  elements  is  the  number  of  Smalltalk  objects  it  contains 

changed  from  what  this  macro  sets  it  to.  If  you  use  BP  be  sure 

/  bytes  is  the  number  of  bytes  it  occupies  (including  header) 

to  restore  it  before  using  the  macros  that  make  use  of  BP. 

/  note  that  objects  always  occupy  an  even  number  of  bytes 

/For  example: 

PUSH  BP  /save  old  BP 

/  #(  1  2  3  )  is  an  array  with  three  elements  and  it  occupies  24  bytes 

MOV  BP, SP  /set  BP  to  Top  of  Stack 

ENDM 

/  'hello'  is  a  string  with  5  elements  and  it  occupies  18  bytes 

/extract  the  size  in  elements 

This  macro  must  be  used  when  the  primitive  must  be  exited  and  the 

getElementSize  MACRO  objSeg, objOf f, resultLowWord, resultHighByte 

primitive  was  SUCCESSFUL.  The  resulting  pointer  or  small  integer 

MOV  resultHighByte, byte  ptr  objSeg: [objOff+objectSize+2] 

must  be  in  DX,AX  (DX=segment,  AX=offset)  before  invoking  this  macro. 

MOV  resultLowWord, word  ptr  objSeg : [objOf f+objectSize] 

ENDM 

exitWithSuccess  MACRO 

/compute  the  size  in  bytes 

getBigByteSize  MACRO  objSeg, objOf f, resultLowWord, resultHighByte 

On  entry  DX,AX  must  contains  the  result  to  be  pushed 

LOCAL  addHeader 

on  the  stack. 

getElementSize  objSeg, objOf f, resultLowWord, resultHighByte 

isPointerObject  objSeg, objOf f 

JZ  addHeader 

RETF  /far  return 

ENDM 

ADD  resultLowWord, resultLowWord 
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listing  Four  ( Listing  continued,  text  begins  on  page  16.) 

******  -phis  macro  must  be  called  after  EVERY  pointer  store  ******* 

******  Faiiure  to  do  so  will  invalidate  the  garbage  collector  **** 

ADC  resultHighByte, resultHighByte 

******  leading  to  catastrophic  and  unpredicable  results  ********** 

ADD  resultLowWord, resultLowWord 

ADC  resultHighByte, resultHighByte 

This  macro  detects  old  space  to  new  space  pointer  stores, 

addHeader:  ADD  resultLowWord, size  ob jectHeader+1 

and  updates  the  GC  data  base  accordingly. 

ADC  resultHighByte, 0 

AND  resultLowWord, OFFFEH 

macro  arguments  are  as  follows: 

ENDM 

segReg  =  seg  reg  of  object  stored  into 

offReg  =  offset  reg  of  object  stored  into 

/user  calls  to  interpreter  routines 

valueSeg  =  segment  of  pointer  that  was  stored 
workReg  =  a  work  register 

/routine  vector  offsets 

ISVqueueVMinterrupt  equ  0FFF0H  -  4 

example  of  use:  store  ptr  BX:AX  into  object  ES:DI  at  slot  'contents' 

queueVMInterrupt  equ  ISVqueueVMinterrupt-4 

MOV  word  ptr  es : [di+contents] , AX  /store  offset 

oldToNewStore  equ  queueVMinterrupt-4  /used  in  oldToNewUpdate  macro 

MOV  word  ptr  es : [di+contents+2 ] , BX  /store  segment 

OldToNewUpdate  es,di,bx,ax 

/queue  an  interpreter  interrupt  (in  protected  mode) 

OldToNewUpdate  macro  segReg, of fReg, valueSeg, workReg 

/  AL=interrupt  number  to  queue 

LOCAL  done 

interruptVM  MACRO 

MOV  wcrkReg, segReg 

CALL  DWORD  PTR  SS : [queueVMinterrupt ) 

CMP  workReg, 92EH 

ENDM 

JAE  done 

CMP  valueSeg, 92EH 

/queue  an  interpreter  interrupt  (in  real  mode) 

JB  done 

ISVinterruptVM  MACRO 

PUSH  segReg 

MOV  ES,CS: [realParmSeg] 

PUSH  offReg 

CALL  DWORD  PTR  ES: l ISVqueueVMinterrupt] 

CALL  DWORD  PTR  SS : [oldToNewStore] 

ENDM 

POP  offReg 

POP  segReg 

/miscellaneous  but  usefull  macros 

done : 

ENDM 

/is  object  a  small  positive  integer  --  je=yes,  jne=no 

/ (only  segment  needs  to  be  tested) 

**************************************************************************** 

isSmallPosInt  MACRO  segmentExpression 

SOCKPRIM. ASM 

CMP  segmentExpression, plusSmallSeg 

The  V286  Socket  Primitives  V2.0 

ENDM 

In  this  implementation,  recv()  and  accept ()  only  operate  in 
a  nonblocking  fashion,  returning  errno  EWOULDBLOCK  if  the 

/is  object  a  small  negative  integer  —  je=yes,  jne=no 

operation  can  not  be  completed  immediately.  All  other  calls 

/ (only  segment  needs  to  be  tested) 

block  until  completion  or  error. 

isSmallNeglnt  MACRO  segmentExpression 

Opcode  0  is  implemented  in  this  version  as  Socket  closeAll. 

CMP  segmentExpression, minusSmallSeg 

Opcode  18  is  implemented  in  this  version  as  Socket  version. 

ENDM 

An  additional  non-standard  errno  EDRIVER  (254)  is  returned  if 
installation  fails  or  the  installed  driver  behaves  strangely. 

/is  object  a  character  —  je=yes,  jne=no 

*.******.**.*.***.***********•***************•*************.**************** 

/ (only  segment  needs  to  be  tested) 

isCharacter  MACRO  segmentExpression 

TITLE  Socket  Primitives 

CMP  segmentExpression, characterSeg 

286P 

ENDM 

INCLUDE  fixdptrs.usr 

INCLUDE  objects.usr 

/is  object  static,  i.e.  constant,  no  stores  allowed  —  ja=no,  jbe=yes 

INCLUDE  access. usr 

/ (only  segment  needs  to  be  tested) 

isStaticObject  MACRO  segmentExDression 

INCLUDE  sockprim.inc 

CMP  segmentExpression, characterSeg 

(continued  on  page  100) 

ENDM 
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listing  Four  (Listing  continued,  text  begins  on  page  16.) 

code  SEGMENT  PUBLIC  'CODE' 

ASSUME  CS : code, DS : nothing, ES : nothing 

PGROUP  GROUP  CODE 

;  Smalltalk/V286  Reserved  Area 


ORG  0 

DW  OFFSET  install  /installation  routine  entry  point 
DW  0  /reserved  for  future  use 


DW  0  /real  mode  segment  of  this  code 

DW  OFFSET  primTable  /addr  of  table  of  primitives  and  entry  points 
DW  0  /real  mode  segment  address  of  protected  mode 

/parameter  area 


SET_PB_FOR 

MOV 


CALL_NETWORK 

RET 

socket  install  ENDP 


SI, OFFSET  initialized_flag 
DS: [SI] ,AX 

OPCODE_register_event_handler 
WORD  PTR  DS:PB_Event_Handler [BX] , OFFSET 
socket_event_handler 

AX,DS: [realCodeSeg] 

WORD  PTR  DS:PB_Event_Handler+2 [BX] , AX 

BYTE  PTR  DS:PB_errno[BX] ,EDRIVER 
WORD  PTR  DS : PB  Return_Code [BX] , -1 


The  socket  operations 


enterPrimitive 

isSmallPosInt  Slt/WORD  PTR  [BP+arglptr+2] 

sgt/opcode  Smalllnteger? 

JE  ok_opcode 

FAIL  /FAIL  if  not 


AX, initialized_flag 
AX,  AX 

initialized 


/perform  initialization 


CALL  socket_install 
POP  BP 

CMP  AX,  0 

JE  initialized 

SUCCEED  ERROR 


MOV 

check  opcode  bounds 


dispatch  operation 


WORD  PTR  [BP+arglptr] 


AX,  0 

exit_FAIL 
AX, MAX_OPCODE 
exit_FAIL 
AX,  1 
SI, AX 


AX, WORD  PTR  DS: [Socket_Primitives+SI] 
AX 


socket () 

ARG  1  Address_Format 

ARG  2  Type 

ARG  3  Protocol 


PROC  NEAR 

SET  PB  FOR  OPCODE  socket 


GET_POS I T I VE_I NTEGER_ARG  1 

MOV  DS.-PB  Address  Format  [BX] ,  AX 


GET_POSITIVE_INTEGER_ARG  2 

MOV  DS : PB_Type [ BX ] , AX 


GET_POS I T I VE_ I NTEGER_ARG  3 

MOV  DS : PB_Protocol [BX] ,  AX 


CALL_NETWORK 
SUCCEED  INTEGER 


/sets  errno,  result  in  AX 


SUCCEED_POSITIVE_INTEGER 

exit_FAIL: 

FAIL 

socketPrimitive  ENDP 


doEthernetlnt 

This  procedure  executes  in  REAL  MODE.  The  parameter  block  has 
been  filled,  setup  es:bx  to  point  to  the  parameter  block  and 
call  the  ethernet  driver. 


The  socket  event  handler  -  called  by  resident  driver  in  real  mode 


socket_event_handler  PROC  FAR 

MOV  AX, Network_VMInterrupt 

ISVinterruptVM 

RET 

socket  event  handler  ENDP 


General  purpose  success  exit 

AX  =  integer  value  to  be  returned  (positive  or  negative) 


SUCCEED_INTEGER  PROC  NEAR 

CMP  AX,  0 

JL  SUCCEED_NEGATIVE 

SUCCEED_POSITIVE_INTEGER 
SUCCEED_NEGATIVE : 

SUCCEED_NEGATIVE_INTEGER 
SUCCEED  INTEGER  ENDP 


Install  Socket  Event  Handler  -  called  automatically 
by  dispatch 


socket_install  PROC  NEAR 
MOV 


AX,  CS 
ES,  AX 

BX,  OFFSET  Socket_PB 

Resident_Driver_Interrupt 

ES 


doEthernetlnt  PROC 
PUSH  AX 
PUSH  BX 
PUSH  ES 
MOV 
MOV 
MOV 
INT 
POP 
POP 
POP 
RET 

doEthernetlnt  ENDP 


/table  of  primitive  names  and  entry  points 
primTable: 

DB  'socketPrimitive' 

DB  0 

DW  offset  socketPrimitive 


Save  registers 


es  points  to  this  segment 
bx  contains  offset  to  pblock 
/  call  driver 
/  restore  registers 


/Smalltalk  name  of  primitive 
/offset  of  entry  point 


more  entries  can  go  here 
DW  0 


/end  of  table 


/installation  routine,  called  at  the  time  the  module  is  loaded 
install  PROC  FAR 

ret  /we  have  nothing  to  do,  so  return 

install  endp 


End  Listings 
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Listing  One  (Text  begins  on  page  22.) 

/*  DOT.C  -  uses  Lahey  FORTRAN'S  random  number  generator  to  randomly 
place  pixels  on  the  screen. 

This  example  demonstrates  how  to  call  F77L  functions  and 
subroutines  from  a  C  program. 

Uses  Initialize  ()  from  Borland's  BGIDEMO  example  to 
perform  hardware  detection,  load  the  appropriate  BGI 
driver  and  initialize  the  system  to  graphics  mode. 

Link  line  using  Borland's  TLINK  is  as  follows: 

link  bcf 771 . 150+c01+f rand+do_f rand, f rand, , emu+mathl+cl+f771 

*/ 

linclude  <stdio.h> 
linclude  <stdlib.h> 

♦include  <graphics.h> 

char  *DriverNames[]  =  { 

"Detect", 

"CGA" , 

"EGA", 

"HercMono", 

"VGA" 

In¬ 


struct  PTS  { 
int  x,  y; 

};  /*  Structure  to  hold  vertex  points  */ 


int 

GraphDriver; 

/* 

int 

GraphMode; 

/* 

double 

AspectRatio; 

/* 

int 

MaxX,  MaxY; 

/* 

int 

MaxColors; 

/* 

int 

ErrorCode; 

/* 

struct 

palettetype  palette; 

/* 

/* 

Function  prototypes 

/* 

extern 

void  frand  (int  *,  int 

*); 

extern  void  seed_rnd  (int  *) ; 
void  Initialize (void) ; 
void  RandomDot (void) ; 


The  Graphics  device  driver  */ 

The  Graphics  mode  value  */ 

Aspect  ratio  of  a  pixel  on  the  screen*/ 
The  maximum  resolution  of  the  screen  */ 
The  maximum  #  of  colors  available  */ 
Reports  any  graphics  errors  */ 

/*  Used  to  read  palette  info  */ 

*/ 

*/ 

*/ 


/*  Begin  main()  */ 

main () 

{ 

Initialize () ; 
RandomDot ( ) ; 
closegraph () ; 

1  /*  End  main()  */ 


/*  Set  system  into  Graphics  mode  */ 
/*  Place  pixels  at  random  locations  */ 
/*  Return  the  system  to  text  mode  */ 


/*  INITIALIZE:  Initializes  the  graphics  system  and  reports  */ 

/*  any  errors  which  occured.  *' 


void  Initialize (void) 

( 

int  xasp,  yasp; 

GraphDriver  =  DETECT; 
initgraph(  SGraphDriver,  SGraphMode, 
ErrorCode  =  graphresult () ; 
if(  ErrorCode  !=  grOk  ){ 

printf("  Graphics  System  Error: 
exit (  1  ) ; 

) 

getpalette(  &palette  ); 

MaxColors  =  getmaxcolor ()  +  1; 


/*  Used  to  read  the  aspect  ratio*/ 

/*  Request  auto-detection  */ 

""  )  ; 

/*  Read  result  of  initialization*/ 
/*  Error  occured  during  init  */ 
%s\n",  grapherrormsg (  ErrorCode  )  ); 


/*  Read  the  palette  from  board  */ 
/*  Read  maximum  number  of  colors*/ 


Listing  Two  (Listings  continued,  text  begins  on  page  22.) 


C 

c  FRAND . FOR  -  Calls  F77L' s  random  Number  generator  RND. 

c  Demonstrates  how  to  call  a  FORTRAN  function  from 

c 

c  Inputs  :  None 

c  Outputs:  RETVAL 


C 


FUNCTION  FRAND (N) 


BCEXTERNAL  FRAND 
INTEGER*2  N,  FRAND 

FRAND  =  INT (RND ()  *  N  ) 
RETURN 


c 

c  SEED_RND  -  Used  to  seed  F77L's  random  Number  generator, 
c  Demonstrates  how  to  call  a  FORTRAN  subroutine  from  C 

c 

c  Inputs  :  None 

c  Outputs:  RETVAL 

SUBROUTINE  SEED_RND (RETVAL) 

BCEXTERNAL  SEED_RND 
INTEGER*2  RETVAL 

RETVAL  =  INT (RRAND ( ) ) 

RETURN 

END 


End  listing  Two 


Listing  Three 

C 

c  SEARCH. FOR  uses  rnd()  to  generate  a  list  of  random  values 

c  that  are  then  passed  to  C's  qsort  routine  for  sorting  in 
c  ascending  and  descending  order.  Once  sorted,  the  values 
c  are  dislayed  and  the  user  is  prompted  for  a  value  to  search 

c  for.  The  input  value  is  passed  to  C's  bsearch  function  and 

c  the  results  of  the  search  are  displayed 
c 

c  To  link,  use  the  following  command  line: 
c 

c  tlink  f771bc.l50+search+do_srch, search, , emu+mathl+cl+f 771 
c 

PROGRAM  SEARCH 

BCEXTERNAL  q_sort,  bin_search 
INTEGER*2  A(0:20) ,  B (0:20) ,  C(0:20),  I,  J 
INTEGER*2  FOUND,  bin_search,  VAL,  R 

DO  10  I  ■  0,  19 
A  (I)  =  0 
B  (I)  =  0 
c (I)  =  0 

10  CONTINUE 

R  =  rrandO 
PRINT  *,  R 
DO  20  I  =  0,  19 

A ( I )  =  32767.0  *  rnd() 

B  (I)  =  A  (I) 

C(I)  =  A ( I ) 


MaxX  =  getmaxx ( ) ; 

MaxY  =  getmaxy { ) ;  /*  Read  size  of  screen  */ 

getaspectratio(  &xasp,  syasp  );  /*  read  the  hardware  aspect  */ 

AspectRatio  =  (double) xasp  /  (double) yasp;  /*  Get  correction  factor  */ 

}  /*  End  Initialize  */ 

void  RandomDot (void) 


20  CONTINUE 

PRINT  *,  'Input  Ascending  Descending' 
PRINT  *,  ' MMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMM' 
call  q_sort (A, 20, 0) 
call  q_sort  (B, 20, 1) 

DO  30  J  =  0,  19 

PRINT  40,  C(J),  A ( J) ,  B ( J) 


int  seed; 

int  i,  x,  y,  height,  width,  rand_val,  color,  temp; 
struct  viewporttype  vp; 

getviewsettings  (  Svp  ); 
height  =  vp. bottom  -  vp.top; 
width  =  vp. right  -  vp.Ieft; 

seed_rnd(  sseed  );  /*  Seed  F77L's  Random  #  Gen.  Output  discarded  */ 


30  CONTINUE 

40  FORMAT (16, 113, 113) 

PRINT  *,  'Enter  value  to  search  for:  ' 
READ  *,  VAL 

FOUND  =  bin_search (A,  20,  VAL) 

IF  (FOUND  .NE.  0)  THEN 

PRINT  *,  VAL,  '  found  in  list!' 

ELSE 

PRINT  *,  VAL,  '  NOT  found!' 

END  IF 


for (  i=0  ;  i<1000  ;  ++i  )1  /*  Put  1000  pixels  on  screen  */ 

temp  =  width  -  1; 

f rand (  &rand  val,  Stemp  );  /*  Call  F77L's  RND  function  */ 

x  =  rand_val  +  1; 

temp  =  height  -  1; 

frand(  Srand_val,  Stemp  ); 

y  =  rand_val  +  1; 

frand(  srand_val,  sMaxColors  ); 

color  =  rand_val; 

putpixel (  x,  y,  color  ); 

}  /*  End  for  loop  */ 


}  /*  End  RandomDot ()  */ 


End  Listing  One 


End  Listing  Three 


102 

560 


Dr.  Dobb’s Journal,  August  1989 


FORTRAN  CONNECTION 

POSTSCRIPT 

Listing  Four 

Listing  One  (Text  begins  on  page  30.) 

“  q_sort() 

Name:  pcx.c 

Author:  Kent  J.  Quirk 

“  integer  width  and  will  sort  it  in  ascending  or  descending  order. 

Abstract:  This  file  contains  subroutines  to  read  PCX  files. 

“  Nothing  is  returned  —  status  always  equals  zero  if  any  checking 

. 

“  is  done  by  the  FORTRAN  calling  program. 

“  inputs:  array  ptr  to  array 

“  length  number  of  elements  in  array 

♦include  <stdlib.h> 

♦include  <malloc.h> 

“  order  0  =  ascending 

“  1  =  descending 

♦include  <memory.h> 

♦include  "pcx.h" 

/““  pcx  read  header  **“ 

Abstract:  Reads  the  header  of  a  PCX  file. 

♦include  <stdio.h> 

♦include  <stdlib.h> 

Parameters:  A  data  storage  area  for  the  header,  an  open  file. 

Returns:  The  pointer  to  the  data  storage  area  passed,  or  NULL  if  error. 

Comments:  The  file  should  be  opened  in  binary  mode. 

****************************/ 

int  ascending  (void  ‘first, void  ‘second); 

PCX_HDR  *pcx_read_header (PCX_HDR  *hdr,  FILE  *f) 

int  descending  (void  ‘first, void  ‘second); 

int  bin  search  (void  ‘array,  int  ‘length,  int  ‘key) ; 

( 

fseek(f,  0L,  SEEK_SET) ;  /*  header  is  at  top  of  file  */ 

if  (fread(hdr,  1,  sizeof (PCX  HDR) ,  f)  !=  sizeof (PCX  HDR) ) 

int  q_sort  (void  ‘array, int  ‘length, int  ‘order) 

return (NULL) ; 

int  status  =  0;  /*  return  value  */ 

return (hdr) ; 

) 

qsort  (array, (size  t)  ‘length, sizeof  (int), 

/““  pcx  print  header  ““ 

(int (*) (const  void  *, const  void  *))  ((‘order  ==  0)  ?  ascending  :  descending)); 

Abstract:  Printf's  a  PCX  file  header  data  to  a  given  file. 

return  (status) ; 

Parameters:  The  PCX  file  header,  the  file  to  write  the  data  to. 

)  /*  end  of  do  sort()  */ 

Returns:  Nothing 

/*  ascending () 

void  pcx  print  header (PCX  HDR  *hdr,  FILE  *f) 

“  This  function  is  used  by  qsort  and/or  bsearch  to  return  a 

“  value  based  on  the  comparison  of  two  inputs,  qsort  uses  this 

( 

char  *t; 

“  function  to  perform  an  ascending  sort. 

“  inputs:  first  ptr  to  first  element 

if  (hdr->pcx  id  !=  OxOA) 

I 

“  second  ptr  to  second  element 

fprintf(f,  "Not  a  PCX  file.W); 

“  return:  result  of  comparison 

return; 

int  ascending  (void  *pl,  void  *p2) 

( 

switch  (hdr->version)  { 
case  0:  t=”2.5";  break; 

case  2:  t="2.8  with  oalette  info.";  break; 

return  ({‘(int  *)  pi  <  *(int  *)  p2)  ?  (-1)  :  ( * ( int  *)  pi  ==  *(int  *)  p2)  ? 

case  3:  t="2.8  without  palette  info.";  break; 

(0)  :  (1)); 

I 

case  5:  t="3.0";  break; 
default:  t="unknown. ";  break; 

/*  descending () 

fprintf(f,  "PCX  Version  %s\n",  t); 

“  This  function  is  used  by  qsort  and/or  bsearch  to  return  a 

fprintf(f,  "Compression:  %s\n", 

“  value  based  on  the  comparison  of  two  inputs,  qsort  uses  this 

hdr->encoding==l  ?  "Run  length"  :  "Unknown") ; 

“  function  to  perform  a  descending  sort. 

fprintf(f,  "%d  bits  per  pixel\n",  hdr->bpp) ; 

“  inputs:  first  ptr  to  first  element 

fprintf(f,  "Image  from  (%d,  %d)  to  (%d,  %d)  pixels. \n". 

“  second  ptr  to  second  element 

hdr->upleftx,  hdr->uplefty,  hdr->lorightx,  hdr->lorighty) ; 

“  return:  result  of  comparison 

fprintf(f,  "Created  on  a  device  with  %d  x  %d  dpi  resolution. \n", 

*/ 

hdr->display  xres,  hdr->display  yres) ; 

int  descending  (void  *pl,  void  *p2) 

1 

fpnntf(f,  "The  image  contains  %d  image  planes.  \n",  hdr->nplanes)  ; 
fprintf(f,  "There  are  %d  bytes  per  line  of  data  after  decompression. \n", 

hdr->bytesperline) ; 

return  ((‘(int  *)  pi  <  *(int  *)  p2)  ?  (1)  :  (Mint  *)  pi  ==  Mint  *)  p2)  ?  (0) 

fprintf(f,  "There  are  %ld  total  bytes  in  the  image. \n", 

:  (-D); 

( (long)hdr->lorighty  -  (long) hdr->uplefty  +  1)  * 

) 

(long) hdr->bytesperline) ; 

return; 

/*  bin  search)) 

) 

**  This  function  takes  a  sorted  FORTRAN  array  and  a  key  and 

/““  pCX  alloc  line  ““ 

“  attempts  to  locate  the  key  value  using  C's  bsearch ().  The 

Abstract:  Allocates  enough  space  to  store  a  complete  scan  line  from  the 

“  function  passes  back  the  value  if  found,  or  0  if  not  found. 

current  PCX  file. 

“  inputs:  array  ptr  to  an  array 

Parameters:  The  header  pointer. 

“  length  length  of  the  array 

Returns:  A  pointer  to  a  "big  enough"  block  of  allocated  space,  or 

“  key  ptr  to  a  key  value 

null  if  not  enough  space  or  an  error  occurred. 

“  return:  result  of  search 

*/ 

***********,*******.*.******/ 

BYTE  *pcx_alloc_line (PCX_HDR  *hdr) 
f 

int  bin_search  (void  ‘array,  int  ‘length,  int  ‘key) 

return (calloc (hdr->nplanes,  hdr->bytes?erline) ) ; 

int  *ptr; 

/**“  pcx  next  line  ““ 

ptr  =  (int  *)  bsearch (key,  array,  (size_t)  ‘length,  sizeof (int),  ascending); 

Abstract:  Reads  the  next  line  from  the  PCX  file. 

Parameters:  Pointer  to  the  header,  a  pointer  to  the  line  area  (or  NULL 

return (ptr  !=  NULL); 

for  automatic  allocation),  and  the  open  data  file. 

) 

Returns:  A  pointer  to  the  line  area,  or  NULL  if  there  was  a  problem. 

Comments:  To  read  the  first  line,  call  pcx  read  header ()  first. 

This  sets  the  file  position  to  the  beginning  of  the  data. 

BYTE  *pcx_next_line(PCX_HDR  *hdr,  BYTE  ‘line,  FILE  *f) 

int  c,  len; 

BYTE  *dp; 

WORD  linesize  =  hdr->nplanes  *  hdr->bytesperline; 

WORD  i; 

if  (line  ==  NULL) 

End  Listings 

if  ((line  =  pcx  alloc  line (hdr))  ==  NULL) 

return (line) ; 

dp  =  line;  /*  point  to  data  */ 

for  (i=0;  i<linesize;  ) 

if  ((c  =  fgetc(f))  ==  EOF) 

return (NULL) ; 

if  ((c  S  PCX_COMPRESSED)  ==  PCX_COMPRESSED) 

len  =  (c  &  PCX  MASK); 

if  ( (c  =  fgetc(f))  ==  EOF) 

return (NULL) ; 

memset (dp,  (BYTE)c,  len); 
dp  +=  len; 
i  +=  len; 

else 

*dp++  =  (BYTE) c; 

i++; 

) 

) 

}  End  Listing  One 
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Listing  Two  (Listing  continued,  text  begins  on  page  30.) 


Listing  Three 


Name :  pcx . h 

Author:  Kent  J.  Quirk 

Abstract:  This  file  contains  information  required  when  handling 

PCX  files. 


Need  these  to  handle  the  PCX  data  below. 


typedef  unsigned  char  BYTE; 
typedef  unsigned  int  WORD; 


This  is  the  definition  of  the  PCX  1 

typedef  struct  { 

BYTE  pcx_id; 

BYTE  version; 

BYTE  encoding; 

BYTE  bpp; 

WORD  upleftx,  uplefty; 

WORD  lorightx,  lorighty; 

WORD  display_xres,  display_yres; 
BYTE  palette [48]; 

BYTE  reserved; 

BYTE  nplanes; 

WORD  bytesperline; 

WORD  palletteinfo; 

BYTE  reserved2 [58] ; 

]  PCX  HDR; 


/*  Always  OxOA  for  PCX  files  */ 

/*  Version  of  the  PCX  format  */ 

/*  1  =  RLE  (RLL)  compression  »/ 

/*  Number  of  bits  per  pixel  */ 

/*  position  of  upper  left  corner  */ 

/*  lower  right  corner  (inclusive)  */ 
/*  resolution  in  dpi  of  display  */ 

/*  palette  data  if  it  fits  */ 

/*  number  of  bit  planes  of  data  */ 

/*  #  bytes  in  an  uncompressed  line  */ 


These  two  definitions  are  used  to  decompress  data  in  the  PCX  file. 
(The  compressed  count  byte  has  the  top  two  bits  set) . 

*»****,*, **.***..**.*/ 

♦define  PCX_COMPRESSED  OxCO 
#def ine  PCX  MASK  0x3F 


These  prototypes  declare  the  PCX  read  subroutines. 
*********************/ 

PCX_HDR  *pcx_read_header (PCX_HDR  ‘hdr,  FILE  *f); 

BYTE  *pcx_alloc_line (PCX_HDR  *hdr); 

BYTE  *pcx_next_line (PCX_HDR  *hdrf  BYTE  ‘line,  FILE  *f); 
void  pcx_print_header (PCX_HDR  *hdr,  FILE  *f); 


End  Listing  Two 


Name:  prpcx.c 

Author:  Kent  J.  Quirk 

Abstract:  This  program  prints  .PCX  files  (as  created  by  PC  Paintbrush 

and  other  software)  on  a  PostScript  printer  by  converting 
them  to  a  PS-compatible  image.  The  user  can  scale  and 
position  the  image. 

-»/ 

♦include  <stdio.h> 

♦include  <stdlib.h> 

♦include  <memory.h> 

♦include  <string.h> 

♦define  BUFSIZE  100 

♦include  "pcx.h" 

typedef  struct  { 
int  xpos; 
int  ypos; 
int  width; 
int  height; 
int  scale; 
int  invert; 
int  prt_res; 
int  dumphdr; 

)  MAPPING; 

/““  copy_ps_header  ““ 

Abstract:  Opens  the  PS  header  file  and  copies  it  to  the  output. 

Parameters:  Filename  of  the  current  file  (the  .PS  extension  is  added 
here)  and  the  output  file  pointer. 

Returns:  0  if  successful,  1  if  failure. 

char  *copy_ps_header (char  ‘name,  FILE  ‘outfile,  char  ‘stop) 

I 

static  char  buf [BUFSIZE] ; 
char  *bp; 

static  FILE  *f  =  NULL; 
if  (f  ==  NULL) 

< 

strcpy(buf,  name); 

if  ((bp  =  strchr(buf,  '.'))  !=  NULL) 

*bp  =  0; 

strcat(buf,  ".ps");  /*  open  file  with  this  name  but  .ps  ext  */ 

if  ((f  =  fopen(buf,  "r"))  ==  NULL) 

( 

fprintf (stderr,  "Unable  to  open  PostScript  header  file  '%s'\n", 
buf) ; 

return (NULL) ; 


fputs(buf,  outfile); 

} 

while  (fgets  (buf,  BUFSIZE,  f) 


if  ((stop  !=  NULL)  &&  (strncmp (buf ,  stop,  strlen (stop) )  ==  0)) 
return (buf);  /*  bail  out  right  now  */ 

fputs(buf,  outfile); 

1 

fclose (f ) ; 
f  =  NULL; 
return (NULL) ; 


/***.  d  o  f  i  1  e  ““ 

Abstract:  Processes  a  single  PCX  file. 

Parameters:  char  ‘filename  -  the  input  PCX  filename  (.PCX  optional) 

MAPPING  ‘map  -  the  structure  containing  page  position  info 
char  ‘psname  -  the  PostScript  prologue  (.PS  will  be  forced) 
FILE  ‘outfile  -  the  open  output  file 
Returns:  0  if  successful,  1  if  no  file  generated 

int  dofile(char  ‘filename,  MAPPING  ‘map,  char  ‘psname,  FILE  ‘outfile) 

( 

FILE  *f ; 

PCX_HDR  hdr; 

WORD  i,  j,  xsize,  ysize; 

BYTE  ‘lineptr  =  NULL; 
char  *t; 

char  buf [BUFSIZE] ; 
long  bbox_x,  bbox_y; 
strcpy(buf,  filename); 
if  (strchr(buf,  '.')  ==  NULL) 

strcatlbuf,  ".pcx");  /*  add  .PCX  if  needed  */ 

if  ((f  =  f open (buf,  "rb"))  ==  NULL) 

( 

fprintf (stderr,  "Unable  to  open  ' %s'\n",  buf); 
return  (1) ; 

I 

if  (pcx_read_header (Shdr,  f)  ==  NULL) 

{ 

fprintf (stderr,  "Unable  to  read  header  for  file  '%s'.\n",  buf)  ; 
fclose (f ) ; 
return  (1) ; 

) 

if  (map->dumphdr) 

I 

pcx_print_header (&hdr,  stdout) ; 
return  (1) ; 

) 

if  (hdr. nplanes  !=  1) 

( 

fprintf (stderr,  "Only  able  to  read  monochrome  .PCX  files. \n"); 
fclose (f ) ; 
return  (1) ; 
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Listing  Three  (Listing  continued,  text  begins  on  page  30.) 

i 

xsize  =  hdr . lorightx  -  hdr.upleftx  +  1; 
ysize  =  hdr.lorighty  -  hdr.uplefty  +1; 


t  =  copy_ps_header (psname,  outfile,  "%%BoundingBox” ) ; 

bbox_x  =  (long) xsize  *  (long) map->width  *  (long)map->scale  /  10000L; 

bbox_y  =  (long) ysize  *  (long)map->height  *  (long)map->scale  /  10000L; 

bbox_x  +=  map->xpos; 

bbox_y  +=  map->ypos; 

sprintf(t,  "%%%%BoundingBox:  %d  %d  %ld  %ld\n",  map->xpos,  map->ypos, 
bbox  x,  bbox_y) ; 

t  =  copy_ps_header {psname,  outfile,  NULL); 


fprintf (outfile,  "/bmap_wid  %d  def\n",  xsize); 
fprintf (outfile,  "/bmap_hgt  %d  def\n",  ysize); 
fprintf (outfile,  "/bpp  %d  def\n",  hdr.bpp); 
fprintf  (outfile,  "/'res  %d  def\n\n",  map->prt_res) ; 
fprintf (outfile,  "/x  %d  def\n",  map->xpos); 
fprintf (outfile,  "/ y  %d  def\n\n",  map->ypos); 
fprintf (outfile,  "/ scy  %d  100  div  def\n",  map->height) ; 
fprintf (outfile,  "/sex  %d  100  div  def\n",  map->width) ; 
fprintf (outfile,  "/ seg  %d  100  div  def\n\n",  map->scale) ; 
fprintf (outfile,  "scaleitXn") ; 
fprintf (outfile,  "imagedata\n\n") ; 
for  (i=0;  i<ysize;  i++) 


lineptr  =  pcx_next_line (&hdr,  lineptr,  f); 
if  (map->invert)  /*  invert  if  necessary  */ 

for  (j=0;  j  <  xsize/8;  j++) 
lineptr (j)  =  -lineptr [j]; 
for  (j=0;  j  <  xsize/8;  j++) 

fprintf (outfile,  "%02X",  lineptr (j]); 
fprintf (outfile,  "\n"); 

) 

fprintf (outfile,  "\nshowit\n") ; 
free (lineptr) ; 
fclose  (f ) ; 
return  (0) ; 

) 

/““  usage  “** 

Abstract:  Prints  a  usage  message  and  dies. 

Parameters:  None 
Returns:  Never  returns. 

void  usage () 


printf ("PRPCX:  by  Kent  QuirkXn"); 

printf ("  Given  a  .PCX  file,  this  program  creates  a  PostScript  file  \n"); 
printf  ("  which  will  print  the  image. \n"); 

printf (”  PRPCX  [-wW]  [ -hH ]  [ -xX]  [ -yY]  [ -sS )  ( -rR]  [ -d )  ( -i ]  filenameXn") ; 

printf  ("  Options  include:  (units)  [default ) \n") ; 

printf  ("  -sSCA  set  overall  scale  factor  (percent)  [100] \n") ; 

printf {"  -wWID  set  horizontal  scale  factor  (percent)  [100] \n") ; 

printf  ("  -hHGT  set  vertical  scale  factor  (percent)  [100] \n"); 

printf  ("  -xPOS  set  horizontal  position  (points  from  left)  [0 ] \n“ ) ; 

printf ("  -yPOS  set  vertical  position  (points  from  bottom)  [0]\n"); 

printf ("  -rRES  set  printer  resolution  (dpi)  [300] \n") ; 

printf ("  -d  dump  PCX  file  info  to  stdout  [off]\n"); 

printf ("  -i  invert  image  [off]\n"); 

printf  ("  -oFIL  set  output  filename,  or  use  SET  PRPCX=f ilenameXn") ; 
printf  ("  The  defaults  print  the  image  at  one  pixel  per  device  pixelXn"); 

printf ("  at  the  lower  left  corner  of  the  page.Xn"); 

printf {"  PRPCX.PS  must  be  in  the  same  directory  as  PRPCX.EXE. \n") ; 
exit  (1) ; 


} 


, ““  main  “** 

The  main  routine  for  PRPCX.  Sets  defaults,  parses  command  line, 
and  calls  dof ile () . 

int  main(int  arge,  char  *argv[|) 
f 

int  i; 

MAPPING  map; 

FILE  *outfile  =  stdout; 
char  *outfname  =  NULL; 
char  ‘filename  -  NULL; 
map.xpos  =  map.ypos  =  0; 
map. width  =  map. height  =  map. scale  =  100; 
map. invert  =  0; 
map.prt_res  =  300; 
map.dumphdr  =  0; 
if  (arge  <  2) 
usage ( ) ; 

for  (i=l;  i<argc;  i++) 

( 

if  (argv[i] [0]  II  argv[i] [0]  ==  '/') 

( 

switch  (argv[i] [1] ) 

( 

case  ' x' :  case  'X' : 

map.xpos  =  atoi (argv [i] +2) ; 
break; 

case  ' y' :  case  ' Y'  : 

map.ypos  =  atoi (argv [i] +2) ; 
break; 

case  'h' :  case  'H'  : 

map. height  =  atoi (argv[i]+2) ; 
break; 

case  ' w' :  case  '  W'  : 

map. width  =  atoi (argv [i] +2) ; 
break; 

case  ' s' :  case  ' S' : 

map. scale  =  atoi (argv [i] +2) ; 
break; 

case  ' r' :  case  '  R'  : 

map.prt_res  =  atoi (argv[i]+2) ; 
break; 


case  ' i' :  case  ' I' : 

map. invert  =  ! map. invert; 
break; 

case  ' d' :  case  ' D' : 
map.dumphdr  =  1; 
break ; 

case  'o' :  case  'O' : 

out f name  =  argv [i] +2; 
break; 
case  ' ?' : 
usage ( ) ; 
break; 
default : 

fprintf (stderr,  "Unknown  option  %s\n",  argv[i]); 

usage ( ) ; 

break; 


else  /*  process  a  file  */ 

I 

filename  =  argv[i]; 

} 


if  ( (out f name  !=  NULL)  ;;  ( (out f name  =  getenv ("PRPCX" ) )  !=  NULL)) 

{ 

if  ((outfile  =  fopen (out f name,  "w"))  ==  NULL) 

( 

fprintf (stderr, "Unable  to  open  output  file  %s",  out f name ) ; 
exit  (1) ; 

1 

I 

i  =  dof ile (filename,  &map,  argv[0],  outfile); 
fclose (outfile) ; 
return (i) ; 


End  Listing  Three 


Listing  Four 

#  Program:  PRPCX 


.c .obj : 

cl  -c  -W2  -Zid  -Od  -AS  $*.c 

pcx.obj  :  pcx.c  pcx.h 

prpcx.obj  :  prpcx.c  pcx.h 

prpcx.exe  :  prpcx.obj  pcx.obj 

echo  prpcx.obj+  >prpcx.lnk 

echo  pcx.obj  >>prpcx.lnk 

echo  prpcx.exe  >>prpcx.lnk 

echo  nul  »prpcx.lnk 

link  /NOI  $ (LDFLAGS)  @prpcx.lnk; 


End  Listing  Four 


Listing  Five 

% ! PS -Adobe  1.0 
%%Title: 

%%Creator : 

%%Pages:  1 
%%BoundingBox: 

%%EndComments 

gsave 

%  the  next  item  translates  the  image  from 
%  top-to-bottom  .PCX  format  to  PS  bottom-to-top 

/xform 

{ 

[  bmap_wid  0  0  bmap_hgt  neg  0  bmap_hgt  ] 

)  def 

/readproc 

I 

(  currentfile  picstr  readhexstring  pop  J 
)  def 

/scaleit 

{ 

x  y  translate 
bmap_wxd  bmap_hgt  scale 
72  res  div  72  res  div  scale 
sex  seg  mul  scy  seg  mul  scale 

/picstr  bmap_wid  8  idiv  string  def 

}  def 

/imagedata 

( 

bmap_wid  bmap_hgt  bpp  xform  readproc  image 
)  def 

/showit 

( 

grestore 
showpage 
)  def 

%  Will  generate  <bmap_hgt>  lines  of  image  data, 

%  each  with  <bmap_wid>/8  bytes  of  data  (in  hex) . 

%%EndProiog  End  Listings 
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listing  One  (Text  begins  on  page  38.) 


10 

11 

12 

13 

14 

15 

16 

17 

18 

19 

20 
21 
22 

23 

24 

25 

26 

27 

28 

29 

30 

31 

32 

33 

34 

35 

36 

37 

38 

39 

40 

41 

42 

43 

44 

45 

46 

47 

48 

49 

50 

51 

52 

53 

54 

55 

56 

57 

58 

59 

60 
61 
62 

63 

64 

65 

66 

67 

68 

69 

70 

71 

72 

73 

74 

75 

76 

77 

78 

79 

80 
81 
82 

83 

84 

85 

86 

87 

88 

89 

90 

91 

92 

93 

94 
95: 
96: 
97: 
98: 
99: 

100: 

101: 

102: 

103: 

104: 

105: 

106: 

107: 

108: 

109: 

110: 


/*  Recursive  descent  parser  for  integer  expressions 
which  may  include  variables  and  function  calls, 
♦include  "setjmp.h" 

♦include  "math.h" 

♦include  "ctype.h" 

♦include  "stdlib.h" 

♦include  "string. h" 

♦include  "stdio.h" 

♦define  NUM_FUNC  100 

♦define  NUM_GLOBAL_VARS  100 

♦define  NUM_LOCAL_VARS  200 

♦define  ID_LEN  31 

♦define  FUNC_CALLS  31 

♦define  PROG_SIZE  10000 

♦define  FOR  NEST  31 


enum  tok_types  {DELIMITER,  IDENTIFIER,  NUMBER,  KEYWORD,  TEMP, 
STRING,  BLOCK}; 

enum  tokens  (ARG,  CHAR,  INT,  IF,  ELSE,  FOR,  DO,  WHILE,  SWITCH, 
RETURN,  EOL,  FINISHED,  END); 
enum  double_ops  {LT=1,  LE,  GT,  GE,  EQ,  NE); 

/*  These  are  the  constants  used  to  call  sntx_err()  when 
a  syntax  error  occurs.  Add  more  if  you  like. 

NOTE:  SYNTAX  is  a  generic  error  message  used  when 
nothing  else  seems  appropriate. 

*/ 

enum  error_msg 

{SYNTAX,  UNBAL_P ARENS ,  NO_EXP,  EQUALS_EXP ECTED , 

NOT_VAR,  PARAM_ERR,  SEMI_EXPECTED , 

UNBAL_BRACES,  FUNCJJNDEF,  TYPE_EXPECTED, 

NEST_FUNC,  RET_NOCALL,  PAREN_EXPECTED , 

WHILE_EXPECTED,  QUOTE_EXPECTED ,  NOT_TEMP , 

TOO_MANY_LVARS } ; 

extern  char  *prog;  /*  current  location  in  source  code  */ 
extern  char  *p_buf;  /*  points  to  start  of  program  buffer  */ 
extern  jmp_buf  e_buf;  /*  hold  environment  for  longjmpO  */ 

/*  An  array  of  these  structures  will  hold  the  info 
associated  with  global  variables. 

*/ 

extern  struct  var_type  { 
char  var_name[32] ; 
enum  variable_type  var_type; 
int  value; 

)  globa l_va rs [ NUM_GLOBAL_VARS ] ; 

/*  This  is  the  function  call  stack.  */ 
extern  struct  func_type  { 
char  func_name [32] ; 

char  *loc;  /*  location  of  function  entry  point  in  file  */ 

}  func_stack [NUM_FUNC] ; 

/*  Keyword  table  */ 
extern  struct  commands  ( 
char  command [20]; 
char  tok; 

1  tablet]  ; 

/*  "Standard  library"  functions  are  declared  here  so 
they  can  be  put  into  the  internal  function  table  that 
follows . 

*/ 

int  call_getche (void) ,  cal l_putch (void) ; 

int  call_puts (void) ,  print (void),  getnum (void) ; 

struct  intern_func_type  ( 

char  *f_name;  /*  function  name  */ 

int  {*  p)();  /*  pointer  to  the  function  */ 

}  intern_func[]  =  ( 

"getche",  call_getche, 

"putch",  call_putch, 

"puts",  call_puts, 

"print",  print, 

"getnum",  getnum, 

0  /*  null  terminate  the  list  */ 

); 

extern  char  token[80];  /*  string  representation  of  token  */ 
extern  char  token_type;  /*  contains  type  of  token  */ 
extern  char  tok;  /*  internal  representation  of  token  */ 
extern  int  ret_value;  /*  function  return  value  */ 
void  eval_exp(int  ‘value),  eval_expl (int  ‘value); 
void  eval_exp2 (int  ‘value); 

void  eval_exp3 (int  ‘value),  eval_exp4 (int  ‘value); 

void  eval_exp5 (int  ‘value),  atom(int  ‘value); 

void  eval_exp0 (int  ‘value); 

void  sntx_err(int  error),  putback (void) ; 

void  assign_var (char  ‘varname,  int  value); 

int  isdelim(char  c),  look_up(char  *s),  iswhite(char  c) ; 

int  find_var (char  *s),  get_token (void) ; 

int  internal_func(char  *s); 

int  is_var(char  *s); 

char  *f ind_func (char  ‘name); 

void  call (void) ; 

/*  Entry  point  into  parser.  */ 
void  eval_exp(int  ‘value) 

( 

get_token () ; 
if  (! ‘token)  ( 
sntx_err (NO_EXP) ; 
return; 

) 

if  (*token==' ; ' )  ( 

‘value  =  0;  /*  empty  expression  */ 
return; 

) 

eval_expO (value)  ; 

putback {);  /*  return  last  token  read  to  input  stream  */ 

) 

/*  Process  an  assignment  expression  */ 
void  eval_expO (int  ‘value) 


char  temp [ID_LEN] ; 


holds  name  of  var  receiving 
the  assignment  */ 


111 

112 

113 

114 

115 

116 

117 

118 

119 

120 
121 
122 

123 

124 

125 

126 

127 

128 

129 

130 

131 

132 
133: 
134 
135: 

136 

137 

138 

139 

140 

141 

142 

143 

144 

145 

146 

147 

148 


168 

169 

170 

171 
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173 

174 

175 

176 

177 

178 

179 

180 
181 
182 
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184 

185 

186 
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188 

189 

190 

191 

192 

193 

194 

195 
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197 

198 

199 

200 
201 
202 

203 

204 

205 

206 

207 

208 

209 

210 
211 
212 

213 

214 

215 

216 

217 

218 

219 

220 
221 
222 


register  int  temp_tok; 
if  (token_type==IDENTIFIER)  { 

if (is_var (token) )  {  /*  if  a  var,  see  if  assignment  */ 

strcpy(temp,  token); 
temp_tok  =  token_type; 
get_token () ; 

if (*token==' =' )  {  /*  is  an  assignment  */ 

gettoken ( ) ; 

eval_exp0 (value) ;  /*  get  value  to  assign  */ 

assign_var (temp,  ‘value);  /*  assign  the  value  */ 
return; 

) 

else  {  /*  not  an  assignment  */ 

putback ();  /*  restore  original  token  */ 

strcpy (token,  temp); 
token_type  =  temp_tok; 

) 


eval_expl (value) ; 

) 

/*  This  array  is  used  by  eval_expl().  Because 

some  compilers  cannot  initialize  an  array  within  a 
function  it  is  defined  as  a  global  variable. 

*/ 

char  relops [7]  =  ( 

LT,  LE,  GT,  GE,  EQ,  NE,  0 

)  ; 

/*  Process  relational  operators.  */ 
void  eval_expl (int  ‘value) 

( 

int  partial_value; 
register  char  op; 
eval_exp2 (value) ; 
op  =  ‘token; 

if (strchr (relops,  op))  { 
get_token ( ) ; 


149 

switch (op)  ( 

/*  perform  the  relational  operation 

150 

case  LT: 

151 

‘value  = 

‘value  <  partial_value; 

152 

break; 

153 

case  LE: 

154 

‘value  = 

‘value  <=  partial_value; 

155 

break; 

156 

case  GT: 

157 

‘value  = 

‘value  >  partial_value; 

158 

break; 

159 

case  GE: 

160 

‘value  = 

‘value  >=  partial_value; 

161 

break; 

162 

case  EQ: 

163 

‘value  - 

‘value  ==  partial  value; 

164 

break; 

165 

case  NE: 

166 

‘value  = 

‘value  !=  partial_value; 

167 

break; 

/*  Add  or  subtract  two  terms.  */ 
void  eval_exp2 (int  ‘value) 

{ 

register  char  op; 
int  partial_value; 
eval_exp3 (value) ; 

while  ((op  =  ‘token)  ==  '+'  J!  op  ==  '-')  ( 
get_token () ; 

eval_exp3 (&partial_value) ; 
switch(op)  (  /*  add  or  subtract  */ 

case  ' : 

‘value  =  ‘value  -  partial_value; 
break; 


case  +' : 
‘value  = 
break; 


value  +  partial_value; 


==  >/' 


*/ 


/*  Multiply  or  divide  two  factors, 
void  eval_exp3 (int  ‘value) 

{ 

register  char  op; 
int  partial_value,  t; 
eval_exp4 (value) ; 
while((op  =  ‘token)  ==  '*'  ! 1  op 
get_token ( ) ; 

eval_exp4 (&partial_value) ; 
switch (op)  (  /*  mul,  div,  or  modulus 
case  ' *' : 

‘value  =  ‘value  *  partial_value; 
break; 
case  ' /' : 

‘value  =  (‘value)  /  partial_value; 
break; 
case  ' : 

t  =  (‘value)  /  partial_value; 

‘value  =  ‘value- (t  *  partial_value) ; 
break; 

) 

) 

) 

/*  Is  a  unary  +  or  -.  */ 
void  eval_exp4 (int  ‘value) 

( 

register  char  op; 
op  =  ' \0' ; 

if (*token==' +'  ;;  *token=='-')  ( 
op  =  ‘token; 
get_token () ; 

> 

eval_exp5 (value)  ; 


op  ==  ' %' ) 


no 
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223:  if (op) 

224:  if(op=='-')  ‘value  =  -(‘value); 

225:  ) 

226:  /*  Process  parenthesized  expression.  */ 

227:  void  eval_exp5 (int  *value) 

228:  { 

229:  if((*token  ==  '('))  ( 

230:  get_token(); 

231:  eval_exp0 (value) ;  /*  get  subexpression  */ 

232 :  if (‘token  !=  ' ) ' )  sntx_err ( P AREN_EXPECTED ) ; 

233:  get_token() ; 

234:  } 

235:  else 

236:  atom (value); 

237:  ( 

238:  /*  Find  value  of  number,  variable  or  function.  */ 

239:  void  atom (int  ‘value) 

240:  { 

241:  int  i ; 

242:  switch (token_type)  ( 

243:  case  IDENTIFIER: 

244:  i  =  internal_func (token) ; 

245:  if (i ! =  -1)  (  /‘  call  "standard  library"  function  */ 

246:  ‘value  =  (*intern_func [i] .p) () ; 

247  :  } 

248:  else 

249:  if (find_func (token) ) {  /*  call  user-defined  function 

250:  call  () ; 

251:  ‘value  =  ret_value; 

252:  ) 

253:  else  ‘value  =  find_var (token) ;  /*  get  var's  value  1 

254:  get_token(); 

255:  return; 

256:  case  NUMBER:  /*  is  numeric  constant  */ 

257:  ‘value  =  atoi (token); 

258:  get_token(); 

259:  return; 

260:  case  DELIMITER:  /*  see  if  character  constant  */ 

261:  if  (*token==' \" )  ( 

262:  ‘value  =  ‘prog; 

263:  prog++; 

264  :  if  (*prog!='\")  sntx_err (QUOTE_EXPECTED) ; 

265:  prog++; 

266:  get_token{); 

267:  } 

268:  return; 

269:  default: 

270:  if (*token==' ) ' )  return;  /*  process  empty  expression  * 

271:  else  sntx_err (SYNTAX) ;  /*  syntax  error  */ 

272:  ) 

273:  1 

274:  /*  Display  an  error  message.  */ 

275:  void  sntx_err(int  error) 

276:  { 

277:  char  *p,  ‘temp; 

278:  int  linecount  =  0; 

279:  register  int  i; 

280:  static  char  *e[]=  { 

281:  "syntax  error", 

282:  "unbalanced  parentheses", 

283:  "no  expression  present", 

284:  "equals  sign  expected", 

285:  "not  a  variable", 

286:  "parameter  error", 

287:  "semicolon  expected", 

288:  "unbalanced  braces", 

289:  "function  undefined", 

290:  "type  specifier  expected", 

291:  "too  many  nested  function  calls", 

292:  "return  without  call", 

293:  "parentheses  expected", 

294:  "while  expected", 

295:  "closing  quote  expected", 

296:  "not  a  string", 

297:  "too  many  local  variables" 

298:  } ; 

299:  printf("%s",  e [error]); 

300:  p  =  p_buf; 

301:  while (p  !=  prog)  (  /*  find  line  number  of  error  ‘/ 

302:  p++; 

303:  if (*p  ==  ' \r' )  { 

304:  linecount++; 

305:  } 

306:  ) 

307:  printf{"  in  line  %d\n",  linecount); 

308:  temp  =  p; 

309:  for(i=0;  i<20  &&  p>p_buf  &&  *p!='\n';  i++,  p — ); 

310:  for(i=0;  i<30  &&  p<=temp;  i++,  p++)  printf("%c",  *p) ; 

311:  longjmp(e_buf,  1);  /*  return  to  save  point  */ 

312:  } 

313:  /*  Get  a  token.  */ 

314:  get_token (void) 

315:  { 

316:  register  char  ‘temp; 

317:  token_type  =  0;  tok  =  0; 

318:  temp  =  token; 

319:  ‘temp  =  ' \0' ; 

320:  /*  skip  over  white  space  */ 

321:  while (iswhite (*prog)  &&  *prog)  ++prog; 

322:  if (*prog=='\r')  ( 

323:  ++prog; 

324:  ++prog; 

325:  /*  skip  over  white  space  */ 

326:  while (iswhite (*prog)  &&  *prog)  ++prog; 

327:  } 

328 :  ‘token  =  ' \0' ; 

329:  if (*prog==' \0' )  (/*  end  of  file  */ 

330:  tok  =  FINISHED; 

331 :  return (token_type=DELIMITER) ; 

332:  } 

333:  if (strchr ("{)",  *prog) )  (  /*  block  delimiters  */ 


334:  ‘temp  =  ‘prog; 

335:  temp++; 

336:  ‘temp  =  ' \0' ; 

337:  prog++; 

338:  return  (tokentype  =  BLOCK); 

339:  ) 

340:  /*  look  for  comments  */ 

341:  if (*prog==' /' ) 

342:  if (* (prog+1) ==' *' )  (  /*  is  a  comment  */ 

343:  prog  +=  2; 

344:  do  {  /*  find  end  of  comment  */ 

345:  while (‘prog! ='*' )  prog++; 

346:  prog++; 

347:  )  while  ( ‘prog !='/') ; 

348:  prog++; 

349:  } 

350:  if (strchr (" !<>=",  *prog) )  (  /*  is  or  might  be 

351:  a  relation  operator  */ 

352:  switch (*prog)  ( 

353:  case  if (* (prog+l)=='=' )  ( 

354:  prog++;  prog++; 

355:  ‘temp  =  EQ; 

356:  temp++;  ‘temp  =  EQ;  temp++; 

357 :  ‘temp  =  ' \0' ; 

358:  } 

359:  break; 

360:  case  '!':  if (* (prog+1) =='=' )  { 

361:  prog++;  prog++; 

362:  ‘temp  -  NE; 

363:  temp++;  ‘temp  =  NE;  temp++; 

364 :  ‘temp  =  ' \0' ; 

365:  ) 

366:  break; 

367:  case  '<':  if (* (prog+1) *='=' )  ( 

368:  prog++;  prog++; 

369:  ‘temp  ■  LE;  temp++;  ‘temp  =  LE; 

370:  ) 

371:  else  { 

372:  prog++; 

373:  ‘temp  =  LT; 

374:  ) 

375:  temp++; 

376:  ‘temp  =  ' \0' ; 

377:  break; 

378:  case  if (* (prog+1 )=='=' )  ( 

379:  prog++;  prog++; 

380:  ‘temp  =  GE;  temp++;  ‘temp  =  GE; 

381:  ) 

382:  else  ( 

383:  prog++; 

384:  ‘temp  =  GT; 

385:  ) 

386:  temp++; 

387 :  ‘temp  =  ' \0' ; 

388:  break; 

389:  ) 

390:  if  (‘token)  return (token_type  =  DELIMITER); 

391:  ) 

392:  if  (strchr ("+-*A/%=; () ,' ",  *prog) ) (  /*  delimiter  */ 

393:  ‘temp  =  ‘prog; 

394:  prog++;  /*  advance  to  next  position  */ 

395:  temp++; 

396:  ‘temp  =  ' \0' ; 

397:  return  (token_type=DELIMITER) ; 

398:  ) 

399:  if (*prog==' )  (  /*  quoted  string  */ 

400:  prog++; 

401:  while (‘prog! *prog!='\r')  *temp++  =  *prog++; 

402:  if (*prog==' \r' )  sntx_err (SYNTAX) ; 

403:  prog++;  ‘temp  =  ' \ 0 ' ; 

404:  return (token_type=STRING) ; 

405:  ) 

406:  if (isdigit (*prog) )  (  /*  number  */ 

407:  while (! isdelim(*prog) )  *temp++  =  *prog++; 

408:  ‘temp  =  '\0'; 

409:  return (token_type  =  NUMBER); 

410:  ( 

411:  if (isalpha (*prog) )  {  /*  var  or  command  */ 

412:  while (! isdelim ( *prog) )  *temp++  =  *prog++; 

413:  token_type=TEMP; 

414:  } 

415:  ‘temp  =  ' \0' ; 

416:  /*  see  if  a  string  is  a  command  or  a  variable  */ 

417:  if (token_type==TEMP)  { 

418:  tok  =  look_up (token) ;  /*  convert  to  internal  rep  */ 

419:  if  (tok)  token_type  =  KEYWORD;  /*  is  a  keyword  */ 

420:  else  token_type  =  IDENTIFIER; 

421:  } 

422:  return  token_type; 

423:  ) 

424:  /*  Return  a  token  to  input  stream.  */ 

425:  void  putback (void) 

426:  | 

427:  char  *t; 

428:  t  =  token; 

429:  for(;  *t;  t++)  prog — ; 

430:  ) 

431:  /*  Look  up  a  token's  internal  representation  in  the 
432:  token  table. 

433:  ‘/ 

434:  look_up(char  *s) 

435:  ( 

436:  register  int  i; 

437:  char  *p; 

438:  /*  convert  to  lowercase  */ 

439:  p  =  s; 


Dr.  Dobb’s Journal,  August  1989 


113 

565 


C  INTERPRETER 


Listing  One  (Listing  continued,  text  begins  on  page  38.) 

76 

int  gvar  index;  /*  index  into  global  variable  table  */ 

77 

int  lvartos;  /*  index  into  local  variable  stack  */ 

440 

while(*p){  *p  =  tolower(*p);  p++;  } 

78 

int  ret  value;  /*  function  return  value  */ 

441 

/*  see  if  token  is  in  table  */ 

79 

void  print (void) ,  prescan (void) ; 

442 

for(i=0;  ‘table [i] .command;  i++) 

80 

void  decl  global (void) ,  call (void),  putback (void) ; 

443 

if (! strcmp (table [i] .command,  s) )  return  table (ij .tok; 

81 

void  decl  local (void),  local  push (struct  var  type  i); 

444 

return  0;  /*  unknown  command  */ 

82 

void  eval  exp (int  ‘value),  sntx  err  (int  error); 

445 

1 

83 

void  exec  if  (void),  find  eob(void),  exec  for (void); 

446 

/*  Return  index  of  internal  library  function  or  -1  if 

84 

void  get  params (void) ,  get  args (void) ; 

447 

not  found. 

85 

void  exec  while (void),  func  push (int  i) ,  exec  do (void); 

44 

*/ 

86 

void  assign  var (char  *var  name,  int  value); 

449 

internal  func(char  *s) 

87 

int  load  program(char  *p,  char  ‘fnarne),  find  var(char  *s) ; 

450 

{ 

88 

void  interp  block (void),  func  ret (void) ; 

451 

int  i; 

89 

int  func  pop (void),  is  var (char  *s) ,  get  token (void); 

452 

for(i=0;  intern  func[i].f  name[0];  i++)  { 

90 

char  ‘find  func (char  ‘name); 

453 

if (! strcmp (intern  func[i].f  name,  s))  return  i; 

91 

454 

} 

92 

main (int  argc,  char  *argv[]) 

455 

return  -1; 

93 

( 

456 

) 

94 

if (argc! =2)  ( 

457 

/*  Return  true  if  c  is  a  delimiter.  */ 

95 

printf ("usage:  c  <f ilename>\n" ) ; 

458 

isdelim(char  c) 

96 

exit (1) ; 

459 

( 

97 

} 

460 

if(strchr("  !;,+-<>' /*%A=() ",  c)  !!  c==9  || 

98 

/*  allocate  memory  for  the  program  */ 

461 

c=='\r'  I j  c==0)  return  1; 

99 

if ( (p  buf= (char  *)  malloc(PROG  SIZE) ) ==NULL)  ( 

462 

return  0; 

100 

printf ("allocation  failure"); 

463 

) 

101 

exit (1) ; 

464 

/*  Return  1  if  c  is  space  or  tab.  */ 

102 

) 

465 

iswhitefchar  c) 

103 

/*  load  the  program  to  execute  */ 

466 

( 

104 

if {! load  program (p  buf,  argv[l]))  exit(l); 

467 

if |c=='  '  |;  c=='\t')  return  1; 

105 

if (set jmp (e  buf))  exit(l);  /*  initialize  long  jump  buffer  */ 

468 

else  return  0; 

106 

/*  set  program  pointer  to  start  of  program  buffer  */ 

469 

} 

107 

prog  =  p  buf; 

108 

prescan ();  /*  find  the  location  of  all  functions 

End  Listing  One 

109 

and  global  variables  in  the  program  */ 

w  . 

no 

gvar  index  =  0;  /*  initialize  global  variable  index  */ 

Lisung  iwo 

111 

lvartos  =  0;  /*  initialize  local  variable  stack  index  */ 

112 

functos  =  0;  /*  initialize  the  CALL  stack  index  */ 

i 

/*  A  Little  C  interpreter.  */ 

113 

/*  setup  call  to  main()  */ 

2 

114 

prog  =  find  func ("main") ;  /*  find  program  starting  point  */ 

3 

♦include  "stdio.h" 

115 

prog — ;  /*  back  up  to  opening  (  */ 

4 

♦include  "setjmp.h" 

116 

strcpy (token,  "main"); 

5 

♦include  "math.h" 

117 

call();  /*  call  main()  to  start  interpreting  */ 

6 

♦include  "ctype.h" 

118 

I 

7 

♦include  "stdlib.h" 

119 

/*  Interpret  a  single  statement  or  block  of  code.  When 

8 

♦include  "string. h" 

120 

interp  block ()  returns  from  it's  initial  call,  the  final 

9 

121 

brace  (or  a  return)  in  main()  has  been  encountered. 

10 

♦define  NUM  FUNC  100 

122 

*/ 

11 

♦define  NUM  GLOBAL  VARS  100 

123 

void  interp  block (void) 

12 

♦define  NUM  LOCAL  VARS  200 

124 

{ 

13 

♦define  NUM  BLOCK  100 

125 

int  value; 

14 

♦define  ID  LEN  31 

126 

char  block  =  0; 

15 

♦define  FUNC  CALLS  31 

127 

do  ( 

16 

♦define  NUM  PARAMS  31 

128 

token  type  =  get  token (); 

17 

♦define  PROG  SIZE  10000 

129 

/*  If  interpreting  single  statement,  return  on 

18 

♦define  LOOP  NEST  31 

130 

first  semicolon. 

19 

131 

*/ 

20 

enum  tok  types  (DELIMITER,  IDENTIFIER,  NUMBER,  KEYWORD, 

132 

/*  see  what  kind  of  token  is  up  */ 

21 

TEMP,  STRING,  BLOCK); 

133 

if (token  type==IDENTIFIER)  ( 

22 

/*  add  additional  C  keyword  tokens  here  */ 

134 

/*  Not  a  keyword,  so  process  expression.  */ 

23 

enum  tokens  (ARG,  CHAR,  INT,  IF,  ELSE,  FOR,  DO,  WHILE, 

135 

putback ();  /*  restore  token  to  input  stream  for 

24 

SWITCH,  RETURN,  EOL,  FINISHED,  END); 

136 

further  processing  by  eval  exp()  */ 

25 

/*  add  additional  double  operators  here  (such  as  ->)  */ 

137 

eval  expf&value);  /*  process  the  expression  */ 

26 

enum  double  ops  (LT=1,  LE,  GT,  GE,  EQ,  NE); 

138 

if  (‘token !=';' )  sntx  err (SEMI  EXPECTED); 

27 

/*  These  are  the  constants  used  to  call  sntx  err()  when 

139 

) 

28 

a  syntax  error  occurs.  Add  more  if  you  like. 

140 

else  if  (token  type==BLOCK)  (  /*  if  block  delimiter  */ 

29 

NOTE:  SYNTAX  is  a  generic  error  message  used  when 

141 

if (*token==' ( ' )  /*  is  a  block  */ 

30 

nothing  else  seems  appropriate. 

142 

block  =  1;  /*  interpreting  block,  not  statement  */ 

31 

*/ 

143 

else  return;  /*  is  a  ),  so  return  */ 

32 

enum  error  msg 

144 

) 

33 

(SYNTAX,  UNBAL  PARENS,  NO  EXP,  EQUALS  EXPECTED, 

145 

else  /*  is  keyword  */ 

34 

NOT  VAR,  PARAM  ERR,  SEMI  EXPECTED, 

146 

switch(tok)  { 

35 

UNBAL  BRACES,  FUNC  UNDEF,  TYPE  EXPECTED, 

147 

case  CHAR: 

36 

NEST  FUNC,  RET  NOCALL,  PAREN  EXPECTED, 

148 

case  INT:  /*  declare  local  variables  */ 

37 

WHILE  EXPECTED,  QUOTE  EXPECTED,  NOT  TEMP, 

149 

putback ( ) ; 

38 

TOO  MANY  LVARS); 

150 

decl  local  (); 

39 

char  *prog;  /*  current  location  in  source  code  ‘/ 

151 

break; 

40 

char  *p  buf;  /*  points  to  start  of  program  buffer  */ 

152 

case  RETURN:  /*  return  from  function  call  */ 

41 

jmp  buf  e  buf;  /*  hold  environment  for  longjmpO  */ 

153 

func  ret(); 

42 

154 

return; 

43 

/*  An  array  of  these  structures  will  hold  the  info 

155 

case  IF:  /*  process  an  if  statement  */ 

44 

associated  with  global  variables. 

156 

exec  if  () ; 

45 

*/ 

157 

break; 

46 

struct  var  type  { 

158 

case  ELSE:  /*  process  an  else  statement  */ 

47 

char  var  name[ID  LEN]; 

159 

find  eob();  /*  find  end  of  else  block 

48 

int  var  type; 

160 

and  continue  execution  */ 

49 

int  value; 

161 

break; 

50 

}  global  vars [NUM  GLOBAL  VARS]; 

162 

case  WHILE:  /*  process  a  while  loop  */ 

51 

struct  var  type  local  var  stack[NUM  LOCAL  VARS]; 

163 

exec  while  () ; 

52 

struct  func  type  ( 

164 

break; 

53 

char  func  name (ID  LEN]; 

165 

case  DO:  /*  process  a  do-while  loop  */ 

54 

char  *loc;  /*  location  of  entry  point  in  file  */ 

166 

exec  do  ()  ; 

55 

)  func  table [NUM  FUNC]; 

167 

break; 

56 

int  call  stack [NUM  FUNC]; 

168 

case  FOR:  exec  for(); 

57 

struct  commands  {  7*  keyword  lookup  table  */ 

169 

break; 

58 

char  command [ 20 ] ; 

case  END: 

59 

char  tok; 

171 

exit (0) ; 

60 

}  tablet]  =  (  /*  Commands  must  be  entered  lowercase  */ 

172 

) 

61 

"if",  IF,  /*  in  this  table.  */ 

173 

}  while  (tok  !=  FINISHED  &&  block); 

62 

"else",  ELSE, 

174 

) 

63 

"for",  FOR, 

175 

/*  Load  a  program.  */ 

64 

"do",  DO, 

176 

load  program (char  *p,  char  ‘fname) 

65 

"while",  WHILE, 

177 

( 

66 

"char",  CHAR, 

178 

FILE  *fp; 

67 

"int",  INT, 

179 

int  i=0; 

68 

"return",  RETURN, 

180 

if ( (fp=fopen (fname,  ”rb") ) ==NULL)  return  0; 

69 

"end",  END, 

181 

i  =  0; 

70 

"",  END  /*  mark  end  of  table  */ 

182 

do  ( 

72 

char  token [80]; 

73 

char  token  type,  tok; 

74 

int  functos;  /*  index  to  top  of  function  call  stack  */ 

75 

int  func_index;  /*  index  into  function  table  */ 
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Listing  Two  (Listing  continued,  text  begins  on  page  38.) 

183:  *p  =  getc (fp) ; 

184:  p++;  i++; 

185:  }  while ( !feof(fp)  &&  i<PROG_SIZE) ; 

186:  * (p— 2)  =  '\0';  /*  null  terminate  the  program  */ 

187:  fclose(fp); 

188:  return  1; 

189:  } 

190:  /*  Find  the  location  of  all  functions  in  the  program 
191:  and  store  global  variables.  */ 

192:  void  prescan (void) 

193:  { 

194:  char  *p; 

195:  char  temp [32]; 

196:  int  brace  =  0;  /*  When  0/  this  var  tells  us  that 

197:  current  source  position  is  outside 

198:  of  any  function.  */ 

199:  p  =  prog; 

200:  func_index  *  0; 

201:  do  { 

202:  while (brace)  {  /*  bypass  code  inside  functions  */ 

203:  get_token{); 

204:  if (*token==' ( ' )  brace++; 

205:  if (‘token—' ) ' )  brace — ; 

206:  ) 

207:  get_token(); 

208:  if  (tok— CHAR  ||  tok==INT)  {  /*  is  global  var  */ 

209:  putback(); 

210:  decl_global () ; 

211:  ) 

212:  else  if  (token_type— IDENTIFIER)  ( 

213:  strcpy(temp,  token); 

214:  get_token{); 

215:  if (*token==' (' )  {  /*  must  be  assume  a  function  */ 

216:  func_table[func_index] .loc  =  prog; 

217:  strcpy (func_table [func_index] .func_name,  temp); 

218:  func_index++; 

219:  while(*prog!=' ) ')  prog++; 

220:  prog++; 

221:  /*  prog  points  to  opening  curly  brace  of  function  */ 

222:  } 

223:  else  putbackO; 

224:  } 

225:  else  if  {‘token— '[' )  brace++; 

226:  )  while (tok! -FINISHED); 

227:  prog  =  p; 

228:  ) 

229:  /*  Return  the  entry  point  of  the  specified  function. 

230:  Return  NULL  if  not  found. 

231:  */ 

232:  char  *find_func (char  *name) 

233:  { 

234:  register  int  i; 

235:  for(i-0;  i<func_index;  i++) 

236:  if  (.’strcmp (name,  func table[i] .func name) ) 


237:  return  func_table[i] .loc; 

238:  return  NULL; 

239:  } 

240:  /*  Declare  a  global  variable.  */ 

241:  void  decl_global (void) 

242:  { 

243:  gettoken ( ) ;  /*  get  type  */ 

244:  global_vars [gvar_index] . var_type  =  tok; 

245:  global_vars [gvar_index] .value  =  0;  /*  init  to  0  */ 

246:  do  {  /*  process  comma-separated  list  */ 

247:  get_token();  /*  get  name  */ 

248:  strcpy (global_vars [gvar_index] ,var_name,  token); 

249:  get_token(); 

250:  gvar_index++; 

251:  )  while (*token==' , ') ; 

252:  if (‘token!-';')  sntx  err (SEMI  EXPECTED); 

253:  ) 

254:  /*  Declare  a  local  variable.  */ 

255:  void  decllocal (void) 

256:  { 

257:  struct  var_type  i; 

258:  get_token();  /*  get  type  */ 

259:  i.var_type  =  tok; 

260:  i. value  =  0;  /*  init  to  0  */ 

261:  do  {  /*  process  comma-separated  list  */ 

262:  get_token();  /*  get  var  name  */ 

263:  strcpy (i .var_name,  token); 

264:  local_push (i) ; 

265:  get_token(); 

266:  )  while (*token==' , ') ; 

267:  if (‘token!-' ;' )  sntxerr (SEMI  EXPECTED); 

268:  ) 

269:  /*  Call  a  function.  */ 

270:  void  call (void) 

271:  { 

272:  char  *loc,  *temp; 

273:  int  lvartemp; 

274:  loc  =  find_func (token) ;  /*  find  entry  point  of  function  */ 

275:  if  (loc— NULL) 

276:  sntx_err (FUNC_UNDEF) ;  /*  function  not  defined  */ 

277:  else  { 

278:  lvartemp  =  lvartos;  /*  save  local  var  stack  index  */ 

279:  get_args();  /*  get  function  arguments  */ 

280:  temp  =  prog;  /*  save  return  location  */ 

281:  func_push (lvartemp) ;  /*  save  local  var  stack  index  */ 

282:  prog  =  loc;  /*  reset  prog  to  start  of  function  */ 

283:  get_params () ;  /*  load  the  function's  parameters  with 

284:  the  values  of  the  arguments  */ 

285:  interp_block () ;  /*  interpret  the  function  */ 

286:  prog  =  temp;  /*  reset  the  program  pointer  */ 

287:  lvartos  =  func  pop();  /*  reset  the  local  var  stack  */ 

288:  } 

289:  ) 

290:  /*  Push  the  arguments  to  a  function  onto  the  local 
291:  variable  stack.  */ 

292:  void  get args (void) 


293:  { 

294:  int  value,  count,  temp [NUM_P ARAMS ] ; 

295:  struct  var_type  i; 

296:  count  -  0; 

297:  get_token(); 

298:  if (‘token!-' (')  sntx_err (PAREN_EXPECTED) ; 

299:  /*  process  a  comma-separated  list  of  values  */ 

300:  do  ( 

301:  eval_exp(4value) ; 

302:  temp [count]  =  value;  /*  save  temporarily  */ 

303:  get_token(); 

304:  count++; 

305:  Jwhile  (‘token—' ,') ; 

306:  count — ; 

307:  /*  now,  push  on  local_var_stack  in  reverse  order  */ 

308:  for(;  count>=0;  count  —  )  { 

309:  i. value  =  temp[count]; 

310:  i.var_type  =  ARG; 

311:  local_push (i) ; 

312:  } 

313:  ) 

314:  /*  Get  function  parameters.  */ 

315:  void  get_params (void) 

316:  { 

317:  struct  var_type  *p; 

318:  int  i; 

319:  i  =  lvartos-1; 

320:  do  {  /*  process  comma-separated  list  of  parameters  */ 

321:  get_token(); 

322:  p  =  Slocal_var_stack [i] ; 

323:  if (‘token!*')')  { 

324:  if (tok! -INT  &4  tok! -CHAR)  sntx_err (TYPE_EXPECTED) ; 

325:  p->var_type  -  token_type; 

326:  get_token {) ; 

327:  /*  link  parameter  name  with  argument  already  on 

328:  local  var  stack  */ 

329:  strcpy (p->var_name,  token); 

330:  get_token(); 

331:  i— 7 

332:  ) 

333:  else  break; 

334:  }  while  (‘token— ',') ; 

335:  if  (‘token!-' )' )  sntx_err (PAREN_EXPECTED) ; 

336:  ) 

337:  /*  Return  from  a  function.  */ 

338:  void  func_ret (void) 

339:  { 

340:  int  value; 

341:  value  =  0; 

342:  /*  get  return  value,  if  any  */ 

343:  eval_exp (tvalue) ; 

344:  ret_value  =  value; 

345:  } 

346:  /*  Push  local  variable  */ 

347:  void  local_push (struct  var_type  i) 

348:  ( 


349:  if (lvartos>NUM_LOCAL_VARS) 

350:  sntx_err (TOO_MANY_LVARS ) ; 

351:  local_var_stack [lvartos]  =  i; 

352:  lvartos++; 

353:  ) 

354:  /*  Pop  index  into  local  variable  stack.  */ 

355:  func  poo (void) 

356:  ( 

357:  functos — ; 

358:  if (functos<0)  sntx_err (RET_NOCALL) ; 

359:  return (call_stack [functos] ) ; 

360:  ) 

361:  /*  Push  index  of  local  variable  stack.  */ 

362:  void  func_push (int  i) 

363:  { 

364:  if  (functos>NUM_FUNC) 

365:  sntx_err (NEST_FUNC) ; 

366:  call_stack [functos]  =  i; 

367:  functos++; 

368:  ) 

369:  /*  Assign  a  value  to  a  variable.  */ 

370:  void  assignvar (char  *var_name,  int  value) 

371:  { 

372:  register  int  i; 

373:  /*  first,  see  if  it's  a  local  variable  */ 

374:  for (i-lvartos-1;  i>=call_stack [functos-1] ;  i — )  { 

375:  if ( ! strcmp (local_var_stack [i] .var_name,  var_name))  { 

376:  local_var_stack [i] .value  =  value; 

377:  return; 

378:  ) 

379:  ) 

380:  if (i  <  call_stack [functos-1] ) 

381:  /*  if  not  local,  try  global  var  table  */ 

382:  for (i=0;  i<NUM_GLOBAL_VARS ;  i++) 

383:  if (! strcmp (global_vars [i] .var_name,  var_name) )  ( 

384:  global_vars [i] .value  =  value; 

385:  return; 

386:  ) 

387:  sntx_err (NOT_VAR) ;  /*  variable  not  found  */ 

388:  } 

389:  /*  Find  the  value  of  a  variable.  */ 

390:  int  f ind_var (char  *s) 

391:  { 

392:  register  int  i; 

393:  /*  first,  see  if  it's  a  local  variable  */ 

394:  for (i=lvartos-l;  i>=call_stack [functos-1] ;  i — ) 

395:  if (! strcmp (local_var_stack (i) .var_name,  token)) 

396:  return  local_var_stack[i) .value ; 

397:  /*  otherwise,  try  global  vars  */ 

398:  for  (i=0;  i<NUM_GLOBAL_VARS;  i++) 

399:  if (! strcmp (global_vars [i] .var_name,  s)) 

400:  return  global_vars [i] .value; 

401:  sntx_err (NOT_VAR) ;  /*  variable  not  found  */ 

402:  ) 

(continued  on  page  120) 
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listing  Two  (Listing  continued,  text  begins  on  page  38.) 

455 

/‘Execute  a  do  loop.  */ 

456 

void  exec  do (void) 

403 

/*  Determine  if  an  identifier  is  a  variable.  Return 

457 

{ 

404 

1  if  variable  is  found;  0  otherwise. 

458 

int  cond; 

405 

*/ 

459 

char  *temp; 

406 

int  is  varfchar  *s) 

460 

putback ( ) ; 

407 

1 

461 

temp  =  prog;  /*  save  location  of  top  of  do  loop  */ 

408 

register  int  i; 

462 

get  token ();  /*  get  start  of  loop  */ 

409 

/*  first,  see  if  it's  a  local  variable  */ 

463 

interp  block();  /*  interpret  loop  */ 

410 

for (i=lvartos-l;  i>=call  stack [functos-1] ;  i — ) 

464 

get  token ( ) ; 

411 

if  (! strcmp (local  var  stack (i].var  name,  token)) 

465 

if (tok ! =WHILE)  sntx  err (WHILE  EXPECTED); 

412 

return  1; 

466 

eval  exp(icond);  /*  check  the  loop  condition  */ 

413 

/*  otherwise,  try  global  vars  */ 

467 

if (cond)  prog  =  temp;  /*  if  true  loop;  otherwise, 

414 

for (i=0;  i<NUM  GLOBAL  VARS;  i++) 

468 

continue  on  */ 

415 

if (! strcmp (global  vars [i). var  name,  s)) 

469 

1 

416 

return  1; 

470 

/*  Find  the  end  of  a  block.  */ 

417 

return  0; 

471 

void  find  eob(void) 

418 

1 

472 

f 

419 

/*  Execute  an  IF  statement.  */ 

473 

int  brace; 

420 

void  exec  if (void) 

474 

get  token (); 

421 

1 

475 

brace  =  1; 

422 

int  cond; 

476 

do  1 

423 

eval  exp(Scond);  /*  get  left  expression  */ 

477 

get  token ( ) ; 

424 

if (cond)  {  /*  is  true  so  process  target  of  IF  */ 

478 

if (*token==' ( ' )  brace++; 

425 

interp  block () ; 

•179 

else  if  (‘token—' )' )  brace--; 

426 

) 

•180 

)  while (brace) ; 

427 

else  i  /*  otherwise  skip  around  IF  block  and 

•181 

I 

428 

process  the  ELSE,  if  present  */ 

■182 

/*  Execute  a  while  loop.  */ 

429 

find  eob();  /*  find  start  of  next  line  */ 

•183 

void  exec  for(void) 

430 

get  token  { ) ; 

484 

( 

431 

if (tok ! =ELSE)  ( 

485 

int  cond; 

432 

putbackO;  /*  restore  token  if 

486 

char  ‘temp,  *temp2; 

433 

no  ELSE  is  present  */ 

487 

int  brace  ; 

434 

return; 

488 

get  token (); 

435 

) 

489 

eval  exp(icond);  /‘initialization  expression  */ 

436 

interp  block (); 

490 

if (‘token!-';')  sntx  err (SEMI  EXPECTED); 

437 

1 

1  91 

prog++;  /*  get  past  the  ;  */ 

438 

1 

4  92 

temp  =  prog; 

439 

/*  Execute  a  while  loop.  */ 

493 

for {; ; )  { 

440 

void  exec  while (void) 

494 

eval  exp(scond);  /*  check  the  condition  */ 

441 

I 

495 

if (‘token!-';')  sntx  err (SEMI  EXPECTED); 

442 

int  cond; 

496 

prog++;  /*  get  past  the  ;  */ 

443 

char  ‘temp; 

497 

temp2  =  prog; 

444 

put back () ; 

498 

/*  find  the  start  of  the  for  block  */ 

445 

temp  =  prog;  /*  save  location  of  top  of  while  loop  */ 

499 

brace  =  1; 

446 

get  token (); 

500 

while  (brace)  ( 

447 

eval  exp(Scond);  /*  check  the  conditional  expression  */ 

501 

get  token (); 

448 

if (cond)  interp  block ();  /*  if  true,  interpret  */ 

502 

if  (*token==' (' )  brace+  +  ; 

449 

else  {  /*  otherwise,  skip  around  loop  */ 

503 

if  (*token==' ) ' )  brace — ; 

450 

find  eob() ; 

504 

I 

451 

return; 

505 

if (cond)  interp  block ();  /*  if  true,  interpret  */ 

452 

1 

506 

else  (  /*  otherwise,  skip  around  loop  */ 

453 

prog  =  temp;  /*  loop  back  to  top  »/ 

507 

find  eob() ; 

454 

) 

508 

return; 

509 

) 

510 

prog  =  temp2; 

511 

eval  expl&cond);  /*  do  the  increment  */ 

512 

prog  =  temp;  /*  loop  back  to  top  */ 

513 

) 

514 

} 

End  Listing  Two 

Listing  Three 

1: 

/“““  Internal  Library  Functions  *******/ 

3: 

/*  Add  more  of  your  own,  here.  */ 

5: 

linclude  "conio.h"  /*  if  your  compiler  does  not 

6: 

support  this  header  file, 

7; 

remove  it  */ 

8: 

♦include  "stdio.h" 

9: 

♦include  "stdlib.h" 

10: 

11: 

extern  char  ’prog;  /*  points  to  current  location  in  program  */ 

12: 

extern  char  token [80);  /*  holds  string  representation  of  token  */ 

13: 

extern  char  token  type;  /*  contains  type  of  token  */ 

14: 

extern  char  tok;  /*  holds  the  internal  representation  of  token  */ 

15: 

16: 

enum  tok  types  (DELIMITER,  IDENTIFIER,  NUMBER,  COMMAND,  STRING, 

17; 

QUOTE,  VARIABLE,  BLOCK,  FUNCTION); 

18: 

/*  These  are  the  constants  used  to  call  sntx  err()  when 

19: 

a  syntax  error  occurs.  Add  more  if  you  like. 

20: 

NOTE:  SYNTAX  is  a  generic  error  message  used  when 

21: 

nothing  else  seems  appropriate. 

22: 

*/ 

23: 

enum  error  msg 

24: 

(SYNTAX,  UNBAL  PARENS,  NO  EXP,  EQUALS  EXPECTED, 

25: 

NOT  VAR,  PARAM  ERR,  SEMI  EXPECTED, 

26: 

UNBAL  BRACES,  FUNC  UNDEF,  TYPE  EXPECTED, 

27; 

NEST  FUNC,  RET  NOCALL,  FAREN  EXPECTED, 

28: 

WHILE  EXPECTED,  QUOTE  EXPECTED,  NOT  STRING, 

29: 

TOO  MANY  LVARS ) ; 

30: 

int  get  token (void) ; 

31: 

void  sntx  err  (int  error),  eval  exp (int  ‘result); 

32: 

void  putback (void) ; 

33: 

/*  Get  a  character  from  console.  (Use  getcharO)  if 

34: 

your  compiler  does  not  support  getcheO.)  */ 

35: 

calx  getcheO 

36: 

I 

37: 

char  ch; 

38: 

ch  =  getche () ; 

39: 

while (*prog!=' )' )  prog++; 

40: 

prog++;  /*  advance  to  end  of  line  */ 

41: 

return  ch; 
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42:  } 

43:  /*  Put  a  character  to  the  display.  (Use  putchar() 
44:  if  your  compiler  does  not  support  putch().)  */ 

45:  call_putch() 

46:  { 

47:  int  value; 

48:  eval_exp(&value)  ; 

49:  putch (value) ; 

50:  return  value; 

51:  } 

52 :  /*  Call  puts () .  */ 

53:  call_puts (void) 

54:  ( 

55:  get_token(); 

56:  if (‘token!-' {')  sntx_err (PAREN_EXPECTED) ; 

57:  get_token(); 

58:  if (token_type! =QUOTE)  sntx_err (QOOTE_EXPECTED) ; 

59:  puts (token); 

60:  get_token(); 

61:  if {‘token!-' )' )  sntx_err (PAREN_EXPECTED) ; 

62:  get_token(); 

63:  if (‘token!-' ;')  sntx_err (SEMI_EXPECTED) ; 

64:  putbackO; 

65:  return  0; 

66:  ) 

67:  /*  A  built-in  console  output  function.  */ 

68:  int  print (void) 

69:  ( 

70:  int  i; 

71:  get_token(); 

72:  if (‘token!-' (' )  sntx_err (PAREN_EXPECTED) ; 

73:  get_token(); 

74:  if (token_type==QUOTE)  {  /*  output  a  string  */ 

75:  printf("%s  ",  token); 

76:  ) 

77:  else  (  /*  output  a  number  */ 

78:  putbackO; 

79:  eval_exp(Si) ; 

80:  print f("%d  ",  i); 

81:  } 

82:  get_token{); 

83:  if (‘token!-' )' )  sntx_err (PAREN_EXPECTED) ; 

84:  get_token(); 

85:  if (‘token!-' ;' )  sntx_err (SEMI_EXPECTED) ; 

86:  putbackO; 

87:  return  0; 

88:  } 

89:  /*  Read  an  integer  from  the  keyboard.  */ 

90:  getnum(void) 

91:  { 

92:  char  s [ 8 0 ] ; 

93:  gets(s); 

94:  while (‘prog!-' )' )  prog++; 

95:  prog++;  /*  advance  to  end  of  line  */ 

96:  return  atoi(s); 

97:  ) 


End  Listing  Three 


Listing  Four 

1:  /*  C  Interpreter  Demonstration  Program 
2:  This  program  demonstrates  all  features 

3:  of  C  that  are  recognized  by  this  C  interpreter. 

4:  */ 

5:  int  i,  j;  /*  global  vars  */ 

6:  char  ch; 

7: 

8:  main() 

9:  ( 

10:  int  i,  j;  /*  local  vars  */ 

11:  puts("C  Demo  Program."); 

12:  print_alpha () ; 

13:  do  ( 

14:  puts ("enter  a  number  (0  to  quit):  "); 

15:  i  =  getnumO  ; 

16:  if (i  <0)| 

17:  puts ("numbers  must  be  positive,  try  again"); 

18:  ) 

19:  else  { 

20:  for(j  =0;  j  <  i;  j=j+l)  ( 

21:  print (j); 

22:  print ("summed  is"); 

23:  print (sum(j) ) ; 

24:  puts(""); 

25:  } 

26:  ) 

27:  }  while (i !=0) ; 

28:  ( 

29:  /*  Sum  the  values  between  0  and  num.  */ 

30:  sum(int  num) 

31:  | 

32 :  int  running_sum; 

33:  running_sum  =  0; 

34:  while (num)  { 

35:  running_sum  =  running_sum  +  num; 

36:  num  =  num  -  1; 

37:  ) 

38:  return  running_sum; 

39:  } 

40:  /*  Print  the  alphabet.  */ 

41:  print_alpha () 

42:  ( 

43:  for(ch  =  'A';  ch<='Z';  ch  =  ch  +  1)  { 

44:  putch (ch); 

45:  ) 

46:  puts(""); 

47:  ) 


48:  /*  Nested  loop  example.  */ 

49:  main() 

50:  ( 

51:  int  i,  j,  k; 

52:  for (i  =  0;  i  <  5;  i  =  i  +  1)  { 

53:  for(j  =  0;  j  <  3;  j  =  j  +  1)  { 

54:  for (k  =  3;  k  ;  k  =  k  -  1)  ( 

55:  print (i); 

56:  print ( j) ; 

57:  print (k); 

58:  puts ("") ; 

59:  } 

60:  ) 

61:  ) 

62:  puts ("done") ; 

63:  ) 

64:  /*  Assigments  as  operations.  */ 

65:  main() 

66:  ( 

67:  int  a,  b; 

68:  a  =  b  =  10; 

69:  print (a);  print (b) ; 

70:  while(a-a-l)  { 

71:  print  (a); 

72:  do  { 

73:  print (b); 

74:  )while((b=b-l)  >  -10); 

75:  ) 

76:  ) 

77:  /*  This  program  demonstrates  recursive  functions.  */ 
78:  main() 

79:  { 

80:  print (factr (7)  *  2); 

81:  ) 

82:  /*  return  the  factorial  of  i  */ 

83:  factr(int  i) 

84:  { 

85:  if (i<2)  { 

86:  return  1; 

87:  ) 

88:  else  ( 

89:  return  i  *  factr  (i-1); 

90:  ) 

91:  ) 

92:  /‘A  more  rigorous  example  of  function  arguments.  */ 
93:  main() 

94:  { 

95:  f  2  (10,  fl  (10,  20),  99); 

96:  } 

97 :  f 1 (int  a,  int  b) 

98:  ( 

99:  int  count; 

100:  print ("in  fl"); 

101:  count  =  a; 

102:  do  ( 

103:  print (count) ; 

104:  )  while (count-count-1) ; 

105:  print (a);  print (b) ; 

106:  print (a*b); 

107:  return  a*b; 

108:  ) 

109:  f2(int  a,  int  x,  int  y) 

110:  ( 

111:  print (a);  print (x); 

112 :  print (x  /  a) ; 

113:  print (y*x); 

114:  ) 

115:  /*  The  loop  statements.  */ 

116:  main() 

117:  { 

118:  int  a; 

119:  char  ch; 

120:  /*  the  while  */ 

121:  puts ("Enter  a  number:  "); 

122 :  a  =  getnumO  ; 

123:  while(a)  { 

124:  print  (a); 

125:  print (a*a); 

126:  puts(""); 

127:  a  =  a  -  1; 

128:  ) 

129:  /*  the  do-while  */ 

130:  puts ("enter  characters,  'q'  to  quit"); 

131:  do  ( 

132 :  ch  =  getche  () ; 

133:  )  while (ch !=' q' ) ; 

134:  /*  the  for  */ 

135:  for(a=0;  a<l0;  a  =  a  +  1)  ( 

136:  print  (a) ; 

137:  } 

138:  ) 


End  Listings 
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Listing  One  (Text  begins  on  page  50  J 


Listing  Three 


♦include  <stdio.h> 

♦include  <malloc.h> 

char  **dim2(row,  col,  size) 
int  row,  col; 
unsigned  size; 

{ 

int  i; 

char  **prow,  *pdata; 

pdata  =  (char  *)  calloc(row  * 
if  (pdata  ==  (char  *)  NULL)  { 
fprintf (stderr, 
exit  (1) ; 

I 

prow  =  (char 
if  (prow  (char 
fprintf (stderr, 
exit  (1) ; 

} 

for  (i  =  0;  i  <  row;  i++)  ( 
prow[i]  =  pdata; 
pdata  +=  size  *  col; 

) 

return  prow; 


void  free2(pa) 
char  **pa; 

( 

free (*pa) ; 
free (pa) ; 


/*  creates  2D  array 


col,  size) ; 


/*  store  pointers  to  rows  */ 

/*  move  to  next  row  */ 

/*  pointer  to  2D  array  */ 

/*  frees  2D  heap  storage  */ 

/*  free  the  data  */ 

/*  free  pointer  to  row  pointers 


'No  heap  space  for  data\n")  ; 


)  malloc(row  *  sizeof  (char  *)); 

*)  NULL)  ( 

"No  heap  space  for  row  pointers\n") ; 


End  listing  One 


Listing  Two 

♦include  <stdio.h> 

♦include  <malloc.h> 

char  ***dim3(grid,  row,  col,  size)  /*  creates  3D  array  */ 

int  grid,  row,  col; 
unsigned  size; 

{ 

int  i; 

char  *  “pgrid,  “prow,  *pdata; 

pdata  =  (char  *)  calloc(grid  *  row  *  col,  size); 

if  (pdata  ==  (char  *)  NULL)  ( 

fprintf (stderr,  "No  heap  space  for  data\n"); 
exit  (1) ; 

} 

prow  =  (char  “)  malloc(grid  *  row  *  sizeof  (char  *)); 

if  (prow  ==  (char  “)  NULL)  ( 

fprintf (stderr,  "No  heap  space  for  row  pointers\n") ; 
exit  (1) ; 

) 

pgrid  =  (char  *“)  malloc(grid  *  sizeof  (char  “)); 

if  (pgrid  ==  (char  *“)  NULL)  ( 

fprintf (stderr,  "No  heap  space  for  grid  pointers\n") ; 
exit  (1) ; 

) 


for  (i  =  0;  i  <  grid  *  row;  i++; 
prow[i]  =  pdata; 
pdata  +=  col  *  size; 


for  (i  =0;  i  <  grid;  i++)  { 
pgrid [i]  =  prow; 
prow  +=  row; 

) 

return  pgrid; 


void  free3(pa) 
char  “*pa; 

( 

free (**pa) ;  /* 

free (*pa) ;  /* 

free (pa);  /* 


{ 

/*  store  pointers  to  rows  */ 
/*  move  to  next  row  */ 


/*  store  pointers  to  grid  */ 
/*  move  to  next  grid  */ 

/*  pointer  to  3D  array  */ 


/*  frees  3D  heap  storage  */ 


free  the  data  */ 

free  the  row  pointers  */ 

free  the  grid  pointers  */ 


/*  det.c  -  find  determinant  of  a  two-dimensional  array  of  doubles  */ 


♦include  <stdio.h> 
♦include  <malloc.h> 
main () 


double  det ( ) ; 


static  double  f[4][4)  =  ( 

1,  3,  2,  1, 

4,  6,  1,  2, 

2,  1,  2,  3, 

1,  2,  4,  1 


static  double  g [ 5 ]  (5]  =  ( 

1,  3,  2,  1,  7, 

4,  6,  1,  2,  6, 

2,  1,  2,  3,  5, 

1,  2,  4,  1,  4, 

8,  5,  4,  1,  3 


printf  ("determinant  of  f  =  %g\n",  det(f,  4)); 
printf  ("determinant  of  g  =  %g\n",  det (g,  5)); 


double  det(arg,  n)  /*  calculate  determinant  for  n  by  n  matrix  */ 

char  *arg; 
int  n; 


register  int  i,  j,  k; 
double  **a;  /* 

char  **sdim2(); 
double  ret;  /* 

double  x;  /* 


this  is  the  array  name  */ 

determinant  */ 
temp  */ 


/*  dynamically  create  2  dimensional  "array"  a  from  arg  */ 
a  =  (double  **)  sdim2(arg,  n,  n,  sizeof (double)); 


/*  determinant  algorithm  using  rows  and  columns  */ 
for  (k  =  0;  k  <  n  -  1;  k++) 

for  (i  =  k  +  1;  i  <  n;  i++) ( 
x  =  a [ i ] [k]/a[k] (kj; 
for  (j  =  k;  j  <  n;  j++) 

a  [  i  J  [  j]  =  a  [  i  ]  ( j]  -  x  *  a  [k]  [j]  ; 

) 


for  (ret  =  1,  i  =  0;  i  <  n;  i++) 
ret  *=  a [i J  [i] ; 

free (a);  /*  free  heap  storage  */ 

return  ret; 


char  **sdim2 (pdata,  row,  col,  size)  /*  "creates"  2D  array  */ 

char  *pdata; 
int  row,  col; 
unsigned  size; 

{ 

int  i; 

register  char  “prow; 

prow  =  (char  **)  malloc(row  *  sizeof  (char  *)); 

if  (prow  ==  (char  **)  NULL)  { 

fprintf (stderr,  "No  heap  space  for  row  pointers\n") ; 
exit  (1); 

) 


for  (i  =0;  i  <  row;  i++) 
prow(i]  =  pdata; 
pdata  +=  size  *  col; 

1 

return  prow; 


/*  store  pointers  to  rows  */ 
/*  move  to  next  row  */ 

/*  pointer  to  2D  array  */ 


End  Listing  Two 


End  Listings 
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listing  One  (Text  begins  on  page  62.) 

1:  /* - 

107 

bp->alloc [bno] . size  =  b; 

2:  xmem.c  —  Extended  Dynamic  Memory  Control  Module. 

108 

3:  - - - */ 

109 

/*  update  total  allocation  */ 

4.  /*  **********************  INCLUDE  files  **********************  */ 

110 

tot  memory  +=  b; 

5:  #include  <stdio.h> 

11] 

6: 

112 

/*  increment  total  number  of  allocations  */ 

7.  /*  ********************  EXTERNAL  functions  *******************  */ 

113 

++tot  alloc; 

8:  extern  char  *malloc (unsigned  int); 

114 

9:  extern  char  *calloc (unsigned  int,  unsigned  int); 

115 

return (p) ; 

10:  extern  void  free (char  *); 

116 

) 

11: 

117 

12 :  /*  *********************  GLOBAL  FUNCTIONS  ********************  */ 

118 

/*  - 

13:  char  *x  malloc (unsigned  int); 

119 

Delete  pointer  from  hash  table 

14:  char  *x  calloc (unsigned  int,  unsigned  int); 

120 

*/ 

15:  void  x  free  (char  *); 

121 

static  void  del  ptr(p) 

16:  void  x  chkfreeO; 

122 

char  *p;  /*  pointer  to  be  freed  »/ 

17: 

123 

{ 

18:  /*  *********************  GLOBAL  VARIABLES  ********************  */ 

124 

int  gap;  /*  index  into  overhead  space  */ 

19:  /*  memtrace  usage: 

125 

register  BUCKET  *bp,  *bq;  /*  bucket  pointers  */ 

20:  *  0  =>  simple  calls  to  malloc  &  free 

126 

register  int  bno,  i;  /*  bucket/entry  number  */ 

21:  =  1  =>  tracking  of  all  allocations  using  hash  table 

127 

22:  =  2  =>  checking  for  changes  to  previously  freed  blocks 

128 

/*  compute  hash  table  index  */ 

23:  */ 

129 

bno  =  (int) ( (unsigned  long)p  %  hashsize); 

24:  int  memtrace  ■  1;  /*  memory  tracing  control  variable  */ 

130 

25:  long  tot  memory  =  0L;  /*  total  amount  of  allocated  memory  */ 

131 

/*  search  bucket (s)  for  pointer  */ 

26:  long  tot  alloc  =  OL;  /*  total  #  of  allocations  */ 

132 

for  (bq  =  NUL  BUCKET,  bp  =  ptrhash [bno] ;  bp;  bp  =  bp->next)  ( 

27:  int  hashsize  =  47;  /*  size  of  hash  table  */ 

133 

for  {  i  =  0;  i  <  bp->entries;  ++i  )  { 

28:  int  bucketsize  =  10;  /*  number  of  entries  per  hash  bucket  */ 

134 

if  (  bp->alloc[i] .ptr  ==  p  )  ( 

29: 

135 

/*  check  integrity  of  gap  */ 

30;  /*  *********************  local  VARIABLES  *********************  */ 

136 

for  (gap=bp->alloc[i] . size-OVHDSIZE; 

31:  /*  memory  allocation  tracking  table  */ 

137 

gap<bp->ailoc(i] .size;  ++gap  )  ( 

32: 

138 

if  (  p [gap]  ! =  FILLCHAR  )  ( 

33:  /*  amount  of  extra  allocation  for  overhead  */ 

139 

printf ("WARNING  overwrite,  addr:  %lx\n", 

34:  Idefine  OVHDSIZE  2 

140 

(long) p) ; 

35: 

141 

break; 

36:  /*  fill  character  for  overhead  gap  */ 

142 

1 

37:  Idefine  FILLCHAR  '\377' 

143 

) 

38: 

144 

if  (  memtrace  ==  1  )  ( 

39:  /*  allocated  entry  information  */ 

145 

/*  remove  entry  from  bucket  */ 

40:  typedef  struct  alloc  entry  ( 

146 

if  (  — bp->entries  ==  0  )  ( 

41:  int  size;  /*  size  of  allocated  area  */ 

147 

/*  free  this  bucket  *  ' 

42:  char  *ptr;  /*  pointer  to  allocated  area  */ 

148 

if  (  bq  ) 

43:  char  ‘freed;  /*  pointer  to  copy  of  allocated  area  */ 

149 

bq->next  =  bp->next; 

44:  )  ALLOCATION; 

150 

else 

45: 

151 

ptrhash [bno]  =  bp->next; 

46:  typedef  struct  bucket  ( 

152 

free ((char  *) bp->alloc) ; 

47:  struct  bucket  ‘next;  /*  pointer  to  next  bucket  when  filled  */ 

153 

free ((char  * ) bp ) ; 

48:  int  entries;  /*  number  of  used  entries  */ 

154 

tot  memory  —  (sizeof (BUCKET)  + 

49:  ALLOCATION  ‘alloc;  /*  allocated  entry  array  */ 

155 

bucket size*sizeof (ALLOCATION) ) ; 

50:  )  BUCKET; 

156 

) 

51: 

157 

else  if  (  i  <  bp->entries  )  ( 

52:  Idefine  NUL  BUCKET  ((BUCKET  *)0) 

158 

/*  move  last  entry  into  current  spot  */ 

53: 

159 

bp->alloc[i]  =  bp->alloc [bp->entries] ; 

54:  /*  dynamic  pointer  hash  table  */ 

160 

1 

55:  static  BUCKET  “ptrhash  =  (BUCKET  “)0; 

161 

free (p) ; 

56: 

162 

) 

58:  Store  pointer  in  hash  table 

164 

/*  memtrace  ==  2 

59:  */ 

165 

=>  save  copy  to  check  for  bad  mods  */ 

60:  static  char  *sto_ptr(p,  b) 

166 

if  (  bp->alloc [i] . freed  ) 

61:  char  *p;  /*  pointer  to  be  stored  */ 

167 

printf ("WARNING  freeing  free  ptr,  addr:  %lx\n", 

62:  unsigned  b;  /*  size  of  area  */ 

168 

(long) p) ; 

63:  ( 

169 

else  if  (bp->alloc[i] .freed  =  malloc (bp->alloc[i] .size) ) 

64:  register  BUCKET  *bp,  *bq;  /*  bucket  pointers  ‘/ 

170 

memcpy(bp->alloc[i] .freed,  bp->alloc[i] .ptr, 

65:  register  int  bno;  /*  bucket/entry  number  */ 

171 

bp->alloc[i] .size) ; 

66: 

172 

67:  if  (  !  ptrhash  )  ( 

173 

) 

68:  /*  allocate  pointer  hash  table  */ 

174 

/*  update  total  allocated  memory  count  */ 

69:  ptrhash  =  (BUCKET  “) calloc (hashsize,  sizeof (BUCKET  ‘)); 

175 

tot  memory  -=  bp->alloc[i] .size; 

70:  if  (  !  ptrhash  ) 

176 

71:  return (NULL) ; 

177 

/*  normal  return  */ 

72:  tot  memory  =  hashsize  *  sizeof (BUCKET  *); 

178 

return; 

73:  ) 

179 

) 

74:  /*  compute  hash  table  index  */ 

180 

) 

75:  bno  =  (int) ( (unsigned  long)p  %  hashsize); 

181 

bq  =  bp; 

76: 

182 

) 

77:  /*  find  first  bucket  with  available  entries  */ 

183 

if  (  !  bp  ) 

78:  for  (bq  =  bp  =  ptrhash [bno] ;  bp  &&  bp->entries  ==  bucketsize; 

184 

printf ("WARNING  freeing  bad  pointer,  addr:  %lx\n",  (long)p); 

79:  bp  =  bp->next) 

185 

) 

80:  bq  =  bp; 

186 

r 

82:  /*  allocate  new  bucket  if  necessary  */ 

188 

Allocate  b  bytes  of  memory 

83:  if  (  bp  ==  NUL  BUCKET  )  { 

189 

*/ 

84:  if  (  !  (bp  =  (BUCKET  *)malloc (sizeof (BUCKET) ) )  ) 

190 

char  *x  malloc (  b  ) 

85:  return (NULL); 

191 

unsigned  int  b;  /*  number  of  bytes  to  allocate  */ 

86:  bp->next  =  NUL  BUCKET; 

192 

( 

87:  bp->entries  =  0; 

193 

register  char  ‘rnptr; 

88:  if  (  bq  ) 

194 

89:  /*  connect  to  end  of  bucket  chain  */ 

195 

if  (  memtrace  )  ( 

90:  bq->next  =  bp; 

196 

/*  add  gap  space  */ 

91:  else 

197 

b  +=  OVHDSIZE; 

92:  /*  initial  bucket  for  this  hash  entry  */ 

198 

93:  ptrhash [bno]  =  bp; 

199 

/*  allocate  memory  */ 

94: 

200 

if  (  rnptr  =  malloc (b)  )  ( 

95:  /*  allocate  bucket's  allocation  entry  array  */ 

201 

/*  fill  gap  */ 

96:  bp->alloc  =  (ALLOCATION  *) calloc (bucketsize, 

202 

memset (mptr+b-OVHDSIZE,  FILLCHAR,  OVHDSIZE); 

97 :  sizeof (ALLOCATION) ) ; 

98: 

/*  store  rnptr  in  ptrhash  */ 

99:  /*  memory  total  includes  space  used  by  hash  table  */ 

205 

rnptr  =  sto  ptr (rnptr,  b) ; 

100:  tot  memory  +■=  sizeof  (BUCKET)  + 

101 :  bucketsize*sizeof (ALLOCATION) ; 

208 

else. 

103:  /*  store  pointer  to  allocated  block  */ 

209 

rnptr  =  malloc (b); 

104:  bno  =  bp->entries++; 

105:  bp->alloc [bno] .ptr  =  p; 

return (rnptr) ; 

106:  bp->alloc [bno] .freed  =  NULL; 

214 

/* - = - 
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215 

216 

217 

218 

219 

220 
221 
222 

223 

224 

225 

226 

227 

228 

229 

230 

231 

232 

233 

234 

235 

236 

237 

238 

239 

240 

241 

242 

243 

244 

245 

246 

247 

248 
249: 
250: 
251: 
252: 

253 

254 

255 

256 

257 

258 

259 

260 
261 
262 

263 

264 

265 


Allocate  and  clear  i*s  bytes  of  memory 
V 

char  *x_calloc(  i,  s  ) 

unsigned  int  i;  /*  number  of  blocks  to  be  allocated  */ 
unsigned  int  s;  /*  size  (in  bytes)  of  each  block  */ 

[ 

register  unsigned  int  amt; 
register  char  *mptr; 

/*  allocate  requested  space  */ 
if  (  mptr  =  x_malloc(amt  =  i*s)  )  { 

/*  clear  requested  space  */ 
memset(mptr,  '\0',  amt); 

} 

return  (mptr) ; 

) 

/  *  - — — - ===== - - - ======== 

Free  allocated  memory 

*/ 

void  x_free(  p  ) 

char  *p;  /*  pointer  to  block  to  be  freed  */ 

I 

if  (  p  ==  NULL  ) 

printf ("WARNING  freed  a  null  pointer\n") ; 
else  if  (  memtrace  ) 
del_ptr (p) ; 
else 

free ((char  *)p); 

} 

/  * - ===== - - = - - - - - - - - ======== 

Check  to  ensure  all  blocks  have  been  freed 

*/ 

void  x_chkfree() 

{ 

ALLOCATION  *ap;  /*  allocation  entry  pointer  */ 

register  int  bno,  i;  /*  bucket/entry  number  */ 

register  BUCKET  *bp,  *bq;  /*  bucket  pointers  */ 

if  (  memtrace  )  { 

/*  check  for  unfreed  variables  */ 
for  (  bno  *  0;  bno  <  hashsize;  ++bno  )  ( 
for  (  bp  =  ptrhash(bno) ;  bp;  bp  =  bq  )  { 
for  (i  -  0;  i  <  bp->entries;  ++i)  ( 
ap  =  &bp->alloc[i] ; 
if  (  memtrace  ==  2  &&  ap->freed  )  { 

/*  check  for  changes  to  freed  blocks  */ 
if  (  memcmp (ap->ptr,  ap->freed,  ap->size)  ) 

printf ("WARNING  block  chgd  after  free,  addr:  %l\n", 
(long) ap->ptr) ; 
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267 

268 

269 

270 

271 

272 

273 

274 

275 

276 

277 

278 

279 

280 
281: 
282 

283 

284 

285 


} 

/*  free  unfreed  block  */ 

printf ("WARNING  freeing  unfreed  block,  addr:  %lx\n", 
(long)ap->ptr) ; 
free (ap->ptr) ; 

) 

bq  =  bp->next; 

/*  free  bucket  */ 
free ((char  *) bp->alloc) ; 
free ( (char  *)bp) ; 


/*  free  pointer  hash  pointer  array  */ 
free  ((char  Mptrhash); 
ptrhash  =  (BUCKET  **)0; 

tot_memory  =  0L; 


End  Listing 


Listing  One  ( Text  begins  on  page  68.) 

/ ********* ***********  *******************************  ********************* 
Name  :  prompter. c 

Description  :  A  routine  for  prompting  a  user  for  a  series  of  answers. 

#include<stdio.h> 

# include "prompter . h" 

struct  group_stack  group_stack [GROUP_STACK_SIZE] ; 


prompter (pc) 

struct  prcontrol  *  pc; 


int  errstat; 


pc->current_question  =  0; 
pc->group_stack_ptr  =  0; 

for ( ; ; ) { 

pc->errstat  =  0; 


display_current_question (pc)  ; 

gets (pc->response) ; 

if (*pc->response  ==  0) ( 
continue; 

) 


if  (! (pc->errstat  - 

(*pc->current_group [pc->current_question] .validate) (pc) ) ) ( 
if (pc->errstat  = 

(*pc->current_group[pc->current_question] .doit) (pc)) ( 
if (pc->errstat  ==  EXIT_NOW) { 
return (0) ; 

} 

) 


if  (pc->current_group [pc->current_question] .response  !»  NULL) ( 
strcpy (pc->current_group[pc->current_question) .response, 
pc->response) ; 


(*pc->current_group[pc->current_question] .set) (pc) ; 

if (pc->current_group[pc->current_question] .text  ==  NULL) ( 
return (0) ; 

) 

if  (pc->errstat) ( 

handle_error (pc->errstat, pc->errormess)  ; 

) 


) 

display_current_question (pc) 
struct  prcontrol  *  pc; 

{ 

printf ("\n%s\n", pc->current_group[pc->current_question) .text) ; 
printf (" — >") ; 

) 

handleerror (errstat, errormess) 
int  errstat; 

struct  errormess  *  errormess; 

< 

int  i; 

int  emess_offset  =  -1; 

char  *  message, messagebuff [100) ; 

ford  =  0  ;  errormess  [i]  .errstat  !=  -1  ;  ++i)  ( 
if (errormess [ij .errstat  ==  errstat)! 
emess_offset  =  i; 
break; 


) 

message  =  messagebuff; 
if (emess_of fset  !=  -1) { 

strcpy (message, errormess [emess_of fset ] .message) ; 
if (errormess [emess_of fset] .build) { 

(*errormess [emess_offset] .build) (message); 

) 

) 

else! 

sprintf (message, "Error  %d. ", errstat) ; 

) 


puts ("\n") ; 
puts (message) ; 
return (0) ; 

) 

Flow  control  routines 

no_op ( ) 

< 

return (0) ; 


next_question (pc) 

struct  prcontrol  *  pc; 

I 

++pc->current_question; 
return (0) ; 

) 

(continued  on  page  130) 
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listing  One  (Listing  continued,  text  begins  on  page  68.) 

pop_group(pc) 

struct  prcontrol  *  pc; 

{ 

— pc - >gr oup_s t  a ck_pt  r ; 

pc->current_group  =  group_stack[pc->group_stack_ptr] .group; 
pc->current_question  =  group_stack[pc->group_stack_ptr] .current_question; 
return (0) ; 

} 


push_current_group (pc) 

struct  prcontrol  *  pc; 

I 

group_stack [pc->group_stack_ptr] .group  =  pc->current_group; 
group_stack [pc->group_stack_ptr] .current_question  =  pc->current_question; 
++pc->group_st  ack_pt  r ; 
return (0) ; 

) 


struct  prcontrol  ( 

int  current_question; 

struct  question  *  current_group; 

int  group_stack_ptr; 

char  response [121] ; 

int  errstat; 

struct  errormess  *  errorraess; 

}: 


struct  question  { 
char  *  text; 
char  *  response; 
int  (‘validate) () ; 
int  (*doit)(); 
int  (*set){); 

}; 


start_group (newgroup, pc) 

struct  question  *  newgroup; 
struct  prcontrol  *  pc; 

( 

push_current_group (pc) ; 
pc->current_group  =  newgroup; 
pc->current_question  =  0; 
return (0) ; 

} 


struct  group_stack  { 

struct  question  *  group; 
int  current_question; 

); 

/************************ 
errormess  data  structure 


restart_group(pc) 

struct  prcontrol  *  pc; 

{ 

pc->current_question  =  0; 
return (0) ; 


end_group(pc) 

struct  prcontrol  *  pc; 


pop_group (pc) ; 
++pc->current_question; 
return (0) ; 


checker ror_end_group (pc) 
struct  prcontrol  *  pc; 


struct  errormess  f 
int  errstat; 
char  *  message; 
int  (‘build) (); 

}; 

♦define  GROUP_STACK_SIZE  50 

♦define  NO_ERROR  0 

♦define  EXIT_NOW  2001 

int  pop_group ( ) ,  end_group ( ) , no_op ( ) , next_question ( ) ; 
int  checkerror_end_group ( ) , checkerror_next_question ( ) ; 


Listing  Three 

Name  :  prsample.c 


End  Listing  Two 


if (pc->errstat) { 
return (0) ; 
i 

end_group (pc) ; 
return (0) ; 


Description  :  A  sample  that  uses  the  prompter ()  routine 

♦include<stdio.h> 

♦include"prompter . h" 

♦include<ctype . h> 


checkerror_next_question (pc) 
struct  prcontrol  *  pc; 

{ 

if (pc->errstat) { 
return (0) ; 

} 

next_question (pc) ; 
return (0) ; 


Listing  Two 

/******************************.***.********■ 
Name  :  prompter. h 

Description  :  Declarations  for  prompter 


End  listing  One 


The  report  parameter  variables 

char  report_destination [2] ; 

char  dest_filename [30] ; 

char  single_or_range [2] ; 

char  start_account [20] ,end_account [20] ; 

int  account_number; 

char  display_parmname [50] ; 

char  include_overshort [2] ; 

Error  Values 
*********************/ 

♦define  ENTER_S_OR_R  1 

♦define  ENTER_Y_OR_N  2 

♦define  START  ACCOUNT_LARGER  3 


(continued  on  page  132) 
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listing  Three  ( Listing  continued,  text  begins  on  page  68.) 


# define  BAD_PARM_NAME  4 
♦define  BAD_ACCOUNT_NUMBER  5 
♦defime  ENTER_P_S_OR_D  6 
♦define  FILE_EXISTS  7 


Report  to  printer,  screen  or  disk  routines 

int  filename_val () ; 

struct  question  report_filename [ ]  =  ( 

{  "What  is  the  name  of  the  disk  file?", 

dest_filename, f ilename_val, no_op, checker ror_end_group} , 
{  NULL, NULL, NULL, NULL, NULL  } 

}; 


filename_val (pc) 

struct  prcontrol  *  pc; 

{ 

FILE  *  fp, *fopen(); 

/*  you  should  put  a  routine  to  validate  that  the  response 
entered  is  a  legal  file  name  here  */ 
if ( f p  =  fopen (pc->response, "r") ) { 
fclose (fp) ; 
return (FILEEXISTS) ; 

} 

return (0) ; 


reportdest_val (pc) 

struct  prcontrol  *  pc; 

{ 

char  *  strchrO; 

if ({ Istrchr ("PpSsDd",pc->response[0] ) )  ! !  (strlen (pc->response)  !-  1))( 
return (ENTER_P  S_OR_D) ; 

I 

return (0) ; 


reportdest_set (pc) 

struct  prcontrol  *  pc; 

( 

char  destination; 

destination  =  islower (*pc->response)  ?  *pc->response-32  :  *pc->response; 
switch (destination) { 
case  'P'  : 

case  'S'  :  next_question (pc) ; 
break; 

case  'D'  :  start_group (report_filename,pc) ; 
break; 

1 

return (0) ; 


Account  routines 

int  account_val ( ) , end_account_set ( ) , end_account_val ( ) ; 

struct  question  account_range[]  =  { 

("Enter  the  starting  account.", 

start_account, account_val, no_op, checkerror_next_question) , 
("Enter  the  ending  account.", 

end_account,  end_account_val, no_op, end_account_set ) , 

{  NULL, NULL, NULL, NULL, NULL  ) 

}; 


int  save_account_doit ( ) , account_set ( ) ; 
struct  question  account [1  =  { 

("Enter  the  account.", 

start_account, account_val, save_account_doit, checker ror_end_group) , 
(NULL, NULL, NULL, NULL, NULL) ); 

account_or_range_val (pc) 
struct  prcontrol  *  pc; 

I 

char  *  strchrO; 

if (( Istrchr ("SsRr",pc->response(0] ) )  !!  (strlen (pc->response)  >  1)){ 
return (ENTER_S_OR_R) ; 

} 

return  (0) ; 


account_or_range_set (pc) 
struct  prcontrol  *  pc; 

{ 

char  account_or_range; 

account_or_range  =  islower (*pc->response)  ?  *pc->response-32  : 
*pc->response; 

if (pc->errstat) ( 
return (0) ; 

) 

if (account_or_range  ==  'S')( 
start_group (account,  pc) ; 

) 

if (account_or_range  ==  'R'){ 

start_group(account_range,pc) ; 

} 

return (0) ; 


end_account_val (pc) 

struct  prcontrol  *  pc; 

< 

int  errstat; 

if  (errstat  =  account_val (pc) ) f 
return (errstat) ; 

) 

if (atoi (start_account)  >=  atoi (pc->response) ) ( 
return (START_ACCOUNT_LARGER) ; 

) 

return (0) ; 


end_account_set (pc) 

struct  prcontrol  *  pc; 

( 

switch (pc->errstat) ( 

case  NO_ERROR  :  end_group (pc) ; 

break; 

case  START_ACCOUNT_LARGER  :  restart_group (pc) ; 

break; 

case  BAD_ACCOUNT_NUMBER  :  break; 

1 

return (0) ; 


Get  display  parameters  routines 


char  *  legal_parmnames [)  =  (  /’ 

"default",  /■ 

"daily",  /’ 

"weekly",  /’ 

"yearly", 

NULL 

}; 


In  a  "real"  system,  this  table  */ 
would  probably  be  stored  in  a  file  */ 
and  parmname_val  would  check  to  see  */ 
if  the  name  entered  is  in  this  file.  */ 


parmname_val (pc) 

struct  prcontrol  *  pc; 

{ 

int  i; 

for(i  =  0  ;  legal_parmnames [i]  !=  NULL  ;  ++i) ( 

if  (strcmp(pc->response,  legal_parirtnames  [i] )  ==  0)  ( 
return (0) ; 


return (BAD_PARM_NAME ) ; 

) 

bld_bad_parmname (message) 
char  *  message; 

( 

sprintf (message  +  strlen (message) , "  %s,  %s,  %s,  or  %s.’\ 

legal_parmnames [0] , legal_parmnames ( 1 ) , legal_parmnames [2] , 
legal_parmnames [3] ) ; 
return  (0) ; 

} 

/**********,********.****** 
yesno  validation 

yesno_val (pc) 

struct  prcontrol  *  pc; 

{ 

char  *  strchrO; 

if { ( ! strchr ("YyNn",pc->response [0] ) )  !!  (strlen (pc->response)  !=  1)){ 
return (ENTER_Y_OR_N) ; 

) 

return  (0) ; 


Main  question  array  procedure  table 
struct  question  account_parms [ ]  =  ( 

("Do  you  want  this  report  for  a  single  account  or  a  range  of  accounts?  (S 
or  R) ", 

single_or_range, account_or_range_val, no_op, account_or_range_set  } , 
("Enter  the  name  of  the  display  parameter  record.", 

display_parmname,parmname_val, no_op, checker ror_next_quest ion), 

("Do  you  want  to  include  the  Over/Short  Report?  (Y/N)", 

NULL, yesno_val, no_op, checkerror_next_question) , 

("Do  you  want  this  report  on  the  printer,  screen,  or  saved  to  disk?(P,S  or 

D)\ 

report_destination, reportdest_val, no_op, reportdest_set ) , 

{  NULL, NULL, NULL, NULL, NULL  ) 

In¬ 


struct  errormess  account_errormess [ ]  =  ( 

{  ENTER_S_OR_R, "Please  enter  S  or  R.",NULL  ), 

{  ENTER_Y_OR_N, "Please  enter  Y  or  N.",NULL  ), 

(  START_ACCOUNT_LARGER, "The  starting  account  must  be  smaller  than  the 
ending  account .", NULL  ), 

(  BAD_ACCOUNT_NUMBER, "The  account  number  must  be  between  100  and 
1000", NULL  ), 

(  BAD_PARM_NAME, "Choose  one  of  the  following  : ", bld_bad_parmname  ), 

{  ENTER_P_S_OR_D, "Please  enter  P,  S  or  D" , NULL  ), 

(  FILE_EXISTS, "That  file  already  exists. ",  NULL  ), 

(  -1, NULL, NULL  } 

); 


save_account_doit (pc) 

struct  prcontrol  *  pc; 

{ 

account_number  =  atoi (pc->response) ; 
return (0) ; 

) 


main (argc, argv) 
int  argc; 
char  *  argvf); 

( 

int  errstat; 

struct  prcontrol  prcontrol; 


account_val (pc) 

struct  prcontrol  *  pc; 

{ 

if ( (atoi (pc->response)  <  100)  !!  (atoi (pc->response)  >  1000) )( 
return (BAD_ACCOUNT_NUMBER) ; 

) 

return (0) ; 

) 


prcontrol. current_group  =  account_parms; 
prcontrol .errormess  =  account_errormess; 

if (errstat  =  prompter (fiprcontrol) ) { 

handle_error (errstat, account_errormess) ; 

) 

/*  Print  the  report  with  the  gathered  parameters  */  End  Listings 


132 

574 


Dr.  Dobb’s Journal,  August  1989 


PROGRAMMING  PARADIGMS 


Background  on 
Backprop 


Last  month  I  reported  on  a  conver¬ 
sation  with  engineer  Hal  Harden- 
bergh  about  his  interest  in  neural 
networks.  I’ve  also  been  talking 
with  Hardenbergh’s  software  cohort  in 
neuraldom,  Tom  Waite,  as  well  as  with 
neural  net  algorist  Dave  Parker  and 
engineer/programmer/writerjurgen  Fey 
about  neural  nets,  transputers,  and  the 
Occam  language.  Next  month  I’ll  re¬ 
port  on  those  conversations  and  take 
a  more  algorithmic  look  at  neural  nets. 

This  month  I’m  stepping  out  of  the 
interview  format  to  present  some  back¬ 
ground  that  I  hope  will  put  last  month’s 
and  next  month’s  columns  in  perspective. 
Last  month’s  column  touched  only  tan- 
talizingly  on  some  issues,  such  as  the 
present-day  practical  uses  of  neural  net 
technology.  There  are  some  remarkably 
mundane  as  well  as  some  cutting-edge 
uses  to  which  neural  net  insights  have 
been  put  in  the  past  twenty-five  years. 

Also,  the  interview  format  may  have 
made  it  hard  to  be  sure,  in  reading  last 
month’s  column,  just  what  was  histori¬ 
cal  or  technological  fact  and  what  was 
Hardenbergh’s  perspective  (however 
valid  and  interesting  that  perspective 
might  be).  This  month’s  neural  net  back¬ 
grounder  should  clear  that  up.  The  very 
fact  that  a  hardware  engineer  would 
get  interested  in  what  has  been  re¬ 
ferred  to  as  “the  parapsychology  of 


Michael  Swaine 


AI,”  a  fact  that  I  presented  as  some¬ 
what  surprising,  in  fact  has  a  history 
of  its  own,  and  in  the  perspective  of 
that  history  is  not  so  surprising  after  all. 

Lately  in  this  column  I  have  been 
asking  software  developers  (and  last 
month  an  engineer)  why  they  are  pur¬ 
suing  certain  approaches  to  software 
development  rather  than  other  ap¬ 
proaches.  This  month  I  guess  I’m  ask¬ 


ing  myself  “Why  neural  networks?” 
You’ll  find  only  one  reference  listed  at 
the  end  of  this  column,  because  all  the 
articles  I  drew  upon  can  be  found  in 
the  omnibus  collection  by  Anderson 
and  Rosenfeld.  I  recommend  it  to  any¬ 
one  interested  in  the  history  and  pre¬ 
sent  state  of  neural  network  research 
and  development. 

Where  Did  11  Begin? 

The  perceptron  model  proposed  by  F. 
Rosenblatt  in  1958  was  the  beginning 
of  all  modern  neural  network  research. 
It  already  contained  most  of  the  inter¬ 
esting  elements  present  in  today’s  neu¬ 
ral  nets. 

It  described  an  artificial  nervous  sys¬ 
tem.  It  combined  cells  into  several  con¬ 
nected  layers:  A  “retina”  where  input 
signals  arrived,  an  “association  layer” 
where  retinal  cells  connected,  and  a 
“response  layer.”  Connections  between 
association-level  and  response-level 
cells  were  bidirectional,  permitting  feed¬ 
back  that  allowed  the  perceptron  to 
learn.  The  goal  of  the  operation  of 
the  perceptron  was  to  learn  to  activate 
the  right  response  layer  for  the  given 
input. 

Rosenblatt  also  focused  on  the  kind 
of  problem  that  occupies  most  neural 
networks  today:  The  classification  of 
interesting  patterns  of  inputs.  It  was  a 
sufficiently  difficult  problem  that  it  still 
challenges  neural  net  developers;  it  was 
also  sufficiently  difficult  to  cause  seri¬ 
ous  problems  for  Rosenblatt’s  per¬ 
ceptron  when  two  AI  experts  subjected 
the  perceptron  to  rigorous  analysis. 

Where  are  the  Practical  Applications? 

As  I  was  working  on  this  column,  I  got 
a  call  from  Hal  Hardenbergh.  You  know 
what  new  explosives  detector  they’re 
using  at  JFK  International  Airport?  he 
wanted  to  know.  Yep.  Well,  it’s  a  neu¬ 
ral  net.  Coming  as  it  did  two  days  be¬ 


fore  I  would  be  standing  in  a  line  at  JFK 
to  board  a  flight  to  Europe,  Harden¬ 
bergh’s  bulletin  took  on  a  personal  sig¬ 
nificance  for  me. 

There  are  more  neural  net  devices 
in  use  than  meet  the  eye.  A  fair  amount 
of  neural  net  research  and  develop¬ 
ment  is  DoD  work,  and  we  either  don’t 
hear  about  it  or  hear  about  it  only 
obliquely.  Sometimes  presentations  at 
neural  network  conferences  seem  to 
be  delivered  in  an  obscure  code.  What 
is  this  about  recognizing  faces  in  the 
fog?  Wait,  if  you  substitute  “smoke”  for 
“fog”  and  “tank”  for  “face,”  does  it 
begin  to  make  more  sense? 

One  of  the  biggest  success  stories  to 
come  out  of  neural  network  research 
is  adaptive  switching  circuits,  described 
by  Bernard  Widrow  and  Marcian  E. 
Hoff  in  I960.  Hoff  is  Ted  Hoff,  the 
inventor  (if  you  live  west  of  the  Rio 
Grande)  of  the  microprocessor. 

The  perceptron  learned  by  changing 
its  coupling  coefficients  in  response  to 
error  feedback  regarding  its  immediate 
past  classifications.  But  many  of  the 
proposed  perceptron  learning  rules 
were  impractically  slow  in  converging 
to  the  coefficients  that  would  give  cor¬ 
rect  classifications.  Widrow  and  Hoff 
developed  what  they  called  an  adap¬ 
tive  neuron,  related  to  perceptrons,  that 
conveiged  to  correct  classification  quickly. 
One  novel  feature  of  Widrow  and  Hoffs 
neuron  was  that  it  continued  to  learn 
even  when  it  was  emitting  correct  re¬ 
sponses. 

Widrow  and  Hoff  built  a  lunchbox¬ 
sized  adaptive  pattern  classification  ma¬ 
chine  to  demonstrate  their  adaptive  neu¬ 
ron’s  learning  behavior.  They  originally 
called  the  box  Adaline,  which  stood 
for  either  Adaptive  Linear  Neuron  or 
Adaptive  Linear  Element,  depending 
on  how  comfortable  they  felt  about 
neural  net  research  when  they  were 
discussing  it. 
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(continued  from  page  134) 

But  it  was  not  learning  lunchboxes 
that  proved  the  value  of  Widrow  and 
Hoffs  technique.  The  error  correction 
algorithm  they  used  is  called  “least  mean 
squares,”  or  LMS,  because  it  involves 
minimizing  the  square  of  the  error,  and 
LMS  has  been  used  extensively  in  sig¬ 
nal  processing  and  has  seen  wide  use 
in  error  correction  in  modems. 

Neural  net  research 
focuses  on  how  to 
hook  up  networks 
of  artificial  neurons  so 
they  can  learn  from 
experience 


Widrow  and  Hoff  also  laid  some 
groundwork  for  current  neural  net  de¬ 
velopment.  Neural  net  research  focuses 
on  how  to  hook  up  networks  of  artifi¬ 
cial  neurons  so  they  can  learn  from 
experience.  The  best-known  current  al¬ 
gorithm  for  implementing  “experience” 
in  neural  nets  is  back  propagation, 
which  is  a  generalization  of  the  Widrow/ 
Hoff  rule.  As  Hardenbergh  pointed  out 
here  last  month,  back  propagation  had 
to  be  discovered  three  times  before  the 
discovery  stuck. 

Why  Three  Times? 

Rosenblatt  first  described  the  perceptron 
in  1958,  but  the  machinery  he  first  pro¬ 
posed  is  still  in  use  in  neural  network 
research  and  development.  For  years 
it  was  a  hot  area  of  research,  with  hun¬ 
dreds  of  papers  published. 

Then,  suddenly,  the  bottom  dropped 
out,  and  so  did  the  funding.  The  very 
use  of  the  word  “neuron”  became  un¬ 
popular  in  AI  work.  The  reason  was 
the  fundamental  inability  of  elemen¬ 
tary  perceptrons  to  classify  certain  kinds 
of  patterns.  Psychological  researchers 
called  the  relevant  kind  of  pattern  clas¬ 
sification  problem  concept  attainment, 
and  the  interesting  patterns  in  concept 
attainment  were  those  involving  dis¬ 
contiguous  sets,  exclusive  ors,  and  prob¬ 
lems  that  could  not  be  solved  by  parti¬ 
tioning  an  input  space  with  planes. 
This  limitation  of  simple  perceptrons 


was  brilliantly  spelled  out  in  Minsky  & 
Papert’s  1969  book  Perceptrons. 

Minsky  and  Papert  made  their  point 
clearly  and  emphatically.  Inability  to 
handle  problems  of  the  concept  forma¬ 
tion-type  was  a  serious  problem,  and 
they  treated  it  as  such:  They  dismissed 
the  bulk  of  the  hundreds  of  perceptron 
papers  as  “without  scientific  value.” 

In  retrospect,  it  appears  that  Minsky 
and  Papert  were  a  little  precipitous  in 
concluding  that  the  problem  they  iden¬ 
tified  could  not  be  solved.  Simple  single¬ 
layer  perceptrons  may  have  been 
proved  to  be  without  scientific  value, 
but  the  same  could  not  be  said  for 
multilayer  perceptrons.  Adding  a  cou¬ 
ple  more  layers  would  allow  per¬ 
ceptrons  to  classify  all  sorts  of  prob¬ 
lems,  although  it  complicated  the  learn¬ 
ing  problem  seriously.  What  was  needed 
was  a  practical  learning  algorithm  for 
multilayer  perceptrons.  But  so  effec¬ 
tive  was  Minsky  and  Papert’s  demoli¬ 
tion  job  that  nobody  took  the  discov¬ 
ery  of  such  an  algorithm  seriously  at 
first.  Or  at  second. 

Is  Backprop  the  Algorithm  of  Choice? 

It  is  if  you  are  doing  multilevel  neural 
net  work.  The  only  other  algorithm 
that  works  with  multilayer  nets,  the 
Boltzmann  machine,  is  much  slower. 

Backprop  is  a  generalization  of  the 
Widrow/Hoff  error  correction  rule.  The 
Widrow/Hoff  rule  compared  the  actual 
output  with  what  the  output  was  sup¬ 
posed  to  be  and  used  the  magnitude 
of  the  error  to  adjust  strengths  of  the 
connections  between  cells.  For  situ¬ 
ations  in  which  the  correct  response 
was  known,  it  worked  well.  Adding 
additional  layers  introduces  a  difficulty. 
How  do  you  compute  the  correct  output 
for  the  hidden  intermediate  layers  in 
order  to  adjust  the  connection  strengths 
that  led  to  these  outputs?  The  problem 
is  complicated  by  the  fact  that  adjusting 
the  connection  strengths  actually  changes 
the  topology  of  the  network. 

The  solution  used  in  back  propaga¬ 
tion  is  to  run  the  connections  back¬ 
ward,  to  ascertain  the  strengths.  Back 
propagation  involves  a  forward  pass 
through  the  layers  to  estimate  the  error 
and  a  backward  pass  to  modify  the 
connection  strengths  and  decrease  the 
error. 

Backprop  currently  looks  like  one 
of  the  most  promising,  if  not  the  most 
promising  area  of  neural  net  research, 
and  could  generate  some  interesting 
results.  One  of  the  intriguing  ideas  about 
neural  nets,  particularly  Boltzmann  ma¬ 
chines  and  backprop  nets,  is  the  no¬ 
tion  that  deep  insights  into  the  nature 
of  the  information  being  processed  and 
the  effective  representation  of  it  can 
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(continued  from  page  136) 
be  derived  from  looking  at  the  internal 
layers.  A  neural  net  that  learns  to  clas¬ 
sify  patterns  effectively,  it  is  argued, 
contains  in  its  hidden  layers  a  repre¬ 
sentation  of  the  input.  If  the  output 
classifications  are  adequate  to  our  needs, 
then  the  hidden-layer  representations 
are  also  adequate,  and  we  could  send 
only  these  representations,  dispensing 
with  the  input. 

One  benefit  could  be  the  use  of 
backprop  neural  nets  to  develop  new 
data  compression  algorithms. 

Why  is  This  of  Interest  to  a 
Hardware  Engineer? 

It’s  not  so  odd  that  Hardenbergh,  an 
engineer,  was  attracted  to  this  domain 
of  artificial  intelligence.  Perceptron  re¬ 
search  and  neural  network  research 
have  always  had  enormous  appeal  for 
engineers.  “Much  of  the  later  work  on 
perceptrons  and  successors  was  done 
by  engineers  and  physicists,”  Ander¬ 
son  and  Rosenfeld  say,  “a  situation  still 
true  today  in  research  on  neural  net¬ 
works."  The  perceptron  was  a  learning 
machine,  potentially  capable  of  com¬ 
plex  adaptive  behavior.  It’s  easier  to 
conceive  of  it  as  a  device  than  as  an 
approach  to  developing  AI  software 
systems;  and  until  you  see  the  algo¬ 


rithms  spelled  out,  it’s  easier  to  see 
neural  nets  as  a  mathematical  or  engi¬ 
neering  challenge  than  as  a  program¬ 
ming  problem. 

Hardenbergh  and  Waite  see  them  as 
all  of  the  above.  Although  I  don’t  mean 
this  to  be  a  plug  for  Vicom  or  its  em¬ 
ployees,  there  are  several  reasons  why 
I  am  going  to  keep  a  journalist’s  eye 
on  Hardenbergh  and  Waite  and  Vicom. 

•  The  canonical  problem  for  neural 
networks  is  the  classification  of  vis¬ 
ual  figures,  pattern  classification.  The 
earliest  work  in  the  neural  net  tradi¬ 
tion,  Walter  Pitts  and  Warren  S. 
McCulloch’s  research  in  the  1940s, 
focused  on  problems  like  recogniz¬ 
ing  squares  wherever  they  appeared 
in  the  visual  field.  The  basic  problem 
remains  unsolved  today.  It’s  particu¬ 
larly  apparent  to  anyone  who  has  to 
process  image  data.  Vicom  is  in  the 
image-processing  business. 

•  Image-processing  companies  are  at 
something  of  an  impasse:  They  all 
have  the  same  algorithms,  nobody 
has  any  technological  edge.  The  time 
is  ripe  for  a  new  approach. 

•  Vicom  is  not  exclusively  wrapped  up 
in  DoD  work,  so  that  smokescreens 
will  not  obscure  their  results. 

•  The  amount  of  money  required  to 


fund  a  real  breakthrough  in  neural 
nets  for  image  processing  is  probably 
not  enormous,  not  beyond  the  reach 
of  potential  customers  of  a  company 
like  Vicom. 

•  I  like  the  way  Waite  and  Harden¬ 
bergh  are  approaching  this.  They  are 
pragmatic  enough  to  be  discussing 
using  neural  nets  as  a  component  of 
an  image  processing  system,  not  over¬ 
loading  the  network,  not  forcing  it 
to  solve  problems  for  which  there  are 
already  good  image  processing  solu¬ 
tions.  They  are  bringing  hardware  and 
software  knowledge  into  the  process 
at  the  start.  And  they  seem  focused, 
which  is  good  if  their  approach  is  the 
right  one. 

Next  month:  Tom  Waite  (and  others) 
on  back  propagation  (and  other  topics). 

Reference 

Anderson,  James  A.  and  Rosenfeld,  Ed¬ 
ward,  Neurocomputing:  Foundations 
of  Research.  MIT  Press,  Cambridge,  MA, 
1988. 
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OOPs  to  the  Left, 
FOPs  to  the  Right, 
and  a  View  from 
the  Center 

It  turns  out  that  I  have  been  misus¬ 
ing  a  C  language  feature,  the  power 
of  which  I  have  only  just  come  to 
understand.  The  feature  is  the 
typedef  statement.  Let’s  examine  how 
my  minor  transgression  came  about  by 
looking  at  how  typedef  can  be  used 
and  how  it  should  be  used. 

Suppose  you  have  a  structure  like 
this  one: 

struct  empl_rc:d  1 
int  emplno; 
char  emplname[251; 
unsigned  date_hired; 
int  empLcategory; 
long  salary; 

); 

You  can  define  a  brand  new  data  type 
for  this  structure  with  the  typedef  state¬ 
ment.  Of  such  is  the  extensible  nature 
of  C.  It  works  like  this: 

typedef  struct  empl_rcd  EMPLOYEE; 

All  declarations  of  the  structure  can 
now  use  the  new  EMPLOYEE  data  type 
rather  than  the  struct  empl_rcd  type. 
These  are  examples  of  how  you  can 
declare  instances  of  this  data  type. 

EMPLOYEE  newhire; 

EMPLOYEE  ’retired; 

EMPLOYEE  chiefs[51; 

Why  do  this?  Subsequent  references 
to  the  structures  might  gain  nothing  from 
the  use  of  the  typedef  In  practice,  you 
could  not  tell  by  looking  at  the  code  that 
accessed  one  of  these  structures  that 
the  EMPLOYEE  data  type  had  been  de¬ 
fined  at  all.  Witness  these  expressions. 

printfCnewhire.emplname); 
total_payroll  +=  chiefsli], salary; 
return  retired->empl_category; 


Al  Stevens 


In  none  of  these  cases  is  the  code 
insulated  from  the  format  of  the  data 
structure.  In  all  cases,  the  code  is  ex¬ 
actly  the  same  as  if  the  typedef  had  not 
been  used.  The  strongest  advantage  of 
the  typedef  its  ability  to  hide  informa¬ 
tion,  is  not  realized  by  these  uses  of  it. 
If  no  other  software  in  your  system 
needs  to  know  that  EMPLOYEES  exist, 
the  typedef  is  wasted.  What,  then,  do 
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you  gain  from  the  EMPLOYEE  typedef 
provided  in  these  examples?  Nothing, 
unfortunately,  unless  you  consider  the 
reduced  keystrokes  involved  in  coding 
the  name. 

Now  consider  the  C  standard  input/ 
output  library  FILE  type.  This  is  a  typedef 
defined  in  stdio.h  that  identifies  a  stream 
file  definition.  The  structure  itself,  if 
such  there  be,  is  defined  in  stdio.h,  and 
its  name  and  format  are  implementation- 
dependent.  A  designer  of  a  standard  C 
input/output  library  can  define  a  FILE 
to  be  anything  from  a  simple  integer 
to  the  file-defining  structure  itself.  This 
seems  to  be  a  more  correct  use  of 
typedef.  There  is  something  called  a 
FILE,  and  its  implementors  know  its 
internals.  You  know  only  what  you 
need  to  know  to  use  a  FILE,  and  you 
do  not  care  whether  it  is  a  structure, 
union,  integer,  pointer,  or  what.  All 
you  know  is  that  you  can  use  one. 

In  an  application  program  you  typi¬ 
cally  do  three  things  with  a  FILE  data 
type.  You  declare  pointers  to  the  type, 
assign  values  to  the  pointers  by  calling 
library  functions  that  return  the  address 
of  a  FILE,  and  pass  the  FILE  pointers 
to  other  functions.  The  library  func¬ 
tions  know  what  to  do  with  the  point¬ 
ers  because  they  know  the  format  of 
the  FILE  data  type.  The  calling  program 
does  not  (or  does  not  need  to)  know 
that.  The  information  is  thus  hidden. 
You  can  peek  and  learn  it  if  you  want, 
and  you  could  code  specific  references 
to  the  data  structures  that  underlie  it,  but 
you  would  surely  sacrifice  portability, 
not  only  among  compilers  but  possibly 
between  versions  of  the  same  compiler. 

How  then  could  we  use  the  EM¬ 
PLOYEE  typedef  in  ways  that  would 
benefit  us?  One  way  would  be  to  de¬ 
fine  it  in  a  header  file  and  tuck  all  the 
employee-related  functions  away  in 
their  own  function  library,  much  like 
the  stdio.h  file  and  standard  library  are 
used.  Then,  applications  programs  that 
need  to  do  things  to  employee  records 
could  call  these  functions  with  EM¬ 
PLOYEE  pointers  in  the  same  way  we 
use  the  FILE  pointer  for  stream  input/ 
output.  The  functions  in  the  library 
would  have  to  be  aware  of  the  formats 
of  the  data  structures,  but  the  using 
functions  would  not.  That  way  payroll, 
personnel,  and  project  management  sys¬ 


tems  could  all  use  the  same  employee 
function  library  without  needing  to  know 
the  internal  formats  and  methods  of 
how  employee  records  are  stored.  Al¬ 
most  object-oriented,  wouldn’t  you  say? 

How  have  I  abused  the  typedef  Last 
autumn,  in  the  window  function  library 
that  supports  the  SMALLCOM  project, 
I  defined  MENU  and  FIELD  data  types 
and  then  required  the  applications  pro¬ 
grams,  programs  that  you  might  write, 
to  initialize  the  .structures  under  the 
typedef  definitions.  Nothing  is  hidden. 
In  order  to  use  the  menu  and  data- 
entry  function  library,  you  must  know 
the  format  of  those  structures.  Change 
the  format  and  you  must  change  your 
programs.  A  better  approach  would 
have  been  to  provide  initializing  func¬ 
tions  or  macros  with  initializing  data 
values  as  parameters.  Then,  when  the 
underlying  structures  and  functions 
change  to  accommodate  new  require¬ 
ments,  only  the  applications  programs 
that  deal  with  the  changes  need  to  be 
looked  at. 

Why  do  1  need  to  hide  information 
from  myself?  I  know  the  formats  of 
those  structures,  I  understand  the  prob¬ 
ability  that  they  will  change  and  the 
implications  of  such  change,  and,  be¬ 
sides,  initializations  are  more  efficient 
at  compile  time  than  at  run-time,  any¬ 
way.  (Insert  here  your  favorite  argu¬ 
ment  for  continuing  to  do  things  the 
way  you  have  always  done  them.) 

A  compiler  must  hide  the  details  of 
the  FILE  data  type  to  preserve  the  stan¬ 
dard  method  for  implementing  it.  But 
how  well  hidden  is  it?  Look  into  stdio.h 
and  you  will  see  the  whole  enchilada. 
The  FILE  structure  format  is  there.  Some 
of  the  standard  library  functions  ex¬ 
pand  into  macros  that  directly  address 
members  in  the  FILE  structure,  and  the 
macros  are  there.  How  well  hidden  is 
information  that  I  can  find  in  well- 
commented  source  code  by  using  my 
text  editor? 

The  answer,  of  course,  is  that  the 
standard  input/output  information  hidey- 
hole  is  a  benign  safe-store,  benign  in 
that  a  curious  seeker  can  find  it  and 
peruse  its  contents  without  difficulty, 
benign  in  that  only  casual  measures 
protect  its  secrets  from  the  voyeur.  You 
would  not  care  to  regard,  on  a  daily 
basis,  the  details  of  the  garbage  dis- 
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posal  in  your  kitchen  or  the  destination 
of  its  fare,  but  you  know  where  the 
information  can  be  found  if  you  really 
need  it.  The  same  is  true  of  the  infor¬ 
mation  hidden  in  readily  accessible 
stashes  such  as  stdio.h. 

These  are  not  new  ideas.  Informa¬ 
tion  hiding  has  been  talked  about  and 
used  for  years.  But  it  has  come  to  be 
viewed  in  a  new  light  in  recent  years, 
one  called  “object-oriented  program¬ 
ming,”  and  I  began  to  revisit  my  own 
practices  with  such  things  as  typedef 
when  I  began  studying  OOP.  The  new 
light  is  still  dim  and  my  vision  myopic, 
but  we’ll  break  out  of  the  clouds  soon, 

I  think.  One  thing  is  clear:  OOP  en¬ 
courages  you  to  do  a  better  job  of 
hiding  the  hideable  information. 

OOPs 

I  think  it  was  Robert  Benchley  who 
observed  that  the  world  is  divided  into 
two  kinds  of  people  —  those  who  di¬ 
vide  the  world  into  two  kinds  of  peo¬ 
ple  and  those  who  do  not.  The  world 
of  programmers  is  dividing.  There  are 
those  who  embrace  object-oriented  pro¬ 
gramming  and  those  who  do  not.  Let’s 
wonder  why. 

We  are  told  that  to  learn  OOP  we 
must  abandon  what  we  know  about 
conventional  programming,  that  the  big¬ 
gest  obstacle  to  learning  is  one  of  un¬ 
learning.  The  prospect  of  returning  to 
elementary  school  will  discourage  a  lot 
of  conventional  programmers  who  feel 
that  they  know  how  to  write  programs 
just  fine,  thank  you. 

My  pal  at  DDJ ,  Kent  Porter,  suggested 
a  two-syllable  word  for  the  notion  that 
OOP  is  totally  new  and  different,  a 
word  that  means  what  you  get  when 
you  run  your  favorite  straw  hat  through 
a  bull.  Kent  had  been  toying  with  the 
object-oriented  extensions  coming  to 
Turbo  Pascal  and  had  crossed  the  fence 
to  the  greener  pastures  of  OOP.  Kent 
was  too  old  to  start  learning  all  over 
again.  And  he  was  too  young  to  leave 
when  he  did.  I  will  miss  him. 

For  me,  I  am  studying  C++  now,  and 
it  has  been  suggested  that  the  Turbo 
Pascal  extensions  are  a  smooth  bridge 
from  C  to  C++.  I  intend  to  explore  that 
possibility.  My  prophesy  is  that  the  pre¬ 
vailing  OOP  language  will  be  C++,  and 
that  its  full  acceptance  will  occur  when 
and  if  Borland  and  Microsoft  introduce 
C++  compilers.  If  anything  has  ever 
screamed  for  OOP  support,  the  appli¬ 
cations  program  interfaces  to  DOS  Win¬ 
dows  and  OS/2  Presentation  Manager 
have.  Their  apparently  object-oriented 
architectures  sure  do  need  a  C++  with 
related  object  libraries  behind  them. 

I  tend  toward  C++  because  it  is  a 
superset  of  C,  and  one  can  always  re¬ 


treat  to  C  when  the  OOP  view  does 
not  seem  to  fit.  Some  OOP  purists  sug¬ 
gest  that  C++  is  not  really  OOP.  Maybe, 
maybe  not,  and  maybe  the  paradigm 
has  not  settled  in,  but  I’ll  still  bet  C++ 
is  the  wave  of  tomorrow  if  there  is 
going  to  be  a  new  wave. 

Whether  or  not  C++  replaces  C  as  a 
primary  development  language  depends 
on  how  much  it  is  hyped  by  the  mov¬ 
ing  forces  in  language  development 
and  what  it  does  for  the  programmer. 
Certainly  if  Borland  and  Microsoft  get 
behind  it,  lots  of  programmers  will  give 
it  a  try.  But  programmers  will  not  stick 
with  C++  unless  there  is  a  reason  to. 

We  measure  the  value  of  a  language 
by  its  ability  to  express  a  complex  algo¬ 
rithm  with  few  lines  of  code  in  a  way 
that  can  be  read  and  plainly  under¬ 
stood.  Most  programmers  took  to  C 
because  it  could  do  those  things  with¬ 
out  getting  too  far  away  from  the  hard¬ 
ware  and  without  rigidly  enforcing  any¬ 
thing.  To  win  C  programmers  over, 
C++  has  to  get  things  nmning  with 
fewer  and  easier  lines  of  code,  make 
for  programs  that  are  easier  to  modify, 
or  both.  As  long  as  the  code  is  readable 
later,  why  code  two  when  one  will  do? 
C++  has  to  improve  our  ability  to  write 
programs,  or  it  is  not  necessary. 

So  what  is  different  about  OOP?  Per¬ 
haps  it  is  that  the  OOP  view  of  a  pro¬ 
gramming  problem  has  a  different  per¬ 
spective  than  the  one  we  enjoy  now. 
But  is  that  really  so? 

The  OOP  view  looks  toward  the  data 
structures  and  the  functions  specific  to 
those  structures.  You  describe  classes 
of  data,  objects  that  are  instances  of 
those  classes,  and  methods  to  process 
the  objects.  Then,  to  make  things  hap¬ 
pen,  you  send  a  message  to  an  object, 
and  things  happen.  Consider  that  old 
chestnut,  hello. c,  in  conventional  C. 

/* - hello. c  in  C - V 

#include  <stdio.h> 
main(  ) 

( 

printfO'hello,  world\n"); 

) 

This  program  is  oriented  to  the  func¬ 
tion  it  performs.  It  is  a  function-ori¬ 
ented  program  (FOP).  The  FOP  pro¬ 
grammer  thinks  about  solutions  in  terms 
of  the  procedure,  the  functions,  the 
steps  one  takes  to  solve  something. 

Now,  consider  the  same  program  in 
C++ 

\\ - hello. c  in  C++ 

#include  <stream.h  » 
main(  ) 

( 

cout  «  "hello,  world  \  n"; 

1 
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(continued  from  page  142) 

This  program,  we  are  told,  is  oriented 
to  its  objects,  the  data  structures  it  sup¬ 
ports,  and  the  methods  it  uses  to  sup¬ 
port  them. 

They  look  similar,  don’t  they?  In  con¬ 
ventional  C,  you  called  the  print/ func¬ 
tion,  passing  it  the  address  of  the  string 
to  display.  The  stdio.h  header  file  pro¬ 
vided  the  prototype  for  the  print/ func¬ 
tion.  In  C++  you  send  a  message  to 
cout,  which  is  an  object  of  class  os- 
tream  as  defined  in  stream.h.  The  mes¬ 
sage  consists  of  the  address  of  the  string. 
The  «  operator,  also  defined  in 
stream.h  as  a  part  of  the  class,  is  the 
method  the  object  will  use. 

The  «  operator  is  not  itself  an  inte¬ 
gral  part  of  C++  any  more  than  the 
print/ function  is  an  integral  part  of  the 
C  language.  The  «  operator  is  associ¬ 
ated  with  the  ostream  class  within 
stream.h.  You  can  associate  custom  op¬ 
erators  with  classes  in  C++.  The  greater- 
than  operator,  for  example,  can  mean 
different  things  to  different  classes.  More¬ 
over,  it  can  mean  different  things  in  the 
same  class  when  taken  in  the  context 
of  the  types  of  what  it  operates  on. 

Now  let’s  write  the  “hello,  world” 
message  to  a  file.  First,  we’ll  use  con¬ 
ventional  C: 

^include  <stdio.h> 
main(  ) 

( 

FILE  *fp; 

fp  =  fopenC'hello.dat",  "w"); 
fputs("hello,  world)  n",  fp); 
fclose(fp); 


In  standard  FOP  C,  you  call  three  func¬ 
tions.  The  first  one  opens  the  file  and 
returns  a  pointer  to  a  FILE.  The  second 
function  accepts  a  data  address  and 
a  FILE  pointer  and  sends  the  data 
string  to  the  file.  The  third  function 
closes  the  file. 

Now  let’s  look  at  the  same  operation 
with  C++: 

^include  <stream.h> 
main(  ) 

( 

filebuf  bf; 

bf.open("hello.dat",  output); 
ostream  op(&bf); 
op.putC'hello,  world\n"); 


In  the  C++  OOP  view,  you  declare  an 
object  of  class  filebuf  named  bf.  This 
object  is  the  data  buffer  itself.  Next  you 
connect  the  buffer  to  a  stream  file  with 
the  filebuf:open  function.  The  other 
way  of  saying  that  is  that  you  send  the 
string  address  and  the  output  flag  as 
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messages  to  the  bf  object,  telling  it  to 
use  its  open  method.  Then  you  declare 
an  object  of  type  ostream  named  op 
with  the  filebuf  as  an  initializing  argu¬ 
ment.  Finally  you  send  the  string  mes¬ 
sage  to  the  op  object  telling  it  to  use  its 
put  method. 

At  this  level,  the  two  views  are  still 
similar.  A  C  programmer  could  make 
the  transition  to  C++  with  little  prob¬ 
lem  if  this  was  as  far  as  it  went.  In  fact, 
you  might  wonder,  why  bother?  It  ap¬ 
pears  to  be  a  syntax  change,  nothing 
more.  The  big  difference,  however,  is 
in  what  is  hidden.  The  definitions  of 
the  filebuf  and  ostream  classes  are  sig¬ 
nificantly  different  from  their  FILE  coun¬ 
terparts  in  standard  C. 

“So  what?”  you  might  ask.  “The  dif¬ 
ferences  are  hidden.  Who  cares  how 
different  they  are?” 

Think  back  to  the  EMPLOYEES 
typedef.  That  one  is  a  part  of  the  appli¬ 
cation,  is  your  responsibility,  and,  if  it 
is  to  be  an  object,  needs  a  class,  hidden 
member  data  structures,  and  public  mem¬ 
ber  method  functions.  To  design  these 
things  you  have  to  be  as  object-ori¬ 
ented  as  the  language.  If  OOP  has  any¬ 
thing  to  offer,  the  apparent  different 
statement  syntax  is  not  it.  There  must 
be  merit  in  the  taking  of  that  different 
perspective. 

One  of  the  problems  we  will  con¬ 
front  in  writing  our  first  C++  programs 
is  deciding  what  should  be  classes  and 
objects  and  what  should  not.  When 
do  we  send  messages  and  when  do 
we  call  functions?  What  is  the  most 
appropriate  way  to  send  messages?  Sup¬ 
pose  your  program  posts  error  condi¬ 
tions  by  opening  a  window  and  dis¬ 
playing  the  message.  Should  the  error 
processor  be  an  old-fashioned  C  func¬ 
tion  like  this? 

errorC'Too  many  Chiefs1'); 

Or  should  the  error  processor  be  an 
object  of  a  class  of  output  like  this? 

class  error:  public  window  I 


error  errs; 

errs.postC'Too  many  Chiefs"); 

Should  the  error  processor  use  a  mem¬ 
ber  function  as  just  shown,  or  should 
it  use  its  own  operator  to  post  errors 
like  this? 

errs  «  "Too  many  Chiefs"; 

You  might  post  errors  with  the  error 
class’s  constructor  and  destructor  func¬ 
tions.  The  constructor  function  is  called 
when  the  object  is  declared,  and  the 


destructor  function  is  called  when  the 
object  goes  out  of  scope. 

if  (chiefs  >  MAXCHIEFS)  ( 
error  errs("Too  many  chiefs"); 


This  OOP  stuff  is  beginning  to  make 
sense.  The  code  in  this  column  may 
have  a  few  mistakes,  but  I’m  just  learn¬ 
ing  C++  myself.  In  the  next  few  months 
I’ll  explore  it  in  more  depth,  and  we’ll 
learn  together. 

Are  People  Object-Oriented? 

For  a  programming  paradigm  to  take 
hold,  it  must  work  like  people  think. 
The  solution  to  a  problem  should  re¬ 
semble  the  problem.  Are  we  object- 
oriented  creatures?  I  think  we  might 
be.  People  know  how  to  do  many  com¬ 
plex  things  but  usually  only  within  the 
context  of  the  objects  involved.  A 
plumber’s  methods  have  meaning  only 
when  considered  in  the  context  of  sinks, 
bathtubs,  and  the  like.  Take  away  an 
understanding  of  the  objects  and  the 
methods  would  be  nonsense. 

So  what  is  more  important  and  de¬ 
serves  more  emphasis,  the  object  or 
the  methods,  the  bathtub  or  the 
plumber’s  tools  and  procedures?  Where 
should  the  perspective  be?  And  what 
should  be  saved? 

With  traditional  FOP,  you  preserve 
general-purpose,  reusable  functions  in 
libraries,  and  you  keep  the  applica¬ 
tions  data  structures  in  header  files. 
The  two  are  not  associated  except  within 
the  context  of  programs  that  tie  them 
together.  The  applications-speciflc  func¬ 
tions  are  generally  not  retained  for  reuse. 
In  OOP  you  can  catalog  the  reusable 
stuff  just  as  with  FOP,  but  you  also 
closely  associate  data-oriented  functions 
with  the  data  structures  as  objects,  and 
you  can  save  these  objects  for  reuse  if 
appropriate. 

So  what  should  be  in  the  library,  the 
functions  or  the  objects?  What  should 
be  designed  to  be  reusable?  Obviously, 
only  those  things  that  are  likely  to  be 
reused  should  be  so  designed,  and  some¬ 
times  it  goes  one  way  and  sometimes 
the  other.  Without  knowing  any  better, 
I  am  drawn  to  C++  because  of  its  sub¬ 
set  ANSI  C.  You  can  go  either  way  even 
within  the  same  program.  Only  time 
will  tell  if  that  is  a  good  idea. 

My  pal  Bill  Chaney  tells  me  to  think 
again;  a  FOP  is  a  dandy,  and  OOPs 
means  a  mistake  has  been  made. 

Book  Report: 

The  C++  Programming  Language 

The  C++  Programming  Language  by 
Bjarne  Stroustrup  tries  a  lot  to  be  the 
K&R  book  of  C++.  It  resembles  the 
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“white  book.”  It  has  the  same  size, 
same  style  and  presentation,  and  (al¬ 
most)  the  same  title.  But  K&R  is  a  well- 
crafted  description  of  C  aimed  at  the 
programmer  who  does  not  yet  know 
the  language.  As  you  read  K&R,  you 
are  led  carefully  through  the  features 
of  the  language  with  well-organized 
examples  and  a  well-designed  sequence 
for  the  presentation  of  information.  The 
C++  book  does  not  measure  up  to  this 
high  standard. 

If  anything  is  going  to  spell  the  de¬ 
mise  of  C++  or  OOP  in  general,  it  is 
that  the  language  and  the  paradigm  are 
or  seem  to  be  difficult  to  describe.  Pro¬ 
grammers  do  not  readily  embrace  some¬ 
thing  that  the  experts  cannot  explain. 
Maybe  it  isn’t  so  difficult;  maybe  no 
one  has  described  them  correctly  yet. 
You  will  hear  that  many  programmers 
have  difficulty  making  the  transition 
from  C  to  C++.  Perhaps  they  are  trying 
to  do  it  by  reading  this  book.  Believe 
me,  Stroustrup’s  book  is  not  the  place 
to  begin. 

Once  it  gets  past  a  brief  description 
of  the  C  subset,  the  book  dives  into 
details  way  too  deep  for  the  newcomer. 
For  example,  it  introduces  classes  with 
a  discussion  of  how  ostream  is  imple¬ 
mented  without  explaining  what  os¬ 
tream  is.  Then  it  sinks  into  an  arcane 
description  of  how  operator  overload¬ 
ing  is  used  to  implement  expressions 
like  A  «  B  «  C  well  before  it  fully 
explains  how  you  can  extend  the 
language  with  operators  for  objects. 
This  book  suffers  from  the  malady  that 
most  treatments  of  OOP  have  —  ab¬ 
struse  examples.  Most  programmers  will 
not  relate  to  the  implementation  of 
stream  input/output  classes  and  ob¬ 
jects  because  they  do  not  do  that 
kind  of  programming.  Most  program¬ 
mers  will  not  associate  with  examples 
that  use  complex  numbers,  because 
relatively  few  real-world  programming 
problems  use  them.  The  book  renames 
C’s  arrays,  calling  them  vectors,  and 
never  explains  that.  Then,  to  further 
confuse  you,  the  discussion  of  vectors 
makes  you  think  that  there  is  a  vector 
class  by  building  one.  Not  until  later 
do  you  learn  that  you  are  being  told 
how  to  use  the  features  of  C++  to 
do  your  own  vector  bounds  checking 
and  not  using  C++’s  unbounded  vec¬ 
tors  at  all.  The  entire  operator  topic 
uses  the  implementation  of  improved 
vectors  as  an  example.  Most  program¬ 
mers  would  not  cozy  up  to  these  exam¬ 
ples  even  if  the  examples  were  well- 
organized  and  -presented  because  most 
programmers  do  not  write  systems  pro¬ 
grams  where  such  techniques  are  ap¬ 
plied.  The  approach  taken  by  this  book 
resembles  the  typical  university  com¬ 


puter  sciences  curriculum,  where  em¬ 
phasis  is  on  language  design  and  com¬ 
piler  development  rather  than  how  and 
why  they  are  used. 

That’s  about  as  far  as  I’ve  gotten  with 
The  C++  Programming  Language.  I’m 
looking  for  another  book. 

My  first  impression  of  C  was  taken 
from  K&R.  The  organization  and  clarity 
of  that  work  engendered  confidence 
in  the  language.  It  was  easy  to  believe 
that  the  language  would  live  up  to  its 
promise;  Dennis  Ritchie,  one  of  the 
coauthors  of  the  book,  designed  the 
language. 

If  the  same  confusion  and  lack  of 
organization  found  in  the  C++  “defini¬ 
tive  reference  and  guide”  is  in  the  lan¬ 


guage  (C++  was  designed  by  Strous- 
trup),  we  are  in  deep  sushi.  First  im¬ 
pressions  die  hard,  but  I  hope  to  be 
wrong.  I  still  believe  that  C++  will  be 
the  next  major  programming  language. 

As  the  work  of  the  ANSI  X3J11  com¬ 
mittee  winds  down,  they  are  consider¬ 
ing  the  standardization  of  C++.  If  this 
undertaking  gets  going,  it  is  a  sure  sign 
that  C++  will  establish  and  maintain  a 
strong  presence  for  a  long  time. 
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The  First  61  Miles 
of  Curves 


Driving  south  from  Carmel,  Cali¬ 
fornia,  along  the  wild,  vertical 
cliffs  of  the  Big  Sur  coastline, 
you  pass  a  sign  saying  “Curves 
Next  67  Miles.”  A  couple  of  hours  and 
67  miles  later,  you  come  to  another  sign 
saying  “Curves  Next  42  Miles.”  I  guess 
some  bureaucrat  figured  that  67  miles’ 
worth  of  bad  news  was  all  your  average 
motorist  could  handle  at  one  time. 

The  drive  through  Big  Sur  is  one  of 
the  most  spectacular  collections  of 
curves  in  the  world.  In  one  respect, 
however,  there’s  nothing  unusual  about 
it.  Nearly  everything  in  nature  consists  of 
curves.  Look  around.  Just  about  the  only 
straight  lines  you  see  are  man-made. 

The  reason  we’ve  concentrated  so 
far  on  straight  lines  in  computer  graph¬ 
ics  is  that  they’re  easy  to  deal  with  and 
easy  to  understand.  However,  if  graph¬ 
ics  is  to  depict  real-world  objects  it  has 
to  draw  curves. 

This  is  a  difficult  subject.  Whole  ca¬ 
reers  in  computer  science  are  devoted 
to  the  investigation  of  curves.  So  I’ll  be 
more  honest  than  that  nameless  bureau¬ 
crat  and  tell  you  up  front  that  there  are 
a  full  109  miles  of  curves  ahead.  How¬ 
ever,  we’re  going  to  take  them  the  same 
way  most  people  travel  through  Big  Sur: 
In  stages,  with  stops  along  the  way. 

We  begin  this  month  with  two  rela¬ 
tively  simple  curves  that  can  be  used 
to  depict  most  rounded  objects.  The 
first  is  the  ellipse,  which  can  also  draw 
a  circle.  The  other  is  the  conic  spline, 
a  remarkably  supple  object  forming  an 
arc.  The  road  through  Big  Sur  can  be 
likened  to  a  connected  string  of  conic 
splines.  In  due  course  later,  we’ll  con¬ 
sider  cubic  and  Bezier  splines,  which 
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are  useful  for  concisely  expressing  com¬ 
plex  curves  in  two  and  three  dimen¬ 
sions.  But  first  let’s  do  the  easier  stuff. 

'Round  and  'Round  We  Go 

Remember  Bresenham?  He’s  the  guy 
we  talked  about  in  March,  who  in¬ 
vented  a  way  to  draw  straight  lines 
efficiently.  Well,  Bresenham  didn’t  stop 
there  to  rest  on  his  laurels.  He  went 


on  to  figure  out  how  to  draw  ellipses 
without  using  floating  point  arithmetic. 
If  you  want  a  good  exposition  of  the 
Bresenham  method,  see  Algorithms  14 
and  15  in  James  Blinn’s  article  “How 
Many  Ways  Can  You  Draw  a  Circle?” 
( DDJ ,  September  1987).  That  article  will 
also  give  you  an  insight  into  the  com¬ 
plexities  of  even  something  as  appar¬ 
ently  simple  as  a  circle. 

The  easiest  way  to  make  a  circle  is 
to  rely  on  classical  trigonometry.  Given 
any  angle,  you  find  the  corresponding 
point  on  the  circle  as  follows: 

•  The  X  is  at  the  cosine  of  the  angle 
times  the  radius,  plus  the  center  X. 

•  The  Y  is  at  the  sine  of  the  angle  times 
the  radius,  plus  the  center  Y. 

This  seems  so  simple  that  one  wonders 
why  circle-making  is  a  big  deal. 

The  problem  is  that  it’s  computation¬ 
ally  intensive.  The  sine  and  cosine  are 
periodic  floating  point  functions  that 
take  a  lot  of  resources  (that  is,  time)  to 
calculate.  It  wouldn’t  matter  much  if 
every  computer  was  equipped  with  float¬ 
ing  point  hardware  such  as  an  ’87  chip. 
However,  few  are,  relying  instead  on  time- 
hungry  floating  point  emulation  in  soft¬ 
ware.  Integer  operations  are  much  faster, 
and  that’s  why  Bresenham  and  others 
have  quested  for  better  methods. 

With  so  many  learned  folks  studying 
the  problem,  it’s  inevitable  that  variants 
on  the  Bresenham  algorithm  have  ap¬ 
peared.  The  one  we  discuss  here  is 
called  the  midpoint  algorithm.  Wilton’s 
PROGRAMMER’S  GUIDE  TO  PC  &  PS/2 
VIDEO  SYSTEMS (1987,  Microsoft  Press) 
devotes  most  of  Chapter  7  to  this  algo¬ 
rithm,  so  I  won’t  go  into  much  depth; 
if  you’re  serious  about  graphics,  get 
this  book. 

In  nature,  an  ellipse  is  a  circle  elon¬ 
gated  in  some  direction.  To  simplify 
matters,  the  Bresenham  algorithm  and 
its  derivatives  impose  a  limit:  An  ellipse 
can  be  elongated  either  horizontally 
or  vertically,  but  not  on  the  diagonal. 
(The  conic  splines  discussed  later  re¬ 
move  this  restriction.)  If  we  can  de¬ 
scribe  an  ellipse  as  a  stretched  circle, 
then  it’s  also  fair  to  say  that  a  circle  is 
an  ellipse  in  which  both  axes  have  the 


same  length.  That’s  why  the  method 
works  for  both  true  circles  and  ellipses, 
and  why  the  terms  are  interchangeable. 

The  midpoint  algorithm  assumes  that 
we  start  at  point  !0,  y)  and  proceed 
through  one  quadrant,  or  90  degrees 
of  angular  motion,  to  point  lx,  0)  (where 
y  is  the  vertical  semiaxis  and  x  is  the 
horizontal).  In  other  words,  it  only  wor¬ 
ries  about  the  upper-right  quadrant  of 
the  ellipse.  Corresponding  points  for 
the  other  three  quadrants  are  found 
by  adding  to  and  subtracting  from  the 
center  coordinates. 

As  the  curve  forms  the  exact  edge 
advances,  moving  among  and  between 
pixel  positions  on  the  raster  display, 
just  like  a  slanting  straight  line.  To  draw 
a  reasonably  accurate  representation, 
then,  it’s  necessary  to  find  out  which 
fixed  pixel  is  closest  to  the  real  curve 
at  any  given  point.  We  could  do  this 
in  the  classic  sine/cosine  method  by 
rounding  the  results  of  the  calculations  . 
To  save  that  overhead,  the  Bresenham 
algorithm  uses  a  decision  variable  called, 
by  convention,  d. 

In  general,  if  d  is  positive,  then  the 
curve  lies  below  the  midpoint  between 
two  vertically  adjacent  pixels,  so  the 
pixel  below  is  selected.  Otherwise  the 
pixel  above  is  closer.  When  the  curve 
has  advanced  through  half  its  arc  (first 
octant)  the  tendency  of  motion  becomes 
more  downward  than  rightward.  Thus 
the  algorithm  switches  its  orientation 
to  select  between  horizontally  adjacent 
pixels.  A  negative  value  for  d  means 
that  the  nearer  pixel  is  outside  the  el¬ 
lipse.  The  algorithm  steps  on  a  pixel-by¬ 
pixel  basis,  assuring  an  unbroken  curve 
on  the  display.  (Gaps  sometimes  occur 
using  the  “pure”  Bresenham  method.) 
The  first  octant  advances  the  X  in  each 
iteration  and  selects  the  nearest  Y.  The 
second  octant  advances  by  Hand  picks 
the  appropriate  X.  The  value  of  d 
changes  each  time  by  a  pair  of  values 
called  dx  and  dy  by  Wilton.  The  el¬ 
lipse ( )  function  implementing  this  al¬ 
gorithm  (Listing  One,  page  171)  refers 
to  them  as  xd  and  yd  to  avoid  conflict 
with  the  virtual  coordinate  functions. 

The  values  of  xd  and  yd,  using  the 
function’s  names,  are  updated  at  each 
step  by  values  that  remain  constant  for 
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(continued  from  page  146) 
the  duration  of  the  call.  These  con¬ 
stants  reflect  the  rate  of  change  in  the 
curve,  taking  into  account  the  tension 
between  the  X  and  Y  semiaxes.  Thus, 
xd  and  yd  maintain  a  running  total  of 
the  effects  of  angular  motion  along  the 
curving  path.  The  value  of  d  is  con¬ 
trolled  by  applying  xd  and  yd,  and  so 
the  sign  of  d  selects  the  nearest  pixel 
to  each  successive  point. 

Because  the  polynomial  constants  of 
angular  motion  are  computed  outside 
the  loop  and  all  values  are  16-  or  32-bit 
integers,  the  midpoint  algorithm  is  effi¬ 
cient  while  drawing  a  smooth,  unbro¬ 
ken,  and  accurate  representation  of  the 
ellipse. 

Want  to  see?  First  compile  ELLIPSE. C 
and  add  it  to  your  copy  of  GRAFIX.L1B 
with  the  command 

LIB  grafix  +ellipse; 

Next,  add  the  two  prototypes  from  List¬ 
ing  Two,  page  171,  to  GRAFIX. H.  And 
then  compile,  link,  and  run  CIRCLES. C 
from  Listing  Three,  page  171.  It  draws 
a  true  circle  and  two  ellipses. 

Just  Partway  'Round,  Thanks 

Graphics  literature  sometimes  explains 
that  the  term  spline  derives  from  the 
loftsman’s  spline,  a  piece  of  thin  flex¬ 
ible  material  used  to  round  inside  edges. 
The  analogy  is  lost  on  me  inasmuch  as 
I  don’t  know  what  a  loftsman  does,  nor 
do  I  care.  A  more  useful  analogy  is  to 
the  fanciful  curlicued  French  curves 
used  by  draftsmen  (which  is  perhaps 
as  meaningless  to  you).  At  any  rate, 
spline  is  a  term  often  used  in  computer 
graphics  to  mean  an  open  curve. 

There  are  several  kinds  of  splines. 
The  simplest  is  the  conic  spline,  so 
called  because  it  exists  inside  a  trian¬ 
gular  outline  (or  “hull”).  Conceptually, 
the  hull  is  a  V-shaped  set  of  three  points. 
The  curve  itself  goes  between  the  two 
end  points  of  the  V.  As  it  crosses  the 
open  space,  the  intersection  of  the  hull’s 
two  sides  —  the  point  of  the  V  —  at¬ 
tracts  the  curve,  causing  it  to  bend  in¬ 
ward.  The  amount  of  curvature  depends 
on  the  depth  of  the  enclosing  cone. 

Figure  1  illustrates  a  couple  of  conic 
splines.  Note  that  the  points  where  the 
curve  meets  the  sides  of  the  cone  are 
called  knots,  and  the  attractor  is  called 
the  control  point.  As  you’ll  see  shortly, 
the  orientation  of  one  of  the  sides 
doesn’t  have  to  be  horizontal  despite 
what  the  drawings  suggest. 

The  curve  in  Figure  la  bends  through 
more  than  90  degrees,  while  that  in 
Figure  lb  falls  somewhat  short  of  a 
quarter-circle.  Nevertheless,  both  curves 
represent  one  quadrant  of  an  ellipse. 


Figure  2  shows  how.  Consequently, 
the  conic  spline  isn’t  really  attracted  to 
its  control  point,  but  is  instead  rotating 
around  the  ellipse’s  center.  In  doing 
so  it  travels  between  the  opposite  cor¬ 
ners  of  a  parallelogram  completed  by 
the  center  and  control  point. 

So,  why  not  just  use  the  midpoint 
algorithm  to  plot  a  conic  spline,  draw¬ 
ing  only  the  affected  quadrant?  Because 
the  ellipses  defining  a  spline  don’t  nec¬ 
essarily  have  vertical  and  horizontal 
axes.  Remember,  Bresenham  imposes 
that  as  a  condition  on  his  ellipses.  We 
could  draw  conic  splines  with  the  mid¬ 
point  method,  but  the  sides  would  al¬ 
ways  have  to  be  at  perpendicular  an¬ 
gles.  Thus,  we  couldn’t  draw  the  curves 
in  Figure  1. 

The  spline  in  Figure  la  illustrates  the 
problem.  Two-thirds  of  the  way  be¬ 
tween  Knots  A  and  B,  the  curve  bends 
beyond  90  degrees  and  begins  moving 
back  in  the  opposite  horizontal  direc¬ 
tion.  It  started  out  going  right,  and  now 
it’s  going  left.  If  we  rotated  the  whole 
thing,  a  similar  problem  would  exist 
with  going  first  up,  then  down,  or  vice 
versa.  The  midpoint  algorithm  simply 
can’t  handle  this  because  it  expects  the 
axes  to  be  orthogonal. 

We  need  a  more  capable  algorithm. 
That’s  what  the  arc()  function  in  ARC.C 
(Listing  Four,  page  172)  provides.  This 
algorithm  uses  fixed  point  arithmetic 
to  approximate  floating  point  without 
the  overhead.  The  fixed  point  values 
are  long  integers  with  a  fractional  value 
in  the  lower  16  bits.  This  accounts  for 
the  left  shifts  when  setting  up  the  con¬ 
trol  values,  and  also  for  the  constant 
HALFPI.  The  arc  sweeps  through  a  quar¬ 
ter-turn,  or  PI/2  radians,  so  we  calcu¬ 
late  HALFPI  as  (3-1415927  /  2)  «  16, 
which  works  out  to  102,944. 


Knot  A  Control  point 


a.  Deep  conic  spline 

Control  point  Knot  A 


Knot  B 


b.  Shallow  conic  spline 

Figure  1:  Examples  of  conic  splines 
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The  whole  idea  of  this  algorithm  is 
somewhat  like  that  of  Bresenham, 
though  it  doesn’t  look  like  it.  The  val¬ 
ues  vx  and  vy  give  offsets  for  the  cur¬ 
rent  point  relative  to  the  center  of  the 
ellipse  ( xO  and  yO).  The  ux  and  uy 
variables  accumulate  angular  motion 
as  the  curve  progresses.  Because  vx, 
vy,  and  ux,  uy  interact  with  each  other, 
in  effect  updating  each  other’s  values 
at  the  bottom  of  the  loop,  the  angular 
motion  to  the  right  (when  drawing  Fig¬ 
ure  la)  gradually  slows  and  eventually 
backtracks. 

Everything  depends  on  the  pixel  den¬ 
sity  variable  called  “den,”  which  pro¬ 
vides  a  power  of  2  by  which  to  multi¬ 
ply  and  divide  the  control  values.  The 
sense  of  this  rests  upon  the  effect  of 
shifting  an  integer.  Every  time  you  shift 
one  bit  to  the  right,  you  divide  by  2. 
Three  shifts  to  the  right  is  division  by 
8,  four  is  division  by  16,  and  so  on. 
Multiplication  by  a  power  of  2  similarly 
occurs  when  shifting  left. 

The  algorithm  draws  a  predictable 
number  of  pixels  depending  on  the 
value  of  den.  When  den  is  10,  it  draws 
804  pixels  between  the  knots.  The  num¬ 
ber  of  pixels  decreases  by  half  each 
time  den  decrements  by  one.  In  com¬ 
puting  the  pixel  density  factor,  then, 
the  algorithm  determines  approximately 
how  far  the  cun/e  has  to  travel,  and 
assigns  the  appropriate  power  of  2  to 
control  its  motion. 

The  exact  number  of  pixels  needed 
to  draw  an  unbroken  curve  depends 
on  the  depth  of  the  cone  and  the  dis¬ 
tance  between  knots.  The  algorithm 
might  attempt  to  write  a  pixel  in  the 
same  position  more  than  once,  so  the 
loop  tracks  the  previous  position  and 
only  allows  a  write  when  the  new  posi¬ 
tion  is  different;  the  comparison  is  com¬ 
putationally  cheaper  than  a  rewrite. 

See,  I  told  you  curves  aren’t  easy.  But 
because  the  conic  algorithm  uses  only 
integers  with  fractional  values  in  the 
lower  16  bits,  it  draws  splines  efficiently. 

Compile  ARC.C,  then  put  it  into  the 
library  with 


a  curve  and  its  enclosing  cone.  The 
curves  are  in  white,  their  hulls  in  red. 

The  next  example,  HANGER.C  in  List¬ 
ing  Six,  page  172,  draws  a  coat  hanger 
to  demonstrate  how  conic  splines  can 
be  joined  with  each  other  and  with 
lines  to  construct  real-world  images. 
The  secret  lies  in  forming  continuous 
joints.  You  do  this  by  placing  one  knot 
and  the  control  point  on  the  same  plane 
as  the  line  that  continues  the  curve, 
and  starting  or  ending  the  line  at  the 
knot.  For  example,  the  bottom  of  the 
hanger  is  on  Y  coordinate  260,  and  its 
right  end  is  at  X=500.  The  right  spline’s 
knot  is  also  at  (500,  260)  and  its  control 
point  similarly  lies  on  Y=260.  The  re¬ 
sult  is  a  smooth  joint;  the  spline  ap¬ 
pears  to  be  a  continuation  of  the  wire 
that  bends  around  to  the  right  shoulder 
of  the  hanger.  The  hook  at  the  top  joins 
four  conic  curves.  In  each  case,  the 
joints  occur  at  coincident  knots  and  the 
control  points  of  any  two  adjacent 
curves  lie  on  the  same  plane  such  that 
a  line  passing  through  them  also  passes 
through  the  common  knot. 

The  final  example,  BALL.C  in  Listing 
Seven,  page  172,  combines  ellipses, 
curves,  and  floodfills  to  form  the  shaded 
3-D  image  of  a  ball  resting  on  its 
shadow.  This  is  a  brute-force  approach 
to  shading,  a  subject  that  still  lies  in  the 
far  distant  future  of  this  column,  but 
the  visual  result  is  the  roughly  the  same. 
The  flow  of  the  program  should  be 
apparent;  the  message  is  that  we  have 
now  reached  the  point  of  being  able 
to  produce  reasonably  good  graphics 
with  the  tools  developed  here. 

Forty-two  more  miles  of  curves  to 
go.  Time  for  a  rest  stop. 

Kent  completed  this  installment  of  his 
“Graphics  Programming”  column 
shortly  before  he  passed  away.  Even 
though  the  series  will  end  with  this 
issue,  wed  like  to  hear  how  you’re  us¬ 
ing  some  of  the  ideas  Kent’s  introduced 
in  this  space.  Drop  us  a  note  about 
your  program  or,  better  yet,  write  an 
article  and  share  your  applications  with 
others.  —  eds 


LIB  grafix  +arc; 

Now  you’re  ready  to  see  some  conic 
splines  in  action. 

The  first  example  is  CONICS.C  in  List¬ 
ing  Five  (page  172).  This  program  viv¬ 
idly  illustrates  the  relationship  between 

Knot  Control  point 


Knot 


DDJ 

(Listings  begin  on  page  171.) 

Vote  for  your  favorite  feature/article. 
Circle  Reader  Service  No.  12. 


Figure  2:  A  conic  spline  is  one  quadrant  of  an  ellipse 
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SJRUCTURED  PROGRAMMING 


Thinking  Big , 
Talking  Small 


There’s  a  definition  of  the  word 
“legendary”  that  I  favor:  Some¬ 
thing  that  everybody  talks  about 
but  which  has  never  had  any  ba¬ 
sis  in  fact.  (The  legendary  Loch  Ness 
monster  comes  to  mind,  as  well  as  that 
legendary  IBM  service  and  support.) 
There’s  a  computer  language  that  comes 
perilously  close  to  being  legendary,  and 
that  language  is  the  (almost-legendary) 
Smalltalk. 

Amidst  the  dusty  stacks  of  computer 
magazines  filling  my  two  walls  of  Hun- 
davad  bookshelves  is  the  October  1980 
issue  of  the  late  and  lamented  Creative 
Computing.  On  the  cover  is  a  Hallow¬ 
een  witch  boarding  her  broomstick, 
cackling  in  a  cartoon  balloon:  “Come 
with  me  on  a  journey  to  the  mysterious 
world  of  Smalltalk!”  Such  is  the  stuff 
of  which  legends  are  made. 

Though  it  tried  gamely,  Creative  Com¬ 
puting  did  little  to  chase  the  smoke 
surrounding  the  language.  At  best,  they 
made  it  sound  like  an  infix  Forth  with 
a  graphics  user  interface,  and  that  comes 
closer  to  the  truth  than  the  PARC  folks 
would  care  to  admit.  The  problem  was 
that  Ted  Nelson  and  the  other  gurus 
of  the  time  were  so  taken  by  the  ivory 
tower  PARC  mystique  and  the  dazzlingly 
precocious  Xerox  graphics  workstations 
that  they  mistook  the  user  interface  for 
the  language,  muttered  things  about 
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animation  scripts  and  notebook-sized 
Dynabooks,  and  never  really  got  around 
to  answering  the  serious  question:  Why 
is  Smalltalk  special? 

It  is  special  because  it  is  the  ultimate 
object-oriented  language.  It  was  easily 
15  years  ahead  of  its  time  in  many 
ways,  and  now  that  a  world  —  scream¬ 
ing  for  Object-Oriented  Anything 
(OOA)  —  is  ready  for  Smalltalk,  the  lan¬ 


guage  revealed  falls  far  short  of  the 
mystical,  magical  otherworldliness  that 
ten  years  of  yearning  have  coated  it 
with.  If  you’ve  never  actually  got  down 
and  hacked  in  Smalltalk,  what  I’d  like 
you  to  do  is  adopt  the  Firesign  Theater 
attitude  toward  it:  Everything  you  know 
is  wrong.  I’m  going  to  try  to  explain 
Smalltalk  from  the  other  direction  — as 
a  perfectly  ordinary  language  within  a 
perfectly  remarkable  framework  —  and 
in  the  process  take  a  stab  at  showing 
you  what  object-oriented  programming 
is  about. 

At  the  Language  Nudist  Park 

You’d  recognize  Smalltalk  if  you  ran 
into  it  at  the  language  nudist  park, 
stripped  bare  of  overlapping  windows 
and  mouse  cursors  and  all  that  other 
folderol.  Here’s  an  assignment  state¬ 
ment  in  Smalltalk: 

fudgeFactor  :=  42. 

Man,  it’s  just  like  back  home  in  Pas- 
calville!  A  numeric  variable  called 
fudgeFactorXak.es  on  a  value  of  42.  The 
period  is  the  local  equivalent  of  Pas¬ 
cal’s  notorious  (if  not  legendary)  semi¬ 
colon,  and  indicates  the  end  of  a  state¬ 
ment.  Like  Pascal  and  C  and  Basic  and 
all  but  the  most  bizarre  languages  like 
Prolog,  a  Smalltalk  program  is  nothing 
more  than  a  series  of  statements  that 
do  something  in  sequence. 

Smalltalk,  it  seems,  has  everything 
all  the  other  languages  have,  and  most 
of  its  parts  look  familiar  in  an  odd, 
polyglot  kind  of  way.  Generating  the 
character  equivalent  of  an  integer  is 
done  this  way: 

68  asCharacter 

Excuse  me,  Mr.  Forth  .  .  .  no,  it  really 
is  Smalltalk,  and  Smalltalk  at  the  lowest 
level  is  just  another  collection  of  rail¬ 


road  diagrams,  like  any  language  you 
could  name.  The  syntax  is  new,  but  the 
concepts  are  utterly  traditional.  If  you’re 
looking  for  a  FOR  loop,  look  no  further: 

4  timesRepeat:  [ 

Turtle 
go:  100; 
turn:  90] 

Smalltalk  sets  off  compound  statements 
within  pairs  of  square  brackets,  just  as 
in  Pascal  we  use  BEGIN/END  and  in  C 
l/l  Saying  4  timesRepeat:  [ /is  just  about 
precisely  equivalent  to  FOR  I  .  =  1  TO 
4  DO  BEGIN  END.  Nothing  magical  or 
legendary  about  that  at  all. 

The  Message  is  the  Medium 

Yet  another  reason  Smalltalk  leans  to¬ 
ward  the  legendary  is  that  the  PARC 
people,  in  designing  it,  made  up  new 
names  for  many  traditional  computer 
science  concepts.  What  in  most  lan¬ 
guages  we'd  call  passing  parameters 
in  Smalltalk  is  called  “passing  messages.” 
The  distinction  makes  sense  once  you’ve 
grokked  the  fullness  of  the  language,  but 
for  newcomers  the  term  message  pass¬ 
ing  promises  more  exotica  than  it  deliv¬ 
ers,  and  the  result  is  gross  confusion. 

Here’s  why:  The  Smalltalk  expres¬ 
sion  mentioned  earlier,  68  asCharacter, 
returns  the  ASCII  character  ‘D.’  How¬ 
ever,  in  the  Smalltalk  jargon,  what  is 
happening  is  that  a  message  called 
asCharacter  is  passed  to  the  value  68. 
The  value  68  responds  by  sending  back 
a  message  consisting  of  the  value  ‘D.’ 
Does  this  confuse  you?  It  sure  con¬ 
fused  the  hell  out  of  me  when  I  first 
encountered  it.  In  Pascal  you’d  pass 
the  value  68  to  the  standard  function 
Chr  (as  in  Chr(68J)  and  the  standard 
function  would  return  the  value  ‘D.’  In 
Smalltalk,  it  seems  like  you  pass  the 
procedure  to  the  parameter,  rather  than 
the  other  way  around.  Bizarre?  No  more 
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so  than  Forth,  and  some  of  my  best 
friends  use  Forth  all  the  time. 

Forth  uses  postfix  notation  (“reverse 
Polish”  —  now  there’s  a  legend  for  you!) 
because  it  serves  the  pathologically  stack- 
centered  architecture  of  the  Forth  lan¬ 
guage.  Smalltalk  uses  its  message-pass¬ 
ing  notation  because  message  passing 
serves  the  architecture  of  Smalltalk, 


You’d  recognize 
Smalltalk  if  you  ran  into 
it  at  the  language 
nudist  park ,  stripped 
bare  of  overlapping 
windows  and  mouse 
cursors  and  all  that 
other folderol 

which,  like  Forth,  differs  from  that  of 
Pascal,  C,  and  Basic.  The  thing  to  re¬ 
member  is  that,  like  Forth,  everything 
about  Smalltalk  makes  perfect  sense  if 
you  take  it  in  the  spirit  of  the  language. 

On  a  statement  level,  then,  Smalltalk 
is  just  a  variation  on  a  common  theme. 
The  uncommon  aspects  of  Smalltalk 
appear  when  it  starts  to  put  its  clothes 
back  on.  The  magic  is  in  the  frame¬ 
work,  not  the  syntax. 

Who's  the  Boss? 

Smalltalk’s  architecture  is  not  easily  de¬ 
scribed  in  the  legendary  25  words  or 
fewer.  I  like  a  challenge,  so  I’ll  try. 
These  are  Smalltalk’s  three  architectural 
principles: 

1.  Data  Is  Boss. 

2.  Data  Knows  What  To  Do. 

3.  Data  Bequeaths  Everything  It  Has 
To  Its  Children. 

First  of  all,  Data  Is  Boss.  To  Pascal  pro¬ 
grammers,  Data  Is  Clay,  and  we  spend 
all  our  time  fiddling  up  code-ish  wid¬ 
gets  to  squeeze,  shape,  spindle,  and 
mangle  that  data.  Smalltalk  moves  data 
to  center  stage.  We  tend  to  think  of  a 
Pascal  program  as  a  series  of  code¬ 
clumps  passing  control  from  one  to 
another.  Data  gets  passed  around  as 
well,  passively  being  beaten  about  the 


ears  and  pounded  into  new  shapes 
and  sizes.  In  a  Smalltalk  program,  the 
active  parties  are  not  sequences  of  code 
but  items  of  data. 

Weird?  Well,  consider  .  .  .  what’s  the 
more  valuable  and  lasting  entity:  The 
act  of  a  dog  barking  or  the  dog  itself? 
As  Confucius  might  say:  There  is  still  a 
dog  even  when  the  dog  is  silent.  Small¬ 
talk  leans  toward  a  philosophy  which 
says:  Mind  the  dog,  and  the  bark  will 
take  care  of  itself. 

When  is  Data  More  than  Data? 

This  is  why  the  statement  68  asCharacter 
is  seen  as  a  message  being  passed  to  a 
data  item.  The  data  item  is  the  active 
party,  because  Data  Knows  What  To 
Do.  Data  in  Smalltalk  is  more  than  data. 
For  every  data  item  in  Smalltalk,  there 
is  a  list  of  actions  that  the  data  item  can 
take.  One  of  the  things  that  a  number 
knows  how  to  do,  for  example,  is  to 
convert  itself  to  an  ASCII  character  and 
pass  the  character  back  as  a  message. 
That’s  what  the  number  6#  does  when 
it  receives  the  message  asCharacter. 
Other  messages  (three  out  of  a  great 
many)  that  an  integer  value  understands, 
and  can  respond  appropriately  to,  are: 

•  factorial  —  The  value  calculates  and 
returns  its  own  factorial 

•  reciprocal  —  The  value  divides  itself 
into  1  and  returns  its  own  reciprocal 

•  negated  —  The  value  subtracts  itself 
from  0  and  returns  its  negated  value 

These  may  look  and  sound  like  proce¬ 
dures  to  you,  and  they  are  in  fact  the 
“code”  portion  of  a  Smalltalk  program. 
But  the  critical  difference  is  this:  They 
are  considered  to  be  part  of  the  integer 
value.  You  cannot  somehow  reach  in 
and  pull  a  procedure  called  factorial 
out  of  an  integer  value.  The  two  are 
welded  together  at  the  hip,  hand  in 
hand  together  for  all  time,  forever  and 
ever  amen. 

This  more-than-data  concept  in  Small¬ 
talk  has  its  own  name,  and  that  name 
is  object.  An  object  in  Smalltalk  is  a 
piece  of  data  and  the  things  it  knows 
how  to  do. 

This  is  only  weird  for  the  first  13 
minutes  you  think  about  it.  (I  timed  it.) 
Why  weld  the  code  to  the  data?  Easy: 
To  keep  the  code  out  of  trouble.  Can 
a  dog  whistle?  Can  a  teakettle  bark? 
No.  Yet  we  Pascal  guys  get  in  trouble 
with  the  compiler  all  the  time,  trying 
to  pass  character  values  to  the  Abs  stan¬ 
dard  function,  trying  to  take  the  cosine 
of  Tme,  things  like  that.  Matching  data 
types  to  code  that  can  legally  manipu¬ 
late  data  of  that  type  is  lots  of  trouble  — 
so  Smalltalk  ends  the  problem  by  glu¬ 
ing  the  two  together. 


Those  actions  an  object  can  take  in 
response  to  messages  are  called  “meth¬ 
ods.”  Every  object  has  its  crisply-de¬ 
fined  suite  of  methods.  And  in  Small¬ 
talk,  everything  (bar  nothing!)  is  an 
object. 

This  is  what  I  was  hinting  at  when  I 
implied  that  Smalltalk  statements  looked 
normal  —  until  they  started  putting  their 
clothes  on.  The  arithmetic  expression 
17+42  looks  the  same  in  Basic,  For¬ 
tran,  Pascal .  .  .  and  Smalltalk.  However, 
through  Smalltalk-colored  glasses,  this 
is  what’s  really  happening:  The  +  mes¬ 
sage  (arithmetic  addition)  is  sent  to  the 
value  17.  Hot  on  the  heels  of  the  + 
message  is  an  argument  —  in  this  case  — 
the  value  42.  The  +  message  tells  1 7, 
“add  yourself  to  the  next  thing  coming 
your  way,  and  return  the  sum.”  The 
next  thing  down  the  pike  is  the  value 
42.  1 7  adds  itself  to  42,  and  sends  the 
value  59  back  out  again. 

The  value  59  is  an  object  too,  So,  if 
you  have  something  like  this: 

(17  +  42)*  3 

Smalltalk  sees  it  as  sending  the  +  mes¬ 
sage  and  the  argument  42  to  the  value 
1 7,  and  then  sending  the  '  (arithmetic 
multiplication)  message  and  the  argu¬ 
ment  3  to  the  value  59,  which  was 
obligingly  returned  by  the  1 7. 

Cynics  might  argue  that  this  is  all 
word  play,  and  that  an  arithmetic  ex¬ 
pression  is  an  arithmetic  expression, 
not  a  bunch  of  numbers  playing  ping- 
pong  with  plus  signs.  And  I’d  have  to 
admit,  it  is  word  play  —  just  as  any 
computer  language  is  an  interplay  of  a 
set  of  symbols,  a  set  of  syntactic  rules, 
and  a  semantic  architecture.  Smalltalk 
uses  standard  symbols  (unlike  some 
truly  weird  languages  like  APL)  and  a 
familiar  set  of  syntactic  rules.  What’s 
different  is  the  semantic  architecture  — 
but  if  you  refuse  to  accept  that  archi¬ 
tecture  at  face  value,  you’re  not  playing 
by  the  rules,  and  I  can  only  advise  you 
to  go  sit  in  the  corner. 

My  Object  All  Sublime 

A  lot  of  Smalltalk’s  reputation  for  weird¬ 
ness  comes  from  this  tendency  to  an¬ 
thropomorphize  things  like  integer  val¬ 
ues.  Objects  know  what  to  do  —  their 
suite  of  methods  is  the  collection  of 
things  they  can  accomplish  —  and  they 
do  what  they  do  in  response  to  mes¬ 
sages  sent  to  them.  One  conjures  up 
visions  of  a  little  purple  number  7  read¬ 
ing  a  telegram  and  doing  some  quick 
pocket  calculator  work  before  sending 
a  sum  back  by  return  wire.  Just  as  we 
sometimes  use  the  metaphor  of  a  stack 
of  china  plates  when  speaking  of  stack- 
oriented  languages  like  Forth,  in  Small- 
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talk  we  use  the  anthropomorphic  zap 
on  inanimate  (nay,  disembodied)  enti¬ 
ties  like  forty-twos  and  screen  windows 
and  text  editors.  It’s  a  mnemonic  de¬ 
vice  to  remind  us  that  data  now  runs 
things  and  takes  action  through  the 
code,  and  not  the  other  way  around. 

The  anthropomorphic  metaphor  was 
stronger  in  the  old  days,  when  lan¬ 
guages  like  Smalltalk  were  called  actor 
languages  because  objects  were  seen 
as  actors,  each  performing  a  script  on 
cue.  The  term  “actor”  has  fallen  into 
disuse  except  in  academe  and  in  the 
title  of  another  object-oriented  language 
that  I’ll  deal  with  in  a  future  column. 

No,  the  term  at  the  center  of  the 
maelstrom  these  days  is  object.  An  ob¬ 
ject  is  the  same  concept  in  Smalltalk, 
Actor,  C++,  or  the  new  Quick  Pascal 
and  Turbo  Pascal  5  5:  A  data  structure 
consisting  of  some  number  of  fields 
(rather  like  the  fields  of  a  record)  bound 
up  with  a  suite  of  procedures  that  act 
on  or  with  those  fields  in  performing 
the  work  that  the  object  must  accom¬ 
plish. 

Bugs  Sealed  in  Amber 

This  welding  together  of  code  and  data 
is  called  “encapsulation.”  In  Smalltalk 
the  term  is  quite  literal:  An  object’s 
fields  (called  “instance  variables”  in  Small¬ 
talk  jargon)  are  so  thoroughly  encapsu¬ 
lated  within  the  object  that  other  ob¬ 
jects  cannot  directly  perceive  them.  The 
closest  familiar  analog  is  the  implemen¬ 
tation  section  of  a  Pascal  unit,  where 
data  can  be  defined  that  cannot  be 
perceived  from  outside  the  unit,  but 
only  accessed  by  the  code  contained 
in  the  unit. 

Smalltalk  enforces  this  as  strictly  as 
Pascal  units  do.  Only  an  object’s  meth¬ 
ods  may  even  know  the  names  of  an 
object’s  instance  variables.  To  read  the 
value  of  some  instance  variable,  a 
method  must  be  defined  to  return  a 
copy  of  that  instance  variable,  and  a 
message  must  be  sent  to  the  object 
requesting  a  copy  of  that  variable.  No 
method,  no  copy,  no  knowledge  that 
the  instance  variable  even  exists! 

Now  that’s  encapsulation. 

Other  object-oriented  languages,  as 
I’ll  explain  in  later  columns,  do  not 
erect  quite  such  impenetrable  walls 
around  their  object’s  inner  fields.  The 
reason  is  pretty  simple:  Speed.  Small¬ 
talk  imposes  a  tremendous  amount  of 
overhead  in  enforcing  encapsulation. 
The  benefits  are  significant  —  side  ef¬ 
fects  and  “sneak  paths”  almost  literally 
cannot  exist  in  Smalltalk  code  —  but 
the  costs  in  performance  are  high. 

Encapsulation  in  Smalltalk  is  rather 
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like  potting  instance  variables  in  mil- 
spec  black  epoxy  resin.  You  get  into 
and  out  of  the  module  through  its  ter¬ 
minal  strip,  period.  C++  and  Object 
Pascal  do  something  a  little  more  like 
blister-packaging  under  transparent  plas¬ 
tic:  The  goodies  can  be  seen  and  felt 
by  the  consumer,  but  direct  manipula¬ 
tion  is  discouraged. 

Family  Resemblances 

Encapsulation  is  a  nice  idea,  but  there’s 
nothing  in  it  (at  least  in  the  C++/Object 
Pascal  sense)  that  can’t  be  accomplished 
by  traditional  C  implementations  and 
good  extended  Pascals  like  Turbo  Pas¬ 
cal.  Code  and  data  can  be  combined 
in  Turbo  Pascal  just  by  placing  proce¬ 
dural  types  as  fields  in  a  record  along 
with  data  fields.  This  works  well,  and 
I’ve  used  it  as  a  means  of  organizing 
programs  in  the  past. 

What  really  sets  Smalltalk  and  other 
true  object-oriented  languages  apart 
from  the  old  school  is  that  third  Small¬ 
talk  architectural  principle:  Data  Be¬ 
queaths  Everything  It  Has  To  Its  Chil¬ 
dren.  This  is  the  notion  of  inheritance, 
and  I’d  call  it  the  single,  most  important 
aspect  of  object-oriented  programming. 

Pascal  has  something  a  little  like  in¬ 
heritance.  When  you  want  to  limit  a 
data  type  to  some  subset  of  the  values 
of  another  type,  you  can  define  a 
subrange: 

TYPE 

CharCodes  =  0..255; 

Here,  we’ve  defined  a  subrange  of  type 
Integer  that  embraces  only  the  first  256 
integer  values.  Values  of  type  CbarCode, 
however,  really  are  integers,  in  that 
they  may  take  place  in  integer  calcula¬ 
tions  and  be  passed  as  actual  parame¬ 
ters  in  formal  parameters  defined  as 


This  more-than-data 
concept  in  Smalltalk 
has  its  own  name, 
and  that  name  is 
object 


Integer.  CbarCode  variables  inherit  their 
integer-ness  from  type  Integer,  while 
taking  on  a  new  characteristic  specific 
to  type  CbarCode:  The  limiting  of  val¬ 
ues  to  those  between  0  and  255. 


Now,  broaden  this  notion  by  an  or¬ 
der  of  magnitude  and  you’ll  begin  to 
get  the  idea.  A  Smalltalk  object  can 
have  child  objects  that  inherit  every¬ 
thing  the  parent  object  has.  Typically, 
however,  child  objects  either  add  to  or 
somehow  modify  the  instance  variables 
or  methods  of  the  parent  objects.  You 
literally  write  code  in  Smalltalk  by  choos¬ 
ing  an  existing  object  or  objects  as  the 
foundation  of  your  application  and  cre¬ 
ating  child  objects  that  modify  the  par¬ 
ent  objects  in  a  way  that  gets  your 
work  done. 

Where  Pascal  has  data  types,  Small¬ 
talk  has  object  classes,  and  inheritance 
works  on  classes  rather  than  on  indi¬ 
vidual  objects.  The  real  work  of  Small¬ 
talk  programming  lies  in  defining  new 
classes  and  writing  their  methods.  A 
new  class  defined  on  the  foundation 
of  an  existing  class  is  called  “a  sub¬ 
class;”  the  class  from  which  a  subclass 
is  defined  is  the  subclass’s  “superclass.” 

A  class,  like  a  data  type  in  Pascal,  is 
a  template.  You  create  Smalltalk  ob¬ 
jects  by  grabbing  a  class  template  and 
whacking  out  a  new  instance  of  that 
object  class.  That’s  Pascal-think, 
though  —  in  keeping  with  Smalltalk’s 
anthropomorphic  metaphor,  it’s  more 
correct  to  say  that  new  instances  are 
created  by  sending  a  message  to  the 
class  in  question,  requesting  that  it  cre¬ 
ate  a  new  instance  of  itself.  Poof!  The 
new  instance  happens. 

Inheritance  allows  a  second-level  struc¬ 
ture  to  be  imposed  on  a  program.  Ob¬ 
jects  themselves  are  structures,  and  ob¬ 
ject  classes  are  related  to  one  another 
within  a  structurerof-structures,  called 
“an  object  class  hierarchy.”  A  portion 
(a  small  portion)  of  the  Smalltalk  object 
class  hierarchy  is  shown  in  Figure  1. 
At  the  top  of  the  tree  is  the  class  Object. 
Everything  in  Smalltalk  is  descended 
from  Object. 

One  such  something  is  Magnitude, 
including  all  objects  that  may  take  val¬ 
ues  that  may  be  equal  to,  greater  than, 
or  less  than  other  values  of  a  similar 
class.  The  children  of  Magnitude  in¬ 
clude  characters,  numbers,  times,  and 
dates. 

Distributed  Functionality 

This  is  all  very  handy  for  showing  rela¬ 
tionships  among  classes,  but  what  is 
actually  handed  down  through  the  hier¬ 
archy?  The  answer  is  object  behavior; 
primarily  methods  that  dictate  what  an 
object  may  do.  “Object  behavior  is  dis¬ 
tributed  throughout  the  object  hierarchy 
at  appropriate  levels.”  This  is  a  subtle, 
sneaky  concept  that  won’t  necessarily 
make  the  lights  come  on  until  you’ve 
done  some  work  in  Smalltalk.  General¬ 
ized  behavior  is  defined  early  on  in  the 
hierarchy,  up  near  the  top.  Objects  mod- 
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ify  the  behavior  of  their  parent  classes 
as  they  need  to,  but  modifying  only 
what  they  need  to,  leaving  general  be¬ 
havior  intact  where  it  is  still  valid. 

As  an  example,  consider  Magnitude. 
Its  methods  define  ordering  and  com¬ 
paring  functions  that  embrace  anything 
that  can  be  said  to  take  on  values  that 
may  be  greater  than  or  less  than  one 
another.  One  date  or  time  can  be  greater 
than  another,  as  can  one  number.  The 
general  behavior  that  all  magnitudes 
can  share  is  defined  for  class  Magni¬ 
tude.  Behavior  specific  to  dates  or  times 
is  defined  within  class  Date  and  Time. 


Magnitude 

Association 

Character 

Date 

Number 

Floater 

Fraction 

Integer 

LargeNegativelnteger 
LargePositivel  nteger 
Smalllnteger 

Time 


Figure  1:  A  portion  of  Smalltalk/V’s 
class  hierarchy 

Numeric  functions  such  as  reciprocal, 
cosine,  tangent,  and  so  on  would  be 
meaningless  as  applied  to  time  or  date 
values,  so  they  are  defined  in  class  Num¬ 
ber  and  inherited  by  the  different  nu¬ 
meric  classes  such  as  Float  and  Integer. 

The  idea  is  not  to  duplicate  any  code 
needlessly.  Internally,  Smalltalk  looks 
a  lot  like  a  threaded-code  Forth  system. 
Methods  perform  specific  behavior,  and 
then  call  parent  methods  to  perform 
more  general  behavior,  after  which  the 
parent  methods  call  their  parent  meth¬ 
ods  to  perform  even  more  general  be¬ 
havior,  and  so  on.  As  with  Forth,  there 
is  a  kernel  of  primitive  methods  written 
in  assembly  language  upon  which  the 
rest  of  the  language  is  built. 

There  are  other,  even  more  subtle 
consequences  of  inheritance  such  as 
polymorphism,  which  may  in  fact  re¬ 
quire  a  column  all  to  itself.  I'll  come 
back  to  inheritance  again  and  again;  it 
is  the  backbone  of  object  orientation 
and  has  more  wrinkles  than  a  cotton 
shirt  in  a  hot  dryer. 

Talking  Small 

With  very  little  fanfare,  a  product  called 
Methods  appeared  in  1985  from  Jim 
Anderson’s  Digitalk  Inc.  in  L.A.  Meth¬ 
ods  was,  remarkably  enough,  a  text- 
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based  implementation  of  Xerox’s  Small¬ 
talk-80  specification.  It  may  have  been 
the  first  low-cost  object-oriented  lan¬ 
guage  to  ever  appear  on  the  PC,  and 
not  one  programmer  in  a  hundred  had 
ever  heard  of  it. 

Methods  grew  into  graphics  over¬ 
shoes  and  became  Smalltalk/V  a  cou¬ 
ple  of  years  later.  (The  V  is  a  vee,  not 
a  five  .  .  .  )  At  $99  it  remains  the  least 
expensive  object-oriented  language  of 
which  I  am  aware.  (Rumor  holds  that 
Quick  Pascal  will  come  in  at  $99,  but  I 
have  no  hard  information  on  it  yet.) 
The  Smalltalk/V  manual  is  excellent, 
and  I  think  that  the  product  represents 
one  of  the  best  ways  to  come  to  under¬ 
stand  object-oriented  programming.  It’s 
graphics-based,  and  the  demo  programs 
are  very  visual  and  lots  of  fun,  with 
animated  dogs  (of  which  I  am  inordi¬ 
nately  fond)  bouncing  around  the 
screen  in  response  to  messages  sent 
from  the  keyboard. 

The  Smalltalk/V  product  is  86-ge- 
neric  and  runs  on  any  DOS  machine 
with  CGA,  EGA,  VGA,  or  Hercules  graph¬ 
ics.  Digitalk  also  has  a  more  advanced 
Smalltalk  product  for  286  and  386  ma¬ 
chines,  Smalltalk/V286,  which  provides 
better  performance  and  a  richer  feature 
set  (including  much  more  room  to 
work)  and  sells  for  $199.  A  Mac  version 
is  available,  and  provides  an  intriguing 
portability  path  between  the  two  hos¬ 
tile  camps. 

The  only  other  DOS-based  Smalltalk 
that  I  know  of  is  offered  by  ParcPlace 
Systems,  a  Xerox  spinoff  that  is  finally 
making  some  effort  to  put  a  Xerox  Small¬ 
talk  implementation  in  the  hands  of  the 
DOS  developer.  The  Smalltalk-80  De¬ 
velopment  System  runs  steep  ($995) 
and  requires  a  386.  In  fairness,  I  must 
admit  that  I’ve  been  using  Smalltalk/V 
for  two  years  and  the  ParcPlace  prod¬ 
uct  for  only  about  a  month,  so  I’ll  re¬ 
frain  from  detailed  comparisons.  The 
price  alone  (and  I  feel  price  is  impor¬ 
tant)  takes  the  ParcPlace  product  down 
a  few  notches  in  my  esteem.  It’s  good, 
but  it’s  not  a  thousand  dollars  good.  It’s 
a  workstation  product,  ported  from 
Unix,  that  has  to  stoop  a  little  to  make 
it  under  DOS,  whereas  Smalltalk/V  was 
designed  from  the  ground  up  to  run  in 
a  DOS  environment. 

On  the  other  hand,  for  those  who 
care,  Smalltalk-80  is  the  Real  Thing, 
born  out  of  the  primordial  soup  that 
Xerox  continually  cooks  but  rarely  al¬ 
lows  others  to  taste.  Its  adherence  to 
the  Smalltalk-80  books  (see  product 
box)  is  closer  than  that  of  Smalltalk/V, 
and  in  fact  ParcPlace  considers  those 
books  its  "real”  user  documentation. 


(The  3-ring  binder  document,  sold  with 
the  product,  is  reference-oriented,  heav¬ 
ily  technical,  and  fragmented.) 

If  you  want  a  taste  of  Smalltalk,  or  a 
taste  of  OOP,  pick  up  Smalltalk/V.  It’s 
cheap  and  it  works  like  a  charm.  The 
286  product  is  there  if  you  want  more 
room  and  more  speed.  I’m  hoping  (but 
not  expecting)  that  ParcPlace  will  port 
Smalltalk-80  to  Presentation  Manager 
soon,  at  which  point  the  price  becomes 
less  of  an  issue.  Anything  that  manages 
the  complexity  of  an  API  like  PM’s  is 
valuable,  and  for  PM  development  Small¬ 
talk-80  would  almost  certainly  be  worth 
the  considerable  price. 

Those  Legendary  Smalltalk  Books 

Smalltalk  is  an  anomaly  in  that  it  had 
superb  documentation  on  the  market 
long  before  there  was  an  implementa¬ 
tion  that  anyone  could  buy.  A  series  of 
three  books  from  Addison-Wesley  ap¬ 
peared  in  the  early  1980s,  and  two  of 
the  three  are  required  reading  for  any¬ 
one  interested  in  Smalltalk.  The  first, 
Smalltalk-80:  The  Language  and  its  Im¬ 
plementation  is  the  “white  book”  for 
Smalltalk,  written  by  Adele  Goldberg 
and  David  Robson.  Beautiful,  interest¬ 
ing,  literate,  and  huge,  the  book  de¬ 
fines  the  language  and  puts  you  on  a 
sound  theoretical  footing.  The  other 
book,  Smalltalk-80:  The  Interactive  Pro¬ 
gramming  Environment ,  by  Adele  Gold¬ 
berg,  describes  the  standard  Smalltalk- 
80  environment  implemented  com¬ 
pletely  by  the  ParcPlace  product  and 
closely  by  Digitalk’s.  It’s  about  browsers 
and  editors  and  form  tools,  and  is  es¬ 
sential  if  you  intend  to  work  in  the 
language.  The  Goldberg/Robson  text, 
on  the  other  hand,  is  sufficient  if  you’re 
interested  only  in  familiarizing  yourself 
with  the  language’s  principles. 

A  third  book,  Smalltalk-80:  Bits  of  His¬ 
tory,  Words  of  Advice,  by  Glenn  Krasner, 
is  meta-Smalltalk,  that  is,  Smalltalk  about 
Smalltalk.  It  provides  some  fascinating 
history  about  the  origins  of  the  language, 
and  liberal  doses  of  hacker-heavy  lore 
on  how  to  bring  up  your  very  own 
implementation  —  which  is  not  some¬ 
thing  I  would  try  to  do  in  ten  thousand 
years.  The  book  is  notable  for  its  photo 
of  the  PARC  NoteTaker  machine,  which 
was  a  256K  8086-based  spitting  image 
of  the  Osborne  1,  in  regular  use  in 
1978.  Xerox  really  did  invent  and  throw 
away  the  personal  computer .  .  .  over 
and  over  and  over  again. 

Addison-Wesley  has  since  published 
a  few  additional  Smalltalk  texts,  but 
none  of  them  come  close  to  any  of 
these  three  in  quality  or  completeness. 
Highly  recommended. 
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The  Downside 

There’s  a  lot  more  to  say  about  Small¬ 
talk,  and  I’ll  touch  on  it  from  time  to 
time  in  these  columns.  I  like  the  lan¬ 
guage  a  lot,  and  I  credit  it  with  prepar¬ 
ing  me  technically  for  the  arrival  of  this 
crowd  of  OOP  steamships  that  I  cata¬ 
loged  last  issue. 

On  the  other  hand,  Smalltalk  will 
probably  never  cross  the  line  to  be¬ 
come  a  mainstream  language,  as  the 
weavers  of  its  legend  have  been  harp¬ 
ing  for  many  years.  The  reason  is  purely 
practical:  Smalltalk  is  by  nature  an  in¬ 
terpreter,  and  unless  everybody  has  the 
interpreter,  the  grass-roots  critical  mass 
of  support  among  recreational  hackers 
and  part-time  programmers  just  won’t 
be  there.  IBM  put  Basic  on  the  map  by 
throwing  a  solid  interpreter  in  the  box 
with  every  machine  they  sold.  Had  they 
done  that  with  Smalltalk,  Smalltalk  might 
be  where  Basic  is  today,  or  close. 

Unfortunately,  it’s  tough  to  write  a 
Smalltalk,  just  as  it’s  fairly  easy  to  write 
a  Basic.  Furthermore,  Smalltalk  is  slug¬ 
gish  on  8088  machines,  in  part  because 
of  its  interpreted  nature,  but  mostly 
because  it  is  inescapably  graphics- 
based.  Digitalk  might  have  done  well 
to  preserve  their  Methods  product  in 
dry  ice  for  the  current  OOP  craze  as  a 
text-based  $49  loss-leader  to  get  peo¬ 


ple  knowledgeable  about  OOPs  in  gen¬ 
eral  and  Smalltalk  in  particular.  (You 
listening,  Jim?)  Given  a  $99  price  and 
some  superb  documentation  from  Ad- 
dison-Wesley,  Smalltalk/V  is  perhaps 
the  best  current  environment  to  learn 
OOP  principles  .  .  .  but  to  apply  those 
principles  broadly  you’re  going  to  have 
to  move  to  a  mass  market  language  like 
Turbo  Pascal. 

Smalltalk  does  well  as  a  prototyping 
tool,  rather  like  a  thinking  man’s  Dan 
Bricklin  for  graphics  apps.  And  if  you’ve 
got  a  fast  machine  and  you’re  in  a 
position  to  work  entirely  within  the 
Smalltalk  environment,  you  can  create 
a  lot  of  powerful  tools  quickly.  Still,  a 
mainstream  language  it  isn’t,  and  I  cau¬ 
tion  those  of  you  who  have  been  daz¬ 
zled  by  the  legend  not  to  expect  effort- 
free  programming.  Smalltalk  is  a  com¬ 
puter  language,  really.  Tools  is  tools. 
The  magic,  if  anywhere,  is  in  you. 
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GRAPHICS  PROGRAMMING 


Listing  One  (Text  begins  on  page  146.) 

/*  ELLIPSE. C:  Midpoint  algorithm  for  drawing  an  ellipse  */ 

/*  Based  on  Wilton's  "VIDEO  SYSTEMS,"  pp  230-231  */ 

/*  For  inclusion  in  GRAFIX.LIB  */ 

/*  K.  Porter,  DDJ  Graphics  Programming  Column,  8/89  */ 

♦include  "grafix.h" 

void  far  ellipse  (int  cx,  int  cy,  /*  center  x,  y  */ 

int  horiz_rad,  int  vert_rad)  /*  radii  ("semi-axes")  */ 

{ 

int  x  =  0,  y  =  vert_rad;  /*  starting  coords  for  curve  */ 

long  asq  =  (long)  horiz_rad  *  horiz_rad;  /*  aA2  */ 

long  a2sq  =  asq  +  asq;  /*  2aA2  */ 

long  bsq  =  (long)  vert_rad  *  vert_rad;  /*  bA2  */ 

long  b2sq  =  bsq  +  bsq;  /*  2bA2  */ 

long  d,  xd,  yd;  /*  control  values  */ 

/*  Initialize  control  values  */ 

d  =  bsq  -  asq  *  vert_rad  +  asq  /  4L;  /*  bA2  -  aA2b  +  aA2/4  */ 

xd  =  0L; 


) 

— y;  /*  next  vertical  point  */ 

yd  -=  a2sq;  /*  update  control  values  */ 

d  +=  asq  -  yd; 

) 

}  /. - */ 


End  listing  One 

Listing  Two 

Add  these  entries  to  your  copy  of  GRAFIX.H 

/*  From  August  '89  */ 

/* - */ 


yd  =  a2sq  *  vert_rad; 

/*  Loop  to  draw  first  half  of  quadrant 
while  (xd  <  yd)  { 

draw_point  (cx+x,  cy+y) ; 
draw_point  (cx-x,  cy+y) ; 
draw_point  (cx+x,  cy-y) ; 
draw_point  (cx-x,  cy-y) ; 
if  (d  >  0L)  {  /*  if  neari 

— y; 

yd  -=  a2sq; 
d  -=  yd; 

) 

++x; 

xd  +=  b2sq; 
d  +=  bsq  +  xd; 


/*  Loop  to  draw  second  half  of  quadrant  */ 
d  +=  (3L  *  (asq-bsq)  /  2L  -  (xd+yd))  /  2L; 
while  (y  >=  0)  ( 

draw_point  (cx+x,  cy+y);  /*  si 

drawjpoint  (cx-x,  cy+y); 
draw_point  (cx+x,  cy-y) ; 
draw_point  (cx-x,  cy-y) ; 


void  far  ellipse 

(int  cx,  int  cy, 
int  horiz_rad,  int  vert_rad) ; 


/*  draw  ellipse  */ 
/*  at  center  x,  y  */ 
/*  radii  (semi-axes)  */ 


set  pixels  in  all  quadrants 


if  nearest  pixel  is  toward  the  center  */ 
/*  move  toward  center  */ 
/*  update  control  values  */ 


void  far  arc  (int  xl,  int  yl,  int  x2,  int  y2,  int  xc,  int  yc) ; 

/*  draw  conic  spline,  where  knots  are  at  xl,  yl  and  */ 
/*  and  x2,  y2,  control  point  is  at  xc,  yc  */ 


End  Listing  Two 


/*  next  horiz  point 
update  control  values 


/*  do  until  y  =  0  */ 
set  pixels  in  all  quadrants  */ 


Listing  Three 


if  (d  <  0L)  { 
++x; 

xd  +-  b2sq; 
d  +=  xd; 


if  nearest  pixel  is  outside  ellipse 
/*  move  away  from  center 
/*  update  control  values 


/*  CIRCLES. C:  Draws  several  ellipses  to  demo  ellipseO  function  */ 
/*  K.  Porter,  DDJ  Graphics  Programming  Column,  Aug  '89  */ 

♦include  <conio.h> 

♦include  "grafix.h" 

void  main  () 

{ 

if  (init_video  (EGA))  { 

setcoords  (-400,  300,  400,  -300); 


(continued  on  page  1 72) 
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GRAPHICS  PROGRAMMING 


Listing  Three  (Listing  continued,  text  begins  on  page  146.) 

I*  draw  a  true  circle  in  upper  center  of  screen  */ 
ellipse  (dx(0),  dy(100),  dxunits  (150),  dyunits  (150)); 

/*  tall  skinny  ellipse  to  left  */ 

set_colorl  (13);  /*  light  magenta  */ 

ellipse  (dx(-300),  dy(0),  dxunits  (50),  dyunits  (250)); 

/*  short  fat  ellipse  lower  right  */ 

set_colorl  (10);  /*  light  green  */ 

ellipse  (dx(150),  dy(-200),  dxunits  (200),  dyunits  (30)); 

/*  hold  for  keypress,  then  quit  */ 
getch  ( ) ; 

) 


End  Listing  Three 


Listing  Four 

/*  ARC.C:  Draws  a  conic  spline  using  fixed  point  math  */ 

/*  Knots  are  at  xl,  yl  and  x2,  y2,  control  pt  at  xc,  yc  */ 

/*  For  inclusion  in  GRAFIX.LIB  */ 

/*  K.  Porter,  DDJ  Graphics  Programming  Column,  Aug  '89  */ 

•include  "grafix.h" 

♦include  <math.h> 

♦define  HALFPI  102944L  /*  fixed-point  PI/2  */ 

void  far  arc  (int  xl,  int  yl,  int  x2,  int  y2,  int  xc,  int  yc) 

{ 

int  i,  x,  y,  prevx  =  -1,  prevy  =  -1; 

int  delta_x,  delta_y,  delta_t,  dt  =  804,  den  =  10; 

long  vx,  vy,  ux,  uy,  xO,  yO; 

/*  fixed-point  control  values  for  this  arc  */ 

vx  =  (long) (xc  -  x2)  «  16;  /*  distance  to  start  */ 

vy  =  (long) (yc  -  y2)  «  16; 

ux  =  (long) (xc  -  xl)  «  16;  /*  current  point  adjustment  factor  */ 

uy  =  (long) (yc  -  yl)  «  16; 

xO  =  ((long)xl  «  16)  -  vx;  /*  center  of  arc  */ 

yO  =  ((long)yl  «  16)  -  vy; 


/*  acute  conic  in  the  center  */ 
set_colorl  (12); 
draw_line  (200,  330,  370,  40); 
draw_line  (340,  200,  370,  40); 
set_colorl  (15) ; 

arc  (200,  330,  340,  200,  370,  40); 


/*  wait  for  keypress  and  quit  */ 
getch () ; 


End  Listing  Five 


Listing  Six 

/*  HANGER. C:  Draws  a  coat  hanger  with  lines  and  conic  splines  */ 
/*  K.  Porter,  DDJ  Graphics  Programming  Column,  Aug  '89  */ 

♦include  <conio.h> 

♦include  "grafix.h" 

void  main  () 

{ 

if  (init_video  (EGA))  ( 

/*  draw  body  of  hanger  */ 
draw_line  (320,  180,  140,  240); 
arc  (140,  240,  140,  260,  80,  260); 
draw_line  (140,  260,  500,  260); 
arc  (500,  260,  500,  240,  560,  260); 
draw_line  (500,  240,  320,  180); 

/*  draw  hook  at  top  */ 
arc  (320,  180,  310,  160,  320,  168); 

arc  (310,  160,  300,  140,  300,  154); 

arc  (300,  140,  320,  120,  300,  120); 

arc  (320,  120,  340,  140,  340,  120); 

/*  wait  for  keypress  and  quit  */ 
getch () ; 

) 

) 


/*  left  top  */ 
/*  left  end  */ 
/*  bottom  */ 

/*  right  end  */ 
/*  right  top  */ 


End  Listing  Six 


/*  compute  pixel  density  factor  (2Aden)  */ 
delta_x  =  (labs  (vx)  +  labs  (ux))  »  16; 
delta_y  =  (labs  (vy)  +  labs  (uy))  »  16; 
delta_t  =  delta_x  +  delta_y; 
while  (dt  >  delta_t)  { 
dt  /=  2; 

— den; 

} 


Listing  Seven 

/*  BALL.C:  Ball  throwing  a  shadow  */ 


for  (i  -  (int) ( (HALFPI  «  den)  »  16);  i 
x  =  (int) ( (xO  +  vx)  »  16); 
y  =  ( int ) ( (yO  +  vy)  »  16); 
if  ( (x  ! =  prevx)  I!  (y  !=  prevy))  / 
draw_point  (x,  y) ; 
prevx  =  x; 
prevy  =  y; 
ux  -=  vx  »  den; 
uy  -=  vy  »  den; 
vx  +=  ux  »  den; 
vy  +=  uy  »  den; 

J 

} 


Listing  Five 


>=  0;  — i)  ( 

/*  current  position  */ 

if  not  same  as  last  point  */ 
/*  draw  new  point  */ 
/*  remember  this  position  */ 

/*  advance  arc  */ 
/*  division  by  2Aden  */ 


End  Listing  Four 


♦include  "grafix.h" 

•include  <conio.h> 

void  main  () 

( 

if  (init_video  (EGA) )  ( 

setcoords  (-320,  240,  319,  -239); 

/*  Draw  the  backdrop  in  dark  blue  */ 
set_colorl  (1); 
f ill_rect  (0,  0,  639,  150); 

/*  Draw  the  floor  in  light  blue  */ 
set_colorl  (9); 
f ill_rect  (0,  150,  639,  199); 

/*  Create  shadow  on  floor  */ 
set_colorl  (8);  /*  dark  gray  */ 

ellipse  (dx(0),  dy(-160),  160,  25); 
setfillborder  (8); 
floodfill  (dx(0),  dy (-130) ) ; 


/*  CONICS. C:  Draws  several  conic  splines  and  their  enclosing  hulls  */ 
/*  K.  Porter,  DDJ  Graphics  Programming  Column,  Aug  '89  */ 


/*  Draw  the  ball  */ 

set_colorl  (7);  /*  light  gray  */ 

ellipse  (dx(0),  dy(0),  dxunits  (150),  dyunits  (150)); 


♦include  <conio.h> 
♦include  "grafix.h" 

void  main  () 


/*  Shade  the  ball  underneath  */ 

arc  (dx (-150) ,  dy(0),  dx(150),  dy(0),  dx(0),  dy (-50) ) ; 
setfillborder  (7); 
floodfill  (dx(0),  dy(-25)); 


if  (init_video  (EGA))  ( 

/*  Fig.  la  */ 

set_colorl  (12);  /*  red  hull  */ 

draw_line  {  5,  20,  250,  20); 
draw_line  (50,  180,  250,  20); 
set_colorl  (15);  /*  white  curve  */ 

arc  (5,  20,  50,  180,  250,  20); 


/*  Shade  the  ball  white  on  top  */ 

set_colorl  (15); 

floodfill  (dx (0) ,  dy  (145)); 

/*  Hold  for  keypress  and  quit  */ 
getch () ; 


/*  Fig.  lb  */ 

set_colorl  (12);  /*  red  hull  */ 

draw_line  (630,  20,  520,  20); 
draw_line  (470,  120,  520,  20); 
set_colorl  (15);  /*  white  curve  */ 

arc  (630,  20,  470,  120,  520,  20); 


End  Listings 
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(continued  from  page  12) 
issue.  Bruce  was  concerned  with  con¬ 
verting  Rob  Moore’s  “Mapping  MS- 
DOS  Memory  Allocation"  (November, 
1988)  program  from  Turbo  C  to  Micro¬ 
soft  C.  I  have  a  few  suggestions  that 
may  help  Bruce  in  this  process. 

1.  Use  pragmas  to  pack  the  MCB 
structure: 

^pragma  pack(l) 
struct  MCB 
( 

char  chain; 

unsigned  pid; 
unsigned  psize; 
char  fillfl  1]; 

1; 

typedef  struct  MCB  huge  ‘PTRMCB; 
^pragma  pack( ) 

The  first  pack  pragma  tells  the  com¬ 
piler  to  perform  byte  alignment  on  any 
following  structures.  The  second  pack 
pragma  tells  the  compiler  to  default 
back  to  word  alignment. 

2.  Use  the  FP_SEG  and  FP_OFF  mac¬ 
ros  found  in  <dos.h>  instead  of  MK_FP: 
in  Turbo  C: 

/*  far  pointer  to  segment  address/ 
/of  first  MCB  *  unsigned  far 

‘segmptr;/ 

/*  get  pointer  to  segment  address 
of  first  MCB*/ 
segmptr  =  MK_FP(sregs.es, 

regs.x.bx-2); 

/*  get  and  return  pointer  to 

first  MCB  */ 

return  MK_FP(*segmptr,  0); 
in  Microsoft  C: 

/*  far  pointer  to  segment  address  of 
first  MCB  */ 

unsigned  far  *segmptr; 

/*  get  pointer  to  segment  address 
of  first  MCB  7 

FP_SEG(segmptr)  =  sregs.es; 
FP_OFF(segmptr)  =  regs.x.bx-2; 

/*  get  pointer  to  first  MCB  */ 
FP_SEG(segmptr)  =  ’segmptr; 
FP_OFF(segmptr)  =  0; 

/*  return  pointer  */ 
return  (segmptr); 

This  may  seem  strange  at  first  (using  a 
macro  on  the  left  side  on  an  assign¬ 
ment  statement),  but  a  look  at  the  mac¬ 
ros  themselves  reveals  that  this  is  per¬ 
fectly  legal.  Recall  that  a  far  pointer  is 
stored  in  memory  as  an  offset  followed 
by  a  segment.  Both  may  be  treated  as 
unsigned  (16-bits).  Through  a  series 
of  casts  to  an  unsigned  pointer,  these 
two  macros  access  the  segment  and 


offset  portions  of  a  far  pointer. 

3.  If  you  are  having  problems  with  de¬ 
claring  MCBPTR  to  be  huge,  (my  com¬ 
piler  kept  treating  it  as  far),  then  you 
may  need  to  change  the  pointer  arith¬ 
metic  used  in  getting  the  next  MCB 
pointer.  In  Turbo  C: 

/*  huge  pointer  to  an  MCB  */ 
PTRMCB  ptrmcb; 

/*  get  pointer  to  next  MCB  */ 
ptrmcb  +=  ptrmcb->psize  +  1; 

in  Microsoft  C: 

/*  "huge”pointer  to  an  MCB  */ 

/*  but,  for  some  unknown  reason 
(at  least  to  me)  */ 
/*  it  is  treated  as  far!  */ 

PTRMCB  ptrmcb; 

/*  temporary  to  hold  segment  ad¬ 
dress  of  MCB  pointer  */ 
unsigned  mcbseg; 

/*  get  pointer  to  next  MCB  */ 
mcbseg  =  FP_SEG(mcbptr)  +  mcbptr- 
>size  +  1; 

FP_SEG(mcbptr)  =  mcbseg; 

Remember,  both  huge  and  far  point¬ 
ers  may  access  any  location  in  mem¬ 
ory.  However,  when  performing  pointer 
arithmetic,  such  as  the  addition  above, 
a  far  pointer  only  uses  1 6-bit  math  while 
a  huge  pointer  uses  32-bit  math!  Since 
far  and  huge  pointers  are  stored  as 
offset  followed  by  segment,  one  can 
see  that  the  segment  of  a  far  pointer 
cannot  be  changed  via  simple  addition! 
Of  course,  you  may  modify  the  seg¬ 
ment  directly  as  shown  above. 

4.  Do  not  use  the  maximum  optimi¬ 
zation  switch  /Ox.  Among  other  things, 
the  /Ox  switch  causes  the  compiler  to 
disregard  pointer  aliasing  in  its  optimi¬ 
zations.  As  there  is  a  lot  of  work  with 
pointers  in  this  program,  this  may  cause 
the  program  to  behave  unpredictably. 
On  my  computer,  this  results  in  an 
endless  loop,  which  continually  prints 
out  information  on  the  first  MCB  only! 

Steve  Smith 
Renton,  Wash. 


TUL  Is  Alive  and  Kicking 

Dear  DDJ , 

Regarding  Frank  Little’s  February  letter 
referencing  the  long-standing  Burroughs 
joint  venture  in  India,  let  me  note  that 
Tata  Unisys  Limited  (TUL)  is  alive  and 
thriving.  The  Burroughs-Sperry  merger 
has  allowed  us  to  combine  operations 
in  India,  so  that  we  are  now  a  major 
information  technology  presence  in  In¬ 
dia.  In  addition,  we  are  the  second- 
largest  software  exporter  from  India 


and  have  an  important  marketing  and 
manufacturing  presence  there  as  well. 

Our  experience  is  that  the  joint  ven¬ 
ture  in  India  significantly  strengthens 
our  global  competitiveness.  TUL  has 
implemented  scores  of  newly  designed, 
leading-edge  applications,  and  not  just 
conversions  as  Mr.  Little  seems  to  im¬ 
ply.  Increasingly,  new  software  devel¬ 
opment  projects  are  being  undertaken 
within  India,  thanks  to  improving  com¬ 
munications  and  satellite  links.  This, 
in  my  view,  proves  once  again  that 
clients  will  ultimately  care  more  about 
quality,  timeliness,  and  cost,  than  where 
a  project  is  performed. 

Anil  Shrikhande 
Unisys  Corporation 
Blue  Bell,  Penn. 

DDJ 

We  welcome  your  comments  (and  sug¬ 
gestions).  Mail  your  letters  to  DDJ,  501 
Galveston  Dr.,  Redwood  City,  CA  94063, 
or  send  them  electronically  to  Compu¬ 
Serve  76704,50  or  via  MCI  Mail,  c/o 
DDJ.  Please  include  your  name,  city, 
and  state.  We  reserve  the  right  to  edit 
letters. 
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A  specification  describing  a  general  ap¬ 
proach  to  object-oriented  software  de¬ 
sign  has  been  published  by  Interac¬ 
tive  Development  Environments 
Inc.  The  specification,  called  Object- 
Oriented  Structured  Design  (OOSD), 
is  a  non-proprietary  notation  for  de¬ 
sign  of  software  systems  that  is  language- 
independent  (supporting  languages 
such  as  C++,  Eiffel,  Smalltalk,  Fortran, 
C,  and  Pascal)  and  synthesizes  tradi¬ 
tional  top-down  design  with  modern 
concepts  for  object-oriented  design  into 
a  comprehensive  approach  to  model¬ 
ing  software  architecture.  In  addition 
to  providing  improved  support  for  the 
pivotal  architectural  design  step  of  the 
software  development  process,  OOSD 
supports  automated  generation  of  code 
for  multiple  programming  languages, 
provides  partitioning  of  a  system  into 
a  coherent  software  architecture,  facili¬ 
tates  reuse  of  design  elements,  and  pro¬ 
vides  a  clear  notation  for  communica¬ 
tion  among  designers  and  reviewers. 
The  key  building  blocks  in  OOSD  are 
modules,  lasses,  and  monitors.  Reader 
Service  No.  20. 

Interactive  Development 
Environments,  Inc. 

595  Market  St., 

12th  Floor 

San  Francisco,  CA  94105 
415-543-0900 

Hamilton  C  shell,  recently  released  by 
Hamilton  Laboratories  is  an  inter¬ 
active  language  for  OS/2.  The  com¬ 
pany  says  that  its  key  benefit  is  that  it 
allows  you  to  describe  what  you  want 
the  machine  to  do  much  more  quickly 
and  easily,  even  if  what  you  want  is 
fairly  complex.  Some  of  its  features  in¬ 
clude:  Fully  nestable  programming  con¬ 
structs  for  iteration  and  condition-test¬ 
ing;  variables,  arrays,  and  a  wide  range 
of  expression  operators  and  built-in  func¬ 
tions;  a  powerful  history  mechanism 
for  recalling  and  editing  past  commands; 
language  constructs  for  I/O  redirection, 
piping,  background  execution,  and  par¬ 
allel  threading;  and  more.  Hamilton  C 


shell  complies  with  the  Berkeley  4.3 
Unix  Programmer’s  Manual.  C  shell 
requires  286-  or  386-based  AT  or  PS/2 
or  compatible  with  a  minimum  of  2 
Mbyte  of  RAM  and  a  2-Mbyte  hard  disk. 
All  executables  will  run  properly  inside 
a  Presentation  Manager  window.  The 
cost  is  $350.  Reader  Service  No.  22. 
Hamilton  Laboratories 
13  Old  Farm  Road 
Wayland,  MA  01778 

508- 358-5715 

VM-DEBUG  (The  Virtual  Machine  De¬ 
bugger),  a  debugging  tool  for  PCs,  XTs, 
and  ATs,  has  been  released  by  Wendin 
Inc.  VM-DEBUG  is  an  interpreter  whose 
language  is  8088  machine  code  ex¬ 
tended  with  the  real-mode  instructions 
of  an  80286.  It  can  stop  the  execution 
of  a  program  at  any  point,  examine  or 
alter  memory  or  registers,  examine  the 
program,  and  determine  where  the  pro¬ 
gram  has  been.  Unlike  normal  debug¬ 
gers,  these  functions  are  accomplished 
by  a  program  outside  the  addressing 
space  of  the  program  or  system  under 
test,  so  that  VM-DEBUG  can  never  be 
altered  or  destroyed  by  an  errant  pro¬ 
gram.  VM-DEBUG  also  has  the  ability 
to  trace  DOS  itself  or  the  ROMs,  and 
set  breakpoints  within  ROM.  It  retails 
for  $99.  Reader  Service  No.  23. 

Wendin,  Inc. 

P.O.  Box  3888 
Spokane,  WA  99220-3888 

509- 624-8088 

A  new  book  that  describes  how  assem¬ 
bler  macros  are  used  with  the  80386 
will  be  released  next  month  by  Tab 
Professional  and  Reference  Books. 
The  book,  entitled  80386  Macro  As- 
sembler  With  Toolkit  and  written  by 
Penn  Brumm  and  Don  Brumm,  dis¬ 
cusses  the  Microsoft  Macro  Assembler 
(MASM)  operands  and  operators,  pro¬ 
gram  structure  and  file  control  direc¬ 
tives,  global,  conditional,  and  macro 
directives,  and  interfacing  MASM  with 
high-level  languages.  The  608-page 
book  retails  for  $25.95.  Reader  Service 
No.  28. 

Tab  Professional  and 
Reference  Books 

Blue  Ridge  Summit,  PA  17294-0850 
800-822-8138 

Lattice  C  6.0,  for  DOS  and  OS/2,  is  now 
available  from  Lattice  Inc.  The  system 
uses  global  optimizing  technology  (see 
“Optimization  Technology”  by  Keith 
Rowe,  DDJ,  June,  1989  for  details  on 
this  technology)  and  includes  a  source- 
level,  native,  and  cross  debugger  and 
an  integrated  screen  editor.  The  com¬ 
piler  also  supports  automatic  register 
variable  and  registerized  parameter  sup¬ 


port,  built-in  function  support,  and  sup¬ 
port  for  precompiled  header  files. 

The  system  includes  more  than  800 
prewritten  functions,  multithreaded  li¬ 
braries,  DLL  support,  and  also  comes 
with  special  graphics,  database,  com¬ 
munications,  and  screen  management 
libraries. 

Lattice  C  6.0  runs  on  IBM  PC/XT/AT 
and  compatibles  and  requires  DOS  2.1 
or  OS/2  1.0  or  later.  The  price  for  ver¬ 
sion  6.0  is  $250,  although  owners  of 
version  3.4  can  upgrade  for  $75.  Own¬ 
ers  of  all  other  versions  can  upgrade 
for  $115.  Reader  Service  No.  32. 

Lattice,  Inc. 

2500  S  Highland  Ave. 

Lombard,  IL  60148 
312-916-1600 

The  new  hardware-assisted  model  of 
the  Periscope  debugger  is  now  avail¬ 
able  from  the  Periscope  Company. 
Periscope  Model  IV  runs  on  80286  and 
80386  systems  with  CPU  speeds  up  to 
25MHz  and  zero  wait  states.  It  works 
on  any  PC-compatible  with  a  standard 
AT-style  bus.  Periscope  IV  is  designed 
to  help  software  developers  achieve 
optimum  performance  from  their  own 
software,  and  can  monitor  program  exe¬ 
cution  in  real-time.  It  can  track  down 
memory  overwrites  because  it  does  not 
slow  down  program  execution  as  soft- 
ware-based  debuggers  do.  The  Peri¬ 
scope  software  provides  source-level 
and  symbolic  support  for  Borland,  IBM, 
Lattice,  Manx,  Microsoft,  and  other  lan¬ 
guages.  Prices  range  from  $2195  to 
$2995.  Reader  Service  No.  26. 

The  Periscope  Company 
1197  Peachtree  St. 

Plaza  Level 
Atlanta,  GA  30361 
404-875-8080 

Microsoft  Corporation  has  released 
a  number  of  programming  tools  for  the 
OS/2  Presentation  Manager  that  com¬ 
plement  its  OS/2  language  compiler 
family.  At  the  centerpiece  is  the  Micro¬ 
soft  OS/2  Presentation  Manager  Toolkit, 
a  complete  “one  box”  answer  to  Pres¬ 
entation  Manager  developer’s  needs, 
and  it  includes  a  collection  of  graphical 
tools,  books,  Quickhelp  documenta¬ 
tion,  sample  code,  and  electronic  sup¬ 
port.  These  components  are  available 
individually  or  in  various  combinations. 
Upgrade  pricing  available.  Minimum 
system  requirements  are  an  80286  or 
80386  processor  running  OS/2  1.1;  2.5 
Mbytes  of  user  memory;  a  high-density 
5.25-inch,  or  a  3.5-inch  drive;  and  a 
hard  disk.  The  toolkit  supports  EGA 
and  VGA  graphics  adapters  and  is  com¬ 
patible  with  any  Microsoft  OS/2  lan- 
(continued  on  page  1 79) 
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(continued  from  page  1 75) 
guage  compiler.  The  complete  Presen¬ 
tation  Manager  Toolkit  is  $500.  Up¬ 
grade  pricing  is  $200  for  registered  own¬ 
ers  of  the  OS/2  Programmer’s  Toolkit. 
Reader  Service  No.  24. 

Microsoft  Corporation 
16011  NE  36th  Way 
Box  97017 

Redmond,  WA  98073-9717 
206-882-8080 

Microsoft  Corporation  has  updated 
its  Fortran  compiler  with  the  recent 
release  of  the  MS  Fortran  Optimizing 
Compiler,  Version  5.0,  which  supports 
DOS  and  OS/2  1.1  with  Presentation 
Manager.  The  company  claims  that  For¬ 
tran  5.0  offers  the  broadest  VAX  and 
IBM  VS  Fortran  compiler  syntax  avail¬ 
able  on  a  PC,  supporting  virtually  all 
VAX  Fortran  syntax  other  than  VAX 
operating  system  calls.  Fortran  5.0  comes 
with  a  graphics  library,  the  CodeView 
source-level  debugger,  the  MS  Editor, 
LINK,  NMake,  LIB,  and  OS/2  support 
and  extended  syntax.  Minimum  system 
requirements  are  a  PC  with  320K  of 
available  user  memory  and  DOS  3.0  or 
OS/2  1.1.  The  suggested  retail  price  for 
Fortran  5.0  is  $450,  although  registered 
owners  of  MS  Fortran  4.1  who  bought 
the  compiler  after  April  1,  1989,  can 


upgrade  for  free.  Other  4.1  registered 
owners  can  upgrade  for  $100,  4.0  own¬ 
ers  for  $150,  and  $250  for  owners  of 
earlier  versions.  Reader  Service  No.  27. 
Microsoft  Corporation 
16011  NE  36th  Way 
Box  97017 

Redmond,  WA  98073-9717 
206-882-8080 

A  protocol  specification  called  the  Vir¬ 
tual  Control  Program  Interface  (VCPI), 
which  is  designed  to  prevent  conflicts 
between  386  software  from  different 
companies,  has  been  sanctioned  by  a 
number  of  different  hardware  and  soft¬ 
ware  companies.  Originally  sponsored 
by  Phar  Lap  Software  Inc.,  VCPI  ad¬ 
dresses  technical  issues  between  con¬ 
trol  programs  and  DOS  extenders  that 
arise  due  to  the  nature  of  the  386.  These 
conflicts  include  CPU  mode  switching, 
hardware  interrupt  processing,  and  the 
sharing  of  extended  memory.  Left 
unresolved,  these  conflicts  force  the 
user  to  turn  off  control  programs  in 
order  to  run  an  extended  application. 
The  agreement  of  a  programming  stan¬ 
dard  allows  the  new  categories  of  soft¬ 
ware  brought  on  by  386  PCs  to  play 
together.  In  addition  to  Phar  Lap,  other 
sponsors  of  the  VCPI  specification  are 
Quarterdeck,  Auadram,  Lotus,  A.I.  Ar¬ 


chitects,  Qualitas,  and  Rational  Systems. 
The  new  VCPI  specification  will  be 
available  on  June  1,  1989,  at  no  cost 
through  Phar  Lap  Software.  Reader  Ser¬ 
vice  No.  29. 

Phar  Lap  Software,  Inc. 

60  Aberdeen  Ave. 

Cambridge,  MA  02138 
617-661-1510 

Clear  Software  Inc.  has  recently  in¬ 
troduced  Clear+  for  C,  a  product  that 
helps  developers  understand  C  code. 
It  is  designed  to  instantly  produce  high- 
quality  system  documentation  and  to 
clarify  the  logic  of  C  programs  and 
applications.  According  to  Sandy  Rudy, 
who  designed  the  language  portions 
of  the  program,  “Clear+  acts  like  a  com¬ 
piler  but  the  output  doesn’t  run,  it  shows 
[on  the  screen].”  Clear  President  Yadim 
Yasinovsky  went  on  to  tell  DDJ  that 
“Clear+  is  ideal  in  an  environment  when 
you  inherit  someone  else’s  code.” 

Clear  reads  the  source  code  of  any 
C  application  and  instantly  produces 
the  system  tree  chart,  function  flow 
charts,  formatted  source  listings,  func¬ 
tion  cross  references,  and  prototype 
files.  As  flow  charts  and  tree  charts  are 
output  to  a  printer,  screen,  or  a  file,  the 
program  automatically  calculates  the 
spacing,  number  of  pages  (or  screens) 


required,  and  the  placement  of  sym¬ 
bols  for  the  flow  chart.  And  diagrams 
look  exactly  the  same  on  screen  as 
they  do  in  print.  Clear  also  features 
powerful  hardcopy  controls,  various 
graphics  options,  and  options  to  di¬ 
rectly  invoke  a  text  editor  or  compiler 
of  the  user’s  choice.  Clear  can  analyze 
C  source  code  as  is  or  after  it  has  been 
preprocessed  with  either  an  external 
or  internal  preprocessor. 

Clear  has  been  designed  for  use  with 
any  IBM  PC/XT/AT  or  compatible  and 
supports  Hercules,  CGA,  EGA,  VGA, 
most  dot-matrix  printers,  and  HP  Laser¬ 
Jet-*-  printer.  Minimum  RAM  require¬ 
ment  is  512K.  Clear  currently  supports 
Microsoft  C,  QuickC,  Turbo  C,  and  any 
generic  C  compiler.  Clear+  for  C  retails 
for  $199-95  plus  $5.00  for  shipping  and 
handling.  Clear+  for  dBase  is  also  avail¬ 
able  for  the  same  price.  A  combination 
package  (Clear-*-  for  C  and  Clear-*-  for 
dBase)  is  sold  for  $310.00  plus  $10.00 
for  shipping  and  handling.  Reader  Ser¬ 
vice  No.  3L. 

Clear  Software,  Inc. 

637  Washington  St.,  Ste.  105 
Brookline,  MA  02146 
617-232-4720 

The  QuickC  family  has  grown  with  Mi¬ 
crosoft  Corporation’s  introduction  of 


the  QuickC  Compiler  with  QuickAs- 
sembler  2.01.  This  package  is  an  inte¬ 
grated  C-and-assembler  environment 
which  includes  an  integrated  editor, 
compiler,  and  debugger.  The  C  portion 
of  the  compiler  has  not  changed  from 
QuickC  2.0.  The  assembler  portion  con¬ 
sists  of  a  macro-assembler  add-in  mod¬ 
ule  built  around  MASM  5.1,  which  fea¬ 
tures  single-pass  assembly  technology. 

Additionally,  the  package  provides 
incremental  compiling/linking  and  re¬ 
compiles/reassembles  and  relinks  only 
modules  that  have  been  changed  since 
the  previous  compilation.  The  debug¬ 
ger  can  be  used  to  debug  both  assem¬ 
bler  and  mixed-language  programs.  The 
package  is  supported  by  an  on-line 
reference  system  in  addition  to  books 
and  manuals. 

System  requirements  are  MS-DOS  2.1 
or  higher  and  512K  of  RAM;  a  mouse 
is  optional.  The  QuickC  compiler  and 
QuickAssembler  package  sells  for  $199 
although  registered  QuickC  Compiler 
2.0  owners  can  buy  the  assembler  add¬ 
in  module  directly  from  Microsoft  for 
$75.  Reader  Service  No.  33. 

Microsoft  Corp 
16011  NE  36th  Way 
Box  97017 

Redmond,  WA  98073-9717 
206-882-8080 


A  page  makeup  system  that  supports 
C  compilers  is  now  available  through 
Quality  Software.  The  system,  called 
FutureComp  Laserline,  is  a  MS-DOS  ver¬ 
sion  of  the  company’s  FutureComp  Page 
Makeup  Environment  which  is  primar¬ 
ily  designed  to  produce  custom  page 
makeup  programs  for  directories,  cata¬ 
logues,  parts  lists,  technical  manuals, 
and  similar  applications. 

The  Laserline  version  of  FutureComp 
can  output  to  most  printers  and  type¬ 
setters  that  support  PCL  or  PostScript. 
(The  Proline  version  of  the  system 
supports  high-resolution  typesetters 
like  those  from  Mergenthaler  and  Auto¬ 
logic.) 

In  addition  to  font  handling  and  hy¬ 
phenation  dictionary  utilities,  Future¬ 
Comp  provides  C  functions  for  com¬ 
posing  blocks  of  text,  placing  illustra¬ 
tions  and  tables,  and  for  positioning 
these  blocks  anyway  on  a  page.  Users 
can  also  construct  logical  fonts  for  spe¬ 
cial  applications. 

The  system  supports  any  compiler 
that  can  call  ANSI  C  functions,  and 
applications  programs  created  with  Fu¬ 
tureComp  can  be  recompiled  on  any 
computer  system  that  supports  C.  The 
system  runs  on  any  IBM  PC/XT/AT  us¬ 
ing  DOS  2.0  or  higher;  Microsoft  C  5.1 
is  also  required.  FutureComp  sells  for 
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$695  and  includes  PostScript  and  HP 
PCL  translators.  Reader  Service  No.  34. 
Quality  Software 
60  Lewis  St. 

Newton,  MA  02158 
617-965-2231 

As  C  portability  tools  become  increas¬ 
ingly  important,  new  ones  continue  to 
pop  up,  the  most  recent  being  Abraxas 
Software’s  CodeCheck.  What  this  pack¬ 
age  does  is  analyze  C  source  code  in 
terms  of  its  portability  between  PC- 
DOS,  OS/2,  Macintosh,  Unix,  and  VMS. 
“In  essence,  CodeCheck  is  an  expert 


system  that  looks  at  the  code  and  tells 
if  it  is  portable  or  not,”  Abraxas  presi¬ 
dent  Patrick  Conley  told  DDJ.  During 
set-up,  the  system  loads  a  set  of  rules 
for  a  particular  platform  (DOS,  OS/2, 
Mac,  and  so  on),  then  checks  the  code 
against  those  rules.  It  then  identifies 
any  code  that  is  not  portable  to  or  from 
any  environment,  including  C++  and 
ANSI  C.  It  also  quantifies  code  main¬ 
tainability  with  user-defined  measures 
at  all  levels  and  identifies  unacceptable 
style  or  usage. 

CodeCheck  supports  all  C  compilers 
from  major  vendors  and  requires  512K 
of  memory.  It  sells  for  $295  and  Conley 


said  it  would  be  shipping  in  mid- August. 
Reader  Service  No.  35. 

Abraxas  Software,  Inc. 

7033  SW  Macadam  Ave. 

Portland,  OR  7219 
503-244-5253 

HCR  Corporation  has  introduced  the 
packaged  version  of  an  advanced  Unix 
C++  compiler  based  on  C++,  Release 
2.0,  from  AT&T.  HCR/C++  provides  all 
of  the  key  features  of  C++,  such  as  type 
safe  linkages,  default  membership  in¬ 
itialization,  and  the  ability  of  each  class 
to  define  its  own  operators.  It  will  run 
on  most  386-based  systems.  HCR’s  db- 
Xtra,  based  on  dbx  Version  3  from 
Berkeley  4.3  BSD  Unix,  adds  the  ability 
to  operate  through  windows,  permit¬ 
ting  users  to  review  their  output  and 
source  code  easily,  even  on  standard 
terminals.  HCR/C++  allows  direct  de¬ 
bugging  of  C++  and  window  access  to 
the  translated  C  source  code.  All  C++ 
code  is  translated  into  C  before  execu¬ 
tion  so  programmers  can  apply  dbXtra 
to  examine  either  C  or  C++  code  dur¬ 
ing  debugging. 

Initial  copies  will  be  available  at  an 
introductory  price  of  $499  (50  percent 
off  the  list  price  of  $995).  HCR’s  stan¬ 
dard  support  and  upgrade  options  are 
available;  each  user  of  HCR/C++,  Ver¬ 
sion  1,  also  will  have  the  option  to 
upgrade  to  Version  2  for  a  delivered 
price  of  $99-  Reader  Service  No.  36. 
HCR  Corporation 
130  Bloor  Street  West 
Toronto,  Ontario,  Canada 
M5S  1N5 
416-922-1937 

Quibus  Enterprises  has  updated  its 
Fortran  Development  Tools  package, 
which  is  designed  to  help  Fortran 
programmers  maintain  their  code.  Re¬ 
lease  2  of  the  package  automatically 
deals  with  poorly  formatted  or  heavily 
modified  code  using  a  pretty  printer 
that  indents,  renumbers,  and  generally 
cleans  up  the  code.  The  program  also 
converts  GOTOs  to  structured  IF-THEN- 
ELSE  blocks. 

A  preprocessor  for  supporting  con¬ 
ditional  compilation  and  code  sharing 
is  included,  along  with  a  utility  to  ex¬ 
tract  subroutines  from  source  files.  All 
tools  accept  Fortran  77  plus  extensions 
from  VMS,  Lahey,  Microsoft  Fortran. 
The  tools  run  on  IBM  PC/XT/AT  com¬ 
patibles  with  512K  of  memory  and  sell 
for  $129.  Reader  Service  No.  37. 

Quibus  Enterprises,  Inc. 

106  N.  Draper  Ave. 

Champaign,  IL  61821 
217-356-8876 
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Unbundled  Integration 

Amanda  Hixson  was  one  of  the  more  savvy  writers  we  relied  upon  to  review  software  back  in 
the  early  1980s  when  I  was  an  editor  at  InfoWorld.  We  knew  we  could  count  on  her  to  hold 
software  to  high  standards,  to  evaluate  it  from  the  user’s  viewpoint,  and  to  get  quickly  to  the 
essence  of  what  was  right  or  wrong  with  the  product.  When,  years  later,  she  went  to  work  for 
Apple,  I  wondered  if  it  was  the  right  move;  writers  should  write,  I  thought. 

Over  the  years,  Hixson  demonstrated  to  the  satisfaction  of  any  observer  that  her  decision  was  a 
savvy  one,  working  her  way  up  to  a  position  reporting  to  Randy  Battat,  the  VP  of  Product  Marketing. 
Early  this  year  she  acquired  a  new  title,  when  she  presented  Battat  with  the  idea  that  the  Macintosh 
System  Software  should  be  marketed.  It  wasn’t  a  difficult  sale;  although  Apple  doesn’t  have  to  sell 
System  Software  on  its  own,  the  company  understands  that  it’s  the  System  Software  that  sells  the 
little  gray  toasters.  Battat  agreed  that  it  was  a  good  idea,  but  pleaded  that  he  had  no  time.  “I  do,” 
she  said,  and  he  made  her  Product  Marketing  Manager  for  System  Software.  The  first  big  step  Apple 
has  taken  in  marketing  its  System  Software  was  the  press  day  at  the  May  Developers’  Conference, 
when  Apple  spelled  out  which  of  the  rumored  new  features  were  in  fact  going  into  the  next  major 
system  release.  The  announcements,  along  with  other  announcements  coming  out  of  the  Developers’ 
Conference,  are  worthy  of  note  to  anyone  remotely  considering  developing  a  Mac  product  but  not 
already  in  on  all  the  former  secrets. 

Some  of  the  features  Apple  will  be  folding  into  System  Version  7.0  are  obvious  and  have  obvious 
developer  consequences.  The  virtual  memory  and  32-bit  addressing,  if  cleanly  implemented,  should 
be  beneficial  for  everybody.  The  nice  feature  of  VM  for  users  is  the  ability  to  buy  memory  for 
average  need,  rather  than  for  maximum  need.  Of  course,  System  Version  7.0  will  require  a  minimum 
of  2  Mbytes  of  memory.  The  outline  fonts  and  layout  manager,  giving  Apple  real  device¬ 
independent  typographic-quality  text,  will  be  very  interesting  for  applications  that  can  make 
effective  use  of  it.  And  the  database  access  mechanism  looks  interesting. 

But  I  found  the  InterApplication  Communications  architecture  (IAC)  the  most  intriguing. 

The  IAC  gives  the  developer  a  choice  of  ways  to  get  information  from  one  application  to  another. 
Beyond  the  existing  Clipboard  for  copying  and  pasting  text  and  pictures,  there  will  be  a  Live 
Copy/Paste  facility  that  programmers  can  incorporate  into  new  applications.  It  uses  a  publish/ 
subscribe  model:  The  user  of  one  application  selects  some  data  in  a  spreadsheet  he’s  working  on 
(for  example)  and  “publishes”  it.  Another  user  can  “subscribe”  to  the  published  data,  which  brings 
it  into  the  word-processing  document  he’s  working  on  (for  example),  and  the  data  will  change  in 
the  subscriber’s  document  whenever  the  publisher  changes  the  original.  Apple  is  providing 
developers  with  a  toolbox  and  user-interface  guidelines  for  implementing  Live  Copy/Paste. 

Then  there  are  the  Event  Manager  extensions.  Because  the  Mac  system  is  event-driven,  extending 
the  Event  Manager  is  a  logical  way  to  allow  inter-application  communication:  Just  let  one 
application  message  another.  The  trick  is  that  the  other  application  has  to  be  able  to  recognize  the 
message,  and  that  requires  some  guidance  from  Apple.  What  Apple  is  providing  is  a  protocol  of 
standard  messages  for  inter-application  communication:  Generic  spreadsheet  messages,  for  example, 
that  only  need  some  conforming  spreadsheet  program  (not  necessarily  Excel)  to  be  on  the  receiving  end. 

The  low-level  Program-to-Program  Communication  mechanism  (PPC)  is  the  tool  the  higher-level 
components  use  to  get  their  jobs  done;  it’s  also  the  tool  a  developer  would  use  to  develop  more 
subtle  inter-application  links  than  the  higher-level  tools  allow.  It  also  permits  desk  accessories, 
control  panels,  and  other  chunks  of  code  to  communicate. 

Not  too  long  ago,  a  lot  of  people  put  their  money  and  time  into  integrated  software  packages: 
Omnibus  programs  that  melded  spreadsheet,  text,  graphic,  and  other  kinds  of  processing. 
Unfortunately,  not  enough  of  these  people  were  customers.  One  theory  about  the  failure  of 
integrated  software  is  that  it  was  the  bundling,  not  the  integration,  that  didn't  work.  If  this  theory 
is  accurate,  then  users  would  love  it  if  they  could  pick  the  applications  they  wanted  to  use  and 
know  that  they  would  work  together  as  tightly  as  the  components  of  one  of  the  integrated  packages. 
Or  more  tightly. 

That's  what  Apple  has  in  mind;  there  was  a  lot  of  talk  at  the  conference  about  not  reinventing 
the  wheel,  about  having  an  application  signal  another  application  when  it  needs  something  done 
outside  its  area  of  specialization.  I'd  like  to  see  that. 


Michael  Swaine 
editor-at-large 
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AUTOROUTING  WITH  THE  A*  ALGORITHM  1 6 

by  Randy  Nevin 

Finding  the  best  of  all  possible  solutions  can  be  made  easier  with  Al-based  search 
algorithms.  Randy  looks  at  the  A*  algorithm  —  and  discusses  how  it  can  be  used  to  simulate 
a  printed  circuit  board  layout. 

SIMULATED  ANNEALING  26 

by  Michael  P.  McLaughlin 

Simulated  annealing  is  most  often  used  by  VLSI  chip  designers  to  determine  the  optimum 
arrangement  of  thousands  of  circuits.  But,  as  Michael  shows  here,  it  has  other  applications 
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by  Todd  King 
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by  Mark  C.  Peterson 
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programs. 
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by  Michael  Abrash  and  Dan  Illowsky 

Mini-interpreters  can  do  lots  of  work  within  a  small  space,  even  letting  you  create  your  own 
customized  minilanguage.  Michael  and  Dan  discuss  the  pros  and  cons  of  mini-interpreters, 
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by  John  M.  Dlugosz 
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by  Jeff  Duntemann 
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programming  may  never  be  the  same  again.  He  then  strays  off  into  the  world  of  REXX 
programming,  with  a  look  at  Personal  REXX. 
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Texas  Instruments  for  providing  the 
schematics  and  boards  used  for  the  photos 
inside  the  issue. 
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If  you’ve  been  experiencing  a  failure  to 
communicate,  you'll  want  to  hear  what  we 
have  to  say  about  data  communications  in 
October.  We’ll  examine  finite  state  machines 
and  communications,  data  compression, 
and  ways  you  can  take  advantage  of 
NetBios  for  high-speed  data  transfers.  You’ll 
also  find  out  how  to  use  that  old  PDP-1 1 
(that's  been  gathering  dust)  as  more  than  a 
boat  anchor.  All  this,  and  more! 
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E  D  I  T  0  R  I  A  L 


Just  Around  the 
Corner 


Whether  you’re  ready  or  not,  the  end  of  this  year  (or  the  beginning  of  the  next,  depending 
on  how  you  look  at  it)  is  right  around  the  corner.  1990  and  we’re  on  a  downhill  run  into 
the  twenty-first  century,  and  writing  the  correct  year  on  your  checks  will  be  the  least  of 
your  problems.  We’ll  have  to  worry  not  only  about  the  right  decade,  but,  before  long,  the  right 
century,  too.  Somehow  that  still  sounds  a  little  unreal.  For  DDJ,  the  new  decade  will  bring  the 
beginning  of  our  fifteenth  year,  spanning  three  decades.  That’s  not  bad  for  any  magazine,  let  alone 
one  that  deals  with  computers. 

For  our  part,  we’re  lining  up  next  year/next  decade  articles  and,  once  again,  we  need  your  help 
to  make  sure  we’re  getting  out  the  right  kind  of  articles  for  you.  When  we  published  the  1989 
editorial  calendar,  we  heard  from  a  lot  of  you  who  sent  in  suggestions  and/or  wrote  articles  (thanks 
from  us  and  from  your  fellow  readers),  and  we’d  like  to  hear  what’s  on  your  mind  this  year. 

So  in  the  first  part  of  1990,  our  monthly  themes  will  be: 


January 

Real-time  Programming 

April 

Neural  Nets 

February 

Windowing  Systems 

May 

Memory  Management 

March 

Assembly  Language  Programming 

June 

Hypertext 

Later  in  the  year,  we’ll  cover  topics  such  as  graphics  programming,  our  annual  C  issue, 
structured  languages,  operating  systems,  and  object-oriented  programming.  I’ll  post  more  specifics 
at  a  later  date. 

As  always,  we’re  looking  for  focused,  task-specific  articles  that  solve  a  particular  programming 
problem,  present  a  new  or  unique  technique  or  utility,  and  list  your  program  code.  If  a  subject  that 
interests  you  isn't  mentioned  above,  that’s  okay,  the  list  isn’t  meant  to  be  all-inclusive.  Only  about 
half  the  articles  in  any  issue  are  theme  related;  the  others  are  on  all  kinds  of  programming-related 
topics.  Any  language  —  C,  Basic,  Pascal,  Modula-2,  C++,  Fortran,  Forth,  Smalltalk,  assembly,  and 
so  on  —  is  fine,  as  is  any  operating  system  platform,  including  Unix,  DOS,  OS/2,  Macintosh,  or 
whatever.  (One  really  popular  article  we  ran  not  long  ago  was  on  the  Amiga  and  I  can  already 
hear  “I  told  you  so. . . .  ”  echoing  from  Amiga  fans.) 

So,  if  you  have  an  idea  for  an  article  that  you’d  like  to  write  or  to  see  someone  else  write,  give 
Mike  or  me  a  call  or  drop  us  a  letter  (E-mail  or  regular)  describing  what  you  have  in  mind.  (For 
CompuServe,  address  to  76704,50,  MCI  Mail  care  of  DDJ,  BIX  to  jerickson,  or  if  you’re  using  the 
DD/listing  service,  jerickson.)  For  regular  mail,  be  sure  to  send  it  to  DDJ,  501  Galveston  Dr., 
Redwood  City,  CA  94063.  We  quite  often  get  letters  addressed  to  us  in  care  of  our  subscription 
service  in  Boulder,  Colo.  The  letters  eventually  get  here,  but  sometimes  weeks  later. 


In  other  news,  AT&T  has  finally  released  its  2.0  specification  for  C++.  It’s  been  a  long  time  coming 
and  everyone,  particularly  compiler  vendors  who’ve  been  waiting  for  the  other  shoe  to  drop,  can 
now  get  down  to  the  business  of  forging  ahead  with  their  C++  plans.  (See  the  “Of  Interest”  column 
in  this  issue  for  details.) 

While  it’s  great  that  the  specification  is  finally  available,  it  was  the  2.0  “language  system”  (don’t 
call  it  “preprocessor”)  license  arrangements  that  caught  my  eye.  To  license  C++  1.02,  all  you  had 
to  do  was  pony  up  $2000,  not  necessarily  a  big  deal  either  for  little  developers  or  the  big  guys. 
That’s  not  the  story  with  2.0,  however.  If  you  currently  hold  a  1.02  license,  a  2.0  license  will  cost 
you  $10,000,  and  if  you  don’t  hold  a  1.02,  but  want  a  2.0  license,  the  cost  is  $20,000.  (Okay,  okay, 

I  know  AT&T  has  to  cover  all  those  development  costs  and  I  wouldn’t  expect  the  company  just  to 
give  it  away.) 

If  you  fall  into  the  former  category  (that  is,  you  want  the  2.0  but  don’t  have  1.02),  here’s  a  tip: 
Get  a  license  to  1.02  for  $2000,  then  immediately  upgrade  to  2.0  for  $10,000,  saving  yourself  $8000 
in  the  process.  I  checked  with  an  AT&T  rep  who  said  they  would  do  this,  but  for  how  long,  she 
didn’t  know.  If  you  take  advantage  of  this  money-saving  tip,  don’t  forget  about  who  put  you  onto 
it.  You  might  want  to  consider  sharing  your  savings;  10  percent  is  a  nice  round  figure,  made  payable 
to  the  editors  of  DDJ,  of  course. 


Jonathan  Erickson 
editor-in-chief 
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Good-bye,  Again 

Dear  DDJ, 

We  were  all  shocked  to  hear  about  the 
death  of  Kent  Porter.  Having  seen  him 
so  recently  at  a  press  conference  made 
the  news  all  the  more  incredible.  What 
can  we  say? 

As  an  industry  leader,  a  writer,  pro¬ 
grammer,  and  technical  editor,  Kent 
taught  us  a  lot.  His  opinion  was  re¬ 
spected.  He  inspired  us.  It’s  hard  for 
us  to  believe  he’s  not  here.  Little 
things,  like  leafing  through  Dobb’s 
only  to  stumble  across  the  “Graphics 
Programming”  column,  become  pain¬ 
ful  reminders.  We  remember  how  pre¬ 
cious  life  is  and  how  seldom  we  stop 
to  appreciate  those  around  us  —  both 
coworkers,  and  friends  —  for  the  spe¬ 
cial  people  they  are. 

This  is  hard  for  us  in  many  ways. 
Most  of  us  know  Kent  through  his 
words.  We  learned  about  the  intrica¬ 
cies  of  VGA  graphics  while  we  laughed 
at  an  anecdote  about  Kent’s  wife  hav¬ 
ing  a  salesman  match  wall  paint  against 
her  wet  washcloth.  We  can’t  pick  up  a 
copy  of  Turbo  Tech n ix  without  seeing 
Kent’s  name.  His  wide  range  of  inter¬ 
ests  and  his  good  humor  made  his  ap¬ 
peal  broad.  Whether  we  are  interested 
in  C  or  Pascal,  bezier  curves  or  binary 
trees,  we  always  find  Kent  teaching  us 
something. 

We  shared  a  common  vision  with 
Kent  and  each  other  that  has  bound 
us  since  the  early  days.  We  saw  the 
world  around  us  changing  and  felt  we 
had  a  hand  in  those  changes.  Com¬ 
puter  Lib,  Dream  Machines,  the  Com¬ 
munity  Memory  Project,  and  the  Peo¬ 
ple’s  Computer  Company,  with  Dr. 
Dobb’s  cheering  us  all  on  from  its  leaves 
of  scratchy  newsprint.  We  never  minded 
that  Dobb ’s  looked  more  like  the  first 
Whole  Earth  Catalog  than  the  slick  and 
polished  journal  that  would  lead  a  revo¬ 
lution,  changing  the  way  we  work  and 
play  forever.  We  thought  that  we  could 


do  anything.  Through  our  intense  com¬ 
mitment  and  energy  we  could  shape 
and  build  a  world  that  our  parents 
and  our  parents’  parents  couldn’t  even 
imagine. 

Kent’s  death  brings  us  back  to  earth. 
Dreams  are  smashed,  a  friend  is  lost, 
we  remember  our  mortality.  Tributes, 
like  funerals,  are  for  those  left  behind. 
We  don’t  know  how  to  ease  the  way 
we  feel  about  Kent.  Maybe  for  a  mo¬ 
ment  we  can  put  aside  the  petty  rival¬ 
ries  and  the  intense  competition,  and 
remember  that  we  all  live  now  on  a 
tiny  planet,  in  the  global  village  that 
shrinks  daily  in  size.  And  maybe  we 
can  remember  that  the  greatest  thing 
we  can  do  for  our  friends  is  appreciate 
and  affirm  them  now  when  a  kind  word 
can  carry  them  through  a  hard  day 
rather  than  waiting  until  our  voice  can 
no  longer  be  heard. 

We  will  miss  Kent. 

Philippe  Kahn 
Greg  Voss 
Robert  Dickerson 
Anders  Hejlsberg 
Dick  O'Donnell 
Tom  Wu 
Gene  Wang 
Brad  Silverberg 
David  Intersimone 
Gary  Whizin 
Rick  Shell 

—  Borland  International 
Scotts  Valley,  Calif. 


Another  View  from  the  Trenches 

Dear  DDJ, 

When  I  read  the  letter  from  Mr.  Rick 
Rodman  in  the  "Letters”  column  {DDJ, 
July  1989),  I  was  surprised.  I  enjoy  the 
bit-twiddling  articles  just  as  much  as 
the  next  reader.  However,  I  feel  that 
there  are  options  other  than  bit-twid¬ 
dling  and  that  they  should  be  explored 
in  a  forum  such  as  DDJ. 

I  disagree  with  Mr.  Rodman’s  opin¬ 
ion,  “  .  .  .  all  those  object-oriented  para¬ 
digms  aren’t  worth  a  plugged  nickel  in 
the  real  world.  All  that  structured  pro¬ 
gramming  data  abstraction  is  the  wrong 
way  to  go,  too.”  Those  statements  are 
very  general.  While  those  techniques 
have  been  shown  to  improve  many 
aspects  of  programmer  productivity, 
they  are  not  necessarily  useful  in  every 
situation  and  may  not  produce  shorter 
program  execution  times.  Perhaps  the 
type  of  environment  he  is  working  in 
would  not  be  suitable  for  the  use  of 
structured,  object-oriented,  or  other  ad¬ 
vanced  techniques. 

I  enjoy  the  current  format  of  DDJ 
very  much.  I  applaud  the  addition  of 


the  “Graphics  Programming”  column, 
the  OS/2  coverage,  and  the  coverage 
of  other  environments  such  as  the  Mac 
and  Amiga.  I  am  looking  forward  to  the 
coverage  of  OOP  in  general  and  Small¬ 
talk  in  the  “Structured  Programming” 
column.  I  always  manage  to  read  my 
copy  of  DDJ  within  two  days,  starting 
with  “Swaine’s  Flames,”  of  course.  I 
just  can’t  put  it  down!  Keep  up  the 
good  work! 

John  H.  Critchfield,  Jr. 

Duenweg,  Missouri 


keyhit( )  without  MASM 

Dear  DDJ, 

In  addition  to  Al  Stevens’  discussion 
of  the  Control-Break  abort  handling 
with  Microsoft  C  in  the  February  issue, 
here  is  a  version  of  Al’s  keyhitC )  func¬ 
tion  that  is  purely  written  in  MSC  and 
therefore  doesn’t  require  MASM  to  be 
compiled. 

The  following  version  of  keyhitO 
uses  the  ROM  BIOS  keyboard  buffer 
head  and  buffer  tail  pointers:  If  the 
pointers  are  equal,  no  input  from  the 
keyboard  is  pending;  otherwise,  a  key 
has  been  pressed  and  its  ASCII  value  put 
into  the  keyboard  buffer  by  BIOS.  The 
pointers  are  located  in  the  BIOS  data 
area  at  0040:001A  and  0040:001C,  and 
can  easily  be  accessed  using  Al’s  peekC ) 
function.  Here’s  all  there  is  to  it: 

int  keyhitC  void) 

I 

return(peek(0x40,0xla)  != 

peekC 0x40, Oxlc)); 


Ralph  Langner 
Langner  Expertensysteme 
Hamburg,  W  Germany 


Fanning  Mohr’s  Flames 

Dear  DDJ, 

Metz’s  response  to  Mohr’s  flames  {DDJ, 
June  1989)  seems  to  me  to  have  missed 
the  most  important  lesson  inherent  in 
Mohr’s  commentary:  When  we  ignore 
history,  we  are  condemned  not  merely 
to  relive  it,  but  to  suffer  living  in  an 
inferior  version.  RT-11,  and  its  big 
brother  TOPS-10,  are  well-designed  op¬ 
erating  systems  that  run  on  well-de¬ 
signed  hardware.  They  owe  their  suc¬ 
cess  to  a  combination  of  features  that 
are  much  too  rare  in  today’s  micro  world: 

1.  Well-designed,  orthogonal  instruc¬ 
tion  sets  invoked  by  consistent  mne¬ 
monics.  Useful  repertoires  of  address¬ 
ing  modes,  operating  over  linear  ad¬ 
dress  spaces. 
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(continued  from  page  10) 

2.  Uniform  subroutine  calling  conven¬ 
tions  across  a  variety  of  high-level 
languages,  and  consistent,  well-docu¬ 
mented,  operating  system  calls. 

3.  A  consistent,  highly  intuitive  com¬ 
mand-line  syntax,  with  highly  mne¬ 
monic  key  words,  each  of  which  can 
be  abbreviated  to  the  fewest  characters 
which  make  it  unique.  A  well-chosen 
set  of  options  for  each  command,  com¬ 
bined  with  well-chosen  defaults. 

4.  Facilities  for  user  profiling,  file  pro¬ 
tection,  access  control,  and  usage  ac¬ 
counting  that  make  it  easy  to  offer  the 
convenience  of  a  command-line  inter¬ 
face  for  the  programmer  and  the  se¬ 
curity  of  an  idiot-proof  interface  for  the 
naive  user. 

Although  some  of  these  features  have 
been  incorporated  in  micro  operating 
systems,  I’ve  yet  to  see  anything  that 
approaches  the  seamless  implementa¬ 
tion  of  the  DEC  products.  And  let  there 
be  no  doubt  that  the  quality  of  the 
operating  system  strongly  affects  a  pro¬ 
grammer’s  productivity.  Over  a  period 
of  some  twelve  years,  I  watched  a  shop 
running  TOPS-IO  outproduce  a  neigh¬ 
boring  shop  running  VM/CMS,  typically 
by  a  factor  of  about  ten  to  one.  Can 
we  afford  to  discard  such  capable  tools? 

Similar  arguments  apply  to  TECO. 
Yes,  Borland’s  integrated  programming 
environment  is  cozy,  but  on  the  whole, 
full  screen  editors  waste  too  much  time 
in  navigation  and  screen  painting.  For 
a  simple  demonstration,  try  a  global 
search  and  replace  with  CP/M’s  ED, 
and  then  do  the  same  job  with  Word¬ 
star.  It’s  faster  to  copy  a  large  DOS  file 
to  a  CP/M  disk,  do  the  replacement 
with  ED,  and  then  move  the  file  back 
to  the  DOS  machine. 

ED  is,  of  course,  a  greatly  simplified 
version  of  TECO.  It  lacks  TECO’s  con¬ 
ditionals,  flow  control,  Q  registers,  push¬ 
down  list,  bounded  searches,  wildcard 
searches,  etc.  TECO  is  as  much  a  pro¬ 
gramming  language  as  an  editor.  A  small 
subset  of  TECO  is  adequate  for  a  ma¬ 
jority  of  editing  jobs,  but  very  powerful 
tools  are  available  whenever  they  are 
needed.  And  although  TECO  is  an  ex¬ 
tremely  terse  language,  most  of  the  com¬ 
mands  have  highly  mnemonic  one-  or 
two-character  “key  words.” 

One  of  the  Mohr  important  points 
in  Doug’s  letter  is  that  a  program  as 
powerful  as  TECO  can  run  on  a  ma¬ 
chine  as  small  as  a  64K  PDP-11.  In  the 
CP/M  world,  ED  wastes  quite  a  bit  of 
memory  because  it  was  written  in  a 
high-level  language,  but  it  still  runs  in 
less  than  8K.  An  assembly  language 
rewrite  could  roughly  halve  the  RAM 
requirement,  leaving  plenty  of  room 


for  some  of  the  more  esoteric  features 
of  TECO.  I  know  of  at  least  two  people 
who  were  convinced  that  writing  their 
own  versions  of  TECO  for  DOS  ma¬ 
chines  was  a  sound  investment  in  fu¬ 
ture  productivity,  and  I  am  currently 
working  on  a  version  for  CP/M. 

On  a  related  subject,  Jeff  Duntemann’s 
column  in  the  June  issue  leads  me  to 
wonder  why,  after  all  these  years,  we 
still  toy  with  clever  kludges  instead  of 
coding  the  obvious  calendar  algorithm. 
Granted,  the  calendar  display  was  in¬ 
tended  only  to  illustrate  screen  man¬ 
agement  techniques,  but  as  Jeff  himself 
asks,  is  this  angst  really  necessary?  Given 
a  suitable  choice  of  offset  for  the  year, 
16-bits  will  hold  179  years’  worth  of 
days,  and  whose  code  will  survive  that 
long?  Jeffs  simple  function  to  test  for 
leap  years  (certainly  justified  in  this 
application)  suggests  that  he  has  no 
such  expectations.  Why  not  stick  to 
integer  arithmetic?  If  one  really  needs 
an  archaeological  time  scale,  a  LONG- 
INT  will  handle  five  million  years.  And 
in  making  the  primary  test  for  leap 
years,  one  can  save  a  few  machine 
cycles  by  coding 

IF  (Year  AND  3)  =  0  THEN 

Is  LeapYear  :=  TRUE 

If  the  full  leap  year  algorithm  is  re¬ 
quired,  this  logic  can  be  applied  twice, 
once  before  and  once  after  dividing 
by  100. 

And  finally,  endorsing  Mark  Picker- 
ill’s  views  in  June  “Letters,”  do  we  build 
bigger  and  faster  machines,  not  be¬ 
cause  we  need  more  computing  power, 
but  because  it’s  more  comfortable  to 
repeat  the  familiar  mistakes  than  to  risk 
making  new  ones? 

Yours  for  the  more  efficient  use  of 
resources. 

Arpad  Elo,  Jr. 

St.  Johnsbury,  Vermont 


Hal’s  A  Hit 

Dear  DDJ , 

I  have  decided  to  renew  my  subscrip¬ 
tion  to  Dr.  Dobb 's  solely  on  the  basis 
of  Michael  Swaine’s  interview  with  Hal 
Hardenbergh.  I  have  followed  him  over 
the  years  through  DTACK  Grounded, 
and  have  always  admired  him  for  the 
fact  that  (as  I  knew  the  facts)  he  was 
right  MOST  of  the  time.  This,  for  a 
writer,  is  quite  a  record  and  generally 
unsurpassed  by  any  other  writer  whom 
I  read  in  the  computer  field. 

He  is  a  first-rate  engineer,  clearly, 
and  I  cannot  say  the  same  for  any  other 
engineer  who  writes  for  the  public.  It 
was  a  pleasure  to  see  his  existence 


recognized  by  Dr.  Dobb’s-,  does  this 
mean  Dr.  Dobb’s  is  “cutting  through 
the  crap”  also?  I  can  now  hope  to  learn 
more  about  AI  through  Hardenbergh’s 
incisive  analytical  powers:  either  in  Dr. 
Dobb’s  or  Programmer’s  Journal. 

Swaine’s  was  a  very  good  interview  — 
keep  up  the  good  work!  Maybe  there 
is  hope  after  all. 

John  Griffith 
Yorktown  Hts.,  N.Y. 


Superlinearity,  Smoke  or  Mirrors 

Dear  DDJ , 

In  the  July  DDJ  “Letters”  department 
was  a  letter  entitled  “Superlinearity  with¬ 
out  Mirrors.”  Phil  might  not  be  using 
mirrors,  but  he  is  certainly  using  slight- 
of-hand  [sic].  The  example  he  described 
is  not  a  demonstration  of  superlinearity, 
but  a  reasoning  fallacy. 

Reviewing  the  example,  Phil  says  that 
one  processor  will  require  (  j+x)  steps, 
and  ten  processors  will  require  x  steps 
per  processor,  or  lOx  total. 

But  this  has  nothing  to  do  with  mul¬ 
tiple  processors,  and  everything  to  do 
with  the  fact  that  he  changed  the  search 
order.  If  he  had  one  processor  search¬ 
ing  the  first  element  in  each  of  ten 
partitions,  then  the  second  element  in 
each,  etc.,  he  would  get  the  same  re¬ 
sults  as  his  multiprocessor  system. 
Likewise,  if  his  first  processor  gets  ele¬ 
ments  0,  10,  20,  .  .  .  the  second  gets  1, 
11,  21,  .  .  .  etc.,  he  would  get  the  same 
results  as  his  uniprocessor. 

The  point  is  that  the  location  of  the 
match  is  random.  What  he  actually  dem¬ 
onstrated  is  that  for  some  values,  search¬ 
ing  in  one  order  will  find  the  value 
sooner  than  searching  in  another  order. 

It  does  not  matter  what  order  is  used, 
since  they  all  average  out  anyway.  So 
you  will  use  a  search  order  that  mini¬ 
mizes  the  overhead  of  the  search. 

John  M.  Dlugosz 

Plano,  Texas 


DDJ 


We  welcome  your  comments  (and  sug¬ 
gestions).  Mail  your  letters  to  DDJ,  501 
Galveston  Dr.,  Redwood  City,  CA  94063, 
or  send  them  electronically  to  Compu¬ 
Serve  76704,50  or  via  MCI  Mail,  c/o 
DDJ.  Please  include  your  name,  city, 
and  state.  We  reserve  the  right  to  edit 
letters. 
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Autorouting  with  the 

A*  Algorithm 

Searching  for  the  best  PC  board  layout 


Randy  Nevin 


A  few  years  ago,  a  friend  of  mine  designed  an  adapter 
board  for  the  IBM  PC.  The  tools  he  used  were  blue 
and  red  strips  of  tape,  a  sharp  knife,  large  sheets  of 
clear  plastic,  and  a  generous  amount  of  patience.  It 
took  him  several  weeks,  and  after  the  first  board 
was  tested  he  discovered  that  some  of  the  traces  were 
incorrect  and  had  to  be  cut  with  the  knife  and  rerouted  with 
a  solder  and  wires.  This  caused  me  to  start  thinking  about 
ways  to  use  the  power  of  the  computer  to  simplify  this 
tedious,  error-prone  job. 

The  design  of  a  printed  circuit  board  implements  an 
electronic  circuit.  First  you  create  a  schematic.  From  this  you 
derive  a  list  of  chips  and  other  components  that  perform  the 
required  functions,  and  a  list  of  the  pins  that  need  to  be 
connected.  Together,  these  lists  are  referred  to  as  the  “net- 
list.”  As  long  as  the  connections  are  made  correctly,  you 
usually  don’t  care  where  the  traces  (the  wires  embedded  in 
the  board)  are  placed. 

As  you  can  imagine  (or  may  already  know),  designing  a 
PC  board  is  a  complex  search  problem  with  a  seemingly 
infinite  number  of  possible  solutions.  Luckily,  there  are 
algorithms  from  the  field  of  artificial  intelligence  that  we  can 
use  to  design  computer  programs  called  “autorouters”  that 
do  this  searching  for  you.  In  this  article,  I’ll  look  at  two 
algorithms:  The  breadth-first  and  A*  (pronounced  as  “A 
Star”)  search  algorithms.  This  article  is  actually  based  on  an 
application  I  wrote  to  layout,  view,  and  laser-print  circuit 
board  designs.  Because  of  the  length  of  that  application 
(nearly  2500  lines  of  C  code),  I’ll  focus  my  discussion  here 
on  the  pseudocode  that  implements  the  two  algorithms 


Randy  holds  a  BS  in  computer  science  from  Oregon  State 
University  and  an  MS  in  computer  science  from  the  Univer¬ 
sity  of  Washington.  He  has  worked  for  Microsoft  since  1983 
on  various  programming  languages  and  networking  prod¬ 
ucts.  He  can  be  reached  at  1731  211th  PL  NE,  Redmond, 
WA  98053- 


mentioned  and  the  source  code  that  implements  the  A* 
algorithm.  The  entire  C  source  code  that  implements  the 
printed  circuit  board  layout  system  is  available  on  DDJ s 
Forum  on  CompuServe,  DDJ s  on-line  service,  and  on  the 
disks  mentioned  at  the  end  of  this  article. 

What  1$  Autorouting? 

Autorouting  is  one  of  a  class  of  global  optimization  prob¬ 
lems  that  are  difficult  to  solve.  A  good  circuit  board  layout, 
for  example,  minimizes  things  like: 

•  Physical  problems  (trace  lengths,  board  size,  number  of 
routing  holes,  holes  that  transfer  a  trace  from  one  side  of 
the  board  to  the  other,  also  called  vias) 

•  Signal  crosstalk 

•  Number  of  layers 

At  the  same  time,  the  layout  maximizes  things  like  signal 
strength,  reliability,  and  ease  of  debugging.  The  overall 
value  of  a  board  design  is  a  function  of  all  of  these  often 
conflicting  variables.  It  is  usually  acceptable  to  find  a  solu¬ 
tion  that  satisfies  a  set  of  constraints,  because  finding  the 
globally  optimal  solution  is  infeasible  for  all  but  the  most 
trivial  problems. 

Autorouting  can  also  be  viewed  as  a  collection  of  search 
problems.  The  individual  problems  deal  with  finding  a  route 
and  laying  down  a  trace  between  two  locations.  There  are 
many  algorithms  for  solving  search  problems,  each  with 
different  running  time  characteristics  and  data  space  re¬ 
quirements. 

Autorouting  search  algorithms  typically  operate  in  two 
phases1,  treating  the  board  as  a  matrix  of  cells.  The  first 
phase  starts  at  the  source  cell  and  searches  for  the  target 
cell,  usually  by  going  in  several  directions  at  the  same  time. 
The  algorithm  builds  an  auxiliary  data  structure  to  keep 
track  of  how  each  cell  was  reached  (this  is  referred  to  as 
“Pred”  in  the  algorithms  in  Figures  1  and  2).  The  first  phase 
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ends  when  the  target  cell  has  been  found,  and  the  second 
phase  begins.  If  the  first  phase  exhausts  all  possibilities 
without  reaching  the  target  cell,  then  no  route  exists  be¬ 
tween  them,  and  there  is  no  reason  to  do  the  second  phase. 

The  second  phase  uses  the  auxiliary  data  structure  to 
trace  the  route  from  the  target  cell  back  to  the  source  cell, 
actually  laying  down  the  electrical  connections.  The  second 
phase  is  identical  for  the  breadth-first  and  A*  search  algo¬ 
rithms.  But  the  first  phase  is  different,  and  it  is  this  phase 
that  gives  these  algorithms  different  behaviors. 

The  main  data  structures  used  in  the  first  phase  are  the 
Open  queue  and  the  Closed  set,  which  hold  cell  coordi¬ 
nates.  Because  a  cell’s  coordinates  uniquely  identify  it,  we’ll 
say  that  the  Open  queue  and  Closed  set  contain  cells.  Cell 
coordinates  will  be  represented  as  r2c3sl  for  the  cell  at  row 
2,  column  3,  side  1,  or  as  r2c3  when  it  is  understood  that  all 
cells  are  on  the  same  side  of  the  board.  To  remind  ourselves 
that  Open  is  a  queue  and  Closed  is  a  set,  when  we  talk  about 
adding  cells  to  them,  we  will  put  the  cells  “on”  the  queue 
and  “in”  the  set.  Initially,  the  Open  queue  contains  the 
source  cell  and  the  Closed  set  is  empty. 

The  first  phase  is  a  loop,  which  removes  an  element  from 
the  head  of  the  Open  queue,  puts  it  in  the  Closed  set  (which 
indicates  that  it  has  been  searched),  and  checks  to  see  if  it 
is  the  target  cell.  If  so,  the  first  phase  is  done.  Otherwise,  the 
neighbors  of  the  cell  (those  adjacent  to  it)  are  placed  on  the 
Open  queue,  and  the  loop  continues.  As  we’ll  see  later,  the 
essential  difference  in  the  breadth-first  and  A*  search  al¬ 
gorithms  is  the-  order  in  which  the  neighbors  are  placed  on 
the  Open  queue. 

Breadth-First  Search 

Figure  1  contains  pseudocode  for  the  breadth-first  search 
algorithm.  This  algorithm  works  by  processing  a  first  in/first 
out  (FIFO)  queue  of  open  cells;  that  is,  cells  that  have  been 
reached,  but  not  yet  searched.  Initially,  the  open  queue 
contains  only  the  source  cell.  A  cell  is  removed  from  the 


head  of  the  open  queue,  placed  in  the  set  of  closed  cells 
(cells  that  have  been  searched),  and  checked  to  see  if  it  is 
the  target  cell.  If  not,  its  neighbors  are  placed  at  the  tail  of 
the  open  queue.  Neighboring  cells  that  have  already  been 
reached  are  ignored.  (If  a  cell’s  coordinates  are  on  the  open 
queue  or  in  the  closed  set,  then  it  has  been  reached,  other¬ 
wise,  it  has  not.)  This  continues  until  one  of  two  things 
happens: 

•  The  target  cell  has  been  found 

•  The  open  queue  is  empty,  in  which  case  the  target  cannot 
be  reached  from  the  source  cell 


BFS  Algorithm  (*  breadth-first  search  *) 

(*  Search  a  graph  or  state  space,  depending  on  the  problem 
definition. *) 

(*  S  is  the  start  node,  T  is  the  goal  node.  *) 

(*  Open  is  an  ordered  list  of  nodes  (ordered  by  arrival  time; 
nodes  enter  at  the  tail  and  leave  at  the  head) ,  also  called  a 
queue.  Closed  is  a  set  of  nodes  (order  doesn't  matter).  In 
general,  nodes  that  need  to  be  searched  are  put  on  Open.  As  they 
are  searched,  they  are  removed  from  Open  and  put  in  Closed.  *) 

(*  Pred  is  defined  for  each  node,  and  is  a  list  of  "came  from" 
indications,  so  when  we  finally  reach  T,  we  traverse  Pred  to 
construct  a  path  to  S.  *) 

1  Open  <-  { S }  (*  a  list  of  one  element  *) 

Closed  <-  ( )  (*  the  empty  set  *) 

Pred[S]  <-  NULL,  found  <-  FALSE 
WHILE  Open  <>  { )  and  not  found  DO 
5  x  <-  the  first  node  on  Open 

Open  <-  Open  -  { x )  (*  remove  x  from  Open  *) 

Closed  <-  Closed  +  { x  >  (*  put  x  in  Closed  *) 

IF  x  *  T  THEN  found  <-  TRUE  (*  we're  done  *) 

ELSE  (*  continue  search  through  node  x  *) 

10  let  R  be  the  set  of  neighboring  nodes  of  x 

FOR  each  y  in  R  DO 

IF  y  is  not  on  Open  or  in  Closed  THEN 

Predfy]  <-  x  (*  remember  where  we  came  from  *) 

Open  <-  Open  +  (y)  (*  put  y  on  Open  (at  the  tail)  *) 

15  IF  found  THEN 

use  Pred[T]  to  find  Pred[Pred ( T ] ]  and  so  on  until  S  is  reached 
(*  this  traces  out  the  solution  path  in  reverse  *) 

ELSE  T  cannot  be  reached  from  S 


Figure  1:  Pseudocode  for  the  breadth-first  algorithm 
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Figure  2:  Behavior  of  Lee’s  algorithm  while  searching 
for  a  path 


A  version  of  breadth-first  search  known  as  Lee’s  algorithm2 
has  served  as  the  basis  for  some  autorouters  since  the  early 
1960s.  The  original  algorithm  does  not  consider  diagonally 
adjacent  cells  as  neighbors,  and  consequently,  the  back¬ 
tracking  phase  can  create  only  horizontal  and  vertical  traces. 
We’ll  enhance  the  algorithm  so  that  diagonally  adjacent  cells 
are  neighbors,  thus  enabling  it  to  produce  diagonal  traces. 
Unfortunately,  Lee’s  algorithm  suffers  from  a  behavior  in¬ 
herent  in  the  breadth-first  search  technique,  which  limits 
its  application  to  problems  of  relatively  small  size.  As  the 
distance  between  the  source  and  target  cells  increases  by 
a  factor  of  N,  the  number  of  cells  processed  by  Lee’s  algo¬ 
rithm  —  and  therefore  processing  time  —  increases  by  the 
square  of  N. 

Figure  2  shows  the  behavior  of  Lee’s  algorithm  while 
searching  for  a  path  between  the  source  cell  S  ( r5c5 )  and 
the  target  cell  T  (r8c8).  Lee’s  algorithm  does  not  specify  the 
order  in  which  neighboring  cells  are  placed  on  the  open 
queue,  but  we’ll  use  the  compass  directions  north,  east, 
south,  and  west,  followed  by  northeast,  southeast,  south¬ 
west,  and  northwest.  This  order  tends  to  produce  traces 
with  a  minimal  number  of  turns. 

In  Figure  2a,  the  source  cell  (r5c5)  has  been  searched, 
and  its  eight  neighbors  have  been  placed  on  the  open 
queue.  The  arrows  indicate  the  direction  from  which  each 
cell  was  reached,  and  correspond  to  the  Pred  data  structure. 
After  the  first  eight  cells  on  the  open  queue  have  been 
reached  and  moved  to  the  closed  set,  the  algorithm  searches 
the  configuration  in  Figure  2b,  where  there  are  sixteen  cells 
on  the  open  queue.  Once  these  sixteen  cells  have  been 
searched,  the  configuration  in  Figure  2c  is  reached.  Now  the 


target  cell  (r8c8)  is  fourth  from  the  end  on  the  open  queue, 
and  a  solution  is  imminent.  Searching  r8c8,  the  algorithm 
recognizes  it  as  the  target  cell,  and  uses  the  Pred  data 
structure  to  construct  a  trace  back  to  the  source  cell. 

You  can  see  that  the  search  progresses  outward  from  the 
source  cell  in  all  directions,  like  ripples  when  you  throw  a 
pebble  into  the  water.  If  we  double  the  size  of  the  problem 
so  that  S  and  T  are  six  cells  apart,  the  number  of  cells 
searched  and  therefore  the  processing  time  will  be  about 
four  times  as  great.  If  we  triple  the  size  of  the  problem,  the 
number  of  cells  searched  will  be  roughly  nine  times  more. 
Thus,  the  behavior  of  Lee’s  algorithm  is  quadratic  in  the  size 
of  the  problem,  which  makes  it  infeasible  for  large  problems. 

A*  Search 

Figure  3  gives  pseudocode  for  the  A*  search  algorithm, 
while  Listing  One,  page  82,  shows  it  implemented  in  C.  This 
method  also  works  by  processing  a  queue  of  open  cells, 
which  initially  contains  only  the  source  cell.  But  this  is  a 
priority  queue,  which  means  cells  are  inserted  according  to 
the  estimated  distance  to  the  target3,  not  just  at  the  end.  Cells 
that  are  on  the  shortest  estimated  path  from  source  to  target 
go  to  the  head  of  the  queue.  The  A*  algorithm  removes  the 
cell  from  the  head  of  the  open  queue  and  checks  to  see  if 
it’s  the  target.  If  not,  the  neighboring  cells  are  put  on  the 
open  queue  at  the  proper  position.  The  algorithm  checks 
neighboring  cells  that  have  already  been  searched  to  see  if 
the  new  path  between  them  and  the  source  is  shorter  than 
the  previous  one.  If  it  is,  they  are  repositioned  on  the  open 
queue  according  to  the  new  estimated  path  length  from 
source  to  target.  As  in  breadth-first  search,  this  continues 


A*  Algorithm  (*  heuristic  search  *) 

(*  Search  a  graph  or  state  space,  depending  on  the  problem 
definition.*) 

(*  S  is  the  start  node,  T  is  the  goal  node.  *) 

(*  Open  is  an  ordered  list  of  nodes  (ordered  by  lowest  F  value; 
see  below),  also  called  a  priority  queue.  Closed  is  a  set  of 
nodes  (order  doesn't  matter).  In  general,  nodes  that  need  to  be 
searched  are  put  on  Open  (at  the  proper  position) .  As  they  are 
searched,  they  are  removed  from  Open  and  put  in  Closed. 
Occasionally  a  newer,  better  route  will  be  found  to  a  node  after 
it  has  already  been  searched,  in  which  case  we  remove  it  from 
Closed  and  put  it  back  on  Open  to  be  reconsidered.  *) 

(*  G[x)  is  the  distance  already  traveled  to  get  from  S  to  node  x, 
and  is  known  exactly.  H(x)  is  a  function  (heuristic)  which 
returns  an  estimate  of  the  distance  from  node  x  to  T.  F [ x)  is 
the  estimated  distance  from  S  to  T  by  going  through  node  x,  and 
is  computed  by  F[x]  =  G[x]  +  H(x).  H(x)  can  be  calculated  for 
any  node,  but  F[x]  and  G[x]  only  become  defined  when  node  x  is 
visited.  *) 

(*  Pred  is  defined  for  each  node,  and  is  a  list  of  "came  from" 
indications,  so  when  we  finally  reach  T,  we  traverse  Pred  to 
construct  a  path  to  S.  *) 

(*  Distance (x, y)  is  a  function  for  calculating  the  distance 
between  two  neighboring  nodes.  *) 

1  Open  <-  { S )  (*  a  list  of  one  element  *) 

Closed  <-  { )  (*  the  empty  set  *) 

G(S]  <-  0,  F [S]  <-  0,  Pred[S]  <-  NULL,  found  <-  FALSE 
WHILE  Open  <>  ()  and  not  found  DO 

5  x  <-  the  first  node  on  Open  (*  node  with  smallest  F  value  *) 

Open  <-  Open  -  { x }  (*  remove  x  from  Open  *) 

Closed  <-  Closed  +  { x )  (*  put  x  in  Closed  *) 

IF  x  «=  T  THEN  found  <-  TRUE  (*  we're  done  *) 

ELSE  (*  continue  search  through  node  x  *) 

10  let  R  be  the  set  of  neighboring  nodes  of  x 

FOR  each  y  in  R  DO 

IF  y  is  not  on  Open  or  in  Closed  THEN 
G ly]  <-  G(x]  +  Distance (x,y) 

F[yj  <-  G[y)  +  H(y)  (*  estimate  solution  path  length  *) 
15  Pred[yl  <-  x  (*  remember  where  we  came  from  *) 

Open  <-  Open  +  |y)  (*  put  y  on  Open  *) 

ELSE  (*  y  is  on  Open  or  in  Closed  *) 

IF  (G ( x ]  +  Distance (x, y) )  <  G ( y ]  THEN 
{*  we've  found  a  better  route  to  y  *) 

20  G[y]  <-  G [x]  +  Distanced, y) 

F[y]  <-  G [y]  +  H(y) 

Pred(y]  <-  x  (*  remember  where  we  came  from  *) 

IF  y  is  on  Open  THEN 

reposition  y  according  to  F(y) 

25  ELSE  (*  y  is  in  Closed  *) 

Closed  <-  Closed  -  (y)  (*  remove  y  from  Closed  *) 

Open  <-  Open  +  (y)  (*  put  y  on  Open  *) 

IF  found  THEN 

use  Pred(T)  to  find  Pred[Pred(T) )  and  so  on  until  S  is  reached 
30  (*  this  traces  out  the  solution  path  in  reverse  *) 

ELSE  T  cannot  be  reached  from  S 


Figure  3:  Pseudocode  for  the  A  *  algorithm 
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(continued  from  page  19) 

until  the  target  cell  has  been  found  or  the  open  queue  is 
empty. 

A*  depends  on  being  able  to  estimate  the  distance  between 
a  cell  and  the  target  cell.  In  the  case  of  autorouting,  a  simple 
measure  of  this  distance  is  available,  and  this  helps  A*  to 
concentrate  the  search  in  the  direction  most  likely  to  suc¬ 
ceed.  The  more  accurate  the  estimate,  the  faster  the  search. 

In  practice,  A*  does  not  suffer  from  the  quadratic  behavior 
of  Lee’s  algorithm,  it  solves  similar  problems  faster  and  can 
be  applied  to  larger  problems  where  Lee’s  algorithm  per¬ 
forms  poorly.  As  the  distance  between  the  source  and  target 
cells  increases,  the  number  of  cells  processed  by  A*  in¬ 
creases,  but  not  as  dramatically  as  with  Lee’s  algorithm. 

Figure  4  shows  the  behavior  of  the  A*  search  algorithm. 
A*  does  not  specify  whether  new  cells  go  in  front  of  or 

A*  trades  off  memory 
against  processing 
time  to  achieve  better 
performance 


behind  cells  already  on  the  open  queue  that  evaluate  to 
identical  estimated  path  lengths.  We  use  the  convention 
that  they  are  placed  in  front.  This  minimizes  the  time  to 
insert  a  cell  on  the  open  queue. 

In  Figure  4a,  the  source  cell  ( rjc3)  has  been  searched,  and 
its  eight  neighbors  are  on  the  open  queue.  Each  cell  on  the 
open  queue  also  includes  the  estimated  length  of  the  short¬ 
est  path  from  Sto  Tthat  goes  through  that  cell.  After  the  first 
cell  ( r4c4 )  has  been  searched  and  moved  to  the  closed  set, 
the  configuration  in  Figure  4b  is  reached,  where  there  are 
12  cells  on  the  open  queue.  After  searching  the  next  cell 
(r5c5),  the  algorithm  reaches  the  configuration  in  Figure  4c. 
Now  the  target  cell  ( r6c6)  is  at  the  head  of  the  open  queue, 
and  a  solution  will  be  found  on  the  next  iteration  of  the  loop. 
Searching  r6c6,  A*  recognizes  it  as  the  target  and  uses  the  Pred 
data  structure  to  construct  a  trace  back  to  the  source  cell. 

You  can  see  that  the  search  progresses  more  directly 
toward  the  target  cell.  The  target  draws  the  search  much  as 
the  earth’s  gravity  pulls  objects  toward  the  center  of  mass. 
If  we  double  the  size  of  the  problem,  the  search  will  process 
about  twice  as  many  cells,  and  if  we  triple  its  size,  the  search 
will  run  through  three  times  as  many.  This  linear  behavior 
makes  A*  more  attractive  for  autorouting  than  the  quadratic 
Lee’s  algorithm.  With  the  incorporation  of  the  heuristic  — 
the  rule,  that  guides  the  search  in  the  direction  most  likely 
to  succeed — it  is  difficult  to  estimate  worst  case  behav¬ 
ior.  However,  A*  will  never  take  more  time  than  Lee’s 
algorithm,  and  it  will  never  search  any  cells  that  Lee’s  algo¬ 
rithm  could  avoid. 

Optimizations  and  Generalizations 

The  algorithms  in  Figures  1  and  3  solve  the  general  search 
problem.  When  these  algorithms  are  implemented  and  cus¬ 
tomized  to  a  particular  application,  there  are  ways  to  speed 
them  up. 

The  A*  algorithm  in  Figure  3  recomputes  the  heuristic 
H(y)  when  it  discovers  a  better  way  to  reach  a  cell.  Depend¬ 


ing  on  how  difficult  this  heuristic  is  to  compute,  you  can 
probably  save  some  work  at  the  expense  of  complicating 
the  algorithm.  When  lines  20  and  21  of  Figure  3  are  exe¬ 
cuted,  the  previous  values  of  G!y]  and  F[y]  are  destroyed. 
But  Fly]  =  Gfy]  +  H(y •),  so  you  could  save  Fly]  -  G[y]  (which 
is  H(y)]  in  a  temporary  variable,  and  use  that  variable 
instead  of  recomputing  H(y)  on  line  21.  Also,  the  common 
sub-expression  G[x]  +  Distance(x,y)  should  be  placed  in  a 
temporary  variable,  instead  of  being  computed  twice  (lines 
18  and  20). 

Often,  rather  than  searching  for  a  path  between  two 
individual  cells,  what  is  really  desired  is  a  path  between  one 
of  a  set  of  source  cells  and  one  of  a  set  of  target  cells  (as 
when  connecting  power  and  ground  pins).  Both  algorithms 
can  be  modified  by  adding  the  entire  set  of  source  cells  to 
the  initial  open  queue,  and  checking  for  a  member  of  the 
set  of  target  cells  on  each  iteration.  When  this  is  done,  the 
heuristic  used  by  the  A*  algorithm  becomes  more  compli¬ 
cated.  It  must  estimate  the  minimum  distance  from  the 
current  cell  to  any  one  of  the  target  cells. 

For  breadth-first  search,  once  the  target  cell  is  placed  on 
the  open  queue,  it  is  pointless  to  add  any  more  cells  to  the 
open  queue  because  when  this  happens,  the  problem  is 
solved.  An  appropriate  shortcut  would  be  to  insert  a  check 
before  line  13  in  Figure  I  to  see  if  y  is  the  target  cell.  If  it  is, 
use  Predly] to  construct  the  trace  back  to  the  source  cell,  and 
return. 

Memory  Requirements 

Both  search  algorithms  use  quite  a  bit  of  memory  to  solve 
problems  of  non-trivial  size.  The  breadth-first  search  al¬ 
gorithm  needs  memory  to  represent  the  board,  the  prede¬ 
cessor  structure,  and  the  closed  set.  The  A*  search  algorithm 
needs  these  also,  plus  structures  for  Fix]  and  GfxJisee  Figure 
3).  In  addition,  both  algorithms  dynamically  allocate  mem¬ 
ory  for  the  open  cell  queue. 
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Figure  4:  Behavior  of  the  A*  search  algorithm 
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(continued  from  page  20) 

The  board  is  represented  as  a  pair  of  two-dimensional 
arrays  —  one  for  the  front  side,  the  other  for  the  back  —  in 
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Figure  5:  Trace  lengths  in  a  50-mil  cell 


which  the  dimensions  are  the  number  of  rows  and  columns 
of  cells.  Not  counting  holes  and  traces  relating  to  holes 
(Figure  5,  groups  A,  B,  and  C),  there  are  30  possible  cell 
contents,  which  can  be  represented  with  5  bits  per  cell. 

The  hole-related  cells  are  more  difficult  to  enumerate; 
they  can  be  combined  in  many  ways.  If  we  simply  assign  1 
bit  to  each  of  the  eight  traces  in  groups  B  and  C,  and  add 
one  more  bit  to  indicate  a  hole,  14  bits  will  be  sufficient  to 
represent  any  cell.  On  a  board  of  N  rows  and  M  columns, 
we’ll  need  N*M*28  bits  total. 

The  predecessor  structure  is  also  a  pair  of  two-dimen¬ 
sional  arrays,  where  an  entry  must  be  able  to  represent  one 
of  the  eight  compass  directions  or  an  indication  for  the 
opposite  side  of  the  board.  This  takes  4  bits  per  cell,  or 
N*M*8  bits  total. 

The  closed  set  can  be  represented  by  a  pair  of  two- 
dimensional,  single-bit  arrays,  where  a  bit  is  one  if  the 
corresponding  cell  has  been  searched,  and  zero  otherwise. 
This  will  take  N*M*2  bits  total. 

F[x]  and  G[x]  will  be  similar  to  the  board  arrays,  but  they 
must  contain  a  16-bit  integer  for  each  cell,  requiring  N*M*64 
bits  total.  Note  that  if  memory  usage  needs  to  be  minimized 
at  the  cost  of  increased  processing  time,  we  could  omit  the 
F[x]  arrays,  and  calculate  the  F  values  as  they  are  needed 
from  the  G[x]  arrays  and  the  heuristic  function,  H(x). 

Breadth-first  search  thus  requires  N*M*38  bits,  and  A* 
needs  N*M*102  bits  of  static  memory.  For  a  printed  circuit 
board  4  x  13  inches  (80  cells  x  260  cells),  breadth-first 
search  will  need  98,800  bytes  and  A*  will  need  265,200 
bytes.  Different  algorithms  that  solve  the  same  problem 
often  trade  off  memory  against  processing  time  to  achieve 
better  performance.  This  is  the  case  with  A*  versus  the 
breadth-first  search. 


Distance  Calculations 


The  A*  search  algorithm  uses  a  heuristic  to  estimate  the 
distance  between  the  current  cell  and  the  target  cell.  As 
implemented  in  the  autorouting  program,  the  heuristic  is 
a  simple  geometric  distance  approximation.  Figure  5  illus¬ 
trates  all  the  possible  cell  types  used  to  construct  a  trace, 
grouped  by  type.  For  each  group,  the  distance  of  that  cell 
type  is  also  given.  These  distances  are  calculated  based 
on  a  cell  size  of  50  x  50  mils.  (A  mil  is  1/1000  inch,  so  the 
autorouter  uses  20  cells/inch.  A  typical  full-length  adapter 
board  for  an  IBM  PC  is  4-inches  high  and  13-inches  long, 
or  80-cell  rows  x  260-cell  columns.) 

The  group  B  and  C  traces  can  coexist  in  the  same  cell, 
so  a  hole  can  have  up  to  16  traces  connecting  it  with 
other  cells  (eight  on  each  side  of  the  board).  Also,  the 
parallel  traces  of  group  F  can  coexist  in  the  same  cell  (on 
the  same  side  of  the  board),  as  shown  by  group  J.  This 
allows  the  routing  of  two  traces  through  the  same  cell, 
providing  the  higher  density  required  by  some  circuits 
(memory  arrays,  for  example).  Aside  from  these  excep¬ 
tions,  cells  can  only  contain  one  trace  type  (on  each  side 
of  the  board). 

To  determine  the  approximate  distance  of  a  trace  that 
will  connect  two  holes,  view  the  board  as  a  matrix,  the 
differences  in  cell  coordinates  are  three  rows  and  five 
columns.  The  shortest  path  between  them  will  use  a  diago¬ 
nal  trace  across  three  cells  and  a  horizontal  trace  across 
two  cells.  Using  the  cell  types  in  Figure  5,  the  length  of  the 
trace  will  be  23  +  (2  *  71)  +  60  +  50  +  12  =  287  mils.  A  trace 
that  uses  a  routing  hole  to  go  from  one  side  of  the  board 
to  the  other  covers  a  greater  distance  than  one  that  goes 


diagonally  across  a  cell  (group  E  in  Figure  5)  and  stays  on 
the  same  side  of  the  board  because  part  of  its  path  goes 
around  the  edge  of  a  circle. 

A  typical  hole  is  25  mils  in  diameter,  and  is  at  the  center 
of  a  cell.  To  calculate  the  distance  of  a  trace  through  a 
routing  hole,  measure  the  section  of  the  hole  between  the 
two  connecting  traces.  For  instance,  an  entering  trace  can 
connect  to  a  hole  at  a  point  A,  and  possible  exiting  traces 
on  the  opposite  side  of  the  board  at  points  B,  C,  D,  and  E. 
The  distances  between  A  and  each  of  these  points  are  10, 
20,  29,  and  39  mils,  respectively.  To  calculate  these,  use 
the  geometric  formula  Circumference  =  PI  *  Diameter 
(approximately  78.5  mils)  and  divide  by  8  (a  1/8  section 
of  a  hole  is  approximately  9.8  mils),  add  1,  2,  3,  and  4  of 
these  sections,  then  round  off  to  an  integer. 

The  heuristic  in  the  autorouting  program  includes  a 
penalty  when  a  trace  takes  a  turn  or  switches  to  the  other 
side  of  the  board  through  a  routing  hole  because  turns  are 
often  the  weak  points  in  a  circuit,  and  traces  are  more 
likely  to  break  at  a  turn  than  in  a  straight  part.  The  penalty 
encourages  A*  to  use  straight  lines,  and  even  allows  a 
slightly  longer  trace  to  be  selected  over  one  with  too  many 
turns.  The  amount  of  penalty  depends  on  the  kind  of  turn; 
sharper  turns  are  assessed  a  larger  penalty.  Routing  holes 
incur  a  significant  penalty,  since  overusing  them  early  in 
the  routing  process  can  make  later  traces  more  difficult  or 
even  impossible  to  construct  because  a  routing  hole  dedi¬ 
cates  a  cell  exclusively  to  a  single  trace,  for  both  sides  of 
the  board.  Such  a  cell  is  not  available  to  later  routing,  thus 
reducing  the  total  number  of  cells  that  can  be  used.  —  R.N. 
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Locality  of  Reference 

Despite  the  fact  that  A*  requires  more  memory  than  breadth- 
first  search,  A*  exhibits  better  memory  usage  patterns.  This 
is  because  it  shows  better  locality  of  reference  than  breadth- 
first  search.  Locality  of  reference  deals  with  the  sequence 
in  which  memory  locations  are  used,  and  consists  of  two 
rules  of  thumb:  1.  The  memory  location  currently  being 
referenced  is  likely  to  be  referenced  again  in  the  near  future, 
and  2.  Memory  locations  near  the  one  currently  being  refer¬ 
enced  are  likely  to  be  referenced  in  the  near  future. 

When  the  first  rule  holds  true  for  a  given  program,  that 
program  can  probably  benefit  from  a  memory  cache.  When 
the  second  rule  holds  true,  the  program  can  probably  bene¬ 
fit  from  a  virtual  memory  environment  with  a  least-recently- 
used  page  preemption  policy.  Most  computer  systems  with 
virtual  memory  and  caches  apply  them  to  both  code  and 
data,  so  programs  that  exhibit  good  locality  of  reference 
should  benefit  from  both  rules. 

This  becomes  a  factor  when  solving  large  problems  (say, 
routing  a  printed  circuit  board  that  is  10  inches  in  both 
dimensions).  In  a  virtual  memory  environment,  improved 
locality  of  reference  can  minimize  swapping.  In  an  environ¬ 
ment  with  cache  memory,  improved  locality  of  reference 
can  increase  the  cache  hit  rate.  Both  of  these  tend  to  de¬ 
crease  the  total  running  time. 

The  memory  references  in  the  breadth-first  search  algo¬ 
rithm  go  around  and  around  in  circles  of  constantly  increas¬ 
ing  size,  and  do  not  reflect  a  common  locality  of  reference. 
Thus,  the  breadth-first  search  algorithm  is  not  able  to  take 
good  advantage  of  virtual  memory  or  a  memory  cache.  The 
memory  references  of  A*  tend  to  be  from  the  same  area  of 
the  printed  circuit  board  for  extended  periods  of  time, 
taking  better  advantage  of  these  mechanisms.  In  a  large 
problem,  this  helps  to  offset  the  extra  memory  that  A* 
requires  by  adding  speed  beyond  that  provided  by  the  basic 
algorithm.  Improved  locality  of  reference  by  itself  may  not 
be  a  sufficient  reason  to  select  A*  over  breadth-first  search, 
but  it  is  icing  on  the  cake. 
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Simulated 

Annealing 

This  algorithm  may  be  one  of  the  best  solutions  to  the 
problem  of  combinatorial  optimization 


Michael  P.  McLaughlin 


In  science  and  engineering,  it 
is  a  truism  that,  in  any  real 
system,  everything  is  con¬ 
nected.  Indeed,  you  could  do 
far  worse  than  to  define  sci¬ 
ence  as  the  search  for  such  con¬ 
nections.  Scientists  accorded  the 
highest  esteem,  those  names  nearly 
everyone  knows,  are  generally  in¬ 
dividuals  whose  insight  allowed 
them  either  to  forge  links  between 
a  large  number  of  separate  con¬ 
cepts  or  to  find  a  connection  that 
no  one  had  suspected. 

Occasionally,  something  similar 
happens  on  a  smaller  scale.  This 
article  concerns  the  application  of 
statistical  mechanics  to  the  solu¬ 
tion  of  a  difficult  problem  in  com¬ 
puter  science.  The  problem  is  com¬ 
binatorial  optimization;  the  tech¬ 
nique  is  called  “simulated  annealing.” 

Combinatorial  optimization  is  the  task 
of  taking  a  finite  number  of  indivisible 
“objects”  and  arranging  them  in  a  con¬ 
figuration  that  is  “best”  according  to 
some  stipulated  criteria.  For  instance, 
how  should  15  swimmers  be  selected 
from  a  team  of  30,  for  an  upcoming 
meet,  if  no  one  is  allowed  to  enter 
more  than  one  event?  Or  how  should 
aircraft,  preparing  to  land,  be  sequenced 
in  order  to  minimize  delays?  What  is 
the  best  routing  for  a  telephone  call 
from  Boston  to  San  Francisco  at  any 
given  moment?  What  is  the  best  parse 
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technical  staff,  Air  Transportation 
Systems,  for  Mitre  Corp.  He  can  be 
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for  a  given  English-language  sentence? 
What  these  and  similar  problems  have 
in  common  are  1.  an  extremely  large 
number  of  discrete  choices,  2.  a  com¬ 
plicated  set  of  optimizing  criteria  and 
3.  numerous  constraints.  In  such  cir¬ 
cumstances,  simulated  annealing  has 
proven  to  be  an  excellent  tool  for  seek¬ 
ing  out  the  best  solution. 

Simulated  annealing  is  a  relatively 
new  form  of  stochastic  search,  familiar 
primarily  to  VLSI  chip  designers.  As 
you  can  imagine,  determining  the 
best  geometrical  arrangement  for  thou¬ 
sands  of  circuits  is  a  formidable  task. 
To  take  an  oversimplified  example,  sup¬ 
pose  you  have  to  partition  1000  circuits 
into  five  regions  on  a  microchip.  Fur¬ 
ther  suppose  that  permutations  within 
a  region  do  not  matter  and  that  every 
chip  configuration  can  be  given  a  nu¬ 


merical  score  ased  upon  an  appro¬ 
priate  set  of  (possibly  conflicting) 
criteria.  Prior  to  assessing  con¬ 
straints  on  placement,  you  have 
five  choices  for  each  circuit  for 
a  total  of  51000  (about  10  6")  con¬ 
figurations. 

With  numbers  such  as  these,  it 
really  doesn’t  matter  what  kind  of 
computer  is  available;  checking 
each  possibility  is  out  of  the  ques¬ 
tion.  Nevertheless,  the  task  remains 
and  neither  guessing  nor  giving 
up  are  viable  options.  An  answer 
is  usually  found  with  the  help  of  a 
little  computer  assistance,  often  us¬ 
ing  simulated  annealing.  Before 
looking  at  the  usefulness  of  this 
simulated  annealing,  however,  let’s 
examine  its  main  competitor. 

The  Greedy  Algorithm 

Perhaps  the  simplest  general  method 
for  trying  to  locate  a  global  optimum 
(maximum  or  minimum)  in  a  discrete 
space  is  a  technique  often  referred  to 
as  the  “greedy”  algorithm.  Described 
in  English,  it  goes  something  like  this: 

1 .  You  randomize  the  starting  configu¬ 
ration. 

2.  If  possible,  you  find  a  better  con¬ 
figuration  by  making  repeated  (usually 
random)  changes  to  the  current  con¬ 
figuration. 

3.  Make  this  better  configuration  the 
current  one,  then  go  back  to  step  2. 

4.  If  a  better  configuration  is  not  found 
after  a  reasonable  amount  of  effort, 
conclude  that  you  have  obtained  a  lo¬ 
cal  optimum.  Save  it  in  the  variable 
OPTIMUM. 
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(continued  from  page  26) 

5.  Repeat  from  step  1,  replacing  OPTI¬ 
MUMS  appropriate,  until  your  patience 
or  computing  resources  are  exhausted. 
Hope  that  the  final  value  of  OPTIMUM 
is  global. 

Until  you  try  a  few  experiments  with 
this  algorithm  on  large  problems  with 
known  answers,  there  is  a  strong  temp¬ 
tation  to  believe  that  it  might  actually 
work.  However,  unless  the  size  of  the 
problem  (the  number  of  elements  to 
be  configured)  is  small  or  the  configu¬ 
ration  space  exceptionally  smooth,  the 
chances  of  finding  a  global  optimum 
in  this  fashion  are  remote. 

The  deficiencies  of  the  greedy  algo¬ 
rithm  are  not  obscure.  Imagine  a  moun¬ 
tain  goat  traipsing  about  the  Rocky  Moun¬ 
tains  looking  for  the  deepest  valley 
(where  the  best  grass  is).  This  goat  is 
very  hungry  (greedy?)  and,  conse¬ 
quently,  never  takes  an  upward  step. 
Unless  the  goat  starts  out  on  a  smooth 
slope  of  the  deepest  valley,  it  will  never 
reach  that  valley  but  will,  instead,  come 
to  a  dead  end  in  some  higher  valley, 
that  is,  in  a  local  minimum,  which  may 
be  much  higher  than  the  global  mini¬ 
mum.  Moreover,  a  space  as  rough  as 
the  Rockies  contains  thousands  of  val¬ 
leys,  some  only  a  few  feet  deep,  and 
repeating  the  exercise  (step  5,  above) 
may  yield  improvement  but  probably 
not  the  best  result. 

A  Great  Deal  of  Difficulty 

The  difficulties  of  combinatorial  opti¬ 
mization  can  be  illustrated  in  the  game 
of  poker  solitaire  where  the  object  is 
to  rearrange  the  25  cards  of  the  tab¬ 
leau,  like  that  in  Figure  1,  so  that  the 
12  hands  of  straight  poker  formed  from 
the  5  rows,  5  columns,  and  2  diagonals 
give  the  highest  total  score.  Various 
scoring  schemes  are  popular,  but  I  shall 
use  the  one  listed  in  Table  1  in  which 


each  hand  of  a  pair  or  better  has  a 
value  inversely  proportional  to  its  prob¬ 
ability  in  a  standard  deck,  normalized 
to  that  of  a  single  pair.  All  hands  of  a 
given  type  (for  example,  full  house) 
are  considered  equal,  and  an  ace  can 
be  high  or  low. 

Compared  to  the  task  of  optimizing 
circuit  placement  on  a  microchip,  this 

Although  the 
connection  between  real 
and  simulated 
annealing  appears  to 
be  little  more  than  a 
metaphor,  this  system 
responds  in  the  same 
way  as  does  a  physical 
system  —  and  with  the 
same  results 


is  a  small  problem  indeed.  There  are 
only  25!  (about  1025)  configurations  and 
even  fewer  if  symmetry  (rotations,  re¬ 
flections,  and  so  on)  is  taken  into  ac¬ 
count.  Nevertheless,  this  is  such  a  huge 
number  that,  even  if  a  computer  could 
evaluate  a  million  configurations  per 
second  without  repetition,  the  execu¬ 
tion  time  required  to  test  all  of  them 
would  be  comparable  to  the  present 
age  of  the  universe.  To  accommodate 
this  situation,  both  simulated  anneal¬ 
ing  and  the  greedy  algorithm  employ 


Hand 

Score 

Straight  flush 

27,456 

Four  of  a  kind 

1,760 

Full  house 

293 

Flush 

215 

Straight 

108 

Three  of  a  kind 

20 

Two  pair 

9 

Pair 

1 

Table  1:  Scoring  table 


stochastic  techniques,  evaluating  only 
a  fraction  of  the  possible  configura¬ 
tions.  Consequently,  these  algorithms 
provide  no  absolute  guarantee  that  they 
will  find  the  global  optimum  every  time. 
For  large  problems,  it  is  usually  suffi¬ 
cient  that  a  technique  provides  a  rea¬ 
sonable  chance  of  coming  close  to  the 
global  optimum  nearly  every  time.  Then, 
a  few  runs  will  yield  as  good  an  answer 
as  you  are  likely  to  require. 

The  tableau  in  Figure  1  contains  7 
pairs  for  a  score  of  7,  although  there 
are  obviously  4  aces  and  4  kings,  so  it 
is  reasonable  to  expect  that  a  good 
score  would  be  at  least  4000.  Finding 
a  really  high  score  is  not  easy,  how¬ 
ever.  The  12  poker  hands  are  tightly 
interlocked,  and  even  a  small  change 
in  configuration  can  result  in  a  drastic 
change  in  score.  This  is  another  way 
of  saying  that  the  configuration  space 
is  very  rough.  Informal  experiments 
have  shown  it  to  be  more  than  a  match 
for  a  human  player,  and  it  provides  a 
good  test  for  any  combinatorial  optimi¬ 
zation  technique. 

Simulated  Annealing 

The  term  annealing  originally  referred 
to  a  process  employed  in  the  fabrica¬ 
tion  of  objects  constructed  of  metal  or 
glass.  When  these  materials  are  shaped, 
small,  often  microscopic,  regions  of 
stress  develop  in  response  to  deforma¬ 
tions  at  the  atomic  level  and  cause  the 
object  to  be  prone  to  fracture.  Anneal¬ 
ing  corrects  this  defect. 

From  a  chemical  standpoint,  regions 
of  stress  have  relatively  high  energy 
and  thus  are  “almost  fractured”  already. 
An  object  would  be  more  stable  (of 
lower  energy)  if  the  stress  were  absent. 
However,  atoms  and  molecules  in  a 
solid  at  room  temperature  do  not  have 
enough  energy,  on  average,  to  move 
about  and  relieve  the  stress.  (If  they 
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(continued  from  page  28) 
did,  the  object  wouldn’t  be  very  solid.) 
When  an  object  is  annealed,  it  is  first 
heated  enough  to  provide  the  constitu¬ 
ent  atoms  with  sufficient  energy  to  re¬ 
lax  any  stress  but  not  enough  to  initiate 
melting.  It  is  then  cooled  very  slowly. 
During  the  cooling  phase,  the  atoms 
are  gradually  “frozen”  in  place.  If  the 
annealing  is  done  properly,  the  result¬ 
ing  object  will  be  without  stress.  If  the 
cooling  is  too  rapid,  there  will  be  insuf¬ 


ficient  time  for  the  atomic  structure  to 
relax  completely,  and  the  object  will 
end  up  with  excess  energy  and  fracture 
too  easily. 

In  simulated  annealing,  score  is  as¬ 
sociated  with  energy  such  that  mini¬ 
mizing  the  energy  means  optimizing 
the  score.  In  the  poker  solitaire  exam¬ 
ple,  high  score  signifies  low  energy. 
The  tableau  in  Figure  1  can  be  thought 
of  as  a  collection  of  “atoms”  frozen 
into  a  configuration  that  has  too  much 


energy.  Proceeding  with  this  analogy, 
the  tableau  may  be  subjected  to  simu¬ 
lated  annealing  by  raising  its  “tempera¬ 
ture”  until  it  is  almost  “melted,”  then 
cooling  it  slowly  until  it  is  again  “fro¬ 
zen.”  Although  the  connection  between 
real  and  simulated  annealing  appears 
to  be  little  more  than  a  metaphor,  this 
system  (25  playing  cards)  responds  in 
the  same  way  as  does  a  physical 
system  —  and  with  the  same  results. 

In  any  physical  system,  the  average 


ANNEAL.C  Data  Structures,  Functions,  and  Variables 


The  playing  cards  are  represented  as 
2-byte  integers.  The  card  values,  2  to 
Ace  (high),  are  coded  as  the  numbers 
2  to  14  and  the  suits  (spades,  hearts, 
diamonds,  clubs)  are  coded  as  {2048, 
1024,  512,  256),  respectively.  The  tab¬ 
leau  is  intrinsically  a  two-dimensional 
array  but  is  implemented  as  a  one¬ 
dimensional  array  to  avoid  the  com¬ 
putational  burden  of  double  indexing 
(see  HAND[12][5]  below).  ANNEAL.C 
ignores  the  symmetry  of  the  tableau 
with  respect  to  the  scoring  function 
because  it  is,  computationally,  more 
trouble  than  it  is  worth. 
randl() — takes  a  31 -bit  integer, 
SEED,  and  returns  another  one.  This 
generator  yields  a  full-cycle  sequence 
without  repeating  any  numbers. 
uni(z)  —  returns  a  double-precision 
float  in  the  range  (0,z)  via  randl( ). 
initialize) )  —  reads  in  the  starting 
data  from  A.DA.T  and  sets  up  the  data 
structures,  and  so  on. 
init( )  —  resets  a  number  of  global 
counters  and  variables,  chiefly  to  aid 
in  the  collection  of  the  statistics  nec¬ 
essary  to  detect,  equilibrium. 
get  _new  jtemperatureO  —  com¬ 
putes  a  temperature  ratio,  if  neces¬ 
sary,  and  a  new  temperature  (see  Ta¬ 
ble  2). 

check jequilibriumO  —  uses  the 
code  given  in  the  article  to  detect  the 
equilibrium  point. 

update( )  —  computes  those  statis¬ 
tics,  which  need  not  be  found  until 
equilibrium  has  been  achieved,  (see 
SCALE). 

selectwr( )  —  is  a  general  routine  to 
perform  N selections  without  replace¬ 
ment. 

reconfigure) direction)  —  makes  a 
new  configuration,  or  restores  the  tab¬ 
leau  to  its  previous  configuration  if 
the  last  move  was  rejected.  (Typi¬ 
cally,  more  than  90  percent  of  the 
reconfigurations  are  rejected.)  This  rou¬ 
tine  uses  giant  steps  or  baby  steps. 
get  score(crcls)  —  is  called  by  evalu¬ 
ate!  ()  and  returns  the  score  of  a  sin¬ 


gle  hand  as  defined  in  HAND[12][5]. 
evaluate  1( ) — passes  each  hand, 
one  by  one,  to  get_score(crds)  and 
tallies  up  the  total  SCOR  (which  be¬ 
comes  the  current  SCORE ,  if  the  re¬ 
configuration  is  accepted).  Along  with 
randl( )  and  reconfigure( ),  the  func¬ 
tions  evaluate  1(  )  and  get_score()  are 
all  written  in  MC68020  assembly  lan¬ 
guage  in  the  working  code.  This  code 
runs  at  a  speed  of  approximately  2035 
attempted  reconfigurations/sec.  on  an 
AMIGA  1000  equipped  with  a  68020/ 
68881  chip  set,  plus  32-bit  RAM  (a 
standard  Amiga,  executing  ANNEAL.C, 
does  70/sec.),  and  finishes  an  aver¬ 
age  simulated  annealing  run  in  less 
than  3  minutes  with  the  results  as 
shown  in  Figure  4.  Without  this  sort 
of  speed,  the  long  series  of  experi¬ 
ments  needed  to  obtain  good  parame¬ 
ter  values,  and  to  compare  with  the 
greedy  algorithm,  would  have  required 
more  patience  than  this  author  has 
ever  possessed. 

decide) )  —  answers  the  question 
“To  accept  or  not  to  accept?”  and 
uses  the  formula  shown  Example  1, 
equation  2.  It  also  accumulates  statis¬ 
tics  like  INCOUNT  and  OUTCOUNT 
that  must  be  computed  at  every  move. 
report( )  —  produces  the  output  sta¬ 
tistics  and  the  final  tableaux. 
try  ttetv  Jemperature) )  —  is  a  call¬ 
ing  function  that  uses  a  newly  com¬ 
puted  temperature.  It  also  checks  that 
the  tableau  passed  on  to  a  new  tem¬ 
perature  is  not  a  low  outlier. 
main( )  —  q.v. 

HAND[ 12] [5]  —  stipulates  the  12 
hands  (5  cards  each)  in  the  TABLEAU 
and  describes  the  various  hands  in 
terms  of  the  appropriate  indices  of 
TABLEAU. 

PARTITION[6],  OVERLAP[66],HEX 
[ 12],CINDEX[25]  —  are  used  to  gen¬ 
erate  a  new  configuration.  PAR’JTllON 
implements  Table  3  in  long  integers 
(pre-multiplied  by  MODULUS).  OVER¬ 
LAP  is  a  triangular  array  giving  the 
index,  in  TABLEAU,  of  the  intersec¬ 


tion  of  two  HANDs  (-1  if  no  overlap). 
HINDEX  and  CINDEX  are  arrays  used 
to  perform  selection  without  replace¬ 
ment  and  to  remember  those  selec¬ 
tions  should  the  new  configuration 
be  rejected. 

SCORES) J8J  —  is  an  implementation 
of  Table  1.  After  evaluate  1( )  has  de¬ 
termined  the  index  to  SCORES,  SCOR 
is  assigned  the  corresponding  value. 
TEMPERATURE,  TJOW,  TJHIN  — 
is  the  scaling  factor.  T_LOW  is  the 
temperature  below,  which  the  tab¬ 
leau  can  be  tested  to  see  if  it  is  FRO¬ 
ZEN  or  not.  If  the  temperature  ever 
goes  below  T_MN,  the  tableau  is  auto¬ 
matically  FROZEN. 

AVGJSCORE,  SIGMA  —  are  the  aver¬ 
age  and  standard  deviation  of  the 
scores  of  all  the  tableaux  accepted  at 
the  current  temperature. 

SCALE  — ■  is  a  typical  SCORE  when 
the  temperature  is  getting  cold.  This 
variable  has  no  function  in  the  algo¬ 
rithm  per  se,  but  is  incorporated  so 
that  SIGMA  may  be  computed  using 
single-precision  arithmetic.  (This  is  es¬ 
pecially  important  in  the  absence  of 
a  floating-point  chip.)  By  subtracting 
off  a  good  score  before  accumulating 
the  square-of-the-score,  the  number 
of  digits  to  be  squared  is  reduced.  If 
this  is  not  done,  then  a  single-preci¬ 
sion  number  will  lose  too  much  pre¬ 
cision  at  a  time  in  the  annealing  pro¬ 
cess  when  the  average-of-the-squares 
and  the  square-of-the-average  are 
nearly  equal.  When  this  happens,  it 
is  possible  to  get  SIGMA  =  0  errone¬ 
ously.  This  has  a  deleterious  effect 
on  the  program. 

TJRATIO—  T(new)/T(old).  The  in¬ 
itial  value  (here,  0.7)  and  10  other 
values  are  listed  in  A.DAT. 
EXGjCUTOFF  —  is  the  ratio  Prob(gi- 
ant  step)/Prob(baby  step). 

SUCC_  MIN, INCOUNT  JIMIT,  OUT¬ 
COUNT JIMTT, FIRST LIMIT,  ULTI¬ 
MATE _LIMIT  —  are  parameters  used 
to  determine  the  equilibrium  point. 

—  M.M. 
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(continued  from  page  30) 
energy,  <E>,  of  the  constituent  atoms 
is  a  function  of  the  absolute  tempera¬ 
ture,  T.  As  the  temperature  of  a  system 
decreases,  the  average  energy  of  its 
atoms  also  decreases.  A  typical  cooling 
curve  is  shown  in  Figure  2.  The  slope 
of  this  curve,  d<E>/dT,  is  the  heat  capac¬ 
ity,  C,  of  the  system.  In  regions  where 
the  curve  is  steep,  the  heat  capacity  is 
high.  This  usually  indicates  a  phase 
change  —  water  into  ice,  for  example. 
Quite  often,  these  regions  also  display 
large  values  of  C/T.  This  quantity  is 
equal  to  dS/dT,  the  rate  of  change  of 
entropy,  S,  with  temperature,  which  is 
related  to  a  change  in  the  orderliness 
of  the  atoms.  Therefore,  regions  of  a 
cooling  curve  that  are  steep  usually 
imply  a  significant  reconfiguration  of 
the  atoms  (or  molecules)  at  the  corre¬ 
sponding  temperatures.  In  an  anneal¬ 
ing  process  where  temperature  is  be¬ 
ing  regulated,  you  would  have  to  slow 
down  the  cooling  in  such  regions  in 
order  to  allow  the  atoms  time  to  rear¬ 
range  themselves  and  to  permit  their 
average  energy  to  decrease  gradually. 
Annealing  works  best  when  this  is  done. 

Simulated  annealing  also  produces  cool¬ 
ing  curves  much  like  that  of  Figure  2.  In 
fact,  the  literature  of  simulated  annealing 
demonstrates  that  these  analogies  run 
very  deep  and  it  is  not  at  all  easy  to 
decide  just  where  to  draw  the  line  be¬ 
tween  metaphor  and  methodology. 

The  Connection 

The  logical  link  between  combinato¬ 
rial  optimization  and  annealing  is  the 
Boltzmann  distribution,  one  of  the  ba¬ 
sic  laws  of  statistical  mechanics.  Up  to 
now,  I’ve  referred  to  the  average  en¬ 
ergy  of  a  collection  of  atoms.  In  most 
large  populations,  there  is  significant 
variation  from  individual  to  individual. 
So  it  is  with  atoms  and  molecules.  They 
are  constantly  moving,  and  their  mu¬ 
tual  collisions  result  in  continual  trans¬ 
fers  of  energy  from  one  atom  (or  mole¬ 
cule)  to  another.  Much  of  the  science 
of  statistical  mechanics  involves  tech¬ 
niques  for  extracting  macroscopic  prop¬ 
erties  of  a  system  from  the  collective 
behavior  of  enormous  numbers  of  at¬ 
oms  and  molecules.  This  information 
may  be  obtained,  to  a  large  extent,  by 
determining  how  energy  is  partitioned 
among  the  atoms  and  molecules  mak¬ 
ing  up  the  sample. 

At  any  temperature,  there  are  gener¬ 
ally  more  atoms  at  lower  energies  than 
at  higher  energies.  The  Boltzmann  dis¬ 


tribution,  (see  Example  1,  equation  1) 
describes  the  relative  number  of  atoms 
(or  molecules)  populating  any  two  en¬ 
ergy  states,  E  hi  >  E  i0,  at  some  tempera¬ 
ture,  T,  where  Nx  is  the  number  of 
atoms  with  energy  Ex,  T  is  the  absolute 
temperature  (degrees  Kelvin),  and  k  is 
Boltzmann’s  constant.  When  equation 
1  is  adapted  to  the  problem  of  combi¬ 
ne  term  “annealing” 
originally  referred  to 
a  process  employed  in 
the  fabrication  of 
objects  constructed  of 
metal  or  glass 


natorial  optimization,  the  constant  is 
ignored,  energy  is  equated  to  score 
(cost),  and  the  left-hand  side  of  equa¬ 
tion  1  is  interpreted  as  a  probability. 
Simulated  annealing  uses  such  prob¬ 
abilities  to  direct  a  stochastic  search  of 
the  configuration  space  by  employing 
equation  2,  Example  1  where  Sx  is  a 
score  and  T  is  a  scaling  factor. 

In  other  words,  you  construct  a  new 
configuration  at  random  and  determine 
its  score.  If  this  score  is  at  least  as  good 
as  that  of  the  current  configuration, 
then  the  old  configuration  is  forgotten 
and  the  new  configuration  becomes 
the  current  configuration,  as  in  the 
greedy  algorithm.  If  the  new  score  is 
worse  (here,  lower),  however,  then  equa¬ 
tion  2  is  used  to  generate  the  probabil¬ 
ity  of  accepting  the  new  configuration 
anyhow.  A  uniform  random  number 
in  the  interval  (0,1)  is  then  generated, 
and  if  it  is  less  than  the  probability 
computed  with  equation  2,  the  new 
configuration  is  made  the  current  con¬ 
figuration.  The  net  effect  is  to  allow  the 
system  to  extricate  itself  from  local  op¬ 
tima  (that  is,  to  let  the  goat  climb  uphill 
sometimes). 

As  equation  2  suggests,  choosing  a 
worse  configuration  is  a  function  of 
temperature.  The  higher  the  tempera¬ 
ture,  the  higher  the  “energy”  of  the 


system.  The  higher  the  energy  of  the 
system,  the  more  readily  it  will  do  the 
work  of  moving  in  an  unfavorable  di¬ 
rection  —  just  like  real  atoms  and  mole¬ 
cules.  As  the  temperature  decreases, 
however,  any  given  expenditure  of 
energy  becomes  less  likely.  Conse¬ 
quently,  simulated  annealing  automati¬ 
cally  adapts  to  the  magnitude  of  the 
features  of  a  good  configuration.  The 
most  profitable  features  are  found  first 
and  the  smaller,  more  subtle,  features 
later.  Starting  with  the  tableau  in  Figure 
1,  simulated  annealing  first  finds  the 
four  kings  and  four  aces.  If  the  tem¬ 
perature  is  very  high,  these  features 
may  be  forgotten  from  time  to  time, 
but  as  the  temperature  decreases,  even¬ 
tually  they  are  frozen  into  every  ac¬ 
ceptable  tableau.  As  the  temperature 
continues  to  fall,  hands  of  lower  and 
lower  scores  are  successively  frozen 
until,  finally,  the  entire  tableau  is  fro¬ 
zen.  Simulated  annealing  is  terminated 
at  this  point. 

It  is  clear  that  the  annealing 
schedule  —  the  program  for  reducing 
the  temperature  —  is  critical;  a  large 
drop  in  temperature  at  the  wrong  time 
may  freeze  in  undesirable  features.  (Ide¬ 
ally,  all  reconfigurations  should  be  re¬ 
versible.)  The  annealing  schedule  an¬ 
swers  the  following  four  questions: 

1.  What  should  be  the  value  of  the 
starting  temperature? 

2.  When  should  the  temperature  be 
changed? 

3.  How  should  the  temperature  be 
changed? 

4.  When  should  the  search  be  stopped? 

A  quick-and-dirty  procedure  is  to  pick 
a  starting  temperature  high  enough  so 
that  virtually  all  scores  are  deemed  ac¬ 
ceptable,  hold  that  and  each  succes¬ 
sive  temperature  for  (100‘SIZE)  recon¬ 
figurations  or  (10*SIZE)  successful  re¬ 
configurations,  whichever  comes  first, 
then  decrease  the  temperature  by  a 
constant  factor  —  for  example,  T(new) 
=  0.9*T(old)  —  stopping  when  T  reaches 
some  very  low  value  (say,  0.1).  Such  a 
schedule  is  often  employed  for  an  ex¬ 
ploratory  run  on  a  new  problem  in 
order  to  determine  the  shape  of  the 
cooling  curve.  Given  the  cooling  curve, 
you  can  then  create  a  proper  annealing 
schedule  by  arranging  for  the  tempera¬ 
ture  to  decrease  most  slowly  where  the 
curve  is  steepest. 

Implementation  Details 

The  ANNEAL.  C  program  (see  Listing 
One,  page  88)  addresses  both  the  poker 
solitaire  problem  and  computes  the  av¬ 
erage  and  standard  deviation  of  the 
scores  accepted  at  any  temperature. 


Equation  1 :  N  hi/N  io  =  exp(  (E  io-E  hi)  /kT) 

Equation  2 :  Prob  (accept  worse  score)  =  exp  ( (S  io  -S  hi)  /T) 
Example  1:  The  Boltzmann  distribution  in  chemistry  and  computer  science 
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These  statistics  help  in  answering  the 
questions  posed  above. 

To  choose  a  starting  temperature, 
begin  by  picking  one  that  seems  high 
relative  to  the  scores  expected  and  run 
the  program  for  that  temperature  only. 
There  should  be  very  few  reconfigura¬ 
tions  rejected.  After  equilibrium  is 
reached  at  this  temperature  (see  be¬ 
low),  statistics  will  be  output,  one  of 
which  is  SIGMA,  the  standard  devia¬ 
tion  of  the  acceptable  scores.  As  the 
temperature  approaches  infinity,  SIGMA 
approaches  SIGMA(inf),  the  standard 
deviation  of  a  large  set  of  random  con¬ 
figurations.  Set  the  starting  tempera¬ 
ture  equal  to  20*SIGMA(inf). 

There  is  no  point  in  trying  further 
reconfigurations  at  a  given  tempera¬ 
ture  once  a  system  has  reached  thermal 
equilibrium.  (The  method  used  here 
for  recognizing  equilibrium  is  adapted 
from  a  procedure  published  by  Huang, 
Romeo,  and  Sangiovanni-Vincentelli.) 

ANNEAL. C  keeps  track  of  the  num¬ 
ber  of  reconfigurations  accepted  Unsuc¬ 
cesses)  and  rejected  ( nfailures )  at  a 
given  temperature  as  well  as  the  num¬ 
ber  of  acceptable  scores  less  than  or 
more  than  SIGMA/2  from  the  average 
acceptable  score  {incount and  outcount, 
respectively).  The  code  in  Listing  Two, 
page  92,  is  then  used  to  decide  whether 
or  not  equilibrium  has  been  reached. 
(Uppercase  variables  are  parameters.) 

Once  equilibrium  has  been  estab¬ 
lished,  the  temperature  is  decreased, 
provided  that  the  current  configuration 
has  a  score  no  worse  than  SIGMA/2 
from  the  average  score.  The  tempera¬ 
ture  is  not  changed  until  this  is  true. 
The  idea  is  to  avoid  transmitting  a  poor 
outlier  to  a  new,  lower  temperature. 
As  shown,  there  is  no  explanation 
for  delaying  the  transition  to  a  lower 
temperature. 

The  simplest  and  most  flexible  method 
for  computing  a  new  temperature  is  to 
use  a  table,  matched  to  the  cooling 


Temperature 
Less  Than 

t_ratlo 

_ 

0.7 

360 

0.8 

215 

0.7 

85 

0.8 

60 

0.9 

30 

0.95 

15 

0.9 

7 

0.8 

3 

0.7 

0 

0.7 

Table  2:  Temperature  ratios 


curve,  listing  the  desired  sequence  of 
temperature  ratios,  T(new)/T(old),  and 
the  temperatures  at  which  they  take 
effect.  Typically,  these  ratios  fall  in  the 
range  (0.5,  1.0).  ANNEAL.C  permits  up 
to  ten  values  for  these  ratios  in  addition 
to  the  initial  value.  Table  2  gives  the 
actual  ratios  used  in  this  example. 

The  configuration  is  considered  fro¬ 
zen  if,  at  equilibrium,  the  largest  single 
change  in  score  observed  at  the  current 
temperature  is  equal  to  the  difference 
between  the  best  and  worst  scores  at 
this  temperature.  This  is  taken  to  indi¬ 
cate  that  all  accessible  scores  are  of 
comparable  value  and  there  is  no  fur¬ 
ther  need  for  simulated  annealing.  In 
ANNEAL.C,  this  test  is  carried  out  only 
after  the  temperature  reaches  a  preset 
limit,  t_low.  As  a  failsafe,  another  pa¬ 
rameter,  t_min,  is  stipulated  as  the  tem¬ 
perature  at  which  the  configuration  is 
always  assumed  to  be  frozen.  Once  the 
configuration  is  frozen,  it  is  “quenched” 
by  setting  the  temperature  equal  to  zero 
(greedy  algorithm). 

In  the  interest  of  expediency,  the 
best  configuration  found  is  always  re¬ 
membered  separately  from  the  current 
configuration.  Ideally,  the  final  con¬ 
figuration  should  be  the  best.  This  is 
often  not  the  case,  howver.  At  the  end 
of  the  program,  this  best-found  con¬ 
figuration  is  also  quenched. 

Giant  Steps  and  Baby  Steps 

Although  a  proper  annealing  schedule 
is  crucial  to  the  success  of  simulated 
annealing,  there  is  another  considera¬ 
tion  that  is  nearly  as  important  — 
namely,  the  manner  in  which  you  make 
a  random  change  to  the  current  configura¬ 
tion.  This  is  true  for  simulated  anneal¬ 
ing  and,  to  a  lesser  extent,  for  the  greedy 
algorithm.  To  find  a  global  optimum, 
any  search  technique  must  be  able  to 
access  the  entire  configuration  space. 
To  do  this  effectively  requires  both 
“giant  steps”  and  “baby  steps,"  the  for¬ 
mer  for  moving  quickly  to  a  distant 
part  of  the  space  and  the  latter  for 
fine-tuning. 

In  this  example,  baby  steps  are  easy  — 
just  interchange  two  cards.  This  is  the 
smallest  reconfiguration  possible.  Find- 


#  of  Cards 
to  Rotate 

Probability 

2 

0.33333 

3 

0.27018 

4 

0.21899 

5 

0.17750 

Table  3-’  Rotation  distribution 


ing  good  giant  steps  is  much  more 
difficult.  Of  course,  you  could  simply 
execute  several  baby  steps  at  once  but 
experience  shows  that  this  strategy 
yields  poor  results.  One  reason  is  that, 
in  making  a  giant  step,  it  is  essential  to 
retain  as  much  of  the  current  score  as 
possible.  At  moderate  to  low  tempera¬ 
tures,  any  arbitrary  giant  step  would 
almost  certainly  cause  a  substantial  wors¬ 
ening  of  the  score  and  the  new  con¬ 
figuration  would  simply  be  rejected. 
All  rejected  moves  are  wasted  and  an 
efficient  algorithm  must  try  to  keep 
such  moves  to  a  minimum. 

In  ANNEAL.C,  a  giant  step  consists 
of  interchanging  2  of  the  12  hands  of 
the  tableau,  selected  at  random  from  a 
uniform  distribution.  A  baby  step,  on 
the  other  hand,  is  implemented  using 
a  “rotation.”  A  random  integer  in  the 
range  [2,5]  is  chosen  from  an  exponen¬ 
tial  distribution  (see  Table  3).  This  num¬ 
ber  of  cards  is  then  selected  from  the 
tableau  using  a  uniform  distribution. 
The  first  card  selected  is  temporarily 
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Figure  3:  Computer’s  best  result 


set  aside  and  the  resulting  hole  filled 
with  card  number  2,  and  so  on.  The 
last  hole  is  filled  with  card  number  1. 
The  ratio  of  giant  steps  to  baby  steps 
is  a  parameter,  exg_cutqff~,  here  set  equal 
to  0.2.  Using  only  giant  steps  or  baby 
steps  generally  gives  poor  performance. 

Experimental  Results 

Simulated  annealing  and  the  greedy 
algorithm  are  both  stochastic  techniques. 
Therefore,  they  do  not  give  the  same 
results  every  time.  The  proper  way  to 
evaluate  a  stochastic  technique  is  to 
apply  it  several  times  and  determine  its 
average  behavior  (actually,  its  behav¬ 
ior  distribution).  One  of  the  reasons 
such  a  small  example  was  chosen  for 
this  article  was  precisely  to  allow  such 
a  test  to  be  done  in  a  reasonable  amount 
of  time. 

The  simulated  annealing  algorithm 
was  carried  out  30  times,  starting  with 
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the  tableau  in  Figure  1  each  time,  using 
a  random-number  generator  with  a  pe¬ 
riod  much  longer  than  that  required 
by  the  experiment.  The  greedy  algo¬ 
rithm  was  then  applied  to  the  same 
tableau  for  the  same  amount  of  CPU 
time.  Apart  from  the  rule  for  accepting 
or  rejecting  a  new  configuration,  the 
two  programs  are  essentially  identical. 
In  particular,  all  the  relevant  parameter 
values  are  the  same  (see  A. DAT,  Listing 
Three,  page  93).  The  best  result  from 
either  technique  is  a  score  of  4516  (see 
Figure  3).  This  apparent  optimum,  found 
once  by  the  greedy  algorithm  and  twice 
by  simulated  annealing,  is  degenerate 
(that  is,  there  are  several  tableaux  with 
this  score,  which  are  not  symmetry- 
related).  The  distribution  of  results  for 


simulated  annealing  is  shown  in  Figure 
4  and  that  for  the  greedy  algorithm  in 
Figure  5. 

The  number  of  iterations  used  to 
generate  Figures  4  and  5  should  be 
enough  to  give  an  approximate  indica¬ 
tion  of  the  average  performance  of  the 
two  techniques.  No  serious  attempt  was 
made  to  find  the  combination  of  pa¬ 
rameters  that  would  optimize  the  simu¬ 
lated  annealing  results  because  this 
would  have  constituted  a  bias  against 
the  greedy  algorithm  and  such  a  com¬ 
bination  would  have  applied  too  spe¬ 
cifically  to  this  particular  initial  tableau. 
The  parameter  values  in  A. DAT  appear 
to  be  adequate  for  the  poker  solitaire 
problem  in  general  although  the  an¬ 
nealing  schedule  will  have  to  be  al¬ 


tered  when  the  cards  are  changed,  es¬ 
pecially  if  the  new  initial  tableau  can 
produce  a  straight  flush  (see  accompa¬ 
nying  box).  For  other  combinatorial 
optimization  problems,  both  the  pa¬ 
rameter  values  and  the  annealing  sched¬ 
ule  will  have  to  be  changed.  The  big 
questions,  of  course,  are,  “Does  simu¬ 
lated  annealing  work?”  and  “Is  it  worth 
the  effort?”  Taken  together,  the  results 
shown  in  Figures  4  and  5  suggest  that 
simulated  annealing  is  definitely  worth 
the  effort.  Although  you  could  argue 
that,  given  equal  amounts  of  computa¬ 
tion  time,  both  techniques  find  what 
appears  to  be  the  global  optimum,  this 
would  be  overly  simplistic.  For  sto¬ 
chastic  techniques,  the  important  crite¬ 
rion  is  their  average  behavior. 


Cellular  Automata:  A  New  Way  of  Simulation 


In  the  annealing  process,  glass,  cer¬ 
tain  metals,  and  alloys  are  heated  and 
cooled  in  a  controlled  way  to  allow 
the  atoms  to  arrange  themselves  into 
a  stable  state.  Normally,  the  process 
of  annealing  is  simulated  by  means 
of  a  set  of  complex  differential  equa¬ 
tions.  Alternatively,  annealing  can  be 
simulated  by  an  intuitively  simpler 
method  known  as  “cellular  automata.” 

Cellular  automata  are  discrete  dy¬ 
namical  systems  in  which  the  behav¬ 
ior  of  the  system  as  a  whole  is  defined 
in  terms  of  a  set  of  local  rules.  The 
simplest  and  best-known  cellular  auto¬ 
mata  is  the  game  of  LIFE  conceived 
by  John  Conway  in  the  early  1970s. 
LIFE  is  a  computer  simulation  that 
consists  of  a  grid  of  cells  upon  which 
a  collection  of  creatures  are  born,  live 
and  die.  The  life/death  process  is  gov¬ 
erned  by  a  neighborhood  mle  that 
defines  the  behavior  of  any  creature 
at  any  cell  located  in  terms  of  the 
behavior  of  its  neighbors.  This  is  a 
significant  concept  because  it  implies 
that  for  collective  systems,  no  mem¬ 
ber  of  that  collection  of  entities  (or 
creatures)  can  exist  independently  of 
the  rest.  Moreover,  the  rules  that  gov¬ 
ern  the  system  as  a  whole  are  only  the 
rules  of  the  local  neighborhoods.  Hence, 
for  example,  in  a  two-dimensional  life 
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game  consisting  of  a  100  x  150  grid, 
the  rules  are  only  defined  for  each 
local  3x3  matrix!  Even  though  this  is 
the  case,  the  complexity  of  the  life  pro¬ 
cess  produced  can  be  quite  profound. 

As  a  result,  cellular  automata  has 
been  applied  in  areas  such  as  phys¬ 
ics,  chemistry,  and  computer  science. 
For  example,  particle  dynamics,  gal¬ 
actic  evolution,  molecular  kinetics,  or 
parallel  distributed  processing  are 
all  fields  where  local  laws  dictate 
global  behavior.  At  Pace  University, 
we’ve  applied  cellular  automata  to 
the  real-time  study  of  the  dynamics 
of  crystal  growth.  Because  of  the 
large  number  of  local  interactions 
that  must  be  accommodated  in  these 
simulations,  even  a  mainframe  can¬ 
not  provide  the  computing  power  re¬ 
quired  for  real-time  visualization.  How¬ 
ever,  assisting  in  the  simulations,  is 
an  IBM  PC-compatible,  high-perform¬ 
ance  hardware  option  called  CAM-6 
(Cellular  Automata  Machine)  that  runs 
under  MS-DOS.  CAM-6  is  a  special- 
purpose  coprocessor  designed  spe¬ 
cifically  for  cellular  automata  simula¬ 
tions  by  researchers  at  the  MIT  Labo¬ 
ratory  for  computer  science.  Its  pipe¬ 
lined  architecture  allows  software  to 
run  at  speeds  comparable  to  that  of  a 
CRAY-1,  therefore  allowing  the  CAM 
board  to  update  and  display  a  256  x 
256  array  of  cells  1/60  of  a  second, 
thus  producing  real-time  animation. 
Each  cell  in  CAM  is  represented  by  a 
pixel,  and  cells  can  assume  1  of  16 
possible  states  signified  by  16  differ¬ 
ent  colors. 

The  CAM-6  machine  is  programma¬ 


ble  in  a  high-level  language  called  “CAM 
Forth,"  a  special  version  of  Forth-83. 
Because  Forth  was  originally  devel¬ 
oped  for  real-time  applications  and 
meets  the  demands  of  cellular  auto¬ 
mata  by  its  code  efficiency. 

We  have  used  this  combination  of 
hardware  and  software  to  simulate 
crystal  growth.  Presently,  we  wish  to 
discover  the  local  rules  which  govern 
the  growth  of  sodium  chloride  (com¬ 
mon  table  salt).  This  is  accomplished 
by  programming  neighborhoods  that 
work  with  the  four  major  neighbors 
on  all  the  planes.  The  difficult  part  in 
programming  “rules”  is  keeping  in 
mind  that  one  cannot  change  the  state 
of  a  neighbor  but  only  the  cell  cur¬ 
rently  in  question.  For  example,  you 
cannot  indicate  if  a  cell  has  three  or 
more  neighbors  at  state  1,  and  turn 
all  neighbors  at  state  0  to  1.  There¬ 
fore,  programming  has  to  be  done 
around  this  constraint,  which  at  times 
can  be  extremely  difficult.  We  have 
also  simulated  complex  solid  liquid 
equilibria.  This  involved  programming 
minor  neighborhoods  which  allowed 
states  to  be  compared  from  a  second 
CAM  machine  that  was  programmed 
as  a  random  noise  generator. 

By  watching  and  studying  these  simu¬ 
lations,  we  hope  to  gain  insight  into 
the  synthesis  of  crystals  and  funda¬ 
mental  patterns  of  molecular  growth. 
The  models  of  cellular  automata  could 
one  day  be  a  major  breakthrough  in 
the  understanding  of  nature’s  rules, 
which  in  turn  could  affect  every  as¬ 
pect  of  life. 

— J.C.,  F.T.M. 
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For  this  example,  the  probability  that 
any  given  iteration  of  the  greedy  algo¬ 
rithm  yields  a  score  greater  than  or 
equal  to  the  average  simulated  anneal¬ 
ing  result  is  6/1583-  Thus,  183  itera¬ 
tions  of  the  greedy  algorithm  afford  a 
50  percent  chance  of  doing  at  least  as 
well  as  simulated  annealing  (607  itera¬ 
tions  for  a  90  percent  chance).  The 
greedy  algorithm,  however,  converges 
only  53  times  faster  in  this  example 
than  does  simulated  annealing.  Clearly, 
there  is  a  higher  payoff  with  simulated 
annealing. 

Final  Thoughts 

Although  I’ve  compared  simulated  an¬ 
nealing  to  the  well-known  greedy  al¬ 
gorithm,  it  would  be  incorrect  to  sug¬ 
gest  that  the  latter  is  the  only  alterna¬ 
tive.  Recently,  neural  networks  and  vari¬ 
ous  genetic  algorithms  have  been 
applied  to  combinatorial  optimization 


problems  with  some  success.  If  the  prob¬ 
lems  are  small  enough,  then  classical 
integer  programming  techniques  (that 
is,  branch-and-bound)  may  also  prove 
fruitful.  Moreover,  when  evaluating  the 
material  presented  here,  there  are  sev¬ 
eral  points  to  bear  in  mind.  First,  not 
every  application  of  simulated  anneal¬ 
ing  will  exhibit  better  performance  than 
a  greedy  algorithm  to  the  extent  ob¬ 
served  in  this  case,  so  you  should  not 
extrapolate  too  much  from  this  single 
example. 

Another  important  consideration  is 
that  simulated  annealing  is  very  time- 
consuming,  and  almost  any  serious  ap¬ 
plication  of  this  sort  is  best  written  in 
assembly  language.  The  program  AN- 
NEAL.C  was  coded  in  C  solely  in  the 
interests  of  pedagogy  and  portability. 

Finally,  both  algorithms  described  in 
this  article  are  stochastic  in  nature.  Even 
though  the  tableau  in  Figure  1  was 


subjected  to  hundreds  of  simulated  an¬ 
nealing  runs,  there  is  still  no  guarantee 
that  the  optimum  found  is,  in  fact,  the 
global  optimum.  It’s  possible  that  there 
exists  a  tableau  with  a  score  greater 
than  4516  but  that  the  path  through  the 
configuration  space  leading  to  it  is  so 
narrow  that  even  the  millions  of  recon¬ 
figurations  carried  out  are  insufficient 
to  find  it. 

In  this  regard,  it’s  interesting  that  all 
the  tableaus  found  having  scores  of 
451$  contained  only  11  scoring  hands, 
not  12.  This  being  the  case,  there  may 
be  “room”  for  an  even  higher  score. 
Better  yet,  what  if  a  13th  hand  were 
defined,  consisting  of  the  4  corners 
plus  the  center  card.  Would  there  be 
any  point  in  adding  the  extra  degree 
of  freedom?  This  intriguing  thought  is 
left  as  an  exercise  for  DDJ  readers. 
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Force-based 

Simulations 


C++  makes  it  easy  to  find  out  how  one  body  in  a  universe 

influences  all  others 


You’ve  probably  heard  it 
said  that  the  languages 
that  best  model  the  real 
world  are  object-orient¬ 
ed.  When  you  try  to 
build  a  simulation  system  you 
realize  just  how  true  this  is.  This 
article  presents  a  force-based  simu¬ 
lation  system  written  in  Zortech’s 
C++  that  demonstrates  how  and 
why  an  object-oriented  language 
like  C++  is  a  natural  choice  for 
implementing  simulation  systems. 

The  most  common  type  of 
simulation  systems  are  probably 
circuit  type  simulations,  where 
components  have  inputs  and  per¬ 
form  transformation  of  the  input 
into  some  form  of  output.  The 
output  is  then  fed  to  another  com¬ 
ponent.  With  force-based  systems, 
you  have  a  collection  of  bodies 
that  forms  a  universe.  Each  body  exerts 
a  force  on  every  other  body  in  the 
universe.  This  means  that  just  the  pres¬ 
ence  of  a  body  has  an  influence  on  all 
other  bodies.  This  is  significantly  dif¬ 
ferent  from  circuit-based  simulation, 
where  influences  are  channeled  from 
component  to  component. 
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Building  a  Forced-based  System 

Probably  the  most  difficult  and  critical 
element  in  a  simulation  system  is  man¬ 
aging  the  objects  that  exist  in  the  simu¬ 
lation.  The  function  of  the  object  man¬ 
ager  is  to  maintain  the  communication 
between  bodies  and  to  enforce  the  physi¬ 
cal  laws.  Listing  One,  page  94,  contains 
the  source  code  for  the  administrator 
for  the  system  presented  in  this  article. 
In  this  listing,  the  administrator  method 
is  called  big_bang( ),  of  the  object  class 
UNIVERSE. 

It  is  crucial  to  maintain  the  integrity 
of  each  body.  In  C++,  this  is  best  ac¬ 


complished  by  making  the  physi¬ 
cal  parameters  private  and  pro¬ 
viding  methods  to  return  the  physi¬ 
cal  parameters.  Because  the  physi¬ 
cal  parameters  for  any  body  in 
the  system  are  the  same,  the  class 
for  bodies  is  called  BODY  (also 
in  Listing  One).  The  method  UNI¬ 
VERSE:  servicej  )  registers  a  body 
with  the  UNIVERSE.  The  collec¬ 
tion  of  bodies  to  be  serviced  is 
maintained  as  an  array  of  objects 
of  class  BODY,  and  is  repeatedly 
stepped  through  when  you  call 
UNIVERSE:  :big_bang(  ). 

In  the  class  of  BODY,  the  most 
notable  method  is  apply _  force ( ), 
which  takes  an  outside  influence 
on  the  body  and  converts  it  into 
a  change  in  physical  parameters. 
The  physical  law  that  determines 
how  bodies  influence  each  other 
is  encoded  in  this  method.  In  the  pre¬ 
sent  system,  we  are  using  the  derivative 
of  the  force  law  of  gravity,  which  re¬ 
sults  in  an  instantaneous  velocity  vec¬ 
tor.  This  velocity  vector  is  then  applied 
to  the  body’s  current  velocity  vector  to 
determine  its  new  vector.  The  other 
member  functions  of  the  BODY  class 
are  simple  and  I’ll  refer  you  to  the 
source  for  details. 

Viewing  the  results  of  the  simula¬ 
tions  can  be  done  in  a  variety  of  ways. 
In  some  cases,  a  table  of  numbers  is 
sufficient,  but  in  most  cases  the  results 
are  best  seen  in  some  animated  form. 
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FORCE-BASED  SIMULATIONS 


(continued  from  page  40) 

Listing  Two,  page  94,  contains  those 
methods  and  functions  that  are  directly 
related  to  the  display  of  a  simulation. 
The  method  BODY::update( )  displays 
a  body  on  the  screen.  It  also  updates 
the  position  of  the  body  based  on  its 
velocity  vector.  Even  though  I  choose 
to  display  things  as  characters  (so  ev¬ 
eryone  can  watch  the  simulation),  it 
should  be  relatively  easy  to  alter  the 
code  to  work  with  graphic  images. 

Simulating  the  Earth  and  Moon 

Let’s  look  at  some  examples.  Example 
1  is  a  simulation  of  the  Earth  and  Moon. 
The  source  is  straight  forward.  We  cre¬ 
ate  the  bodies,  define  their  physical 
parameters  (mass,  location,  and  veloc¬ 
ity),  and  then  let  the  UNIVERSE  take 
care  of  the  rest.  The  numbers  used  in 
all  the  methods  are  real.  So  if  the  physi¬ 
cal  laws  on  which  the  system  is  built 
match  reality,  the  Moon  should  orbit 
the  earth  every  27.3  days.  In  the  exam¬ 
ple,  one  day  is  equal  to  one  tick. 

Another  thing  you  will  observe  when 
you  run  this  example  is  that  the  Earth/ 
Moon  pair  moves  gradually  to  the  left. 
While  trying  to  understand  this  result, 
I  realized  that  the  simulation  system 
had  revealed  the  notion  of  “center  of 


Simulates  the  orbital  dynamics  of  the  Earth 

and  Moon. 

Todd  King 

finclude  "simul.hpp" 
ttinclude  "simulscr.hpp" 

main!)  | 

BODY  earth; 

BODY  moon; 

UNIVERSE  universe; 

earth. set  mass (5. 98»;24) ; 

earth.set_position(5.0e8, 
earth. set  icon('E'); 

5.0e8) ; 

moon. set  mass (7 . 36e22) ; 

moon.set3>osition(5.0e8, 

moon. set  icon  I'M'); 

8 . 8e8) ; 

moon . set_velocity (-1020 . 0 

0.0); 

universe. service (Searth) ; 

uni verse. service (Smoon) ; 
universe. big_bang() ; 

Example  1:  Simulation  of  the  Earth 
and  the  Moon 


mass”  for  systems,  even  though  this 
notion  was  not  bred  into  the  system. 
The  center  of  mass  for  a  system  is  the 
point  that  two  (or  more)  orbiting  bod¬ 
ies  revolve  around.  It  is  this  point  that 
moves  at  the  velocity  of  the  system  as 
a  whole.  So  when  the  Moon  was  given 
its  initial  velocity,  the  center  of  mass 
was  given  the  same  velocity.  Hence  the 
entire  system  moves  to  the  left.  Figure 
1  illustrates  this  system. 

Example  1  is  a  verification-type  simu¬ 
lation  that  demonstrates  that  the  simu¬ 
lation  system  produces  substantiated 
results.  This  allows  us  to  perform  a 
hypothetical  simulation  and  trust  the 
results.  Let’s  look  at  what  would  hap¬ 
pen  if  Planet  X  passed  through  our 
system.  Assume  that  the  planet  is  twice 
as  big  as  the  Moon.  Listing  Three,  page 
96,  is  the  source  for  this  simulation. 
The  system  is  the  same  as  that  pre¬ 
sented  in  Example  1,  with  the  addition 
of  a  third  body  that  moves  through  the 
system  from  the  lower-left  corner  to 
the  upper-right  corner.  When  running 
this  example  you’ll  see  just  how  dis¬ 
ruptive  such  an  occurrence  would  be, 
even  if  Planet  X  doesn’t  collide  with 
any  other  body.  Figure  2,  shows  the 
path  of  Planet  X  through  the  Earth/ 
Moon  system. 


Figure  1:  Physical  components  of  the 
Earth/Moon  system.  Vi  is  the  initial  ve¬ 
locity  given  to  the  Moon 


Conclusions 

Simulation  systems  have  broader  appli¬ 
cations  than  the  model  presented  here. 
They  are  useful  in  developing  and  test¬ 
ing  new  theories.  With  simulation  sys¬ 
tems  you  can  change  the  physical  laws 
and  constants  and  observe  the  results. 
One  such  constant  is  G,  the  gravita¬ 
tional  constant,  which  can  be  found  in 
Listing  Four,  page  96.  Simulations  also 
allow  us  to  duplicate  events  in  nature 
at  a  faster  rate.  For  example,  it  takes  the 
moon  a  lot  less  than  27.3  days  of  wall 
clock  time  to  revolve  about  the  earth 
in  Example  1. 

Games  are  a  form  of  simulation  sys¬ 
tems,  and  with  a  little  work  you  can 
create  a  game  with  this  simulation  sys¬ 
tem  by  adding  a  space  ship  body  to 
one  of  the  examples  and  allowing  the 
user  to  control  the  rockets  on  it.  The 
goal  would  be  to  obtain  an  orbit  about 
one  of  the  other  bodies.  Such  a  skill 
could  be  useful  as  we  begin  to  move 
off  the  surface  of  our  planet. 

The  system  presented  here  has  a 
few  limitations.  First,  the  maximum  dis¬ 
tance  allowed  between  any  two  ob¬ 
jects  is  the  square  root  of  the  largest 
possible  value  for  a  double.  On  a  PC, 
this  value  is  1.3el54.  Next,  the  num¬ 
ber  of  bodies  that  can  exist  in  a  UNI¬ 
VERSE  are  limited.  This  is  set  with  the 
parameter  MAXJSODIES  and  has  an 
upper  boundary  that  is  the  same  as  for 
an  int,  and  is  limited  because  we  use 
an  array  to  track  the  bodies.  Convert¬ 
ing  this  to  a  link  list  would  eliminate 
this  limitation. 
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(Listings  begin  on  page  94.) 


Figure  2:  Path  of  Planet  X  as  it  passes  through  our  Earth/Moon  system 
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Setting 

Precedence 

Improved  search  strategies  mean  high  performance 


Programmers  now  bask  in  the 
luxury  of  huge  expanses  of  com¬ 
puter  memory.  To  take  full  ad¬ 
vantage  of  the  situation,  they 
need  high-speed  algorithms  ca¬ 
pable  of  managing  random  access  to 
correspondingly  huge  amounts  of  data. 
One  solution  involves  the  use  of  binary 
trees  (B-trees)  or  some  extension  such 
as  B+  trees.  Another  solution  that  I 
prefer,  the  precedence  tree  (Ptree),  is 
both  simple  and  elegant. 

Traditional  methods  of  B-tree  con¬ 
struction  tend  to  degenerate  into  linear 
lists  or  other  unbalanced  states.  There 
are  routines  for  balancing  a  B-tree,  but 
they  are  often  time-consuming,  at  times 
having  to  traverse  through  every  ele¬ 
ment  in  the  tree.  In  addition,  these 
routines  tend  to  be  code  intensive.  One 
reason  is  the  many  different  tree  con¬ 
figurations  possible  for  the  same  set  of 
numbers  (see  Figure  1).  The  final  con¬ 
figuration  is  dependent  upon  the  order 
in  which  the  numbers  are  entered.  And 
as  you’ll  soon  see,  inefficiencies  are 
created  by  this  order  of  entry. 

In  addition  to  the  Ptree,  this  article 
explores  the  use  of  pointer  references 
to  create  elegant  code.  The  majority  of 
code  for  the  article  is  contained  in  five 
listings.  SPARRAY  (see  Listings  One  and 
Two,  page  98)  constructs  and  main¬ 
tains  a  sparse  array  utilizing  a  Ptree. 
DIAGARRA  (see  Listings  Three  and 
Four,  page  100)  diagrams  the  Ptree  of 
the  sparse  array  and  provides  statistics. 
PTREE. C  (see  Listing  Five,  page  101) 
inserts  numbers  into  and  deletes  them 
from  a  Ptree  and  utilizes  DIAGARRA 


Mark  Peterson  is  a  contract  computer 
programmer  in  the  Hartford,  Conn.- 
area.  He  can  be  reached  by  calling 
203-754-1162,  or  on  CompuServe  at 
70441, 3353- 


Mi  C.  Peterson 

to  observe  the  different  configurations. 
All  code  is  written  in  ANSI  standard  C. 

Precedence  Trees 

The  Ptree  builds  an  ordered  B-tree  in 
such  a  way  that  only  one  configuration 
is  possible  for  a  given  set  of  numbers. 
This  is  done  by  either  placing  numbers 
in  the  middle  of  an  existing  tree  or  as 
a  new  leaf  to  create  a  tree.  This  tech¬ 
nique  resolves  inefficiencies  due  to  or¬ 
der  of  entry  and  creates  a  configuration 
that  is  always  reasonably  balanced.  Fur¬ 
thermore,  these  trees  tend  to  become 
more  balanced  as  more  numbers  are 
entered. 

The  entry  of  sequential  lists  of  num¬ 
bers,  which  creates  a  linear  list  using 


traditional  methods,  instead  creates  a 
perfectly  balanced  B-tree  using  tech¬ 
niques  of  precedence.  Also,  a  Ptree 
uses  only  one  chain  of  traversals  from 
the  root  to  a  given  leaf  for  placement 
of  a  new  number  in  the  tree.  Removal 
of  an  old  number  is  accomplished  with 
a  single  pass  through  the  Ptree  along 
two  chains  without  recursion.  High¬ 
speed  construction  with  a  tendency  to¬ 
ward  perfect  balance  means  a  lightning- 
fast  algorithm. 

Theory 

One  problem  with  ordered  B-trees  is 
the  many  different  possible  states  for  a 
given  set  of  numbers.  The  reason  is 
that  traditional  binary-tree  implementa- 


Figure  1:  Various  tree  configurations  for  the  values  0,  1,  2,  and  3,  depending 
on  the  order  of  entry 
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tions  only  place  new  numbers  as  addi¬ 
tional  leaves.  This  produces  configura¬ 
tions  that  vary  depending  upon  the 
order  in  which  the  numbers  are  en¬ 
tered  (see  Figure  1).  Note  that  most  of 
the  configurations  in  Figure  1  are  not 
balanced.  Therefore,  if  construction  of 
the  tree  is  left  to  chance,  which  is  the 
traditional  method,  the  odds  of  ending 
up  with  an  efficient  tree  are  not  good. 

The  net  result  is  that  efficiency  li¬ 
abilities  created  by  the  order  of  entry 
are  additive  and  never  resolved  with¬ 
out  balancing  the  tree.  For  example,  if 
the  first  numbers  entered  form  a  linear 
list,  such  as  0,  1,  2,  and  3,  all  successive 
searches  and  placements  must  first  trav¬ 
erse  this  list  (see  Figure  2). 

An  ordered  B-tree  containing  all  pos¬ 
sible  numbers  for  a  given  number  of 
bits  is  referred  to  as  a  full  B-tree.  Only 
two  configurations  are  perfectly  bal¬ 
anced  for  a  full  4-bit  B-tree.  One  con¬ 
figuration  is  shown  in  Figure  3;  the 
other  is  the  trivial  exchange  of  1  and  0. 

A  close  look  at  the  bit  patterns  shows 
a  convergence,  meaning  that  a  traversal 
in  the  proper  direction  on  a  binary 
search  results  in  a  number  with  a  bit 
pattern  more  closely  resembling  the 
number  being  sought.  In  this  case,  this 
is  a  leading  convergence  where  the 
matching  of  bit  patterns  occurs  from 
the  most  significant  bit  to  the  least. 
B-trees  configured  with  the  matching 
bit  pattern  occurring  from  the  least  sig¬ 
nificant  bit  to  the  most  (a  lagging  con¬ 
vergence)  cannot  be  ordered.  Dia¬ 
graming  the  tree  so  that  lower  numbers 
are  to  the  right  and  higher  numbers  are 
down  not  only  makes  it  easier  to  see 
this  leading  convergence  but  is  also 
easier  to  implement. 

Note  that  the  numbers  closer  to  the 
root  contain  more  factors  of  2  than 
those  that  are  further  away.  This  point 
is  key  to  the  Ptree  algorithm.  The  Ptree 
algorithm  compares  the  number  being 
placed  with  the  number  in  the  current 
position,  using  the  factors  of  2  to  deter¬ 
mine  which  has  precedence  (that  is, 


Figure  2:  Example  of  inefficiencies 
created  by  an  imbalanced  tree  config¬ 
uration 
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which  should  be  positioned  closer  to 
the  root).  The  number  with  the  greater 
factors  of  2  has  higher  precedence.  If 
the  two  numbers  initially  have  the  same 
factors  of  2,  they  are  bit-shifted  to  the 
right  until  one  has  more  or  becomes  0. 
By  definition,  0  has  the  lowest  prece¬ 
dence.  As  an  example,  Figure  4  com¬ 
pares  the  precedence  of  the  numbers 
11  and  15.  Because  11  has  more  factors 
of  2  (after  bit  shifting),  it  has  prece¬ 
dence  over  15.  Figure  4  also  compares 
the  numbers  12  and  28.  Because  12 
bit-shifts  to  0  before  28  does,  it  has 
precedence  over  28. 

This  added  dimension  of  precedence 
checking  creates  a  B-tree  that  is  “rigid” 
(Figure  5)  with  only  one  possible  con¬ 
figuration  for  a  given  set  of  numbers. 
This  configuration  is  always  reason¬ 
ably  balanced. 

When  I  say  “reasonably  balanced,” 


I  mean  that  the  Ptree  algorithm  strikes 
a  compromise  between  perfection  and 
practicality.  Keeping  a  tree  perfectly 
balanced  ensures  the  fastest  search  time 
but  requires  a  great  deal  of  trouble  to 
maintain.  Ignoring  balance  invites  ram¬ 
pant  linear  listing.  The  compromise  pro¬ 
duces  a  reasonable  balance. 

There  is  some  listing  for  certain  sets 
of  numbers  that  are  separated  by  or¬ 
ders  of  2  —  for  example  the  numbers 
0,  1,3,  5,  9,  17,  33,  65,  and  so  on,  form 
a  linear  list.  The  maximum  length  of 
this  linear  list  is  dependent  on  the  larg¬ 
est  number  capable  of  being  entered 
into  the  tree.  That  is,  if  the  tree  can 
hold  only  32-bit  numbers,  the  maxi¬ 
mum  length  of  any  linear  list  is  32. 
This,  however,  is  a  very  fragile  state 
because  entered  numbers  not  conform¬ 
ing  to  this  pattern  break  down  the  list 
into  a  more  balanced  state. 


11=1011,  15  =  1111  (each  has  no  factors  of  2) 

5  =  0101,  7  =  01 1 1  (each  has  no  factors  of  2) 

2  =  1001,  15  =  0011  (2  has  one  factor,  3  has  none) 


1 2  =  01 1 00,  28  =  1 1 1 00  (each  has  two  factors  of  2) 
6  =  00110,  14  =  01110  (each  has  one  factor  of  2) 
3  =  0001 1 ,  7  =  001 1 1  (each  has  no  factors  of  2) 

1  =  00001 ,  3  =  0001 1  (each  has  no  factors  of  2) 
0  =  00000,  1  =  00001 


Figure  4:  Comparing  the  numbers  11  and  15  to  determine  which  has 
precedence 
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Figure  5:  The  rigid  structure  created  by  precedence  checking 
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Figure  6:  A  quick  method  for  ascertaining  the  factors  of  2  for  the  purpose  of 
determining  precedence 
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Implementation 

A  quick  algorithm  for  comparing  the 
factors  of  2  in  a  pair  of  numbers  is  to 
XOR  each  number  with  itself  minus  1 
and  compare  the  results  (see  Chk- 
PrecGTO  in  Listing  Two).  Subtracting 
1  from  a  number  turns  all  the  trailing 
binary  Os  (the  factors  of  2)  to  Is  and  the 
least  significant  binary  1  to  a  0,  leaving 
the  rest  of  the  binary  digits  untouched. 
When  this  result  is  exclusively-ORed 
with  the  original  number,  all  the  un¬ 
changed  leading  binary  digits  become 
Os,  leaving  a  result  that  is  representative 
of  the  factors  of  2. 

The  (x  -  1)  a  x  representative  num¬ 
bers  shown  in  Figure  6  can  then  be 
compared  to  see  which  x  has  more 
factors  of  2.  The  expression  0-1  is  un¬ 
defined  because  the  numbers  involved 
are  whole  numbers  (positive  integers) 
and  therefore  the  calculated  (x- 1)  a  x 
of  0  is  0  by  definition. 

The  definition  of  a  Ptree  states  that 
all  numbers  either  greater  or  less  than 
a  given  number  will  have  a  lower  prece¬ 
dence.  This  means  that  putting  a  num¬ 
ber  in  the  Ptree  usually  requires  place¬ 
ment  somewhere  in  the  middle  of  the 
tree  rather  than  at  the  end  by  adding 
another  leaf.  This  requires  that  the  Ptree 
be  “normalized”  after  insertions  and 


the  number  64 


unbalanced  after  inserting  64 
as  the  root 
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deletions.  To  demonstrate,  consider  the 
insertion  of  the  value  64  into  the  Ptree 
in  Figure  7.  Because  64  contains  five 
factors  of  2  and  108  (the  root  value) 
only  contains  two  such  factors,  64  has 
a  higher  precedence  and  should  there¬ 
fore  be  the  new  root. 

After  linking  108  to  the  left  side  of 
64,  the  tree  is  no  longer  ordered  be¬ 
cause  several  numbers  on  the  “greater” 
side  of  64  are  actually  less  (Figure  8). 
These  lesser  numbers  must  be  “pruned” 
away  from  the  left  side  of  the  tree  and 
relinked  to  the  right  side. 

Traversals  are  made  through  the  tree 
using  PruneLower(  land  PruneHigherJ  ). 
Because  108  was  linked  to  the  “higher” 
(left)  side  of  64,  PruneLowerJ  )i,s  called 
first.  If  the  new  linkage  had  been  made 
to  the  “lower”  (right)  side  of  64,  Prune¬ 
HigherJ  )  would  have  been  called  first. 
PruneLowerJ )  traverses  along  the  lower 
linkages  until  it  reaches  a  section  that 
is  less  than  the  reference  value  64.  Prune¬ 
LowerJ  )  breaks  this  linkage  and  makes 
a  call  to  PruneHigherJ ).  PruneHigherJ ) 
traverses  along  the  higher  linkages  of 
this  section  of  lower  numbers  until  it 
reaches  a  section  greater  than  64.  It 
breaks  that  linkage  and  makes  a  call 
to  PruneLowerJ ).  This  process  contin¬ 
ues  until  a  leaf  is  reached.  Prior  to 
return  from  the  recursion,  the  Ptree  is 
divided  into  sections  of  numbers  higher 
and  lower  than  64.  The  return  from  the 
recursion  relinks  these  sections  to  their 
proper  locations  to  create  an  ordered 
B-tree  (see  Figure  9). 

As  shown  in  Figure  10,  the  removal 
of  64  from  the  Ptree  creates  a  hole  that 
must  be  filled.  The  removal  effectively 
leaves  two  sets  of  numbers  correspond¬ 
ing  to  the  left  and  right  sides  of  the  tree. 
In  essence,  there  are  two  subtrees:  one 
with  values  greater  than  64  and  an¬ 
other  with  values  less  than  64.  The  two 
sections  need  to  be  joined  along  an 
interface  line,  as  shown  in  Figure  11. 
A  number  on  the  interface  line  from 
the  greater  section  is  compared  with 
one  on  the  interface  line  of  the  lower 
section  and  linked  according  to  prece¬ 
dence.  Linkages  unrelated  to  the  inter¬ 
face  line  are  unaffected.  The  result  is 
the  original  Ptree  configuration  (see 
Figure  7).  The  use  of  pointer  refer¬ 
ences  allows  this  to  be  done  as  a  sin¬ 
gle,  iterative-style  pass  through  the  Ptree 
without  recursion. 

Application 

The  SPARRAY  structure  (Listing  Two) 
is  a  sparse  array  that  handles  elements 
up  to  the  limit  of  unsigned  long.  For 
most  compilers  this  equates  to  an  ad¬ 
dressing  capability  of  4,294,967,296  lo¬ 
cations.  SPARRAY  uses  a  Ptree  to  man¬ 
age  the  elements  in  the  sparse  array. 

MakeSpArrayJ )  and  DeleteSpArrayJ ) 


are  used  to  allocate  memory  dynami¬ 
cally.  MakeSpArrayJ)  returns  a  null 
pointer  if  there  is  insufficient  memory, 
and  DeleteSpArrayJ )  sets  the  pointer 
referenced  by  RefPtr  to  NULL  to  pre¬ 
vent  further  usage  of  the  memory  space 
after  deletion. 

FindSpElemJ  )  is  a  standard  binary 
search  routine  that  returns  a  null  pointer 
if  the  element  is  not  found.  The  func¬ 
tion  reads: 

•  Starting  with  the  root,  while  this  ele¬ 
ment  is  not  a  null  pointer  and  is  not 
pointing  to  the  desired  location,  con¬ 
tinue  looking  either  higher  or  lower 
depending  on  whether  this  current  lo¬ 
cation  is  greater  or  less  than  the  desired 
one.  Return  the  “this”  pointer  (either 
NULL  or  the  one  sought). 

PlaceElementJ )  assumes  that  the  ele¬ 
ment’s  location  being  placed  is  not  al¬ 
ready  in  the  array.  The  function  first 
sets  up  a  place  for  the  “new”  location 
by  checking  to  see  if  there  are  any 
empty  elements  (that  is,  elements  re¬ 
moved  by  RemoveSpElemJ  J) .  If  there 
are  none,  the  function  chooses  the  next 
highest  element  that  has  been  used.  If 
there  is  no  more  room  in  the  array 
(A  rray->HighestUsed=  =  A  rray- >Size), 
the  function  returns  NULL 

The  next  section  uses  a  binary  search 
similar  to  FindSpElemJ )  with  two  ex¬ 
ceptions:  a  check  is  made  for  prece¬ 
dence,  and  this  is  a  pointer  reference 
rather  than  a  pointer.  The  use  of  a 
pointer  reference  (as  opposed  to  a 
pointer)  allows  setting  the  new  linkage 
based  on  previous  events.  In  other 
words,  the  linkage  can  be  set  “in  con¬ 
text”  rather  than  explicitly  checking  the 
new  linkage  to  see  if  it  is  a  higher, 
lower,  or  a  new  root  pointer.  The  algo¬ 
rithm  reads  as  follows: 

•  First  start  with  the  address  of  the  root. 
While  “this”  address  is  not  referring  to 
a  null  pointer,  check  to  see  if  the  “Loc” 
being  sought  has  precedence  over  the 
referenced  location.  If  so,  then  set  either 
the  “Higher”  or  “Lower”  linkage  of 
“New”  to  the  reference  pointer  and 
call  the  appropriate  pruning  function 
based  on  whether  “this”  referenced  lo¬ 
cation  is  greater  or  less  than  the  “New” 
location.  If  the  referenced  location  has 
precedence  over  the  “New”  location, 
then  traverse  either  higher  or  lower  as 
appropriate.  Break  out  of  the  loop  when 
either  a  null  pointer  is  referenced  or  a 
precedence  check  returns  true,  and  set 
whatever  was  referring  to  “this”  dis¬ 
placed  element  (either  a  “Higher”  or 
“Lower”  linkage  pointer  or  the  root) 
to  the  “New”  element.  Return  the  “New” 
element  pointer. 
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The  pruning  functions  could  be  writ¬ 
ten  iteratively  setting  the  linkages  on 
the  fly.  Using  several  pointer  references 
rather  than  saving  them  on  the  stack, 
however,  is  a  clumsy  solution.  The  time 
spent  dereferencing  the  various  pointer 
references  far  exceeds  the  time  spent 
performing  a  recursion,  and  it  also  takes 
up  more  code  space. 

RemoveSpElem( )  first  sets  the  pointer 
reference  this  to  the  linkage  pointing 
to  the  element  to  be  removed  by  start¬ 
ing  at  the  root  and  performing  a  binary 
search.  The  use  of  the  pointer  refer¬ 
ence  again  allows  for  removal  of  either 
higher,  lower,  or  the  root  linkage  with¬ 
out  explicit  code.  If  the  element  is  not 
found,  a  null  pointer  is  returned;  other¬ 
wise,  the  hole  in  the  Ptree  is  filled. 
There  are,  in  this  case,  only  four  possi¬ 
ble  linkages: 


Figure  9:  New  tree  configuration  after 
the  insertion  of  64 


ing  64  from  the  tree 


1 .  A  number  from  the  higher  interface 
can  maintain  its  original  linkage. 

2.  A  number  from  the  higher  interface 
can  be  linked  to  a  number  from  the 
lower  interface. 

3.  A  number  from  the  lower  interface 
can  maintain  its  original  linkage. 

4.  A  number  from  the  lower  interface 
can  be  linked  to  a  number  from  the 
higher  interface. 

The  Ptree  algorithm 
compares  the  number 
being  placed  with  the 
number  in  the  current 
position,  using  the 

factors  of  2  to  determine 
which  has  precedence 
( that  is,  which  should 
be  positioned  closer  to 
the  root) 


Of  these  four  cases,  there  are  only 
two  variables  in  contention:  Higher 
Inter-> Lower  and  LowerInter->Higher. 

To  further  illustrate  the  linkages,  con¬ 
sider  Figure  11.  Here,  Hole  is  set  to  64, 
Higherlnterxa  the  number  on  the  higher 
side  of  64  (in  this  case,  108),  and  Lower- 
Inter  to  the  number  on  the  lower  side 
of  64  (46),  and  the  reference  pointer 
to  this  is  set  to  whatever  was  pointing 
to  64  (in  this  case,  Array->Root).  The 
values  46  and  108  are  compared,  and 
because  108  has  the  higher  precedence, 
the  pointer  to  64  ( Array->Root )  is  now 
set  to  108,  this  is  set  to  the  address  of 


the  lower  side  of  108  (82),  and  Higher 
is  set  to  82.  Then,  82  and  46  are  com¬ 
pared,  and  because  82  has  precedence, 
the  pointer  referenced  by  this  main¬ 
tains  the  original  linkage.  In  other  words: 

since:  this  =  &HigherInter  ->  Lower 
and:  Higherlnter  = 

HigherInter->Lower 

then:  *this  =  Higherlnter 
means:  HigherInter->Lower  = 

HigherInter->Lower 

Next,  73  is  compared  to  46,  and  be¬ 
cause  46  has  precedence,  the  pointer 
referenced  by  this  is  set  to  46.  This 
links  46  to  the  lower  side  of  82.  The 
pointer  reference  this  is  now  set  to  the 
address  of  LowerInter->Higher ,  and 
Lowerlnter  is  set  to  Lower Inter->Higher 
(62).  The  process  continues  until  either 
Lowerlnter  or  Higherlnter  is  set  to  a 
null  pointer  and  the  final  linkage  made 
accordingly.  The  last  part  of  the  routine 
links  Hole  into  the  beginning  of  the 
chain  of  empty  elements  and  updates 
the  number  of  elements  used. 

Listing  Two  contains  routines  for  di¬ 
agraming  the  Ptree  and  providing  sta¬ 
tistics.  Listing  Three  has  the  user  pro¬ 
gram  for  manually  entering  and  delet¬ 
ing  numbers  from  the  Ptree  and  ob¬ 
serving  the  configuration. 

Winning  Compromise 

The  Ptree  algorithm  rapidly  constructs 
ordered  B-tree  configurations  that  are 
always  reasonably  balanced  by  strik¬ 
ing  a  winning  compromise  between 
perfection  and  practicality.  In  this  sce¬ 
nario,  linear  listing  is  virtually  nonex¬ 
istent.  Sequential  entry,  which  results 
in  a  linear  list  using  standard  B-tree 
construction  methods,  produces  per¬ 
fectly  balanced  trees  using  the  Ptree 
algorithm.  Although  the  code  in  this 
article  is  written  for  a  sparse  array,  the 
Ptree  algorithm  can  easily  be  applied 
to  any  application  requiring  an  ordered 
B-tree. 
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tax)  to  Dr.  Dobb’s Journal,  501  Galves¬ 
ton  Dr.,  Redwood  City,  CA  94063;  or 
call  800-356-2002  (from  inside  Calif.) 
or  800-533-4372  (from  outside  Calif.). 
Please  specify  the  issue  number  and 
format  (MS-DOS,  Macintosh,  Kaypro). 

DDJ 

(Listings  begin  on  page  98.) 

Vote  for  your  favorite  feature/article. 

Circle  Reader  Service  No.  4. 


Dr.  Dobb’s  Journal,  September  1989 


Figure  11:  The  interface  lines  for  the  “higher”  and  “lower”  branches 
of  the  tree 
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Roll  Your  Own 
Minilanguages  with 

Mini-Interpreters 

Customizing  assembler  code  for  speed  and  readability 


Michael  Abrash  and  Dan  lllowsky 


When  you  sit  down  to  pro¬ 
gram,  do  you  ever  think 
about  how  nice  it  would 
be  to  have  a  language  writ¬ 
ten  just  for  your  particular 
application?  Although  C,  Pascal,  assem¬ 
bler,  and  the  like  are  undeniably  pow¬ 
erful,  they’re  general-purpose  lan¬ 
guages;  as  a  result,  you  spend  most  of 
your  time  matching  the  general-pur¬ 
pose  constructs  of  those  languages  to 
the  needs  of  your  particular  applica¬ 
tions.  What  if  instead  you  had  languages 
with  commands  such  as  “Draw  cen¬ 
tered  text  at  bottom  of  screen,”  “Beep 
speaker  three  times  and  wait  for  key,” 
or  “Animate  image  left  for  specified 
distance?”  In  that  case,  simply  put,  you 
could  concentrate  on  the  functionality 
rather  than  the  implementation  of  your 
applications  —  and  your  code  would 
be  one  heck  of  a  lot  shorter,  too. 

Although  customized  languages 
sound  farfetched,  in  truth  they’re  not, 
at  least  not  on  a  small  scale.  In  this 
article  well  look  at  mini-interpreters, 
which  let  you  define  small  languages 
designed  for  specific  tasks.  Mini-inter¬ 
preters  are  easy  to  create,  make  for 
extremely  compact  programs,  are  very 
flexible,  and  are  easily  maintained  and 
modified. 

Well  start  by  defining  what  a  mini¬ 
interpreter  is.  After  that  well  explore 
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the  pros  and  cons  of  mini-interpreters, 
and  well  finish  up  by  looking  at  a  fully 
functional  mini-interpreter.  The  sam¬ 
ple  mini-interpreter  can  draw  text  and 
lines  and  perform  text-mode  anima¬ 
tion,  all  in  less  than  700  bytes. 


The  Flexibility  of 
Assembler-Defined  Data 

Before  you  can  understand  anything 
else  about  mini-interpreters,  you  must 
understand  that  the  data-definition  ca¬ 
pabilities  of  assembler  are  vastly  supe- 
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The  mini-interpreter 
fetches  the  function 
number  pointed  to 
by  the  data  sequence 
pointer ... 


...advances  the 
data  sequence 
pointer  to  point  to 
the  next  byte... 


Free-form 

data 

sequence 


...and  then  uses  the 
function  number  as 
a  lookup  index  into 
the  jump  table  and 
calls  the  corresponding 


Jump  table 


1092 


4 


JData  sequence 
pointer 


1  m  ■  ■  1 1 
•  \  '  ■  •  ' .: 
BBBWBBI 

'  V'  •  ' 

' 

'  ■  ‘  '  '  '  ■  .  . 

;  Sets  the  screen  coords  at 
I ;  which  text  will  be  drawn. 
SetXY%: 

|  lodsw 

mov  [CursorCoordsJ,  ax 
|  ret 

Sets  the  amount  by  which 
the  cursor  will  move  after 
drawing. 

>etXYInc%: 


Program  code 


Figure  I:  Operation  of  a  mini-inter/treler 
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(continued  from  page  52) 
rior  to  those  of  other  languages.  Only 
in  assembler  can  you  readily  create 
data  sequences  that  consist  of  arbi¬ 
trarily  intermixed  8-bit  unsigned  values, 
16-bit  signed  values,  16-bit  pointers, 
32-bit  pointers,  and  even  64-bit  floating¬ 
point  values. 

As  an  example,  the  following  code 
defines  the  contents  of  memory  starting 
at  label  AsmData  to  be  a  mix  of  8-bit 
signed  values,  16-bit  pointers,  and  text: 


AsmData 

db 

db 

dw 

db 

db 


label  byte 
SetXY,79,20 
SubProg 
Box4x4$ 

TextUp, ’Enter  your  name’,0 
Done 


It’s  important  to  understand  that  Asm- 
Data  in  this  example  isn’t  just  some 
sort  of  structure  or  variant  record.  The 
following  would  be  an  equally  valid 
definition  of  AsmData: 


AsmData 

label  byte 

db 

SubProg 

dw 

SpinAround$ 

db 

TextUp, ’Ten  seconds  until 

exit .  .  .’,0 

db 

Wait,  10 

db 

Cls 

db 

TextUp, ’Exited. ’,0 

db 

Done 

AsmData  is  simply  a  free-form  mix 
that  can  contain,  in  any  order,  signed 
and  unsigned  values  of  various  sizes 
and  near  and  far  pointers.  No  regular¬ 
ity,  repetition,  or  structure  is  required, 
for  the  point  of  using  assembler-de¬ 
fined  data  with  mini-interpreters  is  to 
be  able  to  mix  data  in  any  way,  un¬ 
constrained  by  the  limitations  of  high- 
level-language  data  structures.  This 
makes  possible  both  compact  data  en¬ 
coding  and  complete  flexibility  in  data 
definition. 

Try  doing  that  in  C! 

How  Mini-Interpreters  Work 

At  heart,  a  mini-interpreter  is  nothing 
more  than  a  table-lookup  loop  driven 
by  a  jump  table  and  a  free-form  se¬ 
quence  of  data.  The  interpreter  reads 
the  next  function  number  from  the  data 
sequence,  advances  the  data  sequence 
pointer,  and  calls  the  jump  table  entry 
corresponding  to  the  function  number 
read,  as  shown  in  Figure  1.  The  func¬ 
tion  called  via  the  jump  table  may  op¬ 
tionally  read  any  number  of  parame¬ 
ters  of  any  type  from  the  data  sequence, 
advancing  the  data  pointer  each  time 
it  does  so  and  preserving  the  data 
pointer  in  any  case.  When  the  function 
ends  and  returns  to  the  mini-interpreter, 
the  next  number  in  the  data  sequence 
indicates  the  next  function  to  be  exe- 
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Free-form 

data 

sequence 


The  mini-interpreter  reads  the  next  function 
number  from  the  location  pointed  to  by  the 
data  sequence  pointer,  advances  the  pointer, 
looks  up  the  function  number  in  the  jump  table, 
and  calls  the  corresponding  function,  SetXY%. 

f  The  function  SetXY%  reads  the  X  &  Y  coordinate^ 
from  the  location  pointed  to  by  the  datasequence 
pointer,  advances  the  pointer,  sets  the  X  &  Y 
coordinates,  and  returns  to  the  mini-interpreter 

Vjoop. _ 

f  The  mini-interpreter  reads  the  next  function  '7 

number  and  calls  the  corresponding  function, 

\SubProg%. _ ' _ J 

(The  function  SubProg%  starts  a  recursive  copy 
of  the  mini-interpreter  to  execute  the  subprogram 
starting  at  offset  1000.  When  the  subprogram  is 
done,  SubProg%  returns  to  the  mini-interpreter 

Vjoop- _ _ J 


The  mini-interpreter  reads  the  next  function 
number  and  calls  the  corresponding  function, 
.  TextUp% 


The  function  TextUp%  reads  and  displays 
characters  from  the  data  sequence  until  a  zero 
byte  is  encountered,  at  which  point  TextUp% 
returns  to  the  mini-interpreter. _ 


Figure  2:  An  annotated  sample  data  sequence 


cuted.  The  whole  process  is  repeated 
until  the  function  that  terminates  the 
interpreter  is  reached. 

The  key  to  the  operation  of  a  mini¬ 
interpreter  is  that  each  function  knows 
the  number  and  type  of  its  own  pa¬ 
rameters,  so  each  function  is  responsi¬ 
ble  for  reading  data  from  the  data  se¬ 
quence  and  advancing  the  data  se¬ 
quence  pointer  properly.  The  mini¬ 
interpreter  itself  needs  to  know  noth¬ 
ing  more  than  how  to  read  the  next 
function  number  from  the  data  sequence 
and  call  the  corresponding  function. 

In  Figure  2,  which  shows  an  anno¬ 
tated  sample  data  sequence,  note  that 
the  mini-interpreter  reads  only  the  func¬ 
tion  number  bytes,  calling  the  corre¬ 
sponding  function  immediately  after  do¬ 
ing  so.  Each  function  is  responsible  for 
obtaining  and  handling  its  own  pa¬ 
rameters,  thereby  leaving  the  data  se¬ 
quence  pointer  pointing  to  the  func¬ 
tion  number  for  the  next  function. 

The  basic  operation  of  a  mini-inter¬ 
preter  is  simple,  then:  A  data  sequence, 
or  “miniprogram,”  provides  function 
numbers,  which  are  used  to  vector 
through  a  jump  table  to  functions.  The 
function  numbers  are  basically  com¬ 
mands  in  the  “minilanguage”  defined 
by  the  functions  in  the  jump  table.  The 
functions  then  acquire  their  own  pa¬ 
rameters  from  the  data  sequence  as 
needed. 

Another  way  to  view  a  mini-inter¬ 
preter  is  as  a  control  program  that  al¬ 
lows  you  to  call  various  functions  in 
any  order  and  with  any  parameters. 
The  jump  table  defines  the  functions 
that  can  be  called  —  in  effect  defining 
a  minilanguage  —  and  the  data  se¬ 
quence  defines  the  calling  order  and 
the  parameters,  thereby  serving  as  a 
miniprogram.  The  same  result  could, 
of  course,  be  accomplished  simply  by 
writing  code  that  calls  the  desired  rou¬ 
tine  with  the  desired  parameters.  The 
great  advantage  of  using  a  mini-inter¬ 
preter  over  writing  equivalent  code  is 
that  a  mini-interpreter  makes  for  more 
compact  code  that’s  also  easier  to  write 
and  maintain. 

Now,  consider  this:  Pointers  to  the 
jump  table  and/or  the  data  sequence 
can  be  parameters  passed  to  the  inter¬ 
preter,  so  the  operation  of  the  inter¬ 
preter  can  be  changed  instantly.  By 
passing  in  a  pointer  to  a  different  data 
sequence,  the  functions  in  the  jump 
table  can  be  combined  in  different  or¬ 
ders  and  with  different  parameters;  in 
other  words,  a  different  miniprogram 
can  be  run.  By  passing  in  a  pointer  to 
a  different  jump  table,  the  very  minilan¬ 
guage  that  the  mini-interpreter  supports 
can  be  altered. 

In  other  words,  not  only  the  mini- 
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program  that  the  mini-interpreter  is  ain- 
ning  but  also  the  minilanguage  that  it 
supports  can  easily  be  changed,  even 
in  mid-program  —  the  ultimate  in  flexi¬ 
bility. 

Benefits  of  Mini-Interpreters 

The  benefits  of  mini-interpreters  are 
many  and  varied,  with  flexibility,  com¬ 
pact  code,  and  ease  of  use  being  high 
on  the  list.  Let’s  look  at  these  benefits 
in  more  detail. 

As  noted  earlier,  a  mini-interpreter 
is  extremely  flexible  because  it  consists 
of  nothing  more  than  a  function-vec¬ 
toring  loop  that’s  driven  by  a  jump 
table  that  defines  a  minilanguage  and 
a  data  sequence  that  defines  a  minipro¬ 
gram.  A  different  miniprogram  can  be 
executed  by  amning  a  different  data 
sequence  through  the  mini-interpreter. 
The  function  set  and/or  operation  of 
the  functions  that  make  up  a  minilan¬ 
guage  can  be  changed  at  any  time  sim¬ 
ply  by  altering  or  replacing  the  jump 
table  currently  driving  the  mini-inter¬ 
preter.  By  the  same  token,  the  minilan¬ 
guage  supported  by  a  mini-interpreter 
can  be  extended  simply  by  adding  ad¬ 
ditional  functions  to  the  jump  table. 

Not  only  can  a  mini-interpreter  switch 
from  one  minilanguage  or  miniprogram 
to  another,  but  it  can  also  nest  minilan¬ 
guages  and  miniprograms.  A  minilan¬ 
guage  command  can  easily  save  the 
current  data  sequence  pointer  and  re¬ 
cursively  start  the  mini-interpreter  with 
a  new  miniprogram,  then  restore  the 
original  data  pointer  when  the  new 
miniprogram  finishes.  In  effect,  this  al¬ 
lows  mini-interpreters  to  support  sub¬ 
routines.  Similarly,  a  minilanguage  com¬ 
mand  can  save  the  current  jump  table 
pointer  and  start  the  mini-interpreter 
with  a  new  jump  table  (and  a  new 
miniprogram  as  well,  if  desired),  thereby 
temporarily  switching  to  another  minilan¬ 
guage  altogether. 

There  really  aren’t  any  limitations  on 
the  types  of  commands  minilanguages 
can  support.  The  only  rule  is  that  the 
code  that  implements  any  given  minilan¬ 
guage  command  must  preserve  the  data 
sequence  pointer  (the  pointer  to  the 
current  miniprogram),  advancing  it  past 
any  parameters  the  command  uses. 

The  flexibility  of  minilanguage  func¬ 
tion  definition  leads  directly  to  the  next 
benefit  of  mini-interpreters,  which  is 
compact  code.  Functions  are  subject 
to  virtually  no  limitations,  so  it’s  easy 
to  tailor  them  to  perform  precisely  the 
tasks  that  a  given  application  demands, 
with  no  wasted  code.  This  means  that 
miniprograms  can  be  very  efficient  be¬ 
cause  the  commands  available  in  the 
minilanguage  are  matched  to  the  task 
at  hand. 
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Then,  too,  the  function  numbers  in 
a  minilanguage  can  easily  be  encoded 
in  a  single  byte.  This  means  that  all  the 
commands  in  a  minilanguage  can  be  1 
byte  long,  a  claim  that  not  even  assem¬ 
bler  instructions  can  make.  Again,  this 
is  made  possible  by  the  narrow  focus 
of  a  minilanguage.  Only  the  functions 
needed  for  a  specific  task  are  imple¬ 
mented  in  a  minilanguage,  in  contrast 
to  general-purpose  languages,  which 
must  support  a  wide  range  of  general- 
purpose  programming  constructs. 

The  ability  to  support  1-byte  com¬ 
mands  is  one  area  in  which  mini-inter¬ 
preters  are  superior  to  code  that  simply 
calls  the  desired  functions  one  after 
another.  A  function  call,  as  used  in  C 
or  assembler  code,  takes  a  minimum 
of  3  bytes,  in  contrast  to  the  1-byte 
command  encoding  used  by  mini-in¬ 
terpreters. 

Another  area  in  which  mini-interpret¬ 
ers  are  superior  to  code  that  calls  func¬ 
tions  is  that  of  passing  parameters.  Mini- 
interpreters  are  extremely  compact  be¬ 
cause  there’s  no  overhead  involved  in 
passing  parameters.  A  C  compiler  would 
(at  best)  generate  the  following  8-byte 
code  sequence  in  order  to  pass  a  pointer 
to  the  text  string  HelloMsg  as  a  parame¬ 
ter  to  the  function  TextUp%. 

mov  ax, offset  HelloMsg 

push  ax  ;pass  the  pointer 

as  a  parameter 

call  TextUp% 

pop  ax  ;clear  the  parame¬ 

ter  from  the  stack 

Assembler  code  could  be  smaller  — 
but  still  bulky  —  at  6  bytes: 

mov  ax, offset  HelloMsg 

call  TextUp% 

In  a  miniprogram,  however,  a  mere 
byte  of  miniprogram  code  would  suf¬ 
fice,  with  the  text  built  right  into  the 
miniprogram: 

db  15, ’Hello’, 0 

Here,  15  is  the  entry  number  of  Text- 
Up%  in  the  jump  table  that  defines  the 
current  minilanguage.  The  last  exam¬ 
ple  could  be  made  considerably  more 
readable  as  follows: 

TextUp  equ  15 

db  TextUp, Hello’, 0 

We  will  return  to  the  topic  of  making 
miniprograms  readable  shortly. 

Mini-interpreters  lend  themselves  to 
compact  code  in  every  respect.  The 


code  in  the  functions  that  implement  a 
minilanguage  tends  to  be  reused  heav¬ 
ily  because  those  functions  make  up 
the  commands  available  in  the  minilan¬ 
guage.  Programs  written  in  the  minilan¬ 
guage  can  readily  be  reused  in  the  form 
of  subprograms,  which  are  essentially 
subroutines,  particularly  as  subprograms 
can  be  nested.  Any  command  or  sub¬ 
program  can  easily  be  repeated  any 
number  of  times  simply  by  defining  a 
function  in  the  minilanguage  that  starts 
a  nested  mini-interpreter  the  desired 
number  of  times. 

The  code  of  a  mini-interpreter  itself 
can  be  extremely  small  and  usually  is. 
After  all,  mini-interpreters  don’t  actu¬ 
ally  do  much;  they’re  just  the  glue  that 
lets  a  miniprogram  call  the  functions 
that  make  up  a  minilanguage,  as  de¬ 
fined  by  the  jump  table.  Here’s  the 
entire  mini-interpreter  from  Listing  One, 
page  102,  which  we’ll  discuss  later: 

cld 

GetNextCommand: 

lodsb 

mov  bl,al 

xor  bh,bh 

shl  bx,l 

call  [bx+Function_Table] 

jmp  short  GetNextCommand 

The  functions  that  make  up  a  minilan¬ 
guage  do  take  up  code  space,  of  course, 
but  then  you’d  have  to  write  that  code 
anyway  in  order  to  accomplish  the  de¬ 
sired  task.  One  of  the  main  points  of 
using  a  mini-interpreter  is  to  let  you 
sequence  those  functions  and  pass  those 
parameters  as  efficiently  as  possible. 

By  the  way,  although  we’re  only  go¬ 
ing  to  discuss  assembler  mini-interpret¬ 
ers  in  this  article,  don’t  think  that  mini¬ 
interpreters  can’t  be  useful  in  the  con¬ 
text  of  high-level-language  programs. 
For  one  thing,  mini-interpreters  can  eas¬ 
ily  be  called  from  high-level-language 
programs  to  carry  out  specific  tasks  at 
the  cost  of  far  fewer  bytes  than  the 
high-level  language  could  manage. 

What’s  more,  mini-interpreters  can 
even  be  implemented  in  high-level  lan¬ 
guages,  albeit  not  quite  so  efficiently 
as  in  assembler.  All  that’s  required  to 
write  a  mini-interpreter  is  the  availabil¬ 
ity  of  pointers  and  the  ability  to  sup¬ 
port  jump  tables,  requirements  that  C 
meets  admirably.  One  caveat  regarding 
high-level-language  mini-interpreters, 
though:  Always  create  your  minipro¬ 
grams  in  assembler,  even  when  your 
mini-interpreters,  jump  tables,  and 
minilanguage  functions  are  all  written 
in  high-level  languages.  As  we  saw  ear¬ 
lier,  high-level  languages  can’t  come 
close  to  matching  assembler  where  flex¬ 
ible  data  definition  is  concerned  — 
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and  flexible  data  definition  is  abso¬ 
lutely  essential  when  you  want  to  cre¬ 
ate  the  most  compact  and  powerful 
miniprograms  possible. 

Ease  of  Creation  and  Maintenance 

We’ve  yet  to  cover  one  characteristic 
of  mini-interpreters,  and  that’s  ease  of 
use.  You’ve  already  seen  some  of  the 
reasons  why  mini-interpreters  are  easy 
to  use:  The  capabilities  of  minilanguages 
are  matched  to  the  task  at  hand,  so  the 

available  commands  are  intuitive  and 
fit  in  without  any  fuss,  and  minilan¬ 
guages  are  table-driven,  so  it’s  easy  to 
add  new  commands  as  the  need  arises. 
Still  and  all,  at  this  moment  minipro¬ 
grams  might  not  seem  particularly  easy 
to  write  and  maintain,  but  that’s  be¬ 
cause  you  haven’t  yet  seen  the  last 
piece  of  the  puzzle. 

That  last  piece  is  the  translation  of 
function  numbers  in  miniprograms  from 
numbers  to  symbols  by  way  of  either 
the  equ  directive  or  the  macro  direc¬ 
tive.  Assume,  for  example,  that  the  func¬ 
tion  SetXY%  is  the  second  entry  in  the 
jump  table  for  a  minilanguage.  The 
miniprogram 

db  2,79,20 

isn’t  particularly  easy  to  write  or  read  — 
in  fact,  it’s  pretty  much  incomprehen¬ 
sible.  On  the  other  hand,  the  equiva¬ 
lent  miniprogram 

SetXY  equ  2 
db  SetXY, 79, 20 

is  easy  to  write  and  perfectly  readable. 
Basically,  equated  symbols  are  used 
with  mini-interpreters  in  much  the  same 
way  that  mnemonics  are  used  with  as¬ 
semblers:  To  allow  programmers  to 
work  with  human-oriented  symbols 
rather  than  numbers. 

If  you  don’t  mind  losing  some  as¬ 
sembly  speed,  you  can  use  macros  to 
make  miniprograms  still  easier  to  use. 
Macros  can  be  used  both  to  check  the 
number  and  type  of  parameters  and  to 
make  miniprograms  more  readable  — 
for  example,  the  last  example  can  be 


implemented  as  follows: 

SetXY 

macro  X,Y,ErrorCheck 

ifnb 

<ErrorCheck> 

%out  Too  many  parame¬ 
ters  to  SetXY 

.err 

endif 

ifb 

<Y> 

%out  Too  few  parameters 
to  SetXY 

.err 

endif 

db  2,X,Y 

endm 

SetXY  79,20 

The  macro  SetXY  not  only  defines  the 
appropriate  data  for  the  SetXY  com¬ 
mand  but  also  checks  to  make  sure 
that  there  are  exactly  two  parameters. 
If  necessary,  the  if  directive  can  even 
be  used  to  check  the  magnitude  and/ 
or  types  of  the  parameters.  Once  the 
macro  is  defined,  the  actual  code  of  the 
miniprogram  —  SetXY  79,  20 —  is  intui¬ 
tive  and  easy  to  read  or  write.  A  pro¬ 
gram  written  with  such  macros  would 
look  something  like 

SetXY  0,0 

SetXYTextDirection  Down 
TextUp  ’START’, 

EndOfText 

which  is  certainly  straightforward  enough. 

We’re  not  going  to  use  macros  in  the 
example  program,  both  because  mac¬ 
ros  take  more  source  code  space  and 
because  they  tend  to  obscure  the  basic 
operation  of  the  mini-interpreter,  which 
is  what  we’re  exploring  right  now.  Mac¬ 
ros  are,  however,  the  best  way  to  go  if 
you  need  to  implement  long  minipro¬ 
grams  and/or  a  minilanguage  with  many 
commands  because  parameter  error 
checking  can  help  avoid  bugs  and  the 
improved  readability  of  macro-based 
miniprograms  can  help  you  find  your 
way  around  your  code. 

Limitations  of  Mini-Interpreters 

You  might  well  think  that  the  primary 
limitation  of  mini-interpreters  is  speed  — 
but  you’d  be  wrong.  Interpreters  are 
normally  slow,  but  mini-interpreters 
aren’t  normal  interpreters  in  that,  un¬ 
like  most  interpreters,  mini-interpret¬ 
ers  don’t  have  to  do  any  parsing.  Mini¬ 
programs  are  already  parsed  because 
they  consist  only  of  function  number 
bytes  and  function  parameters  already 
in  the  form  —  binary,  text,  what  have 
you  —  that  each  function  expects.  The 
only  overhead  incurred  by  the  mini¬ 
interpreter  is  reading  each  function 
number  from  the  miniprogram  and 
branching  to  the  corresponding  entry 
in  the  jump  table,  and  that  just  doesn’t 
take  long. 

Besides,  when  you  create  the  func¬ 
tions  that  make  up  a  minilanguage, 
you  can  pack  as  much  functionality  as 
you  want  into  any  one  function.  If 
there’s  something  that  just  has  to  be 
done  as  fast  as  possible,  you  can  create 
a  function  that  does  that  task  from  start 


to  finish  as  a  single  mini-interpreter 
command. 

No,  speed  isn’t  the  major  limitation 
of  the  mini-interpreter  approach;  that 
dubious  honor  falls  instead  to  decision 
making.  Mini-interpreters  can  branch 
in  limited  ways  —  for  example,  by  exe¬ 
cuting  a  subprogram  or  repeating  a 
command  multiple  times.  Mini-inter¬ 
preters,  however,  don’t  lend  themselves 
especially  well  to  the  more  general  sorts 
of  conditional  branching  and  code  struc¬ 
tures  that  are  needed  for  decision¬ 
making  code. 

A  command  that  conditionally 
branches  to  another  miniprogram  loca¬ 
tion  is  possible,  but  such  a  command 
couldn’t  easily  handle  generalized  con¬ 
dition  testing  with  relational,  logical, 
and  arithmetic  operations  and  would 
surely  lead  to  cryptic  spaghetti  code. 
Code  structures  such  as  if.  .  .  then.  .  .  else, 
for,  and  do.  .  .  while  aren’t  impossible, 
but  they  certainly  wouldn’t  be  easy  to 
implement. 

Even  if  they  were  easy  to  implement, 
however,  complex  control  structures 
are  contrary  to  the  reason  for  using 
mini-interpreters  in  the  first  place,  which 
is  efficient  implementation  of  well- 
defined  tasks.  If  you’re  going  to  bother 
with  general-purpose  control  structures, 
expression  evaluation,  and  the  like,  you 
might  as  well  use  a  general-purpose 
language  —  that’s  what  those  languages 
are  designed  for.  Mini-interpreters  work 
best  when  you  need  to  perform  tasks 
that  can  be  expressed  as  a  sequence 
of  parameterized  actions. 

Don’t  confuse  decision  making  with 
complexity  —  mini-interpreters  are  ex¬ 
cellent  for  many  sorts  of  complex  tasks. 
Mini-interpreters  save  proportionally 
more  space  when  used  for  lengthy  tasks, 
and  the  ease  of  writing  and  reading 
miniprograms  matters  most  when  the 
task  is  complex. 

Applications 

So  exactly  what  sort  of  complex  tasks 
are  mini-interpreters  suited  for?  They 
are  suited  for  complex  sound  genera¬ 
tion,  for  one,  because  a  miniprogram 
that  could  tweak  the  speaker  in  various 
ways  and  for  various  periods  of  time 
would  be  far  easier  to  write  than,  say, 
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assembler  code  that  did  the  same  with 
a  series  of  out  instructions  and  timer 
reads.  Manipulation  of  structured  data, 
for  another;  a  minilanguage  could  read¬ 
ily  be  built  to  control  insertion,  dele¬ 
tion,  and  modification  of  records  in  a 
database  and  fields  in  those  records, 
for  example.  Parsing  text  is  yet  another 
example,  for  mini-interpreters  lend  them¬ 
selves  well  to  tasks  that  can  be  ex¬ 
pressed  as  state  machines. 

We’ve  saved  the  most  obvious  mini¬ 
interpreter  applications,  screen  control 
and  animation,  for  last.  Next,  we’re  go¬ 
ing  to  implement  a  sample  mini-inter¬ 
preter  designed  for  precisely  those  ap¬ 
plications. 

A  Sample  Mini-Interpreter 

Listing  One  shows  a  fully  functional 
mini-interpreter  in  action.  The  sample 
miniprogram  run  by  this  mini-interpreter 
does  quite  a  bit:  It  clears  the  screen, 
displays  the  text  STARTand  END ,  draws 
a  complex  maze,  and  animates  the  move¬ 
ment  of  an  arrow  through  that  maze. 

Even  though  all  screen  output  in  List¬ 
ing  One  is  done  through  BIOS  func¬ 
tions,  the  entire  screen  is  drawn  instan¬ 
taneously  on  a  PC  AT  and  just  a  bit 
more  slowly  on  a  PC.  In  fact,  the  ani¬ 
mation  actually  must  be  slowed  down 
considerably  by  way  of  the  DELAY_ 
COUNT  value,  so  you  can  see  that  this 
mini-interpreter  provides  better  than  ade¬ 
quate  performance.  What’s  more,  List¬ 
ing  One  assembles  to  a  program  just 
684  bytes  long,  with  some  of  those 
bytes  taken  by  functions  that  aren’t  even 
used  in  the  sample  miniprogram.  Bet¬ 
ter  yet,  the  sample  miniprogram  itself, 
which  starts  at  DemoScreenS  and  ends 
at  SpinAroundS,  is  just  302  bytes  long 
in  its  entirety. 

Mini-interpreters  do  indeed  make  for 
compact  programs. 

Listing  One  illustrates  many  of  the 
desirable  features  of  mini-interpreters. 
The  main  miniprogram  starting  at  Demo- 
ScreenS  uses  subprograms  (started  with 
the  SubProg  command)  to  make  the 
program  still  more  compact  and  modu¬ 
lar.  For  example,  SpinAroundS  is  used 
twice  as  a  subprogram  to  cause  the 
arrow  to  spin  around  a  square  two 
characters  on  a  side.  If  instead  we 
wanted  the  arrow  to  spin  around  a 
square  one  character  on  a  side,  all  we’d 
need  to  do  is  change  2  to  7  in  Spin- 
Around$,  and  the  animation  of  the  ar¬ 
row  spinning  would  be  changed  through¬ 
out  the  program. 

It’s  also  interesting  to  note  that  Demo- 
ScreenS  uses  the  minilanguage’s  DoRep 
command.  In  fact,  it’s  DoRep  that’s 
used  to  repeat  SpinAround$ five  times 
in  order  to  make  the  arrow  spin  at 
the  beginning  and  end  of  the  maze, 


so  you  can  see  that  this  particular 
minilanguage  supports  repetition  of 
subprograms. 

It’s  hard  to  overstate  the  flexibility 
of  mini-interpreters  such  as  the  one  in 
Listing  One.  Because  the  entire  draw¬ 
ing  and  animation  sequence  can  be 
run  by  interpreting  DemoScreen$ ,  the 
whole  demo  could  be  repeated  simply 
by  executing  DemoScreen$  as  a  sub¬ 
program,  with  DoRep  repeating  every¬ 
thing  the  desired  number  of  times.  If 
the  interpreter  were  to  be  started  with 
the  following  miniprogram: 

db  DoRep, 3, SubProg 

dw  DemoScreen 

db  Done 

then  the  entire  demo  would  be  repeated 
three  times  —  at  a  cost  of  just  6  extra 
bytes. 

The  miniprogram  in  Listing  One  is 
easy  to  read,  too.  The  equated  names 
for  the  various  commands  are  clear,  are 
documented  where  they’re  defined  with 
equ,  and  could  be  made  clearer,  if  nec¬ 
essary,  by  lengthening  them.  As  we 
saw  earlier,  the  minilanguage  com¬ 
mands  could  be  implemented  as  mac¬ 
ros  if  either  still  greater  clarity  or  pa¬ 
rameter  checking  were  needed. 

Relatively  few  commands  were  re¬ 
quired  to  support  the  functionality  re¬ 
quired  by  this  application,  so  we  chose 
to  implement  just  one  minilanguage, 
and  to  hard-wire  the  interpreter  Interp 
for  that  one  minilanguage  by  directly 
addressing  the  minilanguage’s  jump  ta¬ 
ble  Function_Table  in  Interp.  If  we 
had  wanted  to,  however,  we  could  eas¬ 
ily  have  passed  the  address  of  the  jump 
table  into  Interp ,  thereby  allowing 
Interp  to  support  whatever  minilan¬ 
guage  the  calling  routine  chooses,  just 
as  it  already  supports  whatever  mini¬ 
program  the  calling  routine  passes  in. 
Had  we  done  that,  we  could  just  as 
easily  have  used  three  minilanguages 
as  one:  One  minilanguage  for  text  draw¬ 
ing,  one  for  maze  drawing,  and  one  for 
animation. 

By  the  way,  Interp  can  be  called 
recursively;  it  is  in  fact  called  recur¬ 
sively  from  the  SubProg%  function, 
which  is  invoked  with  the  SubProg  mini¬ 
program  command.  All  Interp  ever  looks 
at  is  the  current  byte  in  the  minipro¬ 
gram,  which  is  pointed  to  by  si,  so 
starting  a  subprogram  is  a  simple  mat¬ 
ter  of  calling  Interp  with  a  new  pointer 
in  si.  SubProg%  pushes  the  minipro¬ 
gram  pointer  —  the  pointer  to  the  mini¬ 
program  containing  the  SubProg  com¬ 
mand  —  before  calling  Interp  with  a 
pointer  to  a  subprogram  in  si.  That 
means  that  when  the  subprogram  has 
finished  and  Interp  returns  to  SubProg%, 


SubProg%  can  simply  pop  stand  return 
to  Interp  in  order  to  continue  execu¬ 
tion  of  the  original  miniprogram  with 
the  command  following  SubProg. 

Function_Table and  the  functions  fol¬ 
lowing  Interp  in  Listing  One  completely 
define  the  minilanguage  used  in  this 
program  and  provide  all  the  capabili¬ 
ties  available  to  the  miniprogram  Demo- 
Screen$.  Additional  miniprogram  code 
that  needed  commands  not  available 
in  Function JTable  c ould  be  supported 
by  writing  the  needed  functions  and 
adding  an  entry  for  each  to  Func¬ 
tionJTable.  Additional  miniprogram 
code  that  could  make  do  with  just  the 
functions  already  in  FunctionJTable 
would  be  extremely  compact  because 
it  could  be  implemented  as  nothing 
more  than  minilanguage  commands, 
without  the  need  for  a  single  byte  of 
new  assembler  code. 

As  a  final  note,  take  a  look  at  how 
the  functions  following  Interp  obtain 
their  parameters.  Each  function  gets  its 
own  parameters,  if  any,  directly  from 
the  miniprogram  data  pointed  to  by 
si,  advancing  si  so  that  it  points  to 
the  function  number  for  the  next  func¬ 
tion.  Each  function  is  free  to  obtain 
parameters  in  the  most  efficient  possi¬ 
ble  way;  for  example,  SetXY%  loads 
both  the  X  and  Y  coordinates  from  the 
miniprogram  data  sequence  with  a  sin¬ 
gle  lodsw. 

Conclusion 

Mini-interpreters  provide  a  superb  way 
to  implement  many  sorts  of  well-de¬ 
fined  tasks  in  a  minimum  of  space. 
Mini-interpreter-based  miniprograms  are 
easy  to  create  and  maintain,  and  are 
extremely  flexible.  Think  of  mini-inter¬ 
preters  whenever  program  size  is  a  con¬ 
sideration;  even  when  space  is  not  an 
issue,  you  may  want  to  take  advantage 
of  their  ease  of  use. 

Availability 

All  source  code  for  articles  in  this  issue 
is  available  on  a  single  disk.  To  order, 
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Protected  Mode  and 
Multitasking 

Putting  the  386  to  work  under  MS-DOS 


Protected  mode  on  the  80386  (and 
on  the  80286  as  well)  provides 
built-in  memory  protection  and 
hardware  support  for  multi¬ 
tasking.  There  are  not  many  ex¬ 
amples  of  protected-mode  programming 
because  most  of  the  world  uses  the 
80x86  family  to  run  MS-DOS.  I  recently 
built  a  small  symbolic  debugger  and 
multitasking  kernel  for  the  80386,  and 
learned  a  great  deal  about  protected- 
mode  programming  in  the  process.  For 
this  article,  I  developed  some  basic 
80386  tools  that  can  be  used  with  most 
MS-DOS  C  compilers.  I  used  Turbo  C 
2.0  and  TASM  1.0.  and  the  code  should 
be  portable  to  most  compilers  and  as¬ 
semblers.  (The  assemblers  must  sup¬ 
port  the  80386  instruction  set.) 

The  biggest  drawback  to  this  code 
is  that  it  runs  in  16-bit  mode.  The  80386 
allows  a  segment  to  be  marked  as  either 
a  32-bit  segment  or  a  1 6-bit  segment. 
Turbo  C  2.0  produces  code  that  uses 
only  16-bit  registers  and  does  not  take 
full  advantage  of  the  32-bit  registered 
CPU.  (When  you  develop  a  large  appli¬ 
cation,  this  factor  is  a  big  drawback.) 
The  code  does  allow  you  to  learn  more 
about  80386  protected  mode  without 
resorting  to  lots  of  assembly  language 
or  investing  in  expensive  new  tools. 

The  80386  has  32-bit  registers  and 
allows  access  to  a  4-gigabyte  address 
space.  Both  of  these  features  offer  a  big 
improvement  over  the  8086.  I  think 
that  the  most  important  improvement 
in  the  80386  is  its  hardware  support  for 
multitasking.  The  ability  of  the  80386 
to  save  and  restore  the  state  of  a  task 
is  a  big  plus  when  you  write  operating 
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systems  and  debuggers.  All  of  these  80386  machines  run  MS-DOS  as  a  virtual- 

new  features  support  16-bit  and  32-bit  mode  task  in  protected  mode.  You 

code.  As  a  result,  the  code  presented  should  be  able  to  turn  this  off,  so  check 

in  this  article  has  few  limitations.  You  the  documentation  for  your  machine 

could  use  this  code  to  develop  a  small  and  operating  system.)  The  machine 

multitasking  kernel  just  by  adding  a  timer  must  support  and  use  video  modes  2, 

interrupt  and  the  necessary  algorithms.  3,  or  7.  (This  program  writes  directly 

A  warning  before  you  get  started:  to  video  RAM  and  locates  video  RAM 

This  program  only  runs  on  an  MS-DOS  via  the  mode.  If  the  program  finds  a 

machine  with  an  80386  CPU  that  is  video  mode  it  cannot  use,  the  program 

running  MS-DOS  in  real  mode.  (Some  simply  exits.) 


Figure  1:  Three  80386  descriptor  types 
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The  Global  Descriptor  Table 

When  the  80386  nans  in  protected  mode, 
the  segment  registers  (CS,  DS,  ES,  SS, 
FS,  and  GS)  are  loaded  with  selectors. 
Each  selector  points  to  an  8-byte  de¬ 
scriptor  in  either  the  Local  Descriptor 
Table  or  the  Global  Descriptor  Table. 
Each  selector  also  contains  a  privilege 
level.  In  this  case,  all  of  the  code  and 
data  run  at  privilege  level  0  (the  highest 
privilege  level).  The  process  of  cal¬ 
culating  the  selector  for  a  given  de¬ 
scriptor  is  easy  when  privilege  level  0 
is  used  and  a  Local  Descriptor  Table  is 
not  used.  The  selector  is  the  offset  of 
the  descriptor  in  the  Global  Descriptor 
Table.  (Remember  that  a  descriptor  is 
an  8-byte  data  structure.)  To  use  descrip¬ 
tor  2,  for  example,  load  the  segment 
register  with  selector  lOh.  To  deter¬ 
mine  the  appropriate  selector,  multiply 
the  descriptor  by  8,  starting  with  de¬ 
scriptor  1.  8h,  10b ,  18b,  20h,  and  28h 
are  examples  of  typical  Global  Descrip¬ 
tor  Table  selectors.  Descriptor  0  is  the 
NULL  descriptor  and  cannot  be  used. 

Figure  1  shows  the  layout  of  the 
three  types  of  descriptors  in  this  code. 
To  avoid  confusion,  a  Local  Descriptor 
Table  is  not  used.  The  Global  Descriptor 
Table,  which  can  reside  anywhere  in 
physical  memory,  is  located  within  an 
array  of  structures  in  the  C  data  space. 
The  structure  called  “descriptor”  in  List¬ 
ing  One  (386. h),  page  109,  shows  how 
the  descriptors  in  Figure  1  look  when 
written  in  C.  An  array  of  ten  descrip¬ 
tors,  called  gdt,  is  declared  in  Listing 
Two  (task.c),  page  109-  This  array  can 
be  larger  or  smaller,  depending  upon 
how  many  descriptors  are  needed  for 
the  code.  The  Global  Descriptor  Table 
can  contain  up  to  8192  descriptors. 

Next,  set  up  the  descriptors  to  run 
the  C  program.  The  program  will  start 
running  in  real  mode,  so  the  segment 
addresses  of  the  C  code  and  data  must 
be  translated  to  physical  addresses.  This 
program  will  run  in  the  8086  Small 
model,  which  means  it  will  have  64K 
of  code  space  and  64K  for  data,  heap, 
and  stack.  (See  Figure  2  for  the  layout 
of  a  Turbo  C  Small  model  program.) 
The  segment  addresses  in  this  code 
and  data  can  easily  be  converted  into 
20-bit  physical  addresses.  To  do  so, 
left  shift  each  1 6-bit  segment  by  4. 

The  code  uses  the  three  types  of 
descriptors  shown  in  Figure  1:  Data 
Segment  Descriptors,  Executable  Seg¬ 
ment  Descriptors,  and  TSS  Descriptors. 
To  initialize  a  descriptor,  call  the  rou¬ 
tine  init_gdt_descriptor.  This  routine 
is  located  in  the  file  task.c  (Listing  Two). 
The  first  parameter  passed  to  this  rou¬ 
tine  is  a  descriptor  structure  pointer, 
which  is  the  address  of  one  of  the 
descriptors  in  the  gdt  array.  The  sec¬ 
ond  parameter  passed  to  the  routine  is 
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a  32-bit  (unsigned  long)  physical  base 
for  the  segment.  This  32-bit  physical 
address  is  the  location  where  the  seg¬ 
ment  that  is  being  created  will  start. 
The  third  parameter  passed  to  the  rou¬ 
tine  is  a  32-bit  (unsigned  long)  limit  of 
the  segment.  This  limit  indicates  the 
length  of  the  segment  measured  in 
bytes.  The  process  of  setting  up  the 
limit  in  a  descriptor  gets  a  little  compli¬ 
cated  because  only  20  bits  are  available 
to  contain  a  32-bit  value.  In  this  situ¬ 
ation,  use  the  G  bit  or  “granularity  bit.” 
This  process  (which  would  require  a 
long  description)  is  handled  by  the  C 
routine.  The  fourth  parameter  passed 
to  the  routine  is  an  8-bit  (unsigned 
char)  descriptor  type  (either  a  code, 
data,  or  TSS  descriptor). 

Six  segments  —  a  code  segment,  a 
data  segment,  three  Task  State  Seg¬ 
ments  (TSS),  and  a  video  memory  seg¬ 
ment  —  must  be  created  in  order  to 
run  this  code.  First,  the  Turbo  C  pseu¬ 
dovariables  _CS  and  _DS,  which  con¬ 
tain  the  segment  addresses  of  both  the 
code  and  the  data  segments,  are  used 
to  create  the  code  and  data  segments. 
During  the  process,  the  segment  ad¬ 
dresses  are  left  shifted  4  bits  and  turned 
into  physical  addresses.  A  64K  limit  is 
assigned  to  each  of  these  descriptors, 
so  that  each  descriptor  appears  to  the 
program  just  like  a  real-mode  segment 
would  appear.  Next,  the  three  Task 
State  Segments  are  set  up.  (Task  State 
Segments  are  described  in  more  detail 
later  in  this  article.)  Each  Task  State 
Segment  is  a  global  data  structure  with 
a  64h- byte  limit.  The  physical  address 
of  each  Task  State  Segment  is  deter¬ 
mined  by  adding  the  offset  in  the  cor¬ 
responding  data  segment  to  that  data 
segment’s  physical  address. 

The  last  segment  that  must  be  cre¬ 
ated  is  the  video  memory  segment.  This 
4000-byte  data  segment  allows  you  to 
write  directly  to  video  RAM.  When  the 
program  runs  in  protected  mode,  no 
MS-DOS  functions  can  be  accessed,  so 
the  print  routine  must  write  directly  to 
video  RAM.  After  BIOS  is  called  to  de¬ 
termine  the  video  mode,  a  segment  is 
set  up  for  color  or  monochrome  mem¬ 
ory.  The  vid_mem_ putchar  routine 
writes  characters  and  attributes  to  video 
RAM  by  using  a  far  pointer  that  con¬ 
tains  the  selector  for  the  newly  created 
video  RAM  segment. 

Task  State  Segments 

A  Task  State  Segment  is  used  by  the 
80386  when  a  task  switch  occurs.  The 
80386  has  a  special  task  register  that 
holds  the  selector  for  the  TSS  that  cor¬ 
responds  to  the  task  that  is  currently 
running.  Figure  3  shows  a  TSS. 

When  a  task  switch  occurs,  the  cur¬ 


rent  values  of  all  of  the  CPU  registers 
are  saved  into  the  task’s  TSS.  As  you 
can  see  in  Figure  3,  there  is  a  place  to 
store  all  general-purpose  registers  and 
segment  registers.  The  complete  state 
of  the  task  can  be  saved  so  that  the 
next  time  the  task  executes,  it  can  pick 
up  where  it  left  off.  After  the  current 
task’s  state  is  saved  in  that  task’s  TSS, 
the  state  of  the  new  task  is  loaded  into 
the  CPU  registers  from  the  new  task’s 
TSS.  The  CPU  begins  execution  at  the 
address  loaded  into  cs-.eip from  the  TSS. 
The  new  task  picks  up  right  where  it 
left  off  the  last  time  it  was  switched  out 
(or  it  picks  up  the  values  to  which  the 
TSS  is  initialized). 

Listing  One  contains  a  structure, 
called  “tss,”  that  can  be  used  to  set  up 
a  TSS.  This  structure  contains  several 
fields  that  begin  with  fill  and  are  not 
used  by  the  CPU,  but  must  be  zeroed. 
With  this  structure  a  TSS  can  be  initial¬ 
ized  and  installed  in  the  Global  De¬ 
scriptor  Table. 

The  routine  initjtss  in  Listing  Two 
creates  a  TSS  for  a  task.  This  routine 
sets  up  the  starting  selector  value  for 
all  segment  registers  with  the  code  and 
data  selectors  passed  ( cseg  and  dseg 
parameters).  The  ^(instruction  point¬ 
er)  is  set  up  to  point  to  the  code  of  the 
task.  The  esp  and  ebp  registers  are  set 
up  to  point  to  the  stack  for  the  new 
task.  At  this  point,  TSS  has  starting  val¬ 
ues  for  execution,  data,  and  stack.  The 
func_  ptr  ip  parameter,  which  contains 
the  address  in  the  code  segment  where 
execution  begins,  is  passed.  In  this 
code,  pass  the  address  of  the  C  func¬ 
tion  that  will  be  used  for  the  tasks 
(taskl  and  task  2). 

A  TSS  must  be  installed  in  the  Global 
Descriptor  Table  just  as  a  code  or  data 
segment  is  installed.  To  install  a  TSS, 
find  its  physical  address  in  memory 
and  set  up  the  size  limit  of  64h  bytes. 
The  type  field  of  the  descriptor  indi¬ 
cates  to  the  CPU  that  a  TSS  is  a  special 
kind  of  segment. 

Assembly  Language  Routines 

Four  assembly  language  routines  (see 
Listing  Three,  page  112)  are  required 
in  order  to  use  the  80386  code.  These 
routines  are  described  later,  and  are 
called  from  C  with  parameters  passed 
on  the  stack.  It  would  be  a  good  idea 
to  examine  Listing  Three  carefully  while 
you  read  these  descriptions. 


void  protected_mode(unsigned  long 
gdt _ptr, unsigned  int  cseg,  unsigned  int 
dseg).  This  routine  sets  everything  up 
and  makes  the  switch  to  protected 
mode.  The  first  parameter  is  gdt_ ptr, 
which  is  the  32-bit  physical  address  of 

The  ability  of  the  80386 
to  save  and  restore  the 
state  of  a  task  is  a  big 
plus  when  you  write 
operating  systems  and 
debuggers 


the  Global  Descriptor  Table.  (Pass  the 
physical  address  of  the  descriptor  array 
gdt  in  this  parameter.)  The  next  two 
parameters,  cseg  and  dseg,  are  the  se¬ 
lectors  for  the  descriptors  set  up  for  the 
selector  in  the  array  gdt.  (In  these  pa¬ 
rameters,  pass  the  selector  for  the  code 
segment  and  for  the  data  segment,  re¬ 
spectively.)  Next,  the  cs  register  is  loaded 
by  a  jmp  instruction  with  the  code  seg¬ 
ment  selector.  The  rest  of  the  segment 
registers  are  loaded  with  the  data  seg¬ 
ment  selector.  During  the  entire  pro¬ 
cess,  the  code  and  data  descriptors  have 
been  set  up  to  match  the  way  that  the 
segments  would  appear  if  the  CPU  was 
running  in  real  mode.  At  this  point,  the 
routine  can  set  everything  up  and  re¬ 
turn  to  the  C  code.  The  code,  data,  and 
stack  are  all  the  same  as  they  would 
be  in  real  mode.  The  jmp  DWORD  PTR 
p_mode  instruction  flushes  the  CPU  in- 
stiuction  prefetch  queue  and  ensures 
that  the  cs  register  is  loaded  with  the 
correct  selector.  Because  the  code  jumps 
through  a  pointer,  the  data  p_mode  is 
set  up  to  point  to  the  protect  label.  It 
may  seem  strange  to  jump  to  the  next 
instruction,  but  it  must  be  done. 

void  real_mode(unsigned  int  dseg). 
This  routine  switches  back  to  real  mode. 
The  routine  reloads  all  of  the  segment 
registers  with  the  correct  real-mode  seg¬ 
ments,  and  assumes  that  the  code  is 
executing  from  a  64K  segment.  (A  com¬ 
plete  description  of  the  process  of  switch¬ 
ing  back  to  real  mode,  is  presented  on 
page  14  -  4  of  the  Intel  80386 Program¬ 
mer’s  Reference  Manual,  so  I  will  not 
discuss  this  process  in  detail  here.)  Each 
segment  register  must  be  loaded  with 
the  selector  of  a  segment  that  has  a  64K 
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(continued  from  page  70) 
limit  before  returning  to  real  mode. 
The  parameter  dseg  is  loaded  into  all 
of  the  segment  registers  except  the  seg¬ 
ment  register  cs.  The  routine  then  per¬ 
forms  another  jump  to  the  next  instruc¬ 
tion  via  jmp  FAR  PTR  flush.  This  step 
flushes  the  instruction  prefetch  queue, 
and  loads  the  cs  register  with  the  origi¬ 
nal  code  segment  that  runs  in  real  mode. 

void  load_task_register(unsigned  int 
tss_selector).  This  routine  loads  the  CPU 
task  register  with  the  TSS  selector  that 
is  passed.  When  the  CPU  performs  the 
first  task  switch,  it  must  have  an  avail¬ 
able  TSS  where  the  current  task  state 
can  be  stored.  Before  the  routine 
switches  to  the  first  task,  the  task  regis¬ 
ter  must  be  loaded  with  a  valid  TSS 
selector. 

void jumpJto_task(unsigned  int  task). 
This  routine  switches  to  a  new  task. 
Pass  the  selector  of  the  TSS  you  want 
to  switch  to.  If  the  task  that  calls  jump_ 
to_task  is  switched  back  to,  the  task 
resumes  execution  immediately  after 
the  jmp  DWORD  PTR  new_task  instruc¬ 
tion  and  will  return  to  the  C  code  that 
called  jump_to_task.  The  code  can  then 
switch  back  and  forth  between  tasks, 
starting  where  it  left  off  at  the  task 
switch.  In  this  routine,  the  code  is  jump¬ 
ing  through  a  pointer,  so  new_task  data 
must  be  set  up  with  the  selector  of  the 
new  task.  The  address  offset  to  jump 
to  is  not  used  for  new  tasks.  The  task 
gets  the  address  to  start  running  from 
its  TSS  when  the  registers  are  loaded. 

Using  the  Code 

The  code  is  contained  in  three  files: 
task.c,  386. h,  and  mode. asm.  The  fol¬ 
lowing  Turbo  C  2.0  and  TASM  1.0  in¬ 
structions  assemble,  compile,  and  link 
the  code: 

tasm  /MX  mode. asm 

tcc  -I.  Ainclude  -L.  Alib  task.c 

mode.obj 

This  code  can  easily  be  ported  to  other 
MS-DOS  C  compilers.  The  Turbo  C  pseu¬ 
dovariables  _CS  and  _DS  are  used  to 
create  the  Global  Descriptor  Table  and 
Task  State  Segments.  If  your  C  com¬ 
piler  does  not  support  these  pseudo¬ 
variables,  you  can  create  two  small  as¬ 
sembly  language  routines  to  place  the 
values  into  the  cs  and  ds  registers.  If 
your  compiler  expects  the  return  value 
of  a  function  to  be  located  in  the  ax 
register  (which  is  usually  the  case)  the 
routines  can  be  as  simple  as  this: 

Get  current  value  of  cs  register 

mov  ax,cs 

ret 
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Get  current  value  of  ds  register 

mov  ax,ds 

ret 

Some  Turbo  C-specific  screen  I/O 
routines  have  also  been  used  in  this 
code.  If  you  port  the  code  to  another 
C  compiler,  check  that  compiler’s  man¬ 
ual  for  similar  routines. 

The  assembly  language  portion  of 
the  code  must  be  used  with  an  assem¬ 
bler  that  supports  the  80386  instruction 
set  and  some  of  the  new  features  in 
Microsoft  MASM  5.0.  Parameters  are 
expected  on  the  stack,  as  described  for 
the  Turbo  C  Small  C  memory  model. 
You  may  have  to  adjust  these  parame¬ 
ters  before  the  code  can  be  used  with 
your  compiler. 

The  code  in  its  present  form  must 
be  compiled  under  the  Small  C  mem¬ 
ory  model  in  order  to  work  properly. 
In  addition,  the  code  expects  only  two 
segments:  A  code  segment  and  a  data 
segment.  If  you  use  a  memory  model 
with  multiple  code  segments  and  a 
function  tries  to  perform  a  far  jump  to 
another  function,  the  first  function 
will  jump  to  a  differentsegment,  which 
will  be  an  invalid  selector.  With  a  lot 
of  work,  descriptors  could  be  created 
for  all  code  and  data  segments  for 
larger  C  memory  models,  but  I  would 
recommend  starting  with  the  Small 
model. 

To  run  the  program,  type  TASK.  Note 
that  the  program  prompts  you  to  press 
Return  to  enter  protected  mode.  After 
you  press  Return,  several  hello  mes¬ 
sages  from  task  1  and  task  2  appear 
on  the  screen.  Next,  you  are  returned 
first  to  the  main  task  and  finally  to  real 
mode.  You  are  then  prompted  to  press 
Return  in  order  to  exit  to  DOS. 

The  80386  allows  a  task  switch  to 
occur  when  an  interrupt  handler  is 
called.  (This  feature  comes  in  handy 
when  you  develop  a  debugger.)  When 
a  processor  exception  occurs,  the  in¬ 
terrupt  handler  can  cause  a  task  switch. 
To  determine  exactly  what  was  con¬ 
tained  in  all  of  the  registers  at  the  time 
of  the  exception,  examine  the  TSS  of 
the  task  that  caused  the  exception.  In 
addition,  because  the  80386  supports 
breakpoints  in  hardware,  your  debug¬ 
ger  can  also  use  an  interrupt  handler 
that  causes  a  task  switch  to  the  debug¬ 
ger.  Breakpoint  handling  is  easy  when 
supported  by  hardware  breakpoints  and 
multitasking.  I  recommend  a  complete 
reading  of  the  Intel  80386  Program¬ 
mer’s  Reference  Manual  to  see  all  of 
the  features  of  the  80386.  Although  this 
code  does  not  do  very  much,  it  pro¬ 
vides  a  set  of  tools  that  can  be  easily 
expanded  into  a  multitasking  kernel. 


As  mentioned  before,  there  are  some 
drawbacks  to  this  code.  Because  Turbo 
C  2.0  cannot  produce  real  32-bit  code, 
the  32-bit  registers  in  the  80386  are  not 
used.  A  solution  is  to  write  assembly 
language  subroutines  that  take  advan¬ 
tage  of  the  80386  capabilities.  In  addi¬ 
tion,  you  cannot  use  many  of  the  C 
library  routines  or  BIOS  or  MS-DOS 
calls  with  this  code.  These  routines  and 
calls  expect  information  to  be  located 
in  certain  segments,  and  will  load  the 
segment  registers  with  invalid  selectors 
in  protected  mode.  Also,  when  the 
switch  is  made  to  protected  mode,  in¬ 
terrupts  are  turned  off;  the  80386  then 
handles  interrupts  with  a  special  Inter¬ 
rupt  Descriptor  Table.  The  process  of 
implementing  this  step  would  have 
added  too  much  to  the  code,  so  inter¬ 
rupts  must  be  turned  off  when  the  code 
runs  in  protected  mode.  To  run  the 
code  in  protected  mode,  new  interrupt 
handlers  would  need  to  be  developed. 
If  you  develop  an  Interrupt  Descriptor 
Table,  use  the  code  in  a  Global  De¬ 
scriptor  Table  as  a  guide  (the  two  ta¬ 
bles  are  similar). 

I  hope  that  this  article  has  provided 
some  insights  into  80386  protected- 
mode  programming.  If  you  examine 
this  code  with  the  help  of  the  article 
and  the  Intel  80386 Programmer’s  Ref¬ 
erence  Manual ,  you  should  be  able  to 
use  protected  mode.  In  general,  most 
examples  of  protected-mode  routines 
are  written  in  assembly  language  and 
are  difficult  to  understand.  When  the 
Global  Descriptor  Table  and  Task  State 
Segments  are  created  using  C,  protected- 
mode  programs  are  much  simpler  to 
set  up  and  to  install. 
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Watcom  C7.0 

Good  things  do  get  better 


John  M.  Dlugosz 


You’ll  notice  right  away  that  Wat¬ 
com  is  unique.  As  you  open 
the  box  you’ll  find  a  library- 
quality  magazine  holder  con¬ 
taining  several  slim  books,  a 
package  of  disks,  and  a  foam  block 
that  prevents  the  contents  from  rattling 
around  during  shipping.  Throw  the 
foam  away  and  you’ve  got  a  conve¬ 
nient  caddy,  the  perfect  size  for  storing 
books.  This  kind  of  functionality  sums 
up  Watcom  C7.0. 

Documentation 

Watcom’s  documentation  consists  of  a 
Library  Reference  Manual,  Language 
Reference  (including  a  Programmer’s 
Guide),  Optimizing  Compiler  and  Tools 
User’s  Guide,  Express  C  User’s  Guide, 
and  Graphics  Library  Reference.  Among 
the  smaller  documents  are  an  Adden¬ 
dum  to  the  Library  Reference,  Watcom 
Editor  User’s  Guide,  a  Read  Me  First, 
and  a  set  of  8.5-  x  3-inch  fanfold  refer¬ 
ence  cards  (one  covers  the  compiler 
and  tools  use,  including  C  syntax,  an¬ 
other  the  library,  and  a  third  the  graph¬ 
ics  library),  that  fits  nicely  under  the 
keyboard. 

The  no-nonsense  installation  instruc¬ 
tions  are  written  with  the  assumption 
that  you  know  what  you’re  doing,  un¬ 
like  other  instructions  I’ve  recently  seen. 
They  tell  you  what  is  on  the  disks  and 
how  the  installation  program  (which 
is  excellent)  will  arrange  the  files  on 
the  hard  disk.  You  can  do  without  the 
install  program  if  you  like. 

The  User’s  Manual  tells  you  how  to 
run  the  compiler,  debugger,  make  util¬ 
ity,  and  associated  tools,  and  about  the 
pragmas,  calling  conventions,  and  other 
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important  information.  The  Language 
Reference  manual  is  a  reference  to  the 
C  syntax,  and  provides  compiler-de¬ 
pendent  information  (bit  field  organi¬ 
zation,  for  instance).  Everything  you 
need  to  know  about  the  compiler  and 
the  language  implementation  seems  to 
be  listed,  except  how  multi-byte  char¬ 
acter  constants  (such  as  ‘ab’  —  Wat¬ 
com,  is  that  0x6l62  or  0x6261?)  are 
handled.  One  shortcoming,  however, 
is  that  the  books  neither  reference  each 
other  nor  have  a  common  index. 

The  information  in  the  User’s  Guide 
for  the  compiler  and  the  debugger  is 
disorganized,  though  the  index  is  ex¬ 
cellent.  I  thought  the  book  suffered 
from  an  attempt  to  arrange  sections  in 
a  “tutorial”  order  instead  of  as  a  “pure” 
reference  manual.  Nevertheless,  as  a 
reference  for  someone  who  knows  what 
he  is  looking  for,  the  documentation 
is  a  winner. 

Utilities 

The  driver  WCL  is  a  typical  C  compiler 
driver.  You  can  list  file  names  (with 
wild  cards)  and  options  on  the  com¬ 
mand  line  to  compile  and  link  the  files. 
You  can  give  the  program  OBJ  files,  LIB 
files,  and  C  source  files,  but  not  ASM 
files.  Unfortunately  the  options  apply 
to  all  the  files,  rather  than  just  those 
files  that  are  listed  after  the  option 
switch,  which  means  that  you  cannot 
give  different  options  to  different  files. 

You  can  reduce  memory  require¬ 
ments  and  increase  speed  by  using 
WCC,  the  C  compiler,  in  make  files  or 
anywhere  else  the  driver  is  not  needed 
or  wanted. 

Because  the  linker,  WLINK,  does  not 
use  the  same  commands  as  Microsoft’s 
linker  (and  those  that  imitate  it),  you’ll 
have  problems  with  your  existing  linker 
response  files.  (WLINK  is  modeled  af¬ 
ter  PLINK.)  I  took  an  existing  project 


and  tried  to  switch  to  Watcom’s  com¬ 
piler:  I  first  switched  to  the  WCC  com¬ 
mand  in  the  make  file  (with  the  proper 
switches),  keeping  my  old  linker  so  I 
would  not  have  to  rewrite  the  linker 
response  file.  I  ran  into  two  problems: 
First,  other  linkers  cannot  handle  Wat¬ 
com’s  OBJ  modules  that  contain  de¬ 
bugging  information.  Second,  because 
Watcom’s  OBJ  files  use  a  different  for¬ 
mat  for  storing  the  default  library  search, 
other  linkers  will  not  find  it,  and  you 
will  have  to  add  the  library  names  to 
the  linker  response  file. 

The  linker  does,  however,  support 
multiple  overlays,  and  lets  you  include 
or  exclude  debugging  information  on 
a  module-by-module  basis. 

Also  included  is  a  window-based  de¬ 
bugger  called  WVIDEO.  I’m  not  sure 
how  much  memory  it  needs,  but  I  know 
it  requires  much  less  than  CodeView. 
Because  it  loads  symbols  from  the  disk 
module  by  module,  you  can  include 
debug  information  on  everything  and 
not  run  out  of  memory.  All  windows 
are  the  full  width  of  the  screen,  can  be 
moved  or  resized  vertically,  and  can 
overlap. 

The  debugger  is  powerful,  and  has 
a  macro  language  that  controls  all  the 
features  and  functions.  You  can  use 
the  command  line  to  type  in  commands 
or  select  options  (using  the  Alt  key) 
from  a  menu  along  the  top  of  the  screen. 
You  must  use  the  up-  and  down-arrow 
keys,  not  the  initial  keys,  and  press 
Return  to  select  choices  from  submenus, 
or  you  can  choose  items  with  a  mouse. 
The  Tab  key  moves  the  cursor  from 
window  to  window;  with  a  source  of 
assembly  listing  window,  for  instance, 
you  can  move  the  cursor  and  inspect 
different  parts  of  the  program. 

Commands  (or  a  sequence  of  com¬ 
mands)  can  be  assigned  to  a  single 
(continued  on  page  77) 
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key,  and  are  context-sensitive  based 
on  the  window  you  are  in.  So  you  can 
assign  a  key  to  set  a  breakpoint  at  the 
cursor  position  in  the  source  window, 
another  to  single  step  one  step,  or  what¬ 
ever  you  like.  The  file  called  PRO¬ 
FILE. DBG  is  loaded  when  the  session 
is  started  and  contains  all  the  Hot-key 
assignments,  window  layout,  and  ev¬ 
erything  else  you  start  up  with.  You 
can  modify  this  file  to  arrange  things 
the  way  you  like. 


The  Debugger 

Debugger  macros  can  refer  to  variables 
in  your  program,  or  to  variables  de- 


Figure  1:  A  simple  function  that  has 
been  optimized 


fined  by  the  debugger.  A  print/- like 
function  displays  values,  an  If  state¬ 
ment  makes  conditional  choices,  and 
long  scripts  can  be  stored  in  disk  files. 
What  I  liked  best,  however,  is  that  break¬ 
points  can  trigger  macro  execution. 

The  debugger  is  not  perfect,  how¬ 
ever,  as  there  is  no  “watch”  window. 
(I’d  like  a  window  that  would  display 
the  results  of  a  number  of  expressions 
that  I  want  to  keep  an  eye  on.)  A  “com¬ 
mand"  window,  however,  can  be  con¬ 
figured  to  function  as  a  watch  window. 
The  command  window  is  considerably 
more  powerful  than  a  typical  “watch.” 
It  will  execute  a  statement  list,  which 
presumably  contains  some  PRINT  state¬ 
ments,  every  time  the  window  is  up¬ 
dated. 

The  other  thing  I  don't  like  about  the 
debugger  is  that  an  array  of  chars  is 
always  displayed  as  the  address  of  the 
first  element.  If  I  want  to  see  the  value 
of  a  string,  I  must  use  a  format  string 
like  ?{%s!  name  to  display  the  contents 
of  name  in  a  meaningful  way.  Unfortu¬ 
nately  the  same  thing  happens  when 
displaying  an  entire  structure  —  if  you 
print  a  structured  type  variable,  all  the 
fields  are  printed  You  can  also  bring 
up  an  interactive  inspector,  which  shows 
the  fields,  and  then  select  any  of  them 
to  display.  In  both  forms,  strings  show 
up  as  their  address. 

When  debugging  is  complete,  the 
WSTRIP  utility  will  remove  debugging 
information  from  the  EXE  file.  All  in 
all,  the  debugger  is  good  enough  for 
you  to  invest  the  time  it  takes  to  learn 
how  to  use  it  well. 

The  Compiler 

Though  the  compiler  does  not  gener¬ 
ate  a  compiled  listing,  a  separate  utility, 
WDISASM,  disassembles  an  OBJ  file 
and  correlates  it  with  the  original  C 
source.  This  is  the  best  such  utility  I 
have  seen.  You  can  specify  many  de¬ 
tails,  like  putting  register  names  in  all 
caps,  using  [BX-2]  form  instead  of 
2[BX],  including  symbol  references,  and 
producing  an  assembled  listing  or  as¬ 
sembly  source  code  only.  With  full  sym¬ 
bolic  information  in  the  OBJ  file,  it 
does  a  great  job.  Other  tools  included 
are  a  library  manager,  a  touch  utility,  a 
make  utility,  and  a  patch  utility. 

The  compiler  itself  is  the  heart  of  the 
package.  It  is  somewhat  slower  than 
other  compilers,  but  it  finds  all  the  er¬ 
rors  before  it  starts  crunching  away  on 
the  code  generation  part,  so  the  devel¬ 
opment  turn-around  time  is  very  fast. 
One  nice  touch  is  that  if  you  see  a 
warning  you  don’t  like,  the  Break  key 
stops  compilation  and  aborts  instantly. 


The  Code  Generator 

The  code  generator  is  terrific.  It  passes 
parameters  in  registers,  which  can  do 
wonders  for  both  size  and  speed.  In 
some  cases  the  object  code  produced 
was  a  third  of  the  size  of  Microsoft’s. 
For  short  and  simple  functions,  much 

The  debugger  is  good 
enough  for  you  to  invest 
the  time  it  takes  to  learn 
how  to  use  it  well 


of  the  overhead  of  a  function  call  is 
eliminated,  and  it  becomes  more  of  an 
assembly  language  subroutine  than  a 
high-level  language  function  call.  Fig¬ 
ure  1,  for  instance,  shows  a  simple 
function  that  has  been  optimized.  No¬ 
tice  that  a  stack  frame  is  not  generated 
and  that  the  resulting  function  is  a  sim¬ 
ple  subroutine  that  doesn’t  have  the 
overhead  of  a  high-level  language  call. 

With  optimization  disabled,  the  code 
generator  still  generates  fair  code,  so 
some  simple  improvements  must  be 
built  into  the  code  generator  on  a  primi¬ 
tive  level.  Without  optimization,  the 
symbolic  debug  information  is  superb. 
All  the  line  numbers  and  local  symbol 
information  are  exactly  where  I  would 
expect,  without  quirks.  Even  normal 
optimization  is  easy  to  follow  in  the 
debugger,  with  the  exception  of  loop 
optimization,  where  invariant  expres¬ 
sions  are  hoisted  out. 

There  are  numerous  ways  to  fine- 
tune  code  generation.  You  can  use  a 
pragma  to  modify  function  attributes, 
and  you  can  specify  the  calling  se¬ 
quence  in  some  detail  (including  how 
parameters  are  passed,  how  the  call  is 
made,  how  the  value  is  returned,  who 
clears  any  parameters  from  the  stack, 
which  registers  are  not  preserved  by 
the  function,  what  name  the  linker  will 
know  it  by,  and  other  information). 
You  can  even  have  a  “function”  that 
generates  a  sequence  of  bytes  (which 
should  correspond  to  some  meaning¬ 
ful  assembly  language)  instead  of  a 
call  instruction.  For  example,  I  had  a 
function  called  bios_int(  Jthat  was  writ¬ 
ten  in  assembly  language.  It  took  four 
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unsigned  parameters  and  loaded  them 
into  the  AX,  BX,  CX,  and  DX  registers, 
did  an  INT  lOh  call,  and  returned  the 
value  from  AX.  With  Watcom  7.0, 1  can 
define  a  pragma  saying  that  int_bios 
receives  its  parameters  in  AX,  BX,  CX, 
DX,  returns  a  value  in  AX,  and  gener¬ 
ates  an  INT  lOh  instruction  when  the 
function  is  called  instead  of  calling  a 
function.  In  other  words,  the  assembly 
language  function  was  completely  elimi¬ 
nated  and  replaced  by  intrinsic  code 
generation  that  does  the  same  thing. 

Watcom ’s  strong 
suit  is  its  code 
generation 

The  amount  of  information  that  can 
be  specified  by  pragmas  is  enormous. 
You  can  fine-tune  a  program's  perform¬ 
ance,  call  functions  that  were  compiled 
by  a  different  compiler,  and  fix  linkage 
problems. 

One  interesting  feature  is  that  you  can 
use  a  pragma  to  specify  exactly  what 
“cdecl,”  “pascal,”  and  “fortran”  modifi¬ 
ers  mean.  For  example,  you  can  have 
cdecl  mean  the  Microsoft  C  calling  con¬ 
vention,  or  you  could  have  it  mean 
something  else  if  you  were  using  li¬ 
braries  produced  for  another  compiler. 
This  can  be  set  up  to  use  existing  as¬ 
sembly  language  routines.  There  is  one 
quirk,  though.  In  large  models,  the  DS 
register  is  used  freely  and  does  not 
necessarily  point  to  DGROUP  when  your 
assembly  language  function  is  called. 
A  compiler  switch  can  be  used  to  elimi¬ 
nate  this  behavior,  and  DS  points  to 
DGROUP  throughout  the  program.  It 
would  be  better  to  allow  the  pragma 
to  specify  that  DS  be  loaded  before  the 
function  is  called. 

As  I  said  before,  errors  in  the  source 
are  quickly  found.  You  can  even  call 
the  compiler  with  a  switch  for  syntax- 
check  only.  For  the  most  part,  the 
check  finds  mistakes  in  the  source  that 
you  would  expect  a  modern  day  com¬ 
piler  to  find,  though  it  can  miss  some. 
Figure  2  illustrates  that  it  did  not 
warn  me  that  I  was  passing  a  far  pointer 
where  a  long  was  expected.  Neither 
does  it  always  catch  type  errors  where 
typedef  are  involved. 

In  addition  to  this  compiler,  the  pack¬ 
age  includes  an  Express  C  integrated 
environment  compiler,  though  most 
professional  programmers  would  rather 
have  a  regular  version. 


ANSI  Conformance 

Because  the  packaging  proudly  pro¬ 
claimed  “100%  ANSI,"  I  decided  to  delve 
into  the  conformance  issue.  I  tried  the 
home  version  of  the  Plum-Hall  valida¬ 
tion  suite,  and  found  that  the  symbol 
HUGEJVAL  caused  a  linker  error  be¬ 
cause,  it  seems,  the  value  is  actually 
defined  in  the  floating  point  library. 

The  library  name  was  not  included  for 
linking,  even  though  a  variable  of  type 
double  was  defined  and  a  floating  point 
comparison  was  made.  This  shows  that 
you  might  define  a  double  variable  and 
call  printf( ),  and  have  it  not  work  be-  Figure  2:  Example  demonstrating  how 
cause  the  printf(  )  linked  in  was  taken  a  parameter  of  incorrect  type  is  passed 

from  the  regular  library.  This  probably  without  warning 
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would  have  worked  on  a  more  realistic 
program.  I  brought  this  to  Watcom’s 
attention,  and  they  indicated  that  they’ll 
move  the  symbol  into  the  regular  li¬ 
brary.  (Watcom  ought  to  link  the  float¬ 
ing  point  library  in  if  any  floating  point 
variable  is  defined,  as  the  method  they 
are  using  does  not  catch  all  the  cases 
where  it  is  needed.) 

For  things  like  the  order  of  transla¬ 
tion,  double-slash  comments,  line  con¬ 
tinuation,  required  headers,  and  even 
trigraphs,  C7.0  came  through  with  fly¬ 
ing  colors. 

While  the  const  and  volatile  key  words 
are  recognized,  the  semantics  are  not 
all  available.  A  direct  constant  variable 
is  treated  properly,  but  pointers  to  con¬ 
stants  are  not.  In  a  case  like  const  char 
*s;,  the  assignment  *s=c;  is  not  caught 
as  an  error.  As  for  volatile,  it  does  not 
always  prevent  the  kinds  of  optimiza¬ 
tion  it  is  supposed  to.  Figure  3,  which 
is  part  of  a  const  semantics  test  I  ran, 
indicates  that  Watcom  7.0  does  not  im¬ 
plement  pointers  to  const  values. 

I  looked  at  the  standard  library  and 
found  all  the  standard  headers.  I  then 
checked  some  of  the  more  exotic  as¬ 
pects  of  ANSI-ism.  The  library  has  lo¬ 
cale  functions  (probably  the  single  most 
difficult  thing  to  implement)  but  only 
the  “C”  locale  is  supported,  so  you 
can’t  call  setlocale( )  (or  if  you  do  call 
it  with  C,  it  doesn’t  actually  have  to  do 
anything!).  Likewise,  localeconv( )  can 
be  a  trivial  function,  and  any  functions 
that  depend  on  the  current  locale  don’t 
have  to  do  anything  special  because 
the  locale  never  changes. 

There  are  multi-byte  character  han¬ 
dling  functions  like  mblen( ),  which 
gives  the  number  of  bytes  in  the  multi¬ 
byte  character  pointed  to,  and  mbtowcl  ), 
which  converts  a  multi-byte  character 
to  a  wide  character.  But  these  func¬ 
tions  are  trivial  because  the  library  does 
not  actually  support  character  sets  that 
have  characters  comprising  more  than 
one  byte.  Many  of  the  new  functions 
(40  to  be  exact)  are  listed  in  the  Adden¬ 
dum,  but  not  in  the  Library  Reference 
nor  in  the  quick  reference  card. 


void  fl  01  ( ) 

{ 

const  char  *  const  s=  g; 

*s=  c;  //error,  but  allowed  by  Watcom 
s=  p;  //error 
} 


Figure  J:  This  test  indicated  that  Wat¬ 
com  C7.0  does  not  implement  pointers 
to  const  values 


The  standard  library  is  rich,  having 
all  the  ANSI  required  functions  and  all 
the  DOS  expected  functions,  like  FP_ 
SEG( )  and  intdos( ).  Functions  like 
_splitpath( ),  _heapchk( ),  and  _heap- 
shrink( )  (which  frees  any  unused  mem¬ 
ory  back  to  DOS  in  preparation  for  a 
systemO  call)  are  welcome  additions 
to  this  version.  The  library  supports 
most  of  the  niceties  that  I’ve  encoun¬ 
tered  on  other  compilers  with  one 
exception:  I  would  like  to  be  able  to 
automatically  expand  wild  card  file 
names  in  the  argv[ J  list  passed  to 
main(  ). 

Wrapping  It  Up 

Watcom  7.0’s  strong  suit  is  its  code 
generation.  With  its  efficient  calling  con¬ 
ventions,  good  optimization,  and  pow¬ 
erful  pragmas,  it  can  generate  tight  and 
fast  code.  It  has  a  rich  library,  and  is  a 
good  first  cut  at  an  ANSI-conforming 
implementation.  The  linker  handles  over¬ 
lays  well  and  the  debugger  can  set  up 
complex  debugging  scenarios.  I  would 
be  wary  of  the  flaws  in  compile  time 
error  checking,  though.  That  Watcom 
7.0  occasionally  misses  bad  parameter 
types  and  doesn’t  fully  implement  const 
detracts  from  the  overall  evaluation. 
Watcom  7.0  is  worth  using  for  the  code 
generator  if  that  is  what  is  important 
to  you. 


Product  Information 


Watcom  C7.0:  requires  an  IBM  PC/ 
XT/AT  and  PS/2  and  compatibles 
with  512K  memory,  DOS  2.0,  or  later. 


Watcom  C7.0/386:  is  exactly  the 
same  as  C7.0  but  (obviously)  re¬ 
quires  a  386-based  machine.  C7.0/ 
386  compiles  32-bit  80386  native 
code.  The  initial  release  does  not 
include  a  linker  or  debugger,  al¬ 
though  future  releases  will.  This  re¬ 
lease  does  use  Phar  Lap  DOS  Exten¬ 
der  Tools  and  AI  Architect’s  OS/386. 
$895.  Watcom  Products  Inc.,  415  Phil¬ 
lip  Street,  Waterloo,  ON  N2L  3X2, 
Canada;  1-800-265-4555. 
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A*  ALGORITHM 


Listing  One  (Text  begins  on  page  16.) 


**  printed  circuit  board  autorouter.  Copyright  (C)  Randy  Nevin  1989. 
**  you  may  give  this  software  to  anyone,  make  as  many  copies  as  you 
**  like,  and  post  it  on  public  computer  bulletin  boards  and  file 
**  servers,  you  may  not  sell  it  or  charge  any  fee  for  distribution 
**  (except  for  media  and  postage),  remove  this  comment  or  the 
**  copyright  notice  from  the  code,  or  claim  that  you  wrote  this  code 
**  or  anything  derived  from  it. 

**  the  author's  address  is:  Randy  Nevin,  1731  211th  PL  NE,  Redmond, 
**  WA  98053.  this  code  is  available  directly  from  the  author;  just 
**  send  a  floppy  and  a  self-addressed  floppy  mailer  with  sufficient 
**  postage,  however,  you  should  first  attempt  to  get  a  copy  of  this 
**  software  package  from  the  Dr.  Dobb's  Journal  BBS. 

*/ 

/*  the  low-order  bit  indicates  a  hole  */ 

♦define  HOLE  OxOOOOOOOlL  /*  a  conducting  hole  */ 

/*  traces  radiating  outward  from  a  hole  to  a  side  or  corner  */ 


/*  blocking  masks  for  neighboring  cells  */ 

♦define  BLOCK_NORTHEAST  (  DIAG_NEtoSW  !  BENT_StoNE 
:  ANGLE_NEtoSE  !  ANGLE_NWt' 
;  SHARP_NtoNE  1  SHARP_EtoN: 
♦define  BLOCK_SOUTHEAST  (  DIAG_SEtoNW  !  BENT_NtoSE 
:  ANGLE  NEtoSE  !  ANGLE  SEti 


BENT_StoNE  I  BENT_WtoNE  \ 
ANGLE_NWtoNE  \ 
SHARP_EtoNE  ) 

BENT_NtoSE  :  BENT_WtoSE  \ 
ANGLE_SEtoSW  \ 
SHARP_StoSE  ) 

BENT_NtoSW  :  BENT_EtoSW  \ 
ANGLE_SWtoNW  \ 
SHARP_WtoSW  ) 

BENT_EtoNW  I  BENT_StoNW  \ 
ANGLE_NWtoNE  \ 
SHARP_NtoNW  ) 


♦define  HOLE_NORTH 
♦define  HOLE_NORTHEAST 
♦define  HOLE_EAST 
♦define  HOLE_SOUTHEAST 
♦define  HOLE_SOUTH 
♦define  HOLE_SOUTHWEST 
♦define  HOLE_WEST 
♦define  HOLE  NORTHWEST 


0x00000002L  /*  upward 
0x00000004L  /*  upward  and  right 
0x00000008L  /*  to  the  right 
OxOOOOOOlOL  /*  downward  and  right 
Ox00000020L  /*  downward 
0x00000040L  /*  downward  and  left 
Ox00000080L  /*  to  the  left 
OxOOOOOlOOL  /*  upward  and  left 


/*  straight  lines  through  the  center  */ 

♦define  L I NE_HOR I ZONTAL  0x00000002L  /*  left-to-right  line  */ 

♦define  LINE_VERTICAL  Ox00000004L  /*  top-to-bottom  line  */ 

/*  lines  cutting  across  a  corner,  connecting  adjacent  sides  */ 
♦define  CORNER_NORTHEAST  Ox00000008L  /*  upper  right  corner  */ 

♦define  CORNER_SOUTHEAST  OxOOOOOOlOL  /*  lower  right  corner  */ 

♦define  CORNER_SOUTHWEST  0x00000020L  /*  lower  left  corner  */ 

♦define  CORNER_NORT H WE S T  0x00O00040L  /*  upper  left  corner  */ 

/*  diagonal  lines  through  the  center  */ 

♦define  DIAG_NEtoSW  0x00000080L  /*  northeast  to  southwest  */ 

♦define  DIAG  SEtoNW  OxOOOOOlOOL  /*  southeast  to  northwest  */ 


/*  135  degree  angle  side- 
♦define  BENT_NtoSE 
♦define  BENT_NtoSW 
♦define  BENT_EtoSW 
♦define  BENT_EtoNW 
♦define  BENT_StoNW 
♦define  BENT_StoNE 
♦define  BENT_WtoNE 
♦define  BENT  WtoSE 


to-far-corner 
Ox00000200L  /* 
0x00000400L  /* 
Ox00000800L  /* 
OxOOOOlOOOL  /* 
Ox00002000L  /* 
OxOOO04OOOL  /* 
0x00008000L  /* 
OxOOOlOOOOL  /* 


lines  */ 

north  to  southeast  */ 
north  to  southwest  */ 
east  to  southwest  */ 
east  to  northwest  */ 
south  to  northwest  */ 
south  to  northeast  */ 
west  to  northeast  */ 
west  to  southeast  */ 


/*  90  degree  corner-to-ad jacent-corner  lines  */ 

♦define  ANGLE_NEtoSE  Ox00020000L  /*  northeast  to  southeast 
♦define  ANGLE_SEtoSW  Ox00040000L  /*  southeast  to  southwest 
♦define  ANGLE_SWtoNW  Ox00080000L  /*  southwest  to  northwest 
♦define  ANGLE_NWtoNE  OxOOlOOOOOL  /*  northwest  to  northeast 


/*  45  degree  angle  side- 
♦define  SHARP_NtoNE 
♦define  SHARP_EtoNE 
♦define  SHARP_EtoSE 
♦define  SHARP_StoSE 
♦define  SHARP_StoSW 
♦define  SHARP_WtoSW 
♦define  SHARP_WtoNW 
♦define  SHARP  NtoNW 


to-near-corner 
Ox00200000L  / 
OxOO40OOOOL  / 
Ox00800000L  / 
OxOlOOOOOOL  / 
Ox02000000L  / 
Ox04000000L  / 
Ox08000000L  / 
OxlOOOOOOOL  /' 


lines  */ 

north  to  northeast 
east  to  northeast 
east  to  southeast 
south  to  southeast 
south  to  southwest 
west  to  southwest 
west  to  northwest 
r  north  to  northwest 


/*  directions  the  cell  can  be  reached  from  (point  to  previous  cell) 

♦define  FROM_NORTH  1 

♦define  FROM_NORTHEAST  2 

♦define  FROM_EAST  3 

♦define  FROM_SOUTHEAST  4 

♦define  FROM_SOUTH  5 

♦define  FROM_SOUTHWEST  6 

♦define  FROM_WEST  7 

♦define  FROM_NORTHWEST  8 

♦define  FROM_OTHERSIDE  9 

♦define  TOP  0 
♦define  BOTTOM  1 
♦define  EMPTY  0 
♦define  ILLEGAL  -1 

/*  visit  neighboring  cells  in  this  order 
**  (where  (9]  is  on  the  other  side): 


:  4  :  [9] :  5  : 
+ — + — + — + 
:  6  :  7  :  8  : 
+ — + — + — + 


static  int  delta ( 8 ] [ 2 ]  =  {  /*  for  visiting  neighbors  on  the  same  side 
(  1,  —1  ) ,  /*  northwest  */ 

(  1,  0),/*  north  */ 

(  1,  1  ),  /*  northeast  */ 

{  0,  -1  1,  /*  west  */ 

(  0,  1  ),  /*  east  */ 

(  -1,  -1  1,  /*  southwest  */ 

(  -1,  0  },  /*  south  */ 

(  -1,  1  )  /*  southeast  */ 


static  int  ndir[8]  =  {  /*  for  building  paths  back  to  source  */ 
FROM_SOUTHEAST ,  FROM_SOUTH,  FROM_SOUTHWEST, 

FROM_EAST,  FROM_WEST, 

FROM  NORTHEAST,  FROM  NORTH,  FROM  NORTHWEST 


1  SHARP_EtoSE  :  SHARP_StoSE  ) 

♦define  BLOCK_SOUTHWEST  (  DIAG_NEtoSW  I  BENT_NtoSW  I  BENT_EtoSW  \ 

I  ANGLE_SEtoSW  1  ANGLE_SWtoNW  \ 

:  SHARP_StoSW  :  SHARP_WtoSW  ) 

♦define  BLOCK_NORTHWEST  (  DIAG_SEtoNW  :  BENT_EtoNW  !  BENT_StoNW  \ 

I  ANGLE_SWtoNW  1  ANGLE_NWtoNE  \ 

I  SHARP_WtoNW  :  SHARP_NtoNW  ) 

struct  block  { 

int  rl,  cl;  long  bl,  hi; 
int  r2,  c2;  long  b2,  h2; 

}; 

static  struct  block  blocking [8]  =  (  /*  blocking  masks  */ 

1  0,-1,  BLOCK_NORTHEAST ,  HOLE_NORTHEAST , 

1,  0,  BLOCK_SOUTHWEST,  HOLE_SOUTHWEST  ), 

{  0,  0,  0,  0,  0,  0,  0,  0  ), 

(  1,  0,  BLOCK_SOUTHEAST,  HOLE_SOUTHEAST , 

0,  1,  BLOCK_NORTHWEST,  HOLE_NORTHWEST  ), 

{  0,  0,  0,  0,  0,  0,  0,  0  1, 

(  0,  0,  0,  0,  0,  0,  0,  0  ), 

(  0,-1,  BLOCK_SOUTHEAST,  HOLE_SOUTHEAST, 

-1,  0,  BLOCK_NORTHWEST,  HOLE_NORTHWEST  }, 

(  0,  0,  0,  0,  0,  0,  0,  0  }, 

{  -1,  0,  BLOCK_NORTHEAST ,  HOLE_NORTHEAST , 

0,  1,  BLOCK_SOUTHWEST,  HOLE_SOUTHWEST  ) 

1; 

static  int  self ok ( 5 ] ( 8 ]  =  {  /*  mask  for  self-blocking  corner  effects  */ 

<  1,  1,  1,  1,  1,  1,  1,  1  1, 

(  0,  0,  0,  0,  1,  0,  1,  0  ), 

{  0,  0,  0,  1,  0,  0,  1,  0  ), 

{  0,  1,  0,  0,  1,  0,  0,  0  ), 

{  0,  1,  0,  1,  0,  0,  0,  0  ) 

1; 

static  long  newmask[5] [8]  =  {  /*  patterns  to  mask  in  neighbor  cells  */ 

{  0,  0,  0,  0,  0,  0,  0,  0  ), 

(  0,  0,  0,  0,  CORNER_NORTHEAST  I  CORNER_SOUTHEAST ,  0, 
CORNER_SOUTHEAST  !  CORNER_SOUTHWEST,  0  ), 

{  0,  0,  0,  CORNER_SOUTHWEST  I  CORNER_NORTHWEST ,  0,  0, 
CORNER_SOUTHEAST  I  CORNER_SOUTHWEST,  0  1, 

(  0,  CORNER_NORTHEAST  !  CORNER_NORTHWEST ,  0,  0, 

CORNER_NORTHEAST  I  CORNER_SOUTHEAST ,  0,  0,  0  1, 
f  0,  CORNER_NORTHEAST  I  CORNER_NORTHWEST,  0, 

CORNER_SOUTHWEST  \  CORNER_NORTHWEST,  0,  0,  0,  0  ) 

1; 

/*  board  dimensions  */ 
extern  int  Nrows; 
extern  int  Ncols; 

void  Solve  ()  (  /*  route  all  traces  */ 

int  rl,  cl,  r2,  c2,  r,  c,  s,  d,  a,  nr,  nc,  skip; 
register  int  i; 
char  far  *nl; 
char  far  *n2; 

long  curcell,  newcell,  buddy; 
int  newdist,  olddir,  success,  self; 

/*  go  until  no  more  work  to  do  */ 

for  (GetWork(  &rl,  Scl,  &nl,  &r2,  Sc2,  &n2  );  rl  !=  ILLEGAL; 

Get Work (  &rl,  &cl,  ini,  &r2,  &c2,  &n2  ) )  ( 
if  (rl  ==  r2  &&  cl  ==  c2)  /*  already  routed  */ 
continue; 
success  =  0; 

InitQueueO;  /*  initialize  the  search  queue  */ 

/*  get  rough  estimate  of  trace  distance  */ 
a  =  GetApxDist(  rl,  cl,  r2,  c2  ); 

SetQueue(  rl,  cl,  TOP,  0,  a,  r2,  c2  ); 

SetQueue  (  rl,  cl,  BOTTOM,  0,  a,  r2,  c2  ); 

/*  search  until  success  or  we  exhaust  all  possibilities  */ 
for  (GetQueue(  &r,  Sc,  Ss,  Sd,  Sa  );  r  !=  ILLEGAL; 
GetQueue(  Sr,  sc,  Ss,  Sd,  Sa  ) )  { 
if  (r  ==  r2  ss  c  ==  c2)  {  /*  success!  */ 

/*  lay  traces  */ 

Retrace (  rl,  cl,  r2,  c2,  s  ); 

success++; 

break; 

) 

curcell  =  GetCell  (  r,  c,  s  ); 
if  (curcell  S  CORNER_NORTHWEST) 
self  =  1; 

else  if  (curcell  S  CORNER_NORTHEAST ) 
self  =  2; 

else  if  (curcell  S  CORNER_SOUTHWEST) 
self  =  3; 

else  if  (curcell  S  CORNER_SOUTHEAST ) 
self  =  4; 

else 

self  =  0; 

/*  consider  neighbors  */ 
for  (i  =  0;  i  <  8;  i++)  f 

/*  check  self-block  */ 
if  ( ! selfok [self ) ( i ] ) 
continue; 

if  ((nr  =  r+delta ( i ] [0] )  <  0 
! !  nr  >=  Nrows 
!!  (nc  =  c+delta [i]  [1] )  <  0 
! !  nc  >=  Ncols) 

/*  off  the  edge  */ 
continue; 

newcell  =  GetCell (  nr,  nc,  s  ) ; 

/*  check  for  non-target  hole  */ 
if  (newcell  S  HOLE)  { 

if  (nr  !=  r2  ! !  nc  !=  c2) 
continue; 


S  CORNER_NORTHEAST ) 
S  CORNER_SOUTHWEST) 


S  CORNER  SOUTHEAST) 
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newcell  &=  ~(newmask [self ] [i] ) ; 

/*  check  for  traces  */ 
if  (newcell) 

continue; 

) 

/*  check  blocking  on  corner  neighbors  */ 
if  (delta [i] [0]  &&  delta [i] [1] )  { 

/*  check  first  buddy  */ 
buddy  =  GetCell (  r+blocking[i] .rl, 
c+blocking[i] .cl,  s  ); 
if  (buddy  &  HOLE)  { 

if  (buddy  &  (blocking [i] .hi) ) 
continue; 

} 

else  if  (buddy  &  (blocking [i] .bl) ) 
continue; 

/*  check  second  buddy  */ 
buddy  =  GetCell (  r+blocking [i] . r2, 
c+blocking[i] .c2,  s  ); 
if  (buddy  &  HOLE)  ( 

if  (buddy  &  (blocking[i] .h2) ) 
continue; 

} 

else  if  (buddy  &  (blocking [i] . b2 ) ) 
continue; 

} 

olddir  =  GetDir(  r,  c,  s  ); 

newdist  =  d+CalcDist(  ndirfi],  olddir, 

(olddir  ==  FROM_OTHERS I DE ) 

?  GetDir {  r,  c,  1-s  )  :  0  ); 

/*  if  not  visited  yet,  add  it  to  queue  */ 
if  (!GetDir(  nr,  nc,  s  ))  ( 

SetDir(  nr,  nc,  s,  ndir[i]  ); 

SetDist(  nr,  nc,  s,  newdist  ); 
SetQueue(  nr,  nc,  s,  newdist, 

GetApxDist {  nr,  nc,  r2,  c2  ), 
r2,  c2  ) ; 

> 

/*  we  might  have  found  a  better  path  */ 
else  if  (newdist  <  GetDist (  nr,  nc,  s  ))  [ 
SetDir(  nr,  nc,  s,  ndir[i]  ); 

SetDist(  nr,  nc,  s,  newdist  ); 
ReSetQueue(  nr,  nc,  s,  newdist, 

GetApxDist (  nr,  nc,  r2,  c2  ), 
r2,  c2  ); 


/*  consider  other  side  of  board  */ 

/*  check  for  holes  or  traces  on  other  side  * 
if  (newcell  =  GetCell (  r,  c,  1-s  )) 
continue; 
skip  =  0; 

/*  check  for  nearby  holes  */ 
for  (i  =0;  i  <  8;  i++)  ( 

if  ((nr  =  r+delta[i] [0] )  <  0 
1 !  nr  >=  Nrows 
I :  (nc  =  c+delta[i] [1] )  <0 
II  nc  >=  Ncols) 

/*  off  the  edge  */ 
continue; 

if  (GetCell (  nr,  nc,  s  )  &  HOLE)  ( 

/*  neighboring  hole  V 

skip  =  1; 

break; 


if  (skip)  /*  neighboring  hole?  */ 

continue;  /*  yes,  can't  drill  one  here  */ 
olddir  =  GetDir (  r,  c,  s  ); 

newdist  =  d+CalcDist (  FROM_OTHERSIDE,  olddir, 
(olddir  ==  FROM_OTHERSIDE) 

?  GetDir (  r,  c,  1-s  )  :  0  ); 

/*  if  not  visited  yet,  add  it  to  queue  */ 
if  (!GetDir(  r,  c,  1-s  ))  { 

SetDir  (  r,  c,  1-s,  FROM_OTHERSIDE  ); 
SetDist(  r,  c,  1-s,  newdist  ); 

SetQueue(  r,  c,  1-s,  newdist, 
a,  r2,  c2  ); 

1 

/*  we  might  have  found  a  better  path  */ 
else  if  (newdist  <  GetDist (  r,  c,  1-s  ))  ( 

SetDir (  r,  c,  1-s,  FROMOTHERSIDE  ); 
SetDist(  r,  c,  1-s,  newdist  ); 

ReSetQueue(  r,  c,  1-s,  newdist, 
a,  r2,  c2  ) ; 


if  ([success) 

printf (  "\t* ! *  UNSUCCESSFUL  *!*\n"  ); 
/*  clear  direction  flags  */ 
for  (r  =  0;  r  <  Nrows;  r++)  { 

for  (c  =  0;  c  <  Ncols;  C++)  { 

SetDir (  r,  c,  TOP,  EMPTY  ); 
SetDir (  r,  c,  BOTTOM,  EMPTY  ); 


/*  SE  */  (  SHARP_NtoNW,  ANGLE_NWt ONE ,  BENT_EtoNW,  DIAG_SEtoNW, 
BENT_StoNW,  ANGLE_SWtoNW,  SHARP_WtoNW,  0, 

(HOLE  I  HOLE_NORTHWEST)  ), 

/*  S  */  (0,  SHARP_NtoNE,  CORNER_NORTHEAST,  BENT_NtoSE, 

LINE_VERTICAL,  BENT_NtoSW,  CORNER_NORTHWEST,  SHARP_NtoNW, 
(HOLE  I  HOLE_NORTH)  ), 

/*  SW  */  (  SHARP_NtoNE,  0,  SHARP_EtoNE,  ANGLE_NEtoSE,  BENT_StoNE, 
DIAG_NEtoSW,  BENT_WtoNE,  ANGLE_NWtoNE, 

(HOLE  I  HOLE_NORTHEAST)  ), 

/*  W  */  (  CORNER_NORTHEAST ,  SHARP_EtoNE,  0,  SHARP_EtoSE, 

CORNER_SOUTHEAST,  BENT_EtoSW,  L I NE_HORI ZONTAL ,  BENT_EtoNW, 
(HOLE  I  HOLE_EAST)  }, 

/*  NW  */  (  BENT_NtoSE,  ANGLE_NEtoSE,  SHARP_EtoSE,  0,  SHARP_StoSE, 
ANGLE_SEtoSW,  BENT_WtoSE,  DIAG_SEtoNW, 

(HOLE  I  HOLE_SOUTHEAST)  } 

); 

void  Retrace  (  rrl,  ccl,  rr2,  cc2,  s  ) 

/*  work  from  target  back  to  source,  laying  down  the  trace  */ 
int  rrl,  ccl,  rr2,  cc2,  s;  /*  start  on  side  s  */ 

I 

int  rO,  cO,  sO,  rl,  cl,  si,  r2,  c2,  s2; 
register  int  x,  y; 
long  b; 

rl  =  rr2; 
cl  =  cc2; 
si  =  s; 

rO  =  cO  =  sO  =  ILLEGAL; 
do  ( 

/*  find  where  we  came  from  to  get  here  */ 


switch  (x 

=  GetDir (  r2 

=  rl, 

c2  =  cl, 

s2  =  si 

case 

FROM 

NORTH: 

r2++ 

break; 

case 

FROM' 

'EAST: 

c2++; 

break; 

case 

FROM' 

'SOUTH: 

r2— 

break; 

case 

from' 

WEST: 

c2 — ; 

break; 

case 

from" 

NORTHEAST : 

r2++ 

c2++; 

break; 

case 

from' 

SOUTHEAST: 

r2— 

c2++; 

break; 

case 

from" 

SOUTHWEST: 

r2— 

c2 — ; 

break; 

case 

from" 

NORTHWEST: 

r2++ 

c2 — ; 

break; 

case 

FROM_OTHERSIDE : 

s2  = 

l-s2; 

break; 

fprintf(  stderr, 
exit (  -1  ) ; 
break; 


"internal  error\n"  ); 


if  (rO  !=  ILLEGAL) 

y  =  GetDir(  rO,  cO,  sO  ); 

/*  see  if  target  or  hole  */ 
if  ((rl  ==  rr2  &&  cl  ==  cc2)  II  (si  !=  sO ) )  ( 
switch  (x)  ( 
case  FROM_NORTH : 

OrCell (  rl,  cl,  si,  HOLE_NORTH  );  break; 
case  FROM_EAST : 

OrCell (  rl,  cl,  si,  HOLE_EAST  );  break; 
case  FROM_SOUTH : 

OrCell (  rl,  cl,  si,  HOLE_SOUTH  );  break; 
case  FROM_WEST : 

OrCell (  rl,  cl,  si,  HOLE_WEST  );  break; 
case  FROM_NORTHEAST : 

CrCell (  rl,  cl,  si,  HOLE_NORTHEAST  );  br 
case  FROM_SOUTHEAST : 

OrCell (  rl,  cl,  si,  HOLE_SOUTHEAST  );  br 
case  FROM_SOUTHWEST : 

OrCell (  rl,  cl,  si,  HOLE_SOUTHWEST  );  br 
case  FROM_NORTHWEST : 

OrCell (  rl,  cl,  si,  HOLE_NORTHWEST  );  br 
case  FROM_OTHERSIDE : 
default : 

fprintf(  stderr,  "internal  error\n"  ); 

exit (  -1  ) ; 

break; 


if  ((y  ==  FROM_NORTH 

I  1  y  ==  FROM_NORTHEAST 

: :  y  ==  FROM_EAST 

: :  y  ==  FROM_SOUTHEAST 

: :  y  ==  FROM_SOUTH 

: :  y  ==  FROM_SOUTHWEST 

: :  y  ==  FROM_WEST 

: :  y  ==  FROM_NORTHWEST) 

&&  (x  ==  FROM_NORTH 
: :  x  ==  FROM_NORTHEAST 
: :  X  ==  FROM_EAST 
; :  x  ==  FROM_SOUTHEAST 
: :  x  ==  FROM_SOUTH 
: :  x  ==  FROM_SOUTHWEST 
: :  X  ==  FROM_WEST 
: :  X  ==  FROM_NORTHWEST 
: :  x  ==  FROM_OTHERSIDE) 
i&  (b  =  bit (y-1) [x-1] ) )  { 

OrCell (  rl,  cl,  si,  b  ); 
if  (b  &  HOLE) 

OrCell (  r2,  c2,  s2,  HOLE  ); 

} 


/*  this  table  drives  the  retracing  phase  */ 
static  long  bit [ 8 ] [ 9 ]  =  {  /*  OT=Otherside  */ 

/*  N,  NE,  E,  SE,  S,  SW,  W,  NW,  OT  */ 

/*  N  */  {  LINE_VERTICAL,  BENT_StoNE,  CORNER_SOUTHEAST,  SHARP_StoSE, 

0,  SHARP_StoSW,  CORNER_SOUTHWEST,  BENT_StoNW, 

(HOLE  I  HOLE_SOUTH)  ), 

/*  NE  */  {  BENT_NtoSW,  DIAG_NEtoSW,  BENT_EtoSW,  ANGLE_SEtoSW, 
SHARP_StoSW,  0,  SHARP_WtoSW,  ANGLE_S Wt oNW , 

(HOLE  !  HOLE_SOUTHWEST )  ), 

/*  E  */  {  CORNER_NORTHWEST ,  BENT_WtoNE,  LI NE_HORI ZONTAL,  BENT_WtoSE, 

CORNER_SOUTHWEST,  SHARP_WtoSW,  0,  SHARP_WtoNW, 

(HOLE  !  HOLE_WEST)  ), 


fprintf(  stderr, 
exit (  -1  ) ; 


"internal  error\n"  )  ; 


if  (r2  ==  rrl  &&  c2  ==  ccl)  {  /*  see  if  source  */ 
switch  (x)  ( 
case  FROM_NORTH : 

OrCell {  r2,  c2,  s2,  HOLE_SOUTH  );  break; 
case  FROM_EAST : 

OrCell (  r2,  c2,  s2,  HOLE_WEST  );  break; 
case  FROM_SOUTH : 

OrCell (  r2,  c2,  s2,  HOLE  NORTH  );  break; 


OLE_NORTH  ) ;  break; 
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case  FROM  WEST: 


Or Cell (  r2,  c2,  s2,  HOLE  EAST  );  break; 
case  FROM  NORTHEAST: 

OrCell (  r2,  c2,  s2,  HOLE  SOUTHWEST 
case  FROM  SOUTHEAST: 

);  break; 

OrCell (  r2,  c2,  s2,  HOLE  NORTHWEST 
case  FROM  SOUTHWEST: 

) ;  break; 

OrCell {  r2,  c2,  s2,  HOLE  NORTHEAST 
case  FROM  NORTHWEST: 

) ;  break; 

OrCell (  r2,  c2,  s2,  HOLE  SOUTHEAST 
case  FROM_OTHERS IDE : 
default: 

) ;  break; 

fprintf(  stderr,  "internal  error\n"  ); 

exit (  -1  ) ; 

break; 

} 

) 

/*  move  to  next  cell  */ 
rO  =  rl;  cO  -  cl;  sO  =  si; 
rl  =  r2;  cl  =  c2;  si  =  s2; 

}  while  (!(r2  ==  rrl  &&  c2  ccl)); 


int  GetApxDist  (  rl,  cl,  r2,  c2  )  /*  calculate  approximate  distance  */ 
int  rl,  cl,  r2,  c2; 

{ 

register  int  dl,  d2;  /*  row  and  column  deltas  */ 

int  dO;  /*  temporary  variable  for  swapping  dl  and  d2  */ 

/*  NOTE:  the  -25  used  below  is  because  we  are  not  going  */ 

/*  from  the  center  of  (rl,cl)  to  the  center  of  (r2,c2),  */ 

/*  we  are  going  from  the  edge  of  a  hole  at  (rl,cl)  to  */ 

/*  the  edge  of  a  hole  at  (r2,c2).  holes  are  25  mils  in  */ 

/*  diameter  (12.5  mils  in  radius),  so  we  back  off  by  2  */ 

/*  radii.  */ 

if  ( (dl  =  rl-r2)  <  0)  /*  get  absolute  row  delta  */ 
dl  =  -dl; 

if  ( (d2  =  cl-c2)  <  0)  /*  get  absolute  column  delta  */ 
d2  =  -d2; 

if  ( ! dl )  /*  in  same  row?  */ 

return  (  (d2*50)-25  );  /*  50  mils  per  cell  */ 
if  (!d2)  /*  in  same  column?  */ 

return  (  (dl *50) -25  );  /*  50  mils  per  cell  */ 
if  (dl  >  d2)  (  /*  get  smaller  into  dl  */ 
dO  =  dl; 
dl  =  d2; 
d2  =  dO; 

) 

d2  -=  dl;  /*  get  non-diagonal  part  of  approximate  route  */ 
return!  (dl*71) - (d2*50) -25  );  /*  71  mils  diagonally  per  cell  */ 


/*  distance  to  go  through  a  cell  *7 

static  int  dist [10] ( 10 )  =  (  /*  OT=Otherside,  OR=Origin  (source)  cell  */ 


/ 

N, 

NE, 

E, 

SE, 

s, 

SW, 

w, 

NW, 

OT, 

OR  */ 

/* 

N 

*/ 

{ 

50, 

60, 

35, 

60, 

99, 

60, 

35, 

60, 

12, 

12  }, 

/* 

NE 

*/ 

{ 

60, 

71, 

60, 

71, 

60, 

99, 

60, 

71, 

23, 

23  }, 

/* 

E 

*/ 

{ 

35, 

60, 

50, 

60, 

35, 

60, 

99, 

60, 

12, 

12  ), 

/* 

SE 

*/ 

{ 

60, 

71, 

60, 

71, 

60, 

71, 

60, 

99, 

23, 

23  ), 

/* 

S 

*/ 

{ 

99, 

60, 

35, 

60, 

50, 

60, 

35, 

60, 

12, 

12  ), 

/* 

SW 

*/ 

1 

60, 

99, 

60, 

71, 

60, 

71, 

60, 

71, 

23, 

23  ), 

/'* 

w 

*/ 

( 

35, 

60, 

99, 

60, 

35, 

60, 

50, 

60, 

12, 

12  }, 

i* 

NW 

*/ 

( 

60, 

71, 

60, 

99, 

60, 

71, 

60, 

71, 

23, 

23  ], 

1 * 

OT 

*/ 

{ 

12, 

23, 

12, 

23, 

12, 

23, 

12, 

23, 

99, 

99  ), 

/* 

OR 

*/ 

{ 

99, 

99, 

99, 

99, 

99, 

99, 

99, 

99, 

99, 

99  ) 

/* 

distance  around 

(ci 

rcular) 

segment 

of  hole  */ 

static 

int 

circ (10 

[10]  = 

/* 

OT= 

Othe 

rside, 

OR= 

Origin  (source)  cell  */ 

/ 

N, 

NE, 

E, 

SE, 

s. 

SW, 

w, 

NW, 

OT, 

OR  */ 

/* 

N 

*/ 

{ 

39, 

29, 

20, 

10, 

0, 

10, 

20, 

29, 

99, 

0  }, 

/* 

NE 

*/ 

{ 

29, 

39, 

29, 

20, 

10, 

0, 

10, 

20, 

99, 

0  }, 

/* 

E 

*/ 

{ 

20, 

29, 

39, 

29, 

20, 

10, 

o, 

10, 

99, 

0  }, 

/* 

SE 

*/ 

{ 

10, 

20, 

29, 

39, 

29, 

20, 

10, 

o, 

99, 

0  ), 

/* 

S 

*/ 

( 

0, 

10, 

20, 

29, 

39, 

29, 

20, 

10, 

99, 

0  }, 

/* 

SW 

*/ 

{ 

10, 

0, 

10, 

20, 

29, 

39, 

29, 

20, 

99, 

0  ), 

/* 

W 

*/ 

( 

20, 

10, 

0, 

10, 

20, 

29, 

39, 

29, 

99, 

0  ), 

/* 

NW 

*/ 

{ 

29, 

20, 

10, 

0, 

10, 

20, 

29, 

39, 

99, 

0  ), 

/* 

OT 

*/ 

1 

99, 

99, 

99, 

99, 

99, 

99, 

99, 

99, 

99, 

0  >, 

OR 

*/ 

( 

; 

99, 

99, 

99, 

99, 

99, 

99, 

99, 

99, 

99, 

0  ) 

/* 

penalty 

for 

routing 

holes  and  turns 

scaled  by  sharpness  of  turn  */ 

static 

int 

penalty (10] 

10] 

=  { 

/* 

OT=Otherside, 

DR=Origin  (source)  cell 

/ 

N, 

NE, 

E, 

SE, 

s, 

SW, 

w, 

NW, 

OT, 

OR  */ 

/* 

N 

*/ 

{ 

0, 

5, 

10, 

15, 

20, 

15, 

10, 

5, 

50, 

0  }, 

/* 

NE 

V 

1 

5, 

0, 

5, 

10, 

15, 

20, 

15, 

10, 

50, 

0  ), 

/* 

E 

*/ 

( 

10, 

5, 

0, 

5, 

10, 

15, 

20, 

15, 

50, 

0  ), 

/* 

SE 

*/ 

1 

15, 

10, 

5, 

0, 

5, 

10, 

15, 

20, 

50, 

0  ), 

/* 

S 

*/ 

f 

20, 

15, 

10, 

5, 

0, 

5, 

10, 

15, 

50, 

0  }, 

/* 

SW 

*/ 

{ 

15, 

20, 

15, 

10, 

5, 

0, 

5, 

10, 

50, 

0  ), 

/* 

W 

*/ 

{ 

10, 

15, 

20, 

15, 

10, 

5, 

0, 

5, 

50, 

0  1, 

/* 

NW 

*/ 

{ 

5, 

10, 

15, 

20, 

15, 

10, 

5, 

0, 

50, 

0  }, 

/* 

OT 

*/ 

{ 

50, 

50, 

50, 

50, 

50, 

50, 

50, 

50, 

100, 

0  I, 

/* 

OR 

V 

{ 

0, 

0, 

0, 

0, 

0, 

0, 

0, 

0, 

0, 

0  ) 

/* 

**  x  is  the  direction  to  enter  the  cell  of  interest. 

**  y  is  the  direction  to  exit  the  cell  of  interest. 

**  z  is  the  direction  to  really  exit  the  cell,  if  y=FROM_OTHERSIDE . 
**  return  the  distance  of  the  trace  through  the  cell  of  interest. 

**  the  calculation  is  driven  by  the  tables  above. 

*/ 


int  CalcDist  (  x,  y,  z  ) 

/*  calculate  distance  of  a  trace  through  a  cell  */ 
int  x,  y,  z; 

{ 

int  adjust; 

adjust  =  0;  /*  set  if  hole  is  encountered  */ 
if  (x  ==  EMPTY) 
x  =  10; 
if  (y  ==  EMPTY) 

y  =  10; 

else  if  (y  ==  FROM_OTHERSIDE)  { 
if  (z  ==  EMPTY) 
z  =  10; 

adjust  =  circ (x-1 )  [z-1]  +  penalty  [x-1 ] [z-1 ] ; 

) 

return(  dist (x-1 ] [y-1 ]  +  penalty [x-1 ] (y-1 )  +  adjust  ); 
) 


End  Listing 
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SIMULATED  ANNEALING 


Listing  One  (Text  begins  on  page  26.) 

) 

temperature  =  t  ratio*temperature; 

/*  ANNEAL. C  —  Author:  Dr.  Michael  P.  McLaughlin 

) 

*/ 

void  check  equilibrium () 

♦include  <stdio.h> 

/*  Determine  whether  equilibrium  has  been  reached.  */ 

♦include  <math.h> 

( 

if  ( (nsuccesses+nfailures)  >  ultimate  limit) 

♦define  ABS (x)  ( (x<0) ? (- (x) ) :  (x) ) 

equilibrium  =  TRUE; 

♦define  BOOLEAN  int 

else  if  (nsuccesses  >=  succ  min)  { 

♦define  TRUE  1 

if  (incount  >  incount  limit) 

♦define  FALSE  0 

equilibrium  =  TRUE; 

♦define  FORWARD  1 

else  1 

♦define  BACK  0 

if  (outcount  >  outcount  limit)  [ 
if  (nsuccesses  >  first  limit) 

struct  cardtype  { 

equilibrium  =  TRUE; 

char  card [3]; 

else  { 

int  code; 

incount  =  0; 

}  cards [25]; 

outcount  =  0; 

float  ratios [10] [2] ; 

1 

int  tableau [25] , best  tableau [25]; 

) 

float  temperature, best  temperature, t  low,t  min,t  ratio; 

} 

long  seed, score, best  score, tot  successes, tot  failures, scor, exg  cutoff, 

} 

report  time, report  interval, modulus  =  2147483399, step  =  1; 

) 

int  next; 

void  update!) 

BOOLEAN  equilibrium, frozen  =  FALSE, quench=FALSE, final=FALSE; 

/*  Compute  statistics,  etc.  */ 

/*  variables  needed  to  assess  equilibrium  */ 

float  ascore,s; 

float  totscore, totscore2, avg  score, sigma, half  sigma, score  limit; 

if  (nsuccesses  >  0)  ( 

long  bscore, wscore,max  change, nsuccesses, nfailures, scale, 

ascore  =  totscore/nsuccesses; 

incount , outcount ; 

avg  score  =  ascore+scale; 

int  incount  limit, outcount  limit, succ  min, first  limit, ultimate  limit; 

s  =  totscore2/nsuccesses-ascore*ascore; 

if  (s  >  0.0)  ( 

/*  poker  hands  in  tableau  */ 

sigma  =  sqrt(s);  half  sigma  =  0.5*sigma; 

int  hand [12] [5]  =  (0,1,2, 3, 4,  /*  rows  */ 

score  limit  =  avg  score-half  sigma; 

5, 6, 7, 8, 9, 

) 

10,11,12,13,14, 

} 

15,16,17,18,19, 

if  ((temperature  <  t  low) && ( (bscore-wscore)  ==  max  change)) 

20,21,22,23,24, 

frozen  *  TRUE; 

0,5,10,15,20,  /*  columns  */ 

) 

1,6,11,16,21, 

void  selectwr (array, mode, nchoices) 

2,7,12,17,22, 

/*  Select  from  array  without  replacement.  */ 

3,8,13,18,23, 

int  *array, mode, nchoices; 

4,  9,14,19,24, 

{ 

0,6,12,18,24,  /*  diagonals  */ 

int  i,  temp,  size, index; 

4,8, 12,16,20}; 

size  =  mode==l  ?  12  :  25; 

/*  0,4,12,20,24  =  corners  */ 

for  (i=0;i<nchoices;i++)  { 
index  =  uni (size); 

long  randl () 

temp  =  array[ — size]; 

/*  Get  uniform  31-bit  integer  --  Ref.  CACM,  June  1988,  pg.  742  */ 

1 

array[size]  =  array [index] ; 

array [index]  =  temp; 

register  long  k; 

) 

k  =  seed/52774; 

} 

seed  =  40692* (seed-k*52774)-k*3791; 

void  reconfigure (direction) 

if  (seed  <  0) 

/*  If  direction  is  FORWARD,  make  a  new  move;  if  it  is  BACK,  restore 

seed  +=  modulus; 

the  tableau  to  its  previous  configuration.  */ 

return (seed) ; 

int  direction; 

double  uni(z) 

static  long  partition[6]  =  [0,0,715827799,1296031795,1766307855, 

int  z; 

2147483400); 

( 

static  int  hindex[12]  =  (0,1,2,3,4,5,6,7,8,9,10,11); 

return ( (double)  z*randl () /modulus) ; 

static  int  cindex[25]  =  [0,1,2,3,4,5,6,7,8,9,10,11,12,13, 

} 

14, 15,16, 17,18, 19,20,21,22,23,24); 

void  initialize () 

static  int  overlap[66]  =  (-1, -1, -1, -1, -1, -1, -1, -1, -1, -1, 0, 5, 10, 15, 

/*  Set  up  entire  simulated  annealing  run.  */ 

{ 

20,  1,6,11,16,21,-1,2,7,12,17,22,-1,-1,3, 

8,  13, 18, 23, -1,-1, -1,4, 9,  14, 19,  24,-1, -1,-1, 

char  label [20]; 

-1,0,  6,  12,18,24,0,  6,  12,18,  24,4,8,12,  16,  20, 

double  exgc; 

20,16,12,8,4,12); 

register  i; 

static  int  mode, nchoices, common, last;  /*  remember  changes  */ 

FILE  *fp; 

int  temp, hi, lo, i, j,k; 

fp  =  fopen ("a.dat", "r") ; 

if  (direction  ==  FORWARD)  [ 

fscanf (fp, "%f  ls\n", ^temperature, label) ; 

if  (rar.dlO  <  exg  cutoff)  (  /*  giant  step  */ 

fscanf (fp, "%f  ls\n",&t  low, label); 

mode  =  1;  nchoices  =  2; 

fscanf (fp, "If  ls\n",&t  min, label); 

selectwr (hindex, mode, nchoices) ; 

fscanf (fp, "If  %s\n",&avg  score, label) ; 

hi  =  hindex [11];  lo  -  hindex [10];  /*  order  hand  indices  */ 

fscanf (fp, "lid  %s\n", Sscale, label) ; 

if  (hi  <  lo)  ( 

fscanf (fp, "If  ls\n",&t  ratio, label) ; 

hi  *  lo; 

fscanf (fp, "If  ls\n",&sigma, label) ; 

lo  =  hindex [11] ; 

fscanf (fp, "Ilf  ls\n", Sexgc, label) ; 

) 

fscanf (fp, "Id  ls\n",&succ  min, label); 

common  =  overlapjhi* (hi-1) /2+lo] ;  /*  triangular  matrix  */ 

fscanf (fp, "Id  ls\n", sincount  limit, label) ; 

) 

fscanf (fp, "Id  ls\n", Soutcount  limit, label) ; 

else  (  /*  baby  step  */ 

fscanf (fp, "Id  ls\n", &f irst  limit, label) ; 

mode  =  0;  nchoices  =  2; 

fscanf (fp, "Id  ls\n" , ^ultimate  limit, label) ; 

randl ();  /*  How  many  cards  to  rotate?  */ 

fscanf (fp, "lid  ls\n", &report  interval, label) ; 

while  (seed  >  partition [nchoices] ) 

fscanf (fp, "lid  ls\n", &seed, label) ; 

nchoices++; 

half  sigma  =  0.5*sigma;  report  time  =  report  interval; 

selectwr (cindex, mode, nchoices) ; 

score  limit  =  20;  exg  cutoff  =  modulus* exgc; 

temp  =  tableau [cindex [24] ] ;  /*  rotate  forward  */ 

for  (T=0;i<10;i++) 

for  (i=l, j=24;i<nchoices; i++, j — ) 

fscanf (fp, "If  If \n", &  ratios [i] [0] , &  ratios [i] [1] ) ; 

tableau [cindex [ j] ]  =  tableau [cindex [ j-1 ]] ; 

for  (i=0; i<25; i++)  ( 

tableau [cindex [ j] ]  =  temp; 

fscanf (fp, "Id  ls\n",&cards [i] .code, cards [i] .card) ; 

last  =  j; 

tableau(i)  =  cards [i] .code; 

) 

f close (fp) ; 

if  (mode  ==  1)  f  /*  swapping  hands  is  symmetrical  */ 

print f  ("  TOTAL  TOTAL  CURRENT  AVERAGE\n") ; 

register  first, second, c; 

printf ("STEP  TEMPERATURE  SUCCESSES  FAILURES  SCORE  SCORE  "); 

first  =  hindex [11];  second  =  hindex [10]; 

print f  ("  SIGMA\n\n") ; 

k  =  (common<0)  ?  5  :  4; 

1 

for  (c=0, i=0, j=0;c<k;c++, i++, j++)  [ 

void  init() 

if  (hand [first] [i]  ==  common) 

/*  set  up  for  new  temperature  */ 

i++; 

f 

if  (hand[second] [ j]  ==  common) 

nsuccesses  =  0;  nfailures  =  0;  equilibrium  =  FALSE;  incount  =  0; 

j++; 

outcount  =  0;  bscore  =0;  wscore  =  100000;  max  change  =  0; 

temp  =  tableau [handffirst] [i] ] ; 

totscore  =  0;  totscore2  =  0; 

tableau[hand[first] [i] ]  =  tableau (hand [second] [ j] ] ; 

if  (temperature  <  t  min) 

tableau [hand[second] [j] ]  =  temp; 

frozen  =  TRUE; 

} 

void  get  new  temperature () 

1 

} 

if  (temperature  <  ratios [next] [0] )  { 

(continued  on  page  90) 

t_ratio  =  ratios [next] [1]  ; 
next++; 
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Listing  One  (Listing  continued,  text  begins  on  page  26.) 

else  if  (direction  ==  BACK)  {  /*  rotation  is  not  */ 

temp  =  tableau [cindex [last] ] ; 
for  (i=l, j=last;i<nchoices;i++, j++) 

tableau [cindex [j] ]  =  tableau [cindex [ j+1] ] ; 
tableau [cindex [24 ] )  =  temp; 

) 

) 

long  get_score (crds) 

/*  Return  score  of  one  hand.  */ 
int  *crds; 

{ 

static  long  scores[18]  =  [0,1,1,20,1,9,20,1760,1,9,9, 

293,20,293,1760,108,215,27456); 

int  flush,  i,  index  =  0; 

flush  =  crds[0]&crds[l]&crds[2]&crds[3]&crds[4]60xff00; 
for  (i=0;i<5;i++) 

crds[i]  =  crds [i] sOxf f ;  /*  ignore  suits  */ 

{ 

register  b,k,t;  /*  sort  cards  from  high  to  low  */ 
for  (b=4;b>0;b — ) 
for  (k=0;k<b;k++) 

if  (crds[k)  <  crds[k+l])  ( 
t  =  crds [k] ; 
crds[k]  =  crds[k+l); 
crds[k+l)  =  t; 

} 

} 

if  (! flush)  (  /*  multiple  cards  ?  */ 

if  (crds[0]  ==  crds[l])  index  +=  8; 
if  (crdsflj  ==  crds[2])  index  +=  4; 
if  (crds[2]  ==  crds[3])  index  +-  2; 
if  (crds [3]  ==  crds [4])  index  +=  1; 

) 

if  (! index)  (  /*  straight  ?  */ 

if  ( ( (crds  [0) -crds  [4] )  ==*  4)  !  I  { (crds  [0]  ==  14) &&  (crds  [  1 )  —  5))) 
index  *  15; 
if  (flush) 

index  =  (index  ==  15)  ?  17  :  16; 

) 

return (scores [index] ) ; 

) 

long  evaluatelO 

/*  Return  total  score  of  tableau  (no  corners) .  */ 

{ 

int  temp[5],h,c; 
long  scr  =  0; 

for  (h“0;h<12;h++)  {  /*  h<13  for  corners  */ 

for  (c=0;c<5;c++) 

temp[c]  =  tableau [hand(h) [c] ) ; 
scr  +=  get_score (temp) ; 

1 

retu.rn  (scr)  ; 

1 

void  decide () 

/*  Either  accept  new  configuration  or  restore  old  configuration  */ 

{ 

float  pdtl,pdt2,  sscor; 
long  s; 

BOOLEAN  acceptable  =  FALSE; 
scor  =  evaluatel () ; 
if  (scor  >=  score)  ( 

if  (scor  >  best_score)  { 
register  i; 
best_score  =  scor; 
best_temperature  =  temperature; 
for  (i=0;i<25;i++) 

best_tableau [i]  =  tableau [i); 

) 

acceptable  =  TRUE; 

1 

else  if  (temperature  >  0.0)  (  /*  uphill  movement?  */ 

if  (uni(l)  <  exp ( (scor-score) /temperature) )  /*  Equation  2  */ 

acceptable  =  TRUE; 

1 

if  (acceptable)  (  /*  statistics,  etc.  */ 

s  =  ABS (score-scor) ; 
if  (s  >  max_change) 
max_change  =  s; 
score  =  scor; 

sscor  =  scor-scale;  /*  to  aid  precision  of  sigma  */ 
totscore  +=  sscor; 
totscore2  +=  sscor*sscor; 
nsuccesses++; 

if  (ABS (avg_score-score)  <  half_sigma) 
incount++; 
else 

outcount++; 

if  (score  >  bscore)  /*  maximization  */ 
bscore  =  score; 
else  if  (score  <  wscore) 
wscore  =  score; 

) 

else  {  /*  unacceptable  */ 

reconfigure (BACK) ; 
nfailures++; 

) 

I 

void  report () 

{ 

tot_successes  +=  nsuccesses;  tot_failures  +=  nfailures; 
printf("%31d  %10.1f  %91d  %91d  %71d  %7.0f  %5 . lf\n”, step, temperature, 

totsuccesses, tot_failures, score, avg_score, sigma) ; 
report_time  +=  report_interval; 
if  (frozen)  { 

int  temp [25] ,k,kk; 
register  i, j; 

BOOLEAN  ok; 
if  (final) 


listing  One  (Listing  continued,  text  begins  on  page  26.) 

printf ("XnFINAL  —  "); 
else  if  (quench) 

printf ("\nQUENCH  --  "); 
else 

printf ("\nFROZEN  —  "); 

printf ("BEST  SCORE  =  %51d  BEST  TEMPERATURE  =  %5.1f\n\n’\ 
best_score,best_temperature) ; 
for  (i=0; i<25; i++)  ( 
k  =  best_tableau[i) ; 

j  =  0; 

ok  =  FALSE; 
while  (!ok)  ( 

if  (cards[ j] .code  ==  k)  ( 
temp [i]  =  j; 
ok  =  TRUE; 

) 

else  j++; 

) 

) 

for  (i=0;i<25;i+=5)  { 

for  ( j=i; j< (i+5) ; j++)  ( 

k  =  4-strlen (cards [tempi j] ] .card) ; 
for  (kk=0;kk<k;kk++)  printf ("  "); 
printf ("%s", cards [tempi j] ] .card) ; 

} 

printf ("\n") ; 

) 

printf ("\n") ; 

) 

) 

void  try_new_temperature () 

( 

init  () ; 

while  (! equilibrium)  { 
reconfigure (FORWARD) ; 
decide ( ) ; 

check_equilibrium() ; 

} 

update () ; 

if  ( (quench)  {  /*  ratchet  */ 

while  ((float)  score  <  score_limit)  {  /*  maximization  */ 

reconfigure (FORWARD) ; 
decide () ; 

} 

) 

I 

main () 

{ 

initialize () ; 
while  ((frozen)  ( 

try_new_temperature () ; 
update  ()  ; 

if  ((step  ==  report_time) !! (frozen) ) 
report () ; 
step++; 

if  (temperature  >  0.0) 
get_new_temperature () ; 

) 

/*  Quench  frozen  configuration.  */ 
temperature  =  0; 
quench  =  TRUE; 
try_new_temperature () ; 
update ( ) ; 
report () ; 
step++; 

/*  Quench  best  configuration  (rarely  useful) .  */ 

< 

register  i; 
final  =  TRUE; 
for  (i=0;i<25;i++) 

tableau [i]  =  best_tableau(i] ; 

) 

try_new_temperature () ; 
update  () ; 
report ( ) ; 

printf  ("SEED  =  %ld\n", seed) ;  /*  seed  of  next  run  */ 


End  Listing  One 


Listing  Two 

if  ( (nsuccesses+nfailures)  >  ULTIMATE_LIMIT) 
equilibrium  =  true; 
else  if  (nsuccesses  >=  SUCC_MIN)  ( 
if  (incount  >  INCOUNT_LIMIT) 
equilibrium  =  true; 
else  ( 

if  (outcount  >  OUTCOUNT_LIMIT)  ( 
if  (nsuccesses  >  FIRST_LIMIT) 
equilibrium  =  true; 
else  ( 

incount  =  0; 
outcount  =  0; 

) 

) 

} 


End  Listing  Two 
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FORCE-BASED  SIMULATIONS 


Listing  Three 

Listing  One  (Text  begins  on  page  40.) 

2150  temperature 

1.5  t  low 

/* - 

0.1  t  min 

Basic  object  classes  and  method 

40  avg  score 

definitions  for  simulation  software 

4400  scale 

File:  simul.hpp 

0.7  t  ratio 

Todd  King 

150  sigma 

- */ 

0.2  exg  cutoff 

♦include  <stream.hpp> 

200  succ  min 

♦include  <disp.h> 

250  incount  limit 

♦include  <conio.h> 

400  outcount  limit 

♦include  <math.h> 

2700  first  limit 

♦include  <time.h> 

10000  ultimate  limit 

♦include  <math.h> 

1  report  interval 

♦include  "simconst.h" 

1234567890  seed 

360  0.8 

♦define  ESC  27 

215  0.7 

85  0.8 

♦define  MAX_BODY_POOL  100 

60  0.9 

typedef  struct  VECTOR  2D  { 

30  0.95 

15  0.9 

7  0.8 

double  x,  y; 

}; 

3  0.7 

class  BODY  ( 

0  0.7 

VECTOR  2D  world; 

0  0.7 

VECTOR  2D  velocity; 

1032  8H 

double  mass; 

2061  KS 

double  gmass; 

270  AC 

char  icon; 

526  AD 

public: 

522  10D 

BODY  ( )  ; 

1029  5H 

set  mass (double  m) ; 

265  9C 

set  velocity (double  x,  double  y) ; 

1035  JH 

set  position (double  x,  doubie  y) ; 

1037  KH 

apply  force (VECTOR  2D  from,  double  amount); 

525  KD 

VECTOR  2D  position (); 

515  3D 

double  get  gmass (); 

263  7C 

update ( ) ; 

2058  10S 

2062  AS 

set  icon (char  c) ; 

}; 

/*  Distance  and  time  units  are  converted  to  screen  units  and  ticks  */ 

267  JC 

BODY:: set  mass (double  m)  { 

259  3C 

2053  5S 

double  pow ( ) ; 

269  KC 

mass  =  m; 

520  8D 

1028  4H 

gmass  =  G  *  m; 

}; 

1038  AH 

519  7D 

BODY:: set  velocity (double  x,  double  y)  ( 

1026  2H 

velocity. x  =  x; 
velocity. y  =  y; 

End  Listings 

}; 

BODY:: set  position (double  x,  double  y)  ( 

world. x  =  x; 
world. y  =  y; 

); 

BODY::apply  force (VECTOR  2D  from,  double  gmass)  ( 

VECTOR  2D  d; 

double  rs; 

double  v; 
double  r; 

d.x  =  world. x  -  from.x; 
d.y  =  world. y  -  from.y; 

rs  =  (d.x  *  d.x)  +  (d.y  *  d.y); 

if(rs  !=  0.0)  (  //  there's  a  separation 

r  =  sqrt (rs)  ; 

v  =  (gmass  /  rs)  *  SECS  PER  TIC; 

velocity. x  +=  v  *  d.x  /  r; 
velocity. y  +=  v  *  d.y  /  r; 

} 

}; 

BODY : : BODY ( )  { 

world. x  =  0; 
world. y  =  0; 
velocity. x  =  0; 
velocity. y  =  0; 

icon  =  '  ; 

}; 

VECTOR  2D  BODY: :position()  { 

VECTOR_2D  vec; 

vec.x  =  world. x; 
vec.y  =  world. y; 
return (vec) ; 

J; 

double  BODY::get  gmassO  ( 

return (gmass) ; 

) 

BODY:: set  icon (char  c)  (  icon  =  c;  ) 

class  UNIVERSE  { 

unsigned  int  body  cnt; 

BODY  *body_pool [MAX  BODY  POOL); 

public: 

UNIVERSE ( ) ; 
service (BODY  *bptr); 
big  bang () ; 

); 

UNIVERSE : : UNIVERSE ( )  < 

body  cnt  =  0; 

}; 
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UNIVERSE: : service (BODY  *bptr)  { 

if(body_cnt  >=  MAX_BODY_POOL)  return (0); 
body_pool [body_cnt ]  =  bptr; 
body_cnt++; 


UNIVERSE: :big_bang()  { 
int  i,  j; 

init_screer.()  ; 

print_message ("  Press  ESC  to  stop."); 
for {; ; )  { 

print_tick () ; 
if (kbhit () )  { 
switch (getch {) ) 

1 

case  ESC: 
return  (0) ; 

} 

} 

sleep (0.1) ; 

/*  Let  each  body  influence  all  others  */ 
for(i  =  0;  i  <  body_cnt;  i++)  ( 
for(j  =  0;  j'<  body_cnt;  j++)  ( 
if  ( j  ==  i)  continue;  //  don't  apply  force  to  self 
body_pool ( i ) ->apply_f orce (body_pool [ j ) ->position ( ) , 
body_pool ( j ) ->get_gmass ( ) ) ; 

} 

) 

/*  Display  all  bodies  "/ 

for(i  =0;  i  <  body_cnt;  i++)  { 
body_pool ( i ] ->update ( ) ; 

) 

) 

deinit_screen {) ; 


sleep (double  seconds)  ( 
time_t  ltimel,  ltime2; 

time (& ltimel) ; 
time (&ltime2) ; 

while (difftime (ltimel,  ltime2)  <  seconds)  { 
time (&ltime2)  ; 

) 


End  Listing  One 


Listing  Two  (Listing  continued,  text  begins  on  page  40.) 

print_message (char  mesg(])  { 
dispjnove (24,0); 
disp_printf (mesg) ; 


End  Listing  Two 


Listing  Three 

/* - 

Simulation  of  what  would  happen  if  a  planet 
about  twice  the  size  of  the  Moon  passed 
close  to  the  earth  within  the  Moon's  orbit. 

Todd  King 

- */ 

# include  "simul.hpp" 

♦include  "simulscr .hpp" 

main()  1 

BODY  earth; 

BODY  moon; 

BODY  planet_x; 

UNIVERSE  universe; 

earth. set_mass (5.98e24) ; 
earth.set_position(5.0e8,  5.0e8) ; 
earth. set_icon('E' ) ; 
moon.set_mass(7.36e22)  ; 
moon. set_posit ion (5.0e8,  8.8e8) ; 
moon.set_icon('M' ) ; 
moon. set_velocity (-1020.0,  0.0); 
planet_x.set_mass(14.8e22) ; 
planet_x.set_position(1.0,  1.0e4) ; 
planet_x.set_icon (' X' ) ; 
planet_x.set_velocity (1800,  2000) ; 

universe. service (Searth) ; 
universe. service (Smoon) ; 
universe. service (&planet_x) ; 
universe.big_bang() ; 


End  Listing  Three 


Listing  Two 

/* - - 

Methods  which  are  related  to  screen  I/O. 

File:  simulscr. hpp 
Todd  King 

- 

finclude  "simconst .h" 

fdefine  DISPLAY_Y  24 

♦define  DISPLAY_X  80 

BODY: : updated  ( 

extern  VECTOR_2D  Extent; 

VECTOR_2D  screen; 

screen. x  =  DISPLAY_X  *  (world. x  /  EXTENT_X) ; 
screen. y  =  DISPLAY_Y  *  (world. y  /  EXTENT_Y) ; 
iff  (screen. x  <  DISPLAY_X  &&  screen. x  >=  0.0)  && 

(screen. y  <  DISPLAY_Y  &&  screen. y  >=0.0)  )  { 
disp_move (DISPLAY_Y  -  (int)  screen. y,  (int)  screen.x); 
disp_printf ("  "); 

) 


Listing  Four 


/*. 


Various  constants  which  affect  the  simulation 
system.  Units  are  in  meters,  seconds  and  Kilograms. 
File:  simconst. h 
Todd  King 


fdefine  G  -6.67e-ll 

fdefine  SECS_PER_TIC  86400 

fdefine  EXTENT_X  10e8 

fdefine  EXTENT  Y  10e8 


- ./ 

/*  Gravitational  constant  */ 

/*  One  day  */ 

/*  Width  of  displayed  universe 
/*  Hieght  of  displayed  universe 


/ 

*/ 


world. x  +=  velocity. x  *  SECS_PER_TIC; 
world. y  +=  velocity. y  *  SECS_PER_TIC; 

screen.x  =  DISPLAY_X  *  (world. x  /  EXTENT_X) ; 
screen. y  =  DISPLAY_Y  *  (world. y  /  EXTENT_Y) ; 
iff  (screen.x  <  DIS?LAY_X  &&  screen.x  >=  0.0) 

(screen. y  <  DISPLAY_Y  &&  screen. y  >=0.0)  )  { 
disp_mcve (DISPLAY_Y  -  (int)  screen. y,  (int)  screen.x); 
disp_printf ("%c",  icon) ; 

1 

disp_move (0,0); 

)? 

init_screen ()  { 
disp_open () ; 
disp_move(0,  0); 
disp_eeop() ; 


deinit_screen ()  { 
disp_close () ; 

) 


End  Listings 


print_tick()  ( 

static  unsigned  int  Tick  =  0; 

disp_move(0,  0); 

disp_printf ("Tick:  %u",  Tick); 

Tick++; 
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PTREE 


Listing  One  (Text  begins  on  page  44.) 

/*  SPARRAY . H  -  Header  file  for  SPARRAY.C  */ 

/*  Copyright  (C)  1988,  Mark  C.  Peterson  */ 

♦ifndef  SPARRAY_H 
#define  SPARRAY_H 

union  VARIABLE  ( 
long  Num; 
void  *Ptr; 

}; 


SPARRAY  *MakeSpArray (unsigned  NumElem)  ( 

SPARRAY  ‘Array; 

if (Array  =  calloc(l,  sizeof (SPARRAY) ) )  ( 

Array->Size  =  NumElem; 

if ( ! (Array->SpElem  =  (SPELEM*) calloc (NumElem,  sizeof (SPELEM) )) )  f 
free (Array) ; 

Array  =  (SPARRAY*) 0; 

} 

} 

return (Array) ; 


typedef  struct  _SPELEM  { 

struct  _SPELEM  ‘Higher,  ‘Lower; 
unsigned  long  Loc; 
union  VARIABLE  Element; 

}  SPELEM; 


*  Loc 

*  Higher 

*  Lower 

*  Element 


The  location  of  the  element  within  the  sparse  array. 

A  pointer  to  a  SPELEM  with  a  higher  "Loc"  of  a  lower 
precedence. 

A  pointer  to  a  SPELEM  with  a  lower  "Loc"  of  a  lower 
precedence. 

A  union  VARIABLE  for  storage  of  either  a  "long"  or  "void*" 
element.  "Element"  is  initialize  to  a  NULL  (either  0L  or 
(void*)0)  by  MakeSpArray ()  or  when  an  element  is  removed  by 
RemoveSpElem() . 


typedef  struct  _SPARRAY  ( 

SPELEM  ‘SpElem,  ‘Root,  ‘EmptyElem; 
unsigned  Size,  ElemUsed,  HighestUsed; 
}  SPARRAY; 


*  SpElem 

*  Root 

*  EmptyElem 

*  Size 

*  ElemUsed 

*  HighestUsed 


An  array  of  SPELEM  structures.  The  number  of  SPELEM 
structures  in  the  array  is  stored  in  "Size". 

A  pointer  to  an  SPELEM  structure  that  is  the  root  to  the 
Ptree. 

A  pointer  to  a  chain  of  SPELEM  structures  (along  the 
"Higher"  pointer)  that  has  been  removed  from  the  sparse 
array. 

The  number  of  SPELEM  structures  in  SpElem  array. 

Keeps  track  of  the  number  of  elements  in  the  sparse  array. 
"ElemUsed"  should  be  checked  by  the  programmer  periodically 
to  see  if  the  sparse  array  is  full  (i.e  "ElemUsed"  == 
"Size") . 

Used  by  PlaceElement () .  If  there  are  no  empty  elements 
("EmptyElem"  ==  NULL)  and  "HighestUsed"  ==  "Size"  the 
function  returns  a  NULL. 


*  Note  that  the  only  variable  that  should  be  changed  directly  by  the  * 

*  programmer  is  the  "Element"  member  in  the  SPELEM  structure.  * 


SPARRAY  ‘MakeSpArray (unsigned  NumElem); 

/*  Creates  the  SPARRAY  structure  with  "NumElem"  number  of  elements, 
initializes  all  the  elements  to  zero,  and  returns  a  pointer  to  the 
SPARRAY  structure.  */ 

SPELEM  ‘FindSpElem (SPARRAY  ‘Array,  unsigned  long  Loc); 

/*  Returns  a  pointer  to  the  SPELEM  structure  associated  with  "Loc". 
if  "Loc"  is  not  in  the  sparse  array  the  function  returns  a  NULL.  */ 

SPELEM  ‘PlaceSpElem (SPARRAY  ‘Array,  unsigned  long  Loc); 

/*  Places  the  "Loc"  in  the  Ptree  structure.  Returns  a  NULL  if  the  sparse 
array  is  full. 

WARNING:  This  function  should  only  be  called  if  FindElement ()  returns 
a  NULL.  Attempts  to  place  a  "Loc”  that  is  already  there  will  corrupt 
the  Ptree.  */ 

SPELEM  *SpAr ray (SPARRAY  ‘Array,  unsigned  long  Loc); 

/*  Attempts  to  locate  "Loc"  using  FindElement () .  If  not  found  the  "Loc" 
is  placed  using  PlaceElement () .  Returns  a  NULL  if  "Loc"  is  not  found 
and  the  sparse  array  is  full.  */ 


static  SPELEM  ‘PruneLower (SPELEM  ‘this,  unsigned  long  Loc)  ( 

SPELEM  ‘RetPtr; 

while (this->Lower  &&  (this->Lower->Loc  >  Loc))  this  =  this->Lower; 
if  (RetPtr  =  this->Lower)-  this->Lower  =  PruneHigher  (this->Lower,  Loc); 
return (RetPtr) ; 


static  SPELEM  ‘PruneHigher (SPELEM  ‘this,  unsigned  long  Loc)  { 

SPELEM  ‘RetPtr; 

while (this->Higher  &&  (this->Higher->Loc  <  Loc)) 
this  =  this->Higher; 

if (RetPtr  =  this->Higher)  this->Higher  =  PruneLower (this->Higher,  Loc); 
return (RetPtr) ; 


static  unsigned  ChkPrecGT (unsigned  long  Loc,  unsigned  long  ThisLoc)  { 
unsigned  long  LocPrec,  ThisPrec; 

while (Loc  &&  ThisLoc)  ( 

LocPrec  =  (Loc  -  1)  A  Loc; 

ThisPrec  =  (ThisLoc  -  1)  A  ThisLoc; 

if (LocPrec  !=  ThisPrec)  return (LocPrec  >  ThisPrec); 

Loc  »=  1; 

ThisLoc  »=  1; 

} 

return (Loc  >  ThisLoc); 


SPELEM  ‘PlaceSpElem (SPARRAY  ‘Array,  unsigned  long  Loc)  ( 

SPELEM  “this,  ‘New; 

/*  This  section  sets  up  a  "New"  SPELEM  pointer  */ 
if ( ! Array->EmptyElem)  ( 

if (Array->HighestUsed  <  Array->Size) 

New  =  &Array->SpElem[Array->HighestUsed++) ; 
else  return ( (SPELEM* )0); 

} 

else  ( 

New  =  Array->EmptyElem; 

Array->EmptyElem  =  Array->EmptyElem->Higher; 

} 

Array->ElemUsed++; 

New->Higher  =  New->Lower  =  (SPELEM*) 0; 

New->Loc  =  Loc; 

/*  This  section  places  the  "New"  SPELEM  pointer  into  the  Ptree  */ 
this  =  &Array->Root; 
while (‘this)  ( 

if (ChkPrecGT (Loc,  (‘this) ->Loc) )  ( 
if ( (‘this) ->Loc  >  Loc)  { 

New->Higher  =  ‘this; 

New->Lower  =  PruneLower (‘this,  Loc); 

1 

else  ( 

New->Lower  =  ‘this; 

New->Higher  =  PruneHigher (‘this,  Loc); 

) 

break; 

) 

else  this  =  (*this)->Loc  >  Loc  ?  & (‘this) ->Lower  :  & (‘this) ->Higher; 

} 

‘this  =  New; 
return (‘this) ; 

} 


void  ClrSpAr ray (SPARRAY  ‘Array); 

/*  Removes  all  the  elements  from  the  sparse  array.  */ 


void  RemoveSpElem (SPARRAY  ‘Array,  unsigned  long  Loc)  ( 
SPELEM  ‘Hole,  ‘Higherlnter,  ‘Lowerlnter,  “this; 


void  DeleteSpAr ray  (SPARRAY  “ArrayRef ) ; 

/*  Frees  the  memory  allocated  by  MakeSpArray  and  sets  the  SPARRAY  pointer 
referenced  by  ArrayRef  to  NULL.  */ 

void  RemoveSpElem (SPARRAY  ‘Array,  unsigned  long  Loc) ; 

/*  Removes  "Loc"  from  the  sparse  array.  */ 

#endif 


End  Listing  One 


Listing  Two 

/*  SPARRAY.C  -  Routines  for  maintaining  a  sparse  array  using  a  Ptree  */ 
/*  Copyright  (C)  1988,  Mark  C.  Peterson  */ 

♦include  <stdlib.h> 

♦include  " SPARRAY. H" 

static  SPELEM 

‘PruneLower (SPELEM  ‘this,  unsigned  long  Loc), 

‘PruneHigher (SPELEM  ‘this,  unsigned  long  Loc); 

static  unsigned 

ChkPrecGT (unsigned  long  Loc,  unsigned  long  ThisLoc); 

/*  Check  "Loc"  precedence  greater  than  "ThisLoc"  precedence.  */ 


/*  Find  the  element  to  be  removed  */ 

this  =  &Array->Root; 

while  (‘this  &&  ( (‘this) ->Loc  !=  Loc)) 

this  =  (‘this) ->Loc  >  Loc  ?  & (‘this) ->Lower  :  & (‘this) ->Higher; 
if (Hole  =  ‘this)  ( 

/*  Fill  the  hole  in  the  Ptree  if  the  element  was  found  */ 

Lowerlnter  =  Hole->Lower;  /*  Lower  Interface  Pointer  */ 

Higherlnter  =  Hole->Higher;  /*  Higher  Interface  Pointer  */ 
while (Lowerlnter  &&  Higherlnter)  { 

if (ChkPrecGT (LowerInter->Loc,  HigherInter->Loc) )  | 

‘this  =  Lowerlnter; 

this  =  &LowerInter->Higher; 

Lowerlnter  =  LowerInter->Higher; 

) 

else  ( 

‘this  =  Higherlnter; 
this  =  &HigherInter->Lower; 

Higherlnter  =  HigherInter->Lower; 

} 

} 

if (Lowerlnter)  ‘this  =  Lowerlnter; 
else  ‘this  =  Higherlnter; 

/*  Link  the  unused  spot  into  the  chain  of  empty  elements  along 
the  "Higher"  linkage.  */ 

Hole->Higher  =  Array->EmptyElem; 

Array->EmptyElem  -  Hole;  (continued  OH  page  100) 
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Listing  Two  (Listing  continued,  text  begins  on  page  44.) 

printf  (" — ")  ; 

RecDiagSpArray (this->Lower) ; 

Array->ElemUsed — ;  /*  Update  the  number  of  elements  used  */ 

) 

StrLength  -=  (NumLength  +  2); 

if  (this->Higher)  ( 

printf ("\n%s\n",  String); 

SPELEM  ‘FindSpElem (SPARRAY  ‘Array,  unsigned  long  Loc)  { 

SPELEM  ‘this; 

NumLines++; 

String [StrLength]  =  '\0'; 

printf  ("%s",  String); 

this  =  Array->Root; 

RecDiagSpArray (this->Higher) ; 

else  String[StrLength]  =  ' \0' ; 

this  =  this->Loc  >  Loc  ?  this->Lower  :  this->Higher; 

return (this) ; 

1 

void  DiagSpArray (SPARRAY  ‘Array)  ( 

SPELEM  ‘SpArray (SPARRAY  ‘Array,  unsigned  long  Loc)  { 

SPELEM  ‘Found; 

String[0]  =  '\0'; 

NumLines  =  StrLength  =  0; 

if (Array->Root)  RecDiagSpArray (Array->Root) ; 

Found  =  FindSpElem (Array,  Loc); 

else  printf ("<NULL>") ; 

if ( ! Found) 

* 

Found  =  PlaceSpElem (Array,  Loc); 
return (Found) ; 

void  DumpSpArray (SPELEM  ‘this)  ( 

if (this->Lower)  DumpSpArray (this->Lower) ; 

printf  ("%lu\t",  this->Loc); 

void  ClrSpArray (SPARRAY  ‘Array)  ( 

if (this->Higher)  DumpSpArray (this->Higher) ; 

unsigned  n; 

Array->EmptyElem  =  Array->Root  =  (SPELEM*) 0; 

static  void  RecSumSpAr ray (SPELEM  ‘this)  ( 

for(n  =0;  n  <  Array->Size;  n++) 

Array->SpElem[n] .Element .Num  =  0L; 

Array->HighestUsed  =  Array->ElemUsed  =  0; 

* 

if (NumTrav  >  MaxTrav)  MaxTrav  =  NumTrav; 

TotalTrav  +=  (long) NumTrav; 
if  (this->Lower)  ( 

NumTrav++; 

void  DeleteSpArray (SPARRAY  “ArrayRef)  ( 

SPARRAY  ‘Array; 

RecSumSpArray (this->Lower) ; 

NumTrav — ; 

if (Array  =  ‘ArrayRef)  ( 

if (this->Higher)  ( 

NumTrav++; 

RecSumSpArray (this->Higher) ; 

NumTrav — ; 

} 

) 

free (Array->SpElem) ; 
free (Array) ; 

‘ArrayRef  =  (SPARRAY*) 0; 

1 

End  Listing  Two 

void  SumSpArray (SPARRAY  ’Array)  ( 

MaxTrav  =  NumElem  =  NumTrav  =  0; 

TotalTrav  =  01; 

Listing  Three 

RecSumSpArray (Array->Root)  ; 

1 

/*  DIAGARRA.H  -  Header  file  for  DIAGARRA.C  */ 

/*  Copyright  (C)  1988,  Mark  C.  Peterson  */ 

(fifndef  DIAGARRA  H 

End  Listing  Four 

# define  DIAGARRA_H 

# include  " SPARRAY. H" 

Listing  Five 

extern  unsigned  MaxTrav,  NumElem,  NumLines; 

/*  PTREE. C  -  Program  for  constructing  and  diagraming  a  Ptree  */ 

extern  unsigned  long  TotalTrav; 

*  MaxTrav  -  Maximum  number  of  traversals  from  the  root  to  any  * 

/*  Copyright  (C)  1988,  Mark  C.  Peterson  */ 

((include  <stdio.h> 

*  number  in  the  Ptree,  set  by  SumSpArray () . 

tinclude  <stdlib.h> 

*  NumElem  -  Number  of  elements  in  the  Ptree,  set  by  SumSpArray () .  * 

tinclude  "SPARRAY. H" 

*  NumLines  -  Number  of  lines  printed,  set  by  DiagSpArray () . 

tinclude  "DIAGARRA.H" 

*  TotalTrav  -  Total  number  of  linkages  in  the  Ptree,  set  by  * 

*  SumSpArray () .  * 

tdefine  INPUT  SIZE  15 

***********************************/ 

tdefine  ARRAY_SIZE  100 

void  DiagSpArray (SPARRAY  ‘this); 

char  ‘InputNum (char  ‘Input,  unsigned  size)  f 

/*  Diagram  the  Ptree  used  by  the  SPARRAY  */ 

static  char  PromptStr[]  =  "\n\nNumber?  "; 

void  DumpSpAr ray (SPELEM  ‘this); 

printf (PromptStr) ; 

/*  Dump  an  ordered  listing  of  the  elements  of  the  SPARRAY  */ 

return (fgets (Input,  size,  stdin) ) ; 

void  SumSpArray (SPARRAY  ‘Array); 

/*  Determine  various  statistics  about  the  Ptree  used  by  the  SPARRAY  */ 

void  main (void)  ( 

char  Input [INPUT  SIZE]; 

#endif 

SPARRAY  ’Array; 

unsigned  long  Number; 

if (Array  =  MakeSpArray (ARRAY  SIZE))  ( 

puts ("Enter  a  number  at  the  prompt.  If  it  is  not  in  the"); 

puts  ("Ptree  it  will  be  added.  If  the  number  is  in  the"); 

puts ("Ptree  it  will  be  deleted.  To  end  the  program  enter  a"); 

End  Listing  Three 

puts  ("blank  line.W); 

while (*InputNum(Input,  INPUT  SIZE  -  1)  !=  ' \n' )  ( 

Listing  Four 

putchar ( ' \n' ) ; 

Number  =  atol (Input); 

/*  DIAGARRA.C  -  Routines  for  diagraming  the  Ptree  of  a  SPARRAY  */ 

if (FindSpElem (Array,  Numbei))  RemoveSpElem (Array,  Number); 

/*  Copyright  (C)  1988,  Mark  C.  Peterson  */ 

if ( !PlaceSpElem(Array,  Number))  ( 

tinclude  <string.h> 

puts ("Array  Full"); 

break; 

((include  <stdlib.h> 

tinclude  <stdio.h> 

tinclude  "DIAGARRA.H" 

DiagSpArray (Array) ; 

static  char  String [8000] ; 

DeleteSpArray (SArray) ; 

unsigned  MaxTrav,  NumElem,  NumTrav,  StrLength,  NumLines; 

unsigned  long  TotalTrav; 

else  puts ("Error  making  SpArray"); 

static  void  RecDiagSpArray (SPELEM  ‘this)  ( 

unsigned  NumLength; 

NumLength  =  printf ( "%ld",  this->Loc) ; 

if (this->Higher)  strcat  (String,  "I  "); 

else  strcat (String,  "  "); 

StrLength  +=  2; 

memset (String  +  StrLength,  '  ',  NumLength); 

StrLength  +=  NumLength; 

String [StrLength]  =  '\0'; 
if (this->Lower)  { 

End  Listings 

100 
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Listing  One  (Text  begins  on  page  52.) 


This  program  demonstrates  the  use  of  a  mini-interpreter  to  produce 
code  that  is  compact,  flexible  and  easy  to  modify.  The  mini¬ 
program  draws  and  labels  a  maze  and  animates  an  arrow  through 
the  maze. 

Note:  This  program  must  be  run  in  80-column  text  mode. 

1  Tested  with  TASM  1.0  and  MASM  5.0. 

By  Dan  Illowsky  &  Michael  Abrash  2/18/89 
Public  Domain 


.•allocate  stack  space 


:ak  segment  para  stack  'stack' 

db  200h  dup  (?) 

:ak  ends 

rEXT  segment  para  public  'code' 
assume  cs:_TEXT,  ds:_TEXT 

Overall  animation  delay.  Selected  for  an  AT:  set  higher  to  slow 
animation  more  for  faster  computers,  lower  to  slow  animation  less 
for  slower  computers. 


DELAY  COUNT 


equ 


30000 


Equates  for  mini-language  commands,  used  in  the  data 
sequences  that  define  mini-programs.  The  values  of  these 
equates  are  used  by  Interp  as  indexes  into  the  jump  table 
Function_Table  in  order  to  call  the  corresponding  subroutines. 

Lines  starting  with  "»"  describe  the  parameters  that  must 
follow  the  various  commands. 


Done  equ 
SubProg  equ 


Ends  program  or  subprogram. 

»No  parms. 

Executes  a  subprogram. 

»Parm  is  offset  of  subprogram. 

Sets  the  cursor  location  (the  location  at 
which  to  output  the  next  character) . 

»Parms  are  X  then  Y  coordinates  (both 
bytes) . 

Sets  the  distance  to  move  after  displaying 
each  character. 

»Parms  are  X  then  Y  amount  to  move  after 
displaying  character  (both  bytes) . 

Sets  the  X  part  of  the  cursor  location. 
»Parm  is  the  X  coordinate  (byte) . 

Sets  the  Y  part  of  the  cursor  location. 
>>Parm  is  the  Y  coordinate  (byte) . 

Sets  the  X  part  of  the  amount  to  move  after 
displaying  each  character. 

>>Parm  is  the  X  amount  to  move  after 
character  is  displayed  (byte) . 

Sets  the  Y  part  of  the  amount  to  move  after 
displaying  each  character. 

»Parm  is  the  Y  amount  to  move  after 
character  is  displayed  (byte) . 

Sets  the  screen  attribute  of  characters  to 
be  displayed. 

»Parm  is  attribute  (byte)  . 

Displays  a  string  on  the  screen. 

»Parm  is  an  ASCII  string  of  bytes, 
which  must  be  terminated  by  an  EndO  byte. 
Displays  a  single  character  on  the  screen 
a  number  of  times. 

>>Parms  are  char  to  be  displayed  followed 
by  byte  count  of  times  to  output  byte. 
Clears  screen  and  makes  text  cursor 
invisible. 

>>No  parms. 

Sets  location  of  maze  start. 

»Parms  are  X  then  Y  coords  (both  bytes)  . 
Draws  maze  wall  upwards. 

»Parm  is  byte  length  to  draw  in  characters. 
Draws  maze  wall  right. 

»Parm  is  byte  length  to  draw  in  characters. 
Draws  maze  wall  downwards. 

»Parm  is  byte  length  to  draw  in  characters. 
Draws  maze  wall  left. 

»Parm  is  byte  length  to  draw  in  characters. 
Sets  arrow  starting  location. 

»Parms  are  X  then  Y  coordinates 
(both  bytes) . 

Animates  arrow  going  up. 

»No  parms . 

Animates  arrow  going  right. 

>>No  parms . 

Animates  arrow  going  down. 

»No  parms. 

Animates  arrow  going  left. 

»No  parms. 

Repeats  the  command  that  follows 
a  specified  number  of  times. 

»Parm  is  repetition  count  (one  byte)  . 

)  ;used  to  indicate  the  end  of  a 

;  string  of  text  in  a  TextUp 
/  command . 


The  sequences  of  bytes  and  words  between  this  line  and  the  next 
line  of  stars  are  the  entire  mini-program  that  our  interpreter  will 
execute.  This  mini-program  will  initialize  the  screen,  put  text  on 
the  screen,  draw  a  maze,  and  animate  an  arrow  through  the  maze. 

DemoScreen$  label  byte  /this  is  the  main  mini-program  that  our 
;  interpreter  will  execute 

/  Initialize  the  screen 
db  SubProg 
dw  InitScreen$ 

;  Put  up  words 

db  SetXY,0,0,  SetXYInc, 0, 1,  TextUp, ' START' ,  EndO 
db  SetXY, 79,20,  TextUp, ' END' , EndO 
/  Draw  the  maze 

db  SetMstart, 4, 0,  Mrt,8,  Mdn,4,  Mrt,4,  Mup,3,  Mrt,4,  Mdn,3 
db  Mrt,4,  Mdn,8,  Mrt,3,  Mup, 3,  Mrt,5,  Mup, 9,  Mrt,17,  Mdn, 9 
db  Mrt,5,  Mdn, 3,  Mrt,4,  Mup, 10,  Mrt,12,  Mdn,  18,  Mrt,6 
db  SetXY, 4, 2,  Mrt,4,  Mdn, 2,  Mlt,4,  Mdn, 18,  Mrt,12,  Mup, 4 
db  Mrt,4,  Mdn, 4,  Mrt,ll,  Mup, 11,  Mrt,5,  Mup,  9,  Mrt,9,  Mdn, 9 


SetXY 

equ 

2 

SetXYInc 

equ 

3 

SetX 

equ 

4 

SetY 

equ 

5 

SetXInc 

equ 

6 

SetYInc 

equ 

7 

SetAtt 

equ 

8 

TextUp 

equ 

9 

RepChar 

equ 

10 

Cls 

equ 

11 

SetMStart 

equ 

12 

Mup 

equ 

13 

Mrt 

equ 

14 

Mdn 

equ 

15 

Mlt 

equ 

16 

SetAStart 

equ 

17 

Aup 

equ 

18 

Art 

equ 

19 

Adn 

equ 

20 

Alt 

equ 

21 

DoRep 

equ 

22 

db  Mrt,5,  Mdn, 11,  Mrt,12,  Mup, 4 
db  SetXY, 8, 6,  SubProg 
dw  Box4x6$ 

SubProg 


Mrt,4,  Mdn, 4,  Mrt,10 


db  SetXY, 8, 14, 
dw  Box4x6$ 
db  SetXY, 2 4, 14,  SubProg 
dw  Box4x6$ 

db  SetXY, 54, 14,  SubProg 
dw  Box4x6$ 

db  SetXY, 62, 4,  SubProg 
dw  Box4x6$ 

db  SetXY, 16, 6,  SubProg 
dw  Box4x4$ 

db  SetXY, 16, 12,  SubProg 
dw  Box4x4$ 

db  SetXY, 62, 12,  SubProg 
dw  Box4x4$ 

;  Animate  the  arrow  through  the  maze. 

db  SetAStart, 3, 0,  Alt, 2,  Adn,2,  Art, 2,  Aup,2 
db  SetXY, 0,0 
db  DoRep, 5, SubProg 
dw  SpinAround? 

db  Alt, 2,  Adn,l,  Art, 9,  Adn,4,  Alt, 4,  Adn,8,  Art, 8,  Adn,8 
dbAlt,8,  Aup,8,  Art, 8,  Aup,2,  Art, 8,  Adn,2,  Art, 7,  Aup, 3 
dbArt,5,  Aup, 9,  Art, 13,  Adn,9,  Art, 5,  Adn,ll,  Art, 8,  Aup, 10 
db  Art, 8,  Aup, 8,  Alt, 8,  Adn,8,  Art, 8,  Adn,10,  Art, 8,  Adn, 1 
db  Art, 2,  Aup, 2,  DoRep, 5, SubProg 
dw  SpinAroundS 
db  Alt, 2,  Adn,l,  Art,l 
db  Done 

/  Subprogram  to  clear  the  screen  and  initialize  drawing  variables. 
InitScreenS  db  SetXY, 0,0,  SetAtt,7,  SetXYInc, 1, 0,  Cls,  Done 
;  Subprograms  to  draw  boxes. 

Box4x4$  db  Mrt,4,  Mdn, 4,  Mlt,4,  Mup, 4,  Mrt,2,  Done 
Box4x6$  db  Mrt,4,  Mdn, 6,  Mlt,4,  Mup, 6,  Mrt,2,  Done 
/  Subprogram  to  spin  the  arrow  around  a  square. 

SpinAroundS  db  Alt, 2,  Adn, 2,  Art, 2,  Aup, 2,  Dene 

;  Data  for  outputting  text  characters  to  the  screen. 

Text  Out  Data  label  byte 


Cursor_X_Coordinate 
Cursor_Y_Coordinate 
Cursor_X_Increment 
Cursor_Y_increment 
Character_Att  ribute 
Last  Maze  Direction 


db 

db 

db 

db 

db 

db 


AnimateLastCoordinates  dw 


Offh  ;0-up,  1-rt,  2-dn,  3-lt 
;  Of fh-starting 

0  /low  byte  is  X,  high  byte  is  Y 


Jump  table  used  by  Interp  to  call  the  subroutines  associated 
with  the  various  function  numbers  equated  above.  The  functions 
called  through  this  jump  table  constitute  the  mini-language 
used  in  this  program. 

/list  of  function  addresses 
/  which  correspond  one  for 
/  one  with  the  commands  defined 
/  with  EQU  above 

/Set!,  MOut!,  and  Animate%  all  use 
;  the  function  number  to  determine 
/  which  byte  to  set  or  which 
/  direction  is  called  for 


i  Table 

label  word 

dw 

Done% 

dw 

SubProg% 

dw 

SetXY! 

dw 

SetXYInc! 

dw 

Set% 

dw 

Set! 

dw 

Set! 

dw 

Set! 

dw 

Set! 

dw 

TextUp% 

dw 

RepChar% 

dw 

Cls! 

dw 

SetMStart! 

dw 

MOut% 

dw 

MOut! 

dw 

MOut% 

dw 

MOut! 

dw 

SetAStart! 

dw 

Animate! 

dw 

Animate! 

dw 

Animate! 

dw 

Animate! 

dw 

DoRep! 

Program  start  point. 


Start  proc 
push 
pop 
mov 
call 

int 

mov 

int 

sub 

int 

mov 

int 

Start  endp 


cs  /code  and  data  segments  are  the 

ds  z  same  for  this  program 

si, offset  DemoScreen$  /point  to  mini-program 


Interp 
ah,  1 
21h 
ah,  15 
lOh 
ah,  ah 
lOh 

ah, 4ch 
21h 


execute  it 
wait  for  a  key  before  clearing  the 
the  screen  and  ending 
get  the  current  screen  mode 
so  it  can  be  set  to  force 
the  screen  to  clear  and  the 
cursor  to  reset 

/end  the  program 


Mini-interpreter  main  loop  and  dispatcher.  Gets  the  next 
command  and  calls  the  associated  function. 


Interp  proc  near 
cld 

GetNextCommand : 
lodsb 
mov 
xor 
shl 
call 


bl,  al 
bh,  bh 
bx,  1 

[bx+Function_Table] 
jmp  short  GetNextCommand 


/get  the  next  command 

convert  to  a  word  in  BX 
*2  for  word  lookup 
call  the  corresponding 
function 

do  the  next  command 


The  remainder  of  the  listing  consists  of  functions  that 
implement  the  commands  supported  by  the  mini-interpreter . 

Ends  execution  of  mini-program  and  returns  to  code  that 
called  Interp. 
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pop 

ret 


; don't  return  to  Interp 

;done  interpreting  mini-program  or  subprogram 
;  so  return  to  code  that  called  Interp 


Executes  a  subprogram. 

SubProg% : 

lodsw 

push  si 

mov  si, ax 

call  Interp 

pop  si 

ret 


;get  the  address  of  the  subprogram 
;save  pointer  to  where  to 
/  resume  the  present  program 
.•address  of  subprogram 
;call  interpreter  recursively 
z  to  execute  the  subprogram 
; restore  pointer  and  resume 
;  the  program 


Sets  the  screen  coordinates  at  which  text  will  be  drawn. 
SetXY% : 

lodsw 

mov  word  ptr  [Cursor_X_Coordinate] , ax 


Sets  the  amount  by  which  the  cursor  will  move  after  each 
character  is  output  to  the  screen. 


SetXYInc% : 

lodsw 

mov 

ret 


word  ptr  [Cursor_X_Increment] ,ax 


Sets  individual  X  coordinate,  Y  coordinate,  X  movement  after 
character  is  output  to  the  screen,  Y  movement,  or  character 
attribute  depending  on  function  number. 


shr  bx,l  .-calculate  the  command  number 

lodsb  ;  get  the  new  value 

mov  [bx+Text_Out_Data-SetX] ,al  ;store  in  location 
;  corresponding  to 
/  the  command  number 


Displays  a  string  of  text  on  the  screen. 


TextUp% : 

GetNextCharacter : 


lodsb 

/get  next  text  character 

■ 

or 

al,al 

/see  if  end  of  string 

/  Sets  the  animation  start  coordinates 

je 

Return 

/if  so,  next  command 

/ 

call 

OutputCharacter 

/else  output  character 

SetAStart% : 

jmp 

short  GetNextCharacter  /next  character 

lodsw 

/get  both  X  S  Y 

mov 

[AnimateLastCoordinates] , ax  /  coordinates  and 

/  Displays  a 

single  character  on 

the  screen  multiple  times. 

ret 

/  store 

RepChar% : 

/  Repeats  the 

command  that  follows  the 

count  parameter  count  times. 

lodsw 

/get  the  character  in  AL 

/  and  the  count  in  AH 

DoRep% : 

RepCharLoop: 

lodsb 

/get  count  parameter 

push 

ax 

/save  the  character  and  count 

NextRep: 

call 

OutputCharacter 

/output  it  once 

push 

si 

/save  pointer  to  command 

pop 

ax 

/restore  count  and  character 

/  to  repeat 

dec 

ah 

/decrement  count 

push 

ax 

/save  count 

jne 

RepCharLoop 

/jump  if  count  not  now  0 

lodsb 

/get  command  to  repeat 

ret 

mov 

bl,  al 

/convert  command  byte  to 

xor 

bh,  bh 

/  word  index  in  BX 

Clears  the  screen  and  turns  off 

the  cursor. 

shl 

bx,  1 

/ 

call 

[ bx+Funct ion_Table ] 

/execute  command  once 

Cls% : 

pop 

ax 

/get  back  the  count 

mov 

ax, 600h 

/BIOS  clear  screen  parameters 

dec 

al 

/see  if  it's  time  to  stop 

mov 

bh, (Character  Attribute] 

je 

DoneWithRep 

/jump  if  done  all  repetitions 

xor 

cx,  cx 

pop 

si 

/get  back  the  pointer  to  the 

mov 

dx, 184fh 

/  command  to  repeat,  and 

int 

lOh 

/clear  the  screen 

jmp 

NextRep 

/  do  it  again 

mov 

ah,  01 

/turn  off  cursor 

DoneWithRep: 

mov 

cx, 2000h 

/  by  setting  bit  5  of  the 

pop 

ax 

/clear  pointer  to  command  to 

int 

lOh 

/  cursor  start  parameter 

/  repeat  from  stack,  leave 

ret 

/  SI  pointing  to  the  next 

/  command 

Sets  the  start  coordinates  for 

maze-drawing. 

ret 

js 

OutputFirstCharacter 

/look  up  corner  character 

shl 

dl,  1 

/  in  table  using  last 

shl 

dl,  1 

z  direct ion *4  +  new  direction 

add 

bl,dl 

/  as  index 

mov  al, [bx+FirstCharGivenNewAndOldDirectionTable] 

irstCharacter : 

push 

ax 

/AL  has  corner,  AH  side  char 

call 

OutputCharacter 

/put  out  corner  character 

pop 

lodsb 

ax 

/restore  side  char  to  AH 
/get  count  of  chars  for  this 

dec 

al 

/  side,  minus  1  for  corner 

xchg 

al,  ah 

/  already  output 

jmp  short  RepCharLoop 

/put  out  side  char  n  times 

Table  of  arrow  characters  pointing  in  four  directions. 
limateCharacterTable  db  24,26,25,27 
Animates  an  arrow  moving  in  one  of  four  directions. 


Animated : 

sub 

mov 

mov 

lodsb 

shr 

mov 

xchg 

NextPosition: 

mov 


mov 

push 

mov 

call 

pop 

push 

mov 

mov 

call 

mov 

WaitSome: 

loop 

pop 


bx, (Aup+Aup)  ;get  word  dir  index 

ax, word  ptr  [XYIncTable+bx]  ;set  move  direction 
word  ptr  [Cursor_X_Increment] , ax 

;get  move  count 

bx,  1 

ah, [bx+AnimateCharacterTable] 
al,ah 


dx, [AnimateLastCoordinates) 


/make  into  byte 
;  index  and  get 
;  char  to  animate 
;  into  AL,  AH  count 
/coords  of  last  arrow 
/move  cursor  to  where  last 
;  character  was  output 
word  ptr  [Cursor_X_Coordinate] , dx 
ax  /save  char  and  count 

al,20h  /output  a  space  there 

OutputCharacter  /  to  erase  it 

ax  /restore  char  in  AL,  count  in  AH 

ax  /save  char  and  count 

dx.word  ptr  [Cursor_X_Coordinate]  /store  new  coords 


dec 

jne 

ret 


[AnimateLastCoordinates] ,  dx 

OutputCharacter 

cx, DELAY  COUNT 


ah 

NextPosition 


as  last 
/output  in  new 
/  location  then 
/  wait  so  doesn't 
/  move  too  fast 
/restore  count  and 
/  character 
/count  down 
/  if  not  done 
do  again 


SetMStart? : 

lodsw 

mov 

mov 

ret 


/get  both  X  and  Y  coordinates  and  store 
word  ptr  [Cursor_X_coordinate] ,  ax 
[Last_Maze_Direction] ,0ffh  /indicate  no 

/  last  direction 


Maze-drawing  tables. 

XYincTable  db  0,-1,  1,0,  0,1,  -1,0 

/X  &  Y  increment  pairs  for  the  4  directions 
CharacterGivenDirectionTable  db  179,196,179,196 

/vertical  or  horizontal  line  character  to  use 
Z  for  a  given  direction 

FirstCharGivenNewAndOldDirectionTable  label  byte 

db  179,218,179,191,  217,196,191,196  /table  of  corner 

db  179,192,179,217,  192,196,218,196  /  characters 

Outputs  a  maze  line  to  the  screen. 


sub  bx,Mup+Mup  /find  new  direction  word  index 
mov  ax, word  ptr  [bx+XYincTable]  /set  for  new 

mov  word  ptr  [Cursor_X_Increment] ,  ax  /  direction 

shr  bx, 1  /change  to  byte  index  from  word  index 
mov  al, [bx+CharacterGivenDirectionTable]  /get  char  for 

/  this  direction 

mov  ah,al  /move  horizontal  or  vert 

mov  dl, [Last_Maze_Direction]  /  character  into  AH 

mov  [Last_Maze_Direction] ,bl  /if  last  dir  is  Offh  then 

or  dl,dl  /  just  use  horiz  or  vert  char 


Interp  endp 

Outputs  a  text  character  at  the  present  cursor  coordinates, 
then  advances  the  cursor  coordinates  according  to  the 
X  and  Y  increments. 

OutputCharacter  proc  near 

push  ax  /save  the  character  to  output 

mov  ah, 2  /set  the  cursor  position 

mov  dx.word  ptr  [Cursor_X_Coordinate] 

xor  bx.bx  /page  0 

int  lOh  /use  BIOS  to  set  cursor  position 

pop  ax  /restore  character  to  be  output 

mov  ah, 9  /write  character  BIOS  function 

mov  bl, [Character_Attribute]  /set  attribute 
mov  cx, 1  /write  just  one  character 

int  lOh  /use  BIOS  to  output  character 

/advance  X  &  Y  coordinates 

mov  ax, word  ptr  [Cursor_X_Coordinate]  /both  x  S  y  Incs 

add  al, [Cursor_X_Increment]  /  can  be  negative 

add  ah,  [Curscr_Y_Incrementj  /  so  must  add  bytes 

/  separately 

mov  word  ptr  [Cursor_X_Coordinate] , ax  /store  new 


coordinates 


ret 

OutputCharacter  endp 


ends 

end 


/start  execution  at  Start 


End  Listing 
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Listing  One  ( Text  begins  on  page  64.) 

/*  386. H  -  structures  etc.  for  the  80386  */ 

/*  By  Tom  Green  */ 

/*  all  of  these  structures  are  processor  dependant,  so  »/ 

/*  you  must  set  code  generation  for  byte  alignment  */ 

/*  generic  descriptor  -  data,  code,  system,  TSS  */ 

typedef  struct  descriptor! 
unsigned  int  limit_lo; 
unsigned  int  base_lo; 
unsigned  char  basejnid; 
unsigned  char  type_dpl; 
unsigned  char  limit_hi; 
unsigned  char  base_hi; 

}descriptor; 

/*  call,  task,  interrupt,  trap  gate  */ 


#include  <stdio.h> 
♦include  <dos.h> 
♦include  <conio.h> 
♦include  <stdlib.h> 
♦include  "386. h" 


/*  selectors  for  entries  in  our  GDT  */ 


♦define  CODE  SELECTOR 

0x08 

♦define  DATA  SELECTOR 

0x10 

♦define  TASK  1  SELECTOR 

0x18 

♦define  TASK  2  SELECTOR 

0x20 

♦define  MAIN  TASK  SELECTOR 

0x28 

♦define  VID  MEM  SELECTOR 

0x30 

/*  physical  address  of  video  ram,  mono  and  color 

♦define  COLOR  VID  MEM 

0xb8000L 

♦define  MONO  VID  MEM 

OxbOOOOL 

/*  video  modes  returned  by 

BIOS  call  */ 

♦define  MONO  MODE 

0x07 

♦define  BW  80  MODE 

0x02 

♦define  COLOR  80  MODE 

0x03 

typedef  struct  gatef 

unsigned  int  offset_lo; 
unsigned  int  selector; 
unsigned  char  count; 
unsigned  char  type_dpl; 
unsigned  int  offset_hi; 

I  gate; 

/*  this  is  the  layout  for  a  task  state  segment  (TSS)  */ 

/*  the  fill  fields  of  structures  are  not  used  by  the  80385  */ 
/*  but  must  be  there  */ 


typedef  struct  tss( 

unsigned  int  back  link; 
unsigned  int  fill!; 
unsigned  long  espO; 
unsigned  int  ssO; 
unsigned  int  f i 1 1 2 ; 
unsigned  long  espl; 
unsigned  int  ssl; 
unsigned  int  f i 1 1 3 ; 
unsigned  long  esp2; 
unsigned  int  ss2; 
unsigned  int  f i 1 1 4 ; 
unsigned  long  cr3; 
unsigned  long  eip; 
unsigned  long  eflags; 
unsigned  long  eax; 
unsigned  long  ecx; 
unsigned  long  edx; 
unsigned  long  ebx; 
unsigned  long  esp; 
unsigned  long  ebp; 
unsigned  long  esi; 
unsigned  long  edi; 
unsigned  int  es; 
unsigned  int  fill5; 
unsigned  int  cs; 
unsigned  int  f i 1 1 6 ; 
unsigned  int  ss; 
unsigned  int  f i 1 1 7 ; 
unsigned  int  ds; 
unsigned  int  f i 1 1 8 ; 
unsigned  int  fs; 
unsigned  int  f i 1 1 9 ; 
unsigned  int  gs; 
unsigned  int  filla; 
unsigned  int  ldt; 
unsigned  int  fillb; 
unsigned  int  tbit; 


/*  selector  for  last  task  */ 


/*  stack  pointer  privilege  level  0  */ 
/*  stack  segment  privilege  level  0  */ 


/*  stack  pointer  privilege  level  1  */ 
/*  stack  segment  privilege  level  1  */ 


/*  stack  pointer  privilege  level  2  */ 
/*  stack  segment  privilege  level  2  */ 


/*  control  register  3,  pace  table  */ 
/*  instruction  pointer  */ 


uns: 

Lgned  int  iomap; 

}tss; 

♦define 

TSS  SIZE 

(sizeof (tss) ) 

♦define 

DESCRIPTOR  SIZE 

(sizeof (descriptor) ) 

♦define 

GATE  SIZE 

(sizeof (gate) ) 

♦define 

DPL(x) 

(x«5) 

♦define 

TYPE  CODE  DESCR 

0x18 

♦define 

TYPE  DATA  DESCR 

0x10 

♦define 

TYPE  TSS  DESCR 

0x09 

♦define 

TYPE  CALL  GATE 

0x0c 

♦define 

TYPE  TASK  GATE 

0x05 

♦define 

TYPE  INTERRUPT  GATE 

OxOe 

♦define 

TYPE  TRAP  GATE 

OxOf 

♦define 

SEG  WRITABLE 

0x02 

♦define 

SEG  READABLE 

0x02 

♦define 

SEG  EXPAND  DOWN 

0x04 

♦define 

SEG  CONFORMING 

0x04 

♦define 

SEG  ACCESSED 

0x01 

♦define 

SEG  TASK  BUSY  BIT 

0x02 

♦define 

SEG  PRESENT  BIT 

0x80 

♦define 

SEG  GRANULARITY  BIT 

0x80 

♦define 

SEG  DEFAULT  BIT 

0x40 

♦define 

SELECTOR  MASK 

Oxf f f 8 

/*  exception  on  task  switch  bit  */ 


End  Listing  One 


Listing  Two 


/*  TASK.C  -  this  code  creates  and  sets  up  the  Global  Descriptor  */ 
/*  Table  and  Task  State  Segments.  The  code  switches  tc  protected  */ 
/*  mode,  runs  tasks,  and  returns  to  real  mode.  */ 
/*  Compile  with  Turbo  C  2.0  */ 
/*  By  Tom  Green  */ 


/*  pointer  to  a  function  */ 
typedef  void  (func_ptr) (void) ; 

/*  extern  stuff  in  mode. asm  */ 

void  protectedjnode (unsigned  long  gdt_ptr, unsigned  int  cseg, unsigned  int 
dseg) ; 

unsigned  int  load_task_register (unsigned  int  tss_selector) ; 

void  real_mode (unsigned  int  dseg); 

void  jump_to_task (unsigned  int  tss_selector) ; 


/*  prototypes  for  local  functions  */ 
void  taskl (void); 
void  task2 (void) ; 

void  init_tss(tss  *t, unsigned  int  cs, unsigned  int  ds, unsigned  char  *sp, 
func_ptr  ip); 

void  init_gdt_descriptor (descriptor  *descr, unsigned  long  base, unsigned  long 
limit, unsigned  char  type); 
void  print (unsigned  int  x, unsigned  int  y,char  *s) ; 
void  vid_mem_putchar (unsigned  int  x, unsigned  int  y,char  c) ; 

/*  this  array  of  descriptors  will  be  our  Global  Descriptor  Table  */ 
descriptor  gdt [ 10 J ; 

/*  these  are  the  TSS's  for  our  tasks  */ 
tss  main_tss; 
tss  task_l_tss; 
tss  task_2~tss; 

/*  seperate  stacks  for  each  task  */ 
unsigned  char  task_l_stack ( 1024 ] ; 
unsigned  char  task_2_stack [1024] ; 


/*  global  y  location  for  protected  mode  screen  writes  */ 

/*  using  descriptor  for  video  ram  */ 
unsigned  int  y=0; 

void  main (void) 

I 

unsigned  long  base; 
unsigned  char  type; 
union  REGS  r; 

/*  setup  code  and  data  descriptors  in  GDT  */ 

/*  code  GDT  entry  l  */ 

/*  turn  code  segment  into  20  (and  32)  bit  physical  base  address  */ 
base=  ( (unsigned  long)_CS)«4; 

/*  set  descriptor  type  for  a  readable  code  segment  */ 
type=TYPE_CODE_DESCR  !  SEG_PRESENT_BIT  !  SEG_READABLE; 
init_gdt_descriptor (&gdt [ 1 ] ,  base,  Oxf f f fL, type)  ; 

/*  data  GDT  entry  2  */ 

/*  turn  data  segment  into  20  (and  32)  bit  physical  base  address  */ 
base=  ( (unsigned  long)_DS)«4; 

/*  set  descriptor  type  for  a  writeable  data  segment  */ 
type=TYPE_DATA_DESCR  I  SEG_PRESENT_BIT  !  SEG_WRITABLE; 
init_gdt_descriptor (&gdt (2) , base, Oxf f ffL, type) ; 

/*  set  up  TSS's  for  tasks  here  */ 

/*  set  descriptor  type  for  a  TSS  */ 
type=TYPE_TSS_DESCR  :  SEC-_PRESENT_BIT; 

/*  put  a  descriptor  for  each  TSS  in  the  GDT  */ 

/*  TSS  GDT  entry  3,  TSS  for  taskl  */ 

/*  turn  segment :offset  of  taskl  TSS  into  physical  base  address  */ 
base= (( (unsigned  long)_DS) «4) + (unsigned  int) &task_l_tss; 
init_gdt_descriptor (&gdt [3] ,base, (unsigned  long) TSS_SIZE-1, type) ; 

/*  TSS  GDT  entry  4,  TSS  for  task2  */ 

/*  turn  segment : offset  of  task2  TSS  into  physical  base  address  */ 
base= (( (unsigned  long)_DS) «4) + (unsigned  int) &task_2_tss; 
init_gdt_descriptor (&gdt [4 ] , base,  (unsigned  long) TSS_SIZE-1 , type) ; 

/*  TSS  GDT  entry  5,  TSS  for  main  starting  task  */ 

/*  turn  segment : offset  of  main  TSS  into  physical  base  address  */ 
base= (( (unsigned  long)_DS) <<4) + (unsigned  int) &main_tss; 
init_gdt_descriptor (&gdt [5] ,base, (unsigned  long) TSS_SIZE-1, type) ; 

/*  init  the  TSS  with  starting  values  for  each  task  */ 

(continued  on  page  110) 
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80386  PROTECTED  MODE 


Listing  Two  (Listing  continued,  text  begins  on  page  64.) 


/*  task  1  */ 

init_tss (4task_l_tss, CODE_SELECTOR,  DATA_SELECTOR,  task_l_stack+ 
sizeof (task_l_stack)  , taskl) ; 

/*  task  2  */ 

init_tss (4task_2_tss, CODE_SELECTOR, DATA_SELECTOR, task_2_stack+ 
sizeof (task_2_stack) , task2) ; 

/*  video  ram  descriptor  GDT  entry  6  */ 

/*  set  descriptor  for  a  writeable  data  segment  */ 
type=TYPE_DATA_DESCR  !  SEG_PRESENT_BIT  !  SEG_WRITABLE; 
r.h.ah=15;  /*  get  video  mode  BIOS  */ 

int86 (0x10, 4r,  4r) ; 

/*  check  if  mono  mode  */ 
i f  ( r . h . al==MONO_MODE ) 

init_gdt_descriptor (Sgdt [6] ,MONO_VID_MEM, 3999,  type) ; 

/*  check  if  color  mode  */ 

else  if (r.h.al==BW_80_MODE  II  r .h.al==COLOR_80_MODE) 

init_gdt_descriptor (Sgdt (6) ,COLOR_VID_MEM,  3999, type) ; 
else{ 

printf ( "\nThis  video  mode  is  not  supported."); 
exit  (1) ; 

) 

/*  we  are  now  ready  to  enter  protected  mode  */ 
clrscr () ; 

cprintf ("\nPress  return  to  enter  protected  mode."); 
getchar () ; 

/*  turn  segment : offset  of  GDT  into  20  bit  physical  address  */ 
base= ({ (unsigned  long) _DS) «4) + (unsigned  int)sgdt; 

/*  this  puts  us  in  protected  mode  */ 
protected_mode (base, CODE_SELECTOR, DATA_S ELECTOR) ; 

/*  this  loads  the  task  register  for  the  first  task  */ 
load_task_register ( MA I N_TAS  K_SELECTOR ) ; 

y=3;  /*  this  is  line  we  will  start  printing  on  in  protected  mode  */ 

/*  using  our  descriptor  to  write  to  video  ram  */ 

print (0, y++, "Entered  protected  mode  in  main  task"); 

/*  this  jumps  to  first  task  (which  will  jump  back  here  eventually)  */ 
jump_to_task ( TAS  K_1 _SE  LECTOR ) ; 

print (0, y++, "Returned  to  main  task,  leaving  protected  mode"); 

/*  return  us  to  real  mode  */ 
real_mode (DATA_SELECTOR) ; 


gotoxy  (1,22); 

cprintf ("Returned  to  real  mode.  Press  return  to  exit  to  DOS"); 
getchar  () ; 
clrscr () ; 


/*  code  for  task  1  */ 

void  taskl (void) 

{ 

while (1) ( 

print (0, y++, "Hello  from  taskl"); 
jump_to_task { TASK_2_S  ELECTOR ) ; 

/*  return  to  original  task  (in  mainO)  after  several  task  switches  */ 
if (y>18) 

jump_to_task ( MAI N_TASK_SELECTOR ) ; 

1 

) 

/*  code  for  task  2  */ 

void  task2 (void) 

{ 

while  (1) ( 

print (0,y++, "Hello  from  task2"); 
jump_to_task (TASK_l_SELECTOR) ; 

) 


/*  this  initializes  a  TSS  */ 

/*  inits  segment  registers,  eip,  and  stack  stuff  to  starting  values  */ 

void  init_tss(tss  *t, unsigned  int  cs, unsigned  int  ds, unsigned  char  *sp, 
func_ptr  ip) 

{ 

t->cs*cs;  /*  code  selector  */ 

t->ds=ds;  /*  set  these  to  the  data  selector  */ 

t->es=ds; 

t->ss=ds; 

t->fs=ds; 

t->gs=ds; 

t->eip= (unsigned  int) ip;  /*  address  of  first  instruction  to  execute  */ 
t->esp= (unsigned  int)sp;  /*  offset  of  stack  in  data  */ 
t->ebp= (unsigned  int)sp; 

} 

/*  this  initializes  a  descriptor  in  the  Global  Decsriptor  Table  */ 

/*  sets  up  the  base,  limit,  type,  and  granularity  */ 

void  init_gdt_descriptor (descriptor  *descr, unsigned  long  base, unsigned  long 
limit, unsigned  char  type) 


80386  PROTECTED  MODE 


Listing  Two  ( Listing  continued,  text  begins  on  page  64.)  Listing  Three 


descr->base_lo= (unsigned  int) base; 
descr->base_mid= (unsigned  char) (base  »  16); 
descr->type_dpl=type ; 

/*  if  limit  >  OxfffffL  then  we  have  to  set  granularity  bit  and  shift  */ 
if (limit  >  OxfffffL) ( 
limit  =  limit  »  12; 

descr->limit_hi= ( (unsigned  char) (limit  »  16)  4  OxOf)  ! 
SEG_GRANULARITY  BIT; 

) 

else 

descr->limit_hi= ( (unsigned  char) (limit  »  16)  4  OxOf); 
descr->limit_lo= (unsigned  int) limit; 
descr->base_hi= (unsigned  char) (base  »  24); 


MODE. ASM 

Routines  for  switching  to  protected  and  real  mode.  Also  includes 
routines  for  loading  task  register  and  jumping  to  a  task. 
Assemble  with  Turbo  TASM  1.0 
By  Tom  Green 


/*  this  routine  prints  a  string  using  vid_mem_putchar  */ 
void  print (unsigned  int  x, unsigned  int  y,char  *s) 


while  (*s) 

vid_mem_putchar (x++,y, *s++) ; 


/*  this  routine  writes  a  character  directly  to  video  ram  */ 

/*  uses  the  selector  for  the  descriptor  we  set  up  in  main  */ 

/*  for  video  ram  */ 

void  vid_mem_putchar (unsigned  int  x,  unsigned  int  y,char  c) 

( 

register  unsigned  int  offset; 
char  far  *vid_ptr; 

offset=  (y* 1 60)  +  (x*2); 

/*  make  our  far  pointer  use  our  special  video  ram  descriptor  */ 
/*  yes,  we  can  even  use  far  pointers  with  selectors  */ 
vid_ptr=MK_FP (VID_MEM_SELECTOR, offset) ; 

*vid_ptr++=c;  /*  write  character  */ 

*vid_ptr=0x07;  /*  write  attribute  byte  */ 


;this  is  where  we  stuff  address  of  GDT  that  is  passed 
gdtptr  LABEL  PWORD 

dw  50h  ;size  in  bytes  of  GDT,  enough  for  10  entries 

dd  ?  ;this  is  where  we  will  put  physical  address  of  GDT 

;this  is  where  we  will  store  the  address  of  a  task  (the  selector)  that 
;we  will  jump  to  in  jump_to_task 
new_task  LABEL  DWORD 

dw  OOh 

new_select  LABEL  WORD 

dw  OOh 

;this  is  where  we  store  address  to  jump  to  when  we  enter  protected  mode 
;in  protected_mode 
.•offset  of  code  where  we  will  jump 

p_mode  LABEL  DWORD 

dw  OFFSET  protect 

;put  selector  of  protected  mode  code  segment  here 
p_mode_select  LABEL  WORD 

dw  0 


PUBLIC  _real_mode,_protected_mode,_jump_to_task 
PUBLIC  _load_task_register 


End  Listing  Two 
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;  void  protected_mode (unsigned  long  gdt_ptr, unsigned  int  cseg, 

;  unsigned  int  dseg)  -  puts  386  in  protected  mode  and  loads  segment 
;  registers  with  code  and  data  selectors  passed  (cs  and  ds 
;  parameters) .  pass  this  routine  a  32  bit  physical  address  of  the 
;  Global  Descriptor  Table  (gdt_ptr  parameter) .  Turns  interrupts 
;  off  while  we  run  in  protected  mode. 
;************************************************„***********„**** 
_protected_mode  PROC  NEAR 
push  bp 


bp,  sp 
ax, [bp+4] 
dx, [bp+6] 

WORD  PTR  gdtptr+4, dx 
WORD  PTR  gdtptr+2,ax 
ax, [bp+8] 
dx, [bp+10] 
p_mode_select , ax 
eax,  0 


PWORD  PTR  gdtptr 
eax, crO 
eax,  1 
crO,eax 

DWORD  PTR  p_mode 


;get  low  word  of  address  of  GDT 
;get  high  word  of  address  of  GDT 
; store  high  word  of  address  of  GDT 
; store  low  word  of  address  of  GDT 
;get  selector  for  code  descriptor 
;get  selector  for  data  descriptor 
;put  code  selector  in  our  jmp  pointer 
;prepare  to  zero  out  eflags 

;zero  out  eflags 

;load  gdt  register  with  limit  and  ptr 


;turn  protected  mode  on 

;this  will  jump  to  protect  through  ptr 

; (cs  will  be  loaded  with  code  selec- 


_real_mode  PROC  NEAR 
push  bp 

mov  bp,  sp 

mov  ax, [bp+4] 

mov  ds,ax 


eax, crO 

eax, 07f f f f f feh 

crO,eax 

FAR  PTR  flush 


ax, DGROUP 
ds,  ax 
ss,  ax 


get  selector  for  data  segment 
now  make  sure  all  segment  registers 
contain  selector  to  64k  segment 
must  have  this  to  return  to  real  mode 


; protected  mode  off 

; flush  queue  and  set  cs  for  real  mode 
;now  cs  will  be  loaded  with  correct 
/segment  for  real  mode 

/restore  data  seg  registers  for  real  mode 


/interrupts  back  on  for  real  mode 


tor) 

protect: 

/we  are  now  running  in  protected  mode,  and  we  will  load  segment  registers 
/with  selectors  that  look  like  our  code  is  still  in  real  mode 

mov  ss,dx  /load  segment  registers  with  data  selector 

mov  ds , dx 

mov  es,dx 

mov  fs,dx 

mov  gs,dx 

mov  ax, 0 

lldt  ax  /make  sure  ldt  register  has  0 

pop  bp 

ret 

_protected_mode  ENDP 


real  mode  ENDP 


void  jump_to_task (unsigned  int  tss_selector)  - 

jumps  to  386  TSS  task,  pass  this  routine  the  selector  of  the 

TSS  of  the  task  you  want  to  jump  to. 


_jump_to_task 

push 


3mP 

pop 

ret 

_jump_to_task 


PROC  NEAR 
bp 

bp.  sp 

ax, [bp+4]  /get  selector  of  new  task 

new_select,ax  /store  it  in  pointer 

DWORD  PTR  new_task  /jump  to  task  through  selector : offset  ptr 
bp 


End  Listings 


void  load_task_register (unsigned  int  tss_selector) 
loads  task  register  with  TSS  selector 


_load_task_register  PROC 
push  bp 

mov  bp, sp 

ltr  [bp+4] 

pop  bp 

ret 

_load_task_register  ENDP 


/load  task  register  with  selector  for  current  task 


void  real_mode (unsigned  int  dseg)  - 

returns  386  to  real  mode,  pass  this  routine  the  selector  for 
a  64k  data  segment  so  we  can  return  to  real  mode,  this 
routine  assumes  we  are  executing  from  a  64k  data  segment. 
(80386  segment  registers  must  have  selector  of  segment  with 
64k  limit  to  return  to  real  mode) 
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In  a  short  story  by  Nikolay  Gogol, 
an  officer  misplaces  his  nose,  which 
is  subsequently  spotted  here  and 
there  about  Petersburg,  masquerad¬ 
ing  as  an  officer  of  higher  rank.  While 
the  officer  is  trying  to  place  an  adver¬ 
tisement  offering  a  reward  for  his  nose’s 
return,  the  press  official  solicitously  but 
injudiciously  offers  him  snuff.  Insulted, 
the  officer  retorts  that  he  is  missing 
precisely  what  is  required  to  appreci¬ 
ate  snuff,  and  besides  he  would  never 
use  that  cheap  brand. 

The  point  is  .  .  .  but  first  I  think  I 
need  to  backtrack  a  bit. 

Slow  Leorner 

Hal  Hardenbergh  called  to  clarify  a  point 
in  the  interview  with  him  that  was  pub¬ 
lished  in  the  June  issue.  In  that  inter¬ 
view,  I  left  the  speed  issue  ambiguous: 
It’s  not  the  execution  speed  of  trained 
neural  nets,  but  the  convergence  of  the 
learning  algorithm,  that  is  slow.  One 
other  correspondent  knowledgeable  in 
neural  net  techniques  also  caught  the 
slip. 

In  Hardenbergh’s  words,  “While  it’s 
true  that  multi-level,  perceptron-based 
artificial  neural  networks  are  extremely 
slow,  this  is  only  true  for  the  training 
phase.  When  you  actually  run  them, 
they  are  much  faster.  This  is  even  true 
for  toy  problems.  I  have  been  playing 
with  neural  nets  on  my  three  Atari  STs 


Michael  Swaine 


and  have  achieved  speedups  from  train¬ 
ing  to  practice  of  one  million  to  one.” 

Tom  Waite,  who  is  working  on  neu¬ 
ral  nets  with  Hardenbergh  at  Vicom  in 
San  Jose,  Calif.,  pointed  out  that  the 
performance  of  the  system  as  it  learns 
is  dramatic.  Unlike  adaptive  filters, 
which  just  get  better  as  they  learn,  neu¬ 
ral  nets  do  a  flip-flop  to  which  it  is  hard 
not  to  attach  anthropomorphic  labels. 


You  see  the  system  spontaneously  “gets 
the  idea,”  and  develops  “insight”  into 
the  problem.  “It  will  be  stuck  in  a  rut 
and  all  of  a  sudden  go  wild  and  drop 
into  the  right  answer,”  Waite  said. 

But  that  insight  may  take  a  while. 

Slow  or  not,  multi-level,  perceptron- 
based  artificial  neural  networks  con¬ 
verge  to  solutions  more  rapidly  than 
some  competitors.  Hardenbergh  said, 
“the  Boltzmann  machine  training 
method  is  generally  regarded  as  more 
robust  than  multi-level  perceptrons,  but 
it  is  also  considered  to  be  two  orders 
of  magnitude  slower  than  back  propa¬ 
gation,  so  it’s  not  used  for  practical 
work.”  Anderson  and  Rosenfeld,  in  their 
massive  and  important  book  Neuro¬ 
computing, ,  say  “[Backprop]  is  .  .  .  the 
most  popular  learning  algorithm  for 
working  with  multi-layer  networks.  It 
is  considerably  faster  than  the  other 
learning  algorithm  that  is  successful  with 
multi-layer  networks,  the  Boltzmann 
machine.” 

So,  if  your  response  to  the  interview 
was  that  you  were  missing  precisely 
what  was  required  to  appreciate  the 
stuff  (algorithms,  code,  hands-on  ex¬ 
amples),  and  besides  you  would  never 
use  such  a  slow  technique,  I  hope  I 
have  corrected  the  impression  I  gave 
about  the  speed  of  neural  nets.  As  for 
the  algorithms,  code,  and  hands-on  ex¬ 
amples,  that  will  have  to  wait  until  I 
can  devote  a  full  column  to  it,  because 
a  backprop  algorithm  doesn’t  make  any 
sense  without  a  fairly  complete  descrip¬ 
tion  of  the  network  to  which  it  is  ap¬ 
plied.  At  the  end  of  this  column,  though, 
are  references  to  a  book  and  an  article 
where  backprop  is  well  exemplified. 

The  Explosive  Market  for  Neural  Nets 

Hardenbergh  also  brought  up  to  date 
a  reference  in  that  article  to  a  possible 
development  in  the  commercial  neural 
nets  market. “At  the  time  of  the  publica¬ 
tion  of  your  interview  with  me  there 


were  no  commercial  applications  of 
multi-level  artificial  neural  nets.  Since 
then  SAIC  has  signed  a  multimillion 
dollar  contract  to  provide  explosives 
detectors  to  airports. 

“The  way  their  device  works  is  that 
the  explosives  are  subjected  to  bom¬ 
bardment  from  a  gamma  ray  source 
and  the  molecules  making  up  the  ex¬ 
plosive  substance  have  characteristic 
signatures  under  gamma  rays.  This  re¬ 
sults  in  a  diffraction  pattern  that  identi¬ 
fies  the  explosive.  And  SAIC  uses  a 
multi-level,  perceptron-based  artificial 
neural  network  to  detect  the  character¬ 
istic  patterns. 

“I  call  a  one-hundred-million-dollar 
contract  real  activity.”  So  do  we,  Hal. 

Closing  the  Circle 

The  management  at  Vicom  is  suppor¬ 
tive  of  Waite  and  Hardenbergh’s  neural 
net  explorations  because  Vicom  is  in 
the  image  processing  business,  and  the 
applications  of  neural  nets  to  image 
processing  are  evident.  But  there  are 
many  powerful  techniques  already  de¬ 
veloped  for  processing  images,  dating 
back  at  least  to  Fourier’s  development, 
in  1807,  of  the  Fourier  transform,  which 
has  had  applications  Fourier  could  not 
have  imagined,  such  as  transforming  medi¬ 
cal  diagnosis  by  way  of  the  CAT  scan. 

Waite  and  Hardenbergh  see  neural 
nets  as  needing  to  fit  in  with  existing, 
more  conventional  algorithms,  so  they 
find  themselves  regularly  thinking  in 
different  paradigms.  Lately,  Harden¬ 
bergh  has  been  treading  the  well-trod 
path  of  efficient  algorithms  for  circle 
drawing. 

“The  past  three  weekends  I’ve  been 
playing  with  plotting  curves.  Back  when 
I  was  [working  on  another  project]  I 
plotted  curves  and  pulled  out  three 
curve-plotting  algorithms,  all  in  fact  from 
DDJ.  When  I  looked  at  them  recently, 
I  found  to  my  surprise  that  all  of  them 
used  multiplication  for  each  point.  Then 
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I  came  across  Bresenham’s  algorithm.” 

In  fact,  DDJ published  an  implemen¬ 
tation  and  discussion  of  Bresenham’s 
algorithm  in  September,  1987.  It  was 
by  Jim  Blinn,  a  graphics  expert  at  JPL. 
I  used  Blinn’s  version  of  Bresenham’s 
algorithm  in  my  book  on  HyperTalk, 
to  show  beginning  HyperTalk  program¬ 
mers  three  ways  to  draw  a  circle,  but 
of  course  drawing  circles  in  an  inter¬ 
preted  language  doesn’t  tell  you  a  whole 
lot  about  algorithmic  efficiency.  I  was 
interested  in  Hardenbergh’s  take  on 
Bresenham’s  algorithm,  because  1. 
Hardenbergh  is  interested  in  algorithmic 
efficiency  and  usually  has  an  interest¬ 
ing  timing  result  or  two  to  report,  and 
2. 1  knew  how  he  hated  wading  through 
academic  explanations  of  technical  is¬ 
sues.  I  suspected  that,  if  he  hadn’t  seen 
the  Blinn  piece,  he  had  only  seen  aca¬ 
demic  explications,  and  would  have 
impatiently  taken  off  on  his  own,  pos¬ 
sibly  interesting  tangent. 

Sure  enough,  he  told  me,  “The  Bre- 
senham  algorithm  doesn’t  use  multipli¬ 
cation,  but  Bresenham  is  an  academi¬ 
cian  and  so  the  article  I  read  was  full 
of  derivations  and  math.  Normally,  peo¬ 
ple  doing  this  kind  of  work  keep  it  as 
a  trade  secret,  but  Bresenham  is  an 
academic,  trying  to  make  PhD  Brownie 
points,  so  he  just  made  it  obscure. 

“So  I  put  away  the  book  and  set 
about  trying  to  write  a  good  circle¬ 
drawing  algorithm  myself.  Then  I  found 
out  that  Vicom  does  not  know  how  to 


Waite  and 
Hardenbergh  see 
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do  fast  ellipses,  so  I  worked  on  ellip¬ 
ses.  Now  I  have  a  circle  algorithm,  an 
algorithm  that  does  ellipses  oriented 
to  the  axes,  and  also  a  tilted  ellipse 
algorithm,  all  without  multiplies.” 

At  that  point  Hardenbergh  went  back 
to  the  books.  “I  picked  up  the  book  in 
which  I  had  read  the  Bresenham  algo¬ 


rithm  and  found  to  my  surprise  that  I 
had  not  reinvented  Bresenham;  my  al¬ 
gorithm  is  just  not  Bresenham’s.  Mine 
is  simpler.  It  is  ridiculously  simple.  And 
the  ellipse  and  tilted  ellipse  algorithms 
are  just  extensions  of  the  circle  algo¬ 
rithm,  so  I  suspect  that  my  ellipse  algo¬ 
rithms  are  also  different  from  Bresen¬ 
ham’s.  I  tried  to  check  this  but  could 
find  no  book  there  that  contained  the 
Bresenham  algorithm  [for  ellipses].” 

Hal  didn’t  give  me  his  algorithms, 
but  he  did  give  me  a  number  to  test 
against:  one  thousand  radius-100  cir¬ 
cles  drawn  in  5.84  seconds  with  a  0.02 
second  loop  overhead.  The  hardware 
was  an  Atari  ST. 

The  48th  Parallel  Processor 

In  the  Bavarian  countryside  outside  Mu¬ 
nich,  I  met  with  Jurgen  Fey,  almost  ex¬ 
actly  on  the  48th  parallel,  roughly  the 
same  latitude  as  Poltava,  where  the 
young  student  Gogol  was  mercilessly 
teased  for  his  beak-like  nose  a  century 
and  a  half  earlier. 

Jurgen  turned  up  his  nose  when  I 
told  him  that  Hardenbergh  had  criti¬ 
cized  the  Transputer  for  its  lack  of 
registers  (Jurgen  has  developed  a 
Transputer  board).  “It’s  true  that  it’s 
not  a  register  machine.  You  can’t  do 
parallel  processing  on  a  parallel  ma¬ 
chine.  I  challenge  him  to  find  a  register- 
based  machine  that  supports  parallel 
processing.” 

But  Jurgen  did  agree  that  the 
Transputer’s  “native”  language,  occam, 
was  on  its  way  out.  There  are  now,  he 
explained,  several  more  or  less  viable 
alternatives  in  the  works,  including 
“.Lisp,  SC-Prolog,  Parallel  Prolog, 
Modula-2,  C,  C,  C,  C,  C,  and  C,  Ada, 
assembler,  and  Forth.”  Jurgen  is  work¬ 
ing  on  something  compatible  with 
Turbo  Pascal  4.0. 

Antisocial  Behavior  in  the 
Society  of  Mind 

What  has  been  called  “the  Minsky 
smoke  bomb”  continues  to  smell. 

In  The  Structure  of  Scientific  Revolu¬ 
tions,  Thomas  Kuhn  wrote:  "But  para¬ 
digm  debates  are  not  really  about  rela¬ 
tive  problem-solving  ability,  though  for 
good  reasons  they  are  usually  couched 
in  those  terms.  Instead,  the  issue  is 
which  paradigm  should  in  the  future 
guide  research  on  problems  many  of 
which  neither  competitor  can  yet  claim 
to  resolve  completely  .  .  .  that  decision 
must  be  based  less  on  past  achieve¬ 
ment  than  on  future  promise.” 

And  Kuhn  wrote:  .  .  the  defenders 
of  traditional  theory  and  procedure  can 
almost  always  point  to  problems  that 
its  new  rival  has  not  solved  but  that  for 


their  view  are  no  problems  at  all.  .  .  .  if 
a  new  candidate  for  paradigm  had  to 
be  judged  from  the  start  by  hard-headed 
people  who  examined  only  relative  prob¬ 
lem-solving  ability,  the  sciences  would 
experience  very  few  major  revolutions.” 

And:  .  .  The  member  of  a  mature 

scientific  community  is,  like  the  typical 
character  of  Orwell’s  1984,  the  victim 
of  a  history  rewritten  by  the  powers 
that  be.” 

In  Perceptrons,  Marvin  Minsky  and 
Seymour  Papert  presented  an  impecca¬ 
bly  reasoned  argument  showing  cer¬ 
tain  limits  on  the  results  you  could  get 
out  of  any  single-layer  perceptron  net¬ 
work,  along  with  something  quite  dif¬ 
ferent:  An  “intuitive  judgment  that  the 
extension  [to  multi-layer  networks]  is 
sterile.” 

Together,  the  reasoned  argument  and 
the  unsupported  (and  mistaken)  intui¬ 
tive  judgment  undermined  support  for 
this  neural  net  paradigm  that  was  con¬ 
tending  for  AI  research  funding  with 
their  favored  Lisp-based  work  at  MIT. 
In  1969,  Minsky  and  Papert  were  the 
hard-headed  establishment  of  artificial 
intelligence  and  neural  nets  was  the 
new  candidate  paradigm  that  got  writ¬ 
ten  out  of  the  history  of  AI  work  by 
their  efforts.  Two  decades  later,  the 
dramatic  comeback  of  neural  nets  is 
one  of  those  heartening  success  sto¬ 
ries,  like  “Nikolay  Gogol,  the  odd,  beak¬ 
nosed  boy,  had  turned  obscurity  and 
failure  into  triumph,  and  was  well  on 
his  way  to  becoming  one  of  the  most 
famous  authors  in  Russia”  (Dick  Pen- 
ner).  Heartening  once  you  get  to  the 
success  part,  but  discouraging  through 
the  years  of  obscurity  and  failure.  Were 
those  years  unnecessary? 

Some  interesting  public  documents 
recently  came  into  my  possession,  and 
anyone  interested  in  the  history  of  in¬ 
vention  in  this  area  ought  to  take  a 
look  at  them. 

The  problem  that  formed  the  crux 
of  Minsky  and  Papert’s  denunciation 
of  perceptron-based  neural  net  research 
was  linearly  separable  functions;  basi¬ 
cally,  the  exclusive-OR  problem  of  clas¬ 
sifying  unlike  objects  into  the  same 
category.  For  example,  given  a  collec¬ 
tion  of  red  and  green  squares  and  cir¬ 
cles,  you  are  to  classify  the  red  squares 
and  green  circles  together  in  one  group, 
and  the  red  circles  and  green  squares 
in  the  other  group.  You  can’t  form  the 
grouping  with  a  straight  line  through 
the  space  whose  dimensions  are  red- 
green  and  circle-square.  But  it’s  a  per¬ 
fectly  logical  grouping,  expressed  by 
the  exclusive-OR  expression  “red  or 
circle  (but  not  both).”  The  first  group 
contains  all  objects  satisfying  the  ex- 
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pression,  the  second  group  all  objects 
not  satisfying  it.  The  expression  per¬ 
fectly  assigns  the  objects  to  the  required 
groups.  Single-layer  perceptrons,  and 

What  has  been 
called  “the  Minsky 
smoke  bomb” 
continues  to 
smell 


thus  neural  nets,  Minsky  and  Papert 
said,  couldn’t  do  that. 

Although  Minsky  and  Papert  clari¬ 
fied  the  full  consequences  of  the  prob¬ 
lem  with  single-layer  perceptrons  in  a 
way  that  had  never  been  done,  this 
basic  problem  had  been  perceived  years 
earlier,  and  many  people  had  given 
thought  to  its  solution. 

At  the  very  least,  the  problem  was 
under  attack.  Here  is  what  one  re¬ 
searcher  wrote  in  1963:  “Two  layers 
were  used  .  .  .  because  one  layer  can 
only  be  trained  successfully  on  linearly 
separable  functions  [Minsky  and  Pa- 
pert’s  point].  .  .  .  Having  two  layers  of 
variable  weights  was  our  initial  inten¬ 
tion,  but  we  do  not  yet  know  of  an 
algorithm  leading  to  a  convergent  train¬ 
ing  process.”  The  writer  went  on  to 
discuss  his  group’s  search  for  such  a 
convergent  algorithm,  as  well  as  practi¬ 
cal  measures  they  had  taken. 

How  close  were  neural  net  research¬ 
ers  to  solving  the  problem?  Had  the 
problem  been  solved,  perhaps  acci¬ 
dentally,  nearly  a  decade  before  Minsky 
and  Papert  published  their  book?  And 
was  Minsky  aware  of  the  solution?  I 
don’t  have  the  answers,  but  the  issue 
is  apparently  more  complex  than  any¬ 
one  has  yet  admitted.  I  refer  you  to  the 
work  on  graphical  data  processing  done 
at  SRI  in  the  early  1960s  (references  are 
at  the  end  of  this  article). 

Recommended  Rending 

Hal  Hardenbergh  has  been  buying  all 
the  books  he  can  find  on  neural  nets. 
He  called  me  to  recommend  strongly 
Neural  Computing:  Theory  and  Prac¬ 
tice,  by  Philip  D.  Wasserman,  Van  Nos¬ 
trand  Rinehart,  1989. 

“I  now  know  enough  about  back 
propagation  to  judge  that  the  chapter 


on  back  propagation  is  good,  so  by 
extension  I  suspect  that  the  rest  is  good. 
I’m  particularly  interested  in  the  chap¬ 
ter  on  stochastic  methods.  I  know  some¬ 
one  who  knows  the  author  and  who 
says  he’s  more  interested  in  the  Cauchy 
machine  than  in  back  propagation.  He 
says  the  training  is  better  with  simu¬ 
lated  annealing.  The  Cauchy  machine 
is  another  stochastic  method  based  on 
the  Boltzmann  machine,  so  I’m  cur¬ 
rently  studying  the  stochastic  chapter 
in  Wasserman’s  book.” 

Hardenbergh  considers  the  Wasser¬ 
man  book  a  good  place  to  start  learn¬ 
ing  about  neural  nets:  The  right  level 
and  the  right  size.  “It’s  not  a  large  book. 
The  problem  is  that  when  you  are  start¬ 
ing  to  get  into  a  new  field  you  need  to 
cover  a  lot  of  ground  so  you  need  a  big 
book  but  you’re  not  really  ready  to 
handle  a  big  book.” 

A  much  more  elementary  but  very 
broad  presentation  of  this  area  can  be 
found  in  Cognizers:  Neural  Networks 
and  Machines  that  Think,  by  R.  Colin 
Johnson  and  Chappell  Brown,  John 
Wiley,  1988.  Light  reading. 

Hardenbergh  and  Waite  have  pub¬ 
lished  their  own  version  of  the  back 
propagation  algorithm  in  the  June  is¬ 
sue  of  Programmer's  Journal. 

The  SRI  work  mentioned  had  to  do 
with  the  development  of  several  pieces 
of  parallel  processing  hardware  (includ¬ 
ing  MINOS  I  and  MINOS  II)  and  both 
theoretical  and  practical  work  on  multi¬ 
level  neural  net  algorithms.  The  work 
is  described  in  several  reports  under 
SRI  project  number  3192.  Quarterly  Re¬ 
ports  4  and  5  are  particularly  interest¬ 
ing,  showing  MINOS  I  doing  exclusive- 
OR  classification.  The  quote  is  from  the 
final  report,  Report  No.  12,  by  A.E.  Brain. 

Many  Russian  writers  have  written 
stories  about  noses.  Gogol’s  The  Nose, 
however,  may  be  the  only  one  in  which 
the  curious  Russian  fascination  with 
noses  has  survived  translation.  It  was 
published  in  The  Diary  of  a  Madman 
and  Other  Stories,  Nikolay  Gogol,  trans¬ 
lated  by  Andrew  R.  MacAndrew,  New 
American  Library  I960;  and  was  re¬ 
printed  in  Fiction  of  the  Absurd:  Prat¬ 
falls  in  the  Void,  edited  by  Dick  Pen- 
ner,  New  American  Library,  1980.  The 
latter  book  contains  several  other  works 
that  offer  insights  into  the  software  de¬ 
velopment  process,  including  a  selec¬ 
tion  from  Catch-22  and  Camus’  essay 
on  software  engineering,  The  Myth  of 
Sisyphus. 

DDJ 
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C  PR0GRAMMIN6 


C++:  Of  Books, 
Compilers,  and  a 
Window  Object 


Last  month  I  looked  at  Bjome  Strous- 
trup’s  The  C++  Programming  Lan¬ 
guage  and  decided  to  find  another 
book  to  be  an  introduction  to  C++. 
The  Stroustrup  book,  which  I  will  here¬ 
after  affectionately  call  BS  (in  the  tradi¬ 
tion  of  K&R),  will  serve  as  a  reference 
once  I  understand  the  C++  language 
better.  But  because  I  still  needed  a  C++ 
tutorial  text,  I  scoured  the  bookstores. 

I  found  a  book  that  I  can  recom¬ 
mend  for  learning  C++  but  only  with 
strict  reservations.  The  book  is  The  Waite 
Group’s  C++  Programming  by  John 
Berry  and  is  for  C  programmers  who 
want  to  learn  C++.  Berry  is  a  good 
writer  and  a  good  teacher.  The  organi¬ 
zation  and  presentation  of  the  material 
is  just  right  for  teaching  the  extensions 
that  C++  brings  to  C. 

The  C++  Programming  Language  is 
not,  however,  for  programmers  who 
do  not  already  know  C.  While  Berry 
writes  effectively  about  C++,  he  does 
not  attempt  to  teach  ancestral  C,  so  if 
you  don’t  already  know  it,  you  aren’t 
going  to  learn  it  here.  That  omission  is 
understandable  and  even  appropriate  — 
there  are  plenty  of  good  texts  on  C 
already.  But  this  book  has  one  unfor¬ 
givable  problem,  one  that  most  pro¬ 
grammers  will  readily  identify  with  and 


Al  Stevens 


some  will  condemn.  The  code  is  replete 
with  errors.  Most  of  the  errors  are  ones 
that  the  C  programmer  will  spot  right 
away.  But  someone  else  might  assume 
that  the  code  works,  might  assume  that 
C  works  that  way,  and  might  actually 
try  to  get  the  examples  to  work,  an 
exercise  that  the  author  himself  should 
have  undertaken  before  going  to  print. 
Some  of  the  programs  in  this  book 


would  not  compile,  much  less  execute. 
Others  are  built  with  conventions  that 
might  work  in  the  limited  contexts  of 
the  examples,  but  that  are  generally 
recognized  by  seasoned  C  programmers 
to  be  undesirable  coding  practices. 

Following  are  examples  of  the  errors 
I  found  in  the  book.  I  am  about  half 
way  through  now  and  can  only  assume 
that  the  second  half  is  no  better  than 
the  first. 

First,  the  author  insists  on  putting 
executable  code  into  header  files.  The 
typical  .h  file  contains  class  definitions 
and  their  member  functions.  Programs 
that  have  several  source  code  files  all 
using  the  same  classes  will  run  into 
link  problems  with  multiply-defined  func¬ 
tions.  C  programmers  long  ago  estab¬ 
lished  a  convention  of  style  where 
header  files  are  for  definitions  and  pro¬ 
totypes  only,  while  all  statements  that 
reserve  or  use  memory  go  into  ,c  files. 
As  a  newcomer  to  C++  I  am  assuming 
that  C++  will  have  the  same  conven¬ 
tion.  If  it  doesn’t,  it  should. 

Next,  there  are  several  programs  in 
the  book  that  use  the  length  of  a  string, 
as  returned  by  strlen,  to  allocate  a  new 
buffer.  Then  strcpy  copies  the  string  to 
the  buffer.  Every  C  programmer  knows 
that  strlen  does  not  count  the  null  ter¬ 
minator  character  but  that  strcpy  cop¬ 
ies  it.  The  examples  might  work,  but 
only  when  nothing  critical  is  on  the 
heap  just  past  the  new  buffer. 

The  book  uses  a  stack  data  structure 
to  illustrate  C++  class  definitions.  The 
stack  functions  do  not  use  the  first  ele¬ 
ment  in  the  stack  array,  but  they  do  use 
the  element  one  past  the  last  one.  Once 
again,  the  example  program  probably 
runs  OK,  but  if  you  use  it  in  a  bigger 
program,  you  are  likely  to  trash  some¬ 
thing  else.  In  at  least  one  other  place 
Berry  uses  a  subscript  of  2  to  address 


the  second  element  of  an  array,  a  tech¬ 
nique  that  does  not  work  in  any  con¬ 
text.  The  example  code  would  not  de¬ 
liver  the  stated  results  at  all.  These  sub¬ 
scripting  errors  are  typical  of  those  made 
by  new  C  programmers,  particularly  pro¬ 
grammers  coming  to  C  from  Basic,  and 
they  are  the  kind  of  errors  that  the  auth¬ 
or  would  have  found  if  he  had  taken 
the  time  to  try  out  some  of  his  code. 

The  give_date  function  allocates  a 
new  buffer  every  time  you  call  it.  Noth¬ 
ing  ever  deletes  the  buffer.  This  error 
occurs  several  places  in  the  book.  Make 
enough  calls  to  give_date  and  the  heap 
(called  the  “free  store”  in  C++)  exhausts. 
BS  defines  a  technique  for  capturing 
such  errors,  but  the  book  ignores  it. 

The  Julian  date  functions  ignore  leap 
years.  I  suppose  that’s  forgivable,  but 
the  book  should  point  it  out.  Some 
unsuspecting  and  trusting  programmer 
might  just  try  to  use  some  of  this  stuff. 

The  nth_token  function  returns  the 
‘\0’  character  when  the  function  is  clear¬ 
ly  defined  to  return  a  character  pointer. 

Finally,  the  discussion  of  function 
overloading  confuses  long  and  int.  The 
examples  of  operator  overloading  use 
strcat  improperly. 

If  you  are  not  already  a  veteran  C 
programmer,  stay  away  from  this  book 
—  it  sets  bad  examples.  If  you  are  one, 
I  can  recommend  it  for  its  textual  con¬ 
tent.  After  recognizing  the  sloppy  code 
and  code  conventions,  I  made  allow¬ 
ances  and  proceeded  to  enjoy  the  work. 
It  does  what  I  wanted  it  to  do.  It  clearly 
explains  the  C++  extensions  in  ways 
that  I  can  understand.  It  is  a  shame  that 
the  code  examples  are  so  bad.  They 
mar  an  otherwise  excellent  book. 

The  book’s  zeal  for  C++  clouds  its 
objectivity.  In  several  places  it  attempts 
to  justify  the  language  and  the  object- 
oriented  extensions  that  it  brings  to  C 
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by  citing  advantages  of  the  new  and 
disadvantages  of  the  old.  And  in  every 
one  of  these  cases  there  are  adjacent 
advantages  in  C  and  adjacent  disad¬ 
vantages  in  C++.  Perhaps  Berry  does 
not  understand  C  as  well  as  he  should. 

The  Worth  of  the  C++  Extensions 

As  I  get  further  into  C++  and  the  object- 
oriented  paradigm,  the  real  advantage 
they  offer  to  the  C  programmer  be¬ 
comes  evident.  The  OOPs  proponents 
might  not  agree,  but  I  believe  that  what 
C++  offers  is  not  a  better  way  to  declare 
and  define  application-specific  objects 
of  information,  but  a  marvelous  method 
for  extending  the  C  language  with  ad¬ 
vanced  and  complex  data  types. 

C  and  C++  are  language  environments 
with  no  intrinsic  input/output  opera¬ 
tions.  Early  on,  C  programmers  evolved 
a  standard  library  of  functions  that  man¬ 
age  file  and  console  I/O.  Other  stan¬ 
dard  functions  came  along  as  well  — 
string  handlers,  math,  memory  man¬ 
agement,  and  so  on.  C++,  as  a  superset 
of  ANSI  C,  inherits  all  those  functions, 
but  it  has  the  potential  for  another  layer 
of  standard  extensions  to  the  language. 
C++  lets  you  add  data  types  —  objects. 
This  means  that  you  can  extend  the 
language  to  include  types  that  have 
universal  application  to  programming 
problems.  For  example,  you  might  eas¬ 
ily  define  a  string  object  that  has  most 
of  the  functionality  of  the  string  opera¬ 
tions  that  Basic  programmers  have  al¬ 
ways  enjoyed.  Other  possible  object 

What  C++  offers  is  a 
marvelous  method  for 
extending  the  C 
language  with 
advanced  and  complex 
data  types 


extensions  are  dollar  fields,  dates, 
names,  and  addresses.  These  extensions 
are  not  complex  object  trees  such  as 
you  might  build  in  a  custom  database 
application,  but  common  data  types 
that  you  can  define  in  ways  that  every¬ 
one  can  use.  Besides  the  obvious  ones 
just  mentioned,  there  could  be  generic 
data  structures  that  most  programmers 
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use,  such  as  linked  lists,  stacks,  binary 
trees,  AVL  trees,  B-trees,  and  many  oth¬ 
ers.  C++,  far  more  than  C,  is  extensible. 

But  beware.  A  programmer  can  let 
his  imagination  overload  his  ability,  over¬ 
load  the  heck  out  of  operators  and 
functions  in  C++,  and  the  result  can 
be  the  same  kind  of  incomprehensible 
code  that  plagues  everything  from  Co- 
bol  to  4GLs. 

As  C++  overtakes  C  as  the  language 
of  choice,  we  will  need  C++  standards 
that  go  beyond  standard  functions  and 
type  extensions.  We  need  a  set  of  guide¬ 
lines  to  use  in  the  design  of  overloaded 
operators  and  functions,  lest  we  all  write 
unreadable  code.  You  could,  for  exam¬ 
ple,  easily  design  an  object  that  over¬ 
loads  the  plus  operator  to  perform  sub¬ 
traction.  That  would  be  a  silly  thing  to 
do  and  is  an  exaggeration  of  the  prob¬ 
lem,  but  C++  offers  the  potential  for 
some  really  dense  operations,  and  we 
need  direction  in  the  use  of  this  power¬ 
ful  new  tool. 

The  Zortech  C++  Compiler 

Last  year  I  began  an  occasional  foray 
into  C++  by  using  the  Zortech  C++ 
compiler.  Zortech  graciously  provided 
the  compiler,  which  is  up  to  Version 
1.07  now.  It  is  a  good  product,  being 
the  descendent  of  the  Datalite  C  com¬ 
piler.  Zortech  C++  includes  a  full  ANSI 
C  compiler  as  well  as  the  C++  product. 

The  weaknesses  in  the  Zortech  pack¬ 
age  are  in  places  that  do  not  matter 
much  to  me.  The  ZED  editor  is  a  visual 
joke,  but  I  use  Brief.  The  memory- 
resident  help  system  is  buggy,  will  freeze 
your  PC,  and  you  should  not  use  it. 
The  MAKE  utility  program  blows  up 
predictably  when  it  finds  certain  com¬ 
pile  errors.  The  compiler,  however, 
works  great.  It  does  not  have  an  inte¬ 
grated  development  environment  after 
the  fashion  of  Turbo  C  and  QuickC,  and 
it  has  no  debugger.  You  can  compile 
with  certain  switches  and  link  with  the 
Microsoft  LINK  program  so  that  you 
can  use  CodeView.  Unfortunately,  the 
Turbo  Debugger  utility  program  that 
makes  CodeView  programs  work  with 
TD  does  not  work  with  Zortech  C++ 
programs,  so  I  am  denied  the  use  of 
my  favorite  debugger. 

I  have  read  that  Zortech  C++  is  not 
compatible  with  other  C++  language 
environments,  but  I  do  not  yet  know 
enough  about  C++  to  judge,  other  than 
to  say  that  everything  I  have  learned 
from  BS  and  the  Berry  book  have 
worked  just  fine.  Until  there  are  stan¬ 
dards  for  C++  and  until  the  big  boys 
publish  C++  compilers,  Zortech  will 
do  for  me. 


C++  Windows 

To  wring  out  my  new  C++  skills,  I  de¬ 
cided  to  attempt  a  simple  language  ex¬ 
tension  and  build  a  video  window  data 
type.  Most  of  my  PC  programs  involve 
pop-up  windows  and  menus,  so  the 
Window  data  type  is  a  natural  jumping- 
off  place. 

Listing  One,  page  138,  is  window. h, 
which  defines  the  Window  class  and 
three  derived  classes.  In  addition,  win¬ 
dow. h  defines  certain  global  values  that 
are  used  by  these  new  classes.  A  C++ 
program  that  uses  the  new  classes 
would  include  this  header  file  and 
would  link  to  the  object  module  that 
is  compiled  from  Listing  Two,  window.c, 
page  138. 

Window. h  and  window.c  create  a 
new  class,  called  “Window.”  Programs 
can  now  use  objects,  which  are  in¬ 
stances  of  this  class,  just  as  they  can 
use  int, float,  struct ,  and  the  other  stan¬ 
dard  C  data  types.  A  Window  appears 
on  the  screen  when  it  comes  into  scope 
and  disappears  when  it  leaves  scope, 
so  a  using  program  does  not  open  and 
close  the  window  in  the  way  it  would 
with  traditional  C  programs.  This  con¬ 
vention  imposes  a  certain  amount  of 
structure  on  programs  that  use  the  Win- 
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dow  type,  not  altogether  a  bad  idea. 

C++  uses  constructor  and  destructor 
functions  that  accompany  a  new  class. 
The  constructor  automatically  executes 
when  the  class  comes  into  scope,  and 
the  destructor  function  executes  when 
the  class  goes  out  of  scope.  The  Win¬ 
dow’s  constructor  function  establishes 
and  displays  the  window,  and  the  des¬ 
tructor  function  erases  it.  When  you 
declare  an  object  as  an  instance  of  the 
class,  you  include  parameters  in  paren¬ 
theses  that  the  constructor  function  uses 
to  construct  the  object.  To  declare  a 
Window,  you  use  this  format: 

Window  wname(lf,tp,rt,bt,fg,bg); 

The  first  four  parameters  are  character 
coordinates  of  the  four  corners  of  the 
Window,  with  the  top  left  corner  of  the 
screen  being  0,0.  The  last  two  parame¬ 
ters  are  enum  color  constants  as  de¬ 
fined  in  window. h  that  specify  the 
foreground  and  background  colors  of 
the  window. 

A  class  definition  specifies  the  pri¬ 
vate  and  public  parts  of  the  class.  An 
evolving  convention  has  the  data  val¬ 
ues  of  the  class  in  the  private  part  and 
the  functions  that  operate  on  the  class 
(called  “methods”  inOOP-speak,  “mem¬ 
ber  functions”  in  C++  terminology)  in 
the  public  part.  Only  the  class’s  mem¬ 
ber  functions  can  read  and  write  the 
private  parts  (sorry,  but  that’s  what  the 
C++  founders  call  them)  of  the  class. 

The  Window’s  private  parts  include 
its  colors,  screen  position,  pointers  to 
video  memory  save  buffers,  cursor  po¬ 
sition,  and  a  pointer  to  a  body  of  text 
that  can  be  assigned  to  the  Window. 
The  public  parts  include  the  construc¬ 
tor  and  destructor  functions,  a  function 
to  assign  an  optional  title  to  the  Win¬ 
dow,  overloaded  «  operators  to  write 
characters,  lines,  and  blocks  of  text  to 
the  Window,  and  functions  to  manipu¬ 
late  the  text  in  a  Window.  The  com¬ 
ments  in  window,  h  tell  you  what  these 
functions  are. 

Derived  Window  Classes 

Window. h  and  window. c  contain  three 
classes  derived  from  the  Window  class. 
In  C++  a  derived  class  inherits  the  char¬ 
acteristics  of  the  class  from  which  it  is 
derived.  The  three  derived  classes  pro¬ 
vide  for  Notice  Windows,  Error  Win¬ 
dows,  and  a  YesNo  Window.  These 
utility  Windows  pop  up,  display  a  mes¬ 
sage,  wait  for  a  keystroke,  and  pop 
down.  In  each  case  the  Window  dis¬ 
plays  the  initializing  message  that  is 
specified  when  the  class  is  declared 
and  waits  for  a  keystroke  before  it  goes 
away.  The  YesNo  Window  requires  a 
Y  or  N  keystroke  and  returns  a  true 


value  if  the  key  is  the  Y.  The  difference 
between  the  other  two  are  the  Window 
colors.  As  published,  the  Error  Window 
is  red  with  blinking  yellow  letters,  and 
the  Notice  Window  has  black  letters  on 
a  cyan  background.  YesNo  Windows 
are  white  on  green. 

Console  Functions 

As  with  all  such  systems,  we  must  deal 
with  the  console  hardware.  I  have  de¬ 
fined  a  group  of  functions  that  manage 
the  screen  displays,  cursor,  and  the  key¬ 
board.  Most  of  them  have  corresponding 
functions  in  the  Zortech  display  library. 
Listing  Three,  console. h,  on  page  143, 
contains  macros  for  the  Zortech  func¬ 
tions  and  prototypes  for  the  others. 
Listing  Four,  on  page  143,  is  console. c, 
which  contains  the  functions  that  we 
need  but  that  are  not  represented  by 
Zortech  display  functions.  Users  of  other 
compilers  must  substitute  macros  or 
functions  for  those  supported  by 
Zortech  functions.  Following  are  the 
console  management  functions  needed 
by  the  Window  class  and  provided  either 
as  C  functions  in  console. c  or  macros 
to  Zortech  functions  in  console.h: 

hidecursor  —  This  function  hides  the 
cursor  so  that  its  position  still  affects 
text  displays  but  the  cursor  itself  is 
invisible. 

unhidecursoi - This  function  makes 

the  cursor  visible  again. 

savecursor  —  This  function  saves  the 
cursor’s  current  configuration  on  a  stack. 

restorecursor  —  This  function  restores 
the  cursor’s  configuration  to  the  one 
most  recently  pushed  on  the  savecur¬ 
sor  stack. 

getkey  —  This  function  gets  a  keystroke 
by  avoiding  DOS  calls  to  avoid  Ctrl- 
Break  interrupts  on  MS-DOS  computers. 
It  also  translates  function  keypresses 
into  unique  8-bit  values  as  defined  in 
console.h. 

inttconsole  and  closeconsole  — These 
functions  initialize  and  close  the  console 
functions.  Many  video  packages  require 
such  functions  for  setting  up  system 
parameters  and  flushing  buffers. 

savevideo  and  restorevideo  —  These 
functions  transfer  video  memory  char¬ 
acters  to  and  from  a  save  buffer.  They 
are  used  to  save  and  restore  what  a 
window  covers  when  it  comes  into 
scope.  The  function  parameters  spec¬ 
ify  the  buffer  address  and  the  win¬ 
dow’s  character  corner  coordinates. 


box  —  This  function  draws  a  single- 
line  box  on  the  screen.  The  Window 
class  uses  it  to  make  a  window  border. 

colors  —  This  function  establishes  the 
foreground  and  background  colors  for 
subsequent  screen  displays. 

setcursor  —  This  function  positions 
the  cursor  to  the  specified  character 
coordinates. 

window  _  printf  and  window  _  putc  — 

These  are  window-oriented  versions 
of  printf  and  putchar. 

videoscroU  —  This  is  a  window  scroll¬ 
ing  function.  Its  parameters  include  the 
direction  and  number  of  lines  to  scroll 
and  the  character  corner  coordinates. 

Look.c 

The  program  in  Listing  Five  (page  xx) 
is  look.c.  It  demonstrates  the  Window 
classes  with  a  procedure  that  lets 
you  view  a  text  file  in  a  full-screen 
Window.  Look.c  begins  by  calling  the 
set_new_handler  function,  a  BS  tech¬ 
nique  supported  by  Zortech  that  calls 
your  function  get  when  the  were  opera¬ 
tor  cannot  get  any  more  memory  from 
the  free  store.  Next,  the  program  de¬ 
clares  a  Window  that  occupies  the  en¬ 
tire  screen  and  uses  the  title  method  to 
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write  a  title  in  the  Window’s  top  bor¬ 
der.  The  program  sets  up  a  filebuf  ob¬ 
ject,  opens  a  file  by  using  the  name  on 
the  command  line,  and  associates  an 
instream  object  with  the  filebuf. 

The  C++  stream  convention  for  files 
is  one  that  I  find  less  than  intuitive. 
Buffers  are  objects  and  streams  are  ob¬ 
jects.  You  declare  a  buffer  and  tell  it  to 
open  a  file.  Then  you  declare  a  stream 
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and  associate  it  with  the  buffer.  To  read 
and  write  the  file,  you  send  messages 
to  the  methods  of  the  stream.  It  seems 
to  me  that  all  that  could  be  done  with 
one  object  making  it  simpler  and  easier 
to  understand.  But  because  the  two- 
object  convolution  is  a  BS  technique, 
compiler  vendors  will,  no  doubt,  per¬ 
petuate  it  forevermore  in  the  name  of 
conformity. 

The  look.c  program  reads  all  the  lines 
of  text  from  the  file,  puts  each  line  in  a 
new  buffer,  and  puts  the  addresses  of 
the  buffers  into  an  array  of  character 
pointers.  Then  the  text  goes  to  the  Win¬ 
dow  by  way  of  the  overloaded  «  op¬ 
erator. 

To  demonstrate  the  use  of  the  YesNo 
derived  class,  the  program  uses  a  YesNo 
window  to  ask  if  you  want  to  continue. 
If  so,  the  program  calls  the  page  mem¬ 
ber  function  to  let  you  scroll  and  page 
through  the  text. 

The  program  uses  Error  objects  to 
tell  you  that  there  was  no  file  name  on 
the  command  line  or  that  it  cannot  find 
the  file  that  you  specified. 

A  Long  Way  Up  the  C++  Slope 

The  learning  curve  I  climbed  to  get 
these  window  extensions  working  was 
steep  indeed,  and  it  was  made  worse 
by  the  dearth  of  good  OOPs  and  C++ 
tutorial  literature.  Things  would  have 
been  smoother  if  the  Berry  book  had 
been  available  for  the  C++  introduc¬ 


tion,  but  what  was  really  missing  was 
a  decent  explanation  of  the  OOP  para¬ 
digm.  To  fill  that  gap  for  you  I  am 
about  to  break  tradition  for  the  “C  Pro¬ 
gramming”  column  and  recommend 
that  you  beg,  borrow,  or  buy  Turbo 
Pascal  5  5.  It  does  not  matter  to  me  if 
you  never  use  the  software;  the  little 
book  that  explains  the  object-oriented 
extensions  to  TP  is  what  you  want.  It 
is  head  and  shoulders  above  any  intro¬ 
duction  to  OOPs  I  have  seen  so  far. 

Next  month  we’ll  use  the  Window 
class  as  a  base  from  which  to  derive 
some  menu  classes,  thus  getting  deeper 
into  the  inheritance  features  of  C++. 

Availability 

All  source  code  for  articles  in  this  issue 
is  available  on  a  single  disk.  To  order, 
send  $14.95  (Calif,  residents  add  sales 
tax)  to  Dr.  Dobb's Journal ,  501  Galves¬ 
ton  Dr.,  Redwood  City,  CA  94063;  or 
call  800-356-2002  (from  inside  Calif.) 
or  800-533-4372  (from  outside  Calif.). 
Please  specify  the  issue  and  format  (MS- 
DOS,  Macintosh,  Kaypro). 

DDJ 

(listings  begin  on  page  138.) 

Vote  for  your  favorite  feature/article. 

Circle  Reader  Service  No.  11. 


Free-Diffusion  Begets 
Shareware 


“I’m  aware  that  a  lot  of  unacknowledged 
use  of  software  is  going  on.  As  an  advocate 
of  [free!  diffusion,  I  do  not  disapprove  of 
this.  I  would  object  to  a  'double-standard’ 
in  which  ‘borrowers’  incorporated  free- 
diffusion  software  into  their  programs 
without  permission,  then  made  waves  if 
someone  else  ‘borrowed’  their  work.  This 
raises  the  question:  What  about  coding  of 
these  algorithms  for  other  micros  than  the 
650X?  You  cannot  copyright  an  algorithm. 
Thousands  of  people  could  easily  code 
them  for  the  8080  etc.  —  who,  if  anyone 
can  then  claim  an  exclusive  copyright’”  — 
H.T.  Gordon  "An  Unusual  Pseudorandom 
Number  Generator  Program DDJ, 
February,  1979. 


Yes,  And  Sometimes  It  Is  As 
Clear  as  Mud 

“A  certain  conceptual  clarity  results  from 
organizing  a  program  so  that  the  data-flow 
structure  of  the  problem  is  manifest  in  the 
procedures.”  —  L.L.  Odette,  "Computing 
With  Streams,  ”DDJ,  September,  1984. 
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STRUCTURED  PROGRAMMING 


Admitting  Objects 
to  Pascal 


I  graduated  from  Lane  Technical  High 
School  in  Chicago  in  1970.  Three 
years  later  they  first  admitted  girls.  I 
had  an  opportunity  to  go  back  seven 
or  eight  years  after  graduation  to  speak 
to  one  of  the  student  groups,  and  the 
change  stopped  me  in  my  tracks. 

Girls! 

What  a  thought  .  .  . 

The  sense  of  balance,  of  progress, 
or  rightness  was  astounding.  The  place 
was  no  longer  permeated  by  that  old 
testosterone  fog.  Right  there  in  front 
of  me,  gawky  boy-nerds  were  walking 
down  the  hall  in  animated  conversa¬ 
tion  with  gawky  girl-nerds.  It  made 
me  wonder  why  this  hadn’t  been  done 
fifty  years  earlier,  and  for  a  moment  I 
ached  to  be  fourteen  again. 

Over  the  past  couple  of  months,  both 
Borland  and  Microsoft  have  admitted 
objects  to  the  Pascal  language,  and  the 
effect  is  much  the  same.  It  feels  right, 
right  in  a  way  that  makes  you  want  to 
turn  the  clock  back  to  1972  and  start  all 
over  again. 

Nonetheless,  having  objects  now  is 
sufficient.  And  I  promise  you,  program¬ 
ming  in  Pascal  will  never  be  the  same 
again. 

QuickPascai 

Microsoft’s  QuickPascai  has  finally 
shipped,  and  at  $99  list  (street  price 
considerably  less,  if  you  follow  the 
mail  order  houses)  it  now  ties  with 
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Smalltalk/V  as  the  least  expensive  DOS 
OOP  product. 

QuickPascal’s  environment  is  quite 
slick,  with  mouse  support  and  a  multi¬ 
file  editor  its  main  features.  There  are 
a  source-level  integrated  debugger  and 
a  very  good  on-line  help  system.  Users 
of  MS  Pascal  5  0  should  note  that  Quick- 
Pascal  is  only  very  broadly  compatible 
with  MS  Pascal,  but  instead  is  a  syntac¬ 


tic  clone  of  Turbo  Pascal  5.0.  All  Turbo 
Pascal  5.0  code  I’ve  tried  to  compile 
under  QuickPascai  has  compiled  and 
run  correctly,  but .  .  .  QuickPascal’s  .EXE 
file  is  considerably  larger  than  Turbo 
Pascal’s,  and  the  size  of  the  largest 
compilable  program  under  Quick  is  cor¬ 
respondingly  smaller. 

The  two  compilers’  object-oriented 
features  are  different  enough  to  be  a 
nuisance  but  similar  enough  to  treat 
together. 

Parallel  Evolution 

Considering  that  the  two  products  were 
developed  in  isolation,  Microsoft’s  Quick- 
Pascal  and  Borland’s  Turbo  Pascal  5  5 
have  a  remarkably  similar  slant  on  ob¬ 
ject  orientation.  Their  differences  can 
be  attributed  to  ancestry:  QuickPascai 
adheres  pretty  closely  to  the  Apple  Ob¬ 
ject  Pascal  specification,  whereas  Turbo 
Pascal  5  5  draws  about  equally  on  Ob¬ 
ject  Pascal  and  C++.  In  an  interlocking 
directorate  like  this,  similarities  are  likely 
to  outnumber  differences. 

For  both  products,  objects  are  closely 
related  to  records  and  are  defined  in 
just  about  the  same  way.  The  impor¬ 
tant  thing  to  notice  about  object  defini¬ 
tions  is  that  code  and  data  are  defined 
together,  within  a  named  structure.  This 
is  how  object-oriented  Pascal  imple¬ 
ments  encapsulation: 

TYPE 

PrintByte  = 

OBJECT 

BV  :  Byte;  I  Byte  Value  ) 

FUNCTION 

DontPrint(ShouldI  :  Byte)  : 

Boolean; 

PROCEDURE  PrintDecimal; 

PROCEDURE  PrintHex; 

PROCEDURE  PrintBinary; 

PROCEDURE  PrintSymbol; 
END; 

The  new  reserved  word  OBJECT  makes 
this  an  object  definition.  Referencing  code 


and  data  is  done  through  another  record¬ 
like  convention,  dotting.  Assuming  an 
object  instance  named  MyByte,  you 
would  reference  field  BV  as  MyByte. BV, 
and  call  the  PrintHex  method  as  MyByte. 
PrintHex. 

Object  Types  with  No  Class 

Adam  gave  all  the  animals  unique  names 
because  when  he  said,  “Hey  you  with 
the  four  legs  and  a  tail!”  half  of  creation 
ambled  over.  The  naming  of  names 
is  a  critical  issue  in  object-oriented  pro¬ 
gramming,  because  so  many  of  the  con¬ 
cepts  are  new.  Sadly,  there  are  major 
disparities  in  how  QuickPascai  and 
Turbo  Pascal  refer  to  certain  concepts. 

The  worst  and  most  confusing  is  what 
to  call  objects  themselves.  Just  as  vari¬ 
able  types  and  variables  are  not  the 
same  things,  objects  and  their  types  are 
not  the  same  either.  An  object  type  in 
Turbo  Pascal  is  simply  an  “object  type," 
and  an  object  variable  (what  we  also 
call  an  instance  of  an  object  type)  is 
just  an  “object.”  QuickPascai  uses  the 
term  “class”  instead  of  “object  type,” 
but  the  meaning  is  exactly  the  same. 
The  term  “class”  comes  from  Smalltalk, 
as  I  described  last  month.  In  this  col¬ 
umn  I’ll  be  using  the  term  “object  type” 
rather  than  “class”  in  this  column  (re¬ 
gardless  of  which  Pascal  is  under  dis¬ 
cussion)  because  it’s  more  descriptive 
and  sounds  less  mystical/magical. 

Creating  Objects 

Turbo  and  Quick  diverge  most  sharply 
in  their  means  of  creating  objects.  Turbo 
Pascal  objects  are  true  to  their  record¬ 
like  heritage.  You  can  create  an  object 
in  the  same  ways  you  create  a  record, 
either  as  a  static  variable  in  the  data 
segment,  or  as  a  dynamic  variable  on 
the  heap: 

VAR 

(  Declaring  a  static  object:  1 

MyByte  :  PrintByte; 

{  A  pointer  to  a  dynamic  object:  1 
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MyBytePtr :  AprintByte; 

I  Allocating  a  dynamic  object:  1 

New(MyBytePtr); 

These  items  could  as  well  be  records 
as  objects.  The  syntax  is  the  same. 

QuickPascal  implements  objects  as 
something  truly  different.  An  object  in¬ 
stance  variable  may  exist  only  on  the 
heap;  there  is  no  way  to  create  an  ob¬ 
ject  in  the  data  segment.  Syntactically, 
object  variables  sit  on  the  fence  half¬ 
way  between  records  and  pointers.  An 
object  is  treated  like  a  record  when 
defined,  treated  like  a  pointer  when 
created,  and  then  treated  like  a  record 
when  used,  with  a  couple  of  twists: 

VAR 

(  Allocates  no  space!!  1 

QuickByte  :  PrintByte; 

(  Allocates  object  on  heap:  I 

New(QuickByte); 

(  Reference  without  caret:  1 

QuickByte. BV  :=  42; 

This  is  supposed  to  be  a  sort  of  short¬ 
hand,  allowing  programmers  to  dis¬ 
pense  with  the  multitude  of  caret  sym¬ 
bols  that  would  be  necessary  if  objects 
on  the  heap  really  were  treated  as  pointer 
referents.  And  while  shorthand  is  con¬ 
venient,  it’s  hard  to  read,  and  I’m  afraid 
this  somewhat  inconsistent  syntax  is 
something  (like  irregular  verbs  in  Span¬ 
ish)  that  you  just  have  to  bite  the  mne¬ 
monic  bullet  and  remember. 

Once  a  Quick  object  is  created,  it 
can  be  referenced  just  as  a  Turbo  Pas¬ 
cal  object  can  be.  The  inconsistency 
returns  when  you  want  to  reclaim  an 
object’s  heap  space.  You  pass  the  ob¬ 
ject’s  identifier  to  Dispose,  again  as 
though  the  object  were  a  pointer: 

Dispose(QuickByte); 

Overriding  Methods 

Creating  a  child  object  type  that  inher¬ 
its  from  a  parent  object  type  is  done 
identically  in  both  implementations.  The 
name  of  the  parent  type  is  enclosed 
in  parentheses  after  the  child  type’s 
OBJECT  reserved  word: 

TYPE 

PrintByteHP  = 

OBJECTCPrintByte) 

PROCEDURE  Print  Symbol 
I;  OVERRIDE;) 

END; 

The  differences  between  the  two  prod¬ 
ucts  emerge  again  when  a  method  de¬ 
fined  in  the  parent  object  type  is  rede- 
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fined,  or  overridden,  by  a  new  method 
with  the  same  name.  Turbo  Pascal  sim¬ 
ply  allows  the  method  to  be  overrid¬ 
den  by  redefining  it.  QuickPascal  re¬ 
quires  that  the  overriding  method  be 
flagged  to  the  compiler  with  the  OVER¬ 
RIDE  reserved  word.  I  kind  of  like  that: 
It  makes  the  code  easier  to  compre¬ 
hend  by  flagging  unmistakably  whether 
a  method  is  brand  new  in  the  object 
hierarchy,  or  whether  it  redefines  a 
method  farther  up  the  hierarchy  tree. 

In  Search  of  Self 

The  one  thing  that  drives  me  truly 
berserk  about  QuickPascal  is  its  Self¬ 
ishness.  Within  the  body  of  a  method, 
the  object’s  data  fields  need  to  be  quali¬ 
fied  by  the  use  of  a  new  predefined 
identifier,  Self.  Here’s  a  simple  Quick¬ 
Pascal  method  definition  belonging  to 
the  PrintByte  object  type: 

PROCEDURE  PrintByte. 

PrintDecimal; 

BEGIN 

Write(LST,Self.BV:3); 

END; 

This  is  peculiar  —  traditional  Pascal  scop¬ 
ing  should  allow  the  compiler  to  rec¬ 
ognize  a  reference  to  an  object’s  fields 
as  local  variables.  After  all,  the  method 
definition  begins  with  the  PrintByte. 
qualifier,  and  field  BV  is  as  much  a 
part  of  PrintByte  as  the  PrintDecimal 
method.  Most  remarkably,  using  the 
WITH  Self  DO  structure  does  not  work 
with  methods.  (It  does  work  with  ob¬ 
ject  data  fields,  however.)  Methods  must 
be  qualified  by  Se/fitself,  directly.  This 
may  be  a  bug  or  it  may  be  a  feature, 
depending  on  how  you  look  at  it,  but 
every  time  I  look,  I  see  six  legs. 

Yet  another  interesting  wrinkle  here 
is  that  Turbo  Pascal  allows,  but  does 
not  require,  the  use  of  the  5e//)dentifier 
in  the  same  context. 

A  Simple  Object  Pascal  Example 

This  column's  listings  present  a  simple 
but  useful  example  of  Object  Pascal  in 
action.  I’ve  given  it  for  both  Turbo  Pas¬ 
cal  5.5  and  QuickPascal,  and  compar¬ 
ing  the  two  will  give  you  a  reasonable 
feel  for  the  way  the  two  implementa¬ 
tions  go  about  things.  Listings  One  and 
Two,  page  146,  are  for  Turbo  Pascal, 
and  Listings  Three  and  Four,  page  149, 
are  for  QuickPascal. 

The  program  itself  prints  an  ASCII 
table,  including  all  256  character  pat¬ 
terns  from  the  smiley  faces  on  up 
through  the  box  drawing  and  math 
characters.  The  catch  in  creating  such 
a  program  is  that  while  many  PC-com¬ 
patible  printers  can  print  a  smiley  face 


or  its  brothers,  the  nature  of  the  com¬ 
mand  to  print  such  special  characters 
varies  all  over  the  map. 

The  PRINBYTE.PAS  (and  PRINT- 
BYTQ.PAS  for  QuickPascal)  implements 
a  simple  object  that  is  nothing  more 
than  a  byte  value  with  some  methods 
to  display  it  to  the  printer  in  various 
formats,  including  decimal,  hex,  binary, 
and  “literal,”  that  is,  in  the  form  of  a 
single  character.  The  value  is  stored  in 
the  PrintByte  object’s  sole  data  field, 
BV.  The  value-added  in  the  PrintByte 
object  lies  in  the  object’s  methods. 

Most  ASCII  characters  can  be  printed 
as  literal  symbols  simply  by  sending 
them  to  the  printer  port.  Send  a  65 
value  and  you’ll  get  an  A  on  the  printer. 
Send  the  value  236  and  you’ll  get  an 
infinity  symbol.  Some  characters,  how¬ 
ever,  are  control  characters,  and  exist 
not  to  be  displayed  so  much  as  to  dic¬ 
tate  commands  to  the  printer.  These 
control  characters  include  carriage  re¬ 
turn  (13),  line  feed  (10),  and  BEL  (7). 
Send  a  control  character  to  the  printer 
and  you  won’t  see  any  symbol,  but 
instead  the  printer  will  index  or  beep 
or  do  something  else  that  involves  its 
mechanism  rather  than  its  output. 

As  you  might  imagine,  some  charac¬ 
ters  do  double  duty  as  both  control 
characters  and  symbols.  The  control 
character  guise  of  such  characters 
(typically,  values  1-31)  takes  priority. 
Send  a  7  to  the  printer,  and  the  printer’s 
beeper  will  beep.  To  get  a  hardcopy 
of  the  small  circular  bullet  that  is  char¬ 
acter’s  symbolic  guise,  you  must  send 
a  control  sequence  to  the  printer.  Such 
a  control  sequence  is  often  an  ESC 
character  (27)  followed  by  the  control 
character,  but  each  printer  has  its  own 
way  of  responding  to  control  sequences, 
and  no  standard  prevails. 

Go  Print  Yourself! 

Printing  the  ASCII  chart  on  any  arbi¬ 
trary  printer  would  mean  a  program 
that  knew  about  every  printer  on  the 
market,  which  is  obviously  impossible. 
The  way  out  is  for  the  PrintByte  object 
to  take  the  low  road  and  refuse  to  print 
any  control  character  at  all  —  and  let 
the  user  of  the  PrintByte  object  extend 
PrintByte  to  match  the  user’s  specific 
printer.  The  example  shown  uses  the 
HP  LaserJet  II  printer  as  the  specific 
printer.  You  can  modify  (and  should, 
for  practice)  ASCII. PAS  or  ASCIIQ.PAS 
to  match  the  needs  of  your  own  printer, 
whatever  it  might  be. 

Extendability  of  code  is  one  of  the 
major  benefits  of  object-oriented  pro¬ 
gramming.  The  way  is  to  define  a  child 
object  of  the  PrintByte  object,  and  over¬ 
ride  only  the  method  that  prints  the 
symbol  to  the  printer.  This  is  the 
PrintSymbol  method. 
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ASCII. PAS  and  ASCIIQ.PAS  (for  Quick- 
Pascal)  demonstrates  this.  A  child  ob¬ 
ject  type,  PrintByteHP ,  is  defined  so 
that  it  inherits  all  of  PrintBytds  data 
and  methods.  PrintByteHP  changes  only 
what  must  be  changed  —  no  unneces¬ 
sary  duplication  of  code  is  needed.  The 
only  change  is  to  the  PrintSymbol 
method,  which  is  redefined  in  ASCII. PAS 
and  ASCIIQ.PAS.  Note  the  presence 
of  the  OVERRIDE  reserved  word  in 
ASCIIQ.PAS. 

The  sense  of  the  PrintByteHP  object 
type  is  that  it  extends  the  PrintByte 
object  type  by  “knowing”  how  to  print 
control  symbols  to  the  LaserJet  II  printer. 
(The  PrintByte  type  simply  punts  by 
printing  a  space  for  any  control  charac¬ 
ter.)  So  you  as  a  programmer  don’t 
have  to  fuss  with  control  sequences. 
You  simply  tell  a  particular  PrintByteHP 
object  to  go  print  itself,  and  shazam! 
You’ve  got  smiley  faces  all  over  the 
place. 

Look  Ma,  No  Source! 

One  of  the  interesting  benefits  of  this 
process  is  that  an  object  can  be  ex¬ 
tended  by  a  programmer  without  hav¬ 
ing  the  source  code.  I  provide  you  with 
PRINBYTE.PAS,  but  all  you  really  need 
is  the  object  type’s  definition  (basically, 
the  procedure  headers  and  data  defini¬ 
tions)  and  the  linkable  unit  file  imple¬ 
menting  the  object.  This  can  be  done 
to  some  extent  with  Pascal  units  right 
now,  in  that  you  can  write  a  different 
version  of  a  routine  in  a  unit,  and  as 
long  as  your  rewritten  routine  is  linked 
after  the  routine  it  replaces,  the  re¬ 
placement  routine  will  be  used  by  all 
code  linked  afterwards. 

The  real,  real  slick  wrinkle  (not  shown 
in  this  example)  is  the  way  that  the 
original  object  can  make  use  of  its  child 
objects  that  did  not  exist  when  the 
parent  object  was  compiled.  (Think 
about  that  for  a  moment.)  It’s  part  of 
the  mind-warping  notion  of  polymor¬ 
phism,  and  I’ll  return  with  some  con¬ 
crete  examples  in  a  future  column. 

In  the  meantime,  I  powerfully  rec¬ 
ommend  that  you  pick  up  either  Turbo 
Pascal  5.5  or  QuickPascal  and  start  prac¬ 
ticing  your  objects  now. 

Nothing  more  important  has  hap¬ 
pened  to  programming  languages  since 
procedures  parted  the  in-line  code 
chaos  in  the  seventies. 

Blows  Against  the  Empire 

As  my  sixties  Day-Glo  Desiderata  poster 
used  to  say,  “No  doubt  the  universe  is 
unfolding  as  it  should.”  Those  ubiqui¬ 
tous  370-class  mainframes  (as  distinct 
from  what  are  now  called  —  gakkh!  — 
supercomputers)  are  evolving  into  their 
appropriate  ecological  niche  as  rela¬ 


tively  dumb  but  cavernous  file  servers 
under  the  control  of  personal  computers 
out  where  the  real  work  gets  done. 

Not  surprisingly,  your  average  MIS/ 
DP  department  doesn’t  see  things  this 
way.  (Just  as  T.  Rex  didn’t  say,  “Hi, 
Boss!”  to  the  shrew  with  egg  yolk  on 
his  whiskers.)  Ask  DP  for  a  mainframe 
application,  and  the  schedule  will  be 
something  like  six  months  plus  a  fudge 
factor  of  three  months  to  two  years, 
depending  on  how  recently  the  MIS 
manager  got  a  promotion.  I  can  smile 
now  (having  been  out  of  Xerox  MIS  for 
six  years)  but  the  DP  backlog  is  still  a 
serious  problem  out  in  pinstripe  land. 

And  I  don’t  normally  have  much  truck 
with  teenage  mutant  Ninja  languages, 
but  one  has  recently  come  to  light  that 
has  landed  some  serious  blows  against 
the  DP  empire.  It’s  called  REXX,  and  if 
you’re  in  the  position  of  living  in  the 
walls  of  T.  Rex’s  nest,  it’s  a  great  way 
of  making  omelets  out  of  the  big  guy. 

REXX  is  a  structured  language  devel¬ 
oped  originally  for  370-class  main¬ 
frames  by  a  delightful  IBM  curmud¬ 
geon  named  Mike  Cowlishaw.  It  was 
designed  as  a  replacement  for  the  main¬ 
frame  batch  processor  cancer  they  call 
JCL,  and  has  therefore  been  called  a 
“super  batch  language.”  REXX  can  be 
used  as  a  batch  language,  but  it’s  a  real 
programming  language  in  its  own  right 
with  all  the  body  parts  a  proper  lan¬ 
guage  ought  to  have.  (Including 
GOTO  —  now  that’s  authentic!)  It’s  most 
similar  to  Basic  in  that  it’s  usually  inter¬ 
preted  and  has  that  inescapable  line- 
oriented  mainframe  flavor  about  it. 

REXX  is  important  to  this  column:  It 
has  a  crisp  definition  published  by  Cow¬ 
lishaw  that  has  enabled  identical  imple¬ 
mentations  on  both  mainframes  and 
on  PCs  under  DOS.  This  means  that 
you  can  build  a  REXX  application  in 
the  safety  and  comfort  of  your  cubicle, 
and  upload  it  to  your  mainframe  users 
when  T.  Rex  isn’t  looking.  Shazam! 
You’ve  cut  the  development  time  for  a 
simple  readafile/writearecord  DP  ap¬ 
plication  from  ten  months  to  ten  hours. 

There  are  numerous  mainframe  im¬ 
plementations  of  REXX,  and  I’m  told 
one  can  be  had  for  almost  any  of  the 
innumerable  different  370  operating  en¬ 
vironments.  The  only  commercial  im¬ 
plementation  for  DOS  is  the  one  I  tested 
and  will  describe  later,  Personal  REXX 
from  The  Mansfield  Software  Group. 

With  Feet  in  Two  Worlds 

I’ve  not  had  the  honor  of  sweating 
blood  over  the  VM/CMS  mainframe  op¬ 
erating  system,  so  I  can’t  tell  you  how 
REXX  looks  from  its  perspective.  From 
DOS,  however,  REXX  is  very  much  a 


language  with  feet  in  two  worlds.  On 
one  hand,  as  I’ve  said,  REXX  is  a  per¬ 
fectly  ordinary  and  reasonable  inter¬ 
preted  language.  All  the  familiar  pro¬ 
gram  structures  are  there  and  imple¬ 
mented  quite  nicely.  On  the  other  hand, 
when  REXX  encounters  a  clause  it  does 
not  recognize  as  part  of  a  REXX  state¬ 
ment,  it  automatically  passes  that  clause 
to  DOS  to  execute.  This  ability  is  what 
makes  REXX  a  super-batch  language. 

Mansfield  allows  REXX  to  be  loaded 
from  disk  as  a  transient  program  that 
remains  in  memory  only  while  the  cur¬ 
rent  REXX  program  is  being  interpreted, 
or  REXX  can  be  loaded  as  a  TSR  that 
remains  in  memory  until  unloaded  or 
until  reboot.  The  TSR  REXX  takes  150K 
of  RAM,  which  prevents  its  use  with 
many  of  the  larger  business  applica¬ 
tions.  My  hunch  is  that  memory  man¬ 
agement  is  the  real  kicker  in  making 
REXX  pay  off  under  DOS.  You’ll  have 
to  experiment  to  get  a  feel  for  what’s 
possible  and  what’s  impossible. 

REXX  as  a  batch  processor  doesn’t 
interest  me  nearly  as  much  as  REXX 
as  a  mainframe  bridge,  and  as  a  main¬ 
frame  bridge  it  won’t  be  managing  DOS 
applications. 

Language  Highlights 

Space  is  short,  so  I  won't  rehash  how 
REXX  implements  ordinary  structured 
elements  like  DO  loops,  IF  statements, 
and  so  on.  They’re  all  there,  and  re¬ 
semble  Pascal’s  strongly.  REXX  does 
contain  some  remarkable  features  that 
I  would  like  to  call  attention  to.  For  the 
full  story  on  REXX,  get  Cowlishaw’s 
“white  book”  on  the  language,  which 
defines  it  thoroughly  and  is  one  of  the 
most  readable  such  white  books  as 
well:  The  REXX  Language,  M.F.  Cow¬ 
lishaw,  Prentice-Hall,  1985.  (Note  that 
The  Mansfield  Software  Group  bun¬ 
dles  Cowlishaw’s  book  with  their  Per¬ 
sonal  REXX  product,  so  if  you  buy  the 
book  and  then  buy  Personal  REXX, 
you’ll  be  buying  the  book  twice.) 

The  PARSE  instruction  provides  a  gen¬ 
eralized  string  parser  that  dismantles  a 
string  value  into  several  separate  vari¬ 
ables  according  to  a  template.  A  good 
example  is  entry  of  date  values: 

SAY  “Enter  the  date  as  mm/dd/yy” 

PARSE  PULL  mo  ’/’  da  ’/’  yr 

Here,  the  user  is  told  what  string 
data  to  enter  with  the  SAY  instruction. 
The  PULL  instruction  is  roughly  analo¬ 
gous  to  Readln ,  in  that  it  pulls  data 
in  from  an  input  queue.  The  template 
is  mo  /'  da  /’  yr,  indicating  that  the 
string  data  accepted  through  PULL  is 
to  be  separated  out  into  three  string 
variables,  with  slash  symbols  acting  as 
separators. 
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This  is  about  as  simple  as  a  useful 
template  gets,  and  REXX’s  parser  is  ca¬ 
pable  of  a  lot  more.  Patterns  to  be 
matched  may  be  stored  in  variables 
and  may  be  looked  for  in  specific  posi¬ 
tions  in  the  string  if  desired.  Parsers  are 
elemental  code  machines  that  should 
be  a  part  of  every  language,  but  in  fact 
are  part  of  almost  none. 

Perhaps  the  most  intriguing  REXX 
construct  is  INTERPRET,  which  allows 
a  REXX  program  to  build  a  mini-REXX 
program  on  the  fly  and  then  interpret 
it.  Interpreted  Prolog  implementations 
can  do  something  like  this,  but  none 
of  the  traditional  languages  (Pascal,  C, 
Modula-2,  Basic,  Fortran,  ADA)  have 
anything  that  comes  even  close.  In 
his  book,  Cowlishaw  does  little  with 
INTERPRETb u t  uses  it  to  write  a  simple 
formula  calculator  emulator,  but  in  fact 
this  way  of  treating  code  as  data  is  used 
in  a  lot  of  AI  research  —  if  any  readers 
have  used  REXX  in  this  fashion,  I’d  like 
to  hear  about  it. 

That  Old  Mainframe  Goblin 

While  REXX  the  language  is  easy  to 
program  in  and  relatively  easy  to  read, 
REXX  the  language  processor  is  haunted 
by  that  old  mainframe  goblin,  com¬ 
plexity.  There  are  any  number  of  ways 
to  feed  statements  to  REXX,  and  lots 
of  niggling  little  gotchas  that  must  be 
digested  and  understood  to  make  the 
program  operate  to  its  best  advantage. 
Many  of  these  seem  unnecessary,  like 
the  separate  TSR  that  does  nothing  but 


grab  interrupt  vector  60.  Grabbing  vec¬ 
tors  is  not  time  consuming  and  should 
be  done  in  an  initialization  section/exit 
procedure  manner  inside  the  language 
processor,  as  with  Turbo  Pascal.  A  much 
simpler  Personal  REXX  could  be  cre¬ 
ated  if  The  Mansfield  Software  Group 
decided  to  go  the  distance. 

On  the  other  hand,  if  you  can  (or 
must)  handle  mainframes,  you  can  han¬ 
dle  REXX.  Give  it  a  shot. 

Sometimes  a  Great  Notion . . . 

.  .  .  never  quite  seems  to  set  the  world 
on  fire  as  it  should.  I  am  personally 
fond  of  technical  anthologies;  that  is, 
books  to  which  several  experts  on  a 
subject  have  each  contributed  a  chap¬ 
ter.  Such  books  are  rare,  and  publish¬ 
ers  for  some  reason  don’t  like  them. 

So  you’ll  have  to  forgive  me  for  rec¬ 
ommending  one  such  book  here,  even 
though  I  was  a  (relatively  minor)  con¬ 
tributor.  It’s  from  a  small  publisher  and 
has  had  little  distribution,  but  get  it  if 
you  can:  Turbo  Pascal  Innovations,  ed¬ 
ited  by  Judie  Overbeek  and  Rick  Gess- 
ner.  If  you  can’t  find  it  at  a  bookstore 
(likely)  the  book  can  be  ordered  di¬ 
rectly  from  the  publisher. 

The  book  contains  eight  chapters  in 
all,  each  on  a  different  subject  by  a 
different  author.  The  topics  include 
(among  others)  DOS  time  and  date  top¬ 
ics,  directory  management,  high-preci¬ 
sion  code  timing,  graphics,  and  proce¬ 
dural  types.  I  don’t  have  time  to  de¬ 
scribe  them  all,  but  there  are  two  abso¬ 
lutely  essential  chapters:  One  by  Rick 


Products  Mentioned 


Turbo  Pascal  5.5 
Borland  International 
1800  Green  Hills  Road 
Scotts  Valley,  CA  95066 
408-438-8400 
Turbo  Pascal  $149 
Turbo  Pascal  Professional 
(Includes  Turbo  Debugger 
&  Turbo  Assembler)  $250 


Turbo  Pascal  Innovations 
Ed.  by  Judie  Overbeek  & 

Rick  Gessner 

Rockland  Publishing,  Inc.,  1989 

1706  Bison  Drive 

Kalispell,  MT  59901 

406-756-9079 

ISBN  0-939621-01-0 

$32.95  (includes  listings  diskette) 


QuickPascal  1.0 
Microsoft 

16011  NE  36th  Way 
Redmond,  WA  98073 
206-882-8088 
$99.00 

The  REXX  Language 
M.F.  Cowlishaw 
Prentice-Hall,  1985 
ISBN  0-13-780685-X 
$19.95 

Personal  REXX 

The  Mansfield  Software  Group 

PO  Box  532 

Storrs,  CT  06268 

203-429-8402 

DOS  version  $150.00 

OS/2  version  (which  includes 

DOS  version)  $175.00 
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(continued  from  page  134) 

Gessner  on  user-interface  design,  and 
another  by  Lane  Ferris  describing  a  unit 
allowing  you  to  write  TSR  programs  that 
multitask  with  ordinary  DOS  programs. 

For  all  that  user-interface  design  is 
touted  as  the  key  to  improved  user 
productivity,  there’s  been  little  published 
on  just  how  such  interface  code  is  de¬ 
signed.  Gessner  does  an  excellent  job 
of  providing  some  guidelines  for  user 
interface  components,  along  with  sam¬ 
ple  implementations  of  various  line  edi¬ 
tors  and  menus.  The  code  is  solid  and 
easy  to  read,  and  the  approach  demon¬ 
strates  a  sensitivity  to  human  needs 
that  rarely  turns  up  in  the  programmer 
press. 

The  real  blockbuster  in  this  book, 
however,  is  Lane  Ferris’s  multitasking 
TSR  unit.  Code  like  this  doesn’t  happen 
by  very  often,  and  when  it  does,  it  is 
rarely  opened  up  and  dissected  with 
such  clarity.  Lane’s  unit  uses  a  round- 
robin  time-slicing  system  to  allow  a 
TSR  to  pre-emptively  execute  multiple 
tasks  while  the  DOS  foreground  pro¬ 
gram  multitasks  on  equal  terms.  This 
means  you  can  put  something  as  sim¬ 
ple  as  a  real-time  clock  in  the  corner 
of  your  screen,  or  something  as  com¬ 
plex  as  a  pop-up  calculator  that  doesn’t 
freeze  your  telecommunications  ses¬ 
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sion  in  the  foreground.  Very  heavy  stuff, 
and  beautifully  implemented. 

Best  of  all,  it’s  not  written  in  C. 

The  reason  books  like  this  are  valu¬ 
able  is  that  no  one  person  is  equally 
good  at  everything,  and  by  presenting 
the  best  that  several  intelligent  persons 
have  to  offer,  the  book  becomes  far 
more  diverse  and  useful  than  a  book 
any  single  person  could  create.  In 
that  respect  it’s  like  a  very  thick  maga¬ 
zine  with  no  ads.  Nothing  quite  like 
it .  .  .  even  though  there  should  be. 

When  the  Good  Die  Young 

I  was  at  the  American  Booksellers 
Association  convention  in  Washington, 
D.C.  when  1  got  the  news  that  Kent 
Porter  had  died  in  the  saddle,  doing 
what  both  he  and  I  do  every  day:  Writ¬ 
ing  and  editing.  I  met  Kent  when  he 
submitted  a  raft  of  articles  to  TURBO 
TECHNIX,  and  acted  as  his  editor  there 
for  an  outstanding  series  of  projects, 
including  his  popular  “Mouse  Myster¬ 
ies’’  series.  Later,  when  TURBO  TECH¬ 
NIX  became  history,  the  partitions 
swapped  a  little  and  Kent  became  my 
editor  here  at  DDJ.  We  understood 
one  another  in  the  way  that  only  two 
editors  —  who  have  edited  one  another’s 
work  —  can. 

Kent’s  mission  and  mine  were  the 


same:  To  wipe  the  fuzz  away  from 
your  windows  onto  the  programming 
craft,  and  in  doing  so  spread  the  magic 
around  to  the  uninitiated.  Magazines 
and  books  don’t  just  happen  —  behind 
each  is  a  strong  mind  and  a  strong 
hand;  writer  and  editor  working  to¬ 
gether  in  a  common  cause.  It  takes 
some  skill  to  see  the  work  of  the  edi¬ 
tor’s  hand  sometimes  —  unless  you’re 
another  editor. 

Good  night,  good  friend.  As  to  your 
mission:  Stet. 

It  will  stand. 

Availability 

All  source  code  for  articles  in  this  issue 
is  available  on  a  single  disk.  To  order, 
send  $14.95  (Calif,  residents  add  sales 
tax)  to  Dr.  Dobb’s Journal,  501  Galves¬ 
ton  Dr.,  Redwood  City,  CA  94063;  or 
call  800-356-2002  (from  inside  Calif.) 
or  800-533-4372  (from  outside  Calif.). 
Please  specify  the  issue  and  format  (MS- 
DOS,  Macintosh,  Kaypro). 

DDJ 

(Listings  begin  on  page  146.) 

Vote  for  your  favorite  feature/article. 

Circle  Reader  Service  No.  12. 
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C  PROGRAMMING 


Listing  One  (Text  begins  on  page  121.) 

// - window,  h 


♦include  "console. h" 

♦define  HEIGHT  (bt  -  tp  +  1) 
♦define  WIDTH  (rt  -  If  +  1) 


♦ifndef  WINDOWS 
♦define  WINDOWS 

//  -  screen  dimensions 

♦define  SCREENWIDTH  80 
♦define  SCREENHEIGHT  25 

//  -  atrribute  values  for  colors 

enum  color  { 

BLACK,  BLUE,  GREEN,  CYAN,  RED,  MAGENTA,  BROWN,  LIGHTGRAY, 
GRAY,  LIGHTBLUE,  LIGHTGREEN,  LIGHTCYAN,  LIGHTRED, 
LIGHTMAGENTA,  YELLOW,  WHITE,  BLINK  =  128 

); 


// - spaces  per  tab  stop  (text  displays) 

♦define  TABS  4 

//  -  color  assignments  for  window  types 


♦define  YESNOFG  WHITE 
♦define  YESNOBG  GREEN 
♦define  NOTICEFG  BLACK 
♦define  NOTICEBG  CYAN 
♦define  ERRORFG  (YELLOW  I  BLINK) 
♦define  ERRORBG  RED 


video  window 


//  window  colors 

//  window  position 

//  video  memory  save  buffer 

//  hide  window  save  buffer 

//  current  cursor  row  and  column 

//  tab  stops,  this  window 

//  window  text  content 


// - 

class  Window 

unsigned  bg,  fg; 
unsigned  lf,tp, rt,bt; 
unsigned  ‘wsave; 
unsigned  *hsave; 
unsigned  row,  col; 
int  tabs; 
char  “text; 
public: 

Window (unsigned  left,  unsigned  top, 

unsigned  right,  unsigned  bottom, 
color  wfg,  color  wbg) ; 

“Window (void) ; 
void  title (char  *ttl); 

Windows  operator«(char  “btext); 

Windows  operator«(char  *ltext); 

Windows  operator«  (char  ch) ; 
void  cursor (unsigned  x,  unsigned  y) ; 
void  cursor (unsigned  *x,  unsigned  *y) 

(  *y  -  row,  *x  =  col;  ) 
void  clear_window (void) ; 
void  clreos (void) ; 
void  clreol (void) ; 
void  hidewindow(void) ; 
void  restorewindow(void) 
void  page (void); 
void  scroll (int  d) ; 
void  set_colors (int  cfg,  int  cbg) 

{  fg  =  cfg,  bg  =  cbg;  ) 
void  set_tabs(int  t)  //  change  the  tab  stops 

{  if  (t  >  1  ss  t  <  8)  tabs  =  t;  ) 

); 


//  clear  to  end  of  screen 
//  clear  to  end  of  line 
//  hide  an  in-scope  window 
//  unhide  a  hidden  window 
//  page  through  the  text 
//  scroll  the  window  up,  down 
//  change  the  colors 


//  -  utility  notice  window 

class  Notice  :  Window  { 
public: 

Notice (char  ‘text); 

“Notice () { ) 

}; 

//  -  utility  yes/no  window 

class  YesNo  :  Window  { 
public: 

YesNo (char  ‘text); 

“YesNo () { ) 
int  answer; 

)! 


//  -  utility  error  window 

class  Error  :  Window  { 
public: 

Error (char  ‘text); 

“Error  ()  { } 

}; 

♦define  max (x,y)  ( ( (x)  >  (y) )  ?  (x)  :  (y) ) 
♦define  min(x,y)  ( ( (x)  >  (y))  ?  (y)  :  (x) ) 

♦endif 


End  Listing  One 


Listing  Two 

// - window,  c 


// - constructor  for  a  Window 

Window: : Window (unsigned  left,  unsigned  top,  //  0  -  79,  0-24 
unsigned  right,  unsigned  bottom, 
color  wfg,  color  wbg) 

{ 

savecursor () ; 
initconsole () ; 
hidecursor () ; 

//  -  adjust  for  windows  beyond  the  screen  dimensions 

if  (right  >  SCREENWIDTH-1)  { 

left  -=  right- (SCREENWIDTH-1) ; 
right  =  SCREENWIDTH-1; 

} 

if  (bottom  >  SCREENHEIGHT-1 )  { 

top  -=  bottom- (SCREENHEIGHT-1); 
bottom  =  SCREENHEIGHT-1; 

) 

//  -  initialize  window  dimensions 

If  =  left; 
tp  =  top; 
rt  =  right; 
bt  =  bottom; 

//  -  initialize  window  colors 

fg  =  wfg; 
bg  =  wbg; 

//  -  initialize  window  cursor  and  tab  stops 

row  =  col  -  0; 
tabs  =  TABS; 

// - save  the  video  rectangle  under  the  new  window 

wsave  =  new  unsigned [HEIGHT  »  WIDTH); 
hsave  -  NULL; 

savevideo (wsave,  tp,  If,  bt,  rt); 

// - draw  the  window  frame 

box(tp,  If,  bt,  rt,  fg,  bg) ; 

// - clear  the  window  text  area 

clear_window() ; 
unhidecursor () ; 

) 

// - destructor  for  a  Window 

Window:  .‘“Window (void) 

( 

//  -  restore  the  video  RAM  covered  by  the  window 

restorevideo (wsave,  tp,  If,  bt,  rt) ; 
delete  wsave; 
if  (hsave  !=  NULL) 
delete  hsave; 
restorecursor () ; 

J 

//  -  hide  a  window  without  destroying  it 

void  Window: :hidewindow (void) 

I 

if  (hsave  —  NULL)  ( 

hsave  =  new  unsigned [HEIGHT  *  WIDTH); 
savevideo (hsave,  tp,  If,  bt,  rt); 
restorevideo (wsave,  tp,  If,  bt,  rt); 

) 

1 

//  -  restore  a  hidden  window 

void  Window: : restorewindow ( void) 

1 

if  (hsave  !=  NULL)  { 

savevideo (wsave,  tp,  If,  bt,  rt); 
restorevideo (hsave,  tp,  If,  bt,  rt); 
delete  hsave; 
hsave  =  NULL; 
colors (fg,bg)  ; 

) 

) 

// - add  a  title  to  a  window 

void  Window: :title (char  *ttl) 

[ 

setcursor(lf  +  (WIDTH  -  strlen(ttl)  -  1)  /  2,  tp) ; 
colors (fg,  bg) ; 
window_printf ("  %s  ",  ttl); 
cursor (col,  row) ; 

} 

// - write  text  body  to  a  window 

Windows  Window:  :operator«  (char  “btext) 

I 

cursor (0,  0) ; 
text  =  btext; 
if  (‘btext  ! =  NULL) 

•this  «  *btext++; 

while  (‘btext  !=  NULL  SS  row  <  HEIGHT-3) 

‘this  «  '\n'  «  *btext++; 

) 

// - write  a  line  of  text  to  a  window 

Windows  Window: :operator« (char  *ltext) 

{ 

while  (‘ltext  SS  col  <  WIDTH  -  2  SS  row  <  HEIGHT  -  2) 

‘this  <<  *ltext++; 
return  ‘this; 

) 


//A  C++  window  library 


♦include  <stddef.h> 
♦include  <string.h> 
♦include  <ctype.h> 
♦include  "window. h" 


// - write  a  character  to  a  window 

Windows  Window: :operator« (char  ch) 

{ 

cursor (col,  row); 
switch  (ch)  { 

(continued  on  page  141) 
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Listing  Two  ( Listing  continued,  text  begins  on  page  121.) 

case  ' \n' : 
clreol () ; 

if  (row  ==  HEIGHT-3) 
scroll  (1) ; 

else 

row++; 
case  ' \r' : 
col  =0; 
break? 
case  ' \b' : 
if  (col) 

— col; 
break; 
case  ' \t' : 
do 

‘this  «  '  ' ; 
while  (col  %  tabs) ; 
break; 
default : 

if  (col  ==  WIDTH  -  2) 

*this  «  ' \n' ; 
colors (fg, bg) ; 
window_putc (ch) ; 
col++; 

return  ‘this; 

} 

cursor (col,  row); 
return  *this; 

} 

//  -  position  the  window  cursor 

void  Window: : cursor (unsigned  x,  unsigned  y) 

{ 

if  (x  <  WIDTH-2  &&  y  <  HEIGHT-2)  { 
setcursor (lf+l+x,  tp+l+y) ; 
row  =  y; 
col  -  x; 

} 

) 

//  -  clear  a  window  to  all  blamks 

void  Window: :clear_window (void) 

cursor (0, 0)  ; 
clreos ()  ; 


//  —  clear  from  current  cursor  position  to  end  of  window 
void  Window: :clreos (void) 

{ 

unsigned  rw  =  row,  cl  =  col; 
clreol () ; 
col  “  0; 

while  (++row  <  HEIGHT-2) 
clreol () ; 
row  =  rw; 
col  =  cl; 


//  —  clear  from  current  cursor  position  to  end  of  line 
void  Window: : clreol (void) 

{ 

unsigned  cl  =  col; 
colors (fg, bg) ; 
while  (col  <  WIDTH-2) 

‘this  «  '  ' ; 
col  =  cl; 


// - page  anci  SCroll  through  the  text  file 

void  Window: : page (void) 

| 

int  c  =  0,  lines  =  0; 
char  “tx  =  text; 

hidecursor  () ; 

// - count  the  lines  of  text 

while  (*(tx  +  lines)  !=  NULL) 
lines++; 

while  (c  ! =  ESC)  { 
c  =  getkey () ; 
char  “htext  =  text; 
switch  (c)  ( 

case  UP: 

if  (tx  !=  text)  ( 

— tx; 

scroll (-1) ; 
unsigned  x,  y; 
cursor (&x,  &y) ; 
cursor (0,  0); 

‘this  «  *tx; 
cursor (x,  y) ; 

} 

continue; 
case  DN: 

if  (tx+HEIGHT-3  <  text+lines-1)  ( 
tx++; 

scroll  (1) ; 
unsigned  x,  y; 
cursor (&x,  &y) ; 
cursor (0,  HEIGHT-3); 

‘this  «  ‘ (tx  +  HEIGHT  -  3) ; 
cursor (x,  y) ; 

1 

continue; 
case  PGUP: 

tx  -=  HEIGHT-2; 
if  (tx  <  text) 
tx  =  text; 


Listing  Two  (Listing  continued,  text  begins  on  page  121.) 

break; 
case  PGDN: 

tx  +=  HEIGHT-2; 

if  (tx+HEIGHT-3  <  text+lines-1) 
break; 
case  END: 

tx  =  text+lines- (HEIGHT-2) ; 
if  (tx  >  text) 
break; 
case  HOME: 

tx  =  text; 
break; 
default : 

continue; 

) 

‘this  <<  tx; 
text  =  htext; 
clreos  ()  ; 

} 

unhidecursor () ; 

} 

// - scroll  a  window 

void  Window: :scroll (int  d) 

{ 

videoscroll (d,  tp+1,  If +1 ,  bt-1,  rt-1,  fg,  bg) ; 

) 

//  -  utility  notice  window 

Notice: : Notice (char  ‘text) 

:  ( (SCREENWIDTH-(strlen(text)+2) )  /  2,  11, 

( (SCREENWIDTH-(strlen(text)+2))  /  2)  +  strlen (text) +2, 

14,  NOTICEFG,  NOTICEBG) 

{ 

‘this  «  text  «  "\n  Any  key 
hidecursor () ; 
getkey () ; 
unhidecursor ()  ; 
hidewindow()  ; 


//  -  utility  error  window 

Error : :Error (char  ‘text) 

:  (  (SCREENWIDTH- (strlen (text) +2) )  /  2,  11, 

( (SCREENWIDTH- (strlen (text) +2))  /  2)  +  strlen (text) +2, 
14,  ERRORFG,  ERRORBG) 

{ 

‘this  «  text  «  "\n  Any  key 
hidecursor ( ) ; 
getkey  () ; 
unhidecursor () ; 
hidewindow () ; 


//  -  utility  yes/no  window 

YesNo: :YesNo(char  ‘text) 

:  (  (SCREENWIDTH- (strlen (text) +10) )  /  2,  11, 

((SCREENWIDTH- (strlen (text) +10))  /  2)  +  strlen  (text) +10, 
13,  YESNOFG,  YESNOBG) 

{ 

‘this  «  text  «  "?  (Y/N)  "; 
int  c  =  0; 
hidecursor () ; 

while  (tolower(c)  !=  'y'  &&  tolower(c)  !=  'n') 
c  =  getkey  () ; 
unhidecursor  () ; 
hidewindow () ; 

answer  =  tolower(c)  ==  'y'; 


End  Listing  Two 


Listing  Three 

/* - console. h - */ 

lifndef  CONSOLE 
♦define  CONSOLE 

♦include  <disp.h> 

//  -  cursor  and  keyboard  functions  (via  BIOS) 

void  hidecursor (void) ; 
void  unhidecursor (void) ; 
void  savecursor (void) ; 
void  restorecursor (void) ; 
int  getkey (void) ; 

//  -  key  values  returned  by  getkey () 

♦define  BELL  7 

♦define  ESC  27 

♦define  UP  200 

♦define  BS  203 

♦define  FWD  205 

♦define  DN  208 

♦define  HOME  199 

♦define  END  207 

♦define  PGUP  201 

♦define  PGDN  209 

♦define  attr(fg,bg)  ( (fg)  +  ( ( (bg) &7)  «4) ) 

//  -  video  functions  (defined  as  Zortech  C++  equivalents) 
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#define  initconsole{) 
tdefine  closeconsole {) 

♦define  savevideo (bf , t, l,b, r) 
tdefine  restorevideo (bf , t, l,b, r) 
tdefine  box (t, 1, b, r, fg, bg) 
tdefine  colors (fg,bg) 
tdefine  setcursor (x, y) 
tdefine  window_printf 
tdefine 
tdefine 


disp_open () 
disp_f lush () 

disp_peekbox(bf,t,  l,b,  r) 
disp_pokebox (bf ,  t,  1,  b,  r) 
disp_box(l, attr (fg,bg) , t, l,b, r) 


disp_setat.tr  (attr  (fg,  bg) ) 
disp_move (y,  x) 
disp_printf 
window_putc  disp_putc 

videoscroll (d,t,l,b, r, fg,bg)  \ 
disp_scroll (d, t, l,b, r, attr (fg, bg) ) ; 


tendif 


Listing  Five  (Listing  continued,  text  begins  on  page  121.) 

// - look.c 

//A  C++  program  to  demonstrate  the  use  of  the  window  library. 

//  This  program  lets  you  view  a  text  file 

♦include  <stdio.h> 

♦include  <string.h> 

♦include  <stream.hpp> 

♦include  <stdlib.h> 

♦include  "window. h" 

♦define  MAXLINES  200  //  maximum  number  of  text  lines 


End  Listing  Three 


Listing  Four 

/* - console. c - */ 

/*  PC-specific  console  functions  */ 


♦include  <dos.h> 
♦include  <conio.h> 
♦include  "console. h" 


/* - video  BIOs  (0x10) 

♦define  VIDEO  0x10 

tdefine  SETCURSORTYPE  1 
tdefine  SETCURSOR  2 

tdefine  READCURSOR  3 

tdefine  HIDECURSOR  0x20 


functions 


tdefine  SAVEDEPTH  20  /*  depth  to  which  cursors  are  saved  */ 


static  int  cursorpos [SAVEDEPTH] ; 
static  int  cursorshape [SAVEDEPTH] ; 
static  int  sd; 


union  REGS  rg; 

/*  -  Low-level  get  cursor  shape  and  position  -  */ 

static  void  getcursor (void) 

{ 

rg.h.ah  =  READCURSOR; 

rg.h.bh  =  0; 

int86 (VIDEO, 4rg, 4rg) ; 

) 


/*  -  Save  the  current  cursor  configuration  -  */ 

void  savecursor (void) 

( 

getcursor () ; 

if  (sd  <  SAVEDEPTH)  [ 

cursorshape [sd]  =  rg.x.cx; 
cursorpos [sd++j  =  rg.x.dx; 

) 


/*  -  Restore  the  saved  cursor  configuration  -  */ 

void  restorecursor (void) 
f 

if  (sd)  ( 

rg.h.ah  =  SETCURSOR; 
rg.h.bh  =  0; 

rg.x.dx  =  cursorpos [ — sd] ; 
int86 (VIDEO, 4rg, 4rg) ; 
rg.h.ah  =  SETCURSORTYPE; 
rg.x.cx  =  cursorshape [sd] ; 
int86 (VIDEO, 4rg, 4rg) ; 


static  char  *wtext [MAXLINES+1] ;  //  pointers  to  text  lines 

II  -  taken  from  BS;  handles  all  free  store  (heap)  exhaustions 

void  out_of_store (void) ; 
typedef  void  (*PF)(); 
extern  PF  set_new_handler (PF) ; 

main (int  argc,  char  *argv[]) 

{ 

set_new_handler (4out_of_store) ; 
if  (argc  >  1)  ( 

//  -  open  a  full-screen  window 

Window  wnd(0, 0,79, 24, CYAN, BLUE); 
char  ttl [80] ; 

//  -  put  the  file  name  in  the  title 

sprintf(ttl,  "Viewing  %s",  argv(l]); 
wnd.title(ttl) ; 
filebuf  buf; 

if  (buf .open (argv[l] ,  input))  { 
istream  inf ile (4buf ) ; 
int  t  =  0; 

//  —  read  the  file  and  load  the  pointer  array 
char  bf [120] ,  *cp  =  bf; 

while  (t  <  MAXLINES  &&  iinfile.eof () )  ( 

infile. get (*cp) ; 
if  ( *cp  ! =  ' \r' )  ( 

if  (*cp  ==  ' \n' )  ( 

*cp  =  ' \0' ; 

wtext[t]  =  new  char  [strlen (bf ) +1 ] ; 
strcpy(wtext[t++] ,  bf); 
cp  =  bf; 

) 

else 

cp++; 

} 

1 

wtextft]  =  NULL; 

II  -  write  all  the  text  to  the  window 

wnd  «  wtext; 

II  -  a  YesNo  window 

YesNo  yn ("Continue") ; 
if  (yn. answer) 
wnd . page ( ) ; 

II - a  Notice  window 

Notice  nt("All  done."); 

} 

else 

II  -  error  windows 

Error  err ("No  such  file"); 


Error  err ("No 


file  name  specified"); 


//  -  the  BS  free-store  exhaustion  handler 

void  out_of_store (void) 

( 

cerr  «  "operator  new  failed:  out  of  store\n"; 
exit (1) ; 

1  End  Listings 


/* - Hide  the  cursor - */ 

void  hidecursor (void) 

{ 

getcursor () ; 
rg.h.ch  1=  HIDECURSOR; 
rg.h.ah  =  SETCURSORTYPE; 
int86 (VIDEO, &rg, &rg) ; 

) 

I* - Unhide  the  cursor - *1 

void  unhidecursor (void) 

{ 

getcursor {) ; 
rg.h.ch  4=  "HIDECURSOR; 
rg.h.ah  =  SETCURSORTYPE; 
int86 (VIDEO, &rg,&rg) ; 

) 

/* - Read  a  keystroke - */ 

int  getkey(void) 

I 

rg.h.ah  =  0; 
int86 (0x16, &rg, &rg) ; 
if  (rg.h.al  ==  0) 

return  (rg.h.ah  !  0x80)  &  255; 
return  rg.h.al  4  255; 


End  Listing  Four 
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Listing  One  (Text  begins  on  page  128.) 

Listing  Two 

'  ) 

{  PrinByte  } 

(  ASCIIChart  ) 

1  I 

{  Byte-value  print  object  for  object  extendability  demo  } 

(  Object  Extendability  demo  program:  Prints  an  ASCII  chart  ) 

{  by  Jeff  Duntemann  } 

*  / 

(  Note:  This  program  contains  control  codes  specific  to  ) 

{  Turbo  Pascal  V5.5  } 

(  the  HP  Laserjet  Series  II  Printer.  Use  with  ) 

{  Last  modified  5/11/89  } 

i - 1 

(  other  printers  may  be  hazardous  to  your  aesthetic  ) 

(  sensibilities.  ) 

i  / 

{  Jeff  Duntemann  ) 

UNIT  PrinByte; 

{  Turbo  Pascal  V5.5  ) 

[  Last  modified  6/8/89  ) 

INTERFACE 

I - 1 

USES  Printer; 

, - 1 

i - 1 

[  Run  this  on  an  HP  Laser jet  Series  II,  and  you'll  get  an  ( 

(  The  PrintByte  object  "knows"  how  to  print  its  byte  value  in  ( 

(  ASCII  chart  including  all  the  weird  characters  for  which  the  ) 

{  four  different  formats:  As  decimal  quantity,  hex  quantity,  } 

(  Series  II  has  characters  in  its  built-in  fonts.  If  you  have  ) 

{  binary  quantity,  and  extended  ASCII  symbol.  It  takes  the  } 

(  some  other  printer,  you  need  only  modify  the  PrintSymbol  ) 

{  cautious  path  in  printing  symbols,  as  prints  spaces  for  all  } 

{  method  to  use  whatever  mechanism  your  printer  has  to  print  ) 

{  of  the  "control"  characters  0-31,  "rubout"  ($7F) ,  and  char  } 

(  the  weird  characters.  By  modifying  PrintSymbol  you  are  ) 

{  $FF.  If  your  printer  has  some  means  of  printing  smiley  ) 

(  extending  the  object  PrintByte  defined  in  unit  PRINBYTE. PAS,  ) 

(  faces  and  all  that  other  folderol  in  the  low  32  characters,  } 

(  WITHOUT  needing  full  source  code  to  PRINBYTE. PAS.  ) 

{  override  the  PrintSymbol  method  with  a  new  method  that  uses  } 
j  whatever  mechanism  your  printers  offers  to  print  those  } 

{  characters  "spaced  out"  by  this  implementation  of  the  } 

f  PrintSymbol  method.  } 

, - 1 

1 - ) 

PROGRAM  ASCIIChart; 

TYPE 

PrintByte  =  OBJECT 

USES  Printer,  {  Standard  Borland  unit  } 

BV  :  Byte;  {  Byte  value  } 

FUNCTION  DontPrint (Shouldl  :  Byte)  :  Boolean; 

PrinByte;  {  PRINBYTE. PAS  from  DDJ  for  September  1989  } 

PROCEDURE  PrintDecimal; 

PROCEDURE  PrintHex; 

CONST 

PROCEDURE  PrintBinary; 

Title  =  'THE  EXTENDED  ASCII  CODE  AND  SYMBOL  SET'; 

PROCEDURE  PrintSymbol; 

Header  =  '  Dec  Hex  Binary  Symbol  Dec  Hex  Binary  Symbol'; 

END; 

BarChar  =  Chr (205)  ; 

ColChar .  =  Chr (177) ; 

FormFeed  =  Chr (12); 

IMPLEMENTATION 

TYPE 

(  Returns  True  for  any  code  that  CANNOT  be  printed  verbatim  ) 

FUNCTION  PrintByte. DontPrint {Shouldl  :  Byte)  :  Boolean; 

(  This  is  a  child  object  of  PrintByte,  defined  in  separate  file  ) 

(  PRINBYTE. PAS.  Remember:  PrintByteHP  inherits  EVERYTHING  ) 

CONST 

(  defined  in  PrintByte.  EVERYTHING!  The  only  difference  is  ) 

NotThese  -  [0 .. 31, 127,255] ;  f  Unprintable  codes  ) 

(  that  the  PrintSymbol  method  is  overridden  by  an  HP  Series  II  ) 

(  specific  symbol-print  method.  Everything  else  is  EXACTLY  as  ) 

BEGIN 

(  it  is  defined  in  PrintByte.  ) 

IF  Shouldl  IN  NotThese  THEN  DontPrint  :=  True 

, - - 

ELSE  DontPrint  :=  False; 

END; 

PrintByteHP  =  OBJECT (PrintByte) 

PROCEDURE  PrintByte .PrintDecimal; 

PROCEDURE  PrintSymbol 

END; 

VAR 

BEGIN 

I,J,K  :  Integer; 

Write (LST, BV: 3) ; 

Chari, Char2  :  PrintByteHP;  (  Instances  of  PrintByteHP  object  type  } 

END; 

I - ) 

[  This  method  overrides  the  PrintSymbol  method  defined  in  the  ) 

PROCEDURE  PrintByte. PrintHex; 

(  PrintByte  parent  object  defined  in  PRINCHAR.PAS:  ) 

CONST 

HexDigits  :  ARRAY [0.. 15]  OF  Char  =  ' 0123456789ABCDEF' ; 

PROCEDURE  PrintByteHP . PrintSymbol ; 

BEGIN 

BEGIN 

Write (LST, HexDigits [BV  SHR  4 ], HexDigits [BV  AND  $0F] ) ; 

IF  DontPrint (BV)  THEN  (  If  DontPrint  method  says  so,  ) 

END; 

Write (LST, Chr (27) ,' &plX' , Chr (BV) )  {  use  "transparent  data  print"  ) 

ELSE  (  feature  to  print  weird  chars  } 

Write (LST, Chr (BV) ) ;  {  Otherwise,  just  print  'em...  ) 

END; 

PROCEDURE  PrintByte .PrintBinary; 

VAR 

Index  :  Integer; 

PROCEDURE  Spaces (NumberOfSpaces  :  Integer); 

BEGIN 

VAR 

FOR  Index  :=  7  DOWNTO  0  DO 

Index  :  Integer; 

IF  Odd (BV  SHR  Index)  THEN  Write (LST, ' 1' ) 

ELSE  Write (LST,' O'); 

BEGIN 

END; 

FOR  Index  :=  1  TO  NumberOfSpaces  DO 

Write (LST, '  ') 

END; 

PROCEDURE  NewPage; 

PROCEDURE  PrintByte. PrintSymbol; 

VAR 

BEGIN 

Index  :  Integer; 

IF  DontPrint (BV)  THEN 

Write (LST,'  ') 

BEGIN 

ELSE 

Write (LST, FormFeed) ; 

Write (LST, Chr(BV)); 

END; 

END; 

END. 

PROCEDURE  PrintHeader; 

End  listing  One 

(continued  on  page  149) 

146 


Dr.  Dobb’s Journal,  September  1989 

663 


STRUCTURED  PROGRAMMING 


Listing  Two  (Listing  continued ,  text  begins  on  page  128.) 

VAR 

Index  :  Integer; 

BEGIN 

Spaces (10) ; 

Writeln (LST,  Header) ; 

Spaces (10) ; 

FOR  Index  :=  1  TO  60  DO 
Write (LST,  BarChar) ; 

Writeln (LST) ; 

END; 


{ - ) 

{  Nothing  more  elaborate  here  than  printing  the  byte  out  as  a  ) 
(  decimal  number,  a  hex  number,  a  binary  number,  and  a  symbol.  ) 


{  The  four  "Target."  calls  are  method  calls  to  the  object  ) 
(  passed  to  PrintChar  in  the  Target  parameter.  ) 
I - } 


PROCEDURE  PrintChar (Target  :  PrintByteHP) ; 

BEGIN 

Spaces (3) ; 

Target .PrintDecimal; 

Spaces  (3) ; 

Target  .Prir.tHex; 

Spaces (3) ; 

Target . PrintBinary; 

Spaces (3) ; 

Target .PrintSymbol; 

Spaces (4) ; 

END; 


< — : — : - ) 

(  This  simply  sets  the  HP  Series  II  to  its  PC  symbol  set.  ) 

I - 1 


PROCEDURE  InitHP; 

BEGIN 

Write (LST, Chr (27), ' (10U');  (  Select  symbol  set  10U  ) 

END; 


BEGIN 

InitHP;  { 

Spaces  (10);  { 

Writeln (LST, Title) ;  ( 

Writeln (LST) ;  ( 

FOR  I  :=  0  TO  3  DO  ( 

BEGIN 

FOR  K  :=  1  TO  3  DO  Writeln (LST) 
PrintHeader; 

FOR  J  :=  0  TO  31  DO 
BEGIN 

Chari .BV  :=  (1*64) +J;  Char2 
Spaces (10) ; 

PrintChar (Chari) ; 

Write (LST, CoiChar) ; 
PrintChar (Char2) ; 

Writeln (LST) ; 

END; 

NewPage; 

END; 

END. 


Select  the  PC  symbol  set  ) 

Output  10  spaces  } 

Print  out  the  title  string  ) 

Space  down  one  line  ) 

256  characters  takes  4  pages  ) 

{  Space  down  3  lines  ) 

(  Print  the  chart  header  ) 
i  Do  2  columns  of  32  chars.  ) 

.BV  :=  (1*64) +J+32; 

Print  the  left  column  character  ) 
Print  the  column  separator  ) 

Print  the  right  column  character  ) 


(  Issue  a  form  feed  to  printer  ) 


TYPE 

PrintByte 


=  OBJECT 


3V  :  Byte;  {  Byte  value 
FUNCTION  DontPrint (Shouldl 
PROCEDURE  PrintDecimal; 
PROCEDURE  PrintHex; 
PROCEDURE  PrintBinary; 
PROCEDURE  PrintSymbol; 

END; 


Byte) 


Boolean; 


IMPLEMENTATION 


(  Returns  True  for  any  code  that  CANNOT  be  printed  verbatim  ) 
FUNCTION  PrintByte. DontPrint (Shouldl  :  Byte)  :  Boolean; 

CONST 

NotThese  =  [0.  .31, 127,255] ;  (  Unprintable  codes  ) 

BEGIN 

IF  Shouldl  IN  NotThese  THEN  DontPrint  :=  True 
ELSE  DontPrint  :=  False; 

END; 


PROCEDURE  PrintByte . PrintDecimal ; 
BEGIN 

Write (LST, Self .BV: 3) ; 

END; 


PROCEDURE  PrintByte. PrintHex; 

CONST 

HexDigits  :  ARRAY[0..15]  OF  Char  =  ' 0123456789ABCDEF' ; 
BEGIN 

WITH  Self  DO 

Write (LST, HexDigits (BV  SHR  4 ], HexDigits (BV  AND  $0F] ) ; 

END; 


PROCEDURE  PrintByte. PrintBinary ; 

VAR 

Index  :  Integer; 

BEGIN 

WITH  Self  DO 

FOR  Index  :=  7  DOWNTO  0  DO 

IF  Odd (BV  SHR  Index)  THEN  Write (LST, ' 1' ) 
ELSE  Write (LST,' O'); 

END; 


PROCEDURE  PrintByte. PrintSymbol; 
BEGIN 

WITH  Self  DO 

IF  DontPrint (BV)  THEN 
Write (LST, '  ') 

ELSE 

Write (LST, Chr (BV) ) ; 

END; 


End  Listing  Two 

Listing  Three 


i - - 1 

f  PrinByte  ) 

t  > 

{  Byte-value  print  object  for  object  extendibility  demo  ) 
<  ) 

f  by  Jeff  Duntemann  ) 

1  QuickPascal  VI. 0  ) 

f  Last  modified  6/6/89  ) 

{ - j 


UNIT  PrinByte; 
INTERFACE 

USES  Printer; 


END. 


End  Listing  Three 

Listing  Four 


(  ASCIIChart  ) 
(  ) 
(  Object  Extendability  demo  program:  Prints  an  ASCII  chart  ) 

I  ) 

1  Note:  This  program  contains  control  codes  specific  to  ) 
{  the  HP  Laser jet  Series  II  Printer.  Use  with  ) 
I  other  printers  may  be  hazardous  to  your  aesthetic  ) 
(  sensibilities.  ) 

I  ) 

(  Jeff  Duntemann  ) 
f  QuickPascal  VI. 0  ) 
(  Last  modified  6/6/89  ) 

I - ) 


{ - - - - - ) 

(  The  PrintByte  object  "knows"  how  to  print  its  byte  value  in  ) 
(  four  different  formats:  As  decimal  quantity,  hex  quantity,  ) 
(  binary  quantity,  and  extended  ASCII  symbol.  It  takes  the  ) 
{  cautious  path  in  printing  symbols,  as  prints  spaces  for  all  ) 
{  of  the  "control"  characters  0-31,  "rubout"  ($7F),  and  char  ) 
(  $FF.  If  your  printer  has  some  means  of  printing  smiley  ( 
{  faces  and  all  that  other  folderol  in  the  low  32  characters,  ) 
1  override  the  PrintSymbol  method  with  a  new  method  that  uses  ) 
(  whatever  mechanism  your  printers  offers  to  print  those  ) 
(  characters  "spaced  out"  by  this  implementation  of  the  ) 
{  PrintSymbol  method.  } 
1 - 1 


, - 1 

(  Run  this  on  an  HP  Laser jet  Series  II,  and  you'll  get  an  ( 

(  ASCII  chart  including  all  the  weird  characters  for  which  the  ) 

(  Series  II  has  characters  in  its  built-in  fonts.  If  you  have  ) 
i  some  other  printer,  you  need  only  modify  the  PrintSymbol  ) 

(  method  to  use  whatever  mechanism  your  printer  has  to  print  ) 

(  the  weird  characters.  By  modifying  PrintSymbol  you  are  ) 

(  extending  the  object  PrintByte  defined  in  unit  PRINBYTE. PAS,  ) 

(  WITHOUT  needing  full  source  code  to  PRINBYTE. PAS.  } 

I - ) 

(continued  on  page  150) 
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Listing  Four  (Listing  continued,  text  begins  on  page  128.) 

PROGRAM  ASCIIChart; 


USES  Printer,  (  Standard  Borland  unit  } 

PrinByte;  f  PRINBYTE .PAS  from  DDJ  for  September  1989  } 


CONST 

Title 

Header 

BarChar 

ColChar 

FormFeed 


'THE  EXTENDED  ASCII  CODE  AND  SYMBOL  SET'; 

'  Dec  Hex  Binary  Symbol  Dec  Hex 
Chr (205) ; 

Chr (177) ; 

Chr (12) ; 


Binary  Symbol'; 


TYPE 


1 - ) 

{  This  is  a  child  object  of  PrintByte,  defined  in  separate  file  } 
{  PRINBYTE. PAS.  Remember:  PrintByteHP  inherits  EVERYTHING  } 
[  defined  in  PrintByte.  EVERYTHING!  The  only  difference  is  ) 
{  that  the  PrintSymbol  method  is  overridden  by  an  HP  Series  II  } 
{  specific  symbol-print  method.  Everything  else  is  EXACTLY  as  } 
{  it  is  defined  in  PrintByte.  } 
1 - ) 


PrintByteHP  =  OBJECT (PrintByte) 

PROCEDURE  PrintSymbol;  OVERRIDE 
END; 


VAR 
I,  J,  K 

Chari, Char2 


Integer; 

PrintByteHP;  {  Instances  of  PrintByteHP  object  type  } 


PROCEDURE  Spaces (NumberOf Spaces  :  Integer); 
VAR 

Index  :  Integer; 

BEGIN 

FOR  Index  :=  1  TO  NumberOf Spaces  DO 
Write (LST, '  ') 

END; 


PROCEDURE  NewPage; 

VAR 

Index  :  Integer; 
BEGIN 

Write (LST, FormFeed) ; 
END; 


PROCEDURE  PrintHeader; 

VAR 

Index  :  Integer; 

BEGIN 

Spaces  (10) ; 

Writeln (LST, Header) ; 
Spaces (10) ; 

FOR  Index  :=  1  TO  60  DO 
Write (LST, BarChar) ; 
Writeln (LST) ; 

END; 


1 - > 

{  This  method  overrides  the  PrintSymbol  method  defined  in  the  } 
{  PrintByte  parent  object  defined  in  PRINCHAR.PAS:  ) 
( - ) 


PROCEDURE  PrintByteHP. PrintSymbol; 


( - > 

(  Nothing  more  elaborate  here  than  printing  the  byte  out  as  a  } 
{  decimal  number,  a  hex  number,  a  binary  number,  and  a  symbol.  ) 
(  The  four  "Target."  calls  are  method  calls  to  the  object  ) 
{  passed  to  PrintChar  in  the  Target  parameter.  ) 
( - ) 


BEGIN 

WITH  Self  DO 

IF  Self .DontPrint (BV)  THEN  {  If  DontPrint  method  says  so,  ) 

Write(LST,Chr (27) ,  '&plX' ,Chr(BV) )  (  use  "transparent  data  print"  ) 

ELSE  (  feature  to  print  weird  chars  ) 

Write (LST, Chr (BV) ) ;  {  Otherwise,  just  print  'em...  ) 

END; 


PROCEDURE  PrintChar (Target  :  PrintByteHP); 

BEGIN 

Spaces  (3) ; 

Target .PrintDecimal; 

Spaces  (3) ; 

Target .PrintHex; 

Spaces  (3) ; 

Target .PrintBinary; 

Spaces  (3) ; 

Target .PrintSymbol; 

Spaces  (4)  ; 

END; 


, - > 

(  This  simply  sets  the  HP  Series  II  to  its  PC  symbol  set.  ) 

1 - ) 


PROCEDURE  InitHP; 

BEGIN 

Write (LST, Chr (27) ,' ( 10U' );  (  Select  symbol  set  10U  ) 

END; 


BEGIN 

InitHP;  ( 

New (Chari);  New(Char2);  ( 

Spaces (10);  ( 

Writeln (LST, Title) ;  ( 

Writeln (LST) ;  I 

FOR  I  :=  0  TO  3  DO  I 

BEGIN 


FOR  K  :=  1  TO  3  DO  Writeln (LST) ; 
PrintHeader; 

FOR  J  :=  0  TO  31  DO 
BEGIN 

Chari. BV  :=  (I*64)+J;  Char2. 
Spaces (10) ; 

PrintChar (Chari)  ;  ( 

Write (LST, ColChar) ;  { 

PrintChar (Char2) ;  ( 

Writeln (LST) ; 

END; 

NewPage;  { 

END; 

END. 


Select  the  PC  symbol  set  } 

Create  objects  on  the  heap  } 
Output  10  spaces  ) 

Print  out  the  title  string  ) 

Space  down  one  line  ) 

256  characters  takes  4  pages  ) 

(  Space  down  3  lines  ) 

{  Print  the  chart  header  ) 

|  Do  2  columns  of  32  chars.  ) 

BV  :=  (1*64) +J+32; 

Print  the  left  column  character  ) 
Print  the  column  separator  } 

Print  the  right  column  character 


Issue  a  form  feed  to  printer  ) 


) 


End  Listings 
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OF  INTEREST 


ParcPlace  Systems  has  expanded  be¬ 
yond  the  world  of  Smalltalk  with  the 
introduction  of  Objectworks  for  C++, 
the  first  software  development  system, 
company  president  Adele  Goldberg 
claims,  that  supports  AT&T’s  C++  2.0 
specification.  Objectworks  provides  in¬ 
cremental  compiling  and  linking,  inter¬ 
active  source-level  debugging,  and 
source-code/class  browsing.  Included 
with  Objectworks  is  the  AT&T  C++  2.0. 

The  ParcPlace  C++  offering  lets  you 
import  existing  C++  source  code  or 
export  it  to  other  systems.  The  built-in 
editor  allows  you  to  cross-reference 
dynamically,  although  the  system  lets 
you  use  an  editor  of  your  choice. 

Initially,  Objectworks  C++  (which,  in¬ 
cidentally,  was  written  in  Smalltalk-80) 
will  be  available  only  on  the  Sun-3 
system.  However,  ParcPlace  spokesper¬ 
son  Doug  Pollack  did  say  that  other 
platforms,  including  DOS  and  OS/2, 
would  be  supported  in  the  future.  Pol¬ 
lack  said  that  they  would  be  “tracking" 
the  development  of  Microsoft’s  OS/2  for 
the  80386.  Interestingly  enough,  one  deci¬ 
sion  ParcPlace  must  make  before  intro¬ 
ducing  a  DOS  or  OS/2  version  of  Ob¬ 
jectworks  C++  is  which  C  compiler  to 
support  (Sun  provides  its  own  C  com¬ 
piler)  because,  as  Pollack  indicated, 
the  company  does  not  want  to  support 
every  C  compiler  in  the  PC  marketplace. 

One  area  of  opportunity  for  DDJ read¬ 
ers  is  in  the  realm  of  class  libraries  and 
other  support  tools.  “A  good  object- 
oriented  product  is  not  the  language 
alone,”  Goldberg  told  DDJ.  “It  includes 
a  class  library  and  support  tools.”  In 
short,  ParcPlace  is  eager  to  talk  to  all 
third-party  developers  who  want  to  built 
C++  support  tools  for  Objectworks. 
Reader  Service  No.  22. 

ParcPlace  Systems 
1550  Plymouth  Street 
Mountain  View,  CA  94043 
415-691-6700 


AT&T  has  recently  released  its  long- 
awaited  C++  2.0  specification,  which 
includes  all  of  the  major  features  that 
Bjorne  Stroustrup,  the  author  of  C++, 
has  developed  to  date.  AT&T’s  Mike 
DeFazio,  director  of  Unix  system  soft¬ 
ware,  called  C++  2.0  “an  industrial 
strength  release  of  C++”  that  has  many 
new  features  as  well  as  several  refine¬ 
ments.  The  2.0  specification  was  imme¬ 
diately  lauded  and  supported  by  major 
vendors  including  Apple  Computer, 
Glockenspiel,  Hewlett  Packard,  HCR 
Corp.,  Onotologic,  ParcPlace  Systems, 
and  Sun  Microsystems. 

Among  the  new  features  that  C++  2.0 
now  supports  are  multiple  inheritance, 
whereby  a  child  object  can  inherit  the 
properties  of  more  than  one  parent; 
typesafe  linkage;  default  member-wise 
assignment  and  initialization  of  classes; 
and  the  ability  of  each  class  to  define 
its  own  “new”  and  “delete”  operators. 

Refinements  to  the  language  include 
separation  of  specialized  task  and  com¬ 
plex  libraries,  enhancement  and  reengi¬ 
neering  of  the  task  library,  reimple¬ 
mentation  of  the  stream  I/O  portion  of 
libc.a,  and  reengineering  of  the  C++ 
parsing  mechanism. 

The  2.0  spec  consists  of  new  docu¬ 
mentation,  release  notes,  a  product  ref¬ 
erence  manual,  a  library  manual,  and 
selected  C++  readings.  The  2.0  language 
system  itself  is  available  in  source  code 
format  on  magnetic  tape.  To  order  the 
2.0  documentation,  phone  AT&T  Cus¬ 
tomer  Information  Center  at  1-800-432- 
6600  and  ask  for  the  C++  Product  Ref¬ 
erence  Manual  #307-146.  Although  the 
price  wasn’t  available  at  this  writing, 
an  AT&T  spokesman  told  DDJ  that  it 
should  be  about  $20. 

Licensing  for  the  new  2.0  spec  isn’t 
that  cheap,  however.  If  you  already 
have  a  license  for  the  current  1.2  spec, 
the  2.0  spec  will  cost  you  $10,000. 
However,  if  you  don’t  already  have  a 
license,  the  2.0  spec  will  cost  you 
$20,000.  For  licensing  information,  call 
1-800-828-UNIX.  Reader  Service  No.  20. 
AT&T 

One  Speedwell  Ave. 

Morristown,  NJ  07960 
800-247-1212 

Prentice  Hall  has  announced  several 
new  titles,  including  C  Programming 
Language,  ANSI  C  Version,  2nd  Edi¬ 
tion ,  by  Brian  W.  Kernighan  and  Den¬ 
nis  M.  Ritchie  of  AT&T.  Prentice  Hall 
is  publishing  the  ANSI  version  for  this 
best-seller  to  coincide  with  the  final 
ANSI  standardization  on  the  C  program¬ 
ming  language.  Look  for  the  red  ANSI 
stamp  on  the  new  cover.  This  refer¬ 
ence  provides  the  finalized  ANSI  C  stan¬ 
dard.  The  book  covers  functions  and 


program  structure,  pointers  and  arrays, 
input  and  output,  and  application  port¬ 
ability.  ISBN  013-110362-8.  $30. 

Also  released  is  Programming  in  C++, 
by  Stephen  Dewhurst  of  AT&T  and 
Kathy  Stark  of  Sun  Microsystems,  two 
of  the  designers  on  the  C++  compiler 
design  team  at  AT&T.  The  guide  dis¬ 
cusses  data  types  and  operations,  pro¬ 
cedural  programming,  classes,  data  ab¬ 
stractions  inheritance,  object-oriented 
programming,  and  storage  management, 
and  includes  a  section  devoted  to  the 
design  and  use  of  libraries  and  an  ap¬ 
pendix  of  solved  exercises.  And  it  of¬ 
fers  the  first  look  at  the  2.0  release  of 
C++.  Paper:  ISBN  013-723156-3-  $22. 

The  X/Window  System:  Programming 
and  Applications  with  X,  by  Douglas 
A.  Young  (Hewlett-Packard),  is  a  guide 
to  the  X/Window  system  for  software 
engineers,  applications  programmers, 
and  developers  using  X.  It  focuses  on 
using  the  X  toolkit  to  create  software 
applications  within  the  X/Window  sys¬ 
tem,  and  discusses  the  use  of  widgets 
(prebuilt  user  interfaces  like  menus  and 
command  buttons)  and  intrinsics  (pieces 
of  code  that  enable  a  programmer  to 
build  new  widgets  out  of  existing  ones) 
to  create  graphics  user  interfaces.  The 
book  uses  a  series  of  progressive  ex¬ 
amples  to  introduce  key  concepts  of 
X,  and  presents  30  programs.  Software 
in  the  book  is  available  free  on  Arpanet. 
Paper:  ISBN  013-972167-3.  $25.95. 
Reader  Service  No.  24. 

Prentice  Hall 

College  Sales  and  Marketing 
Prentice  Hall  Building 
Englewood  Cliffs,  NJ  07632 
201-592-2000 

The  Delta  Logic  Division  of  Poqet 
Computer  Corp.  announces  Entry¬ 
way,  an  object-oriented  application 
development  product  for  the  IBM  PS/2 
and  PC  environment.  Entryway  allows 
both  information  systems  professionals 
and  business  managers  to  rapidly  build 
stand-alone  and  coordinated  business 
applications. 

According  to  John  Hiles,  vice  presi¬ 
dent  of  Delta  Logic,  “As  more  organi¬ 
zations  integrate  end-user  computing 
with  their  information  systems,  data- 
processing  professionals  and  end-user 
departments  will  become  increasingly 
involved  in  personal  computer  software 
development.  With  Entryway,  applica¬ 
tion  development  more  closely  resem¬ 
bles  the  writing  of  a  letter  or  memo 
on  a  word  processor.  The  application’s 
background  of  text  or  diagrams,  such 
as  an  office  procedure  flow  chart,  is 
entered  just  as  if  it  were  a  letter.  Then 
the  active,  computer-driven  application 
(continued  on  page  158) 
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(continued  from  page  152) 
components  are  created  or  specified 
in  objects  that  are  placed  on  the  text 
background.  This  ‘first  draft’  represents 
a  working  prototype  that  can  be  re¬ 
fined,  expanded,  and  packaged  for 
distribution  in  a  series  of  interactive 
Entryway  sessions.” 

Entryway’s  development  features  in¬ 
clude  an  object-oriented,  interactive  de¬ 
velopment  environment;  a  script  lan¬ 
guage  with  more  than  200  statements; 
debugging  and  regression  test  facilities 
and  forms  generation.  Included  are  sev¬ 
eral  user  interface  features  —  a  hyper¬ 
text  facility,  menu  generation  and  forms 
management  systems,  and  text  entry 
fields  —  compatible  with  Common  User 
Access  (CUA),  IBM’s  developing  stan¬ 
dard  for  its  Systems  Application  Ar¬ 
chitecture  (SAA). 

The  package  includes  a  WYSIWYG 
full-page  report  writer,  full  support  for 
adding  user-defined  objects,  script-lan¬ 
guage  commands,  and  time-oriented 
facilities.  Entryway  runs  on  the  installed 
base  of  DOS  personal  computers.  Delta 
Logic  Division  can  add  user  objects  for 
the  LAN  or  host  connectivity  option. 
The  cost  is  $795  for  the  development 
version  and  $250  for  the  run-time  pack¬ 
age.  Reader  Service  No.  25. 

Delta  Logic  Division 
550  Hartnell,  Ste.  B 
Monterey,  CA  93940 
408-373-8688 

The  C  Users’  Group  Directory  of  User- 
Supported  C  Source  Code,  Vol.  II,  has 
been  released  by  R&D  Publications 
Inc.  The  Directory  contains  informa¬ 
tion  about  code  in  The  C  Users’  Group 
Library,  a  repository  of  public  domain 
and  user-supported  C  source  code.  The 
C  Users’  Group  focuses  on  source  code 
useful  to  experienced  programmers, 
rather  than  on  end-user  applications. 

Vol.  II,  edited  by  Robert  Ward  and 
Kenji  Hino,  includes  file  by  file  descrip¬ 
tions  for  Library  disk  volumes  200  - 
249,  a  comprehensive  index,  and  arti¬ 
cles  that  describe  some  significant  disk 
volumes.  It  also  catalogs  a  68000  C 
compiler,  portable  utilities,  a  file  main¬ 
tenance  package,  MS-DOS  implemen¬ 
tations  of  several  Unix  utilities,  Small 
C  utilities,  and  several  graphics  pack¬ 
ages.  Volume  I  is  also  available,  and 
both  sell  for  $10.  Reader  service  No.  21. 
The  C  Users’  Group 
2120  W.  25th  St.,  Ste.  B 
Lawrence,  KS  66047 
913-841-1631 
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More  Senselessness  with  Jelly  Beans 

Nineteen  ninety-two  and  the  unification  of  the  European  market  will  soon  be  here,  bringing 
in  a  storm  of  problems  whose  solutions  will  require  wetware,  because  they  will  involve 
semantics.  The  story  of  the  computer  program  that  translated:  “The  spirit  is  willing  but  the 
flesh  is  weak”  into  Russian  and  back  to  English,  ending  up  with  “The  vodka  is  fine,  but  the  meat 
is  rotten,”  is  probably  apocryphal  but  the  problem  it  exemplifies  is  real. 

Some  semantic  confusions  might  be  acceptable.  Motorola  chipset  fans  would  probably  not  mind 
if  a  mention  of  the  orthogonality  of  the  680x0  instruction  set  was  rendered  with  the  sense  “Motorola 
has  the  right  angle.”  But  think  how  confusing  technical  documentation  would  become  if  “number” 
was  translated  as  though  it  was  the  comparative  form  of  “numb;”  i.e.,  “senseless.”  Then  every 
reference  to  number  would  become  more  senseless. 

Sometimes  dealing  with  numbers  makes  people  more  senseless.  In  a  recent  column,  Jeff 
Duntemann  told  of  a  chain-smoking  nuclear  power  opponent  who  wanted  to  see  “the  inventor  of 
radiation”  jailed.  I’d  like  to  offer  a  defense  of  the  smoker,  to  make  her  position  a  little  less  —  or 
more —  senseless. 

The  idea  is  that  there  is  more  to  risk  assessment  than  comparing  probabilities.  There  has  been 
some  research  whose  results  suggest  that  when  people  assess  risks,  they  consider  not  only  the 
magnitude  of  the  risk  but  also  other  factors  affecting  its  acceptability.  So  even  if  the  chain-smoker 
understood  the  relative  safety  records  of  the  nuclear  power  and  the  tobacco  industries  (which  I 
admit  is  questionable),  she  could  well  have  regarded  the  smoking  risk  as  more  acceptable  on  the 
grounds  that  it  is  taken  willingly,  not  imposed  from  without.  Even  that  position  can  be  questioned, 
but  it  shouldn’t  be  dismissed  as  mere  innumeracy,  which  I’m  afraid  too  many  supporters  of  nuclear 
power  do.  (I’m  not  talking  about  Jeff,  though.) 

And  what  is  the  probability  of  deliberate  sabotage  of  a  nuclear  power  plant?  I  submit  that  a 
sufficiently  determined  terrorist  organization  could  locate  key  employees  and  put  sufficient 
pressure  on  them  to  achieve  any  desired  degree  of  damage.  That  fact  doesn’t  mean  a  whole  lot, 
given  that  terrorists  could  just  as  easily  sabotage  baby  food,  drinking  water,  airplanes,  or  anything 
else.  But  it  does  put  the  smug,  so-precise  nuclear  safety  record  figures  in  a  gritty  real-world 
perspective.  The  risks  of  nuclear  power  would  appear,  unfortunately,  to  involve  the  psychology 
of  the  terrorist  mind. 

The  point  is:  Numbers  have  a  semantics  as  well  as  a  syntax. 

And  they  have  a  pragmatics.  Often  we  want  to  use  numbers  for  a  purpose.  Usually  they  can  be 
made  to  cooperate.  The  latest  IEEE  salary  survey  figures  showing  San  Francisco-area  engineers 
making  25  percent  more  than  Johnson  City,  Tennessee  engineers,  don’t  help  a  Silicon  Valley 
engineer  trying  to  get  a  raise  unless  he  first  helps  the  figures  a  little.  But  with  just  a  little  help,  the 
numbers  can  be  made  to  serve  the  engineer’s  purpose;  for  example,  by  expressing  the  salaries  as 
percentages  of  the  mean  (not  median)  cost  of  a  house.  Of  course,  that  might  just  convince  him  to 
move  to  Tennessee. 

“Human  interface  design”  is  a  cumbersome  name  for  one  of  the  most  subtle  and  important  issues 
in  system  development.  My  cousin  Corbett  has  looked  for  years  for  a  better  term,  but  everything 
he  came  across  seemed  even  more  ungainly  or  ugly  than  human  interface  design  (FrontEnding?). 

It  was  only,  he  says,  when  he  read  the  "Real  Time”  column  by  My  Pal  Tyler  in  the  June  issue  of  ESP 
magazine  (“For  People  Who  Don’t  Need  No  Stinkin’  Interface")  that  he  finally  found  his  neologisms. 

Tyler  was  expanding  on  the  metaphor  of  integrated  circuits  as  jelly  beans.  Although  (as  Corbett 
pointed  out  to  me)  Tyler  failed  to  mention  that  the  metaphor  logically  ought  to  run  in  the  other 
direction  today  (there  are  now  more  ICs  than  jelly  beans  in  the  world,  so  we  should  refer  to  jelly 
beans  as  ICs),  he  did  announce  the  Era  of  the  Jelly  Bean  Computer.  Buy  a  few  jelly  beans  and  you 
can  put  together  a  jelly  bean  PC  clone. 

The  term  “jelly  bean  computer"  combines  two  figures  of  speech:  The  obvious  metaphor  of  the 
jelly  bean  for  the  IC  and  the  metonymy  of  the  part  (the  ICs)  standing  for  the  whole  (the  computer). 
The  appeal  of  the  term  comes  from  the  closeness  of  the  two  figures  of  speech  to  actual  fact:  The 
chips  are  (at  least)  as  common  as  jelly  beans,  and  the  PC  clone  described  is  little  more  than  a  few  ICs. 

So  what  kind  of  human  interface  would  a  jelly  bean  computer  have?  Corbett  asked  himself. 
Applying  metonymy,  Corbett  decided  to  represent  the  entire  human  interface  by  a  keyboard,  and 
what  kind  of  keyboard  goes  with  a  cheap  PC?  A  chiclet  keyboard,  of  course.  Hence  Corbett’s  new 
term  for  human  interface  design:  Gluing  chiclets  to  the  jelly  beans. 

He  hopes  it  will  catch  on. 


Michael  Swaine 
editor-at-large 
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IMPLEMENTING  MULTIPLE  COMPUTER  COMMUNICATIONS  LINKS  1 8 

by  Mark  Servello 

If  you’ve  been  asking  yourself  what  to  do  with  that  dust-covered  minicomputer  in  the  back 
room,  Mark  offers  a  productive  suggestion,  and  shows  you  how  to  do  it. 

LZW  DATA  COMPRESSION  29 

by  Mark  R.  Nelson 

We  all  know  that  less  is  better,  especially  when  it  comes  to  data  transfer  and  storage.  Mark 
shows  how  more  can  be  less,  and  that’s  what  data  compression  is  all  about. 

HIGH-SPEED  FILE  TRANSFERS  WITH  NETBIOS  38 

by  Costas  Menico 

Costas  shows  you  how  to  take  advantage  of  the  high-speed  data  transfer  facilities  LANs 
provide,  without  having  to  bite  the  LAN  bullet. 

FINITE  STATE  MACHINES  FOR  XMODEM  45 

by  Donald  W.  Smith 

If  the  chaos  of  communications  is  getting  you  down,  a  finite  state  machine  may  be  what 
you  need.  Don  describes  how  to  implement  one  for  the  XModem  protocol. 

HAMMING-CODE  DECODING  52 

by  Ben  White 

Reliability  and  efficiency  are  the  cornerstones  of  data  communications.  Ben  examines  the 
Hamming-code  method  of  ensuring  these  qualities  and  shows  you  how  to  implement  this 
approach. 

EXECUTABLE  SPECIFICATIONS  WITH  PROLOG  6 1 

by  Gregory  L.  Lazarev 

Gregory  discusses  how  executable  specifications  can  be  generated  from  a  data  flow  diagram 
using  Prolog’s  declarative  and  procedural  capabilities. 

A  GLOBAL  VARIABLE  DEVICE  DRIVER  FOR  MS-DOS  70 

by  Jim  Mischel 

If  you  need  a  way  to  maintain  true  system-wide  global  variables  for  your  DOS  applications, 

Jim’s  GLOVAR  program  should  fill  the  bill. 

EXAMINING  ROOM _ 

FIRST  LOOK  AT  COMMONVIEW  74 

by  Noel  J.  Bergman 

This  month  in  ‘Examining  Room,’  Noel  examines  Common  View,  an  object-oriented  library 
for  mapping  graphical-user  interfaces  onto  a  set  of  object  classes,  to  find  out  if  it  really 
does  make  it  easier  to  write  Windows  and  Presentation  Manager  applications. 

COLUMNS _ 

PROGRAMMING  PARADIGMS  1 1 2 

by  Michael  Swaine 

Delving  deeper  into  neural  nets,  Michael  arrives  at  Dave  Parker’s  doorstep  to  find  out  what 
this  NN  pioneer  is  up  to  now;  and  Parker  shares  a  back  propagation  demonstration  program 
from  way  back  when. 

C  PROGRAMMING  123 


Thanks  to  Amy  White  and  Dale  Maunu 
of  Mitsubishi  Electronics  for  helping  out 
with  the  monitors  used  on  the  cover  and 
elsewhere  in  this  issue. 
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EDITORIAL  6 

by  Jonathan  Erickson 

LETTERS . 10 

by  you 

SWAINE’S  FLAMES . 168 

by  Michael  Swaine 

ADVERTISER  INDEX  152 
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compiled  by Janna  Custer 
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MARKETPLACE . 160 

classified  ads 


by  Al  Stevens 

Al’s  collection  of  C++  tools  continues  to  grow,  as  he  provides  object-oriented  versions  of 
standard  menus  he  developed  last  year  with  regular  C.  He  also  brings  you  up  to  date  on 
ANSI  C. 

STRUCTURED  PROGRAMMING  132 

by  Jeff  Duntemann 

Object-oriented  programming  has  introduced  more  new  terms  than  we'd  care  to  shake  a 
stick  at.  This  month,  Jeff  sorts  out  and  clears  up  some  of  those  terms,  at  least  as  they  apply 
to  Smalltalk,  Actor,  QuickPascal,  and  Turbo  Pascal. 


NEXT  ISSUE _ 

If  two  heads  are  better  than  one,  it  naturally 
follows  that  two  (or  more)  processors  are 
better  than  just  one.  So,  in  November  we’ll 
take  a  look  at  the  problems  —  and  pro¬ 
mise  —  parallel  processing  holds  for  pro¬ 
grammers.  Among  other  topics,  we’ll  exam¬ 
ine  Concurrent  C  and  Silicon  Graphics  SGI 
parallelization  scheme,  and  see  how  run¬ 
time  dynamic  linking  operates  under  OS/2. 
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Communications 

Capers 


In  the  four  or  five  months  since  the  DDJ  listing  service  opened  its  on-line  doors,  about  1500  of 
you  have  been  using  the  service  regularly,  so  report  sysops  Bill  Garrison  and  David  Betz.  This 
translates  into  an  average  of  about  2000  minutes  of  on-line  time  per  day  just  for  downloading 
listings  from  DDJ  and  MIPS  magazine  (a  sister  publication)  and  sending  electronic  mail  to  those  of 
us  at  the  magazine. 

We’ll  gradually  begin  providing  more  features,  starting  with  a  list  of  upcoming  or  proposed 
articles.  You  can  help  us  by  taking  a  look  at  the  selections  and  letting  us  know  which  ones  you’d 
most  like  to  see.  At  the  same  time,  you  can  also  tell  us  what  you  think  about  some  of  the  articles 
we’ve  recently  published:  Which  were  you  favorites,  which  ones  you  didn’t  like,  what  we  could 
have  done  differently. 

We’d  also  like  you  to  log  on  to  give  Bill  and  David  some  feedback  on  what  you  think  of  the 
service  itself  —  the  interface,  the  features,  and  so  on.  Keep  in  mind  that  this  on-line  service  is  still 
in  its  formative  stage,  and  you  have  the  opportunity  to  help  design  it  the  way  you  think  it  should 
be  designed.  All  Bill  and  David  need  are  your  comments  and  suggestions.  So  log  on  (603-882-1599) 
and  drop  us  an  e-note. 


One  of  my  favorite  articles  in  this  issue  is  Costas  Menico’s  “High-Speed  Data  Transfers  With 
NetBIOS."  As  usual,  Costas  shares  some  neat  techniques  that  he  regularly  uses  at  the  Software 
Bottling  Company.  Good  ideas  come  in  batches,  as  we  found  out  when  Tom  Nolan,  an  associate 
scientist  for  Applied  Research  Corp.,  sent  in  an  article  describing  a  very  similar  NetBIOS  data  transfer 
technique  he  uses  at  the  NASA/Goddard  Space  Flight  Center.  Unfortunately,  we  weren’t  able  to 
publish  both  articles,  but  we  will  be  running  another  article  of  Tom’s  in  January,  in  which  he 
provides  the  tools  for  a  complete  real-time  PC-based  data  acquisition  system  (his  area  of  speciality), 
including  a  schematic  for  the  hardware  and  the  source  code  for  the  software.  This  is  one  article  I 
can’t  wait  to  get  into  print. 


So  you  think  data  communications  is  one  area  of  computing  that’s  getting  easier?  If  so,  you  might 
want  to  talk  to  Ed  Dowgiallo,  architect  of  the  DBMS  Decathlon  benchmark  suite  and  head  of  the 
DBMS  Labs.  ( DBMS  is  another  sister  publication  of  DDJ.) 

Ed  spent  the  past  summer  (and  then  some)  setting  up  the  DBMS  Labs  test  bed,  aging  several 
years  in  the  process.  The  initial  configuration  of  the  test  bed,  says  Ed,  was  an  Everex  386,  Step  25 
server  with  five  AT-cIass  PCs,  several  Archive  tape  drives  for  backup,  several  Tandon  DataPacs  for 
transporting  data,  and  various  combinations  of  networking  hardware  and  software.  The  project 
initially  rolled  along  like  a  new  Volvo,  but  when  one  vendor  canceled  development  of  some  of  its 
drivers,  the  wheels  came  off,  and  the  task  of  getting  anything  to  talk  to  anything  else  quickly  turned 
into  a  nightmare. 

I  hope  Ed  gets  the  time  and  opportunity  to  describe  the  nightmare,  if  not  for  DBMS  or  DDJ,  maybe 
for  LAN  Technology  (yet  another  of  DDJ' s  sister  publications).  I’d  like  to  think  that  I  did  my  part  to 
keep  the  project  running  by  taking  Ed  to  Donovan’s,  his  and  my  favorite  local  eatery,  for  an 
occasional  lunch  and  a  requisite  reality  check. 


Just  to  underscore  the  fact  that  communications  have  never  been  easy,  I’m  reminded  of  a  modem 
project  at  a  company  where  I  used  to  work.  The  goal  was  to  build  a  300/1 200-baud  auto-dial, 
auto-answer  modem.  (Yep,  this  is  back  in  the  days  when  1200  baud  was  still  cutting  edge.)  Pretty 
straightforward,  right?  The  modems  were  built,  the  manuals  written,  the  boxes  printed,  and  the 
ready-to-ship  packages  were  assembled  at  the  warehouse.  About  that  time,  one  of  the  engineers 
discovered  a  problem.  It  seems  that,  for  some  reason  or  another,  the  modem  didn’t  work  at  1200 
baud  after  all. 

I  don’t  know  who  made  the  final  decision  on  what  to  do,  but  it  was  quite  simple.  The  crates 
were  unpacked,  the  boxes  and  manuals  thrown  away,  the  labels  on  the  modems  peeled  off,  and 
the  300/1200  baud  selector  switch  removed.  New  labels  (sans  mention  of  1200  baud)  were  stuck 
on,  new  manuals  and  boxes  printed  and  packed,  and  you  guessed  it,  the  company  introduced  a 
new,  state-of-the-art  auto-dial/auto-answer  300-baud  modem. 

Such  is  life  and,  as  Don  Smith  says  later  in  this  issue,  the  chaos  of  communications. 


Jonathan  Erickson 
editor-in-chief 
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When  Is  a  Standard 
Really  a  Standard? 

Dear  DDJ, 

We  write  C  using  the  medium  model, 
which  provides  lots  of  room  for  code 
and  64K  bytes  for  data.  A  lot  of  the  data 
space  is  used  up  by  ASCII  strings,  mes¬ 
sages,  keyword  lists,  and  so  on. 

Most  of  these  strings  are  used  only 
in  one  procedure,  so  it  would  be  nice 
to  have  the  space  they  take  up  not  be 
in  the  precious  data  space,  where  they 
are  as  bad  as  globals. 

Happily,  the  “draft”  ANSI  standard 
now  (and  has  for  more  than  two  years) 
specifies  that  arrays  of  class  ‘auto’  can 
be  initialized.  So,  in  standard  C  code, 
you  can  say 

void  print_error  message(int  error- 
number)  ( 

byte  message  10  =  “This  is  a 

long  error  message”; 

byte  message20  =  “Here  is 

another  message”; 

/*...*/ 

byte  message9990  =  “And  so  on”; 


Any  reasonable  implementation  of  a 
compiler  would  initialize  the  messages 
by  doing  a  move  out  of  the  code  space 
into  variables  with  space  allocated  on 
the  stack,  and  permanent  data  space 
would  not  be  squandered  on  all  the 
messages. 

Unfortunately,  of  the  12  C  compilers 
I  have  tried  out,  only  one,  the  Corpo¬ 
rate  Computer  Systems  compiler  for 
the  Hewlett  Packard  HP-3000,  supports 
this  feature. 

I  have  talked  to  Microsoft  and  some¬ 
one  there  finally  admitted  that  yes,  it  is 
in  the  current  draft  ANSI  standard  but 
as  the  standard  has  not  been  finalized 
yet  they  are  not  necessarily  implement¬ 
ing  all  the  aspects  of  the  C  language. 

Now  I  see  that  Microsoft  is  claiming 
that  their  compiler  is  compatible  with 
the  draft  standard. 

Joe  Weisman 

Computers  for  Marketing  Corp. 

San  Francisco,  Calif. 
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Infant  Damnation  Isn’t 
Our  Cup  of  Tea 

Dear  DDJ, 

The  more  I  see  your  publication,  the 
more  optimistic  I  become  that  I  may 
eventually  learn  something  about  pro¬ 
gramming.  While  they  have  me  scratch¬ 
ing  my  head  in  bewilderment  at  times, 
the  articles  you  publish  avoid  both  the 
superficiality  of  some  publications  and 
the  rancidly  pedantic  turgidity  of  oth¬ 
ers  that  too  often  approach  the  pudding¬ 
like  quality  of  a  19th  century  Welsh 
theologian  expounding  on  predestina¬ 
tion  or  infant  damnation.  When  I  don’t 
understand  what  you  publish,  I  feel 
that  I  simply  haven’t  yet  established  a 
sufficient  groundwork  in  my  own  mind. 

In  the  special  C  issue,  I  found  the 
discussion  of  Smalltalk  interesting,  I 
learned  that  the  graphics  format  of  PC 
Paintbrush  is  in  the  mainstream,  which 
is  important  to  me  because  I’m  about  to 
buy  a  digitizer  which  comes  with  it,  and 
“Building  Your  Own  C  Interpreter”  will 
be  closely  studied.  I’m  looking  forward 
to  the  upcoming  treatment  of  using 
assembly  language  to  create  one’s  own 
minilanguage.  My  areas  of  interest  do 
not  require  a  large  number  of  functions 
or  procedures,  but  the  ones  they  do 
require  are  not  provided  adequately  in 
the  languages  I  have  examined. 

Billy  R.  Pogue 

Lake  Havasu  City,  Ariz. 

GUI  Programming  Guidelines 

Dear  DDJ, 

Yesterday  I  got  my  copy  of  the  July 
issue  and  the  first  article  I  read  was  the 
one  on  the  Presentation  Manager.  Since 
I  do  some  programming  under  Digital 
Research’s  GEM,  I  am  very  interested 
in  how  things  are  done  under  various 
graphic  user  interfaces.  But  what  I  have 
trouble  with  is  the  misuse  of  the  right 
mouse  button.  In  MFIT,  it  is  used  to 
terminate  input  and  to  start  an  action. 
In  some  drawing  programs,  it  is  used 
as  a  replacement  for  the  shift-key.  And 
some  other  systems,  like  the  Smalltalk 
environment,  use  it  as  the  button  that 
pops  up  a  menu. 

This  is  not  easy  to  understand  for  the 
average  user  of  these  applications.  Just 
think  if  every  automobile  firm  would 
place  the  brake  on  a  different  pedal 
or  even  on  a  switch  behind  the  steer¬ 
ing  wheel!  To  avoid  such  misuses  I 
would  strongly  recommend  that  every 
developer  of  applications  that  run  un¬ 
der  graphic  user  interfaces  read  the 
Human  Interface  Guidelines  published 
by  Apple.  This  book  gives  a  philoso¬ 
phy  that  puts  the  user  in  the  middle  of 
the  development  process  of  the  exter¬ 
nal  representation  of  an  application. 
The  only  one  who  can  win  by  such  a 


view  of  the  end  user  is  the  end  user. 

The  second  comment  I  have  to  make 
is  on  the  programming  of  graphic  in¬ 
terfaces  in  general.  I  do  not  understand 
why  a  relatively  small  program  like  MFIT 
requires  about  ten  files  to  compile.  The 
actual  code  for  the  processing  of  the 
points  and  the  drawing  of  the  work¬ 
space  has  only  about  half  a  page,  the 
rest  just  implements  the  STANDARD 
behaviour  of  dialog  boxes,  menus,  and 
other  objects  on  the  screen.  This  over¬ 
head  makes  development  of  user- 
friendly  applications  this  complicated 
and  is  the  cause  for  the  slow  learning 
curve  and  the  long  development  time 
required  for  even  small  programs  like 
MFIT. 

It  is  this  overhead  that  is  responsible 
for  the  minor  acceptance  of  graphic 
user  interfaces  among  software  devel¬ 
opers.  I  know  this  because  it  took  me 
over  two  months  (about  100  hours, 
you  see,  I  am  a  hobbyist)  to  create  an 
invoice  printing  program  with  an  easy- 
to-use  graphic  interface  with  GEM.  The 
actual  code  is  only  about  2K  bytes,  but 
the  overall  size  of  the  source  file  is 
about  70K  bytes.  After  this  experience, 
two  friends  of  mine  and  I  decided  to 
develop  our  own  language  and  devel¬ 
opment  environment.  But  soon  we  no¬ 
ticed  that  this  is  too  big  a  project  for 
three  hobby  programmers.  Now  we 
have  a  lot  of  ideas  for  common  inter¬ 
face  in  which  applications  can  be  used 
on  Unix,  DOS,  or  the  Mac  without  chang¬ 
ing  the  compiled  program.  In  such  an 
environment  the  user  could  run  the 
same  application  under  several  win¬ 
dowing  systems.  The  system  would  care 
about  the  differences  in  the  user  inter¬ 
face  and  OS.  So  if  there  are  other  peo¬ 
ple  interested  in  our  thoughts,  just  drop 
a  line  to  DDJ,  who  will  surely  pass 
your  letter  on  to  us. 

Andreas  Berger 

Neu-Isenburg,  W  Germany 

It’s  All  in  the  Numbers 

Dear  DDJ, 

Your  magazine  continues  to  provide 
enjoyable  articles  and  accompanying 
code.  A  comment  on  A1  Stevens’s  August 
1989  column  in  which  he  restates  Robert 
Benchley  “the  world  is  divided  into 
two  kinds  of  people  —  those  who  di¬ 
vide  the  world  into  two  kinds  of  peo¬ 
ple  and  those  who  do  not.”  As  a  com- 
puphobia  counselor  for  ten  years,  I 
have  learned  that  the  world  is  divided 
into  three  kinds  of  people  —  those  who 
count  and  those  who  can’t. 

mickRacky 

Oakland,  Calif. 

DDJ:  12  out  of  a  dozen  times,  you  're 
right. 
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AWK-Like  Extensions  Revisited 

Dear  DDJ 

I  much  appreciated  Jim  Mischel’s  arti¬ 
cle  “Writing  AWK-Like  Extensions  to 
C”  in  the  June  1989  issue  of  Dr.  Dobb’s 
Journal.  I  have  used  the  pattern  match¬ 
ing  routines  to  construct  an  alternative 
grep  that  shows  matching  lines  within 
a  window  of  lines  before  and  after  the 
matching  one.  I  had  a  shell  version  of 
this  tool  from  the  March  1989  issue  of 
UNIXWorld,  but  my  C  version  obvi¬ 
ously  goes  much  quicker. 

However,  I  have  found  one  prob¬ 
lem,  the  functions  will  not  find  a  match 
for  the  empty  line  pattern  a$.  This  oc¬ 
curs  because  the  gets( )  library  function 
returns  just  an  empty  string,  the  \0 
character.  In  this  circumstance  the 
re_match( )  function  makes  no  attempt 
to  find  a  match,  as  the  body  of  the 
u'hile  loop  is  never  entered,  and  thus 
returns  NULL.  I  have  cured  this  by  chang¬ 
ing  the  loop  to  be: 

_s_end  =  NULL; 
do 
( 

if(  match_term(  c  -  s,  c,  pat  )  != 
FALSE  ) 

( 

RSTART  =  c  -  s; 

RLENGTH  =  _s_end  -  c; 
return!  c  ); 

) 

if(  *c ) 

I 

C++; 

} 

1  while!  *c  !=  ENDSTR  ); 

which  always  does  at  least  one  pass 
through  the  line  to  be  matched. 

JohnM.  Howells 
West  Lancs,  England 

Jim  responds:  Thank  you  for  your  let¬ 
ter.  You  did  indeed  find  a  problem 
with  the  code  and  I  appreciate  your 
response.  I  did  some  testing  and  found 
that  you  can  eliminate  the  awkward 
“if  (*c)”  in  your  code  by  modifying 
the  while  statement:  while  (*c++  != 
ENDSTR)  ; 

Forth,  an  Object  of  Affection 

Dear  DDJ 

I  enjoyed  Jeff  Duntemann’s  “Structured 
Programming"  column  in  the  July  issue 
of  Dr.  Dobb ’s. 

A  lot  of  what  he  said  about  object- 
oriented  programming  sounded  like 
good  factoring  in  Forth.  With  good  fac¬ 
toring,  each  word  is  reusable  and  you 
can  hide  the  details  of  the  lower-level 
words. 

Perhaps  in  a  future  article  you  could 


address  OOP  in  the  Forth  environment, 
such  as  the  Forth  object-oriented  pro¬ 
gramming  extension  to  HS/Forth. 
Ramer  W.  Streed 
Kato  Engineering 
Mankato,  Minn. 

Pascal  Hints 

Dear  DDJ, 

I  have  greatly  enjoyed  reading  Jeff  Dun¬ 
temann’s  articles  in  DDJ-,  as  my  primary 
language  is  Pascal,  his  column  is  inher¬ 
ently  the  easiest  for  me  to  understand. 
I  would  like  to  make  a  few  points  about 
his  June  1989  column:  1.  When  assem¬ 
bly  routines  are  short  —  as  in  the  case 
of  BIOS  hooks  —  it  is  better  to  code 
them  in  assembly,  as  Turbo  adds  much 
housekeeping  code  which  swamps  the 
functional  code.  These  calls  are  by  defi¬ 
nition  machine  dependent  so  there  is 
no  reason  not  to  optimize  them.  2. 
Jeffs  calendar  program  goes  to  too 
much  effort  to  do  its  work!  As  you  are 
restricting  yourself  to  dates  after  1980, 
we  don’t  need  to  know  about  Julian 
and  Gregorian  calendars;  all  we  do  need 
to  know  is  on  which  day  of  the  week 
falls  a  given  date.  The  function  to  serve 
this  purpose  is  called  Zeller’s  congru¬ 
ence,  which  I  learned  about  from  Com¬ 
puter  Language,  March  1988,  pp.  9  - 
10.  1  hope  that  you  find  this  informa¬ 
tion  useful. 

Norman  Newman 
Israel 

P.S.  What  is  KI6RA? 

DDJ:  K16RA  is Jeffs  ham  radio  call  sign. 

More  on  RLE 

Dear  DDJ, 

I  refer  to  your  two  articles,  “Run-Length 
Encoding,"  by  Robert  Zigon,  February 
1989,  and  "RLE  Revisited,”  by  Phil  Daley, 
May  1989.  While  Mr.  Daley’s  compres¬ 
sion  technique  certainly  solves  the  prob¬ 
lems  associated  with  inefficient  coding 
of  streams  of  data  with  frequent  char¬ 
acter  changes,  it  causes  another  prob¬ 
lem  potentially  much  worse  in  terms 
of  data  integrity. 

Consider  the  situation  where  the  al¬ 
gorithms  are  used  for  the  compression 
of  data  where  there  is  potential  to  lose  a 
byte  (or  where  a  byte  may  be  corrupted 
due  to  transmission  or  storage  media). 

The  loss  of  a  byte  using  the  former 
technique  is  susceptible  to  the  worst 
case  loss  of  the  whole  of  the  rest  of  the 
file,  if  the  incorrect  byte  is  one  which 
marks  the  stream  length.  Since  by  defi¬ 
nition,  compression  algorithms  are  used 
to  save  storage  or  transmission  time 
on  large  files,  the  losses  may  be  con¬ 
siderable. 

I  would  be  interested  to  read  a  de¬ 


scription  of  an  algorithm  which  com¬ 
bines  the  ‘best  of  both  worlds’  by  com¬ 
bining  Daley’s  better  compression  tech¬ 
nique,  with  properly  framed  sequences 
which  minimize  the  effects  of  inaccu¬ 
rate  reproduction. 

Luke  E.  Murphy 

French’s  Forest,  Australia 

Notes  from  Down  Pander 

Dear  DDJ, 

I  am  still  shocked  about  your  July  1989 
editorial  concerning  escort  agency  ser¬ 
vices  being  logged  as  “software”  by 
credit  card  users. 

I  feel  that  I  must  chastise  you,  as 
editor,  for  not  warning  your  readers 
concerning  the  rises  associated  with 
using  recursive,  or  ill-behaved,  proce¬ 
dures  in  such  an  obvious  multiuser  en¬ 
vironment. 

I  see  the  lack  of  such  warnings  as 
likely  to  spread  bugs  and  viruses  that 
may  severely  limit  some  users’  forth¬ 
coming  endeavours.  Such  bugs  and  vi¬ 
ruses  may  disable  their  stack  probes, 
or  make  them  Unix. 

P.  Butterworth 

New  South  Wales,  Australia 

Brute  Force  vs.  Boyer-Moore 

Dear  DDJ, 

Thanks  for  Costas  Menico’s  article  on 
faster  string  searches.  The  article  was 
well  written,  and  the  algorithm  he  pre¬ 
sented  is  interesting  and  useful.  How¬ 
ever,  he  seems  to  present  this  approach 
as  being  superior  to  the  brute  force 
method  in  the  general  case,  which  it 
clearly  isn't.  The  weakness  in  the  algo¬ 
rithm  is  the  need  for  constructing  a 
256-byte  skip  array  at  every  cell.  This 
is  equivalent  in  CPU  cycles  to  doing  a 
brute  force  scan  on  a  string  of  about 
80  bytes,  and  it  occurs  before  the  ac¬ 
tual  string  search  even  begins. 

Also,  it  should  be  pointed  out  that 
the  timing  benchmark  program  com¬ 
paring  his  POSBM  to  the  brute  force 
method  tended  to  skew  the  results. 
First  of  all,  Turbo  Pascal’s  built-in  POS 
function  is  an  extremely  poor  example 
of  the  brute  force  method.  I  ran  Mr. 
Menico’s  benchmark  program  to  com¬ 
pare  execution  times  among  POS, 
POSBM,  and  my  own  brute-force  FIRST- 
POS  function,  which  is  included  in  my 
STRINGS.TPU  package  (available  on 
the  Borland  Forum  on  CompuServe). 
Not  to  toot  my  own  hom,  but  on  my 
IBM  XT,  FIRSTPOS  was  about  10  times 
faster  than  POS,  twice  as  fast  as  POSBM! 
So  by  this  benchmark,  POSBM  seems 
to  be  inferior  to  a  well-implemented 
brute  force  approach. 

Another  skewing  factor  in  the  bench¬ 
mark  is  the  use  of  a  255-byte  string, 
from  which  the  last  five  characters  are 
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(continued  from  page  12) 
selected  as  the  search  string.  This  maxi¬ 
mizes  the  distance  over  which  the  al¬ 
gorithm  can  skip.  I  ran  the  benchmark 
using  an  80-character  string  (probably 
closer  to  a  real-world  application)  with 
PCS,  POSBM,  and  FIRSTPOS ,  and  the 
ratio  of  execution  times  was  about 
4. 5: 2. 5:1,  respectively. 

So  the  question  is,  under  what  con¬ 
ditions  is  POSBM  superior  to  the  brute 
force  method?  A  long  pattern  string 
would  work  in  its  favor  by  maximizing 
the  average  distance  per  skip.  A  long 
string  to  search  in  would  also  tend  to 
magnify  the  effects  of  skipping,  but 
here  we’re  limited  by  the  255-byte  length 
of  Turbo  Pascal  strings.  Eliminating  the 
overhead  of  constructing  the  skip  array 
at  every  call  would  go  a  long  way  in 
speeding  things  up,  so  it  seems  an  ideal 
situation  for  using  the  Boyer-Moore 
method  would  be  in  searching  a  series 
of  strings  for  the  same  pattern,  so  that 
the  skip  array  need  be  constructed  only 
once.  Unfortunately,  the  way  POSBM 
is  written,  there  is  no  way  to  save  the 
skip  array  between  calls,  making  it  im¬ 
possible  to  capitalize  on  this  situation. 

Rich  Winkel 

Harrisburg,  Missouri 

C  Multidimensional  Arrays 

Dear  DDJ. 

Your  annual  C  Issue  was  quite  enjoy¬ 
able.  I  should  like  to  comment  on  two 
articles  in  particular. 

The  first,  “C  Multidimensional  Ar¬ 
rays  at  Run  Time"  by  Paul  Anderson, 
is  both  instructive  (with  respect  to  the 
use  of  pointers)  and  useful  in  applica¬ 
tion.  It  should  be  noted  that  the  tech¬ 
niques  developed  for  two-  and  three- 
dimensional  arrays  are  easily  extended 
to  use  the  Far  Heap  as  well  as  the 
(near)  Heap.  One  has  merely  to  use 
farcallocO  and  farmallocC jwith  a  cast 
to  long  for  their  numerical  arguments 
and  of  course  farfree( )  for  releasing 
the  memory  blocks. 

In  Listing  Three,  on  page  124,  Mr. 
Anderson  has  assumed  that  the  deter¬ 
minants  to  be  evaluated  have  positive 
definite  (non-zero)  elements  in  the  ap¬ 
plication  of  the  algorithm  (which  is 
misnamed).  As  written,  a  non-vanish¬ 
ing  determinant  with  a  zero  in  a  diago¬ 
nal  element  would  return  a  divide  by 
zero  error. 

The  method  he  has  used  to  evaluate 
the  determinant  is  known  in  the  litera¬ 
ture  as  “Upper  Triangularization.”  The 
determinant  (matrix)  is  converted  into 
an  upper  triangular  form  (one  in  which 
all  the  elements  below  the  diagonal  are 
zero)  and  evaluated  using  the  theorem 
that  the  determinant  of  an  upper  trian¬ 
gular  matrix  is  the  product  of  its  diago¬ 


nal  elements.  Note  that  any  zero  ele¬ 
ments  on  the  diagonal  of  the  initial 
determinant  are  transformed  in  the  up¬ 
per  triangularizaiton  process  to  non¬ 
zero  elements  if  the  determinant  is  non¬ 
vanishing. 

This  technique  was  originally  devel¬ 
oped  (and  primarily  used)  in  the  solu¬ 
tion  of  systems  of  linear  algebraic  equa¬ 
tions  and  the  related  problem  of  matrix 
inversion.  In  developing  that  solution 
the  determinant  of  the  coefficients  of 
the  equation  is  required.  In  many  ap¬ 
plications  (particularly  statistical)  the 
equations  are  inherently  positive  defi¬ 
nite  and  the  solutions  presented  in  the 
literature  do  not  contain  any  tests  for 
singularity.  I  presume  that  Mr.  Ander¬ 
son  had  referred  to  those  in  obtaining 
his  algorithm. 

I’ve  included  the  correct  code  (see 
Listing  One,  below),  translated  from 
the  pseudo  code  on  page  143  of  Nu¬ 
merical  Methods  for  Computer  Science, 
Engineering,  and  Mathematics,  by  John 
H.  Mathews,  Prentice  Hall  1987.  The 
algorithm  given  there  is  embedded  in 
a  slightly  larger  problem  and  I  have 
extracted  out  only  that  part  relevant  to 
evaluating  the  determinant. 


Jeff  Duntemann  has,  in  my  opinion, 
written  the  most  intelligent  article  by  far 
on  Smalltalk.  He  has  really  placed  it  in 
the  proper  perspective.  It  really  makes 
you  wonder  why  it  hasn’t  been  written 
before.  This  article  alone  is  well  worth 
the  price  of  the  issue  many  times  over. 

Reading  it  and  noting  my  own  reac¬ 
tion,  reminded  me  of  an  event  I  wit¬ 
nessed  many  years  ago  at  a  Physics 
Department  Colloquium.  Professor  E.P. 
Wigner  was  giving  a  talk  on  some  new 
work  he  had  recently  done  and  when 
he  had  concluded  there  was  the  usual 
question  and  answer  session.  A  well- 
known  physicist  (not  quite  as  well 
known  as  Wigner)  in  the  audience  arose 
and  said,  “Well  Professor  Wigner,  that 
was  all  very  nice  but  if  seems  rather 
elementary.”  And  Professor  Wigner  (af¬ 
ter  a  momentary  reflection)  replied: 
“Yes  —  when  something  has  been  ex¬ 
plained  to  you  and  you  do  understand 
it,  it  is  indeed  rather  elementary.” 

Given  that  framework,  any  other  com¬ 
ments  on  my  part  would  be  superfluous. 
Morton  F.  Kaplon 
Easton,  Maryland 

DDJ 


Listing  One 


/**********************«*********************** ****** ******************«/ 
/*  Determinant  Calculator  Using  Near  Heap  and  Upper  Triangular  Matrix  */ 


double  det (arg, n) 
char  *arg? 
int  n; 

{ 

register  int  i,t,k,p; 
double  **a,  ret,  x; 
char  **sdim2(); 

int  *  row; 


/*  arg  =  array  name,  n  ■ 


/*  Array,  Return  value  of  Det,  Temp  variable  */ 
/*  defined  in  Listing  Three  */ 

/*  row  pointer  for  pivoting  */ 


/*  dynamically  create  2  dim  "array  "  array  a  from  arg  */ 
a  =  (double  **)sdim2 (arg, n,n, sizeof (double) ) ; 

row  =  (int  *)malloc (n*sizeof (int) ) ;  /*  row  pointer  for  pivoting  allocation*/ 
if  (row  ==  (int  *)  NULL)  { 

fprintf (stderr, "No  heap  space  for  Row  Pointers  for  Pivoting  "); 
exit  (1) ; 

) 

/*  creating  upper  triangular  matrix  with  test  for  0  values  on  diagonal  */ 

/*  first  initialize  pointer  vector  */ 
for  (i  =  0;  i  <  n  ;  i++) 
row[i]  ■  i  ; 

/*  find  pivot  elements  */ 
for  (p  =  0;  p  <  n  -  1;  p++)  ( 
for  (k  =  p  +  l;k  <  n  ;k++)  { 

if  (  fabs (a[row[k) ] [p] )  >  fabs (a [row[p] ] [p] )  )  {  /*  switch  index  */ 
t  =  row[p]; 
row[p]  =  rowfk]; 
row[k]  =  t; 

} 

) 

/*  In  usual  application  this  would  be  an  error  message  that  the 
*  matrix  is  singular  and  the  program  would  exit  here  */ 

if  (  a [row[p] ] [pj  ==  0  )  /*  Determinant  is  0  */ 

break;  /*  No  need  to  continue  on  */ 

for  (k  =  p+l;k  <  n;  k++)  { 
x  =  afrowfkj  J [p]/a[row[p] ] [p] ; 
for  (  i  =  p  +  1;  i  <  n  ;i++) 
a[row[k)][i]  =  a[row(k] ] [i] 

} 

} 

/*  if  (  a[row[n-l] ] [n-1]  —  0  )  Determinant  is  0  -  This  would  in 
*  normal  application  be  a  message  Matrix  is  singular  and  an  exit  */ 

/*  value  of  determinant  is  product  of  diagonals  of  upper  triangular  matrix  */ 
for  (ret  =  l,i  =  0;i  <  n;  i++) 

ret  *=  a[row[ij] [ij;  /*  if  any  of  diagonals  are  0  Det  =  0  */ 

free (row) ; 
free (a) ; 


/*  do  Gauss  Jordan  elimination  */ 
x  *  a [row[p] }[i] ; 


End  Listing 
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Implementing 
Multiple  Computer 
Communications 

Links 


Mark  Servello 


It's  no  secret  that  PCs  have  put  a  tremendous  amount  of 
computing  power  directly  into  the  hands  of  end  users, 
and  that  end  users  are  becoming  increasingly  sophisti¬ 
cated  in  customizing  the  machines  for  their  particular 
functions.  Consequently,  everyone  is  looking  for  meth¬ 
ods  to  maximize  communication  between  individual  work¬ 
stations,  each  of  which  is  tailored  on  an  individual  basis  to 
obtain  the  largest  productivity  improvement  for  its  user. 
This  communication  is  necessary  in  order  to  improve  the 
effectiveness  of  the  business  unit,  by  allowing  transfer  and 
sharing  of  information  within  and  between  groups. 

This  article  discusses  the  general  concept  of  PC-to- 
minicomputer  communication.  As  an  example,  I  describe 
how  a  network  can  be  constructed  using  common  tele¬ 
phone  equipment  and  a  surplus  minicomputer,  which  be¬ 
comes  a  network  server,  and  illustrate  methods  for  getting 
computers  to  communicate  under  programmed,  rather  than 
terminal,  control. 

The  Environment 

In  our  office,  we  tend  to  work  in  small  groups  on  individual 
projects.  The  members  of  each  group  share  information 
frequently,  and  often  one  or  more  groups  are  in  the  docu¬ 
ment  print/revision  cycle.  We’ve  had  a  relatively  new  DEC 
PDP-11/73  machine  sitting  around  in  the  office  for  some 
time  (a  circa  1985  leftover  from  an  expired  contract),  and 
we  decided  that  its  multiuser  capabilities  would  enable  us 
to  use  it  as  a  network  controller.  As  such,  we  could  use  it 
for  sharing  information  on  an  as-needed  basis  and  for 
providing  spooled  access  to  the  office’s  printing  resources. 
Because  laser  and  high-speed  draft  printers  are  not  small 
expenditures,  it  is  important  to  use  them  effectively,  which 
is  exactly  what  a  multiuser  computing  system  can  do  with 
its  print  spooling  software. 

When  we  moved  into  our  current  offices,  we  installed  a 


Mark  Servello  is  a  software  engineer  for  American  Manage¬ 
ment  Systems  and  can  be  reached  at  1455  Frazee  Road, 
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second  jack  as  a  data  connection  at  every  phone  outlet  wall 
panel  and  several  more  in  common  usage  areas.  The  extra 
line  is  an  RJ-11  type  modular  jack  wired  to  handle  all  eight 
modem  control  signals. 

Each  data  jack  at  a  telephone  wall  panel  in  the  offices 
leads  back  to  a  single  patch  block  in  the  computer  room 
(see  Figure  1).  These  jacks  are  plugged  into  terminal  inter¬ 
faces  on  the  PDP-1 1,  which  also  has  all  shared  devices  such 
as  printers  and  modems  connected  through  the  terminal 
lines.  The  shared  devices  under  PDP-1  l’s  control  use  all 
eight  RS-232  modem  control  signals  for  maximum  reliability 
at  high  speed.  The  connecting  cables  between  the  wall  jacks 
and  office  PCs  (and  between  the  corresponding  patch  block 
location  and  the  PDP-11)  are  standard  six-conductor,  with 
an  RJ-ll-to-DB25/DB9  connector  at  the  PC’s  serial  port.  For 
these  lines,  the  PDP-1 1  provides  TD,  RD,  DTR,  and  Signal 
Ground,  which  are  wired/jumpered  by  the  connector  to 
allow  serial  communication  over  the  port.  All  wiring  from 
the  connector  to  the  PDP-11  is  straight-through,  and  each 
connector  is  labeled  with  the  type  of  device  it  is  configured 
for  (this  lesson  was  learned  the  hard  way). 

The  Software 

The  hardware  was,  of  course,  in  place  much  sooner  than 
the  software.  Communication  between  the  individual  PC 
workstations  and  the  PDP-11  was  established  relatively 
quickly,  using  a  variety  of  communications  packages  con¬ 
figured  on  the  PC  as  Digital  Equipment  Corporation  VT100 
terminal  emulators.  Fortunately,  our  phone  company  was 
careful  to  install  all  jack  lines  uniformly  throughout  the 
offices.  Even  so,  some  serial  devices  are  finicky,  so  an 
RS-232  Breakout  Box  came  in  handy.  (I  know,  programmers 
don’t  change  light  bulbs  because  it’s  a  hardware  problem,  but 
what  happens  when  you’re  programming  the  hardware?) 

We  were  able  to  use  this  type  of  communication  with  the 
PDP-11  to  accomplish  simple  printing  to  high-speed  line 
and  dot  matrix  printers  by  first  using  Kermit  or  XModem  to 
transfer  a  print  file  to  the  PDP-11,  then  spooling  the  file  to 
the  device.  We  also  used  the  Kermit  program  on  the  PDP-1 1 
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to  establish  communications  between  the  PDP-11  and  all 
of  the  shared  modems  and  printers. 

What  we  really  needed,  however,  was  a  method  by  which 
an  individual  PC  could  behave  as  if  the  shared  device  (a 
printer  for  instance)  was  directly  connected  to  it,  so  that 
users  could  run  applications  programs  (like  word  proces¬ 
sors)  and  print  directly  to  the  serial  port.  On  the  other  end, 
the  PDP-11  had  to  be  capable  of  accepting  the  output  to  the 
serial  port  and  placing  it  into  a  print  file  until  the  PC 
application  program  was  finished.  Once  the  file  was  com¬ 
pleted,  it  had  to  be  spooled  to  the  appropriate  printer. 

Because  of  the  variations  in  possible  PC  connections  and 
the  way  the  PDP-1  l’s  operating  system  (DEC  RSTS/E)  works, 
I  decided  that  two  programs  would  have  to  be  written.  The 
first  program,  running  on  the  PC,  provides  configuration 
control  and  establishes  sessions  with  the  PDP-11.  The  sec¬ 
ond  program,  running  on  the  PDP-11,  performs  communi¬ 
cation  functions  with  the  PC  program  by  providing  status, 
executing  commands,  and  catching  print  output  for  spool¬ 
ing.  The  DEC-provided  minicomputer  spooling  program 
then  routes  printout  files  to  the  proper  printer,  as  specified 
by  the  user. 

I  decided  to  use  a  bottom-up  approach  and  began  writing 
the  PC  program's  serial  port  interface  using  Turbo  Pascal  5.0. 

For  the  actual  serial  interrupt  service  routines,  I  used  Ray 
Duncan’s  marvelous  book  Advanced  MS-DOS  Program¬ 
ming  (Microsoft  Press,  1988)  to  familiarize  myself  with  the 
basic  PC  methodology  (I’m  a  minicomputer  programmer), 
then  employed  a  Turbo  Pascal  translation  tailored  for  my 
needs.  Flow  control  from  the  PDP-11  to  the  shared  devices 
is  by  the  full  eight-line  RS-232  modem  signals.  On  the  PC 
connection,  however,  only  four  lines  (TD,  RD,  Signal  Ground, 
and  DTR)  are  normally  used,  because  the  PDP-11  uses  DTR 
to  determine  whether  a  terminal  is  active,  and  logs  out  any 
process  when  its  terminal’s  DTR  goes  low.  Flow  control 
to/from  the  PCs  is  XON/XOFF  in  the  data  path.  The  ISR 
routines  in  Listing  One,  page  81,  show  the  XOFF  sent  when 
the  PC’s  receive  queue  is  within  one  second  of  being  full  (as 
determined  by  the  data  rate  at  the  current  transmission 
speed).  The  XON  is  sent  so  the  minicomputer  can  resume 
transmitting  when  at  least  two  seconds  of  space  are  avail¬ 
able  in  the  receive  queue. 

I  initially  used  a  simple  driver  program  with  routines  that 
would  loop,  checking  the  comm  port  and  displaying  what 
was  received.  The  program  then  checked  the  keyboard, 
sending  whatever  printable  characters  that  were  typed  to 
the  comm  port.  Turbo  Debugger  made  code  testing  simple, 
because  we  had  established  that  communications  with  the 
PDP-11  were  reliable  by  using  a  communications  program. 
No  special  programming  was  required  on  the  PDP-1 1  at  this 
point,  as  its  normal  terminal  logon  and  control  dialogue 
provided  data  to  ensure  that  the  PC  was  receiving  and 
transmitting  correctly. 

After  the  initial  communication  routines  were  verified  and 
the  configuration  routines  added,  I  began  writing  the  code 
necessary  to  establish  a  session  with  the  PDP-11.  RSTS/E 
(resource  sharing,  time  sharing/extended),  a  relatively  old 
multiuser  operating  system,  requires  that  each  user  identify 
himself  with  a  user  identification  code  (UIC)  that  consists 
of  a  project  number  (range  1  -  255),  a  programmer  number 
(range  0  -  255),  and  a  password.  This  is  fine  for  technical 
people,  who  are  (sometimes)  willing  and  accustomed  to 
cryptic  logon  sequences,  but  analysts  and  word  processors 
are  a  different  manner.  None  of  my  users  would  consent  to 
having  to  log  on  and  run  a  program  manually  each  time  they 
needed  to  print  a  document/file.  I  therefore  had  to  develop 
PC  routines  that  would  first  wake  up  the  RSTS/E  operating 
system  on  the  configured  serial  port,  log  the  user  on,  and 
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then  run  a  matching  program  on  the  PDP-11  to  control  its 
spooling  operations.  All  the  user  would  have  to  specify 
were  printer  selection  and  queue  control  options.  Fortunately, 
DEC  still  gives  the  sources  for  the  major  commonly  used 
system  programs  (CUSPs)  into  its  multiuser  operating  sys¬ 
tems,  among  which  is  the  system  logon  program. 

While  researching  the  most  expedient  method  for  identi¬ 
fying  users  to  the  PDP-1 1  and  logging  them  in  automatically, 
I  discovered  that  DEC  has  already  installed  an  Optional 
Feature  Patch  in  the  RSTS/E  logon  program  for  this  purpose. 
This  patch  allows  the  log-on  program  to  recognize  specific 
strings  from  terminal  ports,  to  bypass  password  verification, 
and  to  automatically  execute  a  captive  program  connected 
to  that  terminal  line.  The  terminal  line  itself  would  serve  to 
identify  the  user  uniquely.  I  decided  that  the  PDP-1  l's 

If  you  build  your  modules  into 
cooperating  building  blocks, 
this  methodology  should 
serve  you  regardless  of  your 
communication  medium 

operating  system  security  was  sufficient  for  preventing  un¬ 
authorized  access  to  that  machine,  so  long  as  the  key  word 
that  activates  the  logon  bypass  is  stored  in  encrypted  format 
in  the  PC  program. 

The  RSTS/E  CUSP  programs  are  written  in  the  Basic-PLUS-2 
language  (a  rather  Pascal-like  variant  of  Basic).  It  was  a 
simple  matter  to  implement  the  source  change  enabling  this 
patch  and  to  provide  the  logon  program  with  the  recogni¬ 
tion  string  and  program  name  to  be  executed  when  that 
string  is  detected  on  a  terminal  line.  Debugging  the  logon 
sequence  was  quick  and  straightforward  using  the  PDP-ll’s 
system  console  to  monitor  the  logon  program  and  Turbo 
Debugger  to  monitor  the  PC. 

Figure  2  shows  the  sequence  of  operations  necessary  to 
establish  a  cooperative  communication  session  between  a 
PC  and  the  PDP-1 1 .  The  first  two  steps,  as  described  earlier, 
control  the  PC’s  serial  port  and  establish  a  valid  logon 
session  under  the  PDP-1  l’s  multiuser  operating  system.  The 
third  step,  in  which  the  minicomputer  sends  device  informa¬ 
tion  to  the  PC  interface  program,  is  critical.  As  the  minicom¬ 
puter  maintains  a  table  of  devices  available  on  line,  which 
it  sends  to  each  PC  when  the  interface  program  finishes  the 
logon  process,  various  printers  can  be  added,  removed,  or 
moved  to  new  locations  on  the  PDP-11  without  changing 
any  of  the  PC  software. 

When  the  user  selects  a  printer,  the  minicomputer  speci¬ 
fies  which  spooler  to  use  for  printout  routing,  as  shown  in 
Step  4.  The  bulk  of  two-way  communication  takes  place  in 
Step  5,  where  the  PC  user  can  display  and  manipulate  the 
print  queues  for  the  various  attached  printers.  I  decided  to 
keep  the  queue  manipulation  operations  as  simple  as  possi¬ 
ble  for  the  users,  even  though  this  imposed  an  additional 
burden  on  the  programs. 

The  user  is  able  to  display  the  queue  for  any  printer, 
including  the  file  name,  user  name  (from  the  terminal  connec¬ 
tion),  length,  and  date/time  the  file  was  queued.  The  user 
can  then  examine,  change,  or  delete  queue  entries.  This  is 
one  area  where  we  rely  upon  professional  courtesy,  as  there 
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(continued  from  page  20) 

is  no  security  checking  on  queue  operations,  and  any  user 
can  manipulate  all  entries  in  the  queue.  After  any  necessary 
queue  manipulation  has  been  performed  the  user  initiates 
PDP-11  file  capture  mode,  directing  the  PC’s  serial  port 
output  to  a  file.  This  file  capture  continues  until  one  minute 
has  passed  from  the  last  output  over  the  serial  link;  the  file 
on  the  minicomputer  is  then  closed  and  added  to  the  spooler 
queue  for  the  selected  printer. 


Packet 

type 

Packet 

gjjpgl^ 

100 

PDP-11  OK 

Tells  PC  program  that  PDP- 
11  is  active  and  awaiting 
commands 

101 

Device  List 
Header 

Tells  the  PC  program  that 
device  description  packets 
follow,  and  how  many 

102 

Device 

Description 

Description  of  printer 
available  for  use 

103 

Queue  List 
Header 

Tells  the  PC  program  that 
queue  entry  packets  follow, 
and  how  many 

104 

Queue  List 
Entry 

Contains  information  about 
the  queue  entry 

105 

PDP-11  Error 

indicates  an  error  in  PDP-11 
packet  processing 

Table  1:  PDP-11  packets 


I  decided  to  use  individual  command  and  response  pack¬ 
ets  for  communication  between  the  minicomputer  and  the 
PC  control  programs.  Table  1  shows  the  PDP-11  packets 
used  and  the  information  contained  in  each,  while  Table  2 
shows  the  same  information  about  the  PC  packets.  Figure  3 
shows  the  physical  makeup  of  each  packet. 

After  the  PC  serial  port  has  been  initialized  and  attached, 

This  example  illustrates 
methods  for  getting  computers  to 
communicate  under 
programmed,  rather  than 
terminal,  control 


the  PDP-11  recognition  string  activates  the  minicomputer 
program.  The  minicomputer  program  responds  with  an  OK 
packet,  followed  by  a  device  list  header  packet  and  as  many 
individual  device  packets  as  necessary  (up  to  a  maximum  of 
20)  to  inform  the  PC  program  of  all  available  print  devices. 
This  list  is  used  to  generate  a  menu  of  printer  choices  for  the 
user,  and  is  available  under  function  key  command. 

When  the  available  device  list  has  been  sent  to  the  PC,  it 
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displays  a  function  menu  and  accepts/processes  commands 
from  the  user  until  a  print  file  output  operation  begins. 
When  a  time  limit  of  one  minute  has  passed  since  any  PC 
output  activity,  the  minicomputer  program  closes  the  file, 
spooling  it  to  the  currently  selected  printer  queue.  After  a 
file  has  been  spooled  to  a  printer,  one  additional  minute  is 
allowed  for  the  PC  program  to  restart  command  processing 
to  the  minicomputer.  If  no  further  communication  is  received, 
the  PDP-11  operating  system  kills  the  minicomputer  process. 

Debugging  the  timing  and  content  of  the  send/receive/ 
respond  packets  sent  between  the  two  programs  involved 
more  than  just  the  use  of  the  Turbo  Debugger  on  the  PC. 
The  large  number  of  packet  types  and  the  varying  sizes  of 
data  sections  in  each  packet  required  a  driver  program  to 
test  the  interchange. 

The  PC  driver  let  me  input  packets  to  be  sent  to  the 
PDP-11  while  displaying  the  contents  of  received  packets. 
It  also  provided  a  status  display  of  any  packet  rejected 
because  of  a  transmission  error  or  bad  checksum. 

Listing  Two  (page  85)  shows  the  constant  and  type  defini¬ 
tions  for  packets  in  the  PC  program.  The  PACKET_REC type 
definition  uses  the  Pascal  variant  record  structure  to  define 
each  packet  type,  with  the  data  portion  of  each  packet 
broken  into  field  definitions  applicable  to  the  packet  type. 
This  listing  also  shows  the  main  processing  portions  of  the 
packet  send/receive  procedures.  A  similar  test  program  was 
written  on  the  PDP-11  to  display  the  contents  of  each  packet 
received  or  sent  on  it,  in  the  sequence  of  transmission.  In 
addition  to  responding  to  PC  commands,  the  PDP-11  pro¬ 
gram  has  commands  that  cause  it  to  send  PDP-11  OK, 
Device  List,  Printer  Queue,  and  PDP-11  Error  packets. 

Once  the  command  and  response  packet  routines  were 
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Packet 

Type 

Packet 

Name 

Description 

200 

Micro 

Acknowledge 

Teils  PDP-11  that  the  pre¬ 
ceding  packet  was  received 
correctly 

201 

Printer  Select 

Teils  PDP-11  which  printer  to 
use  for  subsequent  operations 

202 

Request 

Queue  List 

Asks  PDP-11  to  send  the 
queue  list  for  the  selected 
printer 

203 

Delete  Entry 

Tells  PDP-11  to  delete  a 
queue  entry 

204 

Move  Entry 

Tells  PDP-11  to  move  a 
queue  entry  to  another 
position  in  the  queue 

205 

Hold  Entry 

Tells  PDP-11  to  hold  the  en¬ 
try  in  the  queue,  but  not 
print  the  tile 

206 

Release  Entry 

Tells  PDP-11  to  release  a  pre¬ 
viously  held  queue  entry  for 
printing  in  turn 

207 

Print  Start 

Tells  PDP-11  that  print  file 
output  is  to  begin  from  PC 

208 

Print  End 

Tells  PDP-11  that  print  file 
output  is  finished 

209 

Micro  Error 

Indicates  an  error  in  PC 
packet  processing 

Table  2:  PC  packets 
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working  in  the  PDP-11  and  PC  programs,  modifying  the 
display/command  processors  on  each  machine  into  final 
form  was  fairly  easy.  The  bottom-up  implementation  ap¬ 
proach  made  a  complete  toolbox  of  data  types  and  proce¬ 
dures  available  in  the  form  of  Turbo  Pascal  units  on  the  PC 
and  linkable  subprograms  on  the  minicomputer.  I  then  had 
only  to  link  these  units  and  complete  the  user  interface. 

On  the  PDP-11,  the  same  components  used  in  the  pro¬ 
gram  that  communicates  with  the  PC  were  used  to  develop 
a  system-wide  communication  monitor  that  maintains  a 
complete  transaction  log  of  packets  sent/received  on  the 
PDP-11.  This  log,  incidentally,  can  also  be  used  to  provide 
project-oriented  usage  charge  backs  if  the  equipment  in¬ 
volved  must  be  depreciated.  Fortunately,  our  PDP-11  was 
depreciated  long  ago,  so  this  has  not  yet  been  necessary. 
Of  course,  there’s  always  the  next  upgrade.  .  .  . 

Conclusion 

I  hope  this  article  has  provided  some  insight  into  the  prob¬ 
lem  of  getting  cooperative  programs  with  potentially  dif¬ 
ferent  languages  to  communicate  on  different  platforms. 
Utilizing  the  bottom-up  implementation  approach,  first  es¬ 
tablish  reliable  terminal  communication  between  the  de¬ 


vices.  Don’t  forget  your  breakout  box  here,  even  if  you  hate 
hardware,  because  it  sure  can  save  you  time.  Second,  imple¬ 
ment  serial  communication  configuration  and  processing 
routines  in  your  program.  Third,  create  procedures  to  han¬ 
dle  the  dialogue  of  commands  and  responses.  Finally,  en¬ 
sure  that  the  sequence  and  content  of  each  dialogue  are 
correct  before  moving  on  to  complete  functionality  and 
user  interface.  If  you  build  your  modules  into  cooperating 
building  blocks,  this  methodology  should  serve  you  well 
regardless  of  whether  your  communication  medium  is  via  a 
modem,  twisted-pair,  Ethernet,  or  fiber-optic  LAN. 

Availability 

All  source  code  for  articles  in  this  issue  is  available  on  a 
single  disk.  To  order,  send  $14.95  (Calif,  residents  add  sales 
tax)  to  Dr.  Dobb's  Journal ,  501  Galveston  Dr.,  Redwood 
City,  CA  94063,  or  call  800-356-2002  (from  inside  Calif.)  or 
800-533-4372  (from  outside  Calif  ).  Please  specify  the  issue 
number  and  format  (MS-DOS,  Macintosh,  Kaypro). 

DDJ 

(Listings  begin  on  page  81.) 

Vote  for  your  favorite  feature/article. 

Circle  Reader  Service  No.  1. 


B*.,  0*2 


Byte  N  +  Z  Byte  N  +  3  N  +  Z 


Figure  3 ■  Make-up  of  communication  packages.  The  length  of  the  data  portion  depends  on  the  type  of packet  7  he 
CHECKSUM  is  five  ASCII  digits,  giving  the  sum  of  all  data  bytes  modulo  8. 
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Data  Compression 


Here’s  an  all-purpose  data  compression  technique  that 
belongs  in  your  programming  toolbox 


Mark  R.  Nelson 


Every  programmer  should 
have  at  least  some  expo¬ 
sure  to  the  concept  of  data 
compression.  Programs  such 
as  ARC  by  System  Enhance¬ 
ment  Associates  (Wayne,  N.J.)  and 
PKZIP  by  PKWARE  (Glendale, 
Wise.)  are  ubiquitous  in  the  MS- 
DOS  world.  ARC  has  also  been 
ported  to  quite  a  few  other  operat¬ 
ing  systems,  for  example,  Unix, 
CP/M,  and  so  on.  CP/M  users  have 
long  had  SQ  and  USQ  to  squeeze 
and  expand  programs.  Unix  users 
have  the  COMPRESS  and  COM: 
PACT  utilities.  Yet  the  data  compres¬ 
sion  techniques  used  in  these  pro¬ 
grams  typically  show  up  in  only 
two  places:  File  transfers  over 
phone  lines  and  archival  storage. 

Data  compression  has  an  unde¬ 
served  reputation  for  being  difficult  to 
master,  hard  to  implement,  and  tough 
to  maintain.  In  fact,  the  techniques  used 
in  the  previously  mentioned  programs 
are  relatively  simple,  and  can  be  imple¬ 
mented  with  standard  utilities  taking 
only  a  few  lines  of  code.  In  this  article, 
I’ll  discuss  Lempel-Ziv-Welch  (LZW)  com¬ 
pression,  a  good,  all-purpose  data  com¬ 
pression  technique  that  belongs  in  ev¬ 
ery  programmer’s  toolbox. 

LZW,  for  example,  by  compressing 
the  screens,  can  easily  chop  50K  bytes 
off  a  program  that  has  several  dozen 
help  screens.  With  LZW  compression, 
500K  bytes  of  software  could  be  dis¬ 
tributed  to  end  users  on  a  single  360K 
byte  floppy  disk.  Highly  redundant  da¬ 
tabase  files  can  be  compressed  to  ten 
percent  of  their  original  size. 


Mark  is  a  programmer  for  Greenleaf 
Software,  Inc.,  Dallas,  Texas.  Mark  can 
be  reached  through  the  DDJ  office. 


LZW  Fundamentals 

The  original  Lempel/Ziv  approach  to 
data  compression  was  first  published 
in  1977,  and  Terry  Welch's  refinements 
to  the  algorithm  were  published  in  1984. 
The  algorithm  is  surprisingly  simple. 
In  a  nutshell,  LZW  compression  replaces 
strings  of  characters  with  single  codes. 
It  does  not  do  any  analysis  of  the  in¬ 
coming  text.  Instead,  it  just  adds  every 
new  string  of  characters  it  sees  to  a 
table  of  strings.  Compression  occurs 
when  a  single  code  is  output  replacing 
the  string  of  characters. 

The  code  generated  by  the  LZW  al¬ 
gorithm  can  be  of  any  length,  but  it 
must  have  more  bits  in  it  than  a  single 
character.  The  first  256  codes  (when 
using  8-bit  characters)  are  by  default 
assigned  to  the  standard  character  set. 
The  remaining  codes  are  assigned  to 
strings  as  the  algorithm  proceeds.  The 
sample  program  runs,  as  shown  in  List¬ 
ing  One,  page  86,  with  12-bit  codes. 


This  means  codes  0  -  255  refer  to 
individual  bytes,  and  codes  256- 
4095  refer  to  substrings. 

Compression 

The  LZW  compression  algorithm 
in  its  simplest  form  is  shown  in 
Figure  1.  Each  time  a  new  code  is 
generated,  it  means  a  new  string 
has  been  added  to  the  string  table. 
Examination  of  the  algorithm  shows 
that  LZW  always  checks  whether 
the  strings  are  already  known  and, 
if  so,  outputs  existing  codes  rather 
than  generating  new  codes. 

A  sample  string  used  to  demon¬ 
strate  the  algorithm  is  shown  in 
Figure  2.  The  input  string  is  a  short 
list  of  English  words  separated  by 
the  /  character.  As  you  step  through 
the  start  of  the  algorithm  for  this 
string,  you  can  see  that  in  the  first  pass 
through  the  loop  the  system  performs 
a  check  to  see  if  the  string  /W  is  in  the 
table.  When  it  doesn’t  find  the  string 
in  the  table,  it  generates  the  code  for 
/,  and  the  string  /W  is  added  to  the 
table.  Because  256  characters  have  al¬ 
ready  been  defined  for  codes  0  -  255, 
the  first  string  definition  can  be  as¬ 
signed  to  code  256.  After  the  system 
reads  in  the  third  letter,  E,  the  second 
string  code,  WE,  is  added  to  the  table, 
and  the  code  for  letter  W  is  output.  This 
process  continues  until,  in  the  second 
word,  the  characters  /  and  W  are  read 
in,  matching  string  number  256.  In  this 
case,  the  system  outputs  code  256,  and 
adds  a  three-character  string  to  the  string 
table.  The  process  again  continues  un¬ 
til  the  string  is  exhausted  and  all  of  the 
codes  have  been  output. 

The  sample  output  for  the  string  is 
also  shown  in  Figure  2,  along  with  the 
(continued  on  page  32) 
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( continued  from  page  28) 
resulting  string  table.  As  you  can  see, 
the  string  table  fills  up  rapidly,  because 
a  new  string  is  added  to  the  table  each 


Figure  1:  The  compression  algorithm 


Figure  2:  The  compression  process 


Figure  3:  The  decompression  algorithm 


Figure  4:  The  decompression  process 


time  a  code  is  generated.  In  this  highly 
redundant  example  input,  five  code 
substitutions  were  output,  along  with 
seven  characters.  If  we  were  using  9- 


bit  codes  for  output,  the  19-character 
input  string  would  be  reduced  to  a 
13- 5-byte  output  string.  Of  course,  this 
example  was  carefully  chosen  to  dem¬ 
onstrate  code  substitution.  In  the  real 
world,  compression  usually  doesn’t  be¬ 
gin  until  a  sizable  table  has  been  built, 
usually  after  at  least  100  or  so  bytes 
have  been  read  in. 

Decompression 

The  companion  algorithm  for  compres¬ 
sion  is  the  decompression  algorithm. 
It  takes  the  stream  of  codes  output 
from  the  compression  algorithm  and 

LZW  compression  excels 
when  confronted 
with  data  streams  that 
have  any  type  of 
repeated  strings 


uses  it  to  exactly  recreate  the  input 
stream.  One  reason  for  the  efficiency 
of  the  LZW  algorithm  is  that  it  does  not 
need  to  pass  the  string  table  to  the 
decompression  code.  The  table  can  be 
built  exactly  as  it  occurred  during  com¬ 
pression,  using  the  input  stream  as  data. 
This  is  possible  because  the  compres¬ 
sion  algorithm  always  outputs  the 
STRING  and  CHARACTER  components 
of  a  code  before  it  uses  the  code  in  the 
output  stream.  This  means  that  the  com¬ 
pressed  data  is  not  burdened  with  car¬ 
rying  a  large  string  translation  table. 

The  decompression  algorithm  is 
shown  in  Figure  3-  Just  like  the  com¬ 
pression  algorithm,  it  adds  a  new  string 
to  the  string  table  each  time  it  reads  in 
a  new  code.  All  it  needs  to  do  in  addi¬ 
tion  is  to  translate  each  incoming  code 
into  a  string  and  send  it  to  the  output. 

Figure  4  shows  the  output  of  the 
algorithm  given  the  input  created  by 
the  compression  discussed  earlier  in 
the  article.  The  important  thing  to  note 
is  that  the  decompression  string  table 
ends  up  looking  exactly  like  the  table 
built  up  during  compression.  The  out¬ 
put  string  is  identical  to  the  input  string 
from  the  compression  algorithm.  Note 
that  the  first  256  codes  are  already  de¬ 
fined  to  translate  to  single  character 
strings,  just  like  in  the  compression  code. 

The  Catch 

Unfortunately,  the  nice,  simple,  decom¬ 
pression  algorithm  shown  in  Figure  4 
is  just  a  little  too  simple.  There  is  a 


ROUTINE  LZW_COMPRESS 
STRING  =  get  input  character 
WHILE  there  are  still  input  characters  DO 
CHARACTER  =  get  input  character 
IF  STRING+CHARACTER  is  in  the  string  table  THEN 
STRING  =  STRING+character 
ELSE 

output  the  code  for  STRING 
add  STRING+CHARACTER  to  the  string  table 
STRING  =  CHARACTER 
END  of  IF 
END  of  WHILE 
output  the  code  for  STRING 


Input  string:  /WED/WE/WEE/WEB/WET 
Character  input  Code  output  New  code  value  and  associated  string 


/W 

/ 

256  =  /W 

E 

W 

257  =  WE 

D 

E 

258  =  ED 

/ 

D 

259  =  D/ 

WE 

256 

260  =  /WE 

/ 

E 

261  =  E/ 

WEE 

260 

262  =  /WEE 

/  W 

261 

263  =  E/W 

E  B 

257 

264  =  WEB 

/ 

B 

265  =  B/ 

WET 

260 

266  =  /WET 

<EOF> 

T 

ROUTINE  LZWDECOMPRESS 
Read  OLD_CODE 
output  OLD_CODE 

WHILE  there  are  still  input  characters  DO 
Read  NEW_CODE 

STRING  =  get  translation  of  NEWCODE 
output  STRING 

CHARACTER  =  first  character  in  STRING 
add  OLD_CODE  +  CHARACTER  to  the  translation  table 
OLDCODE  =  NEWCODE 
END  of  WHILE 


Input 

NEWCODE 

Input  codes:  /  W  E  D  256  E  260  261  257  B  260  T 

OLD  CODE  STRING  CHARACTER  New  table  entry 

Output 

/ 

/ 

/ 

W 

/ 

W 

W 

256  =  /W 

E 

W 

E 

E 

257  =  WE 

D 

E 

D 

D 

258  =  ED 

256 

D 

/W 

/ 

259  =  D/ 

E 

256 

E 

E 

260  =  /WE 

260 

E 

/WE 

/ 

261  =  E  / 

261 

260 

E  / 

E 

262  =  /WEE 

257 

261 

WE 

W 

263  =  E/W 

B 

257 

B 

B 

264  =  WEB 

260 

B 

/WE 

/ 

265  =  B  / 

T 

260 

T 

T 

266  =  /WET 
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( continued  from  page  32) 
single  exception  case  in  the  LZW  com¬ 
pression  algorithm  that  causes  some 
trouble  on  the  decompression  side.  If 
there  is  a  string  consisting  of  a  (STRING, 
CHARACTER)  pair  already  defined  in 
the  table,  and  the  input  stream  sees 
a  sequence  of  STRING,  CHARACTER, 
STRING,  CHARACTER,  STRING,  the 
compression  algorithm  outputs  a  code 
before  the  decompressor  gets  a  chance 
to  define  it. 

A  simple  example  illustrates  the  point. 
Imagine  the  string  JOEYN  is  defined 
in  the  table  as  code  300.  When  the 
sequence  JOEYNJOEYNJOEY  appears 
in  the  table,  the  compression  output 
looks  like  that  shown  in  Figure  5. 

When  the  decompression  algorithm 
sees  this  input  stream,  it  first  decodes 
the  code  300,  then  outputs  the  JOEYN 
string  and  adds  the  definition  for,  lets 
say,  code  399  to  the  table,  whatever 
that  may  be.  It  then  reads  the  next 
input  code,  400,  and  finds  that  it  is  not 
in  the  table.  This  is  a  problem. 

Fortunately,  this  is  the  only  case 
where  the  decompression  algorithm  will 
encounter  an  undefined  code.  Because 
it  is,  in  fact,  the  only  case,  you  can  add 
an  exception  handler  to  the  algorithm. 
The  modified  algorithm  just  looks  for 
the  special  case  of  an  undefined  code 
and  handles  it.  In  the  example  in  Fig¬ 
ure  6,  the  decompression  routine  sees 
code  400,  which  is  undefined.  Because 
it  is  undefined,  it  translates  the  value 


Figure  5:  Sample  problem 


of  OLD_CODE ,  which  is  code  300.  It 
then  adds  the  CHARACTER  value,  J,  to 
the  string.  This  results  in  the  correct 
translation  of  code  400  to  string  JOEYNJ. 

The  Implementation  Blues 

The  concepts  used  in  the  compression 
algorithm  are  so  simple  that  the  whole 
algorithm  can  be  expressed  in  only  a 
dozen  lines.  But  because  of  the  man- 

Highly  redundant 
database  files  can  be 
compressed  to  ten  per¬ 
cent  of  their  original  size 


agement  required  for  the  string  table, 
implementation  of  this  algorithm  is  some¬ 
what  more  complicated. 

In  the  code  accompanying  this  arti¬ 
cle  (see  Listing  One),  1  have  used  code 
sizes  of  12-,  13- ,  and  14-bits.  In  a  12-bit 
code  program,  there  are  potentially  4096 
strings  in  the  string  table.  Each  and 
every  time  a  new  character  is  read  in, 
the  string  table  has  to  be  searched  for 
a  match.  If  a  match  is  not  found,  a  new 
string  has  to  be  added  to  the  table.  This 
causes  two  problems.  First,  the  string 


table  can  get  very  large  very  fast.  Even 
if  string  lengths  average  as  low  as  3  or 
4  characters  each,  the  overhead  of  stor¬ 
ing  a  variable  length  string  and  its  code 
can  easily  reach  7  or  8  bytes  per  code. 
In  addition,  the  amount  of  storage 
needed  is  indeterminate,  as  it  depends 
on  the  total  length  of  all  the  strings. 

The  second  problem  involves  search¬ 
ing  for  strings.  Each  time  a  new  charac¬ 
ter  is  read  in,  the  algorithm  has  to  search 
for  the  new  string  formed  by  STRING+ 
CHARACTER.  This  means  keeping  a 
sorted  list  of  strings.  Searching  for  each 
string  takes  on  the  order  of  log2  string 
comparisons.  Using  12-bit  words  po¬ 
tentially  means  doing  12-string  com¬ 
parisons  for  each  code.  The  computa¬ 
tional  overhead  can  be  prohibitive. 

The  first  problem  can  be  solved  by 
storing  the  strings  as  code/character 
combinations.  Because  every  string  is 
actually  a  combination  of  an  existing 
code  and  an  appended  character,  you 
can  store  each  string  as  a  single  code 
plus  a  character.  For  example,  in  the 
compression  example  shown,  the  string 
/WEE  is  actually  stored  as  code  260 
with  appended  character  E.  This  takes 
only  3  bytes  of  storage  instead  of  5 
(counting  the  string  terminator).  By  back¬ 
tracking,  you  find  that  code  260  is  stored 
as  code  256  plus  an  appended  charac¬ 
ter  E.  Finally,  code  256  is  stored  as  a 
/character  plus  a  W. 

Doing  the  string  comparisons  is  a 
little  more  difficult.  The  new  method 
of  storage  reduces  the  amount  of  time 
needed  for  a  string  comparison,  but  it 
doesn’t  cut  into  the  number  of  com¬ 
parisons  needed  to  find  a  match.  This 
problem  is  solved  by  using  a  hashing 
algorithm  to  store  strings.  What  this 
means  is  that  you  don’t  store  code  256 
in  location  256  of  an  array,  you  store  it 
in  a  location  in  the  array  based  on  an 
address  formed  by  the  string  itself.  When 
you  are  trying  to  locate  a  given  string, 
you  can  use  the  test  string  to  generate 
a  hashed  address  and,  with  luck,  can 
find  the  target  string  in  one  search. 

Because  the  code  for  a  given  string 
is  no  longer  known  merely  by  its  posi¬ 
tion  in  the  array,  you  need  to  store  the 
code  for  a  given  string  along  with  the 
string  data.  In  Listing  One,  there  are 
three  array  elements  for  each  string. 
They  are:  code_value[i],  prefix_code[i]. , 
and  append_character[i]. 

When  you  want  to  add  a  new  code 
to  the  table,  use  the  hashing  function 
in  routine  find_match  to  generate  the 
correct  i.  find_match  generates  an  ad¬ 
dress,  then  checks  to  see  if  the  location 
is  already  in  use  by  a  different  string.  If 
it  is,  find_match  performs  a  secondary 
probe  until  an  open  location  is  found. 

The  hashing  function  in  use  in  this 


Character  input 

Input  string: . . .  JOEYNJOEYNJOEY  .  .  . 

New  code  value  and  associated  string 

Code  output 

JOEYN 

300  =  JOEYN 

288  (JOEY) 

A 

301  =  NA 

N 

JOEYNJ 

400  =  JOEYNJ 

300  (JOEYN) 

JOEYNJO 

401  = JOEYNJO 

400 

ROUTINE  LZW_DECOMPRESS 
Read  OLD_CODE 
output  OLD_CODE 

WHILE  there  are  still  input  characters  DO 
Read  NEW_CODE 

IF  NEW_CODE  is  not  in  the  translation  table  THEN 
STRING  =  get  translation  of  OLD_CODE 
STRING  =  STRING+CHARACTER 
ELSE 

STRING  =  get  translation  of  NEW_CODE 
END  of  IF 
output  STRING 

CHARACTER  =  first  character  in  STRING 
add  OLD  CODE  +  CHARACTER  to  the  translation  table 
OLD_CODE  =  NEW_CODE 
END  of  WHILE 


Figure  6:  The  modified  decompression  algorithm 
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(continued  from  page  34) 
program  is  a  straightforward  xor-type 
hash  function.  The  prefix  code  and 
appended  character  are  combined  to 
form  an  array  address.  If  the  contents 
of  the  prefix  code  and  character  in  the 
array  are  a  match,  the  correct  address 
is  returned.  If  that  element  in  the  array 
is  in  use,  a  fixed  offset  probe  is  used 
to  search  new  locations.  This  contin¬ 
ues  until  either  an  empty  slot  is  found, 
or  a  match  is  found.  The  average  num¬ 
ber  of  searches  in  the  table  usually 
stays  below  3  if  you  use  a  table  about 
25  percent  larger  than  needed.  Per¬ 
formance  can  be  improved  by  increas¬ 
ing  the  size  of  the  table.  Note  that  in 
order  for  the  secondary  probe  to  work, 
the  size  of  the  table  needs  to  be  a  prime 
number.  This  is  because  the  probe  can 
be  any  integer  between  1  and  the  table 
size.  If  the  probe  and  the  table  size  are 
not  mutually  prime,  a  search  for  an 
open  slot  can  fail  even  if  there  are  still 
open  slots  available. 

Implementing  the  decompression  al¬ 
gorithm  has  its  own  set  of  problems. 
One  of  the  problems  from  the  com¬ 
pression  code  goes  away.  When  you 
are  compressing,  you  need  to  search 
the  table  for  a  given  string.  During  de¬ 
compression,  you  are  looking  for  a  par¬ 
ticular  code.  This  means  that  you  can 
store  the  prefix  codes  and  appended 
characters  in  the  table  indexed  by  their 
string  code.  This  eliminates  the  need 
for  a  hashing  function  and  frees  up  the 
array  used  to  store  code  values. 

Unfortunately,  the  method  used  to 
store  string  values  causes  the  strings 
to  be  decoded  in  reverse  order.  This 
means  that  all  the  characters  for  a  given 
string  have  to  be  decoded  into  a  stack 
buffer,  then  output  in  reverse  order.  In 
the  program  given  here,  this  is  done 
in  the  decode_string  function.  Once 
this  code  is  written,  the  rest  of  the 
algorithm  turns  into  code  easily. 

A  problem  encountered  when  read¬ 
ing  in  data  streams  is  determining  when 
you  have  reached  the  end  of  the  input 
data  stream.  In  this  particular  implemen¬ 
tation,  I  have  reserved  the  last  defined 
code,  MAX_  VALUE ,  as  a  special  end  of 
data  indicator.  Though  this  may  not  be 
necessary  when  reading  in  data  files,  it 
is  helpful  when  reading  compressed  buff¬ 
ers  out  of  memory.  The  expense  of 
losing  one  defined  code  is  minimal  in 
comparison  to  the  convenience  gained. 

Results 

It  is  somewhat  difficult  to  characterize 
the  results  of  any  data  compression 
technique.  The  level  of  compression 
achieved  varies  quite  a  bit,  depending 
on  several  factors.  LZW  compression 
excels  when  confronted  with  data 


streams  that  have  any  type  of  repeated 
strings.  Because  of  this,  it  does  ex¬ 
tremely  well  when  compressing  Eng¬ 
lish  text.  Compression  levels  of  50  per¬ 
cent  or  better  can  be  expected.  Like¬ 
wise,  compressing  saved  screens  and 
displays  generally  shows  great  results. 
Trying  to  compress  data  files  is  a  little 
more  risky.  Depending  on  the  data, 
compression  may  or  may  not  yield  good 
results.  In  some  cases,  data  files  com¬ 
press  even  more  than  text.  A  little  bit 
of  experimentation  usually  gives  you 
a  feel  for  whether  your  data  will  com¬ 
press  well  or  not. 

Your  Implementation 

The  code  accompanying  this  article 
works.  It  was  written,  however,  with 
the  goal  of  being  illuminating,  not  effi¬ 
cient,  with  some  parts  of  the  code  be¬ 
ing  relatively  inefficient.  The  variable 
length  input  and  output  routines,  for 
example,  are  short  and  easy  to  under¬ 
stand,  but  require  a  lot  of  overhead. 
You  could  experience  real  improve¬ 
ments  in  speed  in  an  LZW  program 
using  fixed-length  12-bit  codes,  just  by 
recoding  these  two  routines. 

One  problem  with  the  code  listed 
here  is  that  it  does  not  adapt  well  to 
compressing  files  of  differing  sizes.  Us¬ 
ing  14-  or  15-bit  codes  gives  better 
compression  ratios  on  large  files  (be¬ 
cause  they  have  a  larger  string  table  to 
work  with),  but  poorer  performance 
on  small  files.  Programs  such  as  ARC 
get  around  this  problem  by  using  vari¬ 
able  length  codes.  For  example,  when 
the  value  of  next_code  is  between  256 
and  511,  ARC  inputs  and  outputs  9-bit 
codes.  When  the  value  of  next_code 
increases  to  the  point  where  10-bit  codes 
are  needed,  both  the  compression  and 
decompression  routines  adjust  the  code 
size.  This  means  that  the  12-bit  and 
15-bit  versions  of  the  program  do 
equally  well  on  small  files. 

Another  problem  on  long  files  is  that 
frequently  the  compression  ratio  be¬ 
gins  to  degrade  as  more  of  the  file  is 
read  in.  The  reason  for  this  is  simple: 
Because  the  string  table  is  of  finite  size, 
after  a  certain  number  of  strings  have 
been  defined,  no  more  can  be  added. 
But  the  string  table  is  good  only  for  the 
portion  of  the  file  that  was  read  in 
while  it  was  built.  Later  sections  of  the 
file  may  have  different  characteristics 
and  really  need  a  different  string  table. 

The  conventional  way  to  solve  this 
problem  is  to  monitor  the  compression 
ratio.  After  the  string  table  is  full,  the 
compressor  watches  to  see  if  the  com¬ 
pression  ratio  degrades.  After  a  certain 
amount  of  degradation,  the  entire  table 
is  flushed  and  gets  rebuilt  from  scratch. 
The  expansion  code  is  flagged  when 


this  happens  because  the  compression 
routine  sends  out  a  special  code.  An 
alternative  method  is  to  keep  track  of 
how  frequently  strings  are  used,  and 
to  periodically  flush  values  that  are  rarely 
used.  An  adaptive  technique  like  this 
may  be  too  difficult  to  implement  in  a 
reasonable-sized  program. 

One  final  technique  for  compressing 
the  data  is  to  take  the  LZW  codes  and 
run  them  through  an  adaptive  Huffman 
coding  filter.  This  generally  exploits  a 
few  more  percentage  points  of  com¬ 
pression,  but  at  the  cost  of  consider¬ 
ably  more  complexity  in  the  code  as 
well  as  quite  a  bit  more  run  time. 

Portability 

The  code  in  Listing  One  was  written 
and  tested  on  MS-DOS  machines  and 
has  successfully  compiled  and  executed 
with  several  C  compilers.  It  should  be 
portable  to  any  machine  that  supports 
16-bit  integers  and  32-bit  longs  in  C. 
MS-DOS  C  compilers  typically  have 
trouble  dealing  with  arrays  larger  than 
64K  bytes,  preventing  an  easy  implemen¬ 
tation  of  15-  or  16-bit  codes  in  this 
program.  On  machines  using  different 
processors,  such  as  the  VAX,  these  restric¬ 
tions  are  lifted,  and  using  larger  code 
sizes  becomes  much  easier. 

In  addition,  porting  this  code  to  as¬ 
sembly  language  should  be  fairly  easy 
on  any  machine  that  supports  16-  and 
32-bit  math,  and  offers  significant  per¬ 
formance  improvements.  Implementa¬ 
tions  in  other  high-level  languages 
should  be  straightforward. 

Bibliography 

Terry  Welch,  “A  Technique  for  High- 
Performance  Data  Compression,”  Com¬ 
puter,  June  1984. 

J.  Ziv  and  A.  Lempel,  “A  Universal 
Algorithm  for  Sequential  Data  Com¬ 
pression,”  IEEE  Transactions  on  Infor¬ 
mation  Theory,  May  1977. 

Rudy  Rucker,  Mind  Tools,  Houghton 
Mifflin  Company,  Boston,  Mass.:  1987. 

Availability 

All  source  code  for  articles  in  this  issue 
is  available  on  a  single  disk.  To  order, 
send  $14.95  (Calif,  residents  add  sales 
tax)  to  Dr.  Dobbs  Journal,  501  Galves¬ 
ton  Dr.,  Redwood  City,  CA  94063,  or 
call  800-356-2002  (from  inside  Calif.) 
or  800-533-4372  (from  outside  Calif.). 
Please  specify  the  issue  number  and 
format  (MS-DOS,  Macintosh,  Kaypro). 

DDJ 

(Listing  begins  on  page  86.) 

Vote  for  your  favorite  feature/article. 

Circle  Reader  Service  No.  2. 


36 


Dr.  Dobb's Journal,  October  1989 

683 


High-Speed 
File  Transfers  With 

NetBIOS 

Don’t  let  normal  serial  communication  slow  you  down 


Costas  Menico 


If  you  regularly  transfer  large 
amounts  of  data  between 
PCs,  you’re  familiar  with  the 
time-consuming  constraints  of 
1200-,  2400-,  or  even  9600- 
baud  communications.  No  doubt 
you’ve  wished  more  than  once  you 
could  transfer  files  at  speeds  that 
local  area  network  (LAN)  users 
have  become  used  to;  speeds  as 
(relatively)  low  as  2,500,000  bits/ 
sec.  (2.5-Mbits/sec.)  for  ARCnet, 
to  as  high  as  10-Mbits/sec.  for 
Ethernet. 

Considering  that  in  many  environ¬ 
ments,  LANs  are  getting  to  be  as 
prevalent  as  hard  disks,  high-speed 
file  exchange  using  LAN  facilities 
is  becoming  increasingly  common. 

But  even  if  you  don’t  have  access 
to  a  LAN,  it’s  still  possible  to  use 
LAN  adapter  cards,  which  now  sell  for 
as  low  as  $100  to  $200  each,  as  a 
means  of  exchanging  files  at  high 
speeds  between  two  (or  more)  PCs. 
You  don’t  even  need  the  network  server 
or  operating  system  to  do  so.  All  you 
need  are  the  cards,  a  cable,  and  a  quasi¬ 
standard  driver  called  NetBIOS,  which 
is  usually  supplied  or  sold  with  most 
LAN  adapter  cards  —  and  the  program 
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I’ll  describe  in  this  article. 

The  program,  which  I  call  XNet,  is  a 
custom  file  transfer  program  that  uses 
the  NetBIOS  interface.  The  nice  thing 
about  the  program  is  you  don’t  have 
to  concern  yourself  with  the  usual  se¬ 
rial  communications  nuisances  —  error 
corrections,  checksums,  baud  rates,  and 
such.  NetBIOS  does  all  this  (and  more) 
for  you.  The  program  doesn’t  even  have 
to  wait  around  to  receive  data  because 
NetBIOS  can  notify  your  routine  when 
there  is  data  and  let  you  know  if  a  data 
transfer  to  another  node  failed.  The 
beauty  of  all  this  is  that  data  is  trans¬ 
ferred  from  2.5-Mbits/sec.  to  10-Mbits/ 
sec.,  depending  on  the  type  of  adapter 
cards  you’re  using. 


The  NetBIOS  Interface 

NetBIOS  is  usually  loaded  into  DOS 
as  a  device  driver  from  the  CON¬ 
FIG.SYS.  Follow  the  board  manu¬ 
facturer’s  installation  guidelines.  Be¬ 
fore  calling  NetBIOS,  you  must  set 
the  command  and  other  parame¬ 
ters  in  the  message  control  block 
(MCB).  You  then  load  the  register 
pair  ES:BX  with  the  segment  and 
offset  address  of  the  MCB.  To  call 
the  NetBIOS,  you  execute  an  inter¬ 
rupt  5Ch.  For  a  list  of  NetBIOS 
commands,  see  Figure  1;  for  the 
structure  of  the  MCB,  refer  to  Fig¬ 
ure  2.  When  the  interrupt  com¬ 
pletes,  you  check  the  mcb_retcode 
for  a  successful  completion.  If  it  is 
non-zero,  it  usually  means  there 
was  a  problem  that  your  program 
must  react  to. 

Although,  not  implemented  in  the 
XNet  program,  a  feature  that  needs  spe¬ 
cial  attention  must  be  explained.  Most 
commands  allow  you  to  call  with  the 
no-wait  bit  (bit  8)  set.  This  means  that 
after  you  have  executed  the  call  to 
NetBIOS,  you  do  not  have  to  wait  for 
the  completion.  Rather,  NetBIOS  noti¬ 
fies  you  by  calling  a  designated  routine 
called  a  “post  routine.”  The  post  is  an 
interrupt-like  function  that  you  write, 
and  whose  address  you  set  in  the 
mcb_  post  field  of  the  MCB.  When  your 
routine  is  finally  called,  your  program 
then  checks  the  MCB  for  errors,  or  any 
other  relevant  fields.  This  is  a  powerful 
feature,  for  without  it,  most  network 
software  would  not  work  so  elegantly. 
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MCB  Explained 

The  MCB  fields  are  set  by  your  pro¬ 
gram  before  calling  the  NetBIOS  and 
are  set  again  by  NetBIOS  after  the  call. 
You  may  have  many  independent  MCBs 
as  long  as  you  point  ES:BX  to  the  right 
one  before  calling  NetBIOS.  Not  all 
commands  use  all  the  fields. 

The  first  and  most  important  field  is 
the  mcb_command.  Here,  you  set  the 
code  for  the  command  you  wish  to 
execute  (see  Figure  1).  The  next  field, 
mcb_retcode,  is  where  the  completion 
return  code  is  set  by  NetBIOS.  It  must 
be  set  to  FFh  before  calling  NetBIOS. 
The  session  number  mcb_lsn  is  returned 


to  your  program  by  the  NetBIOS  after 
a  successful  connection  with  another 
node  on  the  system.  You  use  this  for 
all  interactions  with  that  particular  node. 
The  number  mcb_num  identifies  a  lo¬ 
cal  node  name  in  the  adapter  card, 
while  mcb_buffer  is  a  pointer  to  the 
data  buffer  for  receiving  or  sending 
blocks  of  data.  The  mcb_length  deter¬ 
mines  the  length  of  the  data  in  the 
mcb_buffer,  mcb_callname ,  and  mcb_ 
name  are  the  names  used  when  calling 
or  listening  for  another  node.  The  send 
and  receive  time-out  values  are  mcb_rto 
and  mcb_sto.  If  they  are  set  to  zero, 
there  will  never  be  a  data  transmission 


time-out  because  of  a  problem  or  delay 
on  the  network  due  to  other  traffic. 
The  mcb_  post  field  is  set  to  point  to 
our  interrupt  routine  handler  when  we 
call  NetBIOS  with  the  no-wait  in  the 
command  field  bit  set.  The  LAN  card 
number,  usually  set  to  0,  is  mcb_  lana_ 
num ,  and  mcb_cmd_cpl  is  a  command 
completion  code  when  we  call  NetBIOS 
with  the  no-wait  bit  in  the  command 
field  set.  The  mcb_reserve  field  is  used 
to  fill  in  information  by  some  NetBIOS 
commands. 

NetBIOS  Commands 

As  you  can  see  from  Figure  1 ,  the  Net¬ 
BIOS  has  quite  an  assortment  of  com¬ 
mands.  For  now,  I'll  explain  only  the 
commands  used  in  the  XNet  program. 

The  first  command  is  the  msg_reset , 
which  resets  the  LAN  adapter  card  and 
clears  out  any  node  names  it  may  have 
been  using.  You  should  only  use  this 

With  XNet  you  don’t 
have  to  concern  yourself 
with  the  usual  serial 
communications 
nuisances  —  error 
corrections,  checksums, 
baud  rates,  and  such. 
NetBIOS  does  all  this 
( and  more)  for  you 


command  if  no  other  software  is  using 
the  LAN  card  at  the  time.  The  com¬ 
mand  msg_status  returns  the  LAN  card’s 
node  address,  a  unique  number  be¬ 
tween  1  and  255,  depending  upon  the 
installation  of  your  LAN  adapter.  No 
two  adapters  can  have  the  same  node 
number.  The  msg_add_name  command 
allows  your  node  to  be  known  by  some 
arbitrary,  unique  name  on  the  network. 
Your  node  can  have  multiple  names, 
but  no  two  nodes  can  have  the  same 
name.  The  msg_listen  command  makes 
your  program  wait  for  someone  to  talk 
to  you  and  is  the  opposite  of  msg_call. 
Together  they  use  each  other’s  names 
to  establish  a  session.  The  commands 
msg_send  and  tnsg_receive  send  and 
receive  data  via  mcb_bujfer  and  msg_ 
hang_up,  which  hang  up  any  session 
with  another  node. 
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NetBIOS  commands  used  in  this  program 

msg„reset=$32; 

Reset  the  node 

msg_status=$33; 

Determine  the  current  state  of  the  node 

msg_add_name=$30 ; 

Add  a  16  char  unique  node  name  to  NetBIOS 

msg_listen=$11; 

Listen  for  a  node  to  establish  session 

msg_call=$10; 

Call  another  node  to  establish  a  session 

msgjiang_up=$12; 

Hangup  the  session  with  a  node 

msg_send=$1 4; 

Send  a  block  of  data  to  a  node 

msg_receive=$15; 

Receive  a  block  of  data  from  a  node 

Other  NetBIOS  commands 

msg_add_group_name=$36; 

Add  a  group  name 

msg_cancel=$35; 

Cancel  the  last  MCB  command 

msg_chain__send=$1 7; 

Send  2  data  buffers,  one  after  another 

msg„deletejiame=$31 ; 

Delete  a  name  from  the  adapter 

msgjind_name=$78; 

Find  a  a  node  name  on  the  LAN 

msg_receive_any=$1 6; 

Receive  from  any  session  partner 

1  msg_receive_broadcast_datagram=$23;  Datagram  from  any  node  on  LAN 

msg_receive_datagram=$21 ; 

Datagram  from  a  specific  name/group 

msg_send_broadcast_datagram=$22;  Datagram  to  anyone  on  LAN  : 

msg_send_datagram=$20; 

Datagram  to  specific  name/group 

msg_session_status=$34; 

Status  of  a  session 

Figure  1:  NetBIOS  commands  and  values 


buffer=array[l  ..buffsize]  of  byte; 

Buffer  type  declaration 

buffp=Abuffer; 

Pointer  type  to  the  buffer 

arrname=array[1  ..16]  of  char; 

Array  for  names  type 

Message  control  block  record 

mcb=record 

mcb  command:  byte; 

Command  to  execute 

mcb  retcode:  byte; 

Return  code  value 

mcbjsn:  byte; 

Local  session  # 

mcb  num:  byte; 

Number  of  name  added 

mcb_buffer:  pointer; 

Data  buffer  address 

mcbjength:  word; 

Buffer  length  in  bytes 

mcb^callname:  arrname; 

Name  on  remote  node 

mcb  name:  arrname; 

Name  of  local  node 

mcb_rto:  byte; 

Receive  timeout  (NOT  USED) 

mcb_sto:  byte; 

Send  timeout  (NOT  USED) 

mcb_post:  pointer; 

Post  routine  address  (NOT  USED) 

mcb_lana_num:  byte; 

Adapter  card  to  use.  0  is  first 

mcb_cmd_cpl:  byte; 

Command  status  if  NOWAIT  is  used 

mcb  reserve:  array[1.  .14]  of  byte; 

Other  detailed  info 

end; 

Figure  2:  NetBIOS  message  control  block 
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Your  program  could  be  communicat¬ 
ing  with  many  nodes  at  once,  provided 
you  have  established  a  unique  session 
with  them.  Each  session  has  its  own 
number  that  is  used  for  this  purpose. 

The  XNet  File  Transfer  Program 

Even  though  I  chose  to  write  XNet  in 
Turbo  Pascal  (see  Listing  One,  page 
88),  you  can  use  C,  or  for  time/space 
critical  functions,  assembler.  The  pro¬ 
gram  is  as  simple  as  you  can  get  for 
transferring  data  from  one  node  to  the 
other.  I  did  not  use  the  no-wait  capabil¬ 
ity;  the  program  must  be  run  simulta¬ 
neously  on  each  system  (run  it  on  node 
A  first,  and  then  run  it  on  node  B). 

I  programmed  each  NetBIOS  func¬ 
tion  into  a  procedure  call  passing  the 
required  parameters.  All  the  procedures 
start  with  net_.  The  procedure  init_mcb 
is  called  to  set  the  MCB  to  a  known 
state.  Then  each  one  of  the  commands 
sets  the  calling  parameters  before  execut¬ 
ing  an  interrupt  5Ch. 

Notice  that  net_reset  and  net_status 
check  if  the  NetBIOS  driver  is  installed. 
This  is  done  by  checking  if  the  5Ch 
vector  value  is  set  to  a  non-zero  value. 
Any  errors  during  a  call  to  NetBIOS 
will  cause  a  message  indicating  the  com- 

Even  if  you  don ’t  have 
access  to  a  LAN,  it’s  still 
possible  to  use  LAN 
adapter  cards,  which 
now  sell  for  as  low  as 
$100  to  $200  each,  as 
a  means  of  exchanging 
files  at  high  speeds 
between  PCs 


mand  and  error  code  (in  hex)  to  be 
displayed  on  the  screen.  The  program 
then  terminates  by  calling  the  termi¬ 
nate  function. 

Although  XNet  should  work  with  any 
adapter  board  configuration  that  sup¬ 
ports  NetBIOS,  I  tested  it  on  PC210 


ARCnet  boards  from  Standard  Microsys¬ 
tem  Corp.  (Long  Island,  N.Y.)  using 
their  NetBIOS. 

My  CONFIG.SYS  file  had  the  follow¬ 
ing  line  which  tells  NetBIOS  the  port, 
the  IRQ,  and  the  memory  buffer  for  the 
board; 

DEVICE=SMCARC.SYS  /P2E0  /I2  / 

ME000. 

To  compile  the  program,  simply  com¬ 
pile  to  disk.  To  run  the  EXE  file,  type 
XNET  at  the  DOS  prompt. 

Start  the  program  on  whatever  nodes 
will  be  talking  to  each  other.  You'll  first 
see  your  node's  number  on  the  screen, 
and  then  you’ll  be  prompted  for  the 
remote  node’s  number  (a  number  be¬ 
tween  1  and  255). 

You  are  now  ready  to  receive  on  one 
station  and  send  on  the  other.  On  sta¬ 
tion  A,  select  Receive  and  give  the  file 
name  to  save  into.  On  station  B,  select 
Send  and  give  the  file  name  to  send. 
As  soon  as  you  give  the  file  name  to 
send,  the  program  will  transmit  the  file, 
showing  in  bytes  the  size  of  the  file 
transferred.  For  small  files  (around 
128K),  the  transfer  is  practically  instan¬ 
taneous.  In  cases  of  a  message  specify¬ 
ing  the  error  code,  the  command  code 
the  error  occurred  on  will  appear. 

Program  Flow 

When  the  program  is  started  up,  it  will 
first  call  the  net_reset  procedure.  This 
initializes  the  board  and  checks  that 
you  have  NetBIOS  running.  After  the 
reset,  the  program  calls  net_status  to 
get  the  node’s  number.  This  is  the  first 
byte  of  the  data  pointed  to  by  mcb_ 
buffer.  For  convenience,  I  use  this  num¬ 
ber  as  the  name  of  the  node  by  con¬ 
verting  it  to  a  string  and  calling  net_ 
add_name.  For  the  other  node  to  com¬ 
municate,  it  must  use  this  name. 

The  program  will  then  prompt  for 
the  remote  node’s  number  which  must 
be  different  from  the  local.  It  will  then 
ask  if  you  wish  to  Send,  Receive,  or 
Exit.  If  you  choose  Exit,  the  program 
terminates  by  calling  the  procedure  Ter¬ 
minate.  If  you  choose  Send,  it  will  call 
the  procedure  setup_call_send ,  and  for 
Receive,  it  will  call  setup_listen_receive. 

The  procedure  setup_listen_receive 
asks  for  the  file  name  to  save  to.  If  the 
file  exists,  it  will  ask  you  to  overwrite 
it.  It  will  then  proceed  to  listen  for  a 
call  from  the  remote  node  using  the 
function  net_listen,  and  wait  indefinitely. 

The  setup_call_send  procedure  asks 
for  the  file  name  to  send,  verifies  its 
existence,  and  calls  the  remote  node 
using  the  function  net_call.  If  the  re¬ 
mote  node  is  not  listening,  it  prints  a 
message  to  Retry  or  Abort.  If  you  abort, 


the  program  terminates;  otherwise,  it 
reexecutes  the  net_call. 

Once  the  two  nodes  establish  a  ses¬ 
sion  via  the  above  description,  a  ses¬ 
sion  number  is  returned  by  NetBIOS. 
This  session  number  is  then  used 
to  send  the  file  and  receive  it  on  the 
other  end.  The  procedures  sendjhe  Jile 
and  receivejthe _Jile  will  perform  this 
function. 

The  file  is  sent/received  using  net_ 
send  and  net_receive ,  respectively.  The 
first  send  is  a  4-byte  (2  word)  file  size 
number  that  tells  the  receiver  how  big 
a  file  to  expect.  The  sender  will  send 
the  file  in  chunks  of  64K  bytes  with  the 
last  chunk  being  the  remainder  of  the 
64K.  As  soon  as  the  file  size  is  reached, 
they  both  terminate  by  calling  termi¬ 
nate.  If  there  is  a  disk  error  (such  as 
disk  full)  during  the  receive,  the  pro¬ 
gram  terminates  by  hanging  up  —  us¬ 
ing  net_hang_up  and  calling  the  termi¬ 
nate  function. 

Technical  References 
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Shower,  First,  Though 

“In  any  development  environment,  no 
single  programming  tool  is  sufficient  to 
satisfy  every  need.  Any  instrument  or 
methodology  that  can  spare  us  from  the 
tedium  of  a  routine  chore,  or  enable  us  to 
become  more  productive,  should  be 
embraced  with  open  arms.”  —  Charles  F. 
Bowman,  Pattern  Matching  Using  Finite 
State  Machines,  "  DDJ ,  October,  1987. 
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Finite 

State  Machines 

for  XModem 

FSMs  are  one  way  to  cope  with  the 
chaos  of  communications 


Donald  W.  Smith 


Even  though  my  coworkers 
often  refer  to  me  as  a  “Com¬ 
mie,"  I  don’t  take  offense 
because  my  specialty  is  data 
communications  and  net¬ 
working,  an  area  of  computer  sci¬ 
ence  that  is  often  overlooked  in 
favor  of  more  stimulating  topics  such 
as  compiler  technology.  But  what 
we  Commies  do  and  what  com¬ 
piler  writers  do  aren’t  that  much 
different,  particularly  because  we 
share  an  important  tool  called  “fi¬ 
nite  state  automata”  (FSA).  The  main 
difference  between  what  they  do 
and  what  we  do  is  where  we  get 
our  events.  Compiler  events  come 
from  source  code  files  (text  tokens), 
while  most  communication  events 
come  from  another  computer,  or 
from  strange  things  in  between. 

This  article  presents  a  more  general¬ 
ized  description  of  FSA,  one  in  which 
data  structures  and  code  are  used  to 
implement  XModem,  a  well-understood 
communications  protocol,  using  a  tech¬ 
nique  that  is  general  enough  to  be  imple¬ 
mented  with  just  about  any  other  pro¬ 
tocol  as  well.  The  goal  here  is  to  ex¬ 
plain  how  to  use  standard  C  language 
constructs  to  write  dependable,  maintain- 


Don  is  a  senior  course  developer  and 
instructor  for  Wide  Area  Network  Sys¬ 
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at  7029  Via  Del  Rio,  San  Jose,  CA  95139 
or  on  CompuServe:  76515,3406. 


able  programs  using  finite  state  ma¬ 
chines  (FSM).  The  applications  include 
other  communications  protocols,  real¬ 
time  data  acquisition,  or  just  about  any¬ 
thing  with  a  fairly  predictable  flow  of 
events. 

Lexical  Analyzers  and  Such 

The  Unix  environment  provides  a  num¬ 
ber  of  specialized  tools,  YACC  (yet  an¬ 
other  compiler  compiler)  and  LEX  (a 
lexical  analyzer),  for  instance,  that  are 
designed  to  maintain  the  sanity  of  com¬ 
piler  writers.  YACC  utilizes  grammati¬ 
cal  rules  that  can  have  associated  ac¬ 
tions.  YACC  can  be  adapted  to  gener¬ 
ate  FSM-type  machines,  but  requires 
that  you  learn  "yet  another  set  of  syn¬ 
tax.”  (YASS?) 


Other  utilities  have  also  appeared 
to  generate  FSM  code.  They  are  all 
valid  techniques,  if  the  tool  is  well 
understood  by  developers  as  well 
as  maintainers.  But  all  require  an 
extra  level  of  “indirection"  in  the 
coding  process  to  learn  a  special¬ 
ized  tool.  The  technique  I  exam¬ 
ine  in  this  article  does  not  use 
smoke  screens  or  mirrors  and  re¬ 
quires  only  a  standard  C  compiler. 

Finite  State  Basics 

Finite  state  machines  are  directed 
graphs  where  nodes  are  called 
states,  and  arcs  are  actions  (or  tran¬ 
sitions).  Each  state  includes  a  well- 
defined  set  of  events.  There  must 
be  an  action  and  a  next  state  de¬ 
fined  for  each  event,  even  if  the 
action  is  a  null  action.  Events  drive 
the  machine  from  state  to  state.  Once 
a  good  starting  state  is  established  and 
an  initial  event  has  come  in,  the  ma¬ 
chine  is  off  and  running. 

State  Diagrams 

State  diagrams  are  often  used  to  docu¬ 
ment  state  machines.  Figure  1  is  the 
state  diagram  for  XModem  receive.  The 
receive  machine  (Figure  2)  uses  a  total 
of  four  states  (the  circles),  with  a  maxi¬ 
mum  of  four  events  each.  As  the  num¬ 
ber  of  events  increases,  the  state  dia¬ 
grams  sacrifice  some  attractiveness.  The 
final  state  (Exit)  is  used  only  to  help 
human  readers;  it  does  not  respond  to 
events,  and  is  not  included  in  the  dia¬ 
gram.  Each  event  directs  the  machine 
to  an  action,  illustrated  by  a  box  with 
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rounded  corners.  All  actions  in  this  ex¬ 
ample  are  passed  parameters,  which 
are  usually  # defines  and  are  shown  in 
parentheses.  Some  actions  are  shared 


by  multiple  events,  for  instance,  Frame_ 
Wait(RESEND).  Unfortunately,  there  is 
no  “Industry  Standard”  state  diagram 
for  the  XModem  protocol.  (Ward  Chris¬ 


tensen  isn’t  the  only  one  who  forgot 
this  step.  But  then  again,  CP/M  ma¬ 
chines  didn’t  do  graphics  well.)  The 
state  diagram  in  Figure  1  is  exceptionally 
short  and  sweet  because  the  protocol 
is  simple. 

Coding  Technique 

There  are  many  ways  to  implement 
finite  state  machines.  One  method,  us¬ 
ing  a  precompiler  (similar  to  LEX  and 
YACC),  adds  an  extra  layer  of  syntax 
on  top  of  the  source  code  to  identify 
states,  events  and  actions.  Remember, 
FSA  are  normally  a  compiler  writer’s 
game.  What  could  be  more  natural  than 

You  can  use  C  to 
write  dependable, 
maintainable  programs 
using  finite  state 
machines 


yet  another  language?  The  output  C 
code  is  often  strewn  with  labels  and 
GOTOs,  which  are  not  part  of  my  struc¬ 
tured  programming  vocabulary. 

It  is  also  possible  to  limit  the  number 
of  global  variables  (thus,  side  effects) 
when  hand  coding  state  machine  logic. 
This  provides  stand-alone  send  and  re¬ 
ceive  modules  that  share  a  short  list  of 
external  variables.  A  short  list  of  global 
variables  in  each  module  is  declared 
static,  to  prevent  them  from  slipping 
past  the  guards  at  the  file  door. 

The  C  language  provides  the  data 
type  of  pointer  to  function  that  is  as 
flexible  as  using  GOTOs  and  labels, 
but  also  provides  a  series  of  advan¬ 
tages,  such  as  that  parameters  can  be 
passed,  values  can  be  returned,  and 
block  structuring  maintained. 

Static  Tables 

Data  structures  may  be  initialized  with 
anything  that  is  a  constant  at  compile 
time.  Function  pointers  and  pointers 
to  variable  locations  fully  qualify,  but 
the  contents  of  variables  do  not. 

XMRECV  (see  Listing  Three,  page 
92)  shows  the  initialized  state  table  us¬ 
ing  function  pointers  to  actions  ( A_ .  .  .  ). 
The  parameter  field  is  defined  as  an 
int.  This  int  parameter  conveniently 
accommodates  pointers  to  anywhere 
in  the  small  model. 

Most  state  machines  use.  actions  that 
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(continued  from  page  46) 
are  inherently  simple,  and  rely  on  entry 
points  (labels)  to  prevent  duplication 
of  code.  This  technique  uses  standard 
functions  for  actions  which  naturally 
take  parameters.  This  code  requires  all 
functions  to  accept  a  single  in!  pa¬ 
rameter,  due  to  the  struct  used  for  the 
state  table.  Other  parameter  types  are 
casted  to  int  as  required. 

Unfortunately,  this  technique  is  not 
universally  portable.  For  example,  if 
pointers  occupy  more  than  the  size  of 
an  int,  a  larger  data  type  should  be 
substituted  to  hold  them. 

Code  Walkthrough 

The  FSM  presented  here  consists  of 
five  modules.  Listing  One  (page  92), 
CTERM.H,  and  Listing  Two  (page  92), 
COMMN.H,  define  the  system.  Most  of 
my  discussion,  however,  will  concen¬ 
trate  on  the  short  “main  loop”  of  the 
XMRECV.C  file  in  Listing  Three.  The 
same  technique  is  also  used  in  the 
XMSEND.C  module  (Listing  Four,  page 
94),  but  refers  to  a  different  state  table. 
The  action  functions  speak  for  them¬ 
selves  and  illustrate  the  XModem  pro¬ 
tocol,  which  has  been  done  before. 
CTERM1.C,  Listing  Five,  page  100,  is  a 
terminal  emulator  that  demonstrates  the 
use  of  state  machine  driven  communi¬ 
cations  protocols  using  the  C  language. 
Use  makectl  in  Listing  Six  (page  103) 
to  compile  CTERM1.C. 

The  story  normally  starts  in  terminal 
mode.  To  receive  a  file,  press  the  PgDn 
key  to  get  into  the  xmodem_recv( ) 
module.  Note  that  the  mode  variable 
is  set  to  M_XRecv  on  the  way  out  of 
terminal  mode.  The  initial  action  of 
A_Prep_Recv( )  returns  the  first  event 
and,  hopefully,  a  valid  file  name.  A 
while  (mode  ==  M_XRecv)  loop  takes 
control  until  something  good  (or  really 
bad)  happens. 

Within  the  while  loop,  a  copy  of  the 
event  is  made  for  future  reference.  (Sort 
of  like  saving  yesterday’s  newspaper, 
right?)  Then  a  pointer  is  set  up  for 
easier  access  to  the  current  state  table 
entry  (cur_entry).  The  current  state  and 
event  of  the  state  machine  is  then  traced, 
if  tracing  was  enabled  at  compile  time. 
The  predefined  action  to  execute  is 
determined  then  called,  passing  the  ap¬ 
propriate  parameter.  Notice  that  the 
event  variable  is  filled  with  the  return 
value  from  the  function  call  to  new_ 
action( ).  Before  leaving,  the  system 
determines  a  new  current  state  from 
the  next_state  field  of  the  state  table. 

In  this  case,  the  user  should  be  pre¬ 
sented  with  the  opportunity  to  abort 
at  any  time.  The  routine  keyfun( )  pro¬ 
vides  this  capability,  without  allowing 
the  dreaded  (Control-C)  display  or 


program  termination.  Programs  that  al¬ 
ter  interrupt  vectors  should  not  abort 
without  putting  things  back  the  way 
they  were.  One  single  character  is  de¬ 
fined  to  be  the  escape  character  (de¬ 
fault  is  ESC)  that  takes  you  out  of  the 
M_XRecv  via  a  call  to  the  action  A_ 
Recv_End(  ). 

This  code  could  be  tighter  and  run 
faster,  but  a  few  extra  variables  help 
follow  the  action  and  keep  the  code 
more  readable.  Hopefully,  smart  com¬ 
pilers  will  use  registers  where  possible 
anyway. 

Most  state  machines  use 
actions  that  are 
inherently  simple  and 
rely  on  entry  points 
(labels)  to  prevent 
duplication  of  code 


Designing  States 

One  of  the  most  challenging  aspects 
of  designing  good  state  machines  is 
determining  how  many  states  there 
should  be.  There  are  no  hard  and  fast 
rules.  This  is  one  of  those  areas  of 
“fuzzy  logic”  that  intelligent  humans 
were  built  to  handle.  The  goal  is  to 
define  states  where  only  a  limited  num¬ 
ber  of  events  can  occur.  That  number 
is  up  to  the  designer,  but  normally 
should  not  exceed  ten. 

It  is  easier  to  define  the  structure  to 
hold  the  initialized  state  table  if  all  states 
have  the  same  number  of  valid  events. 
It  could  be  an  interesting  exercise  for 
the  reader  to  design  a  state  table  with  a 
variable  number  of  events  for  each  state. 

The  following  are  a  few  notes  to 
keep  in  mind  while  determining  how 
many  states  to  define: 

•  Use  a  flowchart  of  tasks  to  help  de¬ 
rive  the  state  diagram 

•  keep  the  main  path  clean  (as  few 
states/actions  as  possible) 

•  decide  which  return  value  means  “All’s 
Well."  Maybe  0? 

Actions  and  Reactions 

Actions  are  functions  that  do  work  and 
return  events.  Most  actions  normally 
do  not  call  other  actions  and  perform 
fairly  simple  tasks.  It  is  often  necessary 


to  maintain  some  idea  of  context  be¬ 
tween  calls.  For  example,  the  A_Frame_ 
Wait  action  maintains  internal  (static) 
counters  for  retries  while  waiting  for  a 
response  to  a  control  character  sent 
(Ack,  Nak,  and  so  on). 

Remember  that  states  do  no  work. 
(The  Governor  of  California  would  prob¬ 
ably  take  exception  to  my  last  state¬ 
ment,  but  then  I’d  have  been  quoted 
out  of  context.)  Actions  are  where  the 
actual  work  is  done. 

The  action  Validate( )  probably  does 
the  most  work  in  the  receive  logic.  It 
updates  the  screen’s  packet  counter 
and  waits  for  the  interrupt  handler  to 
finish  receiving  the  frame.  It  then  checks 
the  packet  header  and  the  packet  CRC/ 
Checksum,  and  finally  writes  the  packet 
data  to  disk  if  all  is  well.  Validate <  ) 
also  has  the  authority  to  advance  the 
(file)  global  packet  counter  (pkt)  be¬ 
fore  returning  0,  if  all  is  well. 

Some  protocol  purists  may  notice 
that  it  is  possible  to  tolerate  more  than 
a  one-second  delay  between  charac¬ 
ters.  But  some  networks  in  use  today 
cannot  always  guarantee  such  a  lux¬ 
ury.  Validated  )  returns  a  TIMEOUT  only 
after  two  successive  one-second  time¬ 
outs.  Remember  that  we  already  have 
seen  the  SOH,  and  should  not  need  to 
wait  much  longer. 

XModem  uses  a  fixed  frame  size, 
which  differs  significantly  from  other 
common  protocols.  Protocols  with  an 
ETX  (end  of  text)  signifying  the  end  of 
a  variable  size  frame,  should  use  an¬ 
other  state  (and  action)  to  receive  the 
frame  before  validating.  It  is  too  slow 
to  wait  for  a  deadline  and  start  looking 
backwards.  Table  1  shows  a  trace  of  a 
successful  receive  of  three  record  files 
while  Table  2  lists  the  three  states  in¬ 
volved  in  receiving  a  packet. 

Layers  and  Levels 

The  OSI  Reference  model  seems  to  have 
been  described  in  every  publication  in 
the  world.  The  goal  is  to  provide  inter¬ 
computer  networking.  Computers  not 
only  can  communicate,  but  also  share 
resources  with  other  types  of  machines. 
They  can  be  connected  directly,  or 
across  a  network  of  conforming  ma¬ 
chines. 

The  XModem  protocol  is  not  a  good 
example  of  a  layered  protocol.  It  is  a 
point-to-point  file  transfer  protocol  that 
requires  operator  intervention  at  both 
ends;  crude,  but  functional.  In  OSI  terms, 
XModem  provides  mostly  layer  2  (link 
layer)  services,  skips  layers  3  through 
6,  and  provides  a  single  service  of  layer 
7FTAM. 

A  good  example  of  layering  in  use 
today  is  X.25.  The  link  layer  uses  HDLC 
(high-level  data  link  control)  and  is 
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(continued  from  page  48) 
defined  by  a  set  of  state  diagrams  be¬ 
tween  neighbors.  The  network  layer 
provides  routing  services  in  complex 
networks,  and  communicates  with  peer 
network  layers  in  distant  machines. 

Individual  layers  should  be  imple¬ 
mented  as  separate  state  machines.  If 
the  same  program  handles  more  than 
one  layer,  a  mechanism  to  communi¬ 
cate  between  layers  is  required.  The 
lower  layers  are  given  precedence  when 
a  queue  of  events  has  built  up.  In  this 
case,  “it”  rolls  uphill! 

Implementing  a  Protocol 

The  first  step  to  implementing  a  com¬ 
munications  protocol  is  to  gain  a  good 
understanding  of  how  it  works.  Many 
are  well  documented,  but  some  require 
the  source  code  to  unravel  nuances 
like  time-outs  and  recovery  techniques. 
Some  proprietary  protocols  must  be 
“reverse  engineered”  using  data  line 
monitors  and  specialized  tools. 

The  next  step  is  to  break  the  com¬ 
munications  protocol  down  into  lay¬ 
ers,  and  then  to  define  states  within 
layers.  An  outliner  (with  hierarchies  of 
text)  can  help  to  develop  the  states, 
events,  and  next  states.  A  few  walk 
throughs  can  really  pay  off  as  this  step 
is  being  finalized. 


Table  1:  A  trace  of  successful  receive 


Validate  the  machine  against  “script” 
files  of  events.  Stub  out  the  actions  and 
read  events  from  a  script  file.  A  good 
trace  facility  can  record  the  route  taken 
through  the  machine.  The  trace  output 
can  be  compared  to  what  was  expected 
from  the  script  file.  New  states  or  events 
can  be  added  here  without  great  diffi¬ 
culty,  if  necessary. 

Then  it  is  time  to  actually  code  the 
actions.  It  is  amazing  how  quickly  this 
can  flow,  given  a  good  low-level  li¬ 
brary  and  proven  state  machines.  By 
this  time,  the  responsibilities  of  each 
action  should  be  fairly  well  understood. 
Remember,  actions  are  simply  func¬ 
tions  that  return  events! 

The  final  step  takes  at  least  two  com¬ 
puters.  Always  validate  the  protocol 
against  the  best  implementation  avail¬ 
able.  The  closer  to  the  source,  the  bet¬ 
ter  the  copy. 

Conclusion 

A  friend  of  mine  who  has  been  on  the 
“bleeding  edge”  of  computer  science, 
implementing  business  solutions  for 
years,  seems  to  thrive  on  the  ordeal. 
After  years  in  other  areas  of  computer 
science,  he  made  the  conversion  to 
communications.  When  asked  why,  he 
simply  replied,  “Because  comm  is  where 
the  chaos  is!” 


The  three  states  involved  in  receiving  a  packet 

State 

Init  Recv,  Event: 

0,  Note: 

fname  O.K 

State 

Incoming,  Event: 

2,  Note: 

timeout 

State 

Incoming,  Event: 

2,  Note: 

timeout 

State 

Incoming,  Event: 

0,  Note: 

got  one' 

State 

First  What,  Event: 

0,  Note: 

got  SOH 

State 

De-Pktize,  Event: 

0,  Note: 

pktOK 

State 

Incoming,  Event: 

0,  Note: 

got  one 

State 

First  What,  Event: 

0,  Note: 

got  SOH 

State 

De-Pktize,  Event: 

0,  Note: 

pktOK 

State 

Incoming,  Event: 

0,  Note: 

got  one 

State 

First_What,  Event: 

0,  Note: 

got  SOH 

State 

De-Pktize,  Event: 

0,  Note: 

pktOK 

State 

Incoming,  Event: 

0,  Note: 

got  one 

State 

First_What,  Event: 

2,  Note: 

got  EOT 

The  three  states  involved  in  receiving  a  packet  are: 

1. 

Incoming: 

Waiting  for  the  first  character. 

Decodes  the  response  from  Frame_Wait(INIT). 

Normally  calls  Which_Ctrl( )  action. 

2. 

First_What: 

Decodes  the  response  from  Which  Ctri( )  action  based  on  first 
character  (SOH,  CAN,  EOT  or  ???) 

Normally  calls  Validate! )  action. 

3. 

De-Pktize: 

Decodes  the  response  from  Validate( )  action. 

Normally  calls  Frame_Wait(NEXT)  is  all  is  well. 

Table  2:  States  in  motion 


Commies  are  no  different  from  other 
programmers.  Code  words  like  Ack, 
Nak,  and  CRC  are  used  to  scare  bright, 
young  talent  away  from  the  field.  The 
perfect  protocol  has  yet  to  be  written; 
or  if  it  has,  it  isn’t  in  the  public  do¬ 
main  .  .  .  yet! 
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Kicking  the  Habit 


“I  would  like  to  see  you  guys  .  . .  explain 
all  the  nifty  Z-80  tricks,  I  know  I  can't  be 
the  only  one  that  is  stuck  in  the  rut  of 
the  8080  code.  (Please!!  Don’t  tell  me  I 
swapped  my  CPU  board  JUST  for  speed  — 
the  software  potential  is  fantastic.)’’  — 
Letters  to  the  Editor,  DDJ,  November/ 
December  1977. 
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Hamming-Code 

Decoding 

You  don’t  have  to  sacrifice  efficiency  to  achieve  reliability 


Ben  White 


Since  the  earliest  days  of  elec¬ 
tronic  computation  and  data  com¬ 
munication,  equipment  design¬ 
ers  have  had  to  grapple  with  data 
transmission  errors.  For  exam¬ 
ple,  data  being  transmitted  over  a  noisy 
channel,  such  as  a  telephone  line,  may 
have  some  bits  garbled  by  external  phe¬ 
nomena  to  the  extent  that  they  no  longer 
have  their  original  value.  In  addition, 
data  stored  in  certain  types  of  com¬ 
puter  memory  occasionally  lose  the 
value  in  a  single  bit.  In  either  case,  if 
the  data  are  not  somehow  corrected 
or  retransmitted,  they  are  worthless.  If 
an  error  is  undetected,  the  results  can 
be  catastrophic  —  imagine  that  the  data 
represent  a  withdrawal  transaction  from 
a  bank’s  automatic  teller  machine. 

Because  of  the  need  for  reliable,  ac¬ 
curate  data  transmission  and  storage, 
various  methods  have  been  developed 
over  the  years  to  deal  with  this  prob¬ 
lem.  By  introducing  a  certain  amount 
of  redundancy  into  the  transmitted  data, 
an  error  can  be  detected,  and  even 
corrected,  at  the  receiving  end.  A  very 
simple-minded  usage  of  redundancy 
is  shown  in  the  following  example. 
Suppose  that  we  wish  to  transmit  data 
in  8-bit  bytes.  By  transmitting  each  byte 
twice,  the  receiver  can  compare  corre¬ 
sponding  bits  and  flag  any  discrepancy 
as  an  error.  For  example,  compare  the 
two  transmitted  bytes: 


Ben  is  a  C  programmer  and  employee  - 
owner  at  Lockheed  Missiles  &  Space 
Co.,  0/6215,  B/551,  PO  Box  3504, 
Sunnyvale,  CA  94088-3504. 


11010011 

11011011 

These  two  bytes  differ  at  the  fifth  bit 
from  the  left,  indicating  an  error.  There 
is  no  way  to  know  which  value  (0  or 
1)  is  the  correct  value  for  that  bit,  so  the 
receiver  must  request  retransmission. 
By  using  triple  redundancy,  this  prob¬ 
lem  can  be  eliminated,  as  shown: 

11010011 

11010011 

11011011 

Under  this  scheme,  each  byte  is  trans¬ 
mitted  three  times,  and  we  again  note 
that  there  is  a  discrepancy  in  the  fifth 
bit.  The  bit  appears  as  a  0  in  two  of  the 
transmitted  bytes,  and  as  a  1  in  only 
one  byte.  We  can  assume  with  a  high 
degree  of  confidence  that  the  correct 
value  for  that  bit  is  0,  and  retransmis¬ 
sion  is  not  necessary.  This  self-correct¬ 
ing  capability  is  enormously  useful  in 
situations  such  as  satellite  communica¬ 
tions,  where  signal  propagation  takes 
a  long  time. 

The  problem  with  the  above  ap¬ 
proach  is  that  it  is  inefficient.  With 
triple  redundancy,  only  33  percent  of 
the  channel  capacity  is  used  for  ac¬ 
tual  data.  The  use  of  Hamming  codes 
is  a  widely  used  method  of  achieving 
the  same,  or  better,  results.  A  subset 
of  the  bits  in  each  data  word  is  as¬ 
signed  to  (overlapping)  groups,  and  a 
“check  bit”  is  given  to  each  group. 
This  allows  the  detection/correction 
of  errors  in  received  code  words  with 


much  more  efficient  use  of  the  chan¬ 
nel  than  the  method  previously  de¬ 
scribed. 

Hamming-Code  Theory 

To  illustrate  this  procedure,  let’s  as¬ 
sume  that  we  wish  to  transmit  4-bit 
message  (data)  words  across  a  noisy 
channel.  We  also  want  to  be  able  to 
detect  and  correct  any  single  bit  error 
occurring  during  transmission.  It  will 
be  necessary  to  create  three  check 
groups,  and  assign  three  of  the  mes¬ 
sage  bits  to  each  group.  Number  the 
message  and  check  bits  as  follows: 

PI  P2  M3  P4  M5  M6  M7 

PI,  P2,  and  P4  are  check  bits  (P  stands 
for  parity).  M3,  M5,  M6,  and  M7  are  the 
message  bits.  Before  transmitting  the 
7-bit  code  word,  values  must  be  as¬ 
signed  to  the  check  bits.  This  is  done 
as  follows:  PI  is  assigned  odd  parity 
over  M3,  M5,  and  M7.  P2  is  assigned 
odd  parity  over  M3,  M6,  and  M7.  Fi¬ 
nally,  P4  is  assigned  odd  parity  over 
M5,  M6,  and  M7.  For  example,  take  the 


code  word: 

M3 

M5 

M6 

M7 

I 

0 

1 

1 

Because  the  exclusive-OR  of  M3,  M5, 
and  M7  is  0,  PI  will  be  1.  The  4-bit 
group,  including  the  check  bit  itself, 
must  have  odd  parity.  By  the  same 
reasoning,  P2  is  0,  and  P4  is  1.  The 
complete  code  word  to  be  transmitted 
is: 
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(continued  from  page  52) 

PI  P2  M3  P4  M5  M6  M7 

10  110  11 

You  may  notice  that  the  PI  check  bit 
represents  the  parity  over  all  message 
bit  positions  with  the  21  bit  present,  as 
in  positions  3,  5,  and  7  (Oil,  101,  111 
in  binary).  P2  is  parity  for  the  22  bit 
positions,  and  P4  is  parity  for  the  24  bit 
positions.  The  placement  of  check  bits 
in  the  completed  code  word  is  done 
to  reinforce  this  structure  conceptually. 
In  actual  practice,  any  ordering  of  the 
bits  will  do,  as  long  as  sender  and 
receiver  agree  on  the  same  order. 

To  see  that  the  added  check  bits 
provide  enough  redundancy  to  detect 
and  correct  any  single  bit  error,  look 
at  the  receiving  and  decoding  process. 
When  the  receiver  has  all  7  bits  of  the 
code  word,  the  grouping  of  bits  is  re¬ 
peated,  and  parity  of  each  4-bit  group 
is  checked.  PI,  M3,  M5,  and  M7  are 
exclusive-ORed  together  and  checked 
for  odd  parity;  the  same  process  occurs 
for  the  P2  and  P4  groups. 

If  one  or  more  of  the  three  groups 
do  not  have  odd  parity,  a  transmission 
error  has  occurred.  Assume  that  the 
received  code  word  is  1010011,  which 
differs  from  the  transmitted  code  word. 
The  bits  of  the  PI  group  are  1101,  the 
P2  group  is  0111,  and  the  P4  group  is 
0011.  The  exclusive-OR  of  the  4  bits  in 
each  group  is  0,  0,  and  1,  respectively. 
As  one  of  the  groups,  P4,  does  not 
have  odd  parity,  an  error  has  been 
detected. 

We  have  all  of  the  information  needed 
to  locate  the  bit  position  of  the  error 
and  we  can  correct  it.  The  three  parity 
bits  computed  by  the  receiver  are  ar¬ 
ranged  in  descending  order,  left  to  right, 
by  group  number,  P4,  then  P2,  then 
PI.  Arranged  this  way,  the  bits  are  called 


Figure  1:  Parity-generation  circuits  is 
one  method  used  in  logic  designs  to 
add  check  bits  to  message  words 


the  "syndrome.”  In  the  above  exam¬ 
ple,  the  syndrome  is  100,  which  is  the 
binary  number  four  (4).  It  just  so  hap¬ 
pens  that  bit  4  (counting  from  the  left) 
in  the  received  code  word  is  the  bit  in 
error.  Simply  invert  the  bit  to  correct  it. 
Bit  4  also  happens  to  be  one  of  the 
check  bits,  and  nicely  illustrates  that 
the  Hamming  method  of  error  detec¬ 
tion  works  for  any  bit  in  the  code  word, 
whether  it  is  a  message  or  a  check  bit. 

The  Hamming  method  can  be 
adapted  to  work  for  longer  message 
words.  Efficiency  is  gained  in  terms  of 
the  check  bits  to  message  bits  ratio,  but 
the  probability  of  an  error  occurring  in 
a  given  code  word  is  increased.  On  the 
other  hand,  if  more  check  bits  are  used, 
greater  numbers  of  bit  errors  in  a  word 
can  be  detected  and  corrected. 

Encoding  and  Decoding 

Methods  used  in  logic  designs  to  add 
check  bits  to  message  words  include 
parity-generation  circuits  (Figure  1)  and 
address-table  lookups  (as  through  a 
ROM).  In  the  first  case,  exclusive-OR 
gates  are  used  to  generate  odd  parity 
from  2-bit  pairs.  The  outputs  are  exclu¬ 
sive-ORed  again  to  compute  parity  for 
a  4-bit  group.  The  parity  (check)  bits 
are  then  transmitted  with  the  message 
bits. 

For  lookup-based  check-bit  genera¬ 
tion,  the  message  bits  are  presented  as 
the  address  to  a  memory.  The  data  at 
each  memory  location  is  the  appropri¬ 
ate  combination  of  check  bits  for  that 
message  word.  Again,  assume  a  4-bit 
message,  and  three  check  bits  for  single¬ 
error  correction.  The  resulting  memory 
lookup  table  would  require  four  ad¬ 
dress  bits  and  3-bit  data  words,  or  a 
1 6- word  x  3-bit  memory.  As  with  the 
exclusive-OR  network,  the  check  bits 
produced  from  the  lookup  table  are 


transmitted  with  the  message  bits. 

The  traditional  method  for  decoding 
received  data  is  with  an  exclusive-OR 
circuit,  as  shown  in  Figure  2,  for  the 
4-bit  message  and  3-bit  check  scheme. 
The  7  bits  of  the  code  word  are  pre¬ 
sented  in  parallel  to  the  exclusive-OR 
gates.  These  are  divided  into  three 
groups,  corresponding  to  the  three 
check  bits.  The  odd  parity  of  each  of 
the  4  bits  in  the  group  is  calculated, 
and  the  resulting  syndrome  is  presented 
to  a  decoder.  The  decoder  can  be  con¬ 
sidered  to  be  the  error  detector.  If  an 
error  is  indicated  by  the  syndrome,  one 
of  the  outputs  Y1  to  Y7  will  be  asserted. 
If  the  syndrome  is  0,  Y0  will  be  as¬ 
serted,  meaning  no  error  was  detected. 

The  decoder  outputs  are  used  to  drive 
the  correction  logic,  consisting  of  one 
exclusive-OR  gate  for  each  message 
bit.  The  check  bits  do  not  need  to  be 
explicitly  corrected,  as  they  are  used 
only  internally  by  the  receiver.  This  is 
the  reason  nothing  is  connected  to  the 
Yl,  Y2,  and  Y4  outputs  of  the  decoder. 

Normally,  the  exclusive-OR  gates  will 
pass  the  message  bit  through  unchanged. 
In  some  instances,  the  decoder  asserts 
one  of  the  outputs  Y3,  Y5,  Y6,  or  Y7. 
This  will  cause  the  corresponding  gate 
to  invert  its  received  message  bit  and 
correct  the  error  automatically. 

An  alternate  approach  to  decoding, 
which  is  similar  to  encoding  by  ROM 
table  lookup,  boasts  the  same  simplic¬ 
ity  of  design.  For  the  decoding  case, 
the  ROM  needs  a  7-bit  address  and 
4-bit  words,  or  a  128-word  x  4-bit  ROM 
(see  Figure  3).  The  trick  is  in  deciding 
what  to  store  in  each  word  of  the  ROM. 

In  those  cases  where  the  incoming 
code  word  is  correct,  the  answer  is 
clear.  There  are  16  possible  message 
words  (24)  and  16  different  correct  code 
words.  The  message  word  is  stored  at 


Figure  2:  The  traditional  method  for  decoding  received  data  is  with  an 
exclusive-OR  circuit 
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(continued  from  page  54) 
each  of  these  16  ROM  addresses.  When 
the  7-bit  code  word  is  presented  at  the 
inputs,  the  embedded  message  word 
will  be  delivered  at  the  outputs.  It  can 
then  be  passed  on  by  the  receiver  as  a 
correct  message  word. 

For  example,  if  the  (valid)  code  word 
1011011  is  received,  it  is  applied  to  the 
address  inputs  of  the  ROM.  The  data 
stored  at  that  location  is  1011,  the  four 
embedded  message  bits  from  the  code 
word.  The  data  at  address  X  =  X,  for  the 
16  correct  code  words. 

The  remaining  1 12  (27  -  24)  ROM  lo¬ 
cations  correspond  to  erroneous  code 
words.  Given  a  set  of  16  possible  cor¬ 
rect  code  words  and  assuming  that  one 
single-bit  error  occurs,  each  original 
code  word  can  change  in  seven  differ¬ 
ent  ways.  This  means  there  are  16*7  = 
112  possible  erroneous  code  words, 
but  because  of  the  redundancy  built 
in,  a  received  code  word  containing  a 
single  error  has  one  unambiguous  cor¬ 
rect  code  word.  The  reason  this  is  so 
has  to  do  with  the  “Hamming  distance" 
of  the  code  scheme,  a  concept  that 
would,  unfortunately,  require  a  rather 
lengthy  explanation. 

We  must  store  something  at  these 
112  locations  that  will  automatically  cor¬ 
rect  the  message  portion  of  the  code 
word.  If  each  erroneous  code  word  is 
a  ROM  address,  then  the  data  stored  at 
that  address  should  be  the  corrected 
code  word.  In  other  words,  the  data 
stored  at  address  Y  =  X,  where  X  is  the 
corresponding  correct  code  word. 

Assume  that  the  code  word  1010011 
is  received  and  presented  at  the  ad¬ 
dress  inputs  of  the  ROM.  As  it  happens, 
this  is  an  erroneous  code  word.  The 
data  stored  at  location  1010011  would 


be  the  corrected  code  word,  1011,  with¬ 
out  the  check  bits. 

Hamming-Code  Benefits 

By  considering  each  permutation  in  ad¬ 
vance  (an  easily  computable  task  for 
any  realistic  code  word  length),  it  is 
possible  to  program  a  ROM  to  do  the 
decoding  at  the  receiving  end.  The  ROM- 
based  design  is  simpler  and  cleaner 
than  the  exclusive-OR  circuit  and,  for 
small  word  sizes,  approximately  as  fast. 

Furthermore,  ROM-based  designs  can 
easily  be  extended  to  handle  longer 
message  and  code  word  lengths.  With 
longer  code  words,  the  efficiency  ratio 
of  message  bits  to  check  bits  increases, 
although  the  chances  of  an  error  oc¬ 
curring  in  a  given  code  word  are  in¬ 
creased.  The  ROM-based  design  is  also 
able  to  accommodate  different  code 
schemes  that  can  detect  and/or  correct 
more  errors  in  a  code  word  by  using 
more  check  bits  and  assigning  the 
groups  differently.  In  these  cases,  a 
different  size  ROM  is  substituted  and 
programmed.  With  the  exclusive-OR 
circuit,  a  complete  redesign  is  often 
necessary. 
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Executable 
Specifications  with 

Prolog 

Prologs  dual  nature  takes  you  from  design 
to  implementation 


The  Prolog  language  is  the  best 
known  example  of  a  Logic  Pro¬ 
gramming  implementation,  with 
the  uniqueness  that  it  can  be 
viewed  declaratively  as  well  as 
procedurally.  Therefore,  Prolog  may  pro¬ 
vide  an  attractive  tool  in  software  engi¬ 
neering,  particularly  in  the  areas  of 
“executable”  specifications  and  rapid 
prototyping  (Davis,  1982;  Kowalski, 
1982;  Leibrandt  and  Schnupp,  1984). 
Lazarev  (1989)  described  a  mapping 
mechanism  for  converting  a  structured 
specification  in  the  form  of  data  flow 
diagrams  (DFDs)  into  an  executable 
Prolog  program.  In  this  article,  the  map¬ 
ping  is  extended  by  including  a  case 
of  partial  matching.  Several  examples 
of  mapping  are  presented,  and  the  ad¬ 
vantages  of  using  this  methodology  to 
improve  the  quality  of  DFDs  are  dis¬ 
cussed. 

Introduction 

The  standard  software  development  cy¬ 
cle  of  analysis,  design,  and  implemen¬ 
tation  provides  many  benefits,  but  it 
also  has  serious  drawbacks.  One  prob¬ 
lem  is  that  the  mapping  from  a  declara¬ 
tive  specification  to  its  procedural  im¬ 
plementation  is  complex.  There  is  no 
automated  procedure  to  transform  analy¬ 
sis  into  design,  and  verifying  program 
correctness  is  an  unresolved  problem. 


Gregory  Lazarev  is  the  president  of  Ap¬ 
plied  Logic  Programming,  Inc.  and.  can 
be  reached  at  262  Tomkenn  Rd.,  Phila¬ 
delphia,  PA  19151. 


Gregory  L.  Lazarev 

The  nonexplicit  representation  of  re¬ 
quirements  reveals  itself  in  maintenance 
problems.  The  lack  of  executable  speci¬ 
fications  (due  to  informal  syntax  and 
semantics)  leads  to  long  delays  in  evalu¬ 
ating  whether  the  direction  chosen  for 
development  is  right. 

Practical  experiences  using  method¬ 
ologies  based  on  the  analysis-design- 
implementation  model  clearly  demon¬ 
strate  the  critical  nature  of  these  diffi¬ 
culties  (Richter,  1986).  It  has  been  rec¬ 
ognized  that  “an  analysis  specification, 
once  finished,  proved  to  be  of  little 
value.”  In  other  words,  it  neither  can 
be  verified  nor  transformed  automati¬ 
cally  into  a  design.  Further,  “good  analy¬ 
sis  may  require  some  design  and  im¬ 
plementation  —  some  REAL  TESTING 
of  feasibility  —  along  the  way.” 

Structured  Analysis  (De  Marco,  1979) 
is  often  used  to  perform  the  software 
analysis  phase.  Structured  Analysis  is 
a  data-oriented  methodology  with  three 
main  elements.  First,  there  are  data  flow 
diagrams  consisting  of  transformations 
and  data  flows.  Transformations  ( or  “bub¬ 
bles")  represent  distinct  logical  func¬ 
tions,  and  data  flows  stand  for  the  data 
input  and  output  associated  with  trans¬ 
formations. 

The  second  element  is  a  data  dic¬ 
tionary,  which  defines  elements  of  struc¬ 
tured  analysis  (that  is,  data  flows,  trans¬ 
formations,  files,  and  so  forth).  Finally, 
there  is  a  structured  English  specifica¬ 
tion  used  to  describe  functional  primi¬ 
tives.  Functional  primitives  are  the  non- 
partitioned,  lowest-level  bubbles. 


In  structured  analysis,  we  decompose 
a  transformation  into  new  transforma¬ 
tions  on  a  lower  level.  This  procedure 
is  continued  until  no  more  decomposi¬ 
tions  are  possible,  and  then  structured 
English  is  used  to  describe  the  lowest- 
level  nondecomposable  elements. 

It  can  be  argued  that  the  core  of  the 
described  problems  is  the  existence  of 
two  orthogonal  semantics  involved;  the 
specification  is  declarative  and  the  im¬ 
plementation  is  procedural  (Lazarev, 
1987).  Procedural  information  (such  as 
correlations  between  data  flows)  is  pro¬ 
vided  on  the  level  of  functional  primi¬ 
tives  but  is  totally  separated  from  DFDs. 
Therefore,  the  usefulness  of  structured 
analysis  as  a  software  engineering  tool 
is  limited.  Prolog  provides  a  direction 
that  narrows  the  gap  between  analysis 
and  implementation.  Prolog’s  declara¬ 
tive  nature  is  ideally  suited  for  the  analy¬ 
sis  phase,  while  Prolog’s  procedural 
capabilities  are  well  suited  for  software 
implementation  by  making  a  specifica¬ 
tion  “executable.”  The  specification  be¬ 
comes  a  program  that  can  be  run  and 
debugged.  This  approach  is  conceptu¬ 
ally  similar  to  rapid  prototyping:  A  user 
can  see  whether  his  requirements  as 
stated  are  what  he  actually  wants,  and 
the  programmer  can  verify  the  corre¬ 
spondence  of  the  program  to  the  user’s 
requirements. 

Mapping  DFDs  to  an  Executable 
Specification 

The  mechanism  of  automatic  mapping 
between  the  DFDs  (for  all  levels  above 
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6l 


Project 


Figure  la 


Budget  a.  schedule 


System 


■  System 


Budget  a.  schedule 


Figure  1c 


Figure  1:  Model  of  the  project  life  cycle 


str_design(  i(  struct_spec,  config_data) , 
o(  test_plan,  pack  design)  ). 
derive_log_equiv{  i(  user_req,  curr_phys_DFD) , 
o(  curr  log_DFD)  ). 

Example  1:  Sample  Prolog  facts  from  Listing  One 

?- 

project(  X,  Y). 

X  =  i(  user_reqO) 

Y  =  o(  systemO,  budg_schedO) 

?- 

project!  K  user_reqO),  Out). 

Out  =  o(  systemO,  budg_schedO) 

?- 

project(  i(  user_reqO),  o(  systemO,  budg_schedO) ). 
yes 

?- 

str_anal(  X,  Y). 

X  —  i(  user_reqO,  feas_doctO) 

Y  =  o(  struct_specO,  budg_schedO,  phys_reqO) 

?- 

str_anal(  i(  user_reqO,  12),  Out). 

12  =  feas_doctO 

Out  =  o(  struct_specO,  budg_schedO,  phys_reqO) 

Figure  2:  Queries  used  for  Listing  One 


the  level  of  functional  primitives)  and 
an  executable  Prolog  program  was  de¬ 
scribed  by  Lazarev  (1989).  The  most 
important  feature  of  this  mapping  is 
the  one-to-one  correspondence  be¬ 
tween  the  DFDs  and  the  resulting  Prolog 
program.  Each  DFD  is  represented  as 
a  Prolog  predicate  with  two  argu¬ 
ments  —  input  and  output  structures. 
Each  structure’s  components  are  ele¬ 
ments  of  the  Data  Dictionary.  DFDs 
by  themselves  are  not  enough  to  gen¬ 
erate  Prolog  code  automatically.  The 
missing  ingredient  is  a  correlation 
among  the  input  and  output  data  flows 
for  each  transformation  or,  alternatively, 
a  correlation  among  transformations 
themselves.  We’ll  assume  that  these  cor¬ 
relations  (AND  and  OR  correlations) 
are  known. 

The  following  steps  describe  a  map¬ 
ping  algorithm.  The  case  of  partially 
matched  inputs  and  outputs  represented 
by  (d.4)  and  (d.5)  is  an  extension  of  the 
original  algorithm.  Steps  (a),  (b),  and 
(c)  are  performed  on  every  DFD  level. 
Step  (d)  deals  with  interaction  among 
levels: 

a)  Describe  each  transformation  as  a 
predicate  with  the  same  name.  All  predi¬ 
cates  have  two  arguments;  an  input 
argument  represented  as  structure 
i(Il,  12,  .  .  .  ,  In),  where  11,  .  .  ,  In  are 
input  data  flows;  and  an  output  argu¬ 
ment  represented  as  structure  o(  Ol, 
02,  .  .  .  ,  On),  where  Ol,  .  .  ,  On  are 
output  data  flows. 

b)  Represent  OR-correlations  explicitly 
by  replacing  predicates  with  several 
predicates  of  the  same  name,  one  for 
each  mutually  exclusive  case.  For  ex¬ 
ample,  a  predicate  bb(  i(B),  o(Bl,B2, 
B3J)  with  OR-correlations  among  data 
flows  B1 ,  B2 ,  and  B3  can  be  replaced 
with  the  following: 

bb(  i(B),  o(Bl)  ) 

bb(  i(B),  o(B2) ) 

bb(  i(B),  o(B3)  ) 

c)  Review  the  resulting  set  of  predi¬ 
cates  and  mark  all  groups  that  form 
mutually  exclusive  sets.  Such  cases  may 
arise  either  from  OR-correlations  among 
data  flows  or  from  more  complicated 
OR-correlations  among  transformations. 

d)  Build  a  set  of  Horn  clauses.  Each 
clause  has  an  upper-level  predicate  as 
its  head,  and  predicates  from  one  level 
below  as  its  body.  There  may  be  multi¬ 
ple  clauses  for  any  given  upper-level 
predicate.  Clauses  must  satisfy  the  fol¬ 
lowing  requirements  for  a  goal  (that  is, 
a  head’s  predicate)  and  subgoals  (body’s 
predicates): 
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•  d.l)  Each  group  of  mutually  exclu¬ 
sive  predicates  marked  in  (c)  can  pro¬ 
vide,  at  most,  one  subgoal  in  a  clause. 

•  d.2)  Each  input  of  each  subgoal  must 
be  matched  with  some  input  of  the 
goal  or  with  an  output  of  some  previ¬ 
ous  subgoal  (a  balanced  input). 

•  d.3)  Each  output  of  each  subgoal  must 
be  matched  with  some  output  of  the 
goal  or  with  an  input  of  some  later 
subgoal  (a  balanced  output). 

•  d.4)  If  (d.2)  or  (d.3)  fail  then  un¬ 
matched  inputs  (outputs)  of  a  subgoal 
are  replaced  by  an  atom  nil.  At  least 
one  input  and  one  output  of  each 
subgoal  must  be  non-nil. 

•  d .  5)  Unmatched  arguments  of  the  goal 
(inputs  and  outputs)  are  replaced  by 
an  atom  nil 

Let’s  illustrate  this  procedure  using 
a  model  project  life  cycle  taken  from 
De  Marco  (1979)  (see  Figures  la,  lb, 
and  lc).  Minor  changes  have  been  made 
in  decomposing  the  structured  analysis 
“bubble”  (Figure  lc). 

These  DFDs  do  not  include  any  OR- 
correlations,  so  steps  (b)  and  (c)  in  the 
mapping  algorithm  do  not  apply.  The 
corresponding  Prolog  program  is  shown 
in  Listing  One,  page  68.  In  order  to  be 
executable,  it  includes  facts  (like  those 
shown  in  Example  1)  that  provide  a 
representation  for  the  lowest  decom¬ 
position  level. 

Despite  the  fact  that  the  decomposi¬ 
tion  process  can  be  stopped  at  any 
level,  the  value  of  such  a  mapping  pro¬ 
gram  is  maximized  by  going  to  the 
level  of  nondecomposable  functional 
primitives. 

As  Listing  One  demonstrates,  the 
mapping  preserves  key  features  of 
DFDs  such  as  a  top-down  design  with 
capabilities  for  further  refinement,  and 
modularity.  Developing  an  executable 
specification  substitutes  —  to  a  large 
degree  —  for  the  design  and  program¬ 
ming  phases  of  the  traditional  struc¬ 


tured  methodology.  The  resulting  pro¬ 
gram  is  strictly  logical,  therefore  there 
are  no  predefined  input/output  argu¬ 
ments  (a  property  known  as  invertabil- 
ity).  Three  query  types  are  supported: 

1.  Find  all  possible  input/output  com¬ 
binations.  This  corresponds  to  the  case 
of  totally  unbound  parameters.  The 
query  has  the  form: 

?-  predicate!  X,  Y) 

2.  For. some  given  input/output  parame¬ 
ters  find  unbound  parameters  (that  is, 
conditions  under  which  the  DFD  predi¬ 
cate  is  true).  This  corresponds  to  the 
case  of  partially  instantiated  variables, 
and  includes  two  important  subclasses: 

a)  For  a  totally  defined  input,  find 
an  output 

b)  For  a  totally  defined  output,  find 
an  input 

3.  Check  whether  the  DFD  predicate 
with  all  variables  instantiated  is  true. 

The  queries,  shown  in  Figure  2,  for 
Listing  One  provide  an  illustration. 

Extension  to  Partial  Matching 

Data  flow  diagrams  may  have  serious 
deficiencies,  and  because  of  the  com¬ 
plexity  of  the  total  picture,  problems 
often  remain  hidden.  The  mapping  pro¬ 
cedure  based  on  Prolog  may  be  help¬ 
ful  in  revealing  these  problems.  Exam¬ 
ples  in  this  and  the  following  sections 
illustrate  this  point. 

Consider  the  diagrams  in  Figure  3. 
Suppose  that  transformations  bb and 
cc  are  declared  to  be  OR-correlated. 
Step  (c)  of  the  mapping  algorithm  pro¬ 
duces  the  following  set  of  mutually 
exclusive  predicates: 

bb(  i(A,B),  o(Ol)  ) 
cc(  i(C),  o(02) ) 


top(  i(l),  o(01 ,  nil) ) :-  aa(  i(l),  o(  A,  B,  nil) ), 
bb(  i(A,  B),  o(OI) ). 

top(  i(l),  o(nil,  02) ) aa(  i(l),  o(  nil,  nil,  C) ), 
_ cc(  i(C),  o(Q2) ). 


Step  (d)  cannot  be  achieved  using  full 
matching,  but  partial  matching  using 
nil  atoms  is  possible.  The  output  is 
shown  in  Figure  4. 

The  program  in  Figure  4  demonstrates 
that,  because  of  OR-correlations  be¬ 
tween  transformations  bb  and  cc;  the 
output  of  transformation  aa  is  either 
(A  and  B),  or  C  (but  not  both);  and  the 
output  of  the  transformation  topis  either 
Ol  or  02  (but  not  both).  In  other  words, 
the  appearance  of  "nils”  shows  that 

Prolog’s  declarative 
nature  is  ideally  suited 
to  the  analysis  phase, 
while  Prolog’s 
procedural  capabilities 
are  well  suited  for 
software 

implementation  by 
making  a  specification 
1 executable ’ 


DFDs  can  be  further  decomposed  (“nor¬ 
malized”).  In  our  case,  the  diagram  on 
each  level  can  be  replaced  by  two,  as 
shown  in  Figure  5. 

The  mapping  of  this  diagram  results 
in  a  “nil-free”  Prolog  program.  The  same 
program  can  also  be  obtained  from 
Figure  3  by  declaring  two  OR-correla¬ 
tions  among  data  flows: 

(1)  Ol,  02 

(2)  (A,  B),  C 

One  role  of  nil-arguments  in  programs, 
similar  to  Figure  4,  is  to  perform  a 
unification  of  distinct  concepts.  Under 
some  circumstances  it  makes  sense  to 
use  such  programs  rather  than  to  per¬ 
form  further  decomposition. 

“Disconnected  networks”  are  a  spe¬ 
cial  case  of  partial  matching.  Consider, 
for  example,  the  two-level  diagrams  in 
Figure  6. 

Suppose  that  level  2  diagrams  are 
mutually  exclusive  (that  is,  OR-corre- 
lated).  As  can  be  seen  from  Listing  Two, 
page  68,  the  nil  arguments  in  the  heads 
of  both  clauses  fully  complement  each 


Figure  4:  Resulting  program  generated  from  the  DFD  in  Figure  3 
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other.  This  is  an  indicator  of  discon¬ 
nected  networks.  Such  a  case  must  be 
transformed  into  a  simpler  case  (in  this 
case,  by  deleting  a  level  1  diagram 
and  moving  current  level  2  diagrams 
to  level  1). 

Lost  Causality 

I’ve  shown  how  the  quality  of  DFDs 
can  be  evaluated  by  analyzing  the  cor¬ 
responding  executable  specifications. 
But,  an  inability  to  create  an  execut¬ 
able  specification  from  DFDs  when  us¬ 
ing  the  described  algorithm  may  be  a 
sign  of  problems  in  the  diagrams:  They 
may  be  “non-normalized”  or  they  may 
have  sequencing  ambiguities  (which 
are  resolved  in  structured  English).  For 
instance,  consider  the  two-level  dia¬ 
gram  in  Figure  7. 

Suppose  that  there  are  no  OR-corre- 
lations  and  no  further  decomposition 
provided.  Step  (a)  of  the  mapping  al¬ 
gorithm  produces  the  following  set  of 
predicates: 

top(  i(  K),  o(  L) ). 

aa_ee(  i(  K,  D),  o(  A,  L) ). 

bb_dd(  i(  A,  C),  o(  B,  D) ). 

cc(  i(  B),  o(  C)  ). 

But  step  (d)  fails  because  there  is  no 
way  to  express  the  predicate  top  in 
terms  of  three  lower-level  predicates 
( aa_ee,  bb_dd,  cc ).  The  reason  is  straight¬ 
forward:  The  predicates  are  involved 
in  a  circular  relation.  For  example,  the 
predicate  bb_dd  must  precede  cc  ac¬ 
cording  to  the  data  flow  B,  but  the 
same  predicate  must  follow  cc  accord¬ 
ing  to  data  flow  C.  In  a  more  complex 
diagram,  circular  structures  may  not 
be  seen  as  easily,  but  the  mapping 
algorithm  provides  a  good  indication 
of  such  problems.  One  solution  may 
be  further  decomposition.  Suppose  that 
predicates  aa_ee  and  bb_dd  may  be 
decomposed  into  two  independent  predi¬ 
cates  ( aa ,  ee  and  bb,  dd).  In  this  case, 


Figure  5:  Normalization  of  the  DFD 
in  Figure  3 
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step  (a)  results  in: 

top(  i(  K),  o(  L)  ). 
aa(  i(  K),  o(  A) ). 
ee(  i(  D),  o(  L)  ). 
bb(  i(  A),  o(  B) ). 
dd(  i(  C),  o(  D)  ). 
cc(  i(  B),  o(  C)  ). 

The  resulting  clause  is  straightforward: 

top(  i(K),  o(L) ) 
aa(  i(  K),  o(A)  ), 
bb(  i(  A),  o(  B) ), 
cc(  i(  B),  o(  C)  ), 
dd(  i(  C),  o(  D)  ), 
ee(  i(  D),  o(  L)  ). 


The  sequence  of  processes  in  this  pro¬ 
gram  (aa,  bb,  cc,  dd,  ee,  in  this  order) 
shows  that  any  attempt  to  express  top 
in  terms  of  composite  processes  (like 
aa_ee  or  bb_dd )  with  nontime-sequen- 
tial  elements  will  fail.  “Causality,”  or 
time-dependence,  is  lost  and  a  pro¬ 
gram  cannot  be  constructed. 

Conclusion 

By  incorporating  1 .  a  set  of  DFDs  with 
data  flows  defined  by  a  data  dictionary, 
2.  procedural  information  taken  from 
functional  primitives,  and  3-  the  proce¬ 
dural  semantics  of  Prolog,  it  is  possible 
to  create  executable  specifications  as 
software  programs.  Such  a  program 
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would  contain  basic  control  structures 
that  is,  sequence,  decision,  and  repeti¬ 
tion  (through  recursion).  The  output 
programs  are  in  Prolog.  Although  Prolog 
is  based  on  a  restricted  form  of  logic, 
it  is  adequate  for  our  purposes.  These 
programs  are  “pure”  (free  from  side 
effects).  As  such,  they  are  invertible 
and  consequently  provide  a  broader 
scope  of  experimentation  than  corre¬ 
sponding  DFDs. 

Not  only  can  the  specification  be 
made  executable,  but  the  suggested 
approach  is  also  helpful  in  verifying 


and  improving  specifications.  This  is 
done  by  incorporating  a  partial  match¬ 
ing  extension  into  an  original  algo¬ 
rithm. 

The  approach  presented  is  evolu¬ 
tionary.  It  extends  the  DFDs’  methodol¬ 
ogy  by  making  it  executable.  As  a  re¬ 
sult,  the  main  advantage  of  the  stan¬ 
dard  DFD  methodology  —  a  graphical 
language  used  to  solve  a  communica¬ 
tion  problem  —  remains  intact.  All  of 
the  above  makes  logic  programming 
and  Prolog  very  promising  in  software 
engineering. 


Figure  7:  DFD  with  no  OR  correlations  and  no  further  decomposition 
provided 
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Listing  One 


project (  i(  User_req) ,  o(  System,  Budg_sched)  ) :- 
survey (  i(  User_req) ,  o(  Feas_doct)  ), 
str_anal{  i(  User_req,  Feas_doct), 

o(  Struct_spec,  Budg_sched,  Phys_req)  ), 
hw_study(  if  Phys_req),  o(  Config_data,  Hardw)  ), 
str_design(  i(  Struct_spec,  Conf ig_data) , 
o{  Test_plan,  Pack_design)  ), 
implemf  i<  Hardw,  Testjplan,  Pack_design) ,  o(  System)  ). 

str_anal(  i(  User_req,  Feas_doct), 

o(  Struct_spec,  Budg_sched,  Phys_req)  ):- 
study _curr_environ (  i(  User_req) ,  o(  Curr_phys_DFD)  ), 
derive_log_equiv{  i(  User_req,  Curr_phys_DFD) , 
of  Curr_log_DFD)  ), 

model_new_log_sys {  i{  User_req,  Curr_log_DFD,  Feas_doct), 
o(  New_log_DFD,  DD,  Trans_desc)  ), 
model_new_phys_sys f  if  New_log_DFD) , 

o{  New_phys_DFD,  Budg_sched,  Phys_req) 
produce_struct_spec (  if  New__phys_DFD,  DD,  Trans_desc) , 
of  Struct_spec)  ). 

survey (  if  user_reqO),  of  feas_doct0)  ). 
hw_studyf  if  phys_reqO),  of  config_dataO,  hardwO)  ). 


str_design (  if  struct_spec0,  config_dataO) , 
of  test_plan0,  pack_designO)  ). 
implemf  if  hardwO,  test_pianO,  pack_designO) ,  of  systemO)  ). 
study_curr_eaviron (  if  user_req0),  of  curr_phys  DFDO)  ). 
derive_log_equiv {  if  user_reqO,  curr_phys_DFD0)7 
of  curr_log_DFDO)  ). 

model_new_log_sys (  if  user_req0,  curr_log_DFDO,  feas_doctO), 
of  new_log_DFDO,  ddO,  trans_desc()7  ) . 
model_new_phys_sys (  if  new_log_DFDO) , 

of  new_phys_DFDO,  budg_schedO,  phys_reqO)  ) . 
produce_struct_spec (  if  newjphys_DFDO,  ddO,  trans_desc0T, 
of  struct_specO)  ). 


End  Listing  One 


Listing  Two 


bbf  if  B,  Bl,  nil),  of  nil,  E)  ) 
bb' (  if  B,  Bl),  o(E)  ) . 
bbf  if  nil,  nil,  C) ,  of  D,  nil)  ) 
bb"  {  if  C),  of  D)  ) . 


End  Listings 
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A  Global  Variable 

Device  Driver  for 

MS-DOS 

GLOVAR  lets  you  modify  an  ancestor’s  environment 


.im  Mischel 


While  the  MS-DOS  environ¬ 
ment  string  setup  is  a  handy 
way  to  define  system-wide 
information,  it  suffers  from 
one  major  drawback:  The 
inability  of  a  child  process  to  make 
permanent  modifications  to  an  ances¬ 
tor’s  environment.  Why,  one  might  ask, 
would  you  want  to  do  such  a  thing?  I 
asked  the  same  question  the  first  time 
somebody  brought  it  up,  but  as  luck 
would  have  it,  I  soon  found  myself 
answering  it. 

I  support  an  application  that  makes 
extensive  use  of  environment  variables 
to  store  configuration  information; 
things  like  screen  colors,  data  drive 
assignments,  and  so  on  —  many  of 
which  are  session-dependent.  The  us¬ 
ers  have  a  bad  habit  of  using  the  “DOS 
Shell”  command  and  then  executing 
the  application  again,  then  EXITing  back 
to  the  previous  instance  of  the  pro¬ 
gram.  This  doesn’t  cause  a  problem 
until  some  bright-minded  individual  ex¬ 
its  the  application,  EXITs  DOS,  and 
winds  up  back  in  the  first  instance  of 
the  program.  Any  changes  made  in  the 
second  instance  of  the  program  have 
now  been  lost  and  the  first  instance 
may  contain  invalid  configuration  in¬ 
formation. 


Jim  Mischel  is  a  former  financial  sys¬ 
tems  programmer  and  database  con¬ 
sultant.  He  can  be  reached  at  20  Stew¬ 
art  St.,  Durango,  CO  81301  or  on 
CompuServe:  73  71 7, 1355. 


To  complicate  matters,  the  applica¬ 
tion  runs  on  a  diskless  network  work¬ 
station,  making  it  difficult  to  create  a 
session  configuration  file.  Add  to  this 
the  TSR  that  will  be  communicating 
with  and  getting  its  configuration  in¬ 
formation  from  the  application,  and  the 
need  for  system-wide  global  variables 
becomes  evident. 

My  first  reaction,  of  course,  was  to 
use  the  DOS  environment  variables; 
an  approach  I  soon  discarded  when  I 
found  that  child  processes  can’t  change 
the  parent’s  environment.  Next  I  tried 
back-chaining  —  passing  environment 
addresses  from  one  program  to  the 
other,  thereby  always  changing  the  an¬ 
cestor’s  environment.  This  worked  fine 
but  for  two  drawbacks.  First,  if  a  change 
to  an  ancestor’s  environment  would 
required  more  memory,  DOS  would 
allocate  another  block  of  memory  above 
the  currently  active  program  —  thus  for¬ 
ever  trapping  any  programs  between 
the  ancestor  and  the  newly  allocated 
block.  The  other  problem  is  with  COM¬ 
MAND. COM.  Whenever  a  process  shells 
to  DOS,  COMMAND.COM  is  loaded 
and  assumes  that  it  is  Lord  of  the  Uni¬ 
verse  inside  your  computer.  Any  back- 
chaining  stops  at  the  latest  invocation 
ofCOMMAND.COM.  I’ve  heard  that  it’s 
possible  to  back-chain  beyond  this 
point,  but  I’m  not  too  sure  the  method 
is  stable. 

Several  months  ago,  somebody  put 
forth  this  problem  on  the  CompuServe 
DDJ  Forum.  At  that  time,  someone  else 


suggested  that  a  device  driver  be  writ¬ 
ten  that  would  support  true  global  vari¬ 
ables.  I  waited  a  while  for  the  driver  to 
appear  but  got  impatient  and  decided 
to  tackle  it  on  my  own. 

The  global  variable  device  driver  (GLO¬ 
VAR. ASM,  Listing  One,  page  104)  is 
installed  in  your  system  at  boot  time. 
Simply  place  the  line 

device=glovar.sys 

in  your  CONFIG.SYS  file  and  reboot 
the  machine.  Access  to  the  global  vari¬ 
ables  is  provided  through  the  use  of 
the  DOS  read  command  and  several 
functions  that  are  provided  in  the  de¬ 
vice  driver.  Example  programs  in  both 
Turbo  C  (GVAR.C,  Listing  Two,  page 
108,  and  GVAR.H,  Listing  Three,  page 
108),  and  Turbo  Pascal  (GVAR.PAS,  List¬ 
ing  Four,  page  108)  demonstrate  the 
use  of  the  driver.  The  Turbo  Pascal 
program  requires  an  assembly  language 
interface  to  the  driver  (TPGVAR.ASM, 
Listing  Five,  page  110).  Compile  and 
link  instructions  are  included  as  com¬ 
ments  in  the  listings. 

How  to  Use  It 

In  order  to  access  the  global  variables, 
an  application  program  must  first  open 
the  device  (using  the  standard  DOS 
open  file  function)  and  then  read  the 
address  of  the  interface  structure  from 
the  device.  The  read  routine  in  the 
device  driver  is  rather  simple  minded 
(continued  on  page  73) 
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(continued  from  page  70) 
in  that  it  assumes  the  application  is 
requesting  4  bytes  of  information  (the 
size  of  a  far  pointer).  The  device  can 
be  closed  after  this  read,  as  all  other 
functions  are  provided  through  direct 
calls  to  the  driver’s  code,  init  and  read 
are  the  only  two  DOS  functions  sup¬ 
ported  by  the  driver. 

The  interface  structure  contains  four 
far  pointers;  a  pointer  to  the  memory 
block  and  a  pointer  to  each  of  the  three 
interface  functions.  This  structure  table 
is  shown  in  the  C  header  file  (GVAR.H) 
and  in  the  Turbo  Pascal  interface  rou¬ 
tines  (TPGVAR.ASM). 

The  three  functions  provided  by  the 
device  driver,  their  C  and  Pascal  decla¬ 
rations,  and  a  short  description  are 
shown  shortly.  The  Pascal  functions 
use  a  type  VARSTR,  that  is  defined  as 

type  varstr  =  string[2551; 

function  set_gvar  (varname,  vardef  : 
varstr)  :  boolean;  external;  int  far  pas¬ 
cal  set_gvar  (const  char  far  *  varname, 
const  char  far  *  vardef); 

set_gvar  assigns  a  value  to  a  global 
variable.  It  returns  TRUE  (-1)  if  the 
variable  was  set  successfully,  or  FALSE 
(0)  if  the  global  variable  buffer  in  the 
driver  is  full.  A  variable  can  be  re¬ 
moved  by  assigning  it  a  null  value  (as 
in  se/L^gyar(“VARNAME”, "");). 

Function  get _gvar  (varname  :  varstr; 
var  vardef  :  varstr)  :  boolean;  exter- 
nafint  far  pascal  get_gvar  (const  char 
far  "varname,  char  far  *  vardef);  get_gvar 
returns  the  value  of  a  global  variable 
previously  defined  using  the  set_gvar 
function.  If  the  global  variable  exists, 
the  function  returns  TRUE  (-1)  and  the 
vardef  parameter  holds  the  value  of  the 
variable.  If  the  global  variable  does  not 
exist,  the  function  returns  FALSE  (0), 
and  the  vardef  parameter  is  a  null  string. 

procedure  flush_gvars;  external: 

void  far  pascal  flush_gvars  (void); 

flush_gvars  removes  all  variable  defini¬ 
tions  from  the  buffer. 

Using  the  routines  is  really  quite  sim¬ 
ple.  In  the  C  version,  the  three  func¬ 
tions  set_gvar(  ),  get_gvar(  ),  and  flush_ 
gvars(  )  are  macros  that  expand  to  in¬ 
direct  function  calls  through  pointers 
in  the  GVAR_DEF  structure.  The  Pascal 
version  calls  assembly  language  sub¬ 
routines  that  convert  the  passed  ar¬ 
guments  to  ASCIIZ  strings,  and  then 
perform  an  indirect  function  call  in  much 
the  same  manner  as  the  C  version. 

There  are  some  cautions  and  a  few 
restrictions  regarding  use  of  the  driver. 
First,  because  Turbo  Pascal’s  strings  have 
a  maximum  length  of  255  bytes,  there 


G  L  0  V  A  R 


is  a  possibility  of  string  overrun  when 
using  a  Turbo  Pascal  program  to  re¬ 
trieve  variables  set  by  C  or  assembly 
language  programs.  Neither  the  driver 
nor  the  Turbo  Pascal  interface  routines 
address  this  issue.  An  overrun  string 
will  most  likely  cause  your  program  to 
crash.  The  same  goes  for  C  programs  — 
if  your  buffer  is  smaller  than  the  global 
variable,  unpleasant  things  are  bound 
to  happen. 

Global  variable  names  may  contain 
any  characters  other  than  the  equal 
sign  (=)  and  null  (0).  Variable  values 
may  contain  any  character  other  than 
null.  All  variable  names  are  mapped  to 
uppercase. 

You  may  have  noticed  that  the  ad¬ 
dress  of  the  memory  block  is  provided 
in  the  GVAR_DEF  structure.  This  pointer 
has  been  provided  as  a  means  to  do 
other  things  with  the  block  of  reserved 
memory  (such  as  passing  data  between 
programs).  Note,  however,  that  using 
the  memory  in  this  manner  will  inter¬ 
fere  with  any  programs  that  are  using 
the  global  variable  routines. 

How  It  Works 

Upon  initialization,  the  driver  outputs 
a  sign-on  message,  places  the  proper 
addresses  in  the  interface  structure 
( global_table ),  sets  the  required  top-of- 
memory  address  for  DOS,  and  flushes 
the  global  variable  table.  Because  the 
initialization  code  is  executed  only  once, 
the  global  variable  table  overlays  it, 
thus  reducing  the  amount  of  memory 
taken  up  by  the  driver. 

The  read  call  is  equally  simple.  It 
merely  takes  the  address  of  the  inter¬ 
face  structure  and  writes  it  as  a  long 
pointer  into  the  buffer  provided  by  DOS 
in  the  request  header.  It  then  sets  the 
number  of  bytes  read  to  4  and  exits. 
The  set_gvar  function  works  in  two 
steps.  First,  it  finds  and  removes  the 
specified  variable  and  its  definition  from 
the  table,  moving  the  rest  of  the  entries 
to  fill  the  space  previously  occupied 
by  the  now  deleted  variable.  Then  it 
installs  the  variable  name  (mapped  to 
uppercase)  with  the  new  definition  at 
the  end  of  the  table.  This  process  is  a 
bit  slower  than  the  “use-until-full-then- 
collect-garbage”  method  of  managing 
string  space,  but  it  makes  the  driver 
code  much  simpler  (and  thus  smaller). 
If  I  was  dealing  with  a  much  larger 
block  of  memory  (in  the  order  of  10K 
or  more),  I'd  worry  more  about  the 
time  involved  in  moving  things  around. 

The  get_gvar  function  uses  the 
find_var  internal  function  to  locate  the 
variable  (if  it  exists),  finds  the  begin¬ 
ning  of  the  definition,  and  copies  it 
into  the  buffer  provided  in  the  ‘vardef 
parameter. 


The  flush_gvars  function  is  the  ulti¬ 
mate  in  simplicity.  It  simply  places  two 
null  bytes  (ASCII  0)  at  the  beginning 
of  the  table,  thereby  signifying  the  end 
of  all  defined  strings. 

I  was  a  little  apprehensive  at  first 
about  attempting  to  write  a  DOS  de¬ 
vice  driver.  Happily,  it  turned  out  to 
be  quite  a  bit  easier  than  I  had  ex¬ 
pected.  All  of  the  information  required 
was  gleaned  from  Ray  Duncan’s  excel¬ 
lent  book  Advanced  MS-DOS ,  Micro¬ 
soft  Press,  1986.  In  fact,  the  device  driver 
template  presented  in  that  book  formed 
the  basis  of  my  driver. 

The  most  difficult  part  of  this  entire 
exercise  was  getting  the  Turbo  Pascal 
interface  functions  to  work.  For  some 
reason  I  couldn’t  get  Turbo  Debugger 
to  work  in  source  debugging  mode 
with  the  assembly  language  functions. 
Most  likely,  I  was  doing  something 
wrong.  Testing  the  device  driver  was 
really  quite  simple.  I  originally  wrote 
it  to  be  linked  into  my  Turbo  C  test 
program  and  used  Turbo  Debugger  to 
test  all  the  routines.  When  I  was  con¬ 
vinced  it  was  stable,  I  made  the  neces¬ 
sary  modifications,  booted  my  system 
with  the  device  driver  installed,  and 
was  truly  amazed  when  it  worked  the 
first  time. 

In  its  present  state  the  driver  will  not 
support  concurrent  update  by  multiple 
processes.  Adding  this  functionality 
would  be  a  matter  of  returning  a  ‘busy’ 
status  in  response  to  a  get,  set,  or  flush 
call.  This  modification  is  left  as  an  exer¬ 
cise  to  the  reader. 

While  this  driver  does  not  provide 
permanent  modification  to  an  ances¬ 
tor’s  environment,  it  does  provide  a 
safe,  fast,  documented  way  to  maintain 
true  system-wide  global  variables,  thus 
achieving  the  desired  effect  without 
unnecessarily  complicating  the  appli¬ 
cation  program. 

Availability 

All  source  code  for  articles  in  this  issue 
is  available  on  a  single  disk.  To  order, 
send  $14.95  (Calif,  residents  add  sales 
tax)  to  Dr.  Dobb’s Journal ,  501  Galves¬ 
ton  Dr.,  Redwood  City,  CA  94063;  or 
call  800-356-2002  (from  inside  Calif.) 
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Please  specify  the  issue  number  and 
format  (MS-DOS,  Macintosh,  Kaypro). 


DDJ 


(Listings  begin  on  page  104.) 


Vote  for  your  favorite  feature/article. 
Circle  Reader  Service  No.  7. 


Dr.  Dobbs  Journal  October  1989 

700 


73 


First  Look  at 

CommonView 


OOP  for  Windows  and  PM 


Noel  J.  Bergman 


Object-oriented  programming 
(OOP)  promises  to  provide 
developers  with  a  wide  range 
of  benefits.  Programs  will  be 
easier  to  write,  easier  to  ex¬ 
tend,  and  easier  to  make  portable.  Com¬ 
monView  is  an  object-oriented  C++  li¬ 
brary  (currently  bundled  with  Glock¬ 
enspiel’s  first-rate  C++  implementation 
for  DOS  and  OS/2).  It  is  among  the  first 
such  packages  designed  to  bring  OOP 
to  the  masses  of  C  programmers  who 
work  with  (or  are  interested  in  work¬ 
ing  with)  Microsoft  Windows  and  OS/2 
Presentation  Manager. 

As  we  will  see,  CommonView  has  the 
potential  to  achieve  this  goal,  but  the 
current  incarnation  is  immature. 

What  is  CommonView? 

You  say  that  you’re  all  in  favor  of  easier 
and  more  portable  programming,  but 
what  is  Common-View?  CommonView 
is  an  object-oriented  library  that  maps 
the  functionality  of  graphical  user  inter¬ 
faces  (GUIs)  onto  a  set  of  object  classes. 

Glockenspiel  bundles  CommonView 
with  their  enhanced  implementation  of 
C++  for  OS/2,  DOS,  and  Windows.  The 
total  package  includes  the  C++  transla¬ 
tors,  standard  C++  libraries,  the  Com¬ 
monView  libraries,  and  tutorial  and  sam¬ 
ple  programs.  A  “driver”  program,  which 
is  similar  to  Microsoft’s  CL.  EXE  driver, 
makes  the  process  of  using  the  C++ 
package  almost  like  that  of  using  Mi¬ 
crosoft  C. 

CommonView  differs  from  most  ob¬ 
ject-oriented  programming  languages 


Noel  is  a  software  development  consul¬ 
tant  specializing  in  leading-edge  tech¬ 
nologies,  including  object-oriented  pro¬ 
gramming,  MS-Windows,  and  OS/2.  He 
can  be  reached  on  CompuServe  at: 
76704,34. 


(such  as  Smalltalk,  ACTOR,  and  C_Talk) 
that  derive  all  of  the  classes  in  a  tree 
with  a  single-base  class  ( object )  at  the 
root.  CommonView’s  classes  are  divided 
into  a  few  separate  categories:  windows 
and  events,  controls,  and  miscellaneous 
classes. 

Installing  CommonView 

For  most  programmers,  installing  Com¬ 
monView  should  be  smooth.  The  Com¬ 
monView  installation  program  allows 
you  to  specify  a  separate  directory  for 
each  type  of  file  that  the  program  in¬ 
stalls.  Unfortunately  for  me,  however, 
I  place  headers,  libraries,  and  execut¬ 
ables  on  a  different  partition  from  the 
partition  that  contains  sample  code.  The 
install  program  doesn’t  allow  you  to 
specify  separate  drives,  so  the  installa¬ 
tion  of  CommonView  on  my  personal 
system  was  more  involved.  I  had  to 
install  the  different  components  into 
the  directory  paths  where  I  wanted  the 
components  to  end  up.  I  used  XCOPY 
to  move  directories  from  the  installed 
disk  to  the  disk  where  I  wanted  them 
to  be,  and  then  deleted  the  original 
directories. 

I  encountered  only  a  few  minor 
glitches  (such  as  leaving  a  header  for 
one  of  the  sample  applications  in  the 
wrong  directory)  during  the  process 
of  installing  CommonView. 

There  is,  however,  one  major  prob¬ 
lem  for  DOS  users.  The  current  version 
of  C++  for  DOS  is  very  demanding  with 
respect  to  memory,  and  some  of  the 
sample  applications  will  not  compile 
on  most  DOS  machines.  To  solve  this 
problem,  you  can  spend  an  extra  $100 
to  buy  an  extended  memory  version 
of  C++.  As  another  solution,  you  can 
compile  under  OS/2  and  then  link  un¬ 
der  DOS,  which  is  the  route  I  took. 

A  small  problem  also  arises  if  you 


use  separate  names  for  the  different 
types  of  libraries.  For  example,  I  use 
SLIBCER,  SLIBCEP,  and  SLIBCEW  for 
the  names  of  the  small  model  libraries 
for  DOS,  OS/2,  and  Windows.  The 
driver  program  isn't  quite  smart  enough 
to  use  the  libraries  directly. 

The  modified  .CMD  and  .BAT  files 
that  I  use  to  build  CardFile  are  listed  in 
Figure  1.  Most  of  the  options  should 
be  familiar  because  they  are  the  same 
options  used  by  Microsoft  C’s  CL  driver. 
The  -IY  option  tells  CCXX  to  add  the 
library  XlibYto  the  linker’s  list.  ( X is  the 
model  size,  and  Y  is  the  extension.) 
CCXX  calls  the  resource  compiler  for 
you,  so  when  you  link  under  DOS,  the 
Windows  resource  compiler  is  called, 
rather  than  the  PM’s  resource  compiler. 

Windows  and  Events 

The  classes  that  make  up  the  Window 
hierarchy  are  listed  in  Figure  2.  The 
indentation  style  used  in  Figure  2  shows 
inheritance  relationships. 

This  category  contains  the  classes 
responsible  for  implementing  event  dis¬ 
patching  and  windows.  The  ancestor 
class  at  the  top  of  this  hierarchy  is 
EventContext,  from  which  a  single  de¬ 
scendant,  Window,  is  derived. 

CommonView’s  EventContext  class 
virtualizes  event  dispatching.  The  in¬ 
heritable  virtual  functions  are  Dispatch 
and  Default.  Dispatch  is  an  event  router. 
Default  is  the  default  event  handler, 
and  is  invoked  when  a  default  event 
handler  isn’t  overridden,  or  when  the 
dispatcher  receives  messages  for  which 
it  doesn’t  have  a  handler. 

Technically,  other  types  of  event- 
driven  systems  could  be  derived  from 
EventContext,  but  none  are  provided 
in  the  current  CommonView  release. 
In  fact,  the  CommonView  documenta¬ 
tion  says,  “Although  it  is  possible,  in 
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(continued  from  page  74) 
theory,  to  derive  from  EventContext ,  it 
is  not  possible  for  the  CommonView 
programmer  to  overload  effectively  its 
member  functions.  To  do  this  would 
require  an  indepth  knowledge  of  both 
CommonView’s  implementation  and  the 
underlying  Event  system.” 

One  of  the  drawbacks  of  this  limita¬ 
tion  is  that  you  cannot  implement  se¬ 
rial  I/O  with  CommonView,  unless  you 
resort  to  the  use  of  timer  messages.  The 
simple  fact  is  that  in  MS-Windows  there 
are  no  communications  events  to  dis¬ 
patch.  Serial  I/O  is  performed  by  using 
a  modified  event  loop  that  polls  both 
the  comm  driver  and  the  message  queue. 

Furthermore,  CommonView’s  imple¬ 
mentation  of  look  and  feel  differs  from 
the  implementation  of  look  and  feel 
that  is  represented  by  the  MS-Windows 
and  PM  Application  Style  Guides.  In  or¬ 
der  to  implement  MDI  under  Windows 
2.x,  you  must  play  some  poorly  docu¬ 
mented  tricks  with  Windows,  and  work 
with  messages  not  directly  supported 
in  CommonView.  Compounding  the 
problem  is  the  fact  that  if  you  go  to  all 
the  trouble  to  implement  MDI  under 
CommonView,  you  will  code  look  and 
feel  directly  into  your  application.  If 
you  port  your  application  to  other  en¬ 


vironments  you  will  be  required  to 
change  look  and  feel,  and  thus  losing 
much  of  the  promised  portability.  Also, 
if  Microsoft  changes  either  the  MDI  speci¬ 
fication  or  the  way  in  which  the  speci¬ 
fication  is  implemented  (highly  likely), 
you  will  have  to  change  the  application 
code.  This  should  be  the  responsibility 
of  the  library. 

If  you  decide  to  implement  the  Mi¬ 
crosoft  Style  Guide  suggestions  in  your 
application,  you  will  want  to  create  your 
own  “appropriate  look  and  feel”  object 
subclasses  based  upon  the  Common- 
View  classes,  and  then  use  them  through¬ 
out  your  coding.  This  approach  makes 
the  process  of  moving  your  Common- 
View  application  to  a  new  environment 
less  problematic.  A  sample  MDI  appli¬ 
cation  available  from  Microsoft  upon 
request  or  for  downloading  from  their 
CompuServe  Forum.  The  sample  appli¬ 
cation  illustrates  most  of  the  nastier 
tricks  that  are  necessary. 

The  Window  class  provides  two  tilings. 
First,  it  implements  an  Event  system  for 
windows.  Second,  it  defines  the  meth¬ 
ods  for  manipulating  Window  objects. 

The  first  point  is  important  to  under¬ 
stand.  Normal  MS-Windows  or  PM  pro¬ 
gramming  involves  the  use  of  the  "Win¬ 
dow  Procedure"  or  WndProc.  In  Com¬ 


monView,  WndProc  is  virtualized  within 
the  Window  classes’  event  handlers.  The 
event  handlers  contain  the  list  of  pri¬ 
vate  entry  points  to  which  Event  ob¬ 
jects  are  sent  in  response  to  messages 
being  received  from  the  environment. 

This  process  is  performed  by  trans¬ 
lating  MS-Windows  messages  into  Com¬ 
monView  Event  objects,  and  then  dis¬ 
patching  them  to  the  correct  handler 
in  the  relevant  window. 

The  different  subclasses  of  Event  can 
be  received  by  the  different  types  of 
event  handlers.  The  subclass  represent 
mouse  events,  key  events,  scroll  events, 
menu  events,  control  events,  and  win¬ 
dow  status  events. 

The  Window  class  implements  ap¬ 
proximately  30  event  handlers  that  re¬ 
ceive  and  act  on  these  Event  objects. 
Some  representative  event  handlers  are 
Windowlnit ,  MouseButtonDn ,  Activate , 
Expose ,  VerticalScroll,  and  MenuSelect. 
Most  CommonView  programmers  will 
spend  the  majority  of  their  time  writing 
event  handlers.  New  types  of  Window 
subclasses  are  created  by  deriving  a 
subclass  and  overriding  the  inherited 
event  handlers  with  new  event  han¬ 
dlers,  which  implement  the  behaviors 
unique  to  the  new  class. 

ChildAppWindow  represents  child 
windows.  ChildAppWindows  are  owned 
by  instances  of  TopAppWindoiv ,  the 
class  that  represents  pop-up  windows 
in  MS-Windows.  DialogWindow  in¬ 
stances  are  modal  dialogs.  If  you  want 
to  create  modeless  dialogs,  build  them 
by  using  the  AppWindow  subclasses 
and  Controls. 

Control 

All  of  the  classes  in  the  Control  hierar¬ 
chy  (Figure  3)  that  come  with  Com¬ 
monView  should  also  be  familiar  to 
Windows  and  PM  programmers.  This 
hierarchy  consists  of  many  of  the  com¬ 
mon  controls  that  most  programmers 
already  use,  and  can  easily  be  extended. 
It  is  important  to  understand  that  Con¬ 
trols  do  not  do  anything  in  the  Com¬ 
monView  structure.  Controls  cause  in¬ 
stances  of  ControlEvt ,  ScrollEvt ,  EditEvt , 
and  so  on  to  be  generated  and  dis¬ 
patched  to  event  handlers  that  belong 


EventContext 

Window 

AppWindow 

TopAppWindow 

ChildAppWindow 

DialogWindow 


Figure  2:  Classes  that  make  up  the 
Window  hierarchy 


MK.BAT:  — The  original  batch  file  from  Glockenspiel 


CCXX 

-c 

-Gw 

-Zp 

cardfile.cxx 

ccxx 

-c 

-Gw 

-Zp 

edit.cxx 

ccxx 

-c 

-Gw 

-Zp 

expose. cxx 

ccxx 

-c 

-Gw 

-Zp 

cardapp.cxx 

ccxx 

-c 

-Gw 

-Zp 

cardstor.cxx 

ccxx 

-c 

-Gw 

-Zp 

dlg.cxx 

ccxx 

-c 

-Gw 

-Zp 

menu. cxx 

ccxx 

-c 

-Gw 

-Zp 

misc.cxx 

ccxx 

-Gw 

-Zp 

/NOE 

*.OBJ  -oCardFile  CardFile.RC  slibw.LIB 

CardFile.DEF 


COMPIT.CMD:  A  batch  file  to  compile  under  OS/2 

set  cl— 
set 

INCLUDE=c:\pmsdk\include;c:\windows\include;c:\commonvu\inc!ude 
set  ccxx=-Lr  -FPi  -Gsw  -Zp 


CCXX 

-c  -Zp 

cardfile.cxx 

CCXX 

-c  -Zp 

edit.cxx 

ccxx 

-C  -Zp 

expose. cxx 

ccxx 

-c  -Zp 

cardapp.cxx 

ccxx 

-c  -Zp 

cardstor.cxx 

ccxx 

-c  -Zp 

dlg.cxx 

ccxx 

-c  -Zp 

menu.cxx 

ccxx 

-c  -Zp 

misc.cxx 

LINKIT.BAT:  A  batch  file  to  link  under  DOS  with  the  Windows  library 


set  cl— 

set  LIB=c:\pmsdk\lib;f:\winsdk\lib;c:\njb\lib 
set  ccxx=-Lr  -Icew  -FPi  -Gsw  -Zp 

ccxx  /NOE  *.OBJ  -oCardFile  CardFile.RC  slibw.LIB  /NOD:slibce 
CardFile.DEF 


Figure  1:  The  modified  CMD  and  .BAT files  used  to  build  CardFile 
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to  windows.  Ail  of  the  work  is  perform¬ 
ed  in  the  event  handlers.  The  construc¬ 
tors  used  to  build  the  Control  instances 
attach  the  Controls  to  DialogWindow 
or  AppWindow  subclass  instances.  Text 
controls  do  handle  the  text  editing  that 
is  part  of  the  representation. 

Miscellaneous  Classes 

CommonView  provides  other  classes 
such  as  cursors  and  bitmaps,  although 
not  in  any  particular  hierarchy.  The 
collection  of  classes  is  provided  in  Fig¬ 
ure  4.  Most  of  these  classes  should  be 
familiar  to  Windows  programmers  and 
PM  programmers  because  they  repre¬ 
sent  things  within  those  environments 
with  which  we  are  already  acquainted. 
For  example,  Accel  is  a  class  for  build¬ 
ing  and  working  with  keyboard  accel¬ 
erators.  BitMap  is  a  class  for  working 
with  bitmaps.  ResString,  on  the  other 
hand,  may  not  be  familiar.  This  class  is 
CommonView’s  way  to  handle  con¬ 
stant  strings  in  Resource  files.  ResStrings 
can  be  useful  for  allowing  localization 
of  your  program  (that  is,  customize 
messages  or  switch  languages).  Pair 
simply  provides  an  ordered  pair  of  in¬ 
tegers,  but  is  still  a  useful  class.  For 
example,  Range  can  specify  the  limits 


of  a  scrollbar,  a  Point  might  contain  a 
screen  location. 

Containers 

CommonView  comes  with,  and  makes 
extensive  use  of,  a  set  of  extremely 
useful  classes  that  Glockenspiel  de¬ 
signed  and  released  to  the  public  do¬ 
main.  These  classes  are  Container  md 
FreeStore,  which  make  up  Common¬ 
View’s  memory-management  system. 

Containers  are  a  virtualization  of 
various  logical  access  methods.  For 
example,  CommonView  provides  Heaps , 
Rings,  Stacks,  and  Tables.  Containers 
represent  the  way  that  we  think  about 
locating  and  accessing  our  data.  For 
example,  Tables  provide  keyed  access 
to  data.  They  are  implemented  as  Rings 
with  key  access,  but  could  also  be  im¬ 
plemented  with  a  B-tree.  Containers 
do  not  handle  the  actual  storage  of  the 
items  —  that  is  where  FreeStore s  come 
into  play. 

FreeStore s  are  a  virtualization  of  physi¬ 
cal  (rather  than  logical)  access  to  data. 
They  provide  a  virtual  Heap  construct, 


Control 

ScrollBar 

HorizScrollBar 

VerticalScrollBar 

Fixedlcon 

TextControl 

Edit 

SingleLineEdit 

MultiUneEdit 

FixedText 

ListBox 

Button 

PushButton 

ClickBox 

RadioButton 

Figure  3-'  Classes  in  the  Control 
hierarchy 
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Figure  4:  The  collection  of  miscella¬ 
neous  classes  provided  in  CommonView 


on  top  of  which  the  Container  classes 
are  built.  CommonView  comes  with 
three  FreeStore  classes  for  MS-Windows: 
LocalHeap,  GlobalHeap,  and  disk-based 
Heap.  The  disk-based  FreeStore  has  not 
been  implemented  for  OS/2,  although 
that  will  undoubtedly  be  corrected  in 
a  future  release.  The  source  for  all  of 
the  Container  and  FreeStore  classes  is 
provided,  so  you  can  implement  the 
disk-based  FreeStore  yourself  if  you 
need  it. 

Containers  and  FreeStore. s  take  data 
and  provide  you  with  handles.  Each 
Container  is  typed,  which  means  that 
you  only  store  a  single  kind  of  data 
within  the  Container.  Actually,  how¬ 
ever,  this  is  not  entirely  true.  As  long 
as  each  item’s  class  is  derived  from  the 
class  whose  type  the  Container  holds, 
it  is  OK  to  store  instances  of  that  class 
in  the  Container.  Thus,  if  you  create  a 
Heap  of  Windows,  you  can  store  in¬ 
stances  of  any  Window  subclass  within 
that  Heap. 

A  third  class,  Lock,  is  related  to  Con¬ 
tainers  and  FreeStores.  Lock  is  used  to 
access  data  contained  within  that  Heap. 
A  Lock  is  created  with  the  handle  of  the 
data  item,  and  ensures  that  the  data  is 
both  available  in  memory  and  locked 
in  place.  When  you  are  finished  with 
the  Lock ,  you  destroy  it,  either  explic¬ 
itly  or  by  letting  it  go  out  of  scope. 

The  Lock  class  is  primarily  an  OOP 
convenience.  The  actual  locking  and 
unlocking  process  is  performed  by  the 
FreeStore. 

DOODLE:  A  Sample  CommonView 
Application 

Let’s  take  a  look  at  a  simple  WinApp 
from  the  CommonView  package  that 
simply  allows  us  to  freehand  sketch 
with  the  mouse.  DOODLE  (Listing  One, 
below)  is  about  as  basic  a  Common- 


Listing  One 

#include  cCoiranonVu . hxx> 

class  DoodleWind  i  public 

TopAppWindow 

Point  LastPt; 

protected: 

long  far  MouseDrag  (  MouseEvt  }  ; 

long  far  MouseButtonDn  {  MouseEvt  ) ; 

>; 

void  App::far  Start  () 

DoodleWind  Doodle; 

Doodle . EnableSysMenu  ( ) ; 
Doodle. EnableBorder  ( > ; 
Doodle. SetCaptioh  {  "Doodle1 
Doodle. Show  (); 

Exec  ( ) ; 

} 

); 

long  DoodleWind: : far  MouseButtonDn {  MouseEvt  Evt ) 

LastPt  =  Evt. Where  {); 

} 

long  DoodleWind: : far  MouseDrag 

(  MouseEvt  Evt  ) 

MoveTo  (  LastPt  ) ; 

LineTo  {  LastPt  =  Evt. Where 

} 

(Hi 

End  Listing 
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View  program  as  one  might  want  to 
write. 

DOODLE  defines  a  new  subclass  of 
TopAppWindow.  This  new  type  of  win¬ 
dow,  the  DoodleWind ,  only  overrides 
two  of  the  inherited  default  event  han¬ 
dlers:  MouseButtonDn  and  MouseDrag. 
Notice  that  no  constructor  is  defined 
for  DoodleWind.  The  protected  con¬ 
structor  inherited  from  TopAppWindow 
is  sufficient. 

When  the  mouse  button  is  depressed, 
DoodleWind  remembers  the  starting 
location  for  the  freehand  sketch.  When 
the  mouse  Ls  moved,  DoodleWind  moves 
to  the  last  remembered  location  of  the 
mouse,  draws  a  line  from  that  location 
to  the  current  mouse  location,  and  re¬ 
members  the  current  mouse  location 
for  use  the  next  time  MouseDrag  is 
invoked  by  the  Event  dispatcher. 

That’s  it.  In  a  few  lines  of  code  this 
WinApp  creates  a  movable,  resizable 
window  with  a  system  menu,  and  is 
capable  of  freehand  drawing.  We  could 
extend  it  fairly  easily.  Let’s  say  that  we 
maintain  a  list  of  the  mouse  locations 
used  in  the  drawing,  perhaps  by  using 
a  subclass  of  Ring  —  one  of  Common- 
View’s  Container  classes.  We  would 
override  the  default  Expose  handler  to 
repaint  the  display,  using  the  stored 
Points  in  our  PointRing.  We  also  over¬ 
ride  the  default  MenuCommand  han¬ 
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dler  while  adding  a  menu  item,  in  or¬ 
der  to  erase  the  list  of  Points  and  start 
over.  When  MenuCommand  handles 
the  erase  request,  it  should  also  use  the 
RePaint  method  provided  by  Window 
in  order  to  force  a  redisplay  of  the  whole 
window  —  MenuCommand  should  not 
erase  the  window  itself. 

MoveTo  and  LineTo  are  methods  in¬ 
herited  from  Window.  LineTo ,  Paint- 
Rectangle ,  and  TextPrint  are  essentially 
the  only  output  methods  that  belong  to 
Window,  although  there  is  control  over 
the  fonts,  line  types,  and  so  on  that  the 
output  methods  would  display. 

Glockenspiel  is  developing  a  Draw- 
Object  hierarchy  that  would  contain 
all  of  the  things  that  could  be  displayed 
within  windows.  In  the  meantime,  you 
can  “kick  down."  This  term  means 
that  you  ask  a  CommonView  object 
to  give  you  its  Window  or  PM  handle, 
so  that  you  can  write  code  directly  to 
the  environment. 

Drau'Objects  will  respond  to  a  Draw 
message  and  will  be  owned  by  Win¬ 
dows.  Glockenspiel  had  intended  to 
provide  some  samples,  but  pulled  them 
from  the  disk  at  the  last  minute.  A  late 
summer  release  of  CommonView  is  ex¬ 
pected  to  include  DrawObject,  so  by 
the  time  you  read  this  article,  some 
examples  should  be  available  to  use 
as  models  for  your  own  classes. 


DOODLE  also  shows  us  the  basic 
structure  of  a  CommonView  program. 
It  contains  a  class,  App.  This  class  has 
a  method,  Start( ),  that  we  need  to 
provide.  App::Start( )  is  the  Common- 
View  equivalent  of  main( ). 

App::Start( )  first  creates  a  window 
by  declaring  an  instance  of  Doodle¬ 
Wind.  The  system  menu,  a  border,  and 
a  caption  are  added  to  the  window. 
Finally,  the  window  is  made  visible, 
and  CommonView’s  dispatcher  [Exec( )] 
is  turned  on. 

This  is  the  basic  structure  to  the 
CommonView  initialization  and  start¬ 
up  sequence.  You  will  see  this  struc¬ 
ture  repeated  in  each  CommonView 
application. 

Conclusion 

CommonView  does  make  simple  Win¬ 
dows  and  PM  applications  easier  to 
use.  The  compiled  applications  are 
very  fast  and  small  due  to  the  fact  that 
CommonView  is  contained  in  a  DDL 
(and,  in  fact,  encourages  the  creation 
of  other  DDLs).  Unfortunately,  with  Com¬ 
monView’s  current  limitations  —  includ¬ 
ing  the  lack  of  printer  support,  Event- 
Contexts  documentation,  or  graphics  — 
the  initial  release  of  the  product  may 
prove  unusable  for  many  programmers. 
The  major  upgrade  expected  in  late 
summer  1989  is  alleged  to  correct  the 
vast  majority  of  these  problems,  and  is 
anxiously  awaited  by  many  Common- 
View  pioneers. 

Availability 

All  source  code  for  articles  in  this  issue 
is  available  on  a  single  disk.  To  order, 
send  $14.95  (Calif,  residents  add  sales 
tax)  to  Dr.  Dobb’s Journal,  501  Galves¬ 
ton  Dr.,  Redwood  City,  CA  94063,  or 
call  800-356-2002  (from  inside  Calif.) 
or  800-533-4372  (from  outside  Calif.). 
Please  specify  the  issue  number  and 
format  (MS-DOS,  Macintosh,  Kaypro). 
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Soft  Inc. ,  2  Haven  Ave. ,  Port  Washing¬ 
ton,  NY  11050,  800-245-8840.  Sys¬ 
tem  requirements:  IBM  PC  AT  or 
compatibles  with  at  least  640K  of 
RAM,  Microsoft  Windows  2.03  Soft¬ 
ware  Developer’s  Kit  (SDK)  or  Pres¬ 
entation  Manager  1.0  SDK,  Micro¬ 
soft  C  5.1  compiler.  CommonView 
is  bundled  with  Glockenspiel’s  C++ 
for  $495. 
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Listing  One  (Text  begins  on  page  18.) 

LF  =  #10; 

Unit  Serial  10; 

Type  Queue  type  =  record 

{ ************  unit  interface 

Description  ***************} 

queue  :  array [1 . .queue  max]  of  byte; 

Interface 

front, rear  :  integer; 

Type  Confiq  rec 

=  record 

contains  the  configuration  info  } 

count  :  integer; 

for  serial  communication  and  user} 

end; 

interface  } 

Port  Status  =  (XON,  XOFF) ; 

IRQ 

:  Integer; 

Port 

:  Integer; 

Var  Transmit  Queue, 

Data 

:  Integer; 

Receive  Queue  :  Queue  Type; 

Baud 

:  Integer; 

Receive  Status, 

Rate 

:  integer;  {  bytes/sec  } 

Transmit  Status  :  Port  Status; 

Parity 

:  Char; 

Com  STS  :  Integer;  (  Serial  Status  I/O  Port  } 

StopB 

ts 

:  Integer; 

mask  value  :  integer;  {  Control  mask  word  } 

DataBits 

:  Integer; 

old  isr  :  pointer;  {  storage  for  com  port  } 

Snow 

:  Boolean; 

(  ISR  vector  in  place  ) 

Lines 

:  Integer; 

( **********************************************************  j 

Attention 

:  String[40]; 

(  Serial  Interrupt  Service  Routine  -  grab  the  char  and  put  ) 

Fore 

:  Integer; 

(  it  in  the  queue  ) 

Ba 

:k 

:  Integer; 

1  *************.************,****,*,****,****,****,«********  j 

end; 

Procedure  Serial  ISR;  Interrupt; 

var  ch  :  byte;  I  for  the  incoming  char  } 

Var  Current  Cfg 

Con fig  Rec; 

regs  :  registers;  (  for  using  BIOS  to  beep  bell  } 

Procedure  Check 

Receive  (var 

ch  :  char) ; 

next  rear  :  integer; 

Procedure  Check 

Send; 

begin 

Procedure  Configure (  New  Cfg 

:  Con fig  Rec  ) ; 

inline ($FA);  (  Disable  interrupts  } 

ch  :=  port [current  cfg. data);  (  get  character  from  port  ) 

{ *************** 

****  unit 

Implementation  ******************) 

with  receive  queue  do 

Implementation 

begin 

uses  dos,crt; 

( 

DOS 

and  CRT  units  are  utilized  } 

next  rear  :=  rear  +  1; 

Const  queue_max 

=  3936 

1 

queue  can  hold  48  lines  X  82  char} 

if  next  rear  >  queue  max  then  {  wrap  the  pointer  if  } 

next  rear  :=  1;  (  necessary  } 

{  ***********  Serial  Port 

Constants  ***********************} 

if  next  rear  <>  front  then 

C0M1  data 

=  $03f8; 

{  C0M1  Data  port  } 

begin  (  put  char  in  queue  ) 

C0M1  IRQ 

=  $04 

(  COM1  IRQ  Number} 

rear  :=  next  rear; 

COM2  data 

=  $02f8; 

{  COM2  Data  port  } 

queue [rear]  :=  ch; 

COM2  IRQ 

=  $03; 

{  COM2  IRQ  Number) 

end 

ier  offset 

=  1; 

{  UART  IER  Reg  ) 

else 

mcr  offset 

=  4; 

{  UART  Master  Reg) 

begin  [  queue  full, beep  bell  } 

sts  offset 

=  5; 

(  UART  Status  Reg) 

regs. ax  :=  $0E07; 

IRQ 3  Int 

=  $0B 

{  IntVec  for  IRQ3} 

intr ($10, regs) ; 

IRQ4  Int 

=  $oc 

(  IntVec  for  IRQ4} 

IRQ5  Int 

=  SOD 

{  IntVec  for  IRQ5 } 

inc (count);  {  Inc  #  entries  and  ) 

IRQ6  Int 

=  $0E 

{  IntVec  for  IRQ6) 

{  Check  for  queue  getting  full.  Send  XOFF  when  one  ) 

IRQ 7  Int 

=  $0F 

(  IntVec  for  IRQ7} 

{  second  of  space  left  ) 

PIC  CTL 

-  $20 

{  Cmd  for  8259  } 

PIC  MASK 

=  $21 

(  Mask  for  8259  } 

EOI 

=  $20 

(  Eol  command  } 

Receive  status  :=  XOFF; 

XOFF  Char 

=  #19 

{  AS  } 

repeat  until  (port [com_sts]  and  TBE)<>0; 

XON  Char 

=  #17 

{  AQ  } 

CR 

=  #13 

COMMUNICATIONS  LINKS 


Listing  One  (Listing  continued,  text  begins  on  page  18.) 

5  :  Int  Num  :=  IRQ5  Int; 

6  :  Int  Num  :=  IRQ6  Int; 

port [current  cfg. data]  := 

ord (XOFF  Char); 

7  :  Int  Num  :=  IRQ7  Int; 

end; 

end; 

end; 

{  END  WITH  } 

mask  value  :=  port [pic  mask]; 

inline ($FB);  (  Enable  interrupts  ) 

mask  value  :=  mask  value  or  (1  shl  current  cfg. IRQ); 

port (PIC  CTL]  :=  EOI  {  send 

end  of  interrupt  to  PIC  } 

port (pic  mask]  :=  mask  value; 

end;  (  END  PROCEDURESERIAL  ISR  } 

SetlntVec (Int  Num,  Old  ISR);  {  Restore  the  com  port  int-) 

(  errupt  vector  ) 

(********************************** 

************************} 

Receive  Status  :=  XOFF; 

(  Attach  Com  Port  Procedure  -  takes 

over  interrupt  vector  } 

Transmit  Status :=  XOFF; 

(  and  initializes  the  UART  entries 

in  the  configuration  ) 

end; 

(  table. 

} 

j ********************************** 

j ********************************************************** j 

Procedure  Attach  Com  Port; 

{  Check  Receive  Procedure  -  This  procedure  checks  the  in-  ) 

var  mask  value  :  byte; 

(  coming  com  port  queue.  If  any  characters  are  waiting,  ) 

Int  Num  :  integer; 

(  they  are  appended  to  the  incoming  string  for  program  } 

begin 

(  processing.  } 

Case  Current  Cfg. IRQ  of 

I************************** ******************** ************) 

3  :  Int  Num  :=  IRQ3  Int; 

Procedure  Check  Receive  (var  ch  :  char); 

4  :  Int  Num  :=  IRQ4  Int; 

begin 

5  :  Int  Num  :=  IRQ5  Int; 

with  receive  queue  do 

6  :  Int  Num  :=  IRQ6  Int; 

if  front  <>  rear  then  (  Queue  empty  when  front  ptr  ) 

7  :  Int  Num  ;=  IRQ7  Int; 

(  =  rear  ptr  ) 

end; 

begin 

GetlntVec (Int  Num,  old  ISR); 

1  Save  old  intvec  ) 

front  :=  front  +  1; 

SetlntVec (Int  Num,  @Serial  ISR); 

(  point  to  the  ) 

if  front  >  queue  max  then 

(  Serial  ISR  procedure  ) 

front  :=  1; 

port [Current  Cfg.data+mcr  Offset] 

:=  $0B;  {  Set  DSR/OUT2  } 

ch  :=  chr (queue [front] ) ; 

port [Current  Cfg.data+ier  Offset] 

:=  $01;  [  enable  ints  } 

Case  ch  of 

mask  value  :=  port [pic  mask); 

[  read  PIC  mask) 

XOFF  Char  :  Transmit  Status  :=  XOFF; 

mask  value  :=  mask  value  and 

j  allow  ints  ) 

XON  Char  :  Transmit  Status  :=  XON; 

(not  (1  shl  current  cfg. 

irq) ) ;  (on  com  port  ) 

end;  {  END  CASE  CH  ) 

port [pic  mask]  :=  mask  value; 

{  write  it  back) 

{  to  PIC  ) 

[  Check  queue  count  and  send  XON  if  receiving  stop-  } 

receive  status  :=  XON; 

{  send  XON  to  J 

[  ped  and  queue  has  2  seconds  of  space  free  } 

repeat  until  (port [com  sts]  and  TBE)<>0;  (  let  other  end) 

dec (count) ; 

port  [current  cfg. data]  :=  ord (XON 

Char);  [  know  we're  } 

if  (count  -  (2  *  current  cfg. rate))  >  0  then 

{  here.  } 

begin 

transmit  status  :=  XON; 

receive  status  :=  XON; 

end; 

(  END  ATTACH  COM  PORT  ( 

repeat  until  (port [com  sts]  and  TBE)<>0; 

port [current  cfg. data]  :=  ord (XON  Char); 

j***********************!********** 

************************  1 

[  Release  Com  Port  Procedure  -  Gives  the  com  port  interrupt) 

end;  (  END  IF  FRONT  <>  REAR  } 

{  back  to  the  previous  holder. 

) 

end;  {  END  PROC  CHECK  RECEIVE  ) 

j********************************** 

************************  . 

Procedure  Release  Com  Port; 

Var  Int  Num  :  Integer; 

{  Check  Send  Procedure  -  This  procedure  handles  sending  } 

(  chars  out  the  COM  port.  If  there  are  any  characters  wait-  ) 

Case  Current  Cfg. IRQ  of 

1  ing  in  the  send  queue,  they  are  sent  one  at  a  time.  ) 

3  :  Int  Num  :=  IRQ3  Int; 

j***********************************************************j 

4  :  Int_Num  :=  IRQ4_Int; 
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Listing  One  (Listing  continued,  text  begins  on  page  18.) 

Procedure  Check_Send; 

Var  ch  :  char; 
done  :  boolean; 

Begin 

done  :=  false; 
with  transmit_queue  do 
repeat 

if  (front  =  rear)  or  {  Queue  empty  when  front  ptr  ) 

(  =  rear  ptr  ) 

(Transitu. t_Status  =  XOFF)  then  {  Don't  send  | 

done  :=  true 
else 
begin 

if  front  >  queue_max  then 
front  :=  1; 

ch  :=  chr (queue [front] ) ; 
repeat  until  (port [com_sts]  and  TBE)<>0; 
port [cur rent_cfg. data]  :=  ord(ch); 
end; 

until  done; 

End;  (  END  PROCEDURE  CHECK_SEND  ) 

Procedure  Configure!  New_Cfg  :  Config  Rec  ); 

begin 

(  Routine  here  reads  configuration  file  based  on  location  ) 

(  contained  in  environment  string,  then  attaches  the  com  ) 

(  port  and  sets  communication  parameters  } 

end; 

begin  (  Unit  Initialization  ) 

Configure!  Current_Cfg  ); 

end. 

Listing  Two 

Unit  Packet_Comms; 

Interface 

Const  Pkt_PDP_OK  =  100 
Pkt_Dev_hdr  =  101 
Pkt_Dev_lst  =  102 
Pkt_Q  hdr  =  103 
Pkt~Q~lst  =  104 
Pkt_PDP_Err  =  105 
Pkt_Micro_OK  =  200 
Pkt_Print_Sel  =  201 
Pkt_Q  Req  =  202 
Pkt_Q_Del  =  203 
Pkt_Q_Move  =  204 
Pkt_Q_Hold  =  205 
Pkt_Q  Rel  =  206 
Pkt_Prt_Start  =  207 
Pkt_Prt_End  =  208 
Pkt_Micro_err  =  209 
Invalid_PDP_Packet  =  01; 

Invalid  Checksum  =  02; 


End  Listing  One 


Type  Seq_Type  =  array[1..2] 
Fname_Type  =  array [1.. 9] 
Dname_Type  =  array [1.. 20] 
Packet_Rec  =  Record 

Data_Checksum 
Case  Packet_Type 
Pkt_PDP_OK: 
Pkt_Dev_Hdr 
Pkt  Dev  Lst 


Pkt_Q_Hdr : 
Pkt  Q  Lst: 


Pkt_PDP_Err : 
Pkt_Micro_Ok : 
Pkt_Print_Sel : 
Pkt_Q_Req: 
Pkt_Q__Del : 

Pkt_Q_Move : 

Pkt_Q_Hold: 

Pkt  Q  Rel: 


of  char; 
of  char; 
of  char; 

array [1 . .5]  of  char; 

:  byte  of 

(*  PDP-11  OK  has  no  fields  *)(); 
(Number_of_Devices  :  Seq_Type) ; 
(Dev_Num 
Dev_Name 
Desc 
Default 
(Num_Entries 
(Q_Seq 
Q_F i lename 
User 
Length 
Date 
Time 

(PDP  Error 


Seq_Type; 

Dname_Type; 

array  [1..40]  of  char; 
char) ; 

Seq_Type) ; 

Seq_Type; 

Fname_Type; 

array  [1.  .20]  of  char; 
array  [1..7]  of  char; 
array  [1 . . 10]  of  char; 
array  [1..5]  of  char);6 
Char) ; 

(*  Micro  OK  has  no  fields  *) (); 
(Print_Name  :  Dname_Type) ; 

(*  Request  for  queue  list  *)(); 


(D_Fi lename 
Del_Flag 
(M_Fi lename 
Position 
(H_Fi lename 
(R  Filename 


Fname_Type; 
Char) ; 
Fname_Type; 
Seq_Type ) ; 
Fname_Type) ; 


Procedure 

Procedure 

Procedure 

Procedure 

Procedure 

Procedure 

Procedure 

Procedure 


Req_Q 

DelEntry 

Move_Entry 

Hold_Entry 

Rel_Entry 

Print_Start 

Print_End 

Micro  Err 


(  Var 
Var 
(  Var 
Var 
(  Var 
Var 
(  Var 
Var 
(  Var 
Var 
(  Var 
Var 
(  Var 
Var 
(  Var 
Var 


Packet 

Comp_Checksum 

Packet 

Comp_Checksum 

Packet 

Comp_Checksum 

Packet 

Comp_Checksum 

Packet 

Comp_Checksum 

Packet 

Comp_Checksum 

Packet 

Comp_Checksum 

Packet 

Comp_Checksum 


Packet_Rec; 
Integer) ; 
Packet_Rec; 
Integer) ; 
Packet_Rec; 
Integer)  ; 
Packet_Rec; 
Integer) ; 
PacketRec; 
Integer) ; 
Packet_Rec; 
Integer) ; 
Packet_Rec; 
Integer) ; 
Packet_Rec; 
Integer) ; 


Integer; 


Pkt_Prt_ 

Start : 

(*  Print  file 

initialize  *) () ; 

Pkt 

_Micro_OK: 

Micro  Ack 

(  Packet, 

Comp  Checksum 

Pkt  Prt 

End: 

(*  Print  file 

end  *)  ()  ; 

Pkt 

Print  Sel: 

Print_Select 

(  Packet, 

Comp  Checksum 

Pkt  Micro  Err: 

(Micro  Error  : 

Char)  ; 

Pkt 

Q  Req: 

Req_Q 

(  Packet, 

Comp_Checksum 

End; 

Pkt 

_Q_Del : 

Del  Entry 

(  Packet, 

Comp  Checksum 

Pkt 

Q  Move: 

Move_Entry 

(  Packet, 

Comp_Checksum 

Procedure  Receive  Packet 

(  Var 

Packet  :  Packet 

_Rec  )  ; 

Pkt 

"Q  Hold: 

Hold  Entry 

(  Packet, 

Comp  Checksum 

Procedure  Send  Packet 

(  Var 

Packet  :  Packet 

_Rec  )  ; 

Pkt 

J2_Rel: 

Rel  Entry 

(  Packet, 

Comp_Checksum 

Pkt" 

"Prt_Start : 

Print  Start 

(  Packet, 

Comp_Checksum 

Implementation 

Pkt" 

Prt  End: 

Print  End 

(  Packet, 

Comp  Checksum 

Uses  SeriallO; 

Pkt" 

Micro  Err: 

Micro  Err 

(  Packet, 

Comp  Checksum 

Procedure  PDP  OK 

(  Var 

Packet  : 

PacketRec; 

end; 

Procedure  Dev_Header 
Procedure  Dev_Desc 
Procedure  Q_Header 
Procedure  Q_Entry 
Procedure  PDP_Err 
Procedure  Micro_Ack 
Procedure  Print  Select 


Var  Comp_Checksum 
(  Var  Packet 
Var  Comp_Checksum 
(  Var  Packet 
Var  Comp_Checksum 
(  Var  Packet 
Var  Comp_Checksum 
(  Var  Packet 
Var  Comp_Checksum 
(  Var  Packet 
Var  Comp_Checksum 
(  Var  Packet 
Var  Comp_Checksum 
(  Var  Packet 
Var  Comp_Checksum 


Integer) ; 
Packet_Rec; 
Integer) ; 
Packet_Rec; 
Integer) ; 
Packet_Rec; 
Integer) ; 
Packet_Rec; 
Integer) ; 
Packet_Rec; 
Integer) ; 
PacketRec; 
Integer) ; 
Packet_Rec; 
Integer) ; 


Procedure  ReceivePacket (  Var  Packet  :  Packet_Rec  ); 

Va r  Comp_Checksum, Comm_Checksum, Count ,  Val_Error 
ch  :  Char; 

Err_Flag  :  Boolean; 

Checksum_Str  :  string [5]; 

begin 

Err_Flag  :=  Falser- 
Repeat 

comp_checksum  :=  0; 
with  packet  do 
begin 

check_receive (  ch  )  ; 

Val(ch,  packet_type,  val_error) ; 

Case  packet_type  of 

Pkt_PDP_OK:  PDP_OK  (  Packet,  Comp_Checksum  ); 

Pkt_Dev_Hdr:  Dev_Header  (  Packet,  Comp_Checksum  ); 

Pkt_Dev_Lst:  Dev_Desc  (  Packet,  Comp_Checksum  ); 

Pkt_Q_Hdr:  Q_Header 

Pkt_Q_Lst:  Q_Entry 

PKT_PDP_Err :  PDP_Err 

else 
begin 

packet_type  :=  Pkt_Micro_Err; 

Micro_Error  :=  chr (Invalid_Checksum) ; 

Send_Packet (  Packet  ) ; 

Err_Flag  :=  True; 
end; 
end; 

If  not  Err_Flag  then 
begin 

For  Count  :=  1  to  5  dc 
begin 

Checkreceive (  ch  )  ; 
checksum_str  :=  checksum_str  • 
end; 

Val (Checksum_str,  comm_checksum,  val_error) ; 

If  (val_error<>0)  or  (Comm_Checksum<>Comp_Checksum)  then 
begin 

packet_type  :=  Pkt_Micro_Err; 

Micro_Error  :=  chr ( Invalid_Checksum)  ; 

3end_Packet (  Packet  ) ; 

Err_Flag  :=  True; 
end 
else 
begin 

packet_type  :=  Pkt_Micro_Ack; 

Send_Packet (  Packet); 

end;  (  End  Error  ) 

end;  {  End  Checksum  Rev  ( 

end;  (  End  With  Packet  } 

Until  not  Err_Flag; 
end; 

Procedure  Send_Packet (  Var  Packet  :  Packet_Rec  ) ; 

Var  ch  :  Char; 

Comp_Checksum, 

Count, 

Va l_Error 
Err_Flag 
Checksum_Str 
Temp_Packet 


(  See  if  a  packet's  coming] 


(  Packet,  Comp_Checksum  ); 
(  Packet,  Comp_Checksum  ); 
(  Packet,  Comp_Checksum  ); 


End  CASE  ) 


ch; 


Integer; 
Boolean; 
string [5] ; 
Packet  Rec; 


begin 

Err_Flag  :=  False; 

Repeat 

comp_checksum  :=  0; 
with  packet  do 
begin 

Case  packet_type  of 


Str(  Comp_Checksum,  Checksum_Str 
While  (Length (Checksum_str)  <  5) 
Checksum_Str  :=  '0'  +  checksum_ 
For  Count  :=  1  to  5  do 
check_send(checksum_str [count] ) 
Receive_Packet (  Temp_Packet  ); 

If  Temp_Packet . Packet_Type  <>  Pkt 
Err_Flag  :=  True; 

end; 

Until  not  Err_Flag; 
end; 


)  ; 
do 
str; 


_PDP_OK  then 

(  End  With  Packet  } 


(***** 

Begin 

End. 


Unit  Initialization  Main  Code  Block 


End  Listings 
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Listing  One  (Text  begins  on  page  29) 

for  (i=0;i<TABLE  SIZE;i++)  /*  Clear  out  the  string  table  before  starting*/ 
code  value [ i ] =— 1 ; 

/*******************♦***************************** *************************** 

1-0; 

**  LZW  data  compression/expansion  demonstration  program. 

printf ("Compressing. . .\n") ; 

**  Mark  R.  Nelson 

string  code=getc (input] ;  /*  Get  the  first  code*/ 

********************************************************************** *******/ 

/* 

♦include  <stdio.h> 

**  This  is  the  main  loop  where  it  all  happens.  This  loop  runs  util  all  of 
**  the  input  has  been  exhausted.  Note  that  it  stops  adding  codes  to  the 

♦define  BITS  12  /*  Setting  the  number  of  bits  to  12,  13*/ 

**  table  after  all  of  the  possible  codes  have  been  defined. 

♦define  HASHING  SHIFT  BITS-8  /*  or  14  affects  several  constants.  */ 

*/ 

♦define  MAX  VALUE  (1  «  BITS)  -  1  /*  Note  that  MS-DOS  machines  need  to  */ 

while  ( (character=getc (input) )  !=  (unsigned) EOF) 

{ 

♦define  MAX  CODE  MAX  VALUE  -  1  /*  compile  their  code  in  large  model  if*/ 

/*  14  bits  are  selected.  */ 

if  (++i==1000)  /*  Print  a  *  every  1000  */ 

♦if  BITS  ==  14 

(  /*  input  characters.  This  */ 

♦define  TABLE  SIZE  18041  /*  The  string  table  size  needs  to  be  a  */ 

i=0;  /*  is  just  a  pacifier.  */ 

♦endif  /*  prime  number  that  is  somwhat  larger  */ 

printf  ("*"); 

♦if  BITS  ==  13  /*  than  2**BITS.  */ 

) 

♦define  TABLE  SIZE  9029 

index=find  match(string  code, character) ;  /*  See  if  the  string  is  in  */ 

♦endif 

if  (code  value[index]  !=  -1)  /*  the  table.  If  it  is,  */ 

♦if  BITS  <=  12 

string  code=code  value [index] ;  /*  get  the  cede  value.  If  */ 

♦define  TABLE  SIZE  5021 

else  /*  the  string  is  not  in  the*/ 

♦endif 

(  /*  table,  try  to  add  it.  */ 

if  (next  code  <=  MAX  CODE) 

void  *malloc(); 

{ 

code  value [index] =next  code++; 

int  *code  value;  /*  This  is  the  code  value  array  */ 

prefix  code (index) -string  code; 

unsigned  int  *prefix  code;  /*  This  array  holds  the  prefix  codes  */ 

append  character [ index ] -character ; 

unsigned  char  *append  character;  /*  This  array  holds  the  appended  chars*/ 

1 

unsigned  char  decode_stack[4000] ;  /*  This  array  holds  the  decoded  string*/ 

output_code (output, st ring_code) ;  /*  When  a  string  is  found  */ 

string  code-character;  /*  that  is  not  in  the  table*/ 

/*****************************************************************»********** 

)  /*  I  output  the  last  string*/ 

**  This  program  gets  a  file  name  from  the  command  line.  It  compresses  the 

)  /*  after  adding  the  new  one*/ 

**  file,  placing  its  output  in  a  file  named  test.lzw.  It  then  expands 

/* 

**  test.lzw  into  test. out.  Test. out  should  then  be  an  exact  duplicate  of 

**  End  of  the  main  loop. 

**  the  input  file. 

*/ 

****************************************************************************/ 

output_code (output, string_code) ;  /*  Output  the  last  code  */ 

output  code (output, MAX  VALUE);  /*  Output  the  end  of  buffer  code  */ 

main  (int  argc,  char  *argv(]) 

{ 

output  code (output, 0) ;  /*  This  code  flushes  the  output  buffer*/ 

printf  ("\n") ; 

FILE  ’input  file; 

) 

/* 

FILE  ’output  file; 

FILE  *lzw  file; 

**  This  is  the  hashing  routine.  It  tries  to  find  a  match  for  the  prefix+char 

char  input  file  name (81]; 

**  string  in  the  string  table.  If  it  finds  it,  the  index  is  returned.  If 

/* 

**  the  string  is  not  found,  the  first  available  index  in  the  string  table  is 

**  The  three  buffers  are  needed  for  the  compression  phase. 

**  returned  instead. 

code  value=malloc (TABLE  SIZE*sizeof (unsigned  int)); 

find  match (int  hash  pref ix, unsigned  int  hash  character) 

prefix  code=malloc (TABLE  SIZE’sizeof (unsigned  int)); 

I 

append  character-malloc (TABLE  SIZE*sizeof (unsigned  char)); 

int  index; 

if  (code_value— NULL  1 !  pref ix_code==NULL  : :  append_character-=NULL) 

int  offset; 

printf ("Fatal  error  allocating  table  space! \n"); 

index  =  (hash  character  «  HASHING  SHIFT)  A  hash  prefix; 

exit  () ; 

) 

if  (index  ==  0) 

offset  =  1; 

/* 

else 

**  Get  the  file  name,  open  it  up,  and  open  up  the  lzw  output  file. 

*/ 

offset  =  TABLE  SIZE  -  index; 

while  (1) 

if  (argc>l) 

( 

strcpy(input  file  name, argv [ 1 ] ) ; 

if  (code  value [index]  —  -1) 

return (index) ; 

( 

if  (prefix  code[index]  ==  hash  prefix  &&  append  character [index]  —  hash  character) 

printf ("Input  file  name?  "); 

return (index) ; 

scanf ("%s", input  file  name); 

index  —  offset; 

) 

if  (index  <  0) 

input  file=fopen (input  file  name,"rb"); 

index  +=  TABLE  SIZE; 

lzw  f ile=fopen ("test.lzw", "wb") ; 

} 

if  (input_file==NULL  1 !  lzw_f ile==NULL) 

} 

printf ("Fatal  error  opening  files. \n"); 

**  This  is  the  expansion  routine.  It  takes  an  LZW  format  file,  and  expands 

exit  () ; 

**  it  to  an  output  file.  The  code  here  should  be  a  fairly  close  match  to 

}; 

**  the  algorithm  in  the  accompanying  article. 

**  Compress  the  file. 

*/ 

compress (input  file, lzw  file); 

expand (FILE  ‘input, FILE  ‘output) 

unsigned  int  next  code; 

fclose (input  file); 

unsigned  int  new  code; 

fclose (lzw  file) ; 

unsigned  int  old  code; 

free (code  value); 

int  character; 

/* 

int  counter; 

**  Now  open  the  files  for  the  expansion. 

unsigned  char  ‘string; 

*/ 

char  ‘decode  string (unsigned  char  ’buffer, unsigned  int  code); 

lzw  file=fopen("test.lzw", "rb") ; 

next  code-256, ■  /*  This  is  the  next  available  code  to  define  */ 

output  file=fopen ("test. out", "wb") ; 

counter-0;  /*  Counter  is  used  as  a  pacifier.  */ 

if  (lzw_file==NULL  !!  output_f ile==NULL) 

printf ("Expanding. . .\n") ; 

l 

printf ("Fatal  error  opening  files. \n"); 

old  code-input  code (input);  /*  Read  in  the  first  code,  initialize  the  */ 

exit  () ; 

character-old  code;  /*  character  variable,  and  send  the  first  */ 

)? 

putc (old  code, output) ;  /*  code  to  the  output  file  */ 

**  Expand  the  file. 

**  This  is  the  main  expansion  loop.  It  reads  in  characters  from  the  LZW  file 

*/ 

**  until  it  sees  the  special  code  used  to  inidicate  the  end  of  the  data. 

expand (lzw  file, output  file); 

*/ 

fclose (lzw  file) ; 

while  ((new  code-input  code(input))  !=  (MAX  VALUE)) 

fclose (output  file); 

( 

free (prefix  code); 

if  (++counter— 1000)  /*  This  section  of  code  prints  out  */ 

free (append  character); 

{  /*  an  asterisk  every  1000  characters*/ 

) 

counter-0;  /*  It  is  just  a  pacifier.  */ 

printf ("*") ; 

**  This  is  the  compression  routine.  The  code  should  be  a  fairly  close 

/* 

**  match  to  the  algorithm  accompanying  the  article. 

**  This  code  checks  for  the  special  STRING+CHARACTER+STRING+CHARACTER+STRING 

**  case  which  generates  an  undefined  code.  It  handles  it  by  decoding 

*/ 

**  the  last  code,  adding  a  single  character  to  the  end  of  the  decode  string. 

compress (FILE  ‘input, FILE  ‘output) 

*/ 

f 

if  (new  code>=next  code) 

unsigned  int  next  code; 

( 

unsigned  int  character; 

‘decode  stack-character; 

unsigned  int  string  code; 

string-decode  string (decode  stack+l,old  code); 

unsigned  int  index; 

) 

int  i; 

/* 

next  code=256;  /*  Next  code  is  the  next  available  string  code*/ 

**  Otherwise  we  do  a  straight  decode  of  the  new  code. 
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*/ 

else 

string=decode_string (decode_stack, new_code) ; 

/* 

“  Now  we  output  the  decoded  string  in  reverse  order. 

*/ 

character=*string; 
while  (string  >=  decode_stack) 
putc (‘string — , output) ; 

/* 

**  Finally,  if  possible,  add  a  new  code  to  the  string  table. 

*/ 

if  (next_code  <=  MAXCODE) 

( 

pref ix_code [next_code] =old_code; 
append_character (next_code) =character ; 
next_code++; 

) 

old_code=new_code ; 

} 

print f  ("\n") ; 

) 

/* 

“  This  routine  simply  decodes  a  string  from  the  string  table,  storing 
“  it  in  a  buffer.  The  buffer  can  then  be  output  in  reverse  order  by 
“  the  expansion  program. 

*/ 

char  *decode_string (unsigned  char  ‘buffer, unsigned  int  code) 

I 

int  i; 
i=0; 

while  (code  >  255) 

{ 

*buffer++  =  append_character (code) ; 
code=prefix_code[code] ; 
if  (i++>=4000) 

{ 

printf ("Fatal  error  during  code  expansion. \n" ) ; 
exit(); 

) 

I 

*buffer=code; 
return (buffer) ; 

1 

/* 

“  The  following  two  routines  are  used  to  output  variable  length 
“  codes.  They  are  written  strictly  for  clarity,  and  are  not 
“  particularly  efficient. 

*/ 

input_code (FILE  ‘input) 

{ 

unsigned  int  return_vaiue; 
static  int  input_bit_count=0; 
static  unsigned  long  input_bit_buffer=OL; 
while  (input_bit_count  <=  24) 

{ 

input_bit_buffer  !=  (unsigned  long)  getc(input)  «  (24-input_bit_count) ; 
input  bit_count  +=  8; 

) 

return_value=input_bit_buffer  »  (32-BITS); 
input_bit_buf fer  «=  BITS; 
input_bit_count  -=  BITS; 
return (ret urn_value) ; 

) 

output_code (FILE  ‘output, unsigned  int  code) 

( 

static  int  output_bit_count=0; 

static  unsigned  long  output_bit_buf fer=0L; 

output_bit_buf fer  !=  (unsigned  long)  code  «  (32-BITS-output_bit_count) ; 
output_bit_count  +=  BITS; 
while  (output_bit_count  >=  8) 

{ 

putc (output_bit_buffer  »  24, output); 
output_bit_buf fer  «=  8; 
output_bit_count  -=  8; 


End  Listing 


Listing  One  (Text  begins  on  page  38.) 

program  xnet; 

< 

Program  to  demonstrate  file  transfer  between  PCs 
using  the  NETBIOS  device  driver.  This  program  should  work  with 
any  hardware  and  software  that  support  the  NETBIOS  interface. 
Network  software  other  than  the  NETBIOS  is  not  required. 

Program  was  tested  with  the  PC260  Arcnet  boards  from  SMC.  The 
CONFIG.SYS  had  the  following  line  to  install  the  NETBIOS: 

device=smcarc.sys  /p2e0  /i2  /meOOO 
Program  author:  Costas  Menico 


uses  dos,  crt; 


const 

{  Maximum  #  of  bytes  to  transfer  in  a  single  send  } 

buffsize  =  64*1024-1; 

lancard=0;  (  Default  network  card  } 

nowait  =  $80;  (  Return  immediately  from  command. 

Call  the  POST  routine  when  done.  (NOT  USED) ) 
wait=$0;  (  Wait  until  command  is  done.  ) 


{  NETBIOS  Commands 
msg_reset=$32; 
msg_status=$33; 
msg_add_name=$  3  0 
msg_listen=$ll; 
msg_call=$10; 
msg_hang_up=$ 1 2 ; 
msg_send=$14; 
msg_receive=$ 1 5 ; 


used  in  this  program  ) 

(  Reset  the  node  ) 

{  Determine  the  current  state  of 
(  Add  a  16  char  unique  node  name 
(  Listen  for  a  node  to  establish 
(  Call  another  node  to  establish 
(  Hangup  the  session  with  a  node 
(  Send  a  block  of  data  to  a  node 
(  Receive  a  block  of  data  from  a 


the  node  ) 
to  NETBIOS  ) 
session  ) 
a  session  ) 

) 

) 

node  ) 


type 

buffer=array[l. .buffsize]  of  byte; 
buffp=Abuffer; 

arrname=array[l. .16]  of  char; 


(  Buffer  type  declaration  ) 

(  Pointer  type  to  the  buffer  ( 
(  Array  for  names  type  } 


(  Message  control  block  reco 
mcb=record 

mcb_command:  byte;  { 

mcb_retcode:  byte;  { 

mcb_lsn:  byte;  ( 

mcb_num:  byte;  { 

mcb_buffer:  pointer;  { 

mcb_length:  word;  ( 

mcb_callname:  arrname;  { 

mcb_name:  arrname;  { 

mcb_rto:  byte;  { 

mcb_sto:  byte;  { 

mcbjpost:  pointer;  { 

mcb_lana_num:  byte;  { 

mcb_cmd_cpl:  byte;  ( 

mcb_reserve:  array [1. 
end; 


Command  to  execute  } 

Return  code  value  ) 

Local  session  #  ) 

Number  of  name  added  ) 

Data  buffer  address  ) 

Buffer  length  in  bytes  } 

Name  on  remote  node  ) 

Name  of  local  node  ) 

Receive  timeout  (NOT  USED)  } 

Send  timeout  (NOT  USED)  ) 

Post  routine  address  (NOT  USED)  ) 
Adapter  card  to  use.  0  is  first  ) 
Command  status  if  NOWAIT  is  used  ) 
of  byte;  (  Other  detailed  info  ) 


(  Memory  declarations  ) 
var 

b:  buffp;  I  Data  buffer  block  ) 

m:  mcb;  {  Message  control  block  ) 

r:  registers;  {  Registers  used  in  INT  $5C  ) 

localname,  callname:  arrname;  (  Local  and  remote  name  variables  ) 

netaddr:  pointer; 

fi:  file; 

filename:  string [64]; 

mode:  char; 
nodenum:  word; 

remote node, 
localnode:  string[3]; 

lsn:  byte; 

fsize,  bytecount:  longint; 
count :  word; 

noerr:  boolean; 
ans:  char; 

1 - 

procedure  init_mcb(var  m:mcb) ; 

{  Initialize  a  message  control  block  to  blanks  and  nulls  ) 
begin 

m . mcb_command : =0  ; 

m.mcb_retcode:=$ff ;  {  Must  be  set  to  $FF  } 

m.mcb_lsn:=0; 

m.mcb_num:=0; 

m.mcb_buffer :=nil; 

m . mcb_length : =0  ; 

fillchar (m.mcb_callname, 16, '  ' ) ; 
fillchar  (m.mcb_name, 16, '  '); 
m.mcb_rto:=0; 
m.mcb_sto:=0; 
m.mcb_post :=nil; 
m . mcb_lana_num : =lancard; 
m . mcb_cmd_cpl : =0 ; 
fillchar (m.mcb_reserve, 14,0) ; 
end; 

I - 1 

procedure  net_reset (var  m:mcb) ; 

(  Reset  the  node  card  ) 
begin 

init_mcb (m) ; 

m . mcb_command : =msg_reset ; 

netaddr :=ptr (memw[0:$5c‘4] ,  memw[0:$5c*4+2] ) ; 
if  netaddronil  then 


(  NETBIOS  $5C  Interrupt  address  ) 

{  File  handle  for  reading  or  writing  ) 
(  Filename  path  string  ) 

(  Sending  or  receiving  } 

(  Our  card’s  node  number,  1-255  } 


(  Remotes  and  local  node  numbers  ) 

(  Tracks  our  session  number  ) 

(  File  size  and  bytes  sent/received  } 
(  Number  of  bytes  to  send/ receive  ) 

{  General  use  error  flag  ) 

(  Readkey  variable  ) 
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begin 

r.es:=seg(m) ; 
r.bx:=ofs  (in)  ; 
intr ($5c, r) ; 
end; 
end; 


{ - - ) 

procedure  terminate; 

(  Terminate  XNET  } 
begin 

close(fi);  (  Close  open  file  1 

if  ioresultoO  then  ;  {  Clear  the  error  flag  just  in  case  } 
net_reset (m) ;  {  Reset  the  adapter.  Deletes  all  activity  ) 

freemem (b, buff size) ;  {  Free  heap  memory  (Out  of  Habit)  } 
halt;  (  Go  have  coffee  and  think  about  enhancements) 

end; 

1 - - 1 


procedure  net_error (var  m:  mcb) ; 

(  Print  a  NETBIOS  error  and  prompt  user  ) 
var  ans:  char; 

function  hex (h:byte) :string; 

{  Convert  a  byte  to  hex  notation  } 
var  i:byte; 

hexc: string [2] ; 
const 

hs : string ( 16 ] ■' 0123456789ABCDEF'  ; 
begin 

i := (h  shr  4) ; 
hexc:=hs[i+l] ; 
i := (h  and  $0f ) ; 
hexc : =hexc+hs [ i+1 ] ; 
hex:=hexc; 
end; 
begin 

if  m.mcb_retcode=0  then  exit; 

writeln ('NETBIOS  error  code  $' , hex (m.mcb_retcode) , 

'  in  command  code  $' , hex (m.mcb_command) ) ; 
ans :=readkey; 
terminate; 
end; 

I - 1 

procedure  net_status (var  m:mcb;  waitbit :byte;  mcb_buffer :buffp; 

mcb_length : word;  mcb_callname : arrname; 
mcb_post :  pointer) ; 

(  Get  the  current  NETBIOS  status  } 
begin 

init_mcb (m) ; 

m.mcb_command:=waitbit+msg_status; 

m . mcb_bu  f  f e  r : =mcb_bu  f  f e  r  ; 

m.mcb_length:=mcb_length; 

m. mcb_post : =mcb_post  ; 

move  (mcb_callname,m.mcb_callname,  16)  ; 

netaddr:=ptr (memw[0:$5c*4] ,  memw[0:$5c*4+2] ) ; 

if  netaddronil  then 

begin 

r.es:=seg(m) ; 
r .bx:=ofs (m) ; 
intr ($5c, r) ; 
end; 
end; 

, - , 

procedure  net_receive (var  m:mcb;  waitbit :byte;  mcb_buf fer : buff p; 

mcblengthtword;  mcb_lsn :byte; 
mcb_post:  pointer); 

(  Wait  to  receive  a  data  block  from  the  node  we  are  in  session  with  ) 
begin 

initjncb  (m)  ; 

m.mcb_command:=waitbit+msg_receive; 
m.mcb_buf fer :=mcb_buf fer; 
m . mcb_length : =mcb_length; 
m . mcb_l s  n : =mcb_l sn ; 
m . mcb_post : =mcb_post ; 
r.es:=seg(m) ; 
r .bx:=ofs (m) ; 
intr ($5c, r) ; 
end; 

1 - 1 

procedure  net_hang_up(var  m:mcb;  waitbit :byte;  mcb_lsn:byte; 
mcb_post:  pointer); 

{  Hang  up  on  the  other  guy.  Not  polite  but  who's  perfect.  ) 
begin 

init_mcb (m) ; 

m.mcb_command:=waitbit+msg_hang_up; 
m . mcb_l s  n : =mcb_l s  n ; 
m . mcb_post : =mcb_post  ; 
r .es :=seg (m) ; 
r .bx:=ofs (m) ; 
intr ($5c, r) ; 
end; 

, - ) 

procedure  net_send(var  m:mcb;  waitbit :byte;  mcb_buf fer :buffp; 

mcb_length:word;  mcb_lsn:byte;  mcb_post:  pointer); 

(  Send  a  block  of  data  to  the  node  we  are  in  session  with.  ) 
begin 

init_mcb(m) ; 

m . mcb_command : =waitbi t+msg_send; 
m . mcb_bu  ffer:=mcb_buffer; 
m.mcb_length:=mcb_length; 
m . mcb_l sn : =mcb_l sn ; 
m . mcb_post : =mcb_post  ; 
r.es:=seg(m) ; 
r.bx:=ofs (m) ; 
intr ($5c, r) ; 
end; 

I - ) 

procedure  net_add_name (var  m:mcb;  waitbit :byte;  mcbname : arrname; 
mcbpost:  pointer); 

(  Tell  NETBIOS  our  name.  Must  be  unique  anywhere  in  the  network  } 
begin 


init_mcb (m) ; 

m.mcb_command:=waitbiti-msg_add_name; 
move (mcb_name , m . mcb_name  ,16); 
m . mcb_post : =mcb_post ; 
r .es:=seg (m) ; 
r .bx:=ofs (m) ; 
intr ($5c, r) ; 
end; 


procedure  net_call(var  m:mcb;  waitbit :byte;  mcbcallname, 
mcb_name: arrname;  mcb_post:  pointer); 

{  Call  callname,  and  let  him  know  we  are  ready  ) 
begin 

init_mcb (m) ; 

m. mcb_command : =waitbit+msg_call ; 
move (mcb_name,m.mcb_name,  16); 
move (mcb_callname, m.mcb_callname, 16) ; 
m . mcb_post : =mcb_post; 
r.es:=seg(m) ; 
r.bx:=ofs (m) ; 
intr ($5c, r) ; 
end; 

, - } 

procedure  net_listen (var  m:mcb;  waitbit : byte;  mcb_callname, 
mcb_name: arrname;  mcb_post:  pointer); 

{  Listen  if  callname  is  calling  us  } 
begin 

initjncb  (m)  ; 

m.mcb_command:=waitbit+msg_listen; 
move (mcb_name , m . mcb_name  ,16); 
move (mcb_callname,m.mcb_callname, 16) ; 
m . mcb_post : =mcb_post ; 
r.es:=seg(m) ; 
r .bx:=of s (m) ; 
intr ($5c, r) ; 
end; 

( - 1 

procedure  copytoarr(s:  string;  var  name:  arrname); 

(  Copy  a  string  to  a  16  byte  array.  Blank  fill  to  end.  ) 
begin 

f illchar (name, 16, ’  '); 
move(s[l],  name,  length (s) ) ; 
end; 

, - - - ) 

procedure  send_the_f ile; 

{ 

Start  sending  file.  First  send  the  file  size  (2  words) . 

Then  send  the  rest  in  block  of  64K  with  the  remainder 
as  the  last  block. 

} 

begin 

(  Get  file  size  and  display  ) 
fsize:=f ilesize (fi) ; 

gotoxy (1, 23) ;  write ('File  size  ',fsize); 

{  Send  the  length  of  the  file.  Must  be  in  2  words  } 

move(fsize,  b",  4); 

net_send(m,  wait,  b,  4,  lsn,  nil); 

neterror (m) ; 

bytecount :=0; 
noerr :=true; 

(  Loop  until  the  file  is  sent.  } 
while  (bytecount<f size)  and  (noerr)  do 
begin 

(  Read  a  block  and  if  no  error  then  send  ) 
blockread (f i,  bA,  buffsize,  count); 
if  ioresultoO  then 
noerr :=false 
else 
begin 

net_send(m,  wait,  b,  count,  lsn,  nil); 
net_error (m) ; 

bytecount : =bytecount+count ; 

gotoxy (1,24) ;  write('File  size  sent  '.bytecount,'  '); 

end; 
end; 
end; 

( - ) 

procedure  receive_the_file; 

{ 

Start  receiving  file  and  save  to  disk.  First  get  the  file  size. 

Then  receive  in  blocks  of  64K  with  the  remainder  as  the  last  block 

) 

begin 

(  Get  the  file  size.  Block  sent  must  be  in  2  words  ) 
net_receive (m,  wait,  b,  buffsize,  lsn,  nil); 
move(bA, fsize, 4) ; 

{  Display  it  ) 

gotoxy (1, 23) ;  write ('File  size  '.fsize); 
bytecount :=0;  (  File  size  sent  counter  ) 

noerr :=t rue; 

(  Loop,  receiving  block  in  64K  increments  ) 
while  (bytecount<f size)  and  (noerr)  do 
begin 

{  Receive  ) 

net_receive (m,  wait,  b,  buffsize,  lsn,  nil); 
net_error (m) ; 

(  Save  to  file  ) 

blockwrite ( f i,  b*,  m.mcb_length) ; 

{  If  an  error  abort  else  show  file  size  sent  so  far.  } 

if  ioresultoO  then 

begin 

noerr :=false; 

writeln (' Disk  full  error'); 
net_hang_up (m,  wait,  lsn,  nil); 
terminate; 
end  else 


90 


Dr.  Dobbs  Journal,  October  1989 

709 


begin 

by tecount : =bytecount+m . mcblengt h ; 

gotoxy (1, 24) ;  write ('File  size  received  ' , bytecount, '  '); 

end; 
end; 
end; 


procedure  setup_call_send; 

{  Ask  for  file  name  to  send  and  call  the  remote  station.  Hopefully 
the  remote  is  listening  J 
begin 

noerr :=true; 

{  Get  the  file  name  to  send  ) 

while  noerr  do 

begin 

write ('Pathname  of  file  to  send  (blank  to  exit)?  '); 
readln (filename) ; 
if  filename®' '  then  terminate; 
assign (f  i, filename) ; 
reset (fi, 1) ; 
if  ioresultoO  then 
writeln (' File  does  not  exist.') 
else 

noerr : =false; 

end; 

(  Get  the  local  node  and  the  remote  node  into  arrays) 
copytoarr (localnode, localname) ; 
copytoarr ( remotenode, callname) ; 

(  Call  'callname'  using  our  'localname'.  He  should  be 
expecting  our  call  ) 
noerr :=false; 
while  not  noerr  do 
begin 

net_call (m,  wait,  callname,  localname,  nil); 

(  Was  the  remote  node  available  to  listen?  ) 

if  m.mcb_retcode<>0  then 

begin 

writeln ('Remote  Node,  ', remotenode, '  not  ready.  Retry / Abort?' ) ; 
ans:=readkey; 

if  upcase (ans)=' A'  then  net_error (m) ; 
end  else 

noerr :=t rue; 

end; 

lsn:=m.mcb_lsn;  {  Save  the  session  number  NETBIOS  blessed  us  with) 

send_the_f ile; 
close  (fi) ; 
end; 

i - - - ) 

procedure  setup_listen_receive; 

{  Ask  for  file  name  to  receive  into  and  listen  for  the  remote 
node's  call  ) 
begin 

noerr  :=  true; 

(  Get  filename  to  save  in  to.  If  file  exists  verify  and  overwrite.  ) 

while  noerr  do 

begin 

write (' Pathname  of  where  to  save  received  file  (blank  to  exit)?  '); 

readln (filename) ; 

if  filename®''  then  terminate; 

assign (fi, filename) ; 

reset  (fi) ; 

if  ioresult=0  then 

begin 

writeln (' File  EXISTS.  Do  you  wish  to  overwrite  (Y/N)?  '); 
ans:=readkey; 

if  upcase (ans) =' Y'  then  noerr :=false; 


close (fi) ; 
end  else 

noerr :=false; 

end; 

rewrite (fi, 1) ; 

{  Get  the  local  and  remote  nodes  into  array  strings  } 
copytoarr (localnode, localname) ; 
copytoarr (remotenode, callname) ; 

{  Listen  for  the  remote  node  to  call  up  any  moment  ) 
net_listen (m,  wait,  callname,  localname,  nil); 

lsn:=m.mcb_lsn;  (  Save  the  session  number  NETBIOS  blessed  us  with) 
net_error (m) ; 


r e  ce i ve_t  he_f i 1 e ; 
close (fi) ; 
end; 

, - ) 

1  XNET  Main  program  start  } 

I - ) 

begin 


clrscr; 

{  Get  a  data  buffer  from  the  heap  } 
getmem(b,  buffsize); 

(  Initialize  fi  to  something  ) 
assign (fi, 'NUL' ) ; 

(  Are  we  supposed  to  reset?  ) 
net_reset (m) ; 
net_error (m) ; 

(  Check  our  status  ) 

copytoarr ('*' ,  localname);  {  Create  our  localname  ) 

{  Check  our  node's  NETBIOS  status  and 
in  to  the  first  get  the  node  number  (address)  ) 
net_status(m,  wait,  b,  buffsize,  localname,  nil); 
net_error (m) ; 

(  Get  our  node  number  and  add  it  as  a  node  name 
The  node  number  is  set  by  "net_status"  and  is 
in  the  first  byte  of  the  data  buffer  "bA") 
nodenum:=mem[seg (bA) :ofs (bA) ] ; 

writeln('Your  Station  Number  is:  ',nodenum);  writeln; 

str (nodenum, localnode) ;  1  Convert  to  string  array  ) 

copytoarr (localnode, localname) ; 

net_add_name (m,  wait,  localname,  nil);  (  Add  to  NETBIOS  ) 
net_error (m) ; 

(  At  this  point  the  NETBIOS  is  aware  of  our  presence  ) 

(  Ask  the  user  for  the  remote's  node  number. 

This  is  the  node  we  wish  to  communicate  with. 

It  may  not  have  the  same  number  as  our  node  ) 
remotenode :=localnode; 
while  (remotenode=localnode)  do 
begin 

write ('Enter  remotes  station  #:  '); 
readln ( remotenode) ; 
end; 

(  Ask  for  user's  intentions.  Send/Receive/Exit  ) 
writeln (' (S]end-f ile,  [R] eceive-f ile  or  (E)xit'); 
mode:=readkey; 

case  upcase (mode)  of 

'S':  setup_call_send;  {  Send  the  file.  } 

' R' :  setup_listen_receive;  (  Receive  the  file.  ) 
end; 

terminate; 

id. 

End  Listing 
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Listing  One  (Text  begins  on  page  45.) 

/*  CTERM.H  defines  for  CTERMx  series.  */ 


♦define  BUFSIZE 

128 

♦define  DISKREAD 

(BUFSIZE  *  40) 

/*  some  ASCII  defines  */ 

♦define  SOH 

0x01 

/* 

start  of  header  */ 

♦define  EOT 

0x04 

/* 

end  of  transmission  */ 

♦define  ACK 

0x06 

/* 

positive  acknowledgement 

*/ 

♦define  BS 

0x08 

/* 

backspace  */ 

♦define  CR 

0x0D 

/* 

Carriage  Return  */ 

♦define  NAK 

0x15 

/* 

Negative  acknowledgement 

*/ 

♦define  CAN 

0x18 

/* 

Cancel  */ 

♦define  EoF 

OxlA 

/* 

End  of  File  (used  for  name)  */ 

♦define  ESC 

OxlB 

/* 

ASCII  escape  key  */ 

♦define  CRC 

0x43 

/* 

ASCII  'C'  (CRC  mode  request)  */ 

♦define  BADNAME 

0x75 

/* 

Received  bad  name  checksum  */ 

♦define  TIMEOUT 

-1 

/* 

for  state  machine  logic  ’ 

7 

static  char  *SPEED 

|  LIST  [  ] 

= 

(  "50",  "75", 

"110", 

"135", 

"150",  "300",  "600", 

"1200", 

"1800",  "2000", 

"2400", 

"3600", 

"4800",  "7200",  "9600",  1 

'19200", 

"28800",  "38400 

",  "57600"  }; 

static  int  SPEED  VALS[]  = 

{  50,  75,  110,  135, 

150, 

300,  600,  1200, 

1800,  2000,  2400,  3600, 

4800,  7200,  9600,  19200, 

28800,  38400,  57600,  0 

);  /* 

zero  for  anchor  */ 

static  char  * PARITY  LIST ( 1 

{  "NONE",  "NONE", 

"ODD", 

"EVEN", 

);  /*  matches  L_CTRL  p 

enable 

static  char  ‘STOP 

LIST  [  ]  = 

{  "ONE",  "TWO"  } ; 

/*  matches  L_CTRL  p 

two_stc 

static  char  ‘BITS 

LIST  ( ]  = 

1  "FIVE",  "SIX", 

"SEVEN", 

"EIGHT" 

); 

/*  Define  some  common  values  for  the  lctrl  bit  fields  */ 
♦define  atelnone  0x03; 

♦define  sevleven  OxlA; 


typedef  int  (‘action)  {); 


/*  action  is  a  pointer  to  a  function  */ 


struct  event_entry  ( 

char  comment [20];  /* 

action  act;  /* 

int  pa ram;  /* 

enum  send  state  next  state 


for  commented  reading  and  tracing  capability 
pointer  to  action  function  */ 
parameter  to  pass  to  function  */ 

;  /*  from  an  enumerated  list  of  states  */ 


*/ 


/*  The  following  enumeration  is  used  in  all  modules  */ 
enum  modes  1  M_Cmd,  M_Term,  M_Config,  M_XSend,  M_XRecv  }; 

/*  This  struct  maps  the  data  packets  for  the  protocol  */ 
typedef  struct  pkt  ( 
unsigned  char  soh; 
unsigned  char  pkt; 
unsigned  char  pkt_cmp; 
unsigned  char  data [BUFSIZE] ; 
unsigned  char  crcl; 
unsigned  char  crc2; 

}  XPKT; 


typedef  struct 

{ 

unsigned  speed;  /*  value  from  atoi()  of  value  from  speed  array  */ 

U_BITS  ubits; 

}  S_INIT; 


End  listing  Two 


Listing  Three 

/*  XMRECV.C:  Xmodem  receive  state  machine  processing  */ 

♦include  <stdio.h> 

♦include  <ctype.h> 

♦include  <string.h> 

♦include  "cterm.h"  /*  common  defines  and  structs  for  cterm  */ 
♦include  "commn.h"  /*  brings  in  S_INIT  struct  */ 


enum  recv_state 

{  S_Init_Recv,  S_Incoming,  S_First_What,  S_DePktize,  S_Exit  }; 

♦define  TRACE  1  /*  to  turn  on  state  machine  tracing  */ 

/*  ♦define  SMTRACE  1  */ 

♦ifdef  SMTRACE 

static  char  *state_list [ )  = 

{ "Init_Recv",  "Incoming",  "First_What",  "De-Pktize",  "Exit"); 
♦endif 


♦define  RECV  EVENTS  4 


/*  #  of  events  per  RECV  state  */ 


/*  Variables  local  to  this  file  only  */ 

static  char  r_f name [NAMES I ZE+1 ] ;  /*  name  of  file  to  open  */ 

static  FILE  *r_fptr  =  NULL;  /*  file  pointer  or  number  to  use  */ 

static  int  sohor  =  SOH;  /*  location  to  store  first  char  of  pkt  hdr  */ 


static  int  pkt  =  1; 
static  S_INIT  prev_conf; 
static  int  virgin  =  1; 


/*  expected  packet  number  */ 

/*  save  prev  (parity)  conf  */ 

/*  0  =  beyond  initial  NAK  stage  */ 


/*  EXTERNAL  variables  */ 
extern  int  comport; 
extern  int  crc; 
extern  unsigned  crcaccum; 
extern  unsigned  char  checksum; 
extern  S_INIT  cur_config; 
extern  enum  modes  mode; 
extern  int  eschar; 
extern  int  keyfun(int); 
extern  unsigned  int  fgetsnn(FILE 


/*  which  comm  port  to  use  (from  CTERM)  */ 
/*  flag  for  CRC  (!0)  or  checksum  (0)  */ 
/*  from  xmutil  */ 

/*  ditto  */ 

/*  from  CTERM.  For  timeout  calc  */ 

/*  ditto  term  mode  or...  */ 

/*  ditto  escape  character  variable  */ 

/*  ditto  BIOS  keyboard  I/O  */ 

*,  char  *,  int); 


/*  Messages  posted  by  A_Recv_End  */ 

/*  If  declared  as  char  *user_msg,  can't  be  used  in  state  table. 

*  No  variables  allowed.  But  this  way  creates  constants!  */ 
extern  char  user_msg[); 
extern  char  cancel(); 
extern  char  badwrite[); 
extern  char  eof_msg[); 
extern  char  giveupt); 
extern  char  badcomm[); 


/************  Receive  Actions:  ********************/ 


/*  Defines  used  for  keyfun{).  -  Map  exactly  to  BIOS  intr  I6h  0  and  1  */ 
♦define  KEYHIT  1 

♦define  READNEXT  0 

♦define  BIOS_KEY  0x16  /*  for  int86  call  for  keyboard  interrupt  */ 

/*  The  following  defines  are  used  to  map  scan  codes  for  f  keys  and  specials  */ 
♦define  HOME  0x4700 
♦define  PGUP  0x4900 
♦define  END  Ox4FOO 
♦define  PGDN  0x5100 
♦define  INS  0x5200 
♦define  DEL  0x5300 
♦define  CBRK  0x0000 


Listing  Two 

♦define  PORT  2 
♦define  NAMESIZE  24 
♦define  TXTRIES  5 
♦define  RXTRIES  10 

/*  Parameters  to  pass  tc  Send  Action  Make  Pkt  and  Recv  Action  Frame  Wait  */ 


pass  config  info  to  Config_Comm() .  */ 
Control  bits  */ 

Word  length  -  5  */ 

1:  Two  stops,  0:  One  stop  */ 

00,  01:  NONE,  10  ODD,  11  EVEN  */ 

1:  Stuck,  0:  Normal  */ 

1:  Send  break  0:  Stop  break  */ 

1:  See  divisors  0:  See  data  bytes  */ 

unsigned  :  8; 

)  L_CTRL; 

typedef  union  ( 

unsigned  char  lctrl; 

L_CTRL  lbits; 

}  U_BITS; 


♦define  RESEND  0 
♦define  INIT  1 
♦define  NEXT  2 

/*  The  following  declaration  is  used  to 
typedef  struct  {  /*  Map  to  UART  Line 


unsigned  wlen  :  2;  /* 
unsigned  two_stops  :  1;  /* 
unsigned  parity  :  2;  /* 
unsigned  p_stuck  :  1;  /* 
unsigned  set_break  :  1;  /* 
unsigned  div_latch  :  1;  /* 


/*  Book  says  0x5400.  I  see  0x0000  */ 

End  Listing  One 


/*  currently  a  define  12/16/88  */ 
/*  Used  by  xmsend  and  recv  */ 

/*  Transmit  retries  */ 

/*  Receive  retries  */ 


/*  -  A_Prep_Recv:  Prompts  for  file  to  receive,  attempts  open. 

*  Returns:  0  if  O.K.,  1  if  open  fails,  2  is  user  abort.  */ 
A_Prep_Recv(  char  *fname  ) 

( 

int  retval; 

fputs("\n  Please  Input  file  name  to  receive:  ”,stdout); 
fgetsnn  (stdin,  fname,  NAMESIZE  ); 
if  (  (fname(O)  ==  eschar)  ! !  (fname [0)  ==  '\0')  ) 
return (2) ; 

if  (  (r_fptr  =  fopen  (fname,  "wb"))  ==  NULL  )  ( 
print f("\n  Cannot  open  %s.  Try  again. \n",  fname); 
return (1) ; 

} 


prev_conf  =  cur_config; 
cur_config. ubits. lctrl  =  atelnone; 
Config_Comm(  comport,  cur_config  ) ; 


/*  save  entry  config  */ 

/*  Force  things  to  8/1/N  */ 


eat_noise{)  ; 
return (0) ; 


/*  clear  out  any  garbage  from  buffer  */ 


/*  -  A_Frame_Wait :  Send  a  Ctrl  char,  wait  for  reply.  - 

*  Returns:  0:  OK,  1:  comm  error,  2:  timeout,  3:  no  retries.  */ 
A_Frame_Wait (int  which) 


char  inch; 
int  errval; 
int  numread  =  1; 
static  int  passes; 
static  char  last; 
int  retval  =  0; 

if  (virgin)  ( 
switch  (which)  { 
case  INIT:  crc  ■ 


/*  returned  from  reads  and  writes  */ 

/*  give  up  after  10  retries  */ 

/*  Running  value  to  return  */ 

/*  Waiting  for  first  answer  to  NAK  */ 

/*  Go  for  CRC  first  —  fallthru  will  flip 


passes  =  RXTRIES; 

pkt  =  1;  /*  Initialize  to  first  expected  pkt  num  */ 

case  RESEND:  crc  =  !crc;  /*  flip  global  flag  */ 

last  =  (crc  ==  0)  ?  NAK  :  CRC; 
break; 

default:  retval  =  3;  /*  Should  not  occur...  but  */ 


) 
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else  {  /*  Not  virgin.  Normal  Retry  logic  */ 

{ 

register  int  i; 

switch  (which)  ( 

case  NEXT:  last  =  ACK; 

passes  =  RXTRIES; 

crcaccum  =0;  /*  zero  out  global  crc  and  checksum  value  */ 

break; 

checksum  =  0; 

case  RESEND:  if  (passes —  ==  0)  { 

last  =  CAN; 

for  (i  =  0;  i  <  BUFSIZE;  i++,  buf++) 

retval  =  3; 

updcrc (*buf) ; 

passes  =  RXTRIES;  /*  Reset  to  default  */ 

I 

updcrc(0);  /*  Xmodem  deviant  CRC  calc  */ 

updcrc (0) ; 

else 

last  =  NAK; 

if  (crcflag  ==  0)  { 

break; 

if  (crchi  !=  checksum) 

default:  retval  =  3;  /*  An  ounce  of  prevention  */ 

return  (2) ; 

) 

else  ( 

if  (  (crclo  +  (  crchi  «  8))  !=  crcaccum  ) 

errval  =  writecomm(  &last,  1); 
if  (errval  !=  0) 

return (2) ; 

) 

return (0) ; 

return (1);  /*  Get  out  now!  */ 

eat  noise();  /*  clear  out  any  garbage  */ 

/*  -  Action  Validate:  After  SOH,  validates  the  xmodem  header. 

if  (retval  !=  3)  { 

*  Returns:  0:  OK,  1:  bad  header,  2:  bad  CRC,  3:  char  timeout.  */ 

errval  =  read  comm(  finumread,  &inch,  10000  ); 
if  (errval  =»=  TIMEOUT) 

A  Validate (int  *crcflag  ) 

1 

return  (2); 

int  retval; 

else  (  /*  Got  a  live  one!  */ 

int  readnum  =  (‘crcflag  “  0)  ?  131  :  132;  /*  pass  to  read  comm  */ 

sohor  =  inch;  /*  set  global  */ 

int  togo  =  readnum;  /*  if  partial,  running  count  *7 

if  (  (virgin)  &&  (inch  ==  SOH)  )  (  /*  We're  rolling!  */ 

int  msecs;  /*  how  long  to  wait  */ 

printf ("\n\nReceiving  file  %s  using  %s.\n", 

XPKT  r  pkt;  /*  packet  receive  buffer  */ 

r  fname, (crc  ==  0)  ?  "Checksum”  :  "CRC"  ) ; 

unsigned  char  ‘diskbuf  =  (unsigned  char  *)  &r  pkt. data; 

fputs ("\nAwaiting  packet  #  0001", stdout) ; 

unsigned  char  ‘curptr  =  (char  *)  &r  pkt. pkt;  /*  Rem:  got  SOH  already  */ 

virgin  -  0;  /*  flip  the  local  flag  */ 

long  frame_bits  =  (  (BUFSIZE  +3)  *  10  ‘1000L  ); 

) 

printf ("\b\b\b\b%4d", pkt) ;  /*  Allow  up  to  9999  frames  */ 

return (retval) ; 

while  (readnum  !=  0)  ( 

) 

msecs  =  (int)  (  frame_bits  /  (long) cur_con fig. speed  ); 

delay (msecs) ;  /*  Let  the  interrupt  handler  work  */ 

/*  -  A  Which  Ctrl:  Parses  first  char  received.  - 

retval  =  read  comm(  Sreadnum,  curptr,  msecs  ) ; 

*  Returns:  0:  SOH,  1:  CAN,  2:  EOT,  3:  unexpected  (junk)  */ 

curptr  =  curptr  +  readnum;  /*  adjust  curptr  to  next  avail  loc  */ 

A_Which_Ctrl (char  ‘lead) 

readnum  =  (togo  -=  readnum) ;  /*  adjust  BOTH  to  remainder  of  pkt  */ 

switch  (‘lead)  { 

if  (retval  ==  TIMEOUT)  (  /*  Give  it  one  more  second  if  short  */ 

case  SOH:  return (,0); 

togo  =1;  /*  prep  togo  for  1  char  read  test  */ 

case  CAN:  return (1); 

retval  =  read  comm(  Stogo,  curptr,  1000); 

case  EOT:  return  (2); 

if  (retval  ==  TIMEOUT)  /*  Bad  news.  Dead  line  */ 

default:  return (3); 

return (3) ; 

) 

1 

curptr++;  /*  recovered!  adjust  and  try  again  */ 

togo  =  — readnum; 

/*  -  CRC_Good:  Calculates  the  CRC/Checksum.  - 

*  Returns:  0  if  OK,  2  if  error  */ 

CRC_Good(char  *buf,  int  crcflag,  unsigned  char  crchi,  unsigned  char  crclo) 

(continued  on  page  94) 
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listing  Three  (Listing  continued,  text  begins  on  page  45.) 

♦ifdef  SMTRACE 

1 

frame  bits  =  togo  *  10;  /*  Adjust  by  bits  per  character  */ 

printf ("State:  %16s,  Event:  %2d,  Note:  %20s\n", 

state  list [ (int) cur  state],  event,  cur  entry->comment  ); 

♦endif 

} 

/*  Based  on  the  current  state  and  event,  execute  action (param)  */ 

if  (~r_pkt.pkt  !=  r_pkt.pkt  cmp)  { 

new  action  =  cur_entry->act; 

event  =  new  action (cur  entry->param) ; 

return (1) ; 

cur  state  =  recv  machine [ (int) cur_state] [prevent] .next_state; 

if  (  r  pkt.pkt  !=  (pkt  %  256)  ) 

if  (  keyfun (KEYHIT)  )  { 

if  (  r_pkt .pkt  ==  (  (pkt  -  1)  &  OxFF  )  )  { 

inkey  =  (char)  keyfun (READNEXT) ;  /*  Truncate  to  key  only  */ 

return (0);  /*  duplicate  packet!  Ack  and  ignore  */ 

if  (inkey  ==  eschar) 

1 

A  Recv  End (user  msg); 

else 

return (1);  /*  Nak  and  retry.,  probably  useless  but...  */ 

retval  =  CRC  Good (diskbuf ,  ‘crcflag,  r  pkt.crcl,  r  pkt.crc2); 

return  (0);  End  Listing  Three 

} 

if  (retval  !=  0)  { 
return  (2) ; 

) 

Listing  Four 

fwrite (diskbuf,  BUFSIZE,  1,  r_fptr) ; 
pkt++; 

/*  XMSEND.C  Xmodem  Send  state  machine  processing.  */ 

return  (0); 

} 

♦include  <conio.h>  /*  for  putch  call  */ 

/* - Action  EatRest:  Eats  the  rest  of  a  packet.  - */ 

♦include  <ctype.h> 

♦include  <io.h>  /*  for  filelength  call  */ 

A  EatRest (int  calories) 

♦include  <stdio.h> 

1 

♦include  <string.h> 

int  toeat  =  calories; 

♦include  "cterm.h" 

int  retval  -  0; 

♦include  "commn.h"  /*  brings  in  S  INIT  struct  and  defines  */ 

long  frame  bits; 

char  junkbuf (BUFSIZE  +4]; 

enum  send  state 

if  (calories  >  BUFSIZE) 
calories  =  BUFSIZE  +  4; 

(  S  Init  Send,  S  Sync  Wait,  S  Make  Pkt,  S  Send  Pkt,  S  Data  Response,  S  Exit  }; 

♦ifdef  TRACE 

frame  bits  =  (  calories  *  10  *  1000L) ; 

char  ‘state  list [ ]  = 

delay(  (unsigned) (frame  bits/ (long) cur  config. speed)  +  500  ); 

("Init  Send",  "Sync  Wait",  "Make  Pkt",  "Send  Pkt",  "Data  Response",  "Exit"); 

while  (retval  !=  TIMEOUT)  ( 

retval  -  read  comm(  itoeat,  junkbuf,  1000); 

♦endif 

♦define  SEND  EVENTS  4  /*  number  of  events  handled  per  send  state  */ 

toeat  =  1; 

) 

/*  Variables  local  to  this  file  only  */ 

retval  =  A  Frame  Wait (RESEND) ; 

static  char  s  fname [NAMESIZE+1] ;  /*  name  of  file  to  open  */ 

return (retval) ; 

static  FILE  *s  fptr  =  NULL;  /*  file  pointer  or  number  to  use  */ 

} 

static  XPKT  s  pkt;  /*  packet  to  send  */ 

/*  -  Action  Recv  End:  Only  way  out  of  Recv  state  machine.  */ 

static  S  INIT  prev  conf;  /*  saves  previous  bits,  parity  during  xfer  */ 

A  Recv  End  (  char  *  reason  ) 

/*  EXTERNAL  variables  and  functions  */ 

( 

extern  int  comport;  /*  which  comm  port  to  use  (from  CTERM)  */ 

char  eotc  =  ACK;  /*  just  in  case  we  really  Receive  the  file  */ 

extern  unsigned  crcaccum;  /*  from  xmutil  */ 

if  (r  fptr  ! =  NULL)  {  /*  Did  we  even  get  started???  */ 

extern  unsigned  char  checksum;  /*  ditto  */ 

extern  int  crc;  /*  ditto  */ 

if  (reason  !=  eof  msg)  {  /*  Started,  but  bad  news  during  xfer  */ 

extern  S  INIT  cur  config;  /»  from  CTERMx .  For  send  time  calc  */ 

eotc  =  CAN; 

extern  int  eschar;  /*  ditto  escape  character  variable  */ 

unlink  (r  fname) ;  /*  deletes  the  old  file  */ 

extern  enum  modes  mode;  /*  ditto  term  mode  or...  */ 

} 

extern  int  keyfun (int);  /*  ditto  BIOS  call  to  keyboard  */ 

fclose (r_fptr) ; 
writecomm(&eotc,  1); 

/*  If  declared  as  char  ‘user  msg,  can't  be  used  in  state  table. 

Config  Comm(  comport,  prev  conf  );  /*  Put  whatever  parity  back  in  */ 

*  No  variables  allowed.  But  this  way  creates  constants!  */ 

) 

extern  char  user  msg[]; 

printf("\n  “*  Ending  session.  %s.\a\n", reason) ; 

extern  char  nonak [ ] ; 
extern  char  cancel!]; 

virgin  =  1; 

extern  char  badread[); 
extern  char  eof  msg[j; 

mode  =  M  Cmd; 

extern  char  giveupd; 

return  (RECV  EVENTS  -  1);  /*  last  event  always  has  next  state  S  Exit  */ 

} 

/************  send  Actions:  ********************/ 

/************  RECEIVE  STATE  TABLE  ****************/ 

/*  -  A  Get  Fname:  Prompts  for  file  to  transmit,  opens.  - 

struct  event  entry  recv  machine [ (int) S  Exit] [RECV  EVENTS]  = 

*  Returns:  0:  OK,  1:  open  failed,  2:  user  abort.  - */ 

{  /*  S  Init  Recv  */ 

A  Get  Fname (  char  ‘fname  ) 

{  {  "fname  O.K"  ,  A  Frame  Wait  ,  INIT  ,  S  Incoming  }, 

( 

{  "fname  bad"  ,  A  Prep  Recv  ,  (int)r  fname  ,  S  Init  Recv  }, 

long  fbytes; 

{  "user  abort"  ,  A  Recv  End  ,  (int) user  msg,  S  Exit  ), 

int  frees; 

(  "comm  error"  ,  A  Recv  End  ,  (int)badcomm  ,  S  Exit  )  ), 

int  fsecs; 

/*  S_Incoming  */ 

(  (  "got  one"  ,  A  Which  Ctrl  ,  (intj&sohor  ,  S  First  What  ), 

printf ("\n  Please  Input  file  name  to  transmit:  ") ; 

(  "comm  error"  ,  A  Recv  End  ,  (int)badcomm  ,  S  Exit  ), 

fgetsnn  (stdin,  fname,  NAMESIZE  ); 

(  "timeout"  ,  A  Frame  Wait  ,  RESEND  ,  S  Incoming  }, 

if  (  (fname[0]  ==  eschar)  !!  (fname [0]  ==  '\0')  ) 

I  "no  retries"  ,  A  Recv  End  ,  (int)giveup  ,  S  Exit  }  }, 

return (2) ; 

/*  S  First  What  */ 

if  (  (s  fptr  =  fopen  (fname,  "rb"))  ==  NULL  )  ( 

{  (  "got  SOH"  ,  A  Validate  ,  (int)Scrc  ,  S  DePktize  }, 

printf ("\n  Cannot  open  %s.  Try  again. \n",  fname); 

{  "got  CAN"  ,  A  Recv  End  ,  (int) cancel  ,  S  Exit  }, 

return (1) ; 

{  "got  EOT"  ,  A  Recv  End  ,  (int) eof  msg  ,  S  Exit  ), 

) 

{  "got  junk!"  ,  A  EatRest  ,  BUFSIZE  ,  S  Incoming  )  ), 

fbytes  =  filelength (  fileno(s  fptr)  ); 

/*  S  DePktize  */ 

frees  =  (  (fbytes  /  BUFSIZE)  +  (  (fbytes  %  BUFSIZE  —  0)  ?  0  :  1  )  ); 

{  {  "pkt  OK"  ,  A  Frame  Wait  ,  NEXT  ,  S  Incoming  }, 

/*  The  following  adds  time  for  turn  around  (ACK/NAK) ,  but  no  errors  */ 

(  "bad  hdr"  ,  A  EatRest  ,  BUFSIZE  ,  S  Incoming  }, 

fsecs  =  (int)  (  (fbytes  *  10)  /  (cur  config. speed  /  2  )  ); 

1  "bad  CRC"  ,  A  Frame  Wait  ,  RESEND  ,  S_Incoming  ), 

j  "timeout"  ,  A  Frame  Wait  ,  RESEND  ,  S  Incoming  )  ) 

printf ("\n  File  %s:  %4d  records,  est.  min:sec  %3d:%2d  at  %d  bps.\n", 

); 

fname,  frees,  fsecs  /  60,  fsecs  %  60,  cur_config. speed  ); 

/*  -  Xmodem  Receive  state  machine  -  */ 

prev  conf  =  cur_config;  /*  save  entry  config  */ 

cur  config.ubits . lctrl  =  atelnone;  /*  Force  things  to  8/1/N  */ 

xmodem  recv() 

Config  Comm(  comport,  cur_config  ); 

( 

char  inkey;  /*  place  for  user  to  abort  */ 

eat  noise ();  /*  Clear  out  any  garbage  in  the  input  queue  */ 

int  event;  /*  event  returned  from  action  */ 

return  (0) ; 

int  prevent;  /*  previous  event  */ 

) 

struct  event  entry  *cur_entry;  /*  pointer  to  current  row/col  of  sm  */ 
action  new  action;  /*  next  action  to  perform  */ 

/*  -  A  Init  Wait:  Waits  for  initial  sync  character.  - 

enum  send  state  cur  state  =  S  Init  Recv; 

*  Returns:  The  value  returned  from  A  Wait().  */ 

A  Init  Wait (int  expected) 

event  =  A  Prep  Recv(r  fname); 

{ 

static  int  tries  =  2;  /*  try  initial  CRC,  then  once  more  */ 

while  (mode  ==  M  XRecv) 

static  int  passes  =  10;  /*  give  up  after  10  junk  reads  */ 

{ 

static  int  last; 

prevent  =  event;  /*  save  the  previous  event  for  next  state  */ 

int  retval; 

cur  entry  =  &recv  machine [ (int) cur_state] [event] ; 

switch  (expected)  i  (continued  on  page  96) 

94 


Dr.  Dobb’s Journal,  October  1989 

713 


F I NITE  STATE  MACHINES 


Listing  Four  (Listing  continued,  text  begins  on  page  45J 

case  CRC:  last  =  CRC;  /*  If  we  really  want  CRC...  */ 
break; 

case  NAK:  last  =  NAK;  /*  or  if  we  only  want  Checksum  */ 
break; 

case  NEXT:  if  ( — tries  ==  0)  {  /*  want  to  switch?  */ 

last  =  {last  ==  CRC)  ?  NAK  :  CRC; 
tries  =  2; 

> 

} 

printf  ("\rAwaiting  %s . . . ",  (last  ==  CRC)  ?  "CRC"  :  "NAK"); 
retval  =  A_Wait (last) ; 
if  (retval  !=  0)  ( 
if  (passes —  ==  0) 

return<3);  /*  cancelled  */ 

else 

return (retval) ; 

J 

passes  =  10;  /*  reset  passes  counter  */ 

crc  =  (last  ==  CRC)  ?  1  :  0; 
return (retval) ; 


/*  -  A_Wait:  Waits  for  appropriate  time  for  a  character. 

*  Returns:  0:  match,  1:  if  other,  2:  timeout,  3:  cancel.  */ 

A_Wait (  int  expected) 

I 

char  inch; 
int  errval; 
int  numread  =  1; 
int  retval  =  0; 

errval  =  read_comm(  inumread,  &inch,  (expected  ==  SOH)  ?  1000  :  10000  ); 

if  {  numread  >  0  )  { 
if  (inch  ==  (char)  expected) 
retval  =  0; 

else  retval  =  (inch  ==  CAN)  ?  3  :  1  ; 

} 

else 

if  (errval  ==  TIMEOUT) 
retval  =  2; 

return  (retval); 

) 

/*  -  Action  Make_Pkt:  Reads  from  disk,  formats  packet.  - 

*  Returns:  0:  OK,  T:  disk  trouble,  2:  EOF  found.  */ 

A_Make_Pkt (int  which  ) 

f 

register  int  i; 
int  errval; 
unsigned  int  lo_crc; 
static  int  pkt; 

static  unsigned  char  *diskbuf  =  (unsigned  char  *)  Ss_pkt.data; 
static  unsigned  char  *curptr;  /*  where  are  we  now?  */ 

crcaccum  =  0;  /*  zero  out  global  crc  and  checksum  value  */ 

checksum  =  0; 

for  (curptr  =  diskbuf,  i  =  0;  i  <  BUFSIZE;  i++,  curptr++)  ( 
if  (  (errval  =  getc (s_fptr) )  ==  EOF  ) 
break; 

*curptr  =  errval; 
updcrc (errval) ; 

) 

if  (i  ==  0) 

return (2);  /*  That's  all  folks!  */ 

for  {  ;  i  <  BUFSIZE;  i++,  curptr++)  (  /*  Zero  fill  the  rest  of  packet  */ 

*curptr  =  0; 
updcrc (0) ; 

1 


if  (which  ==  INIT)  { 

printf ("\n\nSending  file  %s  using  %s.\n", 

s  fname, (crc  ==  0)  ?  "Checksum"  :  "CRC"); 

pkt  =  1; 

) 

else  pkt  =  (++pkt  %  256) ; 

s_pkt.soh  =  SOH; 
s_pkt . pkt  =  pkt ; 
s_pkt.pkt_cmp  =  ~pkt; 

updcrc (0);  /*  finish  off  xmodem  variation  */ 

updcrc (0) ; 
lo_crc  =  crcaccum; 
if  (crc  ! =  0)  ( 

s_pkt.crcl  =  (crcaccum  »  8);  /*  high  byte  first  */ 

s_pkt.crc2  =  lo_crc; 

} 

else 

s_pkt.crcl  =  checksum; 
return  (0); 


/*  -  Action  Send_Pkt :  Send  a  packet  out  the  comm  port.  - 

*  Returns:  0:  OK,  1:  write  err,  2:  no  retries,  3:  cancelled  */ 
A_Send_Pkt (  int  why  ) 

{ 

static  int  retries  =  TXTRIES;  /*  If  not  general,  make  a  global  table  */ 
int  errval; 

switch  (why)  { 

case  NEXT:  retries  =  TXTRIES; 

putch('.');  /*  show  we  are  making  progress  */ 

break; 

case  NAK: 

case  TIMEOUT: 

case  RESEND:  — retries; 
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Listing  Four  (Listing  continued,  text  begins  on  page  45.) 


putch (' R' ) ; 


if  (! retries)  ( 
retries  =  TXTRIES; 
return  (2); 

1 


errval  =  writecomm(  (char  *)  &s_pkt,  (crc  !=  0)  ?  133  :  132  ); 
if  (errval) 
return  (1) ; 

eat_noise();  /*  clear  out  any  garbage  */ 

return  (0); 


/*  -  Action  Send_End: 

A_Send_End  (  char  ‘reason 
I 

char  eotc  =  EOT; 
int  not done  =  1; 
int  eotries  =  10; 


Only  way  out  of  the  Send  state.  -  */ 

) 

/*  just  in  case  we  really  transmit  the  file  */ 
/*  have  we  received  an  ACK  to  our  EOT?  */ 

/*  Should  be  enough  for  most  */ 


if  (s_fptr  !=  NULL)  {  /*  Did  we  even  get  started???  */ 

if  (reason  !=  eof_msg)  (  /*  Started,  but  bad  news  */ 

eotc  =  CAN; 
writecomm(&eotc,  1); 

1 

else  /*  eof  =  We  did  it!  Send  our  EOT  and  get  out  */ 

while  (  (notdone  !=  0)  &&  [eotries — )  )  { 
writecomm(Seotc,  1); 
notdone  =  A_Wait (ACK) ; 

) 

f close (s_fptr) ; 

Config_Comm(  comport,  prev_conf  );  /*  Put  whatever  parity  back  in  */ 


printf("\n  ***  Ending  session.  %s . \a\n", reason) ; 
mode  =  M_Cmd; 

return  (SEND_EVENTS  -  1);  /*  last  event  always  has  next  state  S_Exit  */ 


**** 

***********  S  E 

N  D  STATE 

TABLE 

* 

**************** 

/ 

struct  event_entry  send_machine( (int) S 
(  /*  S  Init  Send  */ 

_Exit] [SEND_EVENTS]  = 

i 

"fname  O.K" 

A_Init_Wait  , 

CRC 

, 

S_Sync_Wait 

h 

"fname  bad" 

A  Get  Fname  , 

(int)s  fname 

, 

S_Init_Send 

), 

"user  abort" 

A  Send  End  , 

(int) user  msg, 

S_Exit 

), 

/* 

"no  retries" 
S_Sync_Wait  */ 

A_Send_End  , 

(int) nonak 

' 

S_Exit 

)  ) 

( 

"in  sync" 

A_Make_Pkt 

INIT 

S  Make  Pkt 

), 

"unexpected" 

A_Init_Wait  , 

NEXT 

S_Sync_Wait 

), 

"timeout" 

A_Init_Wait  , 

CRC 

S_Sync_Wait 

), 

/* 

"cancelled" 
S_Make_Pkt  */ 

A_Send_End  , 

(int) cancel 

S_Exit 

)  ) 

( 

"pkt  ready" 

A_Send_Pkt  , 

NEXT 

S_Send_Pkt  ), 

"bad  disk?" 

A_Send_End  , 

(int) badread 

S_Exit 

), 

"done! " 

A_Send_End  , 

(int) eof_msg 

S  Exit 

/* 

"trouble ! " 
S_Send_Pkt  */ 

A_Send_End  , 

(int)giveup 

S_Exit 

)  ) 

f 

"sent  O.K." 

A_Wait  , 

ACK 

S  Data  Response 

), 

"comm  error" 

A_Send_Pkt  , 

RESEND 

S_Send_Pkt 

"no  retries" 

A  Send  End  , 

(int) giveup 

S  Exit 

), 

/* 

"cancelled" 

S_Data_Response 

A  Send  End  , 

*/ 

(int) cancel 

S_Exit 

)  ) 

( 

"ack  rcvd." 

A  Make  Pkt  , 

NEXT 

S  Make  Pkt 

1, 

"not  ack" 

A_Send_Pkt  , 

NAK 

S_Send_Pkt 

). 

"timeout" 

A_Send_Pkt  , 

TIMEOUT 

S  Send  Pkt 

), 

"cancelled" 

A_Send_End  , 

(int) cancel 

S_Exit 

)  } 

I; 


/*  - Send  state  machine -  */ 

xmodem_send ( ) 

( 

char  inkey;  /*  In  case  the  user  wants  to  abort  */ 

int  event;  /*  event  returned  from  action  */ 

int  prevent;  /*  previous  event  */ 

struct  event_entry  *cur_entry;  /*  pointer  to  current  row/col  of  sm  */ 

action  new_action;  /*  next  action  to  perform  */ 

enum  send_state  cur_state  =  S_Init_Send; 

event  =  A_Get_Fname (s_fname) ; 

while  (mode  ==  M_XSend)  ( 

prevent  =  event;  /*  save  the  previous  event  for  next  state  */ 

cur_entry  =  &send_machine [ (int) cur_state] [event] ; 

#ifdef  TRACE 

printf  ("State:  %16s,  Event:  %2d,  Note:  %20s\n", 

state_list [ (int) cur_state] ,  event,  cur_entry->comment  ); 

fendif 

/*  Based  on  the  current  state  and  event,  execute  action (param)  */ 

new_action  =  cur_entry->act; 

event  =  new_action (cur_entry->param) ; 

cur_state  =  send_machine [ (int) cur_state] [prevent] .next_state; 

if  (  keyfun (KEYHIT)  )  (  /*  from  CTERM  */ 

inkey  =  (char)  keyfun (READNEXT) ;  /*  Truncate  high  order  */ 
if  (inkey  ==  eschar) 

A_Send_End (user_msg) ; 

} 

) 

return  (0); 

1  End  Listing  Four 

(listings  continued  on  page  100) 
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Listing  Five  (Listings  continued,  text  begins  on  page  45.) 

else 

return  (rg.x. ax); 

/*  CTERM1.C  by  Donald  W.  Smith.  CIS  76515,3406. 

) 

*  A  minimal  terminal  emulator  to  demonstrate  the  use  of  state 

*  machine  driven  communications  protocols  using  the  C  language. 

/* - term:  Emulates  a  dumb  terminal.  — • - -  */ 

*  Use  makectl.  to  compile.  */ 

void  term() 

# define  VERSION  fputs("\n\t  CTERM  1.11:  4/26/89  DWS\n\n", stdout) 

register  int  i; 

♦define  BUFLEN  200 

int  keyin;  /*  Key  =  scan  code  +  ASCII  val  */ 

♦define  LINELEN  80  /*  Max  user  input  length.  Lots  of  slack  */ 

char  gochar; 
int  redd; 

♦include  <conio.h> 

int  ret  code, 

♦include  <ctype.h>  /*  for  Turbo  C  is...  functions  */ 

wait  ret; 

♦include  <dos.h> 

char  ‘tail  =  inbuf;  /*  for  tail  of  input  buffer  */ 

♦include  <process.h>  /*  For  system!)  call  */ 

static  int  cap  flag  =  0;  /*  Is  capture  turned  on  now?  */ 

♦include  <signal.h>  /*  Ctrl-C  and  Ctrl-Break  handling  */ 

♦include  <stdio.h> 

while  (mode  ==  M  Term)  ( 

♦include  <stdlib.h>  /*  For  system!)  call  */ 

redd  =  BUFLEN  /  2;  /*  Go  for  half  at  a  time.  */ 

♦include  "cterm.h"  /*  defines  for  cterm  series  */ 

ret  code  =  read  comm  (sredd,  inbuf,  10);  /*  10  msecs  */ 

♦include  "commn.h"  /*  defines  shared  by  myint  and  cterm  */ 

if  (  (ret  code  !=  0)  S&  (ret  code  !=  TIMEOUT)  ) 

♦include  "getargs.h"  /*  for  getargs  access  */ 

fprintf  (stderr,  "read  comm  error  %x\n",  ret  code  ); 

♦define  CMDDIM(x)  (sizeof (x) /sizeof (x [0] ) ) 

if  (  redd  >  0  )  (  /*  Reading  was  productive  */ 

tail [redd]  =  0;  /*  plant  a  null  */ 

/* - GLOBALS -  */ 

enum  modes  mode  =  M  Cmd;  /*  Term,  Config,  etc.  */ 

for  (  i  =  0;  i  <  redd;  i++)  (  /*  check  for  specials  */ 

char  inbuf [BUFLEN+1] ; 

if  (  isprint(  gochar  =  inbuf (i)  S  0x7F)  !!  /*  zero  hi  */ 

char  outbuf [LINELEN+1] ;  /*  Used  for  short  output  */ 

(  isspace (gochar)  )  !!  /*  CR,LF..  */ 

S  INIT  cur  config  =  (1200);  /*  Current  port  config  */ 

gochar  ==  BS  )  ( 

int  comport  -  1;  /*  Current  comm  port  number  */ 

put ch (gochar) ; 

int  bbsmode  =  0;  /*  BBS  (8,1,N)  or  T16  (7,1,E)  */ 

if  (cap  flag) 

int  eschar  =  ESC;  /*  keyboard  escape  character  */ 

fputc (gochar,  cap  fptr); 

FILE  *cap  fptr;  /*  file  ptr  for  capture  file  */ 

)  /*  printable  test  */ 

static  union  REGS  rg;  /*  used  for  keyfun!)  */ 

)  /*  for  loop  */ 

I  /*  end  if  reading  was  productive  */ 

/* - External  variables -  */ 

extern  unsigned  heaplen  =  4096;  /*  TurboC  1.5  and  above  */ 

if  (  keyfun (KEYHIT)  )  ( 

keyin  =  keyfun (READNEXT) ;  /*  Retrieve  Scan  Code  +  Key  */ 

/*  - External  routines - */ 

gochar  =  keyin  &  OxFF;  /*  truncates  */ 

/*  —  From  myint  —  */ 

if  (gochar  ==  0)  (  /*  Function  key  or  a  special  */ 

extern  void  Config  Comm(  int  port,  S  INIT  conf  ); 

switch  (keyin)  ( 

extern  S  INIT  Get  Conf(  int  port  ) ; 

case  PGUP:  mode  =  M  XSend; 

extern  int  incommO; 

xmodem  send ( ) ; 

extern  int  Inst  IH(void  interrupt  (*faddr){),  int  comnum) ; 

mode  =  M  Term; 

extern  int  Remove  I H ( ) ; 

break; 

extern  int  writecomm (unsigned  char  *buf,  int  len) ; 

case  PGDN:  mode  =  M  XRecv; 

extern  int  xmit  break!); 

xmodem  recv  ( ) ; 

/*  --  from  xmutil  —  */ 

mode  =  M  Term; 

extern  int  read  commfint  *num,  char  *buf,  int  wait); 

break; 

/*  —  from  object  only  files  —  */ 

case  CBRK:  xmit  break (); 

extern  int  getargs!  int,  char**,  ARG  *,  int,  int  (*usage)  ()  ); 

break; 

case  INS:  if  (capture  sw()  ==  0) 

ARG  Argtab[)  =  { 

cap  flag  =  leap  flag; 

(  'b',  BOOLEAN,  &bbsmode,  "BBS  mode  (8,1,N)  vs.  T16)"  }, 

default:  break; 

(  'c',  INTVAR,  &comport,  "1  =  COM1,  2  =  COM2"  ), 

) 

I  'e',  INTVAR,  &eschar,  "Escape  char  (Ox..)"  ), 

) 

(  's',  INTVAR,  &cur_config. speed,  "speed  in  bps"  )  ); 

else  (  /*  Some  plain  old  ascii  character  came  in  */ 

if  (  gochar  !=  eschar  )  { 

/*  -  fgetsnn:  Gets  a  line  from  file,  replacing  \n  with  NULL. 

outbuf [0]  =  gochar; 

*  Return  #  chars,  or  EOF  */ 

writecomm (outbuf,  1); 

int  fgetsnn (FILE  *fp,  char  *s,  int  size) 

{ 

I 

else  /*  ESCAPE  entered  */ 

register  int  i; 

mode  =  M  Cmd;  /*  leave  terminal  mode  */ 

int  c; 

1 

)  /*  end  if  keypressed  */ 

for  (i  =  0;  (i  <  size-1)  && 

)  /*  while  mode  =  M  Term  */ 

(c  =  fgetc(fp))  !=  EOF  && 

(c  !=  '\n')  ;  ++i) 

return; 

} 

s[i]  =  c; 

s [i]  =  '  \ 0 ' ; 

/*  -  off  to  dos:  Prompts  for  command  to  pass  to  dos.  -  */ 

if  (c  ==  EOF) 

void  off  to  dos () 

return (EOF) ; 

( 

char  buf [LINELEN] ; 

return (i) ; 

1 

fputs ("\nlnput  DOS  Command  (CR  returns  to  menu) \nD0S>", stdout) ; 

/*  -  capture  sw:  Enables  saving  sessions  to  (PC)  disc.  - 

while  (  fgetsnn (stdin,  buf,  LINELEN)  )  (  /*  >  1  means  got  1  */ 

*  Returns:  0  O.K.  1  if  open  fails,  2  if  ESC  hit.  */ 

system (buf) ; 

int  capture  sw() 

fputs ("\nDOS>",  stdout) ; 

static  char  cap  fname [NAMESIZE  +  1]  =  "capture . fil"; 

) 

char  cap  temp[NAMESIZE  +  1]; 

static  int  cap_sw  =  0;  /*  capture  on/off  switch  */ 

/*  -  config:  Prompts  for  new  config  (speed  or  default). —  */ 

void  config () 

if  (cap  sw  ==  0)  (  /*  Open  the  file  for  capture  */ 

( 

fprintf (stdout, "\n  Capture  to  file  <%s>  or  :  ",cap  fname); 

S  INIT  work; 

fgetsnn  (stdin,  cap  temp,  NAMESIZE  ); 

char  *cptr; 

if  (cap  temp[0]  ==  eschar) 

char  buf [LINELEN]  ; 

return (2) ; 

unsigned  inval; 

if  (cap  temp[0]  !=  '\0') 

int  inlen; 

strncpy(cap  fname,  cap  temp,  NAMESIZE); 

int  i  =  0; 

if  (  (cap  fptr  =  fopen  (cap  fname,  "a+t"))  ==  NULL  )  { 

printf("\n  Cannot  open  %s.  Try  again. \n",  cap  fname); 

work  =  Get  Conf (comport) ;  /*  a  struct  assignment  */ 

return (1) ; 

) 

fputs ("\n  Current  config  shows :\n",  stdout); 

cap  sw  =  1; 

1 

printf("%5u,  parity  %s,  %s  stops,  %d  bits/char . \n" , 

else  |  /*  we  are  already  capturing.  Close  and  get  out  */ 

work. speed, 

f close (  cap  fptr  ); 

PARITY  LIST [work. ubits . lbits .parity] , 

cap  sw  =  0; 

STOP  LIST[work. ubits. lbits. two  stops], 

1 

work. ubits. lbits. wlen  +  5); 

return (0) ; 

1 

fputs ("0  =  T16  (  7,  1,  Even  )\n",  stdout); 
fputs ("1  =  BBS  (8,  1,  None  )\n”,  stdout); 

/*  -  keyfun:  Use  to  call  BIOS  keyboard  input  services  - 

fputs ("other  =  new  speed  value\n",  stdout); 

*  Use  instead  of  keypressed  and  bioskey  to  prevent  DOS  '’C's.  */ 

inlen  =  fgetsnn (stdin,  buf,  LINELEN);  /*  Got  one  parameter  */ 

int  keyfun (int  serv) 

{ 

if  (inlen  >  0)  ( 

rg.h.ah  =  serv; 

inval  =  atoi(buf); 

int86(BIOS  KEY,  Srg,  Srg); 

if  (inval  ==  0)  ( 

if  (serv  ==  KEYHIT) 

return  ((rg.x. flags  &  0x40)  ==  0); 
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Listing  Five  (Listing  continued,  text  begins  on  page  45.) 

work. ubits . let rl  =  sevleven;  /*  7,1, EVEN  */ 

bbsmode  =  0; 

I 

if  (inval  ==  1)  { 

work. ubits. lctrl  =  atelnone;  /*  8,1, NONE  */ 

bbsmode  =  1; 

) 

if  (inval  >1)  ( 

while  (  SPEED_VALS [i]  &&  SPEED_VALS ( i ]  !=  inval  ) 
i++; 

if  (SPEED_VALS [i]  ==  0) 

printf("\n  Speed  %d  unavailable. \n", inval) ; 
else  (  /*  found  a  valid  new  speed  */ 

work. speed  =  inval; 

) 

) 

Config_Comm (comport,  work); 

cur_config  =  work;  /*  Publish  the  results  */ 

) 

else 

fputs("\n  Exiting  Config  mode.\nn,stdout) ; 
if  (  inlen  ==  (LINELEN  -  1)  ) 

while  (fgetc(stdin)  !=  EOF)  /*  Purge  garbage  in  buffer  */ 


mode  =  M_Cmd; 

1 


/*  -  prompt_wait:  Prompts  with  string,  parses  command.  - 

*  Returns:  The  (int)  index  number  of  the  command  entered.  */ 
prompt_wait  (  char  *prc"'t,  char  *cmds(],  int  n,  int  help  ) 

{ 

char  buffer (LINELEN);  /*  used  by  fgetsnn  */ 
int  i  =  0; 

while  (i  ==  0)  (  /*  Don't  bite  on  CR  only  input  */ 

print f ("\n%s", prompt) ; 
i  =  fgetsnn (stdin,  buffer,  LINELEN  ); 

) 

if  (  i  ==  (LINELEN  -  1)  ) 

while  (fgetc (stdin)  !=  EOF)  /*  Purge  garbage  in  buffer  */ 


for  {  i  =  0  ;  i  <  n  ;  i++  ) 

if  (  *cmds[i]  ==  toupper (buffer (0) )  )  /*  Match  first  char  */ 

return (i) ? 

return  (help);  /*  not  found...  return  help  default  */ 


/*  -  main_help:  Shows  canned  help  message 

void  main_help() 


static  char 
(  "Config 
"Dos, 
"Help, 
"Quit 
"Rcvx, 
"Sendx, 
"Term, 


*details[]  = 

:  Set  up  comm  parameters. \n", 

:  Calls  DOS  with  commands . \n", 

:  See  this  help  info.Xn", 

:  Exit  program. \n", 

:  Receive  file  using  Xmodem. \n", 

:  Send  file  using  Xmodem. \n", 

:  Dumb  terminal  mode.\n"  }; 


register  int  i; 

fputs("\n  Valid  commands  are: \n", stdout) ; 
for  (i  =  0  ;  i  <  CMDDIM(details)  ;  i++) 
print f ("%s", details [i] ) ; 


/*  -  main_menu:  Prompts  for  input,  dispatches  if  valid  --  */ 

void  main_menu() 

{ 

static  char  *prompt  =  "CTERM>"; 
static  char  *maincmds[]  = 

(  "CONFIG", 

"DOS", 

"HELP",  /*  used  for  default  below  (index  2  )  */ 

"QUIT", 

"RCVX", 

"SENDX", 

"TERM"  ) ; 


while  (mode  ==  M_Cmd)  { 

switch  (  prompt_wait (prompt,  mainemds,  CMDDIM (mainemds) ,  2  )) 
{ 

case  0:  mode  =  M_Config; 
config () ; 
break; 

case  1:  of f_to_dos () ; 
break; 

case  2:  main_help(); 
break; 

case  3:  printf("\n  ***  Closing  Comm  port  %d.",  comport); 
close_comm() ; 
exit  (1) ; 

case  4:  mode  =  M_XRecv; 

xmodem_recv ( )  ; 

fputs ("\nReturned  from  xmodem  reev! \n", stdout) ; 
break; 

case  5:  mode  =  M_XSend; 

xmodem  send ( ) ; 

fputs ("\nReturned  from  xmodem  send! \n", stdout) ; 
break; 

case  6:  mode  =  M_Term; 
eatnoise () ; 
term() ; 
break; 

default:  main_help(); 


}  /*  end  switch  */ 

)  /*  end  while  */ 

1 

/* - Catch_23:  Traps  AC  +  "Break  during  user  I/O.  - */ 

void  Catch_23() 

signal (SIGINT,  Catch_23);  /*  Re-install  self  each  time  */ 

return ; 

I 

/*  -  Catch_24 :  Traps  Disk  (Abort,  Retry,  Fail?)  errors  —  */ 

int  Catch_24 (int  errval,  int  ax,  int  bp,  int  si) 

{ 

char  msg[25] ; 
int  drive; 

if  (ax  <  0)  (  /*  device  error  */ 

bdosptr(  0x09,  "device  error$",  0); 
hardretn (-1) ; 

I 

drive  =  (ax  6  OxOOFF) ; 

sprintf(msg,  "disc  error  on  drive  %c  $",  'A'  +  drive); 
bdosptr(  0x09,  msg,  0); 
hardretn (2) ; 

) 

/* - usage:  Give  user  quick  help  before  exit. - */ 

usage () 

printf ("\n  Defaults:  T16,  1200  bps,  8,1, NONE,  COM1,  ESC.\n"); 


/* - main:  Gets  the  ball  rolling!  -  */ 

main(  int  arge,  char  *argv(]  ) 

{ 

int  error; 

VERSION; 

signal (SIGINT,  Catch_23); 
harderr (Catch_24) ; 

arge  =  getargs(  arge,  argv,  Argtab,  CMDDIM (Argtab) ,  usage  ); 

error  =  in it_comm (comport,  bbsmode); 
if  (error  !=  0)  ( 

fprintf (stderr, "\n  ***  Comm  Port  %d  Init  FAILED! ",  comport) ; 
return  (2) ; 

) 

fprintf (stderr, "\n  ***  Comm  Port  %d  Init  O.K.  ***  ",  comport); 
main_menu {) ; 
return  (1) ; 

I  End  Listing  Five 


Listing  Six 

#Make  file  for  cterm  series  Turbo  C.  1/23/89  DWS 
#3/20/89:  Added  getargs  and  stoi  (.obj  only)  from  Holub 
#use  Make  -fmakectl 
# Small  memory  model 
MDL  =  s 

LIB  =  c:\turboc\lib 
fimplicit  rules 

#  To  add  debug  info:  TCC  (-v),  TLINK  (/v) 
tcc  -c  -m$ (MDL)  $< 

♦explicit  rules 

cterml.exe:  commint.obj  xmsend.obj  xmrecv.obj  xmutil.obj  cterml.obj 

tlink  .  .\lib\c0s  cterml  xmsend  xmreev  xmutil  commint  getargs  stoi, 
cterml,  ,  ..\lib\cs 


xmsend.obj : 

xmsend. c 

cterm. h 

commn .  h 

xmrecv.obj : 

xmreev. c 

cterm. h 

commn .  h 

commint.obj : 

commint. c 

commn . h 

commint  .h 

xmutil.obj : 

xmutil. c 

cterm. h 

commn .  h 

commint  .h 

cterml.obj: 

cterml .c 

cterm. h 

commn.  h 

fend  makefile 

End  Listings 
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GLOVAR 


Listing  One  (Text  begins  on  page  70.) 

name  globals 
page  ,132 

title  'GLOVAR  -  global  variable  device  driver 
GLOVAR. ASM 

Copyright  1989,  Jim  Mischel 

This  MS-DOS  device  driver  provides  true  global  variables  to  application 
programs . 

Sample  make  file: 

# 

#  glovar.mak  -  build  global  variable  device  driver  glovar.sys. 

# 

glovar.sys:  glovar.asm 
tasm  glovar 
link  glovar; 

exe2bin  glovar.exe  glovar.sys 

ideal 

locals 

model  tiny, pascal 
CodeSeg 

org  0  ; device  drivers  start  at  offset  0 

;only  12  functions  recognized  by  the  driver 


/buffer  size  in  bytes 


max  cmd 

equ 

12 

cr 

equ 

Odh 

If 

equ 

Oah 

buff  size 

equ 

1024 

TRUE 

equ 

-1 

FALSE 

equ 

0 

;  Device  Driver 

Header 

header 

dd 

-1 

dw 

8000h 

dw 

strat 

dw 

intr 

db 

' $$GVAR$$' 

rh_ptr 

dd 

7 

/link  to  next  device,  -1  =  end  of  list 
/simple  character  device  driver 
/device  Strategy  entry  point 
/device  Interrupt  entry  point 
/Device  name 

/saved  request  header  pointer 


Command  codes  dispatch  table.  Only  functions  0  (initialize)  and  4  (read) 
are  supported.  Other  functions  go  to  a  stub  routine  that  simple  returns 


0  =  initialize  driver 
not  implemented 
not  implemented 
not  implemented 
4  =  read  from  device 
not  implemented 
not  implemented 
not  implemented 
not  implemented 
not  implemented 
not  implemented 
not  implemented 
not  implemented 
not  implemented 


/length  of  request  header 

/unit  number  for  this  request  (block  devices) 
/request  header's  command  code 
/driver's  return  status  word 
/reserved  area 

/media  descriptor  byte  (block  devices) 

/memory  address  for  transfer 

/byte/sector  count  value 

/starting  sector  value  (block  devices) 

/end  of  request  header  template 


8000h 

0200h 

OlOOh 

3 


/  a  non-error  status. 

dispatch: 

dw 

init 

dw 

not  imp 

dw 

not  imp 

dw 

not  imp 

dw 

read 

dw 

not  imp 

dw 

not  imp 

dw 

not  imp 

dw 

not  imp 

dw 

not  imp 

dw 

not  imp 

dw 

not  imp 

dw 

not  imp 

dw 

not  imp 

/  MS-DOS  Request  Header 

struc  request 

rlength  db 

7 

unit  db 

7 

command  db 

7 

status  dw 

7 

reserve  db 

8  dup  ( 

media  db 

? 

address  dd 

7 

count  dw 

7 

sector  dw 

? 

ends  request 

Status  codes 

returned 

error 

equ 

busy  equ 
done  equ 
unknown_command  equ 


Device  strategy  routine  --  save  address  of  request  header. 

strat:  mov  [word  per  cs:rh_ptr) ,bx 

mov  [word  per  cs:rh_ptr+2] ,es 

retf 

Interrupt  routine.  Dispatch  to  the  proper  routine. 


proc 


intr 
pusnr 
push 
pop 
les 
mov 
xor 
emp 
jle 
mov 
jmp 

intrl:  shl 


far  uses  ax  bx  cx  dx  ds  es  di  si 


ds 

di,  [rh_ptr] 

bl, [es :di+request .command] 

bh,  bh 

bx,max_cmd 

intrl 

ax, error+unknown_command 
short  intr2 
bx,  1 


/point  to  local  data 
,*ES:DI  =  Request  Header 
/bx  =  command  code 

/make  sure  it's  legal 

/ Error :  unknown  command 

/form  index  to  dispatch  table 


call 

[word  ptr  bx+dispatch] 

/and  branch  to  driver  routine 

les 

di, [rh  ptr] 

/ES:DI  =  request  header 

or 

ax, done 

/set  Done  bit 

mov 

[es :di+request . status] , ax 

/store  status  in  request  header 

popf 

ret 

intr 

stub'  routine  for  un-implemented  functions. 
not_imp : 


/set  good  status 


Read  —  return  address  of  ' global_table' 

This  routine  assumes  that  the  application  program  asked  for  4  (no  less!) 
bytes  (the  size  of  a  far  pointer) . 

This  function  is  called  with  ES:DI  pointing  to  the  MS-DOS  request  header. 


Ids 

mov 

mov 

mov 

xor 

ret 


si, [dword  ptr  es :di+request .address] 
[word  ptr  ds:si) , offset  globaltable 
[word  ptr  ds:si+2],cs 
[word  ptr  es:di+request. count] ,  4 
ax,  ax 


;DS:SI  is  buffer  address 
/store  offset 
/and  segment 
/4  bytes  transferred 
/return  good  status 


The  following  three  routines  (set_var,  get_var,  flush_vars)  are  accessed 
by  applications  programs  through  FAR  calls.  The  addresses  of  these 
functions  are  provided  in  the  ' global_table'  structure,  the  address  of 
which  is  passed  to  the  application  when  it  does  a  read  on  the  $$GVAR$$ 
device. 


set_var  —  assign  a  value  to  the  global  variable  pointed  to  by  the 
'varname'  parameter.  If  the  'vardef'  parameter  points  to  the  null  string, 
the  variable  is  removed  from  the  table. 


/  Returns  TRUE 

(-1)  if  successful,  FALSE  (0)  if 

variable  table  overflows 

proc 

set  var 

far  uses  si  di  ds,  varname: far 

ptr,  vardef: far  ptr 

Ids 

si, [varname] 

call 

near  ptr  remove  var 

/try  to  remove  variable 

les 

di, (vardef] 

emp 

[byte  ptr  es:di] , 0 

/check  for  NULL  string 

jnz 

doset 

mov 

ax,  -1 

/and  if  so,  just  call  it 

jmp 

short  set_done 

doset : 

Ids 

si, [varname] 

/otherwise, 

call 

near  ptr  install_var 

/install  the  new  def 

set  done: 

ret 

endp 

set_var 

Return  the  definition  of  the  variable  pointed  to  by  'varname'  in  the 
space  pointed  to  by  'vardef'.  Returns  -1  if  the  variable  exists,  0  if 
not.  If  the  variable  does  not  exist  the  null  string  is  returned  in  'vardef' 

proc  get_var  far  uses  si  di  ds,  varname: far  ptr,  vardef: far  ptr 


Ids 

si, [varname] 

call 

f ind_var 

jnc 

getl 

/if  found,  continue 

les 

di, [vardef] 

/otherwise, 

mov 

[byte  ptr  es 

: di ] ,  0  /store  NULL  string 

xor 

ax,  ax 

/set  failure  status 

jmp 

short  @@done 

/and  exit 

cld 

/variable  found,  now  fii 

mov 

al, '=' 

mov 

cx,  -1 

repnz 

scasb 

mov 

si,  di 

push 

es 

pop 

ds 

/DS:SI  now  points  to  first  charactei 

les 

di, (vardef] 

/ES:DI  points  to  return  vardef  area 

lodsb 

/copy  the  definition  to 

stosb 

/the  'vardef'  string 

or 

al,  al 

jnz 

@@loop 

mov 

ax, TRUE 

/set  status  to  TRUE 

ret 

get  var 

flush  all  variables  from  the  global  variable  table.  This  is  done  by  placing 
a  NULL  byte  at  the  start  of  the  table  and  updating  the  ' next_mem'  variable 
so  that  it  also  points  to  the  head  of  the  table. 


f lush_vars : 

mov 

mov 

mov 

retf 


[word  ptr  cs:glovars] , 0 
ax, offset  glovars 
[word  ptr  cs:next_mem] , ax 


Support  routines. 

Remove  the  variable  (name  pointed  to  by  ds:si)  and  its  definition  from 
the  global  variables  table. 


call  find_var 
jc  @@done 

cld 

mov  si,di 

mov  al,0 

mov  cx, -1 


/find  the  variable 

/SI  is  start  of  variable  name 
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repnz 

add 

inc 

xchg 

push 

pop 

mov 

sub 

rep 

@@done:  ret 


scasb 

[word  ptr  cs:next_raem] ,cx 
[word  ptr  cs:next  raem] 
si,  di 
cs 
ds 

cx, offset  end_buff 

cx,  si 

movsb 


/move  past  definition 
/update  nextmem  pointer 


sub  al,32 
tod:  ret 


/si=next  variable,  di=old  var 


even 


/might  as  well 


/cx  is  byte  count 
/variable  has  been  erased 


The  address  of  this  table  is  passed  back  to  the  application  whenever 
a  'read'  call  is  made  on  the  device. 

The  application  uses  this  table  to  access  the  memory  buffer  and  the 
driver  functions. 


Called  with  ds:si  pointing  to  variable  name,  es:di  pointing  to  definition. 


install  var: 

push 

es 

push 

di 

/save  'vardef'  address 

cld 

mov 

al,  0 

mov 

cx,  -1 

repnz 

scasb 

/get  length  of  definition 

not 

cx 

mov 

bx,  cx 

/and  save 

push 

bx 

/will  be  used  to  copy  the  definition 

push 

ds 

pop 

es 

mov 

di,  si 

mov 

cx,  -1 

repnz 

scasb 

/get  length  of  variable  name 

not 

cx 

push 

cx 

/will  be  used  to  copy  the  variable  name 

add 

bx,cx 

/bx=strien (varname) +strlen (vardef) +2 

mov 

ax,buff_size 

+  offset  glovars 

sub 

ax, [word  ptr 

cs:next_mem] 

cmp 

ax,  bx 

jnc 

instl 

/if  not  enough  room 

xor 

ax,  ax 

/then  fail 

add 

sp,  8 

/clean  up  stack 

ret 

instl:  push 

cs 

pop 

es 

mov 

di, [word  ptr 

cs:next  mem]  /ES:DI  points  to  buffer 

pop 

cx 

/ restore  varname  length 

dec 

cx 

/don't  want  null  terminator 

@@loopl : 

lodsb 

call 

toupper 

/convert  char  to  upper_case 

stosb 

/and  store 

loop 

@@loopl 

inst2:  mov 

al, ' =' 

stosb 

/store  the  '='  separator 

pop 

cx 

/restore  definition  length 

pop 

si 

/restore  'vardef'  address 

pop 

bs 

rep 

movsb 

/and  copy  definition  to  buffer 

mov 

[word  ptr  cs:next  mem],di 

stosb 

/store  extra  null  byte  for  safe  keeping 

mov 

ax, TRUE 

ret 


find_var  —  attempt  to  find  the  variable  pointed  to  by  DS:SI  in  the 
global  variables  buffer. 

On  success,  AX  =  TRUE  (-1),  carry  is  cleared,  and  ES:DI  points  to  the  first 
character  of  the  variable  name  in  the  buffer. 

If  the  variable  is  not  found,  AX  =  FALSE  (0),  carry  flag  is  set,  and  ES:DI 
is  undefined. 


f ind_var : 

cld 

push 

pop 

mov 

mov 

findO:  mov 
mov 
dec 

findl:  lodsb 
call 
inc 
cmp 
jz 
or 
jnz 
cmp 
jnz 
mov 
mov 
ret 

get_next_var : 
mov 
mov 
repnz 
cmp 
jnz 
xor 
stc 
ret 


cs 

es 

di, offset  glovars 

dx,  si 

bx,di 

si,  dx 

di 

toupper 

di 

al, [byte  ptr  es:di] 

findl 

al,  al 

get_next_var 

[byte  ptr  es:di],'=' 

get_next_var 

di,bx 

ax, TRUE 


al,  0 
cx,  -1 
scasb 

[byte  ptr  es:di] , 0 

findO 

ax,  ax 


/save  name  starting  address 
/and  variable  starting  address 


/didn't  match,  at  end  of  string? 
/if  not,  go  for  next  variable 
/at  end  of  varname  in  buffer? 

/if  not,  do  next  variable 
/variable  found 


/get  start  of  next  variable 
/if  not  at  end  of  buffer 
/then  do  next  variable 

/the  variable  wasn't  found 


global_table: 

dd 

dd 

dd 

dd 


/address  of  memory  buffer 
/address  of  set_var  routine 
/address  of  get_var  routine 
/address  of  flush_vars  routine 


next_mem  dw  offset  glovars 


/pointer  to  end  of  defined  variables 


glovars : 


/start  of  glovar  buffer 


Initialization  code. 

Initialize  the  function  pointers  table  and  the  global  data  buffer,  and 
return  the  address  of  the  first  byte  of  free  memory  after  all  the  device 
driver  code.  The  global  variables  buffer  overlays  this  initialization  code. 


Upon  entry,  ES:DI  points  to  the  MS-DOS  request  header.  DS  contains  the 
local  data  segment  (same  as  CS) .  This  routine  makes  no  attempt  to  save 
any  registers. 


mov 

ax,  cs 

mov 

es,  ax 

mov 

di, offset  dhaddr 

call 

hexasc 

/convert  load  segment  address  to  ASCII 

mov 

ax,cs 

mov 

es,  ax 

mov 

di, offset  mbaddr 

call 

hexasc 

push 

cs 

pop 

es 

mov 

ax, offset  glovars 

mov 

di, offset  mbaddr+5 

call 

hexasc 

mov 

ah,  9 

/print  sign-on  message  and 

mov 

dx, offset  ident 

/driver  load  address 

int 

21h 

les 

di,  [rh_ptr] 

/request  header  address  in  ES:DI 

/store  first  usable  memory  address  in  request  header 

mov  [word  ptr  es :di+request .address] , of f set  end_buff 
mov  [word  ptr  es :di+2+request .address] , cs 

/  Now  set  up  the  'global_table'  structure  with  proper  memory  addresses. 


mov 

mov 

mov 

mov 

mov 

mov 

mov 

mov 

xor 

mov 

ret 


[word  ptr  global_table] , of f set  glovars 

[word  ptr  global_table+2] , cs 

[word  ptr  global_table+4 ) , of fset  set_var 

[word  ptr  global_table+6] ,  cs 

[word  ptr  global_table+8] , of fset  get_var 

[word  ptr  global_table+10] ,  cs 

(word  ptr  global_table+12] , of fset  flush_vars 

[word  ptr  global_table+14 ] ,  cs 

ax, ax  /return  good  status 

[word  ptr  glovars], ax  /and  clear  glovars  buffer 


ident 

db 

cr, If, If 

db 

'Global  variable  device  driver  version  1.0',cr,lf 

db 

'Copyright  1989,  Jim  Mischel' ,cr, If 

db 

'Device  Header  at  ' 

dhaddr 

db 

'  XXXX: 0000 .  ' 

db 

'Memory  buffer  at  ' 

mbaddr 

db 

' SSSS :OOQO' ,cr,lf,lf,'$' 

hexasc  -  converts  a  binary  16-bit  number  into  a  hex  ASCII  string 

call  with  AX  =  value  to  convert,  ES:DI  =  address  to  store  4-character 
string. 


hexasc: 

mov 

bx,  ax 

/save  value  here 

mov 

cx,  4 

/initialize  character  counter 

mov 

dx,  cx 

hexascl 

xchg 

cx ,  dx 

rol 

bx,cl 

/isolate  next  4  bits 

mov 

al,  bl 

and 

al, Ofh 

add 

al,  '0' 

/convert  to  ASCII 

cmp 

al, ' 9' 

/if  0-9 

jbe 

hexasc2 

/then  jump 

add 

al,  'A'-'9'-l 

/otherwise  add  offset  for  A-F 

hexasc2 : 

stosb 

xchg 

cx,  dx 

loop 

ret 

hexascl 

toupper  -  convert  the  character  in  AL  to  upper-case. 


reserve  space  for  rest  of  global  variable  buffer. 

db  buff_size  -  (offset  $  -  offset  glovars)  +  1  dup  (0) 


toupper : 

cmp  al, ' a' 
jc  tod 

cmp  al,'z'+l 

jnc  tod 


even 

end_buf f : 

end 


End  Listing  One 
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listing  Two  (Listings  continued,  text  begins  on  page  70.) 

Listing  Four  (Listing  continued,  text  begins  on  page  70.) 

/* 

*  GVAR.C  -  program  to  test  global  device  driver  interface. 

*  Required  structure  and  function  definitions  are  in  the  file  GVAR.H 

*) 

* 

f$F+)  (  asm  routines  require  far  calls  ) 

*  Sample  make  file. 

( $L  tpgvar) 

* 

program  test  globals; 

*  # 

type 

*  #  tcgvar.mak  -  make  C  gvar  test  program 

varstr  =  string[255); 

*  gvar.exe:  gvar.c  gvar.h 

var 

*  tcc  -ms  gvar 

buff  :  varstr; 

*/ 

function  gvar  init  :  boolean;  external; 

♦include  <stdio.h> 

function  set  gvar  (varname  :  varstr;  vardef  :  varstr)  :  boolean;  external; 

♦include  <conio.h> 

function  get  gvar  (varname  :  varstr;  var  vardef  :  varstr)  :  boolean;  external; 

♦include  <fcntl.h> 

♦include  <io.h> 

procedure  flush_gvars;  external; 

♦include  "gvar.h" 

begin 

if  (not  gvar  init)  then  begin 

void  main  (void)  { 

writeln  ('Can''t  open  gvars  file.  Program  aborted.'); 

char  buff  (1024]  ; 

halt; 

int  fhandle; 

end; 

if  (not  set  gvar  ('JIMSVAR',  'HELLO  THERE')) 

if  ((fhandle  =  open  <"$$GVAR$$",  0  RDONLY) )  ==  -1)  ( 

writeln  ('Error  setting  variable  JIMSVAR'); 

puts  ("Error:  can't  open  global  variables  file"); 

if  (not  get  gvar  ('jimsvar',  buff)) 

return; 

writeln  ('JIMSVAR  not  defined') 

) 

else 

read  (fhandle,  sgvars,  sizeof  (char  far  *)); 

writeln  ('JIMSVAR=',  buff); 

printf  ("global  table  at  %Fp\n",  gvars) ; 

trash  :=  set  gvar  ('jimsvar',"); 

close  (fhandle); 

if  (not  get  gvar  ('jimsvar',  buff)) 

if  ( ! set  gvar  ("JIMSVAR",  "Hi  jim.!")) 

writen  ('JIMSVAR  not  defined') 

puts  ("Error  setting  variable  JIMSVAR"); 

else 

if  ( ! get  gvar  ("jimsvar",  buff)) 

writeln  ('JIMSVAR=',  buff); 

puts  ("JIMSVAR  not  defined"); 

else 

end. 

set  gvar  ("jimsvar",""); 
if  ( ! get  gvar  ("JIMSVAR",  buff)) 
puts  ("JIMSVAR  not  defined”); 

else 

End  Listing  Four 

printf  ("JIMSVAR=%s\n",  buff); 

} 

Listing  Five 

page  ,132 

name  tpgvar 

title  'TPGVAR  --  Turbo  Pascal  global  variable  interface  routines' 

End  Listing  Two 

;  TPGVAR.ASM 

;  These  routines  provide  the  Turbo  Pascal  interface  to  the  global  variable 

Listing  Three 

;  device  driver. 

;  The  routines  provided  are: 

*  gvar.h  —  required  definitions  for  C  interface  to  global  variable 

;  GVAR  INIT 

*  device  driver. 

;  function  gvar  init  :  boolean;  external; 

* 

;  Returns  TRUE  if  successful,  FALSE  otherwise.  MUST  be  called  before  using 

*  Copyright  1989,  Jim  Mischel 
*/ 

;  any  of  the  other  functions. 

;  SET  GVAR 

/* 

;  function  set  gvar  (varname  :  varstr;  vardef  :  varstr)  :  boolean;  external; 

*  structure  of  table  returned  by  glovar  read  call. 

;  Defines  the  variable  'varname'  with  the  value  'varstr'.  Returns  FALSE 

*/ 

;  if  inserting  this  variable  will  over-run  the  global  variables  buffer. 

typedef  struct  ( 

void  far  *mem  buff;  /*  pointer  to  memory  buffer  */ 

;  GET  GVAR 

/*  function  pointers  */ 

;  function  get  gvar  (varname  :  varstr;  var  vardef  :  varstr)  :  boolean;  external; 

int  far  pascal  (far  *set  var)  (char  far  *,  char  far  *); 

;  Return  the  definition  of  the  variable  'varname'  in  the  string  'vardef'. 

int  far  pascal  (far  *get  var)  (char  far  *,  char  far  *); 

;  Returns  FALSE  if  'varname'  doesn't  exist. 

void  far  pascal  (far  *flush  vars)  {); 

}  GVAR_DEF; 

;  FLUSH_GVARS  procedure  flush_gvars;  external; 

;  Removes  all  global  variables  from  the  buffer. 

GVAR  DEF  far  *  gvars;.  /*  global  pointer  to  global  variables  structure  */ 

;  Copyright  1989,  Jim  Mischel 

*  function  macros 

model  tpascal 

*/ 

ideal 

♦define  set_gvar  (*gvars->set_var) 

♦define  get  gvar  (*gvars->get  var) 

locals 

♦define  flush_gvars  (*gvars->flush_vars) 

;  global  variable  interface  structure 

;  A  pointer  to  this  type  of  structure  is  returned  by  the  $$GVAR$$  device 
;  in  response  to  a  read  call. 

struc  gvars 

membuff_ptr  dd  ? 

End  Listing  Three 

set  var  ptr  dd  ? 
get_var_ptr  dd  ? 
flush  vars  ptr  dd  ? 

Listing  Four 

ends 

CodeSeg 

*  GVAR. PAS  -  Test  global  variable  device  driver. 

;  This  has  to  go  into  the  code  segment  because  'TPascal'  model  won't  allow 

*  This  program  depends  on  the  routines  in  TPGVAR.ASM  to  provide  the  interface 

;  initialization  in  the  data  segment. 

*  to  the  device  driver. 

gvar  filename  db  '$$GVAR$$',0  .-global  variable  device  name 

*  Make  sure  the  file  tpgvar.obj  is  in  the  current  directory 

gvar  ptr  dd  ?  ; pointer  to  global  variables  structure 

glovar  name  db  256  dup  (?)  .-passed  to  driver  routines 

*  (or  Turbo's  /Object  directory)  before  compiling  this  program. 

glovar  def  db  256  dup  (?) 

*  Sample  make  file  for  compiling  this  program: 

public  GVAR  INIT 

*  ♦ 

public  SET  GVAR 

*  ♦  tpgvar.mak  -  make  pascal  gvar  test  program 

public  GET  GVAR 

*  ♦ 

public  FLUSH  GVARS 

*  gvar.exe:  gvar. pas  tpgvar.obj 

*  tpc  gvar 

* 

;  open  the  $$GVAR$$  file  and  read  the  address  of  the  header  into  gvar  ptr 

*  tpgvar.obj:  tpgvar.asm 

;  returns  TRUE  if  successful,  FALSE  if  not. 

*  tasm  tpgvar 

proc  gvar  init  uses  ds 
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push 

pop 

mov 

cs 

ds 

dx, offset 

gvar  filename 

mov 

ax, 3d00h 

int 

21h 

/open  the  file 

jc 

@@error 

/error  opening  file 

push 

ax 

/save  file  handle 

mov 

bx,  ax 

/file  handle  in  BX 

mov 

dx, offset 

gvar  ptr 

mov 

mov 

int 

ah, 3fh 
cx,  4 

21h 

/read  address  of  gvar  structure 

pop 

bx 

/file  handle  in  BX 

mov 

int 

ah, 3eh 

21h 

/close  the  file 

mov 

jmp 

ax,  -1 

short  @@done 

@@error 

@@done: 

xor 

ret 

ax,  ax 

endp 

gvar_ 

init 

This  macro  converts  the  Turbo  Pascal  string  in  the  ' from'  parameter  to  an 
ASCIIZ  string  in  the  'to'  parameter. 


macro  @make_asciiz  from,  to 


Ids 

si,  [sfroms] 

push 

cs 

pop 

es 

mov 

di, offset  &to& 

push 

cs 

push 

di 

call 

near  ptr  make  asciiz 

endm 


; these  values  are  pushed  now,  but  not 
;used  until  the  gvar  call  below 


;  Macro  calls  the  specified  routine. 

macro  (?gvar_call  routine 

les  bx, [cs:gvar_ptr] 

call  [dword  ptr  es:bx+gvars.&routine&] 

endm 


•/  Define  'varname'  with  value  'vardef'.  Returns  TRUE  if  successful,  FALSE 
;  if  the  global  variables  buffer  overflows. 

proc  set_gvar  uses  ds,  varname: far  ptr,  vardef: far  ptr 
@make_asciiz  varname,  glovar_name 
@make_asciiz  vardef,  glovar_def 
@gvar_call  set_var_ptr 
ret 

endp  set_gvar 


Return  definition  of  'varname'  in  'vardef'.  Returns  TRUE  if  successful, 
FALSE  if  'varname'  does  not  exist.  If  'varname'  does  not  exist,  'vardef' 
is  set  to  the  null  string. 


CAUTION:  if  the  returned  variable  definition  is  longer  than  255  characters, 
many  strange  and  not-so-wonderful  things  will  happen. 


@@loop: 


get_gvar  uses  ds,  varname: far  ptr,  vardef: far  ptr 
@make_asciiz  varname,  glovar_name 
push  cs 

mov  ax, offset  glovar_def 

push  ax 

@gvar_call  get_var_ptr 
push 


push 

pop 

mov 

les 

push 

inc 

xor 

cld 

lodsb 

or 


cs 

ds 

si, offset  glcvar_def 
di, [vardef] 
di 
di 

cx,  cx 


stosb 

inc 

jmp 

@@done:  pop 
mov 
pop 
ret 

endp  get_gvar 


al,al 

@@done 


short  @@loop 
di 

[byte  ptr  es:di] ,cl 


;get  the  variable 

;save  return  status 

;now  convert  definition  to  TP  string 


;save  to  set  length 
/start  string  at  second  byte 
;cx  is  byte  count 
/better  safe  than  sorry 


/bump  length 

/restore  pointer  to  length  byte 
/and  store  length  there 
/restore  return  status 


;  flush  all  global  variables 
proc  flush_gvars 

@gvar_call  flush_vars_ptr 
ret 

endp  flush_gvars 


convert  Turbo  Pascal  string  into  ASCIIZ  string. 

Call  with  ds:si  pointing  to  source  string  (TP  format) 
es:di  pointing  to  destination  buffer 
Make  sure  this  is  accessed  through  a  near  call. 


make  asciiz: 

lodsb 

/get  length 

mov 

cl,  al 

xor 

ch,  ch 

/in  CX 

cld 

rep 

movsb 

/move  the  string 

mov 

[byte  ptr  es:di],0 

/and  place  the  null  terminator 

retn 

end 

End  Listings 
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?ROGRMMAlHG  PARADIGMS 


Parkers 

Perceptions 


1  pulled  up  in  front  of  Dave  Parker’s 
house  with  a  trunkful  of  precon¬ 
ceptions,  the  consequence  of  know¬ 
ing  too  much  history. 

There  are  several  reasons  why  research 
in  neural  networks  went  quiescent  for 
over  a  decade,  but  the  most  effective 
single  cause  for  the  big  chill  was  surely 
the  book  Perceptrons.  In  that  book, 
Marvin  Minsky  and  Seymour  Papert 
proved  that  the  single-level  Perceptron 
model  could  not  compute  certain  basic 
functions  of  their  inputs.  Then  M&P 
went  on  to  speculate,  erroneously,  that 
research  in  multi-level  Perceptrons  and 
similar  models  would  be  equally  ster¬ 
ile.  Anyone  looking  for  funding  for  neu¬ 
ral  net  research  after  Perceptrons  came 
out  met  a  cold  response. 

There  are  also  several  reasons  why 
neural  network  research  has  been  heat¬ 
ing  up  of  late,  and  why  it  has  begun  to 
produce  some  success  stories,  but  the 
most  effective,  single  cause  may  have 
been  the  discovery  —  by  several  peo¬ 
ple  at  different  times  —  of  an  algorithm 
called  “back  propagation.”  “Backprop” 
shows  that  Minsky  and  Papert  were 
wrong  about  the  sterility  of  multi-level 
nets.  One  of  the  independent  discover¬ 
ers  of  this  algorithm  is  Dave  Parker.  A 
lot  of  money  is  now  flowing  into  neu¬ 
ral  net  research  and  development,  and 
Parker  is  one  of  the  people  who  turned 
the  faucet  back  on. 


Michael  Swaine 


None  of  that  money  is  flowing  in 
Parker’s  direction.  Today,  he  works  out 
of  his  modest  Silicon  Valley  home,  run¬ 
ning  a  small  graphics  software  com¬ 
pany.  His  company,  Acrobits,  hasn’t 
made  much  of  a  splash  yet,  although 
it’s  a  young  company  and  it  seems  to 
have  a  good  product.  My  preconcep¬ 
tions  said  that  Parker  wasn’t  profiting 
from  the  current  interest  in  neural  net¬ 


works  —  either  financially  or  in  pres¬ 
tige  —  as  much  as  others  were  who 
had  made  less  significant  contributions 
to  the  field.  My  preconceptions  said  that 
a  discoverer  of  the  back-propagation 
algorithm,  who  was  now  writing  graph¬ 
ics  software  for  PCs,  had  reason  to  be, 
if  not  bitter,  at  least  a  little  cynical. 

Parker  threw  a  bucket  of  clarity  on 
my  preconceptions.  When  I  gently  prod¬ 
ded  him  about  why  he  wasn’t  working 
in  neural  nets,  he  explained  patiently 
that,  fundamentally,  this  hot  new  re¬ 
search  area  involved  nothing  more  earth- 
shaking  than  some  parallel  implemen¬ 
tations  of  familiar  minimization  algo¬ 
rithms.  As  for  the  value  of  his  own 
back-propagation  algorithm,  the  day 
is  past,  he  explained,  when  you  could 
make  a  living  selling  an  algorithm.  Of 
course,  some  people  in  neural  nets  are 
making  a  very  good  living.  But  Parker 
doesn’t  seem  to  care  one  way  or  the 
other.  He  enjoys  what  he’s  doing  — 
programming,  running  his  own  busi¬ 
ness,  satisfying  customers  rather  than 
grantfunders  —  and  likes  the  feeling  that 
he’s  in  control  of  where  his  money  is 
coming  from.  He  continues  to  track 
research  and  developments  in  neural 
networks,  but  his  own  present  involve¬ 
ment  in  the  area  is  limited  to  occa¬ 
sional  lectures  and  classes,  where  his 
emphasis  is  on  demystifying  the  com¬ 
plex  of  algorithms,  architectures,  and 
ideas  that  are  collectively  called  neural 
networks. 

After  I  met  Dave’s  wife,  who  is  build¬ 
ing  a  laser  in  the  garage,  and  their  two 
children,  one  walking,  one  crawling, 
we  went  into  the  office,  which  the  con¬ 
tractor  no  doubt  thought  was  a  spare 
bedroom.  Here  Parker  started  pulling 
out  neural  net  materials  for  me:  arti¬ 
cles,  transparencies,  a  listing  of  a  Turbo 
Pascal  program  demonstrating  back 
propagation.  Since  Parker  hasn’t  worked 
in  the  area  in  two  years,  the  neural  nets 
shelf  of  his  bookcase  was  a  disorgan¬ 


ized  heap  of  papers  and  journals.  It 
reminded  me  of  the  confusing  state  of 
the  literature  on  neural  nets,  and  I  men¬ 
tioned  this  as  we  put  cups  of  instant 
coffee  into  the  microwave. 

Parker’s  response  was  to  give  me  a 
dose  of  demystification. 

Parker:  It  is  confusing.  People  may 
make  up  new  names  and  use  all  kinds 
of  jargon.  There  are  whole  strains  of 
neural  networks  with  their  own  jargon. 
Like  Brain  State  in  a  Box:  This  is  a  kind 
of  parallel  steepest  descent,  but  it  has 
its  own  jargon  because  it  was  devel¬ 
oped  at  one  university  and  everybody 
there  talks  the  same.  You  read  the  lit¬ 
erature  and  you  think:  How  does  this 
relate  to  anything  else? 

Swaine:  Is  there  some  way  to  keep  vari¬ 
ous  models  straight? 

Parker:  Yes.  It’s  very  simple  if  you  view 
everything  as  a  parallel  implementation 
of  a  minimization  algorithm.  Learning 
can  be  viewed  as  a  minimization  prob¬ 
lem,  so  you  just  ask,  What  is  the  minimi¬ 
zation  algorithm  being  implemented? 

Swaine:  I  see.  The  whole  point  of  neu¬ 
ral  nets  is  that  they  learn,  so  you  can 
sort  out  the  different  models  by  asking 
how  they  learn.  Let’s  try  it.  Hopfield  Net. 

Parker:  OK.  You  ask,  What  minimiza¬ 
tion  algorithm  does  it  implement?  The 
answer  is,  none.  A  Hopfield  Net  doesn’t 
learn.  Hopfield  nets  are  useful;  they 
can  tell  us  some  things  about  the  capa¬ 
bilities  of  neural  nets,  but  they  don’t 
learn  anything. 

Swaine:  That  was  easy.  Boltzmann 
Machine. 

Parker:  A  Boltzmann  Machine  can 
learn.  Since  it  learns,  a  Boltzmann  Ma¬ 
chine  is  a  (parallel)  implementation  of 
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some  sort  of  minimization  algorithm. 
The  question  is,  what  algorithm?  [He 
picks  up  a  pile  of  paper  from  a  desk, 
drafts  for  an  Acrobits  ad,  turns  them 
over,  and  begins  drawing  on  the  back 
of  the  top  sheet.]  The  simplest  way  to 
see  it  is  to  look  at  the  one-dimensional 
case.  Plot  all  the  weights  on  one  axis, 
and  performance  on  the  other.  [He 
draws  two  axes  and  a  sinusoidal  curve, 
with  two  dips,  one  shallow  and  one 
deep.]  The  weights  are  just  all  of  the 
adjustable  parameters  in  the  network; 
in  the  brain,  these  correspond  to  per¬ 
meabilities  and  whatnot.  You’re  plot¬ 
ting  everything  you  can  adjust  versus 
how  well  your  brain  —  or  your  neural 
network  —  does. 

Swaine:  So  the  algorithm  is  trying  to 
find  the  set  of  weights  that  minimizes 
the  performance  measure —  which  is 
probably  something  like  number  of  er¬ 
rors,  or  distance  from  a  goal,  since  it's 
something  we  want  to  minimize. 

Parker:  Right.  One  very  crude  algo¬ 
rithm  is  to  pick  a  random  set  of  weights, 
see  how  you  do,  remember  the  set,  then 
pick  another  random  set  of  weights.  If 
this  set  is  better,  remember  it;  if  it’s 
worse,  forget  it.  And  one  way  of  imple¬ 
menting  the  randomization  is  to  add 
noise  to  the  weights  you’ve  chosen. 

Swaine:  I’ve  read  that  the  adding  of 
noise  is  called  simulated  annealing,  a 
reference  to  a  process  in  metallurgy.  Is 
this  a  good  algorithm? 

Parker:  Well,  it's  been  proven  that  if 
the  distribution  of  the  noise  slowly  gets 
smaller,  the  probability  will  go  to  one 
that  you  will  find  the  global  minimum. 
[He  points  to  the  deep  dip  in  the  curve.] 
It  takes  a  long  time,  though.  This  is  just 
a  random  search,  so  a  Boltzmann  Ma¬ 
chine,  if  you  look  at  it  as  a  minimiza¬ 
tion  algorithm,  is  a  parallel  implemen¬ 
tation  of  a  random  search. 

Swaine:  Which  is  about  as  crude  as 
you  can  get. 

Parker:  But  it  has  the  nice  property 
that  if  the  noise  you  add  gets  less  and 
less  noisy,  the  probability  goes  to  one 
that  you’ll  find  the  global  minimum. 
The  idea  is  that  when  you  first  start, 
you  search  all  over  the  surface,  and 
then  when  you  narrow  down  to  a  cer¬ 
tain  area  you  gradually  add  less  and 
less  noise  because  the  probability  is 
higher  that  you’re  [near  the  global  mini¬ 
mum], 

Swaine:  Here's  an  easy  one:  Back  propa¬ 
gation. 


Parker:  Back  propagation  is  “parallel 
steepest  descent.”  Steepest  descent  is 
a  well-known  algorithm.  Rather  than 
picking  a  random  place,  you  just  keep 
going  downhill.  That  won’t  necessarily 
get  you  out  of  a  local  minimum.  [He 
points  to  the  shallow  dip  in  the  curve.] 
But  there  are  ways  around  that. 

Swaine:  I’d  like  to  hear  about  the  ways 
around. 

Parker:  Oh,  that’s  a  neat  one.  [He  pulls 
out  another  piece  of  paper  and  re¬ 
draws  the  graph,  this  time  with  a  di¬ 
agonal  line  representing  a  third  dimen¬ 
sion  at  right  angles  to  the  performance 
and  weight  dimensions.]  I  should  give 
credit  for  this:  This  picture  was  first 
drawn  for  me  by  mathematician  Dan 
Asimov.  This  third  dimension  repre¬ 
sents  the  inputs  to  the  system,  the  things 
you  have  no  control  over.  For  instance, 
in  your  brain  you  supposedly  have  con¬ 
trol  over  protein  levels  and  that  kind 
of  stuff,  but  you  have  no  control  over 
the  fact  that  a  car  is  bearing  down  on 
you.  The  inputs  are  things  that  you 
have  no  control  over  during  the  learn¬ 
ing  process,  the  data  that  you’re  getting 
from  the  external  world;  the  weights 
are  the  stuff  that’s  inside  you;  and  the 
performance  is  [the  output]  that  we 
measure.  In  any  particular  task  you’re 
working  on  you’re  only  in  a  small  area 
of  all  the  possible  inputs  the  system 
could  be  getting.  There  are  entirely 
different  inputs  for,  say,  scuba  diving, 
versus  learning  physics.  So  if  you’re 
studying  physics,  as  my  wife  is,  you 
can  look  at  the  performance  surface  in 
that  narrow  band  [of  inputs].  Now  if 
you’re  studying  physics  and  using  a 
steepest  descent  algorithm  and  you’re 
here  [he  points  to  the  shallow  dip  in 
the  curve],  you’re  in  big  trouble,  be¬ 
cause  you’re  always  going  to  be  trying 
to  go  downhill,  which  will  always  take 
you  to  the  local  minimum,  and  you’re 
never  going  to  get  over  the  hump. 
You’re  stuck  in  a  rut.  There’s  a  human 
analogy:  People  are  often  said  to  be 
stuck  in  a  rut,  doing  a  lot  of  work  but 
not  getting  anywhere.  Now,  what  a 
human  will  often  find  helpful  in  that 
situation  is  to  go  and  do  something 
different  for  a  while. 

Swaine:  Get  up  and  go  for  a  walk. 

Parker:  Yeah,  go  for  a  walk,  play  ten¬ 
nis,  go  hiking.  .  .  .  And  what  they’re 
doing  is  going  to  a  different  subspace 
of  their  inputs.  And  there  the  perform¬ 
ance  surface  may  look  radically  differ¬ 
ent:  You  don’t  expect  that  a  tennis  pro, 
just  by  playing  tennis  all  the  time,  will 
become  a  great  physicist,  or  vice  versa. 


So  what  happens  when  the  physicist 
goes  off  and  plays  tennis,  since  the 
optimum  tennis  weights  are  not  the 
optimum  physics  weights,  is  that  the 
weights  get  moved  in  some  direction. 
And  if  the  tasks  are  uncorrelated,  that 
direction  will  be  random.  So  you  go  off 
and  do  something  different  and  when 
you  come  back  to  your  original  task,  if 
you’re  lucky,  you’ll  be  working  on  it 
for  a  while  and  you’ll  say,  Hey,  why 
didn’t  I  think  of  that  before? 

Swaine:  So  you  adjust  the  inputs,  and 
the  weights  are  adjusted  as  a  conse¬ 
quence,  rather  than  directly  tweaking 
the  weights  randomly,  as  the  Boltzmann 
Machine  does. 

Parker:  By  exploring  different  parts 
of  your  input  space  you  can  give  your 
weights  random  pushes  in  different  di¬ 
rections  and  hopefully  be  able  to  find 
the  global  minimum. 

Swaine:  Why  is  that  approach  better 
than  a  Boltzmann  Machine? 

Parker:  They’re  good  at  different 
things.  If  you  have  access  to  the  weights, 
and  all  you’re  doing  is  learning  physics 
or  doing  circuit  board  layout,  it  is  much 
quicker  to  just  kick  all  the  weights  ran¬ 
domly,  stay  in  the  task  subspace,  do  a 
Boltzmann  Machine  followed  by  steep¬ 
est  descent,  and  repeat.  But  people 
don’t  have  access  directly  to  their 
weights,  so  rather  than  kicking  the 
weights  directly,  you  can  go  to  an  un¬ 
correlated  subspace  of  your  inputs,  and 
then  come  back  to  work  on  your  task 
again.  It’s  a  slower  process,  but  you 
don’t  need  access  to  your  weights. 

Swaine:  We ’ve  all  had  that  experience 
of  getting  up  from  the  keyboard  when 
we  ’re  stuck  on  a  problem  and  going  off 
to  do  something  seemingly  completely 
unrelated,  then  finding  when  we  come 
back  to  the  problem  that  the  solution  is 
suddenly  obvious.  Some  people  would 
claim,  I  think,  that  the  intervening  ac¬ 
tivity  is  not  really  uncorrelated,  that 
there  is  some  deep  connection  between 
this  particular  physics  problem  and, 
say,  tennis. 

Parker:  And  when  it  works,  they’d  be 
right.  [It  would  be  a  great  aid  to  teach¬ 
ing  physics]  if  you  knew  that,  when 
you  were  in  the  physics  subspace  and 
were  at  a  certain  local  minimum,  a 
good  thing  to  do  would  be  to  go  play 
the  harpsichord.  But  we  don’t  gener¬ 
ally  know  that.  [But  that’s  not  the  only 
advantage  of  this  approach  over  the 
Boltzmann  Machine.]  To  do  the 
Boltzmann  Machine  you  need  to  keep 
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around  two  sets  of  weights:  Your  best 
and  the  current.  Using  this  approach 
you  only  need  your  current  ones,  but 
it  does  take  longer. 

Swaine:  One  begins  to  get  the  message 
from  all  these  algorithms  that  learning 
simply  takes  a  long  time. 

Parker:  Teaching  people  takes  years 
and  years.  So  anyway,  even  if  you  use 
parallel  steepest  descent  —  which  isn’t 
guaranteed  to  find  the  global  mini¬ 
mum  —  you  can  still  find  it,  by  doing 
this  kind  of  thing. 

Swaine:  So  what’s  the  most  powerful 
neural  net  model?  What’s  the  best  we 
can  do  today? 

Parker:  Is  there  a  more  powerful  mini¬ 
mization  algorithm  than  steepest  de¬ 
scent?  Yes,  there  is.  It’s  been  around 
for  a  long  time,  and  it’s  called  “New¬ 
ton’s  Method.”  Steepest  descent  is  based 
on  the  first  derivative  of  the  perform¬ 
ance  surface:  It  looks  at  the  first  deriva¬ 
tive  and  tries  to  follow  it.  Newton’s 
Method  uses  the  second  derivative,  so 
it’s  based  on  more  information. 

Swaine:  How  does  that  work? 

Parker:  A  handy  analogy  is  from  ski¬ 
ing.  Imagine  that  you’re  on  a  steep 
overhang  and  the  obvious  way  to  get 
back  to  the  lodge  is  to  go  straight  down 
the  steep  slope  to  the  valley  and  then 
down  the  gentle  slope  of  the  valley  to 
the  lodge.  Steepest  descent  is  like  equiva¬ 
lent  to  doing  nothing  but  sitting  on 
your  skis.  You  go  very  quickly  down 
the  slope  to  the  valley,  but  then  you 
get  to  the  valley  and  you  slow  down, 
and  it  gets  very  inefficient.  What  expert 
skiers  will  do  is  cut  across  the  slope, 
by  putting  pressure  on  one  of  their 
skis,  and  that’s  exactly  what  Newton’s 
Method  does.  The  parameters  that  con¬ 
trol  Newton’s  Method  are  equivalent 
to  the  pressure  you  put  on  your  ski.  If 
you  just  sit  on  your  skis,  your  speed  is 
proportional  to  the  steepness  of  the 
slope,  which  is  true  of  steepest  de¬ 
scent.  But  with  Newton’s  Method,  you 
move  at  constant  velocity. 

Swaine:  But  at  some  cost.  What  does 
using  Newton ’s  Method  cost  you? 

Parker:  Newton’s  Method  is  trickier 
to  implement  and  more  computation¬ 
ally  intensive. 

Swaine:  It  sounds  like  there  is  no  one 
best  algorithm for  all  possible  situations, 
which  I  suppose  is  not  surprising. 


Parker:  Newton’s  Method  is  a  superior 
algorithm,  so  if  you  can  afford  the  com¬ 
putational  overhead,  it  pays  off  for  you . 

Swaine:  Where  exactly  does  it  pay  off? 

Parker:  One  way  in  which  it  pays  off 
is  this.  Steepest  descent  takes  a  curved 
path,  and  Newton’s  Method  takes  a 
straight  path.  The  best  path  is  the  straight 
path. 

Steepest  descent  is 
based  on  the  first 
derivative  of  the 
performance  surface:  It 
looks  at  the  first 
derivative  and  tries  to 
follow  it 


Swaine:  Obviously.  But  you  mean  some¬ 
thing  more  than  the  fact  that  a  straight 
line  is  the  shortest  distance  between 
two  points. 

Parker:  Right.  The  disadvantage  of  the 
curved  path  is,  if  you  follow  a  curved 
path  and  then  stop  learning  halfway 
through,  you  may  be  no  closer  to  where 
you  want  to  go,  and  you’ve  moved 
away  from  where  you  used  to  be.  So 
you’ve  forgotten  old  but  useful  infor¬ 
mation  without  having  learned  very 
much  new  information.  Whereas  if  you 
follow  a  straight  line  and  stop,  you’re 
closer  to  where  you  want  to  go  and  as 
close  to  where  you  used  to  be  as  you 
can  be. 

Swaine:  So  if  you  can  afford  it,  New¬ 
ton  's  Method  is  best.  Sort  of  the  high- 
priced  algorithm.  It  occurs  to  me  that, 
even  if  we  can ’t  pick  an  absolute  best 
algorithm,  nature  has  already  made  a 
choice.  Too  bad  we  don’t  know  — •  yet — 
what  algorithm  nature  picked  for  hu¬ 
man  learning. 

Parker:  Yes;  you  can  think  of  almost 
any  example  of  human  learning  as  mini¬ 
mization.  If  you  accept  the  hypothesis 
that  learning  is  exactly  minimization, 
then  people  must  be  implementing 


some  minimization  algorithm,  and  since 
Newton’s  Method  is  the  more  powerful 
of  the  two,  one  would  hope  that  it  was 
a  form  of  Newton’s  Method. 

Swaine:  Really?  I  was  finding  your 
description  of  modified  backprop  pretty 
convincing  in  terms  of  my  experience 
in  learning  things. 

Parker:  I  would  think  it  was  a  back- 
propagation  form  of  Newton’s  Method. 

Swaine:  Nature  has  probably  had  time 
to  try  out  many  algorithms.  But  if  New¬ 
ton  ’s  Method  is  the  most  powerful  mini¬ 
mization  algorithm  we  know,  and  if 
it’s  actually  feasible  to  implement  in  a 
human  brain.  .  .  . 

Parker:  The  performance  difference 
is  great  enough  that  the  other  guys 
would  have  died  out. 

The  listing  that  accompanies  this 
month’s  column  is  Parker’s  demonstra¬ 
tion  of  back  propagation,  written  in 
Turbo  Pascal.  It’s  not  intended  to  be 
an  efficient  implementation,  and  it  won’t 
teach  you  much  if  you  just  run  it  and 
examine  the  output.  The  code,  though, 
is  well  documented  and  is  intended  to 
be  read.  Here  are  some  aids  to  reading 
the  listing. 

The  program  simulates  a  neural  net 
(simulates  because  it  is  purely  software 
and  is  not  a  parallel  implementation) 
of  four  cells;  four  neurons.  Each  neu¬ 
ron  is  a  simple  computational  unit.  It 
has  two  input  channels,  a  channel  for 
receiving  the  error  signal  and  one  out¬ 
put  channel.  The  inputs  are  modified 
by  a  weight  associated  with  each  input. 
The  neuron  computes  its  output  based 
on  the  inputs  and  the  weights;  in  this 
implementation  the  computation  is  a 
sigmoid  function,  but  other  computa¬ 
tions  are  possible. 

The  neurons  are  connected  in  lay¬ 
ers,  with  the  outputs  of  neurons  in  one 
layer  feeding  the  inputs  of  neurons  in 
the  next.  The  original  inputs  are  treated 
as  the  outputs  of  a  nonexistent  O-th 
level,  and  the  outputs  of  the  top  level 
are  compared  with  the  desired  outputs 
to  generate  error  signals.  The  error  sig¬ 
nals  propagate  back  through  the  net, 
causing  the  weights  in  the  neurons  to 
be  adjusted.  The  idea  is  that  “good” 
paths  through  the  net  will  get  weighted 
more  and  more  heavily  and  “bad”  paths 
will  get  lower  and  lower  weights,  so 
that  eventually  only  the  “good”  paths 
will  be  taken. 

The  demo  neural  net  (Listing  One, 
page  146)  learns  a  simple  task.  Given 
one  of  four  input  patterns,  (0,0),  (1,0), 
(0,1),  (1,1),  the  net  is  to  produce  the 
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appropriate  one  of  the  possible  output 
patterns,  (0,0),  (0,1),  (0,1),  (1,1).  De¬ 
scribed  in  this  way,  it’s  a  pretty  mean¬ 
ingless  task,  but  it  makes  a  little  more 
sense  when  expressed  in  functional 
terms:  The  two  values  in  the  output 
pattern  are  respectively  the  logical  AND 
and  the  logical  OR  of  the  two  input 
values. 

So  the  operation  of  the  program  is: 

•  Compute  the  inputs  and  correspond¬ 
ing  outputs 

•  Propagate  the  inputs  forward  through 
the  net 

•  Compare  the  actual  output  to  the  de¬ 
sired  output  and  compute  the  error 

•  Propagate  the  error  signals  back 
through  the  net  and  update  the 

•  Weights,  and  check  to  see  if  the  clas¬ 
sification  has  been  learned. 

The  last  step  involves  examining  the 
sum  of  squares  of  the  error  signals  and 
testing  for  convergence.  The  input  and 
output  values  are  not  really  Os  and  Is 
as  stated  above,  but  numbers  close  to 
0  and  1,  and  the  program  quits  when 
the  classification  is  learned  to  within  a 
preset  degree  of  tolerance  —  when  it 
gets  close  enough  to  Os  and  Is. 

Training  a  neural  net  of  this  sort  re¬ 
quires  that  desired  output  for  each  pass 
be  known,  so  that  the  error  signals  can 
propagate  back  through  the  net  to  cause 
the  weights  to  be  adjusted.  That’s  the 
back  propagation,  and  what  the  net  is 
learning  to  do  is  to  minimize  these 
error  signals.  In  this  demo  program, 
the  computation  of  error  is  handled 
automatically  by  having  an  array  of  the 
desired  outputs  for  each  set  of  inputs. 
That  might  make  the  whole  enterprise 
seem  pointless,  and  in  the  case  of  the 
demo,  it  is:  If  you  examine  the  routine 
that  computes  the  inputs  and  desired 
outputs,  you’ll  see  that  we  have  al¬ 
ready  calculated  the  right  answers  be¬ 
fore  the  network  even  started  running. 

In  a  real  neural  net  implementation, 
computing  the  error  could  be  more 
complicated,  and  in  some  cases  might 
require  that  a  person  evaluate  the  re¬ 
sponse.  Or,  more  interestingly,  we  might 
be  able  to  write  a  routine  that  recog¬ 
nizes  and  characterizes  errors  when  it 
sees  them,  even  though  we  couldn’t 
write  an  algorithm  to  produce  correct 
output.  In  chess,  for  example,  we  can’t 
yet  write  a  program  that  plays  per¬ 
fectly,  but  we  can  write  programs  that 


do  a  perfect  job  of  recognizing  check¬ 
mate,  and  we  can  implement  various 
position-evaluation  heuristics.  These  are 
cases  in  which  we  can  generate  error 
signals  to  train  the  net  even  though 
we  don’t  know  how  to  solve  the  prob¬ 
lem.  And  if  our  error  signals  are  good, 
and  if  our  algorithm  is  one  that  doesn’t 
get  stuck  in  a  rut,  our  network,  left  to 
run  uninterruptedly  and  to  learn  from 
its  mistakes,  will  eventually  learn  to 
play  perfect  chess. 

But  with  current  hardware,  probably 
not  in  our  lifetimes. 

Availability 

All  source  code  for  articles  in  this  issue 
is  available  on  a  single  disk.  To  order, 
send  $14.95  (Calif,  residents  add  sales 
tax)  to  Dr.  Dobb's Journal,  501  Galves¬ 
ton  Dr.,  Redwood  City,  CA  94063,  or 
call  800-356-2002  (from  inside  Calif.) 
or  800-533-4372  (from  outside  Calif.). 
Please  specify  the  issue  number  and 
format  (MS-DOS,  Macintosh,  Kaypro). 
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More  C++  and  a 
Step  Up  to  ANSI  C 


Our  collection  of  C++  tools  be¬ 
gan  last  month  with  a  simple 
window  manager.  The  first  class 
we  built  was  a  Window  that 
pops  up  when  it  is  declared  from  within 
a  program  and  pops  down  when  it 
goes  out  of  scope.  The  Window  meth¬ 
ods  include  the  following: 

•  Overloaded  «  operators  that  add  a 
character,  a  line,  or  a  block  of  text  to 
the  Window 

•  Page  and  scroll  through  the  Window 
•  Hide  the  Window  and  restore  it  to  the 
screen 

•  Change  the  Window’s  display  colors 
and  default  tab  stops 
•  Position  and  read  the  Window’s  cursor 
•  Clear  text  from  the  entire  Window, 
from  the  current  cursor  position  to 
the  end  of  the  current  line,  and  to  the 
end  of  the  window 

The  Window  class  became  the  base 
class  for  three  simple  derived  classes, 
the  YesNo  window,  the  Notice  win¬ 
dow,  and  the  Error  window.  Those 
classes  illustrated  class  inheritance  as 
supported  by  C++.  This  month  we  will 
look  more  closely  at  inheritance  with 
a  popdown  menu  class  that  is  derived 
from  the  Window.  Then  we  will  intro¬ 
duce  a  string  data  type  that  resembles 
the  strings  of  Basic. 

Menu  Classes 

To  continue  our  exploration  of  C++, 
we  will  build  classes  that  implement 


Al  Stevens 


two  kinds  of  menus:  The  sliding  bar 
menu  similar  to  those  used  by  pro¬ 
grams  such  as  Lotus  1-2-3,  and  the 
popdown  menu  similar  to  the  ones 
that  SideKick  uses.  The  sliding  bar  menu 
class,  named  “SlideBar,”  is  its  own  in¬ 
dependent  class.  The  popdown  menu 
class,  called  “PopdownMenu,”  is  de¬ 
rived  from  the  Window  class.  These 
menus  are  similar  to  ones  we  devel¬ 


oped  in  traditional  C  last  year  for  the 
TWRP  and  SMALLCOM  projects. 

A  class  is  a  new  data  type,  described 
by  the  programmer  to  extend  the  lan¬ 
guage.  When  we  built  the  Window  and 
its  derived  classes,  we  effectively  added 
a  data  type.  With  that  addition,  our  C++ 
programs  can  have  chars,  ints,  longs, 
floats,  doubles,  structs,  unions,  Win¬ 
dows,  Notices,  Errors,  and  YesNos.  Next 
we  will  add  SlideBars  and  Popdown- 
Menus.  A  derived  class  inherits  all  the 
characteristics  of  the  base  class  from 
which  it  is  derived  and  adds  its  own 
private  and  public  parts. 

Our  SlideBar  and  PopdownMenu 
classes  perform  operations  similar  to 
one  another  but  with  different  menu 
formats.  When  you  declare  either  class, 
a  menu  is  created  and  displayed,  and 
the  user  is  prompted  to  make  a  selec¬ 
tion.  Depending  on  the  user’s  selec¬ 
tion,  an  applications  function  is  selected 
from  ones  that  you  associate  with  the 
selections  when  you  declare  the  class. 
Let’s  look  first  at  the  SlideBar  class. 

Sliding  Bar  Menus  —  When  you 
declare  a  SlideBar  variable,  you  specify 
the  screen  line  where  the  menu  will 
appear,  the  text  of  the  selections,  the 
first  selection  to  be  highlighted  by  a 
selection  cursor,  and  pointers  to  the 
functions  associated  with  the  selections. 
As  soon  as  you  declare  the  SlideBar, 
its  constructor  function  displays  the 
menu  and  prompts  the  user  to  make  a 
selection.  The  user  can  move  the  selec¬ 
tion  cursor  back  and  forth  by  pressing 
the  right  and  left  arrow  keys  and  can 
make  a  selection  by  pressing  the  Enter 
key  when  the  cursor  is  on  the  de¬ 
sired  selection.  The  user  can  also  make 
a  selection  by  pressing  the  first  letter 
of  the  selection’s  name.  This  conven¬ 
tion  requires  that  you  assign  selection 
names  with  unique  first  letters  when 
you  design  the  menu.  When  the  user 
makes  a  selection,  the  associated  func¬ 
tion  executes. 

When  you  declare  one  of  these  menu 
classes,  your  program  remains  in  the 
member  functions  and  in  the  applica¬ 


tions  functions  associated  with  selec¬ 
tions  until  the  constructor  function  re¬ 
turns.  The  constructor  function  calls 
the  private  dispatch  member  function 
to  manage  user  selections  and  dispatch 
your  applications  functions.  The  Slide- 
Bar  class  has  a  terminate  member  func¬ 
tion  that  the  applications  programs  call 
to  tell  the  dispatch  function  to  termi¬ 
nate  menu  processing.  The  statement 
in  your  program  that  follows  the  Slide- 
Bar  declaration  will  then  execute,  but 
the  menu  will  remain  visible  until  the 
SlideBar  goes  out  of  scope. 

A  dispatched  applications  function  can 
use  the  current_selection  member  func¬ 
tion  to  determine  which  vertical  selec¬ 
tion  on  the  menu  caused  its  dispatch. 

Pop  Down  Menus  —  Next  let’s  con¬ 
sider  the  PopdownMenu  class.  It  is  simi¬ 
lar  in  operation  to  the  SlideBar  class, 
but  the  menu  takes  the  form  of  a  win¬ 
dow  and  is,  therefore,  derived  from  the 
Window  class.  When  you  declare  the 
PopdownMenu,  you  specify  the  col¬ 
umn  and  row  coordinates  where  the 
upper  left  corner  of  the  PopdownMenu 
window  displays.  The  other  initializa¬ 
tion  parameters  are  the  same  as  those 
of  the  SlideBar  menu,  and  the  opera¬ 
tion  is  similar.  With  the  PopdownMenu, 
however,  the  user  moves  the  selection 
cursor  up  and  down  rather  than  to  the 
right  and  left. 

Besides  the  terminate  and  current_ 
selection  member  functions,  which 
work  like  those  of  the  SlideBar  class, 
the  PopdownMenu  class  includes  addi¬ 
tional  features.  A  PopdownMenu  can 
have  selections  that  are  selectively  dis¬ 
abled.  This  means  they  are  displayed 
but  not  available  for  selection.  They 
have  a  unique  color  scheme,  and  the 
selection  cursor  passes  over  them  when 
the  user  moves  it  up  and  down.  The 
disable_selection  and  enable_selection 
public  member  functions  allow  the  ap¬ 
plications  code  to  disable  and  enable 
a  specified  menu  selection. 

PopdownMenus  also  support  toggle 
selections,  ones  that  change  a  binary 
state  switch  but  do  not  have  associated 
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applications  member  functions  to  dis¬ 
patch.  They  display  a  check  mark  next 
to  their  name  if  the  toggle  is  on  and 
no  check  mark  if  the  toggle  is  off.  The 
test_toggle  public  member  function  al¬ 
lows  an  application  to  test  the  current 
value  of  a  selection’s  toggle. 

The  definitions  of  the  SlideBar  and 
PopdownMenu  classes  appear  in  List¬ 
ing  One  (page  148),  menus. h.  A  pro¬ 
gram  that  will  use  either  of  these  classes 
will  include  this  file.  Along  with  the 
class  definitions  are  definitions  of  the 
color  schemes  for  menus.  The  Window 
class  from  last  month  provides  for  the 
initialization  and  changing  of  a  Win¬ 
dow’s  colors.  The  menu  classes,  how¬ 
ever,  assume  that  a  program  uses  a 
consistent  color  scheme  for  all  menus 
and  does  not  require  you  to  identify 
the  menu  colors  every  time  you  de¬ 
clare  a  menu.  Listing  Two  (page  148) 
is  menus. c,  the  code  that  implements 
the  classes.  To  use  them,  you  must  link 
your  program  with  the  object  files  that 
you  compile  from  these  files.  To  use 
the  PopdownMenu  class,  you  will  need 
the  window. h  and  window. c  files  from 
last  month.  All  the  programs  in  this  and 
last  month’s  columns  compile  with  the 
Zortech  C++  compiler,  Version  1.07. 

Listings  Three  and  Four  (pages  150 


and  154,  respectively)  are  demoslid.c 
and  demopop.c.  These  programs  dem¬ 
onstrate  the  use  of  the  two  menu  classes. 
Demoslid.c  defines  a  SlideBar  menu 
with  four  selections.  Each  of  the  selec¬ 
tions  executes  a  function  in  demoslid.c. 
The  first  three  of  these  simulated  appli¬ 
cations  functions  declares  a  Window 
that  the  function  uses  to  identify  itself. 
After  the  user  presses  a  key,  the  func¬ 
tion  returns.  The  fourth  function  is  the 
Quit  selection.  It  uses  a  YesNo  class 
(defined  in  window,  h  and  discussed 
last  month)  to  ask  the  user  to  verify  the 
quit  command.  If  the  user  says  “yes,” 
the  function  calls  the  terminate  mem¬ 
ber  function  to  tell  the  menu  to  quit. 

Demopop.c  is  similar  to  demoslid.c, 
but  it  demonstrates  the  additional  fea¬ 
tures  available  in  the  PopdownMenu 
class.  It  declares  a  PopdownMenu  with 
five  selections.  These  selections  behave 
in  ways  that  suggest  the  File  menu  of 
an  editor  program.  There  are  selections 
to  load  a  file,  save  a  file,  and  declare  a 
new  file.  There  is  a  toggle  selection 
named  Option.  The  last  selection  is  the 
Quit  selection. 

The  Save  selection  is  initially  set  to 
be  a  disabled  selection.  The  minus  sign 
in  the  text  name  “-Save”  identifies  it 
as  such.  Whenever  you  use  the  Load 


or  New  selections,  their  dispatched  func¬ 
tions  call  the  enable_selection  public 
member  function  to  enable  the  Save 
selection.  When  you  then  use  the  Save 
selection,  its  dispatched  function  calls 
the  disable_selection  function  to  dis¬ 
able  itself. 

The  Option  selection  is  a  toggle.  It 
is  implicitly  defined  as  such  by  the 
NULL  function  pointer  that  the  de¬ 
mopop.c  program  specified  for  the  Op¬ 
tion  selection's  associated  applications 
function.  When  the  user  chooses  the 
Option  selection,  the  class  automati¬ 
cally  inverts  the  toggle  setting.  A  toggle 
setting  is  represented  by  the  appear¬ 
ance  or  absence  of  the  check  mark 
symbol  (’\xfb’)  as  the  last  character  of 
the  selection’s  name.  We  use  the  Op¬ 
tion  toggle  in  the  Quit  function  to  see 
if  we  need  to  use  a  YesNo  class  to 
verify  the  Quit  request.  If  the  toggle  is 
on,  we  do  not  ask  the  user  for  verifica¬ 
tion.  This  usage  serves  to  illustrate  the 
mechanics  of  toggle  selections. 

By  combining  the  SlideBar  class  with 
a  series  of  PopdownMenu  classes,  you 
could  build  a  menu  system  where  the 
sliding  bar  is  at  the  top  of  the  screen 
with  popdown  menus  under  each  slid¬ 
ing  bar  selection.  This  is  the  kind  of 
menu  system  used  by  many  programs. 


In  my  development  of  the  two  menu 
classes,  I  attempted  to  go  the  next  logi¬ 
cal  step  and  develop  those  traditional 
sliding  bar/popdown  menus.  The  wall 
I  ran  into  was  either  the  limit  of  Zortech 
C++  or  my  own  inexperience  with  the 
C++  language.  A  two-dimensional  menu 
driver  needs  pointers  to  arrays  of  func¬ 
tion  pointers,  or  something  similar.  I 
was  not  able  to  get  these  constructs 
working  within  the  realm  of  the  new 
operator  or  as  parameters  to  overloaded 
constructor  functions.  It  is  also  not  clear 
to  me  how  the  variable  argument  list 
feature  of  C++  and  ANSI  C  fit  into  the 
overloaded  function  construct.  These 
issues  are  typical  of  the  ones  you  and 
I  will  encounter  as  we  try  to  use  C++ 
in  ways  that  our  imaginations  move  us, 
and,  when  and  if  I  solve  them,  I  will 
share  the  solutions. 

The  String  Class 

When  I  migrated  from  Basic  to  C,  I 
mourned  the  loss  of  the  string  variable. 
K&R  reassured  me  that  character  arrays 
and  standard  functions  using  character 
pointers  would,  with  care,  serve  the 
same  purpose,  but  I  missed  the  old 
way,  wanting  ever  since  to  be  able  to 
say  this  in  a  C  program: 


if  (username  ==  “Wynton”) 

username  =  username  +  “  Marsalis”; 

or  better  yet: 

username  +=  “  Marsalis”; 

With  C,  we  must  use  the  strcat  function 
to  perform  such  a  concatenation,  and 
the  receiving  string  must  be  long  enough 
to  receive  the  added  value.  There  are 
other  useful  string  operations  in  Basic, 
and  I’ve  been  wanting  them  in  C  for  a 
long  time. 

Well,  want  no  more.  C++  brings  that 
capability  to  the  C  language.  It  does, 
that  is,  if  you  roll  your  own  string  class, 
and  that  is  just  what  we  are  about  to  do. 

Listing  Five,  page  154,  is  strings. h, 
the  header  file  that  describes  the  new 
class,  named  “string.”  Listing  Six,  page 
156,  is  strings. c,  the  code  that  imple¬ 
ments  the  string  class. 

The  string  has  one  private  part,  a 
character  pointer.  When  you  declare 
the  string,  the  constructor  function  in¬ 
itializes  the  pointer.  All  operations  on 
the  string  use  this  pointer.  There  are 
four  constructor  functions  for  the  string 
class,  supporting  the  four  different  ways 
you  can  declare  a  string  and  illustrating 
the  C++  technique  for  overloading  con¬ 
structor  functions. 


C++  lets  you  overload  functions.  This 
means  that  several  functions  can  have 
the  same  name  but  different  parameter 
types.  The  language  translator  decides 
which  function  you  are  calling  based 
on  the  parameters  you  are  passing.  (If 
C  had  this  feature,  we  would  not  need 
a  strcpy  function  and  a  strncpy  func¬ 
tion,  for  example.  One  function  could 
handle  both  operations.)  Function  over¬ 
loading  does,  however,  mandate  the 
use  of  prototypes,  and  that  is  a  good 
requirement. 

The  four  ways  of  declaring  a  string 
are  shown  here: 

string  namel;  // null  string 

string  name2(“George”); 

//  character  pointer 
string  name3(name2);  //  another  string 
string  name4(80);  //  length 

Each  of  these  declarations  will  estab¬ 
lish  a  string  with  a  pointer  to  the  appro¬ 
priate  character  array.  The  namel  string 
will  contain  a  pointer  to  a  null  string. 
The  other  three  strings  will  contain  point¬ 
ers  to  character  arrays.  All  four  con¬ 
structors  use  string  space  taken  from 
the  free  store  (the  C++  heap)  with  the 
C++  new  operator.  Each  constructor 
makes  a  new  copy  of  the  string  value 
rather  than  simply  pointing  to  the  in- 
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itializing  value.  The  name4  string  points 
to  an  array  of  81  characters  all  with  a 
zero  value. 

String  Assignments  —  Once  you  de¬ 
clare  a  string,  there  are  a  number  of 
operations  you  can  perform  on  it.  First 
let’s  consider  the  assignment  operator. 
Once  you  establish  a  string  variable, 
you  can  assign  either  a  character  array 
or  another  string  to  it  as  shown  here. 

string  oldstring;  //  declare  two  strings 
string  newstring; 
oldstring  =  “Hello,  Dolly”, 

//  assign  an  array 
newstring  =  oldstring;  //  assign  a  string 

These  two  assignments  are  achieved 
with  the  operator =  overloaded  func¬ 
tions  that  have  a  character  pointer  and 
a  string  as  their  parameters.  In  C++ 
you  can  overload  the  unary  and  bi¬ 
nary  C  operators  to  work  with  classes 
in  ways  you  design.  You  cannot 
change  the  way  the  operators  work 
with  standard  C  data  types,  you  can¬ 
not  create  operators  that  do  not  exist 
in  C,  you  cannot  use  unary  operators 
as  binary  ones,  and  so  forth.  Your  use 
of  operator  overloading  must  be  done 
in  ways  that  make  sense  to  the  lan¬ 
guage  translator’s  lexical  scan  and 
parser.  We’ll  look  at  more  operator  over¬ 
loading  later. 

The  stradr  Function  —  The  stradr 
public  member  function  returns  the  ad¬ 
dress  of  the  string.  It  is  defined  as  a 
const  char  *  function,  which  means 
that  it  returns  a  pointer  to  something 
that  cannot  be  modified.  The  intention 
here  is  to  prevent  an  applications  pro¬ 
gram  from  changing  the  value  of  a 
string  through  the  stradr  function.  All 
changes  to  strings  should  be  made  with 
the  string  operations  described  soon. 
This  intention  is  not  always  realized. 
Zortech  C++  does  not  disallow  you 
from  assigning  the  value  returned  from 
the  function  to  a  regular  character 
pointer.  It  does  prevent  you  from  using 
the  function  call  in  an  expression  that 
would  change  the  string.  For  example, 
the  following  code  is  OK  according  to 
Zortech: 

string  myname(“Joe”) 

char  *cp  =  myname.stradrC  ); 

*cp  =  ’M’; 

The  compiler  should  warn  you  that  the 
second  statement  is  assigning  a  pointer- 
to-constto  a  regular  pointer,  but  it  does 
not.  Experiments  with  Turbo  C  and 
Microsoft  C  reveal  that  they  do  issue 
such  warnings  (in  a  C  context,  of 
course).  See  the  ANSI  Corner  later  for 
more  discussion  on  this  circumstance 
as  it  relates  to  C,  not  C++. 

Zortech  will  issue  an  error  if  you  try 
this  code: 


string  mynameC'Joe”); 
*myname.stradr(  )  =  ’M’; 

The  right,  left,  and  mid  Functions  — 

The  string  class  includes  three  public 
member  functions  designed  to  emulate 
the  RIGHTS ,  LEFTS ,  and  MID$  sub¬ 
string  functions  of  Basic.  These  func¬ 
tions  return  pieces  of  strings  as  new 
strings.  For  example: 

string  name( “George  Kingfish  Stevens”); 
string  firstname; 
string  middlename; 
string  lastname; 
firstname  =  name.left(6); 
middlename  =  name.mid(8,  8); 
lastname  =  name.right(7); 

This  code  assigns  to  the  three  null  strings 
the  three  parts  of  the  originally  initial¬ 
ized  name. 

String  Concatenation  —  The  string 
class  includes  several  ways  that  you 
can  concatenate  strings.  Assume  that 
you  have  strings  named  newname, 
name  and  lastname.  These  are  the  ways 
that  you  can  concatenate  strings: 

newname  =  name  +  “Smith”; 
newname  =  name  +  lastname; 
name  =  name  +  “Smith”; 
name  =  name  +  lastname; 
name  +=  “Smith"; 
name  +=  lastname; 

String  concatenation  does  not  require 
you  to  assure  enough  space  for  the 
added  value.  String  sizes  grow  accord¬ 
ing  ter  their  needs. 

Relational  Operators 

Our  new  string  class  allows  us  to  make 
relational  tests  between  strings  and  be¬ 
tween  strings  and  character  arrays.  You 
can  make  the  following  tests: 

if  (name  ==  “Sam”) 
if  (name  <  othername) 

and  any  other  combination  of  two 
strings  or  one  string  and  a  character 
array  where  the  relational  operator  is 
one  of  these: 

==,  !=,  <,  >,  <=,  >= 

The  only  restriction  is  that  the  left  side 
of  the  test  must  be  a  string  class  rather 
than  an  array. 

String  Subscripts  —  You  can  use 

the  [  1  subscript  operators  to  read  the 
individual  character  values  of  a  string  in 
ways  similar  to  how  you  work  with  regu¬ 
lar  C  character  arrays.  For  example: 

string  name(“Otis”); 
char  ch  =  name[2]; 

The  ch  character  variable  will  receive 


the  T  from  the  string.  You  cannot,  how¬ 
ever,  do  this: 

name[2]  =  ’e’;  //  invalid  statement 

because  the  value  returned  by  the  over¬ 
loaded  [  ]  operator  is  not  a  C  lvalue. 


The  ANSI  C  draft 
standard  document  is 
not  exactly  fireside 
reading 


You  can,  however,  use  the  overloaded 
+  operator  to  form  an  lvalue.  The  follow¬ 
ing  operations  are  valid: 

ch  =  *(name+2); 

*(name+2)  =  ’e'; 

The  string  class  represents  what  I  be¬ 
lieve  to  be  the  real  potential  for  C++,  its 
ability  to  extend  the  C  language  with 
reusable,  generic  data  types.  Perhaps 
you  have  no  desire  to  make  C  look 
more  like  Basic  with  our  string  class, 
but  the  exercise  reveals  the  possibili¬ 
ties  that  class  definition  adds  to  the  C 
language. 

The  C++  language  is  still  without  the 
large  user  base  that  would  drive  us 
toward  standard  conventions.  The  ANSI 
C  committee  has  decided  not  to  under¬ 
take  the  standardization  of  C++.  There¬ 
fore,  not  until  Borland  and  Microsoft 
introduce  C++  compilers,  complete  with 
integrated  development  environments 
and  hot-shot  debuggers,  can  PC  devel¬ 
opers  get  serious  about  it.  We  can  only 
hope  that  it  happens  in  the  not-too- 
distant  future,  but  there  have  been  no 
announcements.  Until  that  time,  C++ 
is  still  a  wonderful  study  in  what  pro¬ 
gramming  ought  to  be,  and  I  encour¬ 
age  you  to  get  into  it. 

The  ANSI  Corner:  const  and  volatile 

The  ANSI  X3J11  committee  submitted 
their  draft  proposed  standard  for  the  C 
language  to  ANSI  for  approval  last 
spring,  but  some  snags  developed, 
mostly  procedural  or  bureaucratic. 
Those  should  be  cleared  up  soon, 
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and  a  true  ANSI  C  standard  should 
exist,  perhaps  by  the  time  you  read  this 
column. 

The  draft  standard  document  is  not 
exactly  fireside  reading.  Eventually  it 
will  be  the  final  authority  on  how  C 
should  work,  but  it  is  neither  a  tutorial 
text  nor  an  easily  understood  reference 
document.  Compiler  developers  will 
study  it  in  great  detail  trying  to  con¬ 
form.  We,  the  consumers,  must  trust 
our  compiler  writers  to  have  correctly 
interpreted  and  implemented  the  stan¬ 
dard  language. 

This  small  section  of  the  DDJ  "C 
Programming”  column  is  a  new  monthly 
addition  that  will  address  some  of  the 
features  that  the  ANSI  C  standard  adds 
to  the  C  language.  Most  of  these  features 
are  already  implemented  in  the  C  com¬ 
pilers  you  use  now  because  the  com¬ 
piler  writers  have  been  closely  following 
the  development  of  the  proposed  stan¬ 
dard.  Each  month  we  will  look  at  an¬ 
other  part  of  the  ANSI  standard. 

The  const  Type  Qualifier  —  A 
const  variable  is  one  that  your  program 
cannot  modify  with  an  assignment  or 
by  incrementing  or  decrementing.  You 
can  declare  a  variable  to  be  a  const  in 
one  of  these  ways: 

1.  const  intil; 

2.  int  const  i2; 

3-  const  int  *ipl; 

4.  int  const  *ip2; 

5.  int  ’const  ip3; 

6.  const  int  ’const  ip4; 

7.  int  const  ’const  ip5; 

The  first  two  forms  declare  integers 
that  cannot  be  changed.  The  only  cor¬ 
rect  way  to  put  a  value  into  this  integer 
or  any  other  cowst-qualified  variable  is 
with  initialization  as  shown  here. 

const  int  i  =  123; 

The  third  and  fourth  forms  are  pointers 
to  integers  where  the  integers  cannot 
be  changed.  The  fifth  form  is  a  pointer 
to  an  integer  that  can  be  changed,  but 
the  pointer  itself  cannot  be  changed. 
The  sixth  and  seventh  forms  are  point¬ 
ers  that  cannot  be  changed  and  that 
point  to  integers  that  also  cannot  be 
changed. 

The  const  type  qualifier  is  not  per¬ 
fect.  There  are  exceptions  to  the  pro¬ 
tection  it  will  provide,  and  the  ANSI 
document  abdicates  responsibility  for 
most  of  them,  saying,  “if  an  attempt  is 
made  to  modify  an  object  defined  with 
a  cowsl-qualified  type  through  use  of 
an  lvalue  with  non-co»rst-qualified  type, 
the  behavior  is  undefined.”  There  must 
have  been  a  good  reason  for  that.  The 
original  K&R  does  not  include  the  const 


keyword,  so  the  reason  cannot  be  to 
protect  existing,  pre-ANSI  code. 

What  does  all  this  mean?  What,  for 
example,  should  happen  if  you  were 
to  initialize  a  non-const  pointer  with 
the  address  of  a  conslvariable  as  shown 
here? 

const  int  i; 

int  *ip  =  &i; 

Some  compilers  courageously  give  a 
warning  for  this  code.  It  should  prob¬ 
ably  be  an  error,  but  the  wimpy  lan¬ 
guage  of  the  ANSI  spec  does  not  pro¬ 
vide  for  that.  Call  it  an  error  and  you 
do  not  conform,  I  think. 

Suppose  we  pass  a  pointer  of  the 
third  form  above  to  a  function  that  is 
expecting  (by  virtue  of  its  prototype 
and  declaration)  a  non -const  pointer. 
Consider  this: 

const  char  *ch  =  “123”; 

strcpy(ch,  “456”); 

Once  again,  some  compilers  issue  warn¬ 
ings.  This  code  should,  however,  be 
an  error,  because  the  strcpy  function  is 
defined  to  expect  a  normal  pointer  as 
the  first  parameter,  and  will,  in  fact 
change  wherever  that  pointer  points.  If 
you  ignore  the  warning,  or  use  a  com¬ 
piler  that  does  not  issue  one,  the  const 
keyword  is  worthless  in  this  context. 

ANSI  specifies  “undefined”  behavior 
when  const  is  used  along  with  a  func¬ 
tion  declaration,  meaning  that  the  fol¬ 
lowing  code  may  or  may  not  give  the 
desired  results: 

const  char  ’myaddr(void); 

The  ANSI  position  (or  nonposition) 
would  seem  to  leave  open  what  should 
happen  when  one  source  code  file  de¬ 
clares  an  external  variable  as  const  and 
another  declares  the  same  variable  as 
non  -const.  Turbo  C,  for  example,  of¬ 
fers  no  protection  for  a  const  variable 
if  another  source  file  leaves  out  the 
const-type  qualifier.  A  more  appropri¬ 
ate  behavior  would  depend  on  a  linker 
that  knows  the  type  qualification  of 
external  variables. 

According  to  ANSI,  if  a  struct  decla¬ 
ration  includes  the  const-type  qualifier, 
the  structure  members  are  const.  Mi¬ 
crosoft  C  conforms  to  this  rule,  but 
Turbo  C  does  not.  ANSI’s  expression 
of  this  rule  is  vague  and  implicit  and 
probably  subject  to  interpretation. 

If  an  array  is  const-qualified,  that 
means  its  elements  are  const. 

The  volatile  Type  Qualifier  —  A 


volatile  variable  is  one  that  might  be 
modified  from  an  external,  asynchro¬ 
nous  source,  such  as  an  interrupt  ser¬ 
vice  routine.  Its  purpose  is  to  allow 
compilers  to  bypass  some  optimization 
when  handling  the  variable.  For  exam¬ 
ple,  you  might  have  a  global  variable 
that  your  program  is  working  with.  A 
hardware  interrupt  occurs,  and  the  in¬ 
terrupt  service  routine  modifies  that  vari¬ 
able.  If  your  compiler  is  unaware  that 
such  modifications  could  occur,  the  com¬ 
piled  code  might  be  saving  the  variable 
in  a  register  or  on  the  stack  rather  than 
in  its  designated  memory  location.  If 
you  qualify  the  variable  as  a  volatile, 
the  compiler  then  knows  to  always  keep 
the  value  in  a  location  available  to  ex¬ 
ternal  influence.  This  could  have  tricky 
consequences.  It  might  be  necessary 
for  the  compiled  code  to  disable  inter¬ 
rupts  whenever  it  is  working  with  the 
variable,  for  example,  which  could  in¬ 
troduce  timing  problems. 

Obviously,  the  volatile  type  qualifier 
has  no  meaning  when  applied  to  an 
automatic  variable.  Static  variables  de¬ 
clared  inside  functions  could  be  modi¬ 
fied  by  interrupts  if  the  interrupted  func¬ 
tion  is  called  recursively  from  the  inter¬ 
rupt  service  routine,  so  they  are  subject 
to  the  benefits  of  the  volatile  qualifier, 
but  automatic  variables  are  usually  on 

the  stack  or  in  registers  and  each  recur¬ 
sive  call  to  a  function  has  its  own  cop¬ 
ies  of  the  automatic  variables. 

A  const  volatile  Variable  —  ANSI 
provides  for  a  variable  that  has  both 
the  const  and  the  volatile  type  qualifi¬ 
ers.  If  you  code  this  statement: 

extern  const  volatile  int  x; 

the  variable  exists  somewhere  else  in 
a  way  that  it  can  be  modified  by  an 
interrupt,  but  the  local  function  cannot 
modify  it. 
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STRUCTURED  PROGRAMMING 


Humpty-Duntemann’s 
Handy  Object- 
Oriented  Glossary 


To  update  the  old  egg  a  little:  When 
I  use  a  word,  it  means  just  what 
I  choose  it  to  mean,  no  more  and 
no  less  —  unless,  of  course, 
you’re  the  one  holding  the  AK-  47. 

We’ve  come  pretty  close  to  blood¬ 
shed  lately  on  CompuServe’s  Borland 
Programming  Forum  A,  Section  1,  over 
words  as  they  apply  to  OOP.  There's 
been  an  explosion  in  programmer  jar¬ 
gon  in  the  past  year  or  two,  and  shrap¬ 
nel  is  flying  every  which  way.  The  word 
“static”  alone  seems  to  have  five  differ¬ 
ent  interpretations,  depending  not  only 
on  what  language  you’re  using,  but 
on  how  you’re  using  the  term  within 
the  language. 

This  way  lies  madness.  Most  of  the 
rest  of  this  month’s  column,  therefore, 
will  be  a  glossary  of  OOP  jargon  as  it 
applies  to  Smalltalk,  Actor,  QuickPas- 
cal,  and  Turbo  Pascal  5.5.  I  won’t  be 
going  into  jargon  specific  to  C++  un¬ 
less  that  jargon  has  been  borrowed  for 
one  of  the  other  languages.  (Turbo  Pas¬ 
cal  5.5  borrows  heavily  from  the  C++ 
lexicon.)  Let’s  not  all  kill  one  another 
over  two-bit  words  like  “virtual.” 

OOP  is  the  future.  It  will  certainly 
help  if  by  the  time  we  reach  that  future 
we’re  all  speaking  the  same  language. 

Abstract  Object  Type 

This  Borlandism  is  synonymous  with 
Smalltalk's  term  abstract  superclass.  An 
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abstract  object  type  is  one  designed  only 
to  be  inherited  from.  Actual  instances 
(see  also)  of  abstract  object  types  or 
abstract  superclasses  are  never  created. 

Because  none  of  the  OOP  languages 
in  common  use  under  DOS  support 
multiple  inheritance  {see  also)  abstract 
object  types  allow  two  otherwise  unre¬ 
lated  object  types  to  be  tied  together 
into  a  single  class  hierarchy  {see  also). 


For  example,  in  a  windowing  system 
there  might  be  a  spreadsheet  window 
and  a  telecommunications  window.  It 
doesn’t  make  sense  to  make  the  spread¬ 
sheet  window  a  child  of  the  telecomm 
window,  nor  the  telecomm  window  a 
child  of  the  spreadsheet  window.  The 
two  are  pretty  thoroughly  independent. 
However,  both  have  a  border  and  a 
position  and  both  may  be  dragged 
around  on  the  screen.  Therefore,  a  Win¬ 
dow  abstract  object  type  is  created  so 
that  the  spreadsheet  window  and  tele¬ 
comm  window  can  inherit  those  com¬ 
mon  characteristics  from  a  common 
ancestor  type.  A  Window  object  by 
itself  would  not  be  useful,  so  no  in¬ 
stances  of  object  type  Window  are  ever 
actually  created.  Class  Window  may, 
however,  act  as  a  “mask”  over  one  of 
its  child  object  types,  as  described  un¬ 
der  polymorphism. 

Ancestor  Class 

(In  Turbo  Pascal  5.5,  ancestor  object 
type.)  Any  class  or  object  type  further 
up  in  the  class  hierarchy  (see  also) 
from  a  given  class  is  an  ancestor  class 
to  that  class.  The  immediate  ancestor 
class  of  any  class  is  its  parent  class  {see 
also.) 

Binding 

The  process  through  which  the  caller 
of  a  routine  gets  the  address  of  that 
routine  is  called  binding.  In  non-OOP 
languages,  this  is  straightforward:  The 
compiler  binds  caller  and  call-ee  at  com¬ 
pile  time  by  building  a  CALL  instruc¬ 
tion  to  the  call-ee’s  address.  The  deci¬ 
sion  is  made  by  the  compiler,  and  can¬ 
not  be  changed  at  run  time. 

OOP  allows  late  binding  (see  also), 
which  defers  the  binding  of  caller  and 
call-ee  until  run  time  through  some 
behind-the-scenes  magic  involving  ta¬ 
bles  of  procedure  addresses.  Something 
approximating  late  binding  can  be  done 
with  procedural  types,  as  implemented 


in  Turbo  Pascal  5.0  and  QuickPascal 
1.0,  but  OOP  brings  late  binding  to 
maturity.  Late  binding  makes  polymor¬ 
phism  possible. 

Browser 

There’s  nothing  specific  to  object- 
oriented  programming  about  browsers, 
but  the  word  is  most  used  in  OOP 
environments  such  as  Smalltalk.  A  Small¬ 
talk  browser  is  a  lot  like  an  inspector 
in  Turbo  Debugger:  A  special-purpose 
editor  that  allows  you  to  look  at  and 
modify  the  various  parts  of  an  object. 
A  browser  typically  has  several  sepa¬ 
rate  interior  regions  called  “subviews” 
or  “panes,”  each  of  which  shows  a 
different  aspect  of  the  object  being 
browsed.  One  pane  may  summarize 
the  object’s  data  fields,  while  another 
indicates  where  it  falls  in  the  class 
hierarchy,  and  yet  another  shows  the 
actual  code  making  up  the  object’s 
methods. 

Browsers  are  a  good  idea,  and  I  pre¬ 
dict  that  they  will  become  a  lot  more 
common  as  our  data  abstraction  tools 
like  OOP  become  more  sophisticated 
and  the  structures  we  use  larger  and 
more  prolix. 

Child  Class 

(In  Turbo  Pascal  5.5,  this  term  would 
be  child  object  type.)  Any  class  that 
inherits  from  another  class  is  a  child 
class  of  that  class.  In  other  words,  if 
class  B  inherits  from  class  A,  B  is  a  child 
class  of  A. 

Class 

Classes  are  to  objects  what  types  are 
to  records  —  the  complete  description 
of  the  item’s  innards.  So  close  is  this 
relationship  that  for  Turbo  Pascal  5.5 
Borland  dropped  the  term  class  alto¬ 
gether  in  favor  of  object  type,  which  it 
considered  more  self-explanatory  and 
less  jargon-like.  (Object  type  and  class 
are  synonyms,  but  only  Borland  uses 
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object  type.)  Class  is  the  correct  term, 
however,  in  nearly  all  other  OOP  lan¬ 
guages,  including  Smalltalk,  C++,  Ac¬ 
tor,  and  QuickPascal. 

Like  a  type,  a  class  is  a  template 
rather  than  an  entity  allocated  at  some 
address  in  memory.  You  create  an  in¬ 
stance  (see  also)  of  a  class,  and  that 
instance  is  an  object.  Again,  it’s  much 
like  creating  an  instance  of  a  record 
type,  which  is  the  record  itself.  Be 
warned  that  in  most  OOP  languages, 
creating  an  instance  of  a  class  is  done 
differently  than  creating  an  instance  of 
an  ordinary  (non-object)  type. 

A  good  capsule  definition  of  class  is 
a  type  that  exhibits  the  characteristics 
of  object  orientation:  Encapsulation  and 
inheritance. 

Class  Hierarchy 

This  Smalltalk  term  is  synonymous  with 
object  hierarchy  (Turbo  Pascal  5.5)  and 
class  tree{ Actor).  Inheritance  {see  also) 
allows  classes  to  be  defined  as  “chil¬ 
dren”  of  existing  classes,  such  that  the 
children  have  access  to  all  data  and 
code  defined  in  the  parent  class.  A 
sophisticated  OOP  application  might 
have  an  elaborate  structure  of  related 
classes  that  resembles  a  tree: 


Window 

Lfouti 

I — Field 

—  IntergerField 
—  BooLeanField 
—  StringField 


A  class  hierarchy  is  created  by  defining 
abstract  objects  (see  also)  at  the  top  of 
the  hierarchy,  and  giving  those  abstract 
objects  all  of  the  most  generally  appli¬ 
cable  code  and  data  for  the  whole  hier¬ 
archy.  The  abstract  objects  thus  exist 
as  “broadcast  stations”  from  which  the 
most  general  code  and  data  may  be 
inherited.  As  you  move  toward  the 
leaves,  each  child  class  adds  code  and 
data  that  is  more  and  more  specific  in 
nature,  until  the  leaves  of  the  hierarchy 
tree  are  objects  that  do  fully  useful  tasks. 

In  the  mini-hierarchy  shown,  the  Win¬ 
dow  class  might  be  nothing  more  than 
a  rectangular  subset  of  the  screen  with 
a  border.  It  contains  only  X,Y  position 
values  and  flags  indicating  whether  or 
not  it  is  currently  visible  or  active.  Its 
methods  would  allow  it  to  be  dragged 


around  the  screen  and  made  visible  or 
invisible,  but  nothing  more.  The  Form 
class  might  add  a  border  and  mecha¬ 
nisms  for  vertical/horizontal  scrolling. 
The  Field  class  adds  generalized  meth¬ 
ods  for  setting  and  returning  a  pointer 
to  a  value,  but  does  not  yet  commit  to 
any  particular  type  of  value.  Only  at 
the  leaves  of  the  hierarchy  do  classes 
like  BooleanField  provide  a  completely 
useful  object  —  in  this  case,  a  field  for 
the  entry  and  editing  of  Boolean  val¬ 
ues.  Remember  that  BooleanField  re¬ 
tains  everything  its  parents  provided: 
Windows,  drag  methods,  scroll  bars, 
and  so  on.  It  only  adds  the  last  and 
most  specific  parts  of  the  object:  Those 
parts  catering  to  the  Boolean  data  type. 

A  class  hierarchy  is  an  extremely  pow¬ 
erful  tool  for  managing  the  complexity 
of  an  OOP  application.  It  distributes 
data  and  functionality  along  a  line  from 
general  to  specific,  and  allows  the 
programmer  to  zero  in  on  only  the 
portion  of  the  functionality  that  is  be¬ 
ing  worked  on  at  any  given  time. 

Class  Tree 

The  Actor  term  for  class  hierarchy  (see 
also). 

Dynamic  Objects 

When  objects  are  allocated  on  the  heap, 
they  are  dynamic  objects ,  just  as  ordi¬ 
nary  variables  that  are  allocated  on  the 
heap  are  dynamic  variables.  You’re  un¬ 
likely  to  run  into  this  term  unless  you’re 
using  or  reading  about  Turbo  Pascal 
5.5.  In  QuickPascal  and  Macintosh  Ob¬ 
ject  Pascal,  all  objects  must  be  allo¬ 
cated  on  the  heap,  so  like  it  or  not 
they’re  all  dynamic,  and  thus  the  term 
loses  its  purpose  and  isn’t  used.  Turbo 
Pascal  5.5,  however,  allows  objects  to 
be  allocated  statically  in  the  data  seg¬ 
ment  exactly  as  ordinary  variables  are. 
So  just  as  in  all  Pascals  you  can  have 
static  variables  and  dynamic  variables, 
in  Turbo  Pascal  you  can  have  static 
objects  and  dynamic  objects. 

Early  Binding 

Binding  (see  also)  is  the  process  by 
which  the  caller  of  a  routine  is  given 
the  address  of  that  routine.  Traditional 
Pascal  procedure  calls  are  good  exam¬ 
ples  of  early  binding ,  because  the  com¬ 
piler  plugs  the  destination  address  into 
the  machine-code  CALL  instruction 
when  the  instruction  is  generated,  at 
compile-time.  Special  mechanisms  ex¬ 
ist  in  OOP  languages  to  defer  binding 
until  run  time;  this  is  called  late  bind¬ 
ing  (see  also). 

Encapsulation 

At  the  heart  of  the  notion  of  OOP  is  the 
practice  of  defining  code  (in  the  form 
of  methods ,  see  also)  and  data  together 


as  a  single-named  entity  called  an  ob¬ 
ject.  This  rolling  up  of  methods  and 
data  into  a  unified  bundle  is  part  and 
parcel  of  the  term  encapsulation.  The 
problem  is,  some  people  (notably,  the 
Smalltalk  partisans)  take  it  consider¬ 
ably  further,  and  hold  that  encapsula¬ 
tion  means  that  users  of  an  object  can¬ 
not  directly  know  of  or  reference  the 
object’s  data.  The  data  lives  at  the  cen¬ 
ter  of  the  capsule,  as  it  were,  and  can 
only  be  accessed  through  one  of  the 
methods  that  surround  it. 

In  other  words,  if  a  Boolean  field 
within  an  object  is  named  Visible,  users 
of  the  object  cannot  perform  a  test 
such  as 

IF  MyObject. Visible  THEN 
MyObject.Drag  ELSE 
MyObject. Relocate; 

Instead,  a  method  named  IsVisible  would 
have  to  be  defined  to  return  the  value 
of  the  data  field  Visible,  and  two  addi¬ 
tional  methods  (perhaps  Show  and  Hide) 
would  be  needed  to  flip  the  Boolean 
state  of  Visible  inside  the  object. 

This  is  literally  true  in  Smalltalk.  Small¬ 
talk’s  encapsulation  of  data  is  absolute. 
In  other  OOP  languages,  this  sort  of 

A  Window  object  by 
itself  would  not 
be  useful,  so  no  in¬ 
stances  of  object  type 
Window  are  ever 
actually  created 

absolute  encapsulation  is  allowed,  but 
not  enforced.  C++,  QuickPascal,  and 
Turbo  Pascal  5-5  allow  ordinary  refer¬ 
ences  to  an  object’s  data  from  any¬ 
where  within  the  object’s  scope.  In  other 
words,  if  the  object  itself  is  “visible,”  its 
data  fields  are  also  visible.  The  pro¬ 
grammer  can  choose  the  degree  to 
which  data  fields  are  encapsulated 
within  objects. 

Absolute  encapsulation  places  an  un¬ 
avoidable  performance  burden  on  some 
types  of  programs,  hence  the  more  le¬ 
nient  encapsulation  of  C++  and  Object 
Pascal.  In  most  cases,  it’s  a  good  idea 
to  access  object  data  only  through  the 
object’s  methods,  but  C++  and  Object 
Pascal  people  can  break  that  rule  ac¬ 
cording  to  their  own  judgment  —  and 


134 

730 


Dr.  Dobb's Journal,  October  1989 


must  accept  the  consequences  if  they 
judge  badly. 

Extendibility 

Through  the  property  of  inheritance 
(see  also),  objects  may  be  extended 
without  access  to  the  objects’  source 
code.  The  mechanism  used  is  overrid¬ 
ing  methods  (see  override .)  A  child 
class  of  an  existing  class  defines  a  new 
method  with  the  same  name  as  an  in¬ 
herited  method.  This  new  method  adds 
some  new  functionality  to  the  inher¬ 
ited  method  and  replaces  it  within  the 
child  class. 

Inheritance 

One  of  the  fundamental  characteristics 
of  OOP  is  that  a  class  (see  also)  may 
be  defined  in  terms  of  an  existing  class. 
The  new  class  inherits  all  definitions 
made  within  the  existing  class  (called 
its  “parent  class”)  and  any  definitions 
its  parent  class  may  have  inherited  from 
classes  further  up  the  class  hierarchy 
(see  also.) 

Inherited  data  and  methods  may  be 
used  as  freely  as  data  and  methods 
defined  within  the  class  itself. 

Instance 

The  term  instance  is  not  limited  to 
OOP  situations,  but  it’s  used  more  fre¬ 
quently  in  connection  with  objects  than 
with  earlier  data  structures  like  arrays 
and  records.  An  instance  is  a  realiza¬ 
tion  in  memory  of  the  description  we 
call  a  class  or  an  object  type.  Classes 
or  object  types  are  defined  after  the 
TYPE  reserved  word,  whereas  instances 
are  declared  after  VAR.  Instances  are 
thus  object  variables,  which  we  nor¬ 
mally  just  call  objects. 

Late  Binding 

Binding  (see  also)  is  the  process  by 
which  the  caller  of  a  routine  is  given 
the  address  of  that  routine.  This  can 
be  done  at  compile  time  ( early  bind¬ 
ing-,  see  also)  or  it  can  be  done  at  the 
time  the  actual  call  is  made.  Binding 
the  caller  to  the  routine  at  the  time  the 
call  is  made  is  called  late  binding. 

Many  different  mechanisms  are  used 
to  implement  late  binding,  but  most 
involve  a  behind-the-scenes  table  of 
method  addresses  specific  to  a  given 
class  or  object  type.  To  execute  a  late- 
bound  method  Dolt  belonging  to  ob¬ 
ject  MyGadget  (in  Object  Pascal  terms 
the  statement  MyGadget. Dolt ,)  the  code 
must  first  determine  the  class  of 
MyGadget,  locate  the  method  table  for 
that  class,  look  up  the  table  entry  for 
method  Dolt,  and  then  pass  control  to 
the  address  at  Dolts  entry  in  the  table. 

Late  binding  makes  polymorphism 
(see  also)  possible. 


Method 

Through  encapsulation  (see  also)  code 
and  data  are  combined  into  a  single- 
named  entity  called  an  object.  The  code 
portion  of  an  object  consists  of  some 
number  of  routines  called  methods. 
The  headers  of  an  object’s  methods  are 
defined  within  the  object’s  definition, 
and  the  bodies  are  defined  later  in  this 
glossary. 

In  the  Location  object  definition 
shown  later  in  the  entry  for  virtual, 
there  are  four  methods:  MoveTo,  Show, 
Hide,  and  IsVisible.  In  Turbo  Pascal  5.5 
and  QuickPascal,  methods  may  be  either 
procedures  or  functions  and  are  de¬ 
fined  in  almost  exactly  the  same  way. 
In  Turbo  Pascal  5.5,  methods  may  also 
be  either  static  methods  or  virtual  meth¬ 
ods  {see  also.)  All  of  QuickPascal’s  meth¬ 
ods  are  the  equivalent  of  Turbo  Pas¬ 
cal’s  virtual  methods;  static  methods 
are  not  present  in  QuickPascal. 

Message 

This  term  is  used  only  by  Smalltalk  and 
Actor.  A  message  is  a  command  to  an 
object.  When  received  by  the  object,  the 
message  selects  which  method  is  to  be 
executed  in  response  to  that  message. 

This  scheme  (called  “message-pass¬ 
ing”)  is  the  functional  paradigm  for 
polymorphism  (see  also)  in  Smalltalk 
and  Actor.  The  message  selects  its 
method  at  run  time  through  late  bind¬ 
ing  (see  also.) 

In  Object  Pascal  and  C++,  the  name 
of  a  virtual  method  is  analogous  to  the 
message,  and  late  binding  resolves  the 
name  of  a  virtual  method  to  the  ad¬ 
dress  of  the  code  implementing  the 
correct  method  for  the  true  class  of  the 
object  making  the  method  call. 

Multiple  Inheritance 

In  most  OOP  languages,  each  class  or 
object  type  has  only  one  parent,  from 
which  it  inherits  everything  defined  by 
that  parent  or  inherited  by  that  parent 
from  classes  higher  in  the  class  hierar¬ 
chy.  Some  newer  OOP  languages  not 
yet  available  for  DOS  (including  C++ 
2.0  and  Eiffel)  allow  a  class  to  inherit 
from  two  or  more  parent  classes.  A 
class  hierarchy  thus  becomes  a  sort  of 
class  web,  and  there  are  significant  ques¬ 
tions  as  to  what  happens  when  more 
than  one  entity  with  the  same  name  is 
inherited  by  a  single  class. 

Note  that  Smalltalk,  Actor,  Turbo  Pas¬ 
cal  5.5  and  QuickPascal  do  not  imple¬ 
ment  multiple  inheritance,  so  I  won’t 
go  into  much  more  detail  here. 

Object 

An  object  is  an  instance  (see  also)  of  a 
class  or  object  type.  By  an  instance  I 
only  mean  that  it’s  a  variable,  with  an 


allocation  of  memory  somewhere,  and 
has  some  special  properties  that  make 
it  an  object  and  not  a  record.  In  Small¬ 
talk  and  (to  a  slightly  lesser  extent) 
Actor,  everything  is  an  object.  In  C++, 
Turbo  Pascal  5.5,  and  QuickPascal,  ob¬ 
jects  coexist  peaceably  with  older,  sim¬ 
pler  types  such  as  integers,  Booleans, 
characters,  and  records. 

Object  type 

Borland  International  redefined  some 
of  the  jargon  when  they  released  Turbo 
Pascal  as  their  implementation  of  Ob¬ 
ject  Pascal.  Their  term  object  type  is 
synonymous  with  class  (see  also)  used 
in  nearly  all  other  OOP  languages.  An 
object  type  or  class  can  be  seen  as  a 
set  of  instructions  by  which  the  com¬ 
piler  builds  objects  in  memory.  In  this 
it  is  no  different  from  an  ordinary  rec¬ 
ord  or  array  type  definition  that  speci¬ 
fies  how  many  bytes  in  size  a  variable 
of  that  type  will  be,  and  how  some  of 
those  bytes  in  combination  represent 
different  flavors  of  data. 

Again,  think  of  object  types  or  classes 
as  templates  by  which  the  compiler 

Browsers  are  a  good 
idea,  and  I  predict 
that  they  will 
become  a  lot  more 
common 


whacks  out  actual  objects  as  needed. 
These  objects  are  called  instances  (see 
also)  of  the  object  type.  An  instance  is 
just  a  variable  of  an  object  type. 

Override 

Object  classes  ordinarily  inherit  all  meth¬ 
ods  from  their  parent  class.  The  child 
class  has  the  option,  however,  of  rede¬ 
fining  a  method  it  inherits  from  its  par¬ 
ent  class  or  (through  the  parent  class) 
some  more  distant  ancestor  class.  This 
process  of  redefining  an  inherited 
method  is  called  overriding  the  ances¬ 
tor’s  method.  This  is  the  primary  way 
that  objects  are  extendible.  A  child  class 
overrides  an  existing  method  and  adds 
new  or  more  specific  behavior  to  the 
overriding  method. 

In  Turbo  Pascal  5.5,  methods  are 
overridden  simply  by  redefining  them 
under  the  same  name.  In  QuickPascal, 
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however,  the  reserved  word  “OVER¬ 
RIDE”  must  be  included  after  the 
method  header  of  the  overriding 
method: 

TYPE 

Point :  OBJECT(Location) 

Color  :  Integer; 

PROCEDURE  Show;  OVERRIDE; 

FUNCTION  GetColor  :  Integer; 

PROCEDURE  SetColor- 

(NewColor  :  Integer); 

END; 

Parent  Class 

(In  Turbo  Pascal  5.5,  parent  object  type.) 
Through  the  property  of  inheritance 
(see  also),  an  object  class  may  be  de¬ 
fined  as  the  child  of  an  existing  class. 
This  existing  class  is  called  the  parent 
class  of  the  new  class.  Smalltalk  calls 
this  a  superclass  (see  also).  QuickPas- 
cal  (but  not  Turbo  Pascal  5.5)  objects 
can  reference  data  and  methods  de¬ 
fined  within  their  parent  classes  by 
qualifying  a  reference  with  the  reserved 
word  “INHERITED.” 

Parent  classes  are  sometimes  called 
“ancestor  classes.” 

Polymorphism 

From  the  Greek  for  “many  shapes,” 
polymorphism  allows  a  single  method 
name  to  act  as  a  doorway  to  numerous 
separate  methods,  with  the  actual 
method  called  chosen  by  the  language’s 
late  binding  mechanisms  at  the  time 
the  call  is  made. 

This  is  most  tersely  explained  by  .ex¬ 
ample.  In  an  object  hierarchy,  an  ab¬ 
stract  class  (see  also)  called  “Field” 
implements  a  generic  data  field  not 
committed  to  any  given  type  of  data. 
Field  defines  numerous  generic  meth¬ 
ods  for  manipulating  data,  including 
Get  Value,  Put  Value,  and  Edit.  Field  has 
numerous  child  classes,  one  for  each 
specific  type  of  data:  IntField,  Boolean- 
Field,  CharField,  StringField,  and  so 
on.  Each  of  these  child  classes  over¬ 
rides  Fields  generic  methods  with  meth¬ 
ods  specific  to  the  child  classes’  own 
data  types.  That  is,  IntField. Edit  edits 
an  integer  value,  StringField. Edit  edits 
a  string  value,  and  so  on. 

One  of  the  subtler  rules  of  OOP  is 
that  assignment  compatibility  and 
pointer  compatibility  are  extended 
down  an  object  hierarchy.  In  other 
words,  in  our  example  an  object  of 
class  Field  may  be  assigned  an  object 
of  class  IntField,  StringField ,  Boolean- 
Field,  and  so  forth.  (But  not  the  other 
way  around!)  A  pointer  defined  as  point¬ 
ing  to  the  Field  class  may  also  point  to 
any  of  Fields  child  classes.  Such  an 
assignment  is  called  a  polymorphic  as¬ 
signment. 


This  means  that  an  object  of  class 
Field  may  in  fact  be  a  mask  over  an 
object  of  class  StringField  or  any  of 
Fields  other  child  classes.  Precisely 
which  class  wears  the  Field  mask  doesn’t 
matter.  Given  a  Field  object  named 
MyField,  when  the  method  call  My- 
Field.Edit  is  made,  late  binding  selects 
the  correct  Edit  method  at  the  time  the 
call  is  made.  If  a  StringField  object  had 
been  assigned  to  MyField,  then  the  String- 
Field. Edit  method  would  be  called.  On 
the  other  hand,  if  a  BooleanField  ob¬ 
ject  had  been  assigned  to  MyField,  then 
the  BooleanField. Edit  method  would 
be  called  —  and  the  decision  is  not 
made  until  the  call  itself  is  made. 

In  a  sense,  what  polymorphism  al¬ 
lows  us  to  do  is  say  to  an  arbitrary  Field 
object:  “Go  edit  yourself!”  and  the  Field 
object  will  select  the  correct  Edit  method 
to  use.  One  command  —  Edit —  has  a 
different  shape  for  each  different  child 
class  of  Field.  Polymorphism! 

This  is  difficult  business,  but  it  is  enor¬ 
mously  powerful.  I’ll  deal  with  polymor¬ 
phism  at  length  in  a  future  column. 

Static 

The  word  static  is  currently  the  bad 
boy  of  OOP  programming,  and  single- 
handedly  causes  more  confusion  than 
all  other  OOP  terms  combined,  includ¬ 
ing  that  old  devil  polymorphism. 

The  problem  mainly  involves  Turbo 
Pascal  5.5.  In  a  Turbo  Pascal  context, 
the  adjective  “static”  has  two  uses  (and 
two  opposites)  with  wildly  different 
contexts.  One  use  involves  the  two 
kinds  of  methods:  Static  methods  are 
early-bound  methods,  as  opposed  to 
virtual  methods,  which  are  late-bound 
methods.  The  other  use  involves  the 
two  ways  objects  can  be  created  in 
memory:  A  static  object  is  an  object 
allocated  in  the  data  segment,  whereas 
a  dynamic  object  is  an  object  allo¬ 
cated  on  the  heap.  Thus  in  one  con¬ 
text  “static”  is  the  opposite  of  “vir¬ 
tual,”  while  in  the  other  context  “static” 
is  the  opposite  of  “dynamic.” 

The  confusion  is  compounded  by 
the  fact  that  the  term  “static”  is  not 
used  at  all  in  QuickPascal,  so  you  Mi- 
crosofters  are  probably  wondering  what 
all  the  hoohah  is  about. 

(I’ve  provided  more  detailed  defini¬ 
tions  of  static  methods,  static  objects, 
dynamic  objects,  and  virtual  methods 
elsewhere.  To  pin  down  your  com¬ 
plete  understanding  of  the  very  slip- 
dpery  term  static  be  sure  to  read  them 
all!) 


Static  Methods 

Only  C++  and  Turbo  Pascal  5.5  allow 
the  definition  of  static  methods.  A  static 
method  is  a  method  subject  to  early 
binding  (see  also)  only.  Methods  sub¬ 
ject  to  late  binding  are  virtual  methods 
(see  also).  Note  that  the  term  virtual 
methods  is  not  used  in  QuickPascal 
because  late  binding  is  applied  to  all 
methods,  making  all  methods  virtual 
and  thus  making  the  distinction  be¬ 
tween  virtual  and  static  methods  un¬ 
necessary. 

Methods  are  static  by  default  in  Turbo 
Pascal  5.5.  To  make  a  method  virtual 
you  must  add  the  reserved  word  “VIR¬ 
TUAL”  immediately  after  the  method 
header.  In  the  “Location”  object  defini¬ 
tion  shown  in  the  entry  for  virtual,  the 
MoveTo  and  Is  Visible  methods  are  static, 
whereas  the  Show  and  Hide  methods 
are  virtual. 

Because  static  methods  are  early- 
bound,  a  static  method  call  is  identical 
to  an  ordinary  procedure  or  function 
call.  There  is  an  additional  level  of  indi¬ 
rection  involved  in  making  a  Turbo 
Pascal  5.5  virtual  method  call,  so  static 
methods  are  slightly  faster  than  virtual 
methods.  (But  only  slightly.) 

Static  methods  may  be  overridden, 
but  are  not  subject  to  polymorphism 
(see  also). 

Static  Objects 

A  static  object  is  an  object  allocated  in 
a  program’s  data  segment  rather  than 
on  the  heap.  The  term  is  another  one 
that  Borland  International  borrowed 
from  C++  in  implementing  Turbo  Pas¬ 
cal  5.5.  QuickPascal,  Smalltalk,  and  Ac¬ 
tor  make  no  use  of  the  term,  because 
in  those  languages  all  objects  are  dy¬ 
namically  allocated. 

A  static  object  is  very  much  like  a 
super-record  having  the  special  proper¬ 
ties  characteristic  of  object-oriented  pro¬ 
gramming.  Like  an  ordinary  record,  you 
create  static  objects  in  the  VAR  section 
of  your  program: 

VAR 

My  Record  :  RecordType; 

MyObject :  ObjectType; 
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Nothing  magical  about  it,  no  pointers, 
no  need  to  mess  with  New  or  Dispose. 
Static  objects  are  a  good  place  to  start 
learning  about  objects,  since  you  can 
concentrate  on  using  objects  without 
worrying  so  much  about  creating  them 
correctly. 

Subclass 

Like  the  term  superclass,  subclass  is 
commonly  used  only  with  regard  to 
Smalltalk.  A  subclass  is  a  child  class. 
In  other  words,  if  class  B  inherits  from 
class  A,  class  B  is  a  subclass  of  class  A. 

Superclass 

Within  an  object  hierarchy  (see  also) 
every  class  has  only  one  immediate 
ancestor,  called  its  “parent”  or  super¬ 
class.  This  term  is  commonly  used  only 
in  Smalltalk. 

Virtual 

The  term  virtual  was  one  of  several 
borrowed  from  C++  by  Borland  Interna¬ 
tional  and  applied  to  their  implementa¬ 
tion  of  Object  Pascal  released  as  Turbo 
Pascal  5  5.  It  is  not  used  in  QuickPascal 
nor  in  Smalltalk  nor  Actor. 

“VIRTUAL”  is  one  of  four  new  re¬ 
served  words  in  Turbo  Pascal  5.5.  It  is 
a  qualifier  placed  after  a  method  header 
in  the  object  type  definition: 

TYPE 

Location  = 

OBJECT 

X,Y  :  Integer; 

Visible  :  Boolean; 
PROCEDURE  MoveTo 

(NewX,NewY  :  Integer); 
PROCEDURE  Show;  VIRTUAL; 
PROCEDURE  Hide;  VIRTUAL; 
FUNCTION  IsVisible  :  Boolean; 
END; 

The  use  of  the  VIRTUAL  reserved  word 
makes  the  method  that  precedes  it  a 
virtual  method,  which  is  a  method  that 
may  be  late  bound.  (See  late  binding .) 

Keep  in  mind  that  the  word  “virtual” 
in  this  context  has  nothing  whatsoever 
to  do  with  virtual  memory  or  other 
storage  issues.  Also  keep  in  mind  that 
functionally,  all  methods  in  QuickPas¬ 
cal  are  virtual  methods.  In  Turbo  Pas¬ 
cal  there  is  the  option  of  defining  meth¬ 
ods  as  static  methods  (see  also)  and  the 
reserved  word  VIRTUAL  was  chosen 
to  differentiate  between  early  and  late 
bound  methods. 

Virtual  Methods 

Except  in  Turbo  Pascal  5.5  and  C++,  all 
methods  are  virtual  methods,  so  the 
term  is  not  used  much  outside  of  Turbo 
Pascal  5.5.  Virtual  methods  are  defined 


as  methods  that  take  part  in  late  bind¬ 
ing  (see  also). 

In  early  binding  (see  also)  the  ad¬ 
dress  of  a  method  is  baked  into  the 
“CALL”  machine  instruction  that  per¬ 
forms  the  method  call,  by  the  compiler 
at  compile-time.  In  late  binding,  the 
actual  address  of  the  method  being 
called  is  not  determined  until  the  time 
that  the  call  takes  place.  How  this  is 
done  varies  from  language  to  language 
(and  is  done  differently,  in  fact,  by 
Turbo  Pascal  5.5  and  QuickPascal)  but 
almost  always  involves  a  table  of  method 
addresses  hidden  inside  the  object  that 
owns  the  methods.  To  make  a  late- 
bound  method  call,  the  address  of  the 
desired  method  is  looked  up  in  the 
table  of  method  addresses,  and  then 
control  is  passed  to  that  address. 

Note  that  all  virtual  methods  of  the 
same  name  must  have  identical  method 
headers,  including  the  identical  type 
and  order  of  parameters. 

The  real  power  of  virtual  methods 
involves  polymorphism,  and  is  not  an 
easy  thing  to  describe  in  a  paragraph 
or  two.  I’ll  take  up  the  subject  of  late 
binding  and  polymorphism  in  detail  in 
a  future  column. 

Algorithms  Over  Easy 

The  difference  between  a  sort  library 
and  a  book  of  sort  algorithms  is  the 
difference  between  giving  a  guy  a  fish 
and  teaching  him  how  to  fish.  If  you 
don’t  know  how  your  tools  work,  you’re 
at  their  mercy  —  which  is  akin  to  the 
feeling  of  downing  your  last  sardine 
with  no  more  in  the  can. 

The  best  algorithms  book  I’ve  ever 
seen  crossed  my  desk  last  week:  Turbo 
Algorithms,  by  Keith  Weiskamp,  Namir 
Shammas,  and  Ron  Pronk.  Space  is 
short,  so  I  can’t  describe  it  in  detail. 
But  the  (rather  remarkable)  idea  is  this: 
The  authors  present  a  fairly  large  num¬ 
ber  of  useful  algorithms  and  then  im¬ 
plement  each  one  in  all  four  Turbo 
languages  —  Pascal,  C,  Basic,  and 
Prolog.  As  you  might  imagine,  the  book 
is  by  needs  terse,  but  it  is  nicely  written 
and  has  some  of  the  best  technical 
figures  I’ve  seen  in  a  long  time.  The 
algorithms  cover  sorting,  searching, 
stacks,  queues,  binary  and  AVL  (bal¬ 
anced)  trees;  singly-linked,  doubly- 
linked,  and  circular  lists;  and  word  and 
token  string  processing.  That’s  a  lot  of 
ground  to  cover  with  real  code  in  four 
languages,  but  somehow,  it  works.  I 
found  the  math  section  pretty  tough 
going,  but  that  could  be  my  own  aver¬ 
sion  to  the  subject,  and  the  rest  of  it 
was  both  graspable  and  immediately 
useful. 

As  it  happens,  Turbo  Libraries  is  one 
in  a  series  of  three  solid  books  by  the 


same  authors,  all  of  them  spanning  the 
four  Turbo  languages;  but  as  Wiley’s 
book  distribution  system  is  as  brain- 
dead  as  their  books  are  good,  you  may 
have  to  order  them  through  your  local 
bookstore.  They  are,  however,  well 
worth  the  wait. 

Those  Old  Release-Level  Blues 

In  my  September  column  I  raised  some 
eyebrows  by  reporting  that  “Users  of 
MS  Pascal  5.0  should  note  that  Quick¬ 
Pascal  is  only  broadly  compatible  with 
MS  Pascal.  .  . Microsoft’s  current  ma¬ 
jor  release  level  of  their  command-line 
Pascal  compiler  is  4,  not  5,  a  mistake 
ascribable  to  late-night,  bleary-eye  syn¬ 
drome.  Although,  the  next  version  of 
Microsoft  Pascal  has  yet  to  be  an¬ 
nounced,  Microsoft  has  confirmed  that 
any  future  release  will  be  upwardly 
compatible  with  QuickPascal  1.0.  The 
aboriginals  who  can  only  count  1  .  .  2  .  . 
many  had  their  finger  on  something  — 
how  are  we  ever  going  to  keep  these 
things  straight  in  the  year  2000,  when 
we’re  dealing  with  MS  Basic  21.0  and 
Turbo  Pascal  17.5  ? 
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PROGRAMMING  PARADIGMS 


listing  One  (Text  begins  on  page  112.) 

Repeat 

CalculatelnputsAndOutputs (Iteration) ; 

For  J  :=  1  To  NumOfCols  Do  (*  Copy  inputs  to  dummy  input  cells.  *) 

Program  BackPropagationDemo; 

CellArray [0, J] .Output  :=  Inputs [J]; 

For  I  :=  1  To  NumOfRows  Do  (*  Propagate  inputs  forward  through  network.  *) 

Const  NumOfRows  =  2;  (*  Number  of  rows  of  cells.  *) 

For  J  :=  1  To  NumOfCols  Do 

NumOfCols  =2;  (*  Number  of  columns  of  cells.  *) 

UpdateCellOnForwardPass (I,  J) ; 

LearningRate  =  0.25;  (*  Learning  rate.  *) 

For  J  :=  1  To  NumOfCols  Do  (*  Calculate  error  signals.  ') 

Criteria  =  0.005;  (*  Convergence  criteria.  *) 

CellArray [NumOfRows, J] .Error  := 

Zero  =  0.05;  (*  Anything  below  0.05  counts  as  zero.  *) 

DesiredOutputs [J] -CellArray [NumOfRows, J] .Output; 

One  =  0.95;  (*  Anything  above  0.95  counts  as  one.  *) 

For  I  :=  NumOfRows  Downto  1  Do  (*  Propagate  errors  backward  through  *) 

For  J  :=  1  To  NumOfCols  Do  (*  network,  and  update  weights.  *) 

Type  CellRecord  =  Record 

UpdateCellOnBackwardPass (I,  J) ; 

Output  :  Real;  {*  Output  of  the  current  cell.  *) 

ErrorSquared  :=  0.0;  (*  Clear  error  squared.  *) 

Error  :  Real;  {*  Error  signal  for  the  current  cell.  *) 

For  J  :=  1  To  NumOfCols  Do  (*  Calculate  error  squared.  *) 

Weights:  Array [0. .NumOfCols]  Of  Real;  {*  Weights  in  cell.  *) 

ErrorSquared  :=  ErrorSquared  +  Sqr (CellArray (NumOfRows, J] .Error) ; 

End; 

If  ErrorSquared  <  Criteria  Then  (*  If  network  has  converged,  increment  *) 

Convergedlterations  :=  Convergedlterations  +  1  (*  convergence  *) 

Var  CellArray  :  Ar ray [0. .NumOfRows, 0. .NumOfCols]  Of  CellRecord;  (*  Cells.  * 

Else  Convergedlterations  :=  0;  (*  count,  else  clear  convergence  count.  *) 

Inputs  :  Array [1 . .NumOfCols]  Of  Real;  (*  Input  signals.  *) 

If  (Iteration  Mod  100)  <  4  Then  (*  Every  100  iterations,  write  out  *) 

DesiredOutputs :  Array [1 . .NumOfCols j  Of  Real;  (*  Desired  output  signals.  *) 

Begin  (*  information  on  the  4  patterns.  *) 

If  (Iteration  Mod  100)  =  0  Then  GotoXY(l,2); 

Procedure  CalculatelnputsAndOutputs (  Iteration:  Integer  ); 

Write('  ',  Iteration^, '  ');  (*  Write  iteration  number.  *) 

Var  I:  Integer; 

For  J  :=  1  To  NumOfCols  Do  (*  Write  out  input  pattern.  *) 

Begin  {*  Calculate  the  inputs  and  desired  outputs  for  the  current  iteration.  *) 

Write(Inputs [J] : 4 :2, '  '); 

(*  The  inputs  cycle  through  the  4  patterns  (0.05,0.05),  (0.95,0.05),  *) 

Write ('  '); 

(*  (0.05,0.95),  (0.95,0.95).  The  corresponding  desired  outputs  are  *) 

For  J  :=  1  To  NumOfCols  Do  (*  Write  out  desired  outputs.  *) 

(*  (0.05,0.05),  (0.05,0.95),  (0.05,0.95),  (0.95,0.05).  The  first  *) 

Write (DesiredOutputs [J] :4:2, '  ' ) ; 

(*  desired  output  is  the  logical  AND  of  the  inputs,  and  the  second  *) 

Write  ('  '); 

(*  desired  output  is  the  logical  XOR.  *) 

For  J  :■  1  To  NumOfCols  Do  (*  Write  out  actual  outputs.  *) 

If  (Iteration  Mod  2)  =  1  Then  Inputs [1]  :=  One  Else  Inputs [1]  :=  Zero; 

Write (CellArray [NumOfRows, J] .Output : 4 :2, '  ' )  ; 

If  (Iteration  Mod  4)  >  1  Then  Inputs [2]  :=  One  Else  Inputs [2]  :=  Zero; 

Writeln; 

If  (Inputs[l]  >  0.5)  And  (Inputs[2]  >  0.5)  Then  DesiredOutputs [1]  :=  One 

End; 

Else  DesiredOutputs [1]  :=  Zero; 

Iteration  :=  Iteration  +  1;  (*  Increment  iteration  count  *) 

If  (Inputsfl]  >  0.5)  Xor  (Inputs[2]  >  0.5)  Then  DesiredOutputs [2]  :=  One 

Until  (Convergedlterations  =  4)  Or  (Iteration  =  32767); 

Else  DesiredOutputs (2]  :=  Zero; 

(*  Stop  when  the  network  has  converged  on  all  4  input  patterns,  or 

End; 

when  * ) 

(*  we  are  about  to  get  integer  overflow.  *) 

Procedure  UpdateCellOnForwardPass (  Row,  Column:  Integer  ) ; 

If  Convergedlterations  <>  4  (*  Write  a  final  message.  *) 

Var  J  :  Integer; 

Then  Writeln (' Network  didn''t  converge') 

Sum:  Real; 

Else  Writeln ('Network  has  converged  to  within  criteria'); 

Begin  (*  Calculate  the  output  of  the  cell  at  the  specified  row  and  column.  *) 
With  CellArray [Row, Column]  Do 

End. 

Begin 

Sum  :=  0.0;  (*  Clear  weighted  sum  of  inputs.  *) 

For  J  :=  0  To  NumOfCols  Do  (*  Form  weighted  sum  of  inputs.  *) 

Sum  :=  Sum  +  Weights[J] *CellArray(Row-l, J] .Output; 

Output  :=  1.0/(1.0+Exp(-Sum) ) ;  (*  Calculate  output  of  cell.  This  *) 

(*  is  called  a  sigmoid  function.  *) 

Error  :=  0.0;  (*  Clear  error  for  backward  pass.  *) 

End; 

End; 

Procedure  UpdateCellOnBackwardPass (  Row,  Column:  Integer  ) ; 

Var  J:  Integer; 

Begin  (*  Calculate  error  signals  and  update  weights  on  the  backward  pass.  *) 

With  CellArray [Row, Column]  Do 

Begin 

End  listing 

For  J  :=  1  To  NumOfCols  Do  (*  Back  propagate  the  error  to  the  cells  *) 

CellArray [Row-1, J] .Error  :=  (*  below  the  current  cell.  *) 

CellArray [Row-1, J] .Error+Error 'Output* (1 .0-Output) 'Weights ( J] ; 

For  J  :=  0  To  NumOfCols  Do  (*  Update  the  weights  in  the  current  cell.  ') 

Weights [J]  := 

Weights [J]  + 

LearningRat  e 'Error 'Output  * ( 1 . 0-Output ) 'CellArray [Row-1 ,  J] . Output ; 

End; 

End; 

Var  I,  J,  K  :  Integer;  (*  I  loops  over  rows,  J  loops  over 

columns,  *) 

(*  and  K  loops  over  weights.  *) 

Convergedlterations :  Integer;  (*  Network  must  remain  converged  for  four  *) 

(*  iterations  (one  for  each  input  pat- 

tern) .  *) 

Iteration  :  Integer;  (*  Total  number  of  iterations  so  far.  *) 

ErrorSquared  :  Real;  (*  Error  squared  for  current  iteration.  *) 

Begin 

ClrScr;  (*  Initialize  the  screen.  *) 

Writeln (' Iteration  Inputs  DesiredOutputs  Actual  Outputs'); 

Iteration  :=  0;  (*  Start  at  iteration  0.  *) 

Convergedlterations  :=  0;  (*  The  network  hasn't  converged  yet.  *) 

For  I  :=  1  To  NumOfRows  Do  (*  Initialize  the  weights  to  small  random  num¬ 
bers.  *) 

For  J  :=  1  To  NumOfCols  Do 

For  K  :=  0  Tc  NumOfCols  Do 

CellArray [ I , J] .Weights [K]  :=  0.2*Random-0.1; 

For  I  :=  0  To  NumOfRcws  Do  (*  Initialize  outputs  of  dummy  constant  cells.  *) 

CellArray [I, 0] .Output  :=  One; 
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Listing  One  (Text  begins  on  page  123  ) 

II - menus,  h 

#ifndef  MENUS 
♦define  MENUS 

♦include  "window. h” 


♦define  MAXSELECTIONS  12 

♦define  CHECK  ' \xfb'  //  IBM  Graphics  character  set  check  mark 

♦define  MENUFG  CYAN 
♦define  MENUBG  BLUE 
♦define  SELECTFG  BLACK 
♦define  SELECTBG  WHITE 
♦define  DISABLEFG  LIGHTGRAY 
♦define  DISABLEBG  BLUE 

// 

//  SLIDING  BAR  MENUS 

// 

class  SlideBar  { 
int  row; 

void  (“mfunc)  (SlideBar*.) ; 
char  “mtext; 
int  selections; 
int  quitflag; 
unsigned  *msave; 
int  selection; 

int  dispatch (int  sel,  int  titlewidth); 
public: 

SlideBar  (int  line,  char  “text,  int  sel, 
void  (“func)  (SlideBar&) )  ; 

“SlideBar  () ; 
void  terminate (void) 

{  quitflag  =1;  ) 
int  current_selection (void) 

{  return  selection;  ) 


//  menu  screen  row 
//  selection  functions 
//  selection  titles 
//  number  of  selections 
//  flag  for  appl  to  say  quit 
//  save  area  for  menu  bar 
//  selection  position 


// 

//  POPDOWN  MENUS 

II 

class  PopdownMenu  :  Window  { 
int  selections; 
void  (“mfunc)  (PopdownMenus) ; 
char  “text; 
int  quitflag; 
int  selection; 

//  -  private  methods 

int  get_selection (int  sel); 
int  dispatch(int  sel); 
int  menuheight (char  “text); 
int  menuwidth (char  “text); 
void  operator«  (char  “text)  ; 

public: 

PopdownMenu (unsigned  left,  unsigned  top, 

char  “text,  int  sel,  void  (“func)  (PopdownMenuS) )  ; 
“PopdownMenu ( ) ( ) ; 
void  terminate (void) 

(  quitflag  =1;  ) 
void  disable_selection(int  sel) 

(  *text[sel-l]  =  ) 

void  enable_selection (int  sel) 

{  *text[sel-l]  =  '  ' ;  ) 
int  test_toggle (int  selection); 
int  current_selection (void) 

{  return  selection;  ) 


//  number  of  selections 
//  selection  functions 
//  address  of  menu  text 
//  flag  for  appl  to  say  quit 
//  current  selection  position 


♦endif 


End  Listing  One 


Listing  Two 

/  / - menus .  c 

♦include  <stddef.h> 

♦include  <string.h> 

♦include  <stdio.h> 

♦include  <ctype.h> 

♦include  <conio.h> 

♦include  "menus. h" 

♦include  "console. h" 

static  void  select (int  row, int  sel,  char  *ttl,int  set, int  wd) ; 
♦define  ON  1 
♦define  OFF  0 

II 

II  SLIDING  BAR  MENUS 
// 

II - constructor  for  a  sliding  menu  bar 

SlideBar: : SlideBar (int  line,  char  “text,  int  sel, 
void  (“func)  (SlideBarS) ) 

{ 

savecursor () ; 
hidecursor () ; 
initconsole {) ; 

// - menu  variables 

quitflag  =  0; 
mfunc  =  func; 
mtext  =  text; 

/  / - save  video  memory 

msave  =  new  unsigned [SCREENWIDTH] ; 
row  =  min (line-1,  24); 

savevideo (msave,  row,  0,  row,  SCREENWIDTH-1) ; 

/  / - display  the  menu  bar 


colors (MENUFG,  MENUBG); 
setcursor(0,  row); 
int  cols  =  SCREENWIDTH; 
while  (cols — ) 

window_putc ('  '); 

//  -  compute  the  width  of  the  selection  texts 

int  titlewidth  =  0; 

for  (int  i  =  0;  mtext [i]  &&  i  <  MAXSELECTIONS;  i++) 
titlewidth  =  max (titlewidth,  strlen (mtext [i] )) ; 

//  -  save  the  selection  count 

selections  =  i; 

//  -  display  the  selection  texts 

for  (i  =0;  i  <  selections;  i++) 

select (row,  i+1,  mtext [i],  OFF,  titlewidth); 

//  -  dispatch  the  menu's  selections 

dispatch (sel,  titlewidth); 


// - destructor  for  a  menu  bar 

SlideBar: : “SlideBar (void) 

{ 

restorevideo (msave,  row,  0,  row,  SCREENWIDTH-1); 
delete  msave; 
restorecursor ()  ; 
unhidecursor () ; 


//  -  navigate  the  menu  and  dispatch  a  chosen  function 

int  SlideBar : :dispatch (int  sel,  int  titlewidth) 

{ 

savecursor () ; 
int  sliding  =  1; 
if  (sel) 

selection  =  sel; 
while  (sliding)  { 

//  -  highlight  the  menu  bar  selection 

select (row,  selection,  mtext [selection-1 ] , 

ON, titlewidth) ; 

// - reacl  a  selection  key 

int  c  =  get key (); 
switch  (c)  ( 

case  ESC: 

// - ESC  key  quits 

sliding  =  0; 
break; 
case  FWD: 

//  -  right-arrow  cursor  key 

select (row,  selection,  mtext [selection-1) , OFF, 
titlewidth) ; 

if  (selection++  ==  selections) 
selection  =  1; 
break; 
case  BS: 

//  -  left-arrow  cursor  key 

select (row,  selection,  mtext [selection-1] , OFF, 
titlewidth) ; 
if  ( — selection  ==  0) 

selection  =  selections; 
break; 
default : 

//  -  test  for  1st  letter  match 

for  (int  i  =  0;  i  <  selections;  i++) 

if  (tolower(c)  ==  tolower (mtext [i] (1) ) )  [ 

//  —  match,  turn  off  current  selection 
select (row,  selection, 
mtext [selection-1] , 

OFF,  titlewidth) ; 

II  —  turn  on  new  selection 
selection  =  i+1; 
select (row,  selection, 
mtext [selection-1] , 

ON, titlewidth) ; 
break; 


) 

if  (i  ==  selections) 
break; 
case  ' \r' : 

// - ENTER  key  =  user  selection 


if  (mfunc [selection-1] ) 

(*mfunc[selection-l] ) (*this); 
sliding  =  [(quitflag  ==  1); 
break; 

} 

) 

restorecursor () ; 

select (row, selection, mtext [selection-1] , OFF, titlewidth) ; 
return  quitflag  ?  0  :  selection; 


//  -  set  or  clear  the  highlight  on  a  menu  bar  selection 

static  void  select  (int  row, int  sel, char  *ttl,int  set, int  wd) 

< 

setcursor (5+ (sel-1) *wd,  row) ; 
if  (set  ==  OFF) 

colors (MENUFG,  MENUBG) ; 

else 

colors (SELECTFG,  SELECTBG); 
window_printf (ttl) ; 


// 

//  POPDOWN  MENUS 
// 


//  -  constructor  for  the  PopdownMenu 

PopdownMenu: :PopdownMenu (unsigned  left,  unsigned  top, 

char  “mtext,  int  sel,  void  (“func)  (PopdownMenuS) ) 
:  (left,  top,  left+l+menuwidth (mtext) , 

top+l+menuheight (mtext) ,  MENUFG,  MENUBG) 


*this  «  mtext; 
mfunc  =  func; 


(continued  on  page  150) 
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C  PROGRAMMING 


Listing  Two  (Listing  continued,  text  begins  on  page  123  ) 

text  =  mtext; 

selection  =  sel; 

selections  =  menuheight (text) ; 

//  -  dispatch  the  menu  selection 

dispatch (sel) ; 


//  -  write  text  selections  into  the  popdown  menu 

void  PopdownMenu: :operator« (char  **mtext) 

{ 

hidecursor () ; 
int  y  =  0; 


//  -  a  NULL-terminated  array  of  character  pointers 

text  =  mtext; 


while  (*mtext  !=  NULL)  { 
cursor (0,  y++); 
char  hold  =  **mtext; 
if  (**mtext  =='-')  { 

set_colors (DISABLEFG,  DISABLEBG) ; 
♦♦mtext  =  ' 


♦this  «  *mtext; 

**mtext++  =  hold; 
set_colors (MENUFG,  MENUBG) ; 

} 

unhidecursor ( ) ; 


// - get  a  popdown  menu  selection 

int  PopdownMenu: :get_selection (int  sel) 


//  -  set  the  initial  selection 

if  (sel) 

selection  =  sel; 
int  selecting  =  1; 
int  c; 

while  (selecting)  { 

//  -  display  the  menu's  selection  texts 

♦this  «  text; 

//  -  watch  for  disabled  selections 

if  (** (text+selection-1) ) 

c  =  DN;  //  force  a  key  to 

//  bypass  a  disabled  selection 

else  ( 

//  -  highlight  the  current  selection 

cursor (0,  selection-1); 
set_colors (SELECTFG,  SELECTBG) ; 

♦this  «  Mtext  +  selection  -  1); 
set_colors (MENUFG,  MENUBG) ; 
hidecursor () ; 

c  =  getkeyO;  //  —  read  the  next  keystroke 

) 

switch  (c)  ( 

case  ESC: 
case  FWD: 
case  BS: 

//  -  ESC, FWD,  or  BS  will  terminate  selection 

selecting  -  0; 
break; 
case  UP: 

// - up-arrow  cursor  key 

do 


if  ( — selection  ==  0) 

selection  =  selections; 
while  (** (text+selection-1)  ==  '-'); 
break; 


//  -  down-arrow  cursor  key 

do 

if  (selection++  ==  selections) 
selection  =  1; 

while  (**  (text+selection-1)  ==  '-'); 
break; 
default : 

//  -  other  key,  test  first  letter  match 

for  (int  i  =  0;  i  <  selections;  i++)  ( 

if  (tolower(c)  ==  tolower (text [i] (1) )  SS 
*  (text [i] )  !=  '-')  ( 

selection  =  i+1; 
selecting  -  0; 

} 

1 

break; 
case  ' \r' : 

//  -  ENTER  key  is  a  selection 

selecting  =  0; 
break; 

) 

) 

return  c  ==  '\r'  ?  selection  :  c; 

} 


// - get  and  dispatch  a  popdown  menu  selection 

int  PopdownMenu: : dispatch (int  sel) 

{ 

int  upanddown  =1; 
while  (upanddown)  { 


// - read  a  user  selection 

sel  =  get_selection (sel) ; 


switch  (sel)  { 

// - these  keys  exit  the  menu 

case  FWD: 
case  BS: 
case  ESC: 

upanddown  =0; 
break; 
default: 


// - user  has  made  a  menu  selection 

if  (mfunc [selection-1 ) )  { 

//  -  execute  a  menu  selection  function 


hidewindow () ; 

(♦mfunc [selection-1] ) (*this); 
upanddown  =  ! (quitflag  ==  1) ; 
restorewindow ( ) ; 

) 

else  { 

//  -  no  function,  must  be  a  toggle 

char  *cp  =  text [selection-1] ; 
cp  +=  strlen (cp) -1; 
if  ( *  cp  ==  '  ' ) 

♦cp  =  CHECK; 

else  if  <(*cp  S  255)  ==  CHECK) 

♦cp  =  '  '; 

) 

break; 


1 

return  sel  ==  ESC  ?  ESC  :  0; 


// - compute  the  height  of  a  popdown  menu 

int  PopdownMenu: : menuheight (char  **text) 

I 

int  height  =  0; 
while  (text [height] ) 
height++; 
return  height; 

) 

// - compute  the  width  of  a  popdown  menu 

int  PopdownMenu: :menuwidth (char  **text) 

{ 

int  width  =  0; 
while  (*text)  ( 

width  =  max (width,  strlen (‘text) ) ; 
text++; 

} 

return  width; 


//  -  test  the  setting  of  a  toggle  selection 

int  PopdownMenu: :test_toggle (int  sel) 

I 

char  *cp  =  text [sel-1] ; 
cp  +=  strlen (cp) -1; 
return  (*cp  &  255)  ==  CHECK; 

End  Listing  Two 


Listing  Three 

II - demoslid.c 

♦include  <stddef.h> 
♦include  <conio.h> 
♦include  <stdio.h> 
♦include  "menus. h" 
♦include  "console. h" 

// - File  menu 

static  char  *fmenu[]  =  [ 
"  Load  ", 
n  Save  ", 

"  New  " , 

"  Quit  ", 

NULL 

}; 


static  void  load (SlideBari) ; 
static  void  save (SlideBarS) ; 
static  void  newfile (SlideBarS) ; 
static  void  quit (SlideBarS) ; 

static  void  (*ffuncs []) (SlideBarS) =( load, save, newfile, quit } ; 
void  main (void) 

I 

SlideBar  menu(l,  fmenu,  1,  ffuncs) ; 

) 

static  void  load (SlideBarS  menu) 

I 

Window  wnd (20, 10, 40, 20, BLACK, CYAN) ; 
wnd. title (" (Stub  Function)"); 
wnd  «  "\n\n\n\n  LOAD  A  FILE"; 
getkeyO  ; 

) 

static  void  save (SlideBar  Smenu) 

I 

Window  wnd (20, 10, 40, 20, YELLOW, RED) ; 
wnd. title (" (Stub  Function)"); 
wnd  «  "\n\n\n\n  SAVE  A  FILE"; 
getkeyO  ; 

) 

static  void  newfile (SlideBar  smenu) 

{ 

Window  wnd (20, 10, 40, 20, YELLOW, RED) ; 
wnd. title (" (Stub  Function)"); 
wnd  «  "\n\n\n\n  NEW  FILE"; 
getkeyO  ; 

} 

static  void  quit (SlideBarS  menu) 

{ 

YesNo  yn("Quit"); 
if  (yn. answer) 

,  menu  ■ terrniMte  1 1 :  End  Listing  Three 

(listings  continued  on  page  154) 
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Listing  Four  (Listings  continued,  text  begins  on  page  123  ) 

II - demopop .  c 


♦include  <stddef.h> 
♦include  <conio.h> 
♦include  <stdio.h> 
♦include  "menus. h" 
♦include  "console. h" 


-  File  menu 
f menu [ ]  =  { 


II - 

static  char  * 
Load 
"-Save 
New 
Option 
Quit 
NULL 


static  void  load (PopdownMenuS ) ; 
static  void  save (PopdownMenuS) ; 
static  void  newfile (PopdownMenuS) ; 
static  void  quit (PopdownMenuS) ; 

static  void  (*ffuncs []) (PopdownMenuS)  * 

(  load,  save,  newfile,  NULL,  quit  ) ; 

void  main (void) 

< 

PopdownMenu  menu (20,  10,  fmenu,  1,  ffuncs); 


static  void  load (PopdownMenuS  menu) 

( 

Window  wnd (20, 10, 40, 20, BLACK, CYAN) ; 
wnd. title(" (Stub  Function)"); 
wnd  «  "\n\n\n\n  LOAD  A  FILE"; 

menu.enable_selection(2) ;  //  enable  the  save  command 

get key () ; 


static  void  save (PopdownMenu  Smenu) 

{ 

Window  wnd(20,  10,  40, 20, YELLOW, RED) ; 
wnd. title (" (Stub  Function)"); 
wnd  «  "\n\n\n\n  SAVE  A  FILE"; 

menu.disable_selection(2) ;  //  disable  the  save  command 

get key (); 

} 

static  void  newfile (PopdownMenu  Smenu) 

( 

Window  wnd (20, 10, 40, 20, YELLOW, RED) ; 
wnd. title (" (Stub  Function)"); 
wnd  «  "\n\n\n\n  NEW  FILE"; 

menu.enable_selection (2) ;  //  enable  the  save  command 

getkeyO  ; 


static  void  quit (PopdownMenuS  menu) 

{ 

if  (menu.test_toggle (4) ) 
menu. terminate () ; 
else  ( 

YesNo  yn("Quit">; 
if  (yn. answer) 

menu. terminate ()  ; 

} 


Listing  Five 

// - strings. h 

♦ifndef  STRINGS 
♦define  STRINGS 

♦include  <string.h> 

class  string  { 

char  ‘sptr; 
public: 

//  CONSTRUCTORS 

// - construct  a  null  string 

string (void) ; 

//  -  construct  with  a  char  *  initializer 

string (char  *s) ; 

//  -  construct  with  another  string  as  initializer 

string (strings  s); 

// - construct  with  just  a  size 

string (int  len) ; 

//  DESTRUCTOR 

'string (void)  f  delete  sptr;  } 

//  MEMBER  FUNCTIONS 

//  -  return  the  address  of  the  string 

const  char  *stradr (void)  (  return  sptr;  } 

//  SUBSTRINGS 

//  -  substring:  right  len  chars 

string  right (int  len); 

//  -  substring:  left  len  chars 

string  left (int  len); 


End  Listing  Four 


Listing  Five  (Listing  continued,  text  begins  on  page  123  ) 

II  -  substring:  middle  len  chars  starting  from  where 

string  mid (int  len,  int  where); 

//  ASSIGNMENTS 

// - assign  a  char  array  to  a  string 

void  operator= (char  *s) ; 

// - assign  a  string  to  a  string 

void  operator= (strings  s)  {  ‘this  =  s.sptr;  } 

//  CONCATENATORS 

//  -  1st  concatenation  operator  (strl  +=  char  *) 

void  operator+= (char  *s)  ; 

//  -  2nd  concatenation  operator  (strl  +=  str2;) 

void  operator+= (strings  s)  (  ‘this  +=  s.sptr;  } 

//  -  3rd  concatenation  operator  (strl  =  str2+char*;) 

string  operator+ (char  *s)  ; 

//  -  4th  concatenation  operator  (strl  =  str2  +  str3;) 

string  operator+ (strings  s)  {  return  ‘this  +  s.sptr;  } 

//  RELATIONAL  OPERATORS 

int  operator== (strings  s)  (  return  strcmp (sptr, s. sptr) ==0 
(  return  strcmp (sptr, s.sptr) !=0 
{  return  strcmp (sptr, s . sptr) <  0 
(  return  st rcmp (sptr,  s.sptr) >  0 
{  return  strcmp (sptr,  s . sptr) <=0 
(  return  strcmp (sptr,  s . sptr) >=0 


int  operator != (strings  s) 
int  operator< (strings  s) 
int  operator> (strings  s) 
int  operator<= (strings  s) 
int  operator>= (strings  s) 
int  operator== (char  *s) 
int  operator != (char  *s) 
int  operator< (char  *s) 
int  operator> (char  *s) 
int  operator<= (char  *s) 
int  operator>= (char  *s) 

//  SUBSCRIPTORS 

char  operator [) (int  n)  (  return  ‘(sptr  +  n) ; 
char*  operator+ (int  n)  (  return  sptr  +  n;  ) 


(  return  strcmp (sptr, s) ==0 
(  return  strcmp(sptr, s) !=0 
(  return  strcmp(sptr, s) <  0 
(  return  strcmp(sptr, s) >  0 
(  return  strcmp (sptr, s) <=0 
(  return  strcmp(sptr, s) >=0 


End  Listing  Five 


Listing  Six 


♦include  <stddef.h> 

♦include  <stream.hpp> 

♦include  "strings. h" 

// - construct  a  null  string 

string: :string(void) 

{ 

sptr  =  new  char; 

‘sptr  =  ' \0' ; 

} 

//  -  construct  with  a  char  *  initializer 

string: :string(char  *s) 

( 

sptr  =  new  char [strlen (s) +1] ; 
strcpy(sptr,  s) ; 

> 

//  -  construct  with  another  string  as  initializer 

string: :string (strings  s) 


sptr  =  new  char [strlen(s. sptr) +1] ; 
strcpy(sptr,  s.sptr); 


// - construct  with  just  a  size 

string: :string(int  len) 

{ 

sptr  =  new  char [len+1]; 
memsetlsptr,  0,  len+1); 

I 

// - assign  a  char  array  to  a  string 

void  string: :operator= (char  *s) 

{ 

delete  sptr; 

sptr  =  new  char (strlen (s)+l) ; 
strcpy(sptr,  s); 

> 

//  -  1st  concatenation  operator  (strl  +=  char  *;) 

void  string: :operator+= (char  *s) 

( 

char  *sp  =  new  char (strlen (sptr)  +  strlen(s)  +  1]; 

strcpyfsp,  sptr); 

strcat(sp,  s); 

delete  sptr; 

sptr  =  sp; 

) 

//  -  3rd  concatenation  operator  (strl  =  str2  +  char*;) 

string  string: :operator+ (char  *s) 

( 

string  tmp(*this); 
tmp  +=  s; 
return  tmp; 

) 

//  -  substring:  right  len  chars 

string  string: : right (int  len) 

{ 

string  tmp (sptr  +  strlen  (sptr)  -  len) ; 
return  tmp; 

) 

//  -  substring:  left  len  chars 

string  string: : left (int  len) 

{ 

string  tmp(len+l); 

strncpy (tmp.stradr () ,  sptr,  len)  ; 

return  tmp; 

} 

//  -  substring:  middle  len  chars  starting  from  where 

string  string: :mid (int  len,  int  where) 

( 

string  tmp (len+1); 

strncpy (tmp. stradr () , sptr+where-1,  len) ; 
return  tmp; 

)  End  Listings 
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OF  INTER  E  S  T 


Erik  Labs  has  released  BiModem,  a 
file  transfer  protocol  for  the  IBM  PC 
and  compatibles  that  can  send  and  re¬ 
ceive  files  simultaneously,  and  which 
allows  operators  to  chat  during  file  trans¬ 
fer.  The  protocol  is  capable  of  attaining 
transfer  speeds  over  98  percent  effi¬ 
cient  in  both  directions  at  the  same 
time.  While  many  bulletin  board  inter¬ 
faces  are  available  and  can  be  used 
with  any  communications  program  that 
permits  execution  of  an  external  pro¬ 
gram,  the  protocol  has  been  imple¬ 
mented  in  GT  POWER  (P&M  Software). 

A  modified  32-bit  CRC  and  a  32-bit 
Filesum  insure  file  accuracy,  and  the 
feature  “refresh  transfers”  compares  files 
and  sends  only  the  information  that 
has  changed.  Download  requests  can 
be  located  through  multiple  directo¬ 
ries;  files  may  be  recovered  from  either 
an  aborted  files  directory  or  the  receiv¬ 
ing  directory.  Additional  file  requests 
may  be  added  and  transfers  in  progress 
canceled  during  the  process  of  trans¬ 
ferring  files.  Doubledos  and  DesqView 
are  automatically  recognized,  giving 
time  to  other  tasks. 

The  protocol  has  the  ability  to  tag 
file  requests  from  disk  or  a  files  list,  and 
a  Hot  key  program  is  included  to  tag 
files  displayed  on  your  screen.  Trans¬ 
fer  requests  can  be  addressed  to  spe¬ 
cific  users  to  take  place  automatically 
the  next  time  they  connect.  The  price 
is  $25  ($32.50  with  laser  printed  docu¬ 
mentation).  Reader  service  no.  20. 

Erik  Labs 

3431  WThunderbird  Rd.,  Ste.  13-311 
Phoenix,  AZ  85023 
602-942-5403 

602-979-5720  (bulletin  board) 

Matrix  Software  Technology  has  in¬ 
troduced  a  telecommunications  black  box 
called  “BlackBox”  that  contains  a  series 
of  objects  that  support  communications 
between  computers  via  modem  or  di¬ 
rect  connection.  This  enables  users  to 
add  independent  telecommunications 
sessions  and  sophisticated  scripting  to 


their  Layout  programs.  “Inside  every 
BlackBox,”  according  to  Vincent  Garo- 
falo,  president  of  Matrix,  “our  software 
engineers  have  built  a  set  of  the  most 
wanted  capabilities.  Rather  than  rein¬ 
venting  the  wheel,  our  users  can  con¬ 
centrate  on  building  better  applications.  ” 

BlackBoxes  are  software  objects  that 
users  can  manipulate  in  Layout.  It  is 
unnecessary  for  users  to  know  what  is 
happening  inside  the  object  —  they  can 
concentrate  instead  on  connecting  Black- 
Boxes  with  other  objects  on  their  cards. 

Inside  the  BlackBox,  Layout  employs 
objects  that  perform  complex  functions, 
which  allows  users  to  add  a  range  of 
capabilities  in  a  particular  area  when 
they  create  their  applications.  These 
include  functions  for  electronically  ex¬ 
changing  text,  documents,  programs, 
and  graphics  between  two  different  com¬ 
puters.  Additional  objects  are  phone 
book  management,  VT100  temninal  emu¬ 
lation,  and  a  graphical  scripting  capa¬ 
bility  (which  facilitates  the  design  of 
programs  that  allow  users  to  outline  a 
series  of  steps  based  on  the  telecom¬ 
munications  dialog).  The  individual, 
modular  nature  of  the  BlackBox  makes 
it  easy  for  users  to  incorporate  one  or 
more  of  these  capabilities  as  they  build 
their  programs. 

At  the  same  time,  Matrix  is  introduc¬ 
ing  a  dBase  BlackBox  to  create  stan¬ 
dard  user  interfaces.  Both  are  priced 
at  $69-95,  and  run  with  Matrix  Layout, 
Version  2.0,  now  available  for  $199.95. 
Layout  and  the  BlackBoxes  both  run 
on  all  IBM  PCs,  PS/2s,  and  compa¬ 
tibles,  with  support  for  all  major  graph¬ 
ics  cards.  A  mouse  is  optional.  Reader 
service  no.  21. 

Matrix  Software  Technology 
Corporation 

1  Massachusetts  Technology  Center 

Harborside  Drive 

Boston,  MA  02128 

800-533-5644 

617-567-0037  (in  Mass.) 

The  Santa  Cruz  Operation  Inc.  (SCO) 

has  begun  shipping  SCO  Unix  System 
V/386,  Release  3-2,  a  full-featured  addi¬ 
tion  to  the  SCO  System  V  family  of 
products  that  addresses  the  need  for 
standards  and  security  in  a  commercial 
Unix  system.  SCO  Unix  System  V/386 
also  runs  on  486-based  systems,  and  is 
the  foundation  of  Open  Desktop,  SCO’s 
integrated  operating  environment  for 
386-  and  486-based  PCs. 

SCO  Unix  System  V/386  features  easy- 
to-use,  menu-based  setup  and  admini¬ 
stration  compatible  with  SCO  Portfo¬ 
lio,  FIPS  151.1  conformance,  X/Open 
conformance,  ANSI  8-bit  internationali¬ 
zation,  enhanced  security,  file  system 
improvements,  SCO  device  drivers  that 


support  dozens  of  standard  peripher¬ 
als,  and  the  highest  level  of  compatibil¬ 
ity  with  SCO  Xenix  applications. 

SCO  Unix  System  V/386  includes  im¬ 
proved  versions  of  the  custom  utility, 
on-line  documentation,  and  an  inte¬ 
grated  system  administration  shell.  It 
also  offers  users  a  new,  streamlined 
installation  procedure,  a  mail  system 
that  allows  communication  with  a  vari¬ 
ety  of  electronic  mail  systems,  a  badtrk 
utility  so  users  can  enter  the  manufac¬ 
turer’s  hard  disk  defect  list,  and  an  in¬ 
teractive  configure  program  that  makes 
it  easy  to  tune  the  system’s  configura¬ 
tion  and  add  or  delete  device  drivers. 
And  more  tutorials,  expanded  refer¬ 
ence  sections,  extensive  examples,  as 
well  as  a  road  map  and  quick-refer¬ 
ence  guide  are  included. 

The  SCO  Unix  System  V/386  devel¬ 
opment  system  contains  MS-DOS  and 
OS/2  cross-development  features;  full 
COFF  and  OMF  support;  IEEE  Posix, 
ANSI  C,  X-Open,  and  C2-security  li¬ 
braries;  the  Microsoft  5.0  C  compiler; 
the  AT&T  C  compiler;  Microsoft  Code¬ 
View;  and  SCO  CGI  graphics  develop¬ 
ment  tools.  The  package  also  includes 
a  guide  to  device  drivers,  which  anno¬ 
tates  examples  of  all  classes  of  device 
drivers,  line  disciplines,  streams,  and 
file  systems. 

It  is  available  for  386  IBM  AT-com- 
patible  systems  equipped  with  an  AT- 
compatible  ESDI  or  SCSI  disk  control¬ 
ler.  It  will  soon  be  available  for  IBM 
PS/2  models  55SX,  70,  and  80,  and  for 
Micro  Channel  compatibles.  The  list 
price  for  the  two-user  version  is  $595; 
the  unlimited  multiuser  version  is  $895. 
Upgrades  are  also  available.  Reader  ser¬ 
vice  no.  22. 

The  Santa  Cruz  Operation,  Inc. 

400  Encinal  St.,  P.O.  Box  1900 
Santa  Cruz,  CA  95061 
408-425-7222 

Jensen  &  Partners  International  Inc. 

are  shipping  a  new  TopSpeed  Modula-2 
Communications  Toolkit  that  is  designed 
to  help  programmers  write  applications 
that  use  IBM  PC  serial  port  hardware. 
The  toolkit  was  written  entirely  in 
Modula-2,  and  gives  access  to  a  wide 
range  of  capabilities,  from  utilizing  hard¬ 
ware  registers  to  terminal  emulation. 

The  Communications  Toolkit  pro¬ 
vides  for  low-level  device  driving.  Pro¬ 
cedures  in  the  RS-232  module  allow 
you  to  select  and  initialize  any  of  four 
hardware  ports,  test  for  carrier,  install/ 
uninstall  the  serial  interrupt  handler, 
select  XON/XOFF  or  RTS/CTS  flow  con¬ 
trol,  perform  serial  read  and  write,  and 
assert  the  break  signal  to  the  modem 
interface. 

(continued  on  page  166) 
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(continued  from  page  158) 

Procedures  in  the  file  transfer  sup¬ 
port  module  include  status  window  sup¬ 
port  to  monitor  the  transfer  status,  and 
sending  and  receiving  data  via  XModem, 
YModem,  windowed  XModem,  and  Ker- 
mit  protocols. 

Applications  support  includes  rou¬ 
tines,  macro  transmission  procedures, 
timer  routines,  and  VT100,  VT52,  and 
BBS  ANSI  terminal  emulation.  There 
are  also  procedures  for  testing  and  set¬ 
ting  logging  modes,  reading,  writing, 
and  printing  files,  file  selections,  and 
parsing  and  building  file  names. 

Scripting  for  automatic  logon  to  re¬ 
mote  services  includes  a  compiled  script 
language  with  commands  for  loading 
new  scripts,  condition  testing,  screen 
clearing,  downloading/uploading  files, 
manipulating  log  files,  transmitting/ 
receiving  strings  to  the  modem  inter¬ 
face  or  keyboard,  and  more. 

The  Communications  Toolkit  includes 
over  8000  lines  (260K)  of  source  code 
for  21  modules.  There  is  documentation 
on  the  8250  UART,  cabling  information 
for  PC  XT  and  AT,  and  a  demonstration 
program. 

TopSpeed  is  also  shipping  a  Modu¬ 
la-2  B-tree  Toolkit  with  tools  for  writ¬ 
ing  powerful  database  applications. 
Both  toolkits  sell  for  $79.95  each.  Reader 
service  no.  23. 

Jensen  &  Partners  International,  Inc. 
1101  San  Antonio  Rd.,  Ste.  301 
Mountain  View,  CA  94043 
800-543-5202  (inside  U.S.) 
800-543-8452  (inside  Canada) 

FORTH  Inc.  has  released  pF/x,  a  real¬ 
time  multiuser,  multitasking  operating 
system  in  a  version  designed  to  run 
coresident  with  PC/MS-DOS  on  80386- 
based  systems.  “pF/x  will  support  as 
many  concurrent,  asynchronous  tasks 
and  users  as  the  80386  will  allow,” 
according  to  spokesperson  Mary  Hawk¬ 
ins,  and  “is  ideal  for  developing  appli¬ 
cations  such  as  instrumentation,  pro¬ 
cess  control,  industrial  sensors,  and  any¬ 
where  else  there  is  a  need  for  real-time 
data  acquisition,  analysis,  and  control.” 

pF/x  is  compatible  with  PC/MS-DOS, 
Versions  3-3  and  higher.  It  normally  runs 
in  protected  mode,  but  transparently 
switches  to  compatibility  mode  when 
accessing  system  resources.  It  can  in¬ 
crease  processing  speed  by  linking  time- 
critical  interrupt  routines  directly  to  the 
hardware  interrupt  vectors  (for  zero 
interrupt  latency),  and  takes  only  9.28 
microseconds  for  a  multi-tasker  loop 
of  two  tasks  on  a  25  MHz  80386. 

pF/x  is  part  of  the  polyForth  devel¬ 
opment  environment,  which  features 
the  Forth  language,  macro-assemblers 
for  the  80386  and  80387,  editor,  target 


and  turnkey  compilers,  graphics,  data¬ 
base  support,  and  utilities.  pF/x  costs 
$3850.  Reader  service  no.  27. 

FORTH,  Inc. 

Ill  N.  Sepulveda  Blvd. 

Manhattan  Beach,  CA  90266 
800-55-FORTH;  213-372-8493 

Lattice  Inc.  has  released  the  new  Lat¬ 
tice  Communications  Library,  which 
they  claim  is  a  comprehensive  set  of 
high-level  and  low-level  C  functions 
for  creating  applications  that  perform 
asynchronous  communications. 

“The  library  supports  DOS,  OS/2,  and 
AmigaDOS  environments  with  a  full  set 
of  functions  for  XModem,  YModem,  Ker- 
mit,  and  ASCII  protocols,”  according  to 
Robert  Hansen,  Lattice  vice  president. 
Functions  included  in  the  library  give 
programmers  the  ability  to  select,  open, 
and  close  a  communications  port;  set 
baud  rate,  data  bits,  parity,  stop  bits, 
and  buffer  size;  and  send  and  receive 
characters  from  the  communications 
port.  Other  functions  dial  and  hang  up 
the  telephone;  reset  the  modem;  set 
automatic  answering;  send  and  receive 
files  using  ASCII,  XModem,  YModem, 
or  Kermit  error-checking  protocols;  and 
display  the  progress  of  file  transfers. 

The  price  is  $250,  with  source  code 
available  for  an  additional  $250.  It  sup¬ 
ports  Lattice  C,  Version  3-4.  Versions 
for  Microsoft  and  Turbo  C  compilers, 
as  well  as  an  AmigaDOS  version,  are 
also  available.  Lattice  will  include  the 
library  in  Version  6.0  of  the  Lattice  C 
Compiler  for  DOS  and  OS/2.  Reader 
service  no.  24. 

Lattice,  Inc. 

2500  South  Highland  Ave. 

Lombard,  IL  60148 
312-916-1600 

Addison- Wesley  has  published  the  Ap¬ 
ple  Communications  Library,  a  new  se¬ 
ries  by  Apple’s  networking  and  com¬ 
munications  publications  department 
that  addresses  computer  networking, 
and  includes  books  for  newcomers  to 
networking  as  well  as  for  programmers 
and  developers. 

AppleTalk  Network  System  Overview , 
$14.95  in  paperback,  is  part  of  the  Li¬ 
brary  Reference  series,  and  describes 
different  Apple  networking  products 
and  how  they  fit  together  in  a  system. 
This  book  is  for  those  new  to  Apple’s 
networking  product  line,  and  is  de¬ 
signed  to  assist  developers,  network 
administrators,  and  managers  in  deci¬ 
sion-making  for  product  development 
and  purchases.  Subjects  include  cabling 
methods,  the  sharing  of  files  and  print¬ 
ers,  and  components  of  the  AppleTalk 
network  system. 

Inside  AppleTalk  $34.95  in  hardcover, 


is  in  the  Library  Technical  series,  and 
is  a  current  technical  guide  to  the  Ap¬ 
pleTalk  network  system  for  program¬ 
mers  and  developers.  The  book  de¬ 
scribes  AppleTalk’s  protocol  architec¬ 
ture,  providing  programmers  with  the 
information  they  need  to  keep  their 
software  and  hardware  compatible  with 
the  AppleTalk  network  system.  It  cov¬ 
ers  topics  such  as  physical  and  data 
link  alternatives,  transmission  between 
nodes,  handling  addressing  discrepan¬ 
cies,  facilitating  end-to-end  transmis¬ 
sion  of  data,  and  end-user  services  im¬ 
plementation. 

These  books  and  others  in  the  series 
are  available  wherever  computer  books 
are  sold.  Reader  service  no.  25. 
Addison- Wesley  Publishing  Company 
Reading,  MA  01867 
617-944-3700 

American  Megatrends  Inc.  (AMI)  an¬ 
nounces  AMIDIAG,  a  menu-driven  di¬ 
agnostic  utility  for  286-  and  386-based 
IBM  PCs  and  compatibles.  According 
to  AMI,  AMIDIAG  exhaustively  tests  all 
hardware  subsystems,  including  moth¬ 
erboard,  memory,  hard  disk  drives, 
floppy  disk  drives,  keyboard,  video 
adapter,  monitor,  printer  port,  and  se¬ 
rial  port. 

AMIDIAG  features  easy-to-use  menus, 
English-language  diagnostic  messages, 
user-configurable  test  routines,  error 
logging,  graphic  display  of  the  location 
of  defective  DIP  and  SIMM  memory 
chips,  and  a  choice  of  continuous,  time- 
bound,  or  count-bound  testing  in  batch 
or  interactive  modes. 

Hard  disk  tests  for  hard  disk  control¬ 
lers  using  MFM  and  ESDI  data  encod¬ 
ing  include  media  analysis,  force  bad 
tracks,  data  transfer  rate,  track-to-track 
seek  time,  seek  test,  read/verify  test,  and 
check  cylinder  test.  Users  can  either  se¬ 
lect  from  the  first  46  drive  types  defined 
in  the  machine’s  ROM  BIOS  or  define 
their  own.  AMIDIAG  can  also  perform 
partial  or  full  hard  disk  formatting,  with 
optional  optimized  interleave  for  faster 
performance.  Floppy  drive  tests  include 
random  and  sequential  read/write,  disk 
change  line  test,  and  speed  test. 

AMI  president  S.  Shankar  says  that 
“AMIDIAG  can  diagnose  defective  mem¬ 
ory  chips,  bad  hard  disk  sectors,  and 
other  critical  subsystems  before  they 
become  a  problem.”  AMIDIAG  retails 
for  $99-  A  monitor  ROM  and  diagnos¬ 
tics  card  is  also  available,  for  $995. 
Reader  service  no.  29- 
AMI 

1346  Oakbrook  Dr.,  Ste.  120 
Norcross,  GA  30093 
404-263-8181 
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Desultory  Philippic  #41 

In  July  I  did  some  work  for  a  computer-industry  veteran  who  had  an  idea  for  a  new  business: 
Selling  a  product  based  on  recent  research  in  an  exciting  and  active  new  area  of  science.  You 
would  recognize  his  name,  but  he  doesn’t  want  any  premature  publicity  for  his  business  — 
whose  prospects  now  look  pretty  grim,  anyway  —  so  I’Ll  just  call  him  Will. 

Will  had  done  his  homework:  He  had  lined  up  a  respected  professor  doing  significant  work  in 
this  area  of  science  at  a  prestigious  school,  who  would  act  as  technical  consultant  and  lend  his 
name  to  the  product;  he  had  researched  the  legal  implications  of  the  business;  he  had  analyzed 
production  issues,  including  how  to  maintain  laboratory-level  quality  control;  he  had  talked  to 
potential  suppliers;  and  he  had  written  a  business  plan.  When  he  was  confident  that  he  had  his  act 
together,  he  called  researchers  at  the  leading  research  institute  in  this  area  of  science,  and  arranged 
to  meet  them  to  discuss  his  plans.  The  support  of  this  institute  was  critical  to  Will’s  business  plan, 
because  it  was  the  only  source  of  certain  components  of  the  product  he  wanted  to  sell.  He  explained 
to  them,  rather  eloquently  I  think,  how  his  product  would  raise  public  consciousness  regarding 
their  work,  begin  the  vital  process  of  educating  the  public  about  this  important  area  of  science  and 
the  vast  potential  it  has  for  improving  the  quality  of  life,  even  for  extending  the  human  life  span. 

Cold  is  the  word  for  the  reaction  he  got:  The  researchers,  including  the  Nobel  laureate  who  directs 
the  lab,  are  afraid  of  adverse  public  reaction  to  their  work.  Paranoia  springs  eternal  in  the  human 
breast  —  and  is  usually  justified,  too.  The  researchers  harbor  the  conviction  that  the  public  has  little 
interest  in  science  other  than  a  blind,  unreasoning  fear  of  it;  and  they  back  up  their  conviction  with 
empirical  data. 

I  am  inclined  to  think  that  Will’s  product  would  have  had  a  healthy  effect,  raising  public 
awareness  of  important  scientific  issues.  I  can’t  say  that  the  researchers  were  wrong,  though; 
ignorance  and  fear  feed  one  another,  and  the  general  public  is  ignorant  and  fearful  of  modern 
science.  But  isn’t  it  obvious  that  the  place  to  break  the  cycle  is  with  kids?  Where  are  the  chemistry 
sets  and  science  kits  that  past  generations  of  American  kids  grew  up  with?  Computers  are 
technology,  not  science,  but  they  are  also  a  delivery  medium  for  getting  science  into  the  home. 
That’s  what  Will  wanted  to  do.  I  hope  some  of  you  want  the  same  thing  and  have  better  luck. 


I’m  launching  a  newsletter  devoted  to  HyperCard  issues,  a  sort  of  Writer’s  Digest  for  the  stackware 
market,  with  scripting  tutorials  and  advanced  user  information.  (Anyone  interested  can  get  more 
information  from  me  at  Card  Tricks,  31  Patrick  Road,  Santa  Cruz,  CA  95060.)  It  was  while 
considering  how  best  to  review  stacks  for  the  newsletter  that  I  confronted  the  dilemma  (for  a 
reviewer,  anyway)  that  software  is  becoming  less  like  cameras  and  more  like  movies.  The 
appropriate  response  for  computer  magazines,  at  least  for  computer  software  magazines,  is  to 
become  less  like  camera  magazines  and  more  like  film  magazines. 

It’s  still  of  some  value  to  tick  off  the  features  and  run  the  benchmarks,  of  course.  PC  Magazine 
has  made  a  fortune  for  Ziff-Davis  with  those  huge  tables  of  checkmarks  detailing  every  tallyable 
fact  about  every  laser  printer  paper  tray. 

But  the  more  subjective  aspects  of  software  evaluation  are  growing  in  importance.  Depth,  general 
appropriateness  to  the  task,  ease  of  use  and  learning,  responsiveness,  and  intuitiveness  have  always 
been  able  to  make  or  break  a  product,  regardless  of  the  number  of  checkmarks  it  got  in  the  feature 
tables.  For  some  games,  responsiveness  and  realism  are  everything.  But  for  many  products  it  is 
becoming  increasingly  important  to  deliver  a  well-crafted  work  rather  than  a  bag  of  nifty  features. 

It  might  not  be  stretching  definitions  too  far  to  say  that  it’s  the  difference  between  reviews  and 
criticism.  Henry  James,  who  was  both  author  and  critic,  said,  “The  practice  of  ‘reviewing’ . .  .  has 
nothing  in  common  with  criticism  ....  To  criticize  is  to  appreciate,  to  appropriate,  to  take 
intellectual  possession,  to  establish  ...  a  relation  with  the  criticized  thing  and  to  make  it  one’s 
own."  The  software  authors  of  the  1990s  will  deserve  criticism,  and  there  is  no  such  thing  in 
computer  publishing  today.  There  could  be.  There  should  be. 

Michael  Swaine 
editor-at-large 
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A  C  Special 
Issue  and  A 
Quick  Look  at 
History 


For  the  last  couple  of  months,  it’s  been  busy  around  here,  real  busy  in  fact.  Between  getting 
out  the  regular  issue  and  the  Macintosh  special  issue  (which  you  should  have  in  your  hands 
by  now  if  you  ordered  it)  and  attending  any  number  of  important  conferences  (such  as 
OOPSLA),  it  generally  seems  that  there  aren’t  enough  hours  in  a  day,  days  in  a  week,  or  bits  in  a 
byte. 

On  top  of  everything,  we've  been  working  on  a  second  special  issue  that  I  think  really  is 
special  —  Dr.  Dobb 's  C  Sourcebook  for  the  1 990s.  In  this  C  sourcebook,  we’ll  be  looking  at  the 
direction  C  will  take  over  the  coming  years  while  —  in  the  same  issue  —  providing  the  kind  of 
practical  C  tools  and  utilities  that  you  can  use  today. 

What’s  in  the  C  special  issue?  For  starters,  A1  Stevens,  our  C  columnist,  made  the  pilgrimage 
to  AT&T  Bell  Labs  where  he  talked  first  with  Dennis  Ritchie,  then  with  Bjarne  Stroustrup  about  C 
and  C++,  respectively.  They  discussed  how  and  why  C  has  evolved,  and  where  the  languages  will 
be  going  in  the  future. 

The  interviews  aren’t  Al’s  only  contribution  to  the  issue,  however.  He  also  contributed  “A 
C  Programmer's  Guide  to  C++,"  one  of  several  C++  related  articles,  all  of  which  cover  the  recently 
released  C++  2.0  specification.  In  yet  another  article,  Narain  Gehani  and  Bill  Roome,  architects  of 
Concurrent  C  (and  authors  of  an  article  in  the  issue  of  DDJ you're  reading  right  now),  discuss 
discrete  event  simulation  and  Concurrent  C. 

Even  though  the  articles  alluded  to  above  are  generally  forward-looking,  we  aren’t  neglecting  the 
tools  C  programmers  need  now.  To  begin  with,  we  revisited  one  of  the  more  popular  C  articles 
we’ve  run  in  recent  years:  Stewart  Nutter’s  “Automatic  Module  Control  In  C”  (August  1988).  In  this 
latest  incarnation,  Stewart’s  program  is  a  launching  pad  for  Ron  Winter,  who  uses  his  version  to 
maintain  nearly  100,000  lines  of  code.  Other  bread-and-butter  articles  in  the  issue  include  Paul 
Anderson’s  piece  on  customized  memory  allocators,  a  feature  on  debugging  the  stack  in  C,  the 
source  code  for  a  general-purpose  list  manager,  and  more.  In  total,  over  4000  lines  of  C  source 
code  are  listed  in  the  magazine,  all  of  which  are  available  from  the  £>Z)/Forum  on  CompuServe,  the 
DDJ  listing  service,  or  on  disk. 

When  will  the  C  special  issue  be  available?  At  the  same  time  as  our  regular  January  issue, 
which  translates  to  around  the  first  or  second  week  in  December. 

How  do  you  get  your  copy  of  the  C  Sourcebook?  Here’s  the  best  part:  We're  bundling  it  with 
the  January  issue,  so  if  you’re  a  subscriber,  you  ’ll  get  it  free.  Two  magazines  —  the  regular  and  the 
special  —  for  the  price  of  one.  For  those  who  usually  get  .£>£>/ off  the  newsstand,  the  special  issue 
will  also  be  available  on  newsstands  or  it  can  be  ordered  directly. 

And  Now  for  the  History  Lesson 

In  his  interviews  with  Dennis  and  Bjarne,  A1  records  some  of  the  history  of  why  C  and  C++  have 
evolved  the  way  they  have.  It’s  easy  to  forget  that  a  technology  as  young  as  computing  has  a  history, 
but  it  does,  and  that  history  should  be  documented.  Although  our  mission  isn’t  to  provide  a 
narrative  of  the  computing  industry,  doing  so  is  a  natural  outgrowth  of  our  goal  (that  is,  to  serve 
as  a  communication  medium  for  the  exchange  of  ideas  and  information  among  serious  program¬ 
mers). 

Stop  and  think  about  it.  Fortran  has  been  around  for  30  or  so  years,  Cobol  about  the  same.  This 
year  is  the  25th  anniversary  of  Basic.  Gary  Kildall  wrote  PL/1  nearly  20  years  ago.  C  was  designed 
about  the  same  time  (and  B,  C’s  predecessor,  was  created  10  years  before  that).  Pascal,  Modula-2, 
Forth,  and  a  host  of  other  languages  have  come  on  the  scene  since  then.  1990  will  be  DDJ s  15th 
year.  Tiny  Basic,  Small  C,  Dr.  Dobb ’s  Journal  of  Computer  Calisthenics  &  Orthodontia.  Fifteen  years 
is  a  long  time,  and  a  lot  of  history  has  passed  between  our  covers  in  the  meantime.  Dr.  Dobb’s  C 
Sourcebook  continues  this  tradition. 

I’ll  close  by  mentioning  that  Mike  Swaine  recently  told  me  he  and  Paul  Freiberger,  his  coauthor 
for  Fire  In  the  Valley,  the  wonderful  history  of  PCs  published  in  1984,  have  approached  their 
publisher  about  updating  the  book.  Here’s  my  two  cents  worth  to  the  publisher:  Do  it.  A  lot  has 
happened  over  the  past  four  or  five  years  that  needs  to  be  chronicled.  I’ll  buy  a  copy  of  the  second 
edition,  and  I’ll  bet  that  a  lot  of  others  will  too. 


Jonathan  Erickson 
editor-in-chief 
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It’s  Binary  Trees,  Not  B-trees 

Dear  DDJ 

The  article,  “Setting  Precedence,"  Sep¬ 
tember  1989,  misused  the  term  “B-tree” 
in  place  of  binary  tree.  A  naive  reader 
might  understand  these  references  ter 
be  to  binary  search  trees  instead  of 
what  they  actually  are.  B-trees  and  their 
variants  (B+  trees)  are  balanced  multi¬ 
way  trees  used  to  form  indexes  for 
large  data  files.  The  term  B-tree  was 
first  used  in  1972  by  its  developers, 
Bayer  and  McCreight,  to  describe  a  way 
of  forming  a  multiway  tree  from  the 
bottom  up  so  that  it  was  always  bal¬ 
anced.  Bayer  and  McCreight  have  never 
revealed  the  origin  of  the  name;  the  B 
could  stand  for  balanced,  broad,  Boe¬ 
ing  (their  employer  at  the  time),  Bayer, 
or  could  be  from  some  inside  joke.  By 
the  way,  an  exceptionally  clear  presen¬ 
tation  of  the  B-tree  concept  is  in  Folk 
and  Zoellick’s  File  Structures:  A  Con¬ 
ceptual  Toolkit.  This  presentation  also 
includes  a  large  amount  of  C  code. 

Terry  Johnson 

Stillwater,  Oklahoma 

Dear  DDJ, 

In  “Setting  Precedence”  by  Mark  Peter¬ 
son  (September  1989),  the  author  uses 
the  term  “B-tree”  when  he  means  “bi¬ 
nary  tree.”  Real  B-trees  are  rarely  binary 
and  are  always  balanced.  A  definition  of 
B-tree  can  be  found  in  Donald  Knuth's 
The  Art  of  Computer  Programming,  Vol¬ 
ume  3/Sorting  and  Searching,  p.  473; 
A  B-tree  of  order  m  is  a  tree  which 
satisfies  the  following  properties: 

i)  Every  node  has  <=  m  sons. 

ii)  Eveiy  node,  except  for  the  root 
and  leaves,  has  >=m/2  sons. 

iii)  The  root  has  at  least  2  sons 
(unless  it  is  a  leaf). 

iv)  All  leaves  appear  on  the  same 
level,  and  carry  no  information. 

v)  A  nonleaf  node  with  k  sons  con¬ 
tains  k-1  keys. 

Further  on  in  the  article  are  the  descrip¬ 
tion  and  figure  of  a  full  4-bit  binary 


tree.  The  author  says  there  are  only- 
two  such  trees,  when  it  seems  to  me 
there  are  16.  This  stems  from  the  fact 
that  there  must  be  one  leaf  at  a  level 
lower  than  all  others,  which  is  shown 
in  Figure  3  as  the  node  numbered  0. 
However,  that  lower  leaf  could  be  any 
value  from  0  to  15. 

While  maintaining  balanced  trees  can 
improve  efficiency,  one  should  not  jump 
at  the  chance  in  every  case.  With  ran¬ 
dom  input,  ordered  trees  tend  to  stay 
remarkably  balanced  by  themselves.  In 
an  application  such  as  compiler  sym¬ 
bol  tables,  additional  work  for  balanc¬ 
ing  would  normally  be  wasted.  Each 
application  must  be  evaluated  individu¬ 
ally  to  determine  if  maintaining  bal¬ 
ance  is  worthwhile. 

Tim  Paterson 

Renton,  Washington 

CP/M  Lives! 

Dear  DDJ, 

In  his  letter  printed  in  your  September 
issue,  Arpad  Elo  Jr.  said  that  he  had 
decided  to  write  a  TECO  editor  for 
CP/M.  Please  allow  me  to  save  him  the 
trouble:  I  wrote  such  a  beast  about  12 
years  ago.  Called  TED,  this  program 
could  be  considered  a  superset  of  TECO 
editors  found  on  TOPS-10  and  RT-11 
systems  (except  for  the  screen-oriented 
features).  Among  other  things,  it  has 
extended  Q-register  functions,  includ¬ 
ing  the  ability  to  use  any  Q-register  as 
the  editing  buffer. 

TED  occupies  about  13K  of  code 
space.  Although  it  was  at  first  a  com¬ 
mercial  offering,  it  has  long  been  freely 
available  through  bulletin  board  sys¬ 
tems  and  on  conferencing  systems  such 
as  BIX.  One  caveat:  it  only  runs  on 
Z-80  based  CP/M  systems. 

Mark  E.  Mallett 

Litchfield,  New  Hampshire 

PS:  Though  I  remember  TECO  fondly, 
I’m  a  longtime  EMACS  convert. 


A  *  Heuristics 

Dear  DDJ 

I  have  just  finished  reading  Randy 
Nevin's  article  “Autorouting  with  the 
A*  Algorithm”  in  the  September  1989 
issue  of  DDJ.  I  am  very  pleased  to  see 
heuristic  search  and  its  applications  re¬ 
ceiving  coverage  in  your  fine  journal. 

I  would,  however,  like  to  add  some 
comments  on  A*,  and  additionally,  its 
heuristic  function,  H(x).  First,  readers 
may  be  interested  in  knowing  that  the 
BFS  (Breadth-First  Search)  algorithm 
is  actually  a  special  case  of  A*,  ob¬ 
tained  by  setting  H(x)  =  0  and  dis- 
tance(pred(x),x )  =  1  for  all  nodes  x 
(the  notation  is  as  defined  in  Figures  1 


and  3  of  Nevin’s  article).  Second,  the 
A*  algorithm  always  terminates  with  a 
solution  whenever  one  exists  (such  an 
algorithm  is  said  to  be  “complete”). 
This  property  holds  regardless  of 
whether  A’  is  applied  to  finite  or  infi¬ 
nite  graphs.  Finally,  if  the  heuristic  func¬ 
tion,  H(x),  used  by  A*  is  optimistic, 
that  is,  if  H(x)  always  underestimates 
(or  exactly  estimates)  the  cheapest  cost 
of  a  path  going  from  node  x  to  a  goal 
node  (such  a  heuristic  is  typically  la¬ 
beled  “admissible”),  then  A*  is  guaran¬ 
teed  to  find  the  optimal  solution  path 
whenever  a  solution  path  exists.  Fur¬ 
ther  constraints  on  H(x)  yield  even 
stronger  results  pertaining  to  the  num¬ 
ber  of  nodes  expanded  by  (and  hence 
the  ain-time  of)  A*.  The  interested  reader 
is  referred  to  Heuristics:  Intelligent 
Search  Strategies  for  Computer  Prob¬ 
lem  Solving,  by  Judea  Pearl  (Addison- 
Wesley:  Reading,  Mass.,  1984), 

Andrew  R.  Spillane 
University  of  Virginia 
Charlottesville,  Virginia 

CA  for  the  Rest  of  Us 

Dear  DDJ, 

This  is  just  a  note  to  update  your  read¬ 
ers  on  the  current  state  of  cellular  auto¬ 
mation  simulators  (as  mentioned  in  the 
sidebar  to  the  article  on  “Simulated  An¬ 
nealing”  by  Michael  McLaughlin  in  your 
September  1989  issue). 

Autodesk  Inc.  is  now  shipping  CA 
Lab,  also  known  as  Rudy  Rucker’s  Cel¬ 
lular  Automata  Laboratory.  CA  Lab  runs 
on  a  PC  clone  with  CGA,  and  updates 
320  x  200  pixels  several  times  a  sec¬ 
ond.  CA  Labs  supports  either  bits  per 
pixel,  and  new  rules  can  be  pro¬ 
grammed  in  C,  Pascal,  or  Basic. 

Rudy  Rucker 
Mathenaut,  Autodesk 
Sausalito,  California 

APL  Deserves  Some  Respect . . . 

Dear  DDJ, 

In  general,  I  agree  with  most  of  the 
technical  articles  in  journals  such  as 
yours.  However,  I  believe  the  column 
by  Jeff  Duntemann  in  the  August  1989 
issue  contains  at  least  one  misleading 
statement. 

APL  is  my  favorite  language,  and  I 
don’t  think  it’s  weird.  In  fact,  it  is  more 
powerful  and  concise  than  any  lan¬ 
guage  mentioned  in  your  journal.  At 
one  of  our  SIG/APL  meetings  some 
time  ago,  we  were  told  by  an  IBM 
employee  that  APL  is  used  there  inter¬ 
nally  for  almost  everything,  then  con¬ 
verted  to  Cobol,  Fortran,  etc.  as  needed 
for  the  outside. 

W.  S.  (Bill)  Cook 
Marina  Del  Rey,  California 

(continued  on  page  12) 
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....  And  So  Does  Oberon 

Dear  DDJ , 

In  his  July  1989  “Structured  Program¬ 
ming”  column,  Jeff  Duntemann  men¬ 
tioned  Niklaus  Wirth's  new  language, 
Oberon.  Considering  the  quality  of 
Wirth’s  previous  languages,  I  think  that 
any  new  language  he  develops  should 
be  examined.  I  believe  the  chances  are 
that  it  will  be  found  to  be  an  excellent 
language. 

I  would  like  to  see  a  discussion  of  it 
in  DDJ ,  or  at  least  a  mention  of  how 
more  information  about  it  can  be  ob¬ 
tained. 

Brian  Jedrick 
Nutley,  New  Jersey 

Another  Country  Heard  From 

Dear  DDJ 

I  am  writing  from  distant  country,  from 
Poland.  In  my  country  there  are  sub¬ 
scribers  of  Dr.  Dobbs  Journal  too.  We 
take  pleasure  in  informing  you  that  in 
our  opinion  DDJ  is  a  journal  on  very 
high  programming  level  and  full  of  tips 
and  tricks. 

I  am  a  student  and  a  member  of  a 
student  computer  circle.  We  have  AT 
and  XT  compatibles.  We  are  very  inter¬ 
ested  in  C  language  and,  for  this  rea¬ 
son,  in  A1  Steven’s  C  column.  (Among 
other  programs,  we  have  the  incred¬ 
ible  Turbo  C  2.0).  Al  has  developed  the 
communication  program  Smallcom.  In 
our  country,  private  communication  via 
modems  is  rising  now  (there  are  some 
mailboxes  like  Fido  net).  His  program 
is  ideal  for  us  (the  cheapest,  but  pow¬ 
erful!).  We  have  tried  it  to  run.  But  here 
the  troubles  have  arisen.  Unfortunately 
we  don’t  have  some  of  the  source  code 
for  libraries  TWRP,  context  sensitive 
help,  and  windows  {DDJ September  to 
December  1988  issues).  Could  you  do 
us  a  favor?  Can  you  send  us  copies 
(reprints)  of  that  source  code  from  DDJ 
Sept.  -  Dec.  1988  with  Al  Stevens’s  arti¬ 
cles?  It  is  the  only  way  for  us  to  obtain 
needed  source  code  and  his  explana¬ 
tion  to  it  (our  DDJ  is  a  gift  subscription). 

That’s  all  for  now.  I  sincerely  hope 
you  will  be  able  to  help  us  in  these 
matters.  We  wish  you  to  keep  the  DDJ 
as  it  is!  Best  wishes  to  you  all  the  edi¬ 
tors  of  DDJ.  I  am  looking  forward  to 
hearing  from  you. 

Artur  Terech 
Krakow,  Poland 

DDJ:  The  source  code  and  copies  of  the 
articles  you  need  are  in  the  mail. 

Finite  State  Machines  Are 
Fine  by  Me 

Dear  DDJ, 

I  found  the  article  on  procedure  tables 


by  Tim  Berens  in  DDJ  #154  (August 
1989)  quite  interesting.  I  have  to  con¬ 
fess  that  I  have  not  used  pointers  to 
functions  in  C  as  much  as  I  probably 
should  because  I  found  the  syntax  of 
pointers  a  bit  messy  and  confusing,  but 
they  are  a  powerful  tool  that  I  should 
have  in  my  programming  toolbox.  One 
application  for  an  array  of  pointers  to 
functions  is  to  implement  a  finite  state 
machine. 

For  the  benefit  of  those  not  familiar 
with  the  finite  state  machine  I  should 
explain  that  the  concept  is  that  the 
program  has  a  limited  (finite)  number 
of  states  or  modes  and  behaves  differ¬ 
ently  in  each  state  or  mode.  For  exam¬ 
ple  I  am  using  the  vi  text  editor  to  write 
this  letter.  At  the  moment  it  is  in  text 
entry  mode  and  if  I  were  to  type  a 
capital  M,  as  I  have  just  done,  it  enters 
it  in  the  buffer  as  part  of  the  document 
that  I  am  preparing.  If  I  press  the  es¬ 
cape  key  it  changes  to  the  command 
mode  and  then  if  I  type  a  capital  M  it 
moves  the  cursor  to  the  beginning  of 
the  line  at  the  middle  of  the  screen. 
Whether  or  not  the  author  of  vi  thought 
of  it  as  a  finite  state  machine  I  do  not 
know.  Each  state  or  mode  does  its  thing 
but  it  also  must  watch  for  indications 
that  it  should  turn  matters  over  to  some 
other  state  and  initiate  the  transfer  when 
it  is  indicated. 

I  know  of  at  least  three  ways  of  pro¬ 
gramming  a  finite  state  machine  and 
there  are  probably  others  that  I  never 
heard  of.  A  finite  state  machine  can  be 
created  using  gotos,  a  switch,  or  a  pro¬ 
cedure  table. 

It  is  said  that  the  goto  method  can 
be  the  most  efficient,  but  it  is  usually 
difficult  to  understand  the  code  and 
therefore  difficult  to  maintain  unless  it 
is  done  in  a  very  disciplined  manner. 
The  code  for  each  state  is  labeled  and 
whenever  a  transition  to  a  different  state 
is  needed  a  go  to  the  label  for  that 
state’s  code  is  executed. 

I  have  usually  used  the  switch  method 
for  my  finite  state  machines.  This  re¬ 
quires  an  integer  variable  called  state 
or  mode  or  whatever  is  appropriate  for 
that  application,  and  a  loop  containing 
a  switch  controlled  by  this  variable. 
There  is  a  case  for  each  state  and  either 
the  code  for  that  state  is  put  directly 
into  the  switch  or  it  is  written  as  a 
function  and  called  within  that  case. 
When  it  is  necessary  to  transfer  to  a 
different  state,  the  code  within  the  case 
can  assign  a  different  value  to  the  state 
variable.  Putting  the  code  directly  in 
the  switch  cases  avoids  the  overhead 
of  a  function  call  and  is  therefore  slightly 
more  efficient;  however,  it  can  result 
in  an  undesirably  long  switch.  It  is  possi¬ 
ble  to  put  the  code  directly  in  the  switch 


only  for  the  simpler  states  and  use  func¬ 
tion  calls  for  the  states  that  require  larger 
amounts  of  code.  Unless  efficiency  is 
of  great  importance,  it  is  probably  bet¬ 
ter  to  use  function  calls  and  have  a 
shorter,  easier  to  understand  switch. 

The  procedure  table  method  pro¬ 
duces  what  is  probably  the  most  com¬ 
pact  and  easiest  code  to  understand. 
To  set  up  a  finite  state  machine  using 
a  procedure  table,  a  function  is  needed 
for  each  state  and  a  state  variable  to 
index  the  procedure  table  in  addition 
to  the  procedure  table  itself.  The  func¬ 
tions  should  return  an  integer  type  and, 
besides  carrying  out  the  work  of  that 
state,  the  function  must  watch  for  indi¬ 
cations  that  a  different  state  is  required 
and  then  return  the  number  for  the 
next  state.  The  procedure  table  is  an 
array  of  function  pointers,  and  by  point¬ 
ing  them  at  the  state  functions  a  num¬ 
ber  is  assigned  to  each  function.  The 
functions  can  then  be  called  by  num¬ 
ber.  The  computer  is  perfectly  happy 
with  numbers  but  we  humans  find  it 
easier  to  use  names,  and  of  course  the 
functions  themselves  must  have  names. 
The  plan  that  I  use  is  to  name  each 
state,  use  the  name  of  the  state  in  lower 
case  for  the  function  name,  and  assign 
the  same  name  in  uppercase  to  the 
number  for  that  state  by  using  a  pre¬ 
processor  define. 

If  you  have  one  of  the  newer  com¬ 
pilers  this  might  be  a  good  place  to  use 
the  new  enumeration  feature  of  the  C 
language.  A  loop  is  established  con¬ 
taining  a  call  to  one  of  the  state  func¬ 
tions  by  means  of  the  procedure  table 
indexed  by  the  state  variable  and  re¬ 
turning  a  new  value  of  the  state  vari¬ 
able.  This  one  statement  is  really  all 
that  is  necessary  in  the  loop,  although 
in  some  cases  it  may  be  desirable  to 
add  some  error  detecting  code.  Unless 
it  is  desired  to  have  the  finite  state 
machine  run  until  somebody  turns  off 
the  computer  or  pulls  the  plug  (and 
this  is  sometimes  done  for  a  dedicated 
process  control  computer),  there  has 
to  be  some  way  to  shut  down  the  finite 
state  machine.  There  are  at  least  two 
ways  to  do  this  that  I  know  of  and 
probably  others  that  I  am  not  familiar 
with.  There  could  be  a  terminal  state 
whose  function  tidies  things  up  (closes 
files,  removes  temporary  files,  etc.),  and 
then  calls  exit( )  and  so  never  returns, 
or  there  could  be  a  value  of  the  state 
variable  not  corresponding  to  any  func¬ 
tion,  which  would  cause  the  loop  to 
end.  Even  if  the  terminal  state  method 
is  used,  it  is  unwise  to  use  a  forever 
loop.  If  the  state  variable  ever  gets  out 
of  range,  then  memory  outside  the  range 
of  the  pointer  array  would  be  used  as 
a  function  pointer  and  almost  anything 
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(continued  from  page  12) 
could  happen  when  code  was  entered 
at  some  random  point  or  data  was  in¬ 
terpreted  as  code!  The  only  sure  thing 
about  such  a  situation  would  be  that  it 
would  be  a  disaster.  The  easiest  way 
to  guard  against  this  is  to  use  a  while 
or  for  loop  with  the  condition  for  con¬ 
tinuing  being  that  the  state  variable  is 
in  range.  Don’t  forget  that  the  state 
variable  must  be  initialized  to  one  of 
the  states  before  the  loop  is  entered. 
Usually  the  finite  state  machine  always 
starts  with  the  same  state,  or  it  can  be 
made  to  start  in  the  same  state  by  hav¬ 
ing  an  initialization  state  which,  often 
among  other  duties,  has  the  task  of 
selecting  the  starting  state  and  transfer¬ 
ring  to  it. 

If  such  a  state  is  used,  it  is  never 
entered  from  any  of  the  other  states  so 
that  it  executes  only  at  the  startup  of 
the  finite  state  machine.  It  is  even  pos¬ 
sible  to  do  it  all  in  one  for  statement.  It 
might  go  something  like: 

for(state=0;state>=0&&state 
<  NSTATES;state=(*proctbl[state]  (  )fp»; 

While  that  is  the  most  compact  form,  it 
might  be  clearer  as: 

state  =  0 

whileCstate  .=  0  &&  state  <  NSTATES) 
state  =  (*proctbl[statel)  (fp); 

Both  of  these  assume  that  the  starting 
state  is  in  the  zero  slot  of  the  procedure 
table.  It  would  probably  be  clearer  and 
less  restrictive  to  use  the  name  defined 
as  the  starting  state  in  place  of  zero  for 
the  initialization  of  the  state  variable. 
The  zero  in  the  comparison  for  the 
while  condition  should  remain  zero, 
however.  NSTATES  is,  of  course,  the 
number  of  states  assigned  slots  in  the 
procedure  table,  and  therefore  the  num¬ 
ber  of  slots  in  the  procedure  table. 
Since  these  slots  are  numbered  zero 
through  NSTATES-1  the  check  on  the 
upper  limits  is  state  <  NSTATES. 

When  the  functions  are  written,  there 
are  some  special  considerations  and 
problems  pertaining  to  finite  state  ma¬ 
chines  that  should  be  kept  in  mind. 
Care  should  be  exercised  in  writing  the 
code  that  determines  whether  the  state 
should  continue  or  transfer  to  another 
state  lest  a  situation  should  arise  that 
would  be  rejected  by  all  of  the  states. 
This  could  result  in  an  endless  loop  of 
transfers  from  state  to  state  with  none 
of  the  states  doing  anything  about  it. 
Perhaps  a  special  state  named  "CON¬ 
FUSION”  would  be  needed  to  deal  with 
these  unresolvable  situations. 

Another  problem  that  often  comes 
up  when  programming  finite  state  ma¬ 


chines  is  the  situation  where  a  state 
starts  to  process  an  item  before  it  dis¬ 
covers,  and  possibly  before  it  can  dis¬ 
cover,  that  the  item  requires  a  different 
state.  Avoid  having  the  state  take  any 
irreversible  action  before  it  is  certain 
that  the  item  being  processed  is  its 
business.  Frequently  this  problem  oc¬ 
curs  in  connection  with  input.  A  state 
will  read  in  an  item  and  then  find  that 
the  item  should  have  been  read  and 
processed  by  a  different  state.  If  the 
input  is  being  read  in  one  character  at 
a  time  then  the  answer  is  to  use  the 
ungetcf  )  function.  When  larger  chunks 
are  being  read,  such  as  a  line  or  a 
record,  there  is  more  of  a  problem.  If 
it  is  certain  that  input  is  coming  from  a 
random  access  file  then  it  is  possible 
to  use  ftellf  )  to  record  the  position  in 
the  file  before  each  read  and  when 
necessary  to  use  fseek(  Jto  “push  back” 
what  was  read.  Unfortunately  this  does 
not  work  for  input  from  most  devices 
or  from  pipes. 

A  more  general  method  is  to  pre- 
read.  This  works  where  the  unit  read 
is  always  the  same,  one  line  or  one 
record  or  whatever.  A  global  buffer, 
accessible  to  all  the  functions,  is  pro¬ 
vided  and  the  first  item  is  read  into  it 
either  before  the  finite  state  machine 
is  started,  or  by  the  initialization  state 
if  that  is  used.  The  processing  loop 
within  each  state  would  be  a  do  loop 
that  would  process  the  item  in  the  buffer, 
read  a  new  item  into  the  buffer,  and 
decide  whether  to  loop  to  process  the 
new  item  or  transfer  to  another  state. 

There  is  always  the  question  of 
whether  or  not  a  finite  state  machine 
is  the  right  program  structure  to  use  for 
a  given  application.  This  depends  on 
what  is  meant  by  "right.”  At  one  ex¬ 
treme  are  those  that  program  for  effi¬ 
ciency  no  matter  if  that  trick  that  gives 
some  tiny  advantage  in  efficiency  makes 
the  code  hard  to  understand  and  main¬ 
tain.  At  the  opposite  extreme  are  those 
that  seem  to  have  contempt  for  any 
considerations  of  efficiency  and  for  the 
sake  of  understandability  and  main¬ 
tainability  they  follow  a  rigid  set  of 
rules  that  permit  only  a  few  structures 
that  have  been  blessed  by  the  high 
priests  of  structured  programming.  Nei¬ 
ther  of  these  are  likely  to  use  the  finite 
state  machine  concept.  One  rejects  it 
because  any  formal  structure  is  non¬ 
sense  to  him,  and  the  other  because  it 
is  not  one  of  the  sacred  structures.  Most 
programmers  are  somewhere  in  be¬ 
tween.  They  realize  that  some  structure 
is  needed  and  take  the  pragmatic  ap¬ 
proach  of  if  the  structure  fits  the  appli¬ 
cation  use  it  and  if  it  does  not  then  find 
one  that  will  fit. 

Some  say  that  a  finite  state  machine, 


even  when  implemented  using  the 
switch  or  the  procedure  table,  is  really 
goto  programming  in  disguise.  To  some 
extent  this  may  be  true  but  if  the  as¬ 
sembly  language  used  to  implement 
the  favorites  of  the  structured  program¬ 
mers,  such  as  the  while  statement,  is 
examined  you  will  find  gotos.  Yet  struc¬ 
tured  programming  with  its  hidden 
gotos  does  have  definite  advantages. 
Therefore  there  must  be  merit  in  hiding 
the  gotos.  The  merit  in  hiding  the  gotos 
lies  in  concealing  confusing  details  so 
that  the  overall  picture  can  be  seen  and 
comprehended  more  easily.  But  hiding 
the  details  does  not  do  much  good  if 
what  does  show  is  confusing  and  hard 
to  understand. 

The  finite  state  machine  concept  is 
a  powerful  tool,  but  like  any  tool,  the 
more  powerful  it  is  the  better  the  re¬ 
sults  if  used  skillfully,  and  the  worse 
the  results  if  misused.  The  finite  state 
machine  structure  is  quite  general.  It 
can  be  used  to  program  almost  any¬ 
thing,  but  it  is  the  best  choice  for  only 
a  small  fraction  of  what  it  can  be  used 
for  programming.  Earlier  I  described 
how  a  finite  state  machine  could  be 
implemented  with  gotos.  Unfortunately 
this  process  can  be  reversed  and  any 
bit  of  goto  programming  can  be  trans¬ 
lated  to  a  finite  state  machine.  Simply 
write  each  labeled  hunk  of  code  as  a 
state  function  with  gotos  and  places 
where  the  program  would  simply  fall 
through  to  another  hunk  of  code  re¬ 
placed  by  return  statements  returning 
the  number  for  the  function  containing 
the  code  that  would  be  reached.  The 
resulting  finite  state  machine  could  then 
be  implemented  by  either  the  switch 
or  the  procedure  table  method.  The 
result  should  superficially  resemble  struc¬ 
tured  programming,  but  bowl  of  spa¬ 
ghetti  programming  is  bad  program¬ 
ming  no  matter  how  it  is  implemented. 

This  letter  is  much  too  long.  You 
probably  will  not  find  room  to  publish 
my  ramblings.  Anyway,  writing  out  my 
ideas  helps  me  get  clear  in  my  own 
mind  so  it  is  not  a  total  waste  of  paper. 

David  S.  Tilton 

Manchester,  New  Hampshire 

DDJ:  Thanks  for  your  explanation  of 
finite  state  machines ,  David.  Be  sure 
to  check  our  October  1989  issue  for 
more  info  on  FSMs. 

We  welcome  your  comments  (and 
suggestions).  Mail  your  letters  (include 
disk  if  your  letter  is  lengthy  or  contains 
code)  to  DDJ,  501  Galveston  Dr.,  Red¬ 
wood  City,  CA  94063,  or  send  them 
electronically  to  CompuServe  76704,50 
or  via  MCI  Mail,  c/o  DDJ.  Please  in¬ 
clude  your  name,  city,  and  state.  We 
reserve  the  right  to  edit  letters. 
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Data-Flow 

Multitasking 

A  bridge  between  single  and 
multiple  processor  systems 


Rabindra  P.  Kar 


In  recent  years,  it  has  become  apparent  that  computer 
designs  based  on  the  traditional  Von  Neumann  com¬ 
puter  architecture  (a  single  processor  stepping  sequen¬ 
tially  through  a  linear  memory)  are  reaching  their  per¬ 
formance  limits.  Performance  continues  to  rise  as  hard¬ 
ware  clock  rates  get  faster  and  features  such  as  pipelining 
and  cache  memory  improve.  However,  the  realization  is 
dawning  that  to  achieve  quantum  performance  leaps  with 
existing  technology,  some  form  of  multiple  processor  archi¬ 
tecture  must  be  used. 

In  the  1980s,  we  have  seen  the  appearance  of  many 
multiple  processor  computer  designs,  but  the  number  of 
these  computers  in  actual  use  is  tiny  compared  with  tradi¬ 
tional,  single  CPU  systems.  There  are  several  reasons  for 
this.  Multiprocessor  systems  are  expensive.  They  cost  more 
because  they  use  more  hardware,  and  do  not  enjoy  the 
economies  of  scale  that  come  with  high-volume  production 
and  sales.  Furthermore,  applications  and/or  systems  pro¬ 
grammers  must  deal  with  a  vastly  more  complex  hardware 
environment,  making  the  entire  development  cycle  difficult. 
Programmers  must  identify  the  sections  of  an  application  that 
can  be  tackled  in  parallel,  and  then  devise  programs  that 
will  take  advantage  of  the  hardware.  Little  performance  gain 
can  be  achieved  for  applications  that  are  sequential  in  nature, 
unless  data-flow  concepts  are  used  in  software  design. 

While  multiprocessing  systems  are  expensive  and  rela¬ 
tively  uncommon,  multitasking  has  been  with  us  for  de¬ 
cades.  With  the  notable  exception  of  DOS,  most  operating 
systems  in  common  use  today  (including  Unix,  IBM’s  OS/ 
MVS,  OS/2,  iRMX  and  VRTX  in  the  real-time  world)  offer 
multitasking.  That  brings  up  an  interesting  question.  Can 
applications  programs  be  written  on  multitasking  systems 
today  that  will  be  easy  to  port  to  the  multiprocessing  sys¬ 
tems  of  tomorrow?  Is  this  possible  even  for  applications  that 
are  sequential  in  nature? 


Robin  is  a  senior  engineer  with  the  Intel  Systems  Group  and 
author  of  the  Rhealstone  real-time  benchmark  proposal.  He 
can  be  reached  at  5200  N.E.  Elam  Young  Parkway,  Hillsboro, 
OR  97124-6497. 


This  article  is  about  data-flow  multitasking,  a  software 
concept  that  may  help  bridge  the  gap  between  multitasking 
and  multiprocessing  capability. 

Data-Flow  Concepts 

Data-flow  architectures  have  been  studied  for  at  least  three 
decades,  but  they  have  been  overshadowed  by  the  now 
dominant  centralized  processing,  control-flow  type  archi¬ 
tectures  identified  with  Von  Neumann.  In  a  data-flow  ma¬ 
chine,  storage  (memory)  is  not  viewed  as  a  separate,  passive 
area,  but  as  a  link  between  data  processing  operations 
(instructions).  Data  processing  operations  are  enabled  (execut¬ 
able)  when  input  data  is  available  to  them,  and  when  their 
previous  output  has  been  read  and  disposed  of.  This  concept 
is  similar  to  “just-in-time”  assembly  lines  pioneered  by  major 
Japanese  manufacturers. 

The  easiest  explanation  of  data-flow  concepts  is  by  a 
simple  example  —  a  program  that  computes  the  roots  of  a 
quadratic  equation  [ax  +  bx  +  c  =  0],  Figure  1  shows  a  flow¬ 
chart  for  this  program  in  classic  sequential  style.  Each  step 
in  the  program  cannot  be  executed  until  the  result(s)  of  the 
previous  operation  are  known.  The  traditional  approach  to 
executing  this  program  is  to  have  the  computer’s  CPU  step 
through  each  operation  sequentially  (read,  compute  DET, 
compute  NUM+/-,  compute  RES)  and  then  loop  back  to 
process  the  next  set  of  data.  The  input  data,  and  all  interme¬ 
diate  results,  are  stored  in  a  part  of  the  computer’s  memory. 
This  is  referred  to  as  the  “control-flow”  approach. 

Now,  let’s  modify  the  flowchart  in  Figure  1.  Instead  of 
thinking  of  each  operation  as  a  subroutine  or  function  that 
a  single  CPU  must  execute  sequentially,  imagine  a  CPU  (or 
hard-wired  logic)  dedicated  to  each  operation.  Each  CPU 
(or  logic  module)  can  be  called  an  operation  processor 
(OP).  Think  of  memory  as  a  set  of  mailboxes  connecting  the 
OPs  as  shown  in  Figure  2. 

Each  OP  is  either  executing  its  specific  operation,  or  it  is 
in  “wait”  mode.  In  wait  mode,  it  constantly  looks  for  new 
data  in  the  mailbox  preceding  the  operation  (its  “input  mail¬ 
box”).  The  OP  also  checks  that  whatever  result  it  placed  in 
the  mailbox  following  the  operation  (its  “output  mailbox”) 


16 


Dr.  Dobb's Journal,  November  1989 

747 


has  been  read  by  the  next  OP  in  line.  If  these  two  conditions 
are  met,  it  reads  the  input  mailbox  data,  executes  the  opera¬ 
tion,  puts  the  result  into  the  output  mailbox,  and  goes  back 
to  wait  mode.  This  is  called  the  “data-flow”  approach  —  each 
CPU  is  dedicated  to  one  operation,  and  data  “flows”  from 
one  CPU  to  another. 

In  a  true  data-flow  machine,  each  operation  is  a  basic 
machine  instruction,  such  as  multiplication  or  addition.  Be¬ 
cause  we  are  trying  to  superimpose  a  macroscopic  data¬ 
flow  strategy  on  a  control-flow  machine,  however,  the  com¬ 
putations  within  each  operation  (calculating  DET  or  NUM, 
for  example)  are  still  executed  with  a  control-flow  ap¬ 
proach.  It  is  only  the  relationship  between  the  major  opera¬ 
tions  in  our  flowchart  that  simulate  a  data-flow  architecture. 

Multiple  Tasks  Simulate  Multiple  CPUs 

The  data-flow  approach  is  promising  because  it  allows  the 
power  of  multiple  processors  to  be  harnessed  to  process  a 
stream  of  data  in  a  sequential  algorithm.  The  problem  today 
with  this  approach  is  that  most  programmers  only  have 
access  to  single  CPU  (Von  Neumann)  architectures,  whether 
they  are  VAX  terminals,  workstations,  or  humble  PC/AT  clones. 
Yet  much  of  today’s  software  may  need  to  be  ported  to 
powerful,  multiprocessing  machines  within  the  next  decade. 

Can  application  programs  using  data-flow  concepts  be 
written  today?  Yes,  if  the  multitasking  abilities  of  today’s 
operating  systems  are  used.  Each  OP  in  the  above  example 
can  be  effectively  simulated  by  a  separate  task  that  reads 
data  from  a  “mailbox, ’’executes  the  operation,  and  writes 
the  result  to  the  next  mailbox.  Most  multitasking  operating 


systems  offer  features  such  as  pipes,  queues,  and  others  for 
intertask  communication.  The  programmer  can  set  these 
up  to  perform  the  mailbox  function.  If  the  OS  allows  tasks 
to  share  memory /data  segments,  simply  assigning  some 
global  variables  as  “mailboxes”  is  an  effective,  high-per¬ 
formance  way  of  passing  data  between  tasks.  This  tech¬ 
nique  is  shown  in  the  following  section  through  a  program¬ 
ming  example.  The  programs  are  based  on  the  flowcharts 
in  Figures  1  and  2. 

A  Programming  Example 

Listing  One,  page  84,  shows  quad_eq.c,  a  C  program  that 
calculates  roots  of  a  quadratic  equation  using  the  “normal” 
control-flow  approach.  Input  data  (100  sets  of  coefficients) 
was  “created”  in  this  example  program  simply  for  con¬ 
venience.  In  actuality  the  data  would  be  read  from  some  I/O 
device. 

In  a  single  CPU  environment,  quad_  eq.c  is  a  simple  and 
efficient  program.  Because  this  is  the  environment  that  99 
percent  of  today’s  computer  science  majors  learned  about 
programming,  it  also  seems  like  the  natural  way.  However, 
if  a  multi-processor  system  became  available,  there  is  no 
obvious  way  to  port  this  program  using  parallel  computa¬ 
tion  to  speed  it  up. 

Listing  Two,  page  84,  shows  dflow.c,  a  multitasking  ver¬ 
sion  of  quad_eq.c,  which  runs  under  Intel’s  real-time  mul¬ 
titasking  operating  system,  iRMX  II.  Each  computational 
function  in  quad_eq.c  has  been  turned  into  a  computational 
task  in  dflow.c.  For  example,  the  numeratori )  function  is 
replaced  by  num_task( ).  Global  variables  act  as  mailboxes 


Data-flow  multitasking 
involves  looking  at 
a  sequential  program 
through  new  eyes 
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DATA-FLOW  MULTITASKING 


Exit 


Figure  1:  Flowchart  of  a  program  that  computes  the  roots 
of  a  quadratic  equation 


to  pass  data  between  tasks.  Essentially,  dflow.c  implements 
the  flowchart  in  Figure  2,  with  computational  tasks  substi¬ 
tuting  for  OPs. 

In  quad_eq.c,  main(  )  controls  the  flow  of  the  program  — 
the  sequence  in  which  each  function  (subroutine)  is  called. 
In  dflow.c,  main()  tells  the  OS  which  tasks  should  be 
created.  After  that,  it  gets  out  of  the  way  (lowers  its  own 
priority)  while  the  computational  tasks  ( det_task( ), 
num_task( ),  and  res_task(J)  process  all  the  input  data.  The 
computational  tasks  delete  themselves  when  the  data  is 
exhausted  (when  the  “a”  coefficient  of  the  next  set  of  data 
is  0.0),  returning  control  to  main( ),  which  promptly  exits. 

Global  variables  det,  num ,  indexl,  index2,  and  array 
yf  ./constitute  the  mailbox  information  passed  from  one  task 
to  the  next.  In  a  data-flow  environment,  each  operation  is 
performed  only  when  there  is  new  data  in  a  function’s  input 
mailbox,  and  only  if  the  result  of  that  function’s  previous 
operation  has  been  read  from  its  output  mailbox.  The  vari¬ 
ables  det  and  num  are  used  for  this  synchronization 
(num_task( )  will  do  a  computation  only  when  it  sees  a 
non-zero  value  in  det,  and  zero  in  num).  After  the  variable 
det  is  read  it  is  set  to  zero,  so  det_task( )  will  know  that  its 
output  mailbox  was  read. 

Each  task  calls  rq$sleep(0,  &status)  if  the  time  is  not  right 
to  process  new  data.  The  first  parameter  of  rq$sleep  is  the 
sleep-time.  A  sleep-time  of  zero  tells  the  operating  system 
that  the  running  task  is  willing  to  give  up  the  CPU  in  favor 
of  some  other  equal  priority  task  that  needs  it. 

The  program  dflow.c  is  a  data-flow  implementation  of  a 
typical  control-flow  program.  It  is  a  multitasking  solution 
to  a  straightforward  computation.  It  is  conceptually  simple 
to  port  a  multitasking  solution  to  a  multiprocessor  environ¬ 


Input  data  stream  or  mailbox 


OP  =  Operation  Processor 

Figure  2:  This  version  of  the  flowchart  in  Figure  1  assumes 
that  a  CPU  is  dedicated  to  each  operation.  Let's  call  each 
CPU  (or  logic  module)  an  operation  processor  (OP)  so  that 
memory  becomes  a  set  of  mailboxes  that  connect  OPs. 


ment,  and  reap  the  enormous  performance  benefits  of  con¬ 
current  computation. 

Multitasking  Versus  Single-Task  Performance 

While  data-flow  multitasking  is  a  bridge  to  high  perfor¬ 
mance  in  a  multi-processor  environment,  it  may  lower  perfor¬ 
mance  slightly  in  a  single-CPU  system.  There  are  two  main 
reasons  for  this.  The  first  is  that  CPU  time  spent  calling  and 
returning  from  a  function  or  subroutine  is  usually  less  than 
the  time  required  for  a  task  switch.  For  this  reason,  quad_eq.c 
will  execute  faster  than  dflow.c  on  most  single  CPU  multi¬ 
tasking  systems.  Secondly,  intertask  communication  mail¬ 
boxes  using  global  variables  may  not  be  feasible  because 
of  OS  restrictions,  or  the  necessity  to  keep  the  software 
more  modular  and  easier  to  maintain.  Using  other  communica¬ 
tion  features,  such  as  pipes,  may  impose  a  performance 
penalty. 

In  some  situations,  though,  data-flow  multitasking  can 
be  used  to  speed  up  a  program,  even  on  a  single  CPU 
system.  A  good  example  is  when  the  program  must  talk  to 
relatively  slow  I/O  devices.  Multitasking  can  be  used  to 
overlap  inherent  I/O  delays.  While  one  task  is  waiting  for  a 
disk  write  to  complete,  another  task  may  write  to  the  con¬ 
sole  or  read  from  a  keyboard. 

Listing  Three,  page  84,  shows  res_  task2( ),  code  for  a  task 
that  could  be  added  to  dflow.c.  This  code  calculates  the 
root  of  a  quadratic.  It  is  identical  to  res_task( )  code.  Except 
that  it  prints  its  output  to  a  file  rather  than  the  console.  Note 
that  det_task( )  and  num_  task( )  involve  no  interaction  with 
any  slow  I/O  device,  the  CPU  probably  spends  most  of  its 
time  waiting  for  the  print  operation  to  complete.  With  two 
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(continued  from  page  20) 

or  more  tasks  printing  the  results  on  different  output  de¬ 
vices,  I/O  delays  can  be  overlapped,  and  the  program  is 
speeded  up. 

Multiple  Processors 

In  general,  if  a  computation  has  been  divided  into  n  number 
of  operations,  at  least  n  tasks  must  be  spawned  to  imple¬ 
ment  data-flow  multitasking.  When  ported  to  a  multiproces¬ 
sor  system,  each  task  will  be  concurrently  executed  by  a 
separate  processor,  thus  utilizing  n  processors.  The  mail¬ 
boxes  can  be  global  variables  in  memory  on  a  common  bus 
(tightly  coupled  multiprocessing),  or  implemented  by  mes¬ 
sage  passing  using  a  wide  variety  of  interprocessor  connec¬ 
tion  schemes. 

If  there  are  more  processors  available,  you  can  utilize 
more  than  two  processors  per  operation  and  share  common 
input  and  output  mailboxes.  Assuming  that  interprocessor 
communication  overhead  is  much  smaller  than  the  execu¬ 
tion  time  for  any  operation,  the  effects  of  using  multiple 
processors  varies.  If  the  processor  subsystems  execute  each 
of  the  n  operations  in  the  same  amount  of  time,  no  perfor¬ 
mance  advantage  can  be  gained  by  using  multiple  proces¬ 
sors  per  operation. 

In  most  cases,  though,  the  execution  time  for  each  of  the 
n  operations  will  be  unequal.  A  rule  of  thumb  is  that  the 
optimum  number  of  processors  per  operation  is  propor¬ 
tional  to  the  execution  time  of  each  operation.  If  the  pro¬ 
gram  involves  three  operations  and  operation  1  takes  t 
milliseconds,  operation  2  takes  2t  and  operation  3  takes  3( 
then  optimal  performance  is  achieved  by  using  one  proces¬ 
sor  to  execute  operation  1,  two  processors  for  operation  2, 
and  three  for  operation  3. 


When  multiple  processors  are  executing  the  same  opera¬ 
tion  concurrently,  data  integrity  in  the  mailboxes  becomes  a 
tricky  problem.  Test  and  set  operations  on  mailbox  data 
must  be  made  atomic  (uninterruptible)  by  hardware  or  soft¬ 
ware  means.  For  example,  if  there  are  two  processors  dedi¬ 
cated  to  calculating  the  numerator  in  Listing  Two,  each  proces¬ 
sor  must  be  able  to  read  the  value  of  det  or  num  and  set  the 
value  in  complete  privacy.  The  other  processor  must  not 
be  able  to  access  the  data  between  the  read  and  set  actions. 

Relevance  of  Real-Time  Operating  Systems 

There  are  several  reasons  why  a  real-time  operating  system 
(iRMX  II)  was  used  as  a  foundation  for  the  data-flow  multi¬ 
tasking  example  in  this  article. 

1 .  Many  real-time  data  acquisition  and  analysis  applications 
are  pushing  the  limits  of  a  single-CPU  solution.  Application 
designers  are  looking  at  real-time  multiprocessing  to  pro¬ 
vide  high  performance  at  a  reasonable  cost.  Data-flow  multi¬ 
tasking  is  the  first  software  step  towards  that  goal. 

2.  iRMX  II  is  part  of  the  family  of  real-time  OSs.  The  newer 
members  of  this  family  are  oriented  towards  distributed 
multiprocessing.  This  is  the  very  environment  that  data-flow 
multitasking  programs  should  be  ported  to  in  order  to  use 
their  built-in  concurrency. 

3.  A  critical  technical  advantage  of  a  real-time  OS  is  deter¬ 
minism  —  the  fact  that  task  switching  happens  on  pre¬ 
dictable  events  or  system  calls,  and  not  according  to  some 
application-invisible  time-slicing  algorithm.  This  is  extremely 
important  when  there  is  more  than  one  task  accessing  the 
same  input  and/or  output  mailbox. 

Both  res_task( )  and  res_task2( )  in  Listings  Two  and 


Three,  read  their  input  data  from  the  global  variable  num 
(their  input  mailbox),  Each  one  sets  num  to  0.0  after  reading 
it,  to  tell  num_task( )  that  the  mailbox  has  been  read.  The 
C  code  that  does  this  is: 

res  =  num  /  (2  *  y[index2].a); 

num  =  0.0; 

These  C  statements  translate  into  several  machine  instruc¬ 
tions  each.  If  the  OS  implements  multitasking  by  a  round- 
robin  time-slicing  algorithm,  a  task  switch  could  occur  any¬ 
time  between  the  machine  instruction  that  reads  num  from 
memory  and  the  one  that  sets  it  to  0.0.  If  res_task( )  were 
so  interrupted,  and  res_task2( /was  activated  before  res_task( ) 
resumed,  both  tasks  would  read  the  same  data  and  compute 
the  same  result  twice.  A  similar  problem  was  described  in 
the  previous  section  regarding  the  use  of  two  processors 
per  operation. 

In  iRMX  II,  task  switching  between  equal  priority  tasks 
will  not  occur  until  a  system  call  is  made.  Thus,  res_task( ) 
and  res_task2( )  will  not  be  switched  in  or  out  except  at  the 
point  where  they  call  rq$sleep.  Most  real-time  kernels  and 
OSs  behave  similarly.  Some  non-real-time  OSs  do  allow  you 
to  stop  task-switching  between  certain  boundaries  (“critical 
sections”  in  OS/2,  for  instance),  but  you  must  use  this 
feature  explicitly.  If  an  OS  offers  multitasking  without  this 
capability,  only  one  task  should  be  spawned  per  operation. 

Summary 

Data-flow  multitasking  is  a  promising  solution  to  the  chal¬ 
lenges  software  faces  over  the  next  decade.  It  involves 


looking  at  a  sequential  program  through  new  eyes.  Each 
major  operation,  function,  or  subroutine  is  viewed  as  a 
separate  task.  The  activation  of  tasks  is  synchronized  by  the 
flow  of  processed  data  from  one  task  to  another.  When 
ported  to  a  multi-processor  environment,  each  task  can  be 
concurrently  executed  by  one  or  more  processors. 

The  use  of  data-flow  multitasking  may  impose  some 
performance  penalty  in  a  computation-intensive  single-CPU 
environment.  This  can  be  more  than  offset  if  multitasking 
is  used  to  overlap  the  slow  I/O  operations  executed  by 
most  programs.  Porting  a  program  to  a  multi-CPU  environ¬ 
ment  almost  always  brings  a  huge  performance  boost. 

Data-flow  multitasking  is  particularly  relevant  for  real¬ 
time  applications.  The  need  for  high  performance  at  moder¬ 
ate  cost  is  much  more  pressing  in  the  real-time  world  than 
it  is  in  batch  or  interactive  computing.  Real-time  multi¬ 
tasking  operating  systems  and/or  kernels  also  provide  a 
high  level  of  determinism,  which  precludes  race  conditions 
associated  with  multiple  task  access  data  mailboxes. 

Availability 

All  source  code  for  articles  in  this  issue  is  available  on  a 
single  disk.  To  order,  send  $14.95  (Calif,  residents  add  sales 
tax)  to  Dr.  Dobb's  Journal,  501  Galveston  Dr.,  Redwood 
City,  CA  94063,  or  call  800-356-2002  (from  inside  Calif.)  or 
800-533-4372  (from  outside  Calif.).  Please  specify  the  issue 
number  and  format  (MS-DOS,  Macintosh,  Kaypro). 
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A  Parallel  make 

With  DESQview 


dvmake  can  easily  run  four  tasks  at  once 


Mark  Streich 


The  make  utility  started  out 
as  a  Unix  tool  for  creating 
executable  applications 
from  a  large  number  of  pro¬ 
gram  files.  Its  main  purpose 
is  to  determine  which  files  of  an 
application  need  to  be  recompiled 
and  issue  whatever  commands  are 
necessary  to  do  so. 

As  computers  with  multiple  pro¬ 
cessors  became  available,  some 
developers  created  make  utilities 
capable  of  executing  the  various 
make  commands  on  separate  proc¬ 
essors.  This  allowed  each  proces¬ 
sor  to  make  a  separate  target,  which 
resulted  in  faster  make  times,  al¬ 
though  the  speedup  was  not  as 
great  as  expected. 

Unfortunately,  parallel  comput¬ 
ers  have  not  yet  reached  the 
masses,  although  multitasking  en¬ 
vironments  and  operating  systems  for 
single-CPU  computers  have;  such  op¬ 
erating  systems,  Unix  and  OS/2  among 
them,  are  great  —  if  you  have  several 
megabytes  of  memory,  a  fast  hard 
disk,  a  386,  and  the  money  to  buy  the 
toolkits. 

With  this  in  mind,  I  decided  to  de¬ 
velop  a  parallel  wafer*  that  DDJ  readers 
can  both  use  and  afford.  After  survey¬ 
ing  the  available  development  environ¬ 
ments,  I  turned  to  Quarterdeck  Office 
System’s  (QOS,  Santa  Monica,  Calif.) 


Mark  is  currently  a  graduate  student 
at  the  University  of  Colorado  in  Boul¬ 
der,  specializing  in  compilers  and  par¬ 
allel  computers.  He  may  be  contacted 
through  the  DDJ  office. 


DESQview,  which  can  juggle  programs 
running  on  everything  from  the  origi¬ 
nal  to  fast  386-based  PCs,  to  create  a 
parallel  make  I  call  dvmake  (short  for 
“DESQview  make”).  Listing  One,  page 
86,  lists  the  C  code  for  the  program. 

dvmake  requires  DESQview  in  order 
to  run.  DESQview-specific  applications 
like  dvmake  make  extensive  use  of 
DESQview’s  API  and  usually  take  ad¬ 
vantage  of  DESQview’s  ability  to  spawn 
new  tasks,  display  menus,  and  com¬ 
municate  with  other  applications.  (Other 
types  of  DESQview  applications  include 
those  that  act  differently  running  under 
DESQview  than  they  do  running  under 
DOS  alone,  as  well  as  those  that  don't 
take  advantage  of  any  of  DESQview’s 
capabilities.) 


What  Is  There  to  Gain? 

The  idea  behind  parallel  comput¬ 
ers,  and  supposedly  behind  multi¬ 
tasking  software,  is  that  a  com¬ 
puter  can  get  more  done  in  the 
same  amount  of  time  if  it’s  doing 
two  or  more  things  simultaneously. 

make  often  needs  to  do  several 
things,  and  until  now  it  had  to  do 
them  one  after  another.  For  exam¬ 
ple,  make  may  have  to  compile 
three  C  source  files  one  after  an¬ 
other,  then  link  the  object  files  to¬ 
gether  to  create  an  executable  pro¬ 
gram.  Let’s  assume  that  it  takes  1 
minute  for  each  compilation  and 
1  for  the  linking  step  for  a  total  of 
4  minutes. 

dvmake ,  on  the  other  hand,  can 
easily  run  four  tasks  at  once,  so 
theoretically,  you  can  remake  the 
entire  program  in  1  minute.  Wrong. 
The  best  that  you  could  hope  for  is  2 
minutes  because  the  linking  step  can’t 
even  start  until  all  of  the  object  files 
have  been  created  (meaning  the  source 
files  have  been  completely  compiled). 

Let’s  assume  it  takes  2  minutes  to 
compile  a  program  called  farm.c,  and 
that  you  only  have  enough  memory  to 
run  two  tasks  at  a  time.  If  you  compile 
both  a  program  called  pig.c  and  an¬ 
other  called  cow.c  in  parallel  (taking  1 
minute),  and  then  compile  farm.c,  you 
spend  3  minutes  compiling.  If  you  re¬ 
arrange  the  scheduling,  you  could  com¬ 
pile  farm.c  and  pig.c  in  parallel,  and 
after  pig.c  completes,  then  compile 
cow.c.  This  ordering  would  take  only 
2  minutes. 

Now  that  you  know  how  to  sched- 
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( continued  from  page  28) 
ule  parallel  tasks,  you  should  know 
that  dvmake  does  nothing  to  optimize 
the  scheduling  because  no  matter  what 
you  do,  a  single-CPU  computer  requires 
(at  least)  the  same  amount  of  time  to 
run  several  tasks  in  parallel  as  it  does 
to  run  the  same  tasks  sequentially.  Af¬ 
ter  all,  it  can  only  execute  one  instruc¬ 
tion  at  a  time. 

Who's  on  First? 

Although  dvmake  does  not  optimize 
the  scheduling,  it  does  have  to  guaran¬ 
tee  that  a  target  file’s  dependents  are 
available  before  the  target  can  be  made. 
This  means:  All  object  files  must  be  cre¬ 
ated  before  they  can  be  linked  together 
to  create  the  executable  program. 

dvmake  uses  a  three-step  process  to 
determine  what  needs  to  be  made  and 
then,  using  a  “greedy”  algorithm,  sched¬ 
ules  those  items  to  be  made.  (For  a 
description  of  the  greedy  algorithm, 
see  “Simulated  Annealing”  by  Michael 
McLaughlin,  DDJ,  September  1989  ) 
The  first  step  is  similar  to  the  original 
mk  program  written  by  Allen  Holub 
(DDJ,  August  1985  ).  A  binary  tree, 
sorted  on  the  target  file  name  ( being__ 
made),  is  created  by  reading  the  mkfile. 
Each  node  in  the  tree  contains  the  tar¬ 
get,  its  dependents,  its  time  and  date 
stamp,  and  the  commands  to  remake 


the  target.  The  dependenciesC )  func¬ 
tion  creates  this  binary  tree. 

The  binary  tree  is  traversed  recur¬ 
sively  in  make_queue( ),  starting  at  First, 
which  is  either  the  first  target  listed  in 
the  mkfile  or  at  the  target  name  you 
add  to  the  command  line  when  run¬ 
ning  dvmake.  Rather  than  traversing 
the  binary  tree  depth-first,  left-to-right, 
the  recursion  is  based  on  the  depen¬ 
dents  of  the  target.  For  a  particular 
target  file  to  be  made,  it  must  be  either 
a  direct  or  indirect  dependent  of  First. 

If  a  target  file  has  dependents  that 
have  time  stamps  more  recent  than  its 
own,  the  target  file  is  added  to  a  queue 
of  items  to  be  made  (MkQueue).  The 
target’s  time  stamp  (in  the  binary  tree, 
not  on  disk)  is  changed  to  fool  any 
parents  of  the  target  file  into  thinking 
that  they  too  must  be  made. 

You  may  wonder  why  I  put  the  item 
to  make  in  a  queue,  when  I  could  just 
as  easily  make  the  item  once  I  know  it 
has  to  be  made.  (In  fact,  this  is  exactly 
how  the  mk  program  works.)  The  an¬ 
swer  is  scheduling. 

By  placing  the  targets  to  make  in  a 
queue,  we  can  easily  find  any  targets 
whose  dependents  have  all  been  made 
and  start  making  them  in  parallel.  We’re 
not  stuck  with  the  order  provided  to 
us  by  recursively  searching  the  binary 
tree.  If  some  intrepid  reader  decides 


to  add  a  smarter  scheduling  algorithm, 
it  is  much  easier  to  do  so  with  a  queue. 

dvmake  is  a  sequential  program  up 
through  the  execution  of  make_queue(  ). 
By  keeping  most  of  the  program  se¬ 
quential,  it  can  be  debugged  using  avail¬ 
able  tools.  Once  multiple  tasks  are 
created,  neither  CodeView  nor  Turbo 
Debugger  can  help,  and  the  QOS  API 
Debugger  only  tracks  the  API  calls  our 
program  makes,  not  where  our  pro¬ 
gram  is  executing. 

Once  make_queue( )  has  completed, 
MkQueue  is  either  empty  or  contains  a 
list  of  target  files  to  make.  If  there  is 
something  to  make,  we  start  the  third 
part  of  the  make  process.  To  help  you 
understand  what  is  about  to  be  ex¬ 
plained,  Figure  1  shows  when  parallel 
tasks  are  started  and  stopped. 

The  startup( )  function  creates  two 
new,  concurrently  executing  tasks.  As 
Figure  2  illustrates,  one  task  executes 
the  dvmenu( )  function  that  displays  a 
small  menu  that  allows  you  to  stop  the 
program.  The  other  task  runs  the  make( ) 
function  that  determines  which  target 
files  can  be  made. 

Both  of  the  new  tasks  run  in  parallel 
with  the  “.main  line”  program  that  calls 
the  outputO  function.  output( )  man¬ 
ages  the  output  from  the  various  pro¬ 
grams  that  are  specified  in  the  com¬ 
mand  blocks  of  the  mkfile. 

The  make( )  function  constantly 
checks  to  see  if  there  is  a  target  file  in 
MkQueue  that  has  all  of  its  dependents 
available,  as  noted  by  the  made  flags  in 
their  nodes.  If  it  finds  one,  it  attempts 
to  start  an  application  window  capable 
of  running  the  commands  listed  below 
the  target  in  the  mkfile.  (Starting  an  ap¬ 
plication  window  is  identical  to  using 
DESQview’s  Open  Window  command.) 

Once  the  application  window  has 
been  created,  another  task  is  started 
that  executes  the  dispatch( )  function. 
dispatch( )  sends  commands  to  the  ap¬ 
plication  window  to  create  the  target 
file,  and  when  all  of  the  commands 
have  been  sent,  it  sends  an  Exit  com¬ 
mand  for  the  window  to  close  itself. 

Although  I’ve  glossed  over  many  of 
the  details  so  far,  you  probably  have 
realized  that  there  are  always  three  tasks 
executing  concurrently,  plus  two  tasks 
for  each  target  file  being  made.  It  may 
seem  like  overkill,  but  the  division  of 
labor  among  the  tasks  keeps  intertask 
communication  (and  interruptions)  to 
a  minimum.  And  there  is  little  house¬ 
keeping  on  our  part.  Each  task  does  its 
work  and  stops.  DESQview  gets  rid  of 
completed  tasks. 

The  DESQview  API 

Before  we  get  into  the  details  of  the 
program,  you  should  have  a  basic  un- 


The  DESQview  Toolset 


To  create  DESQview-aware  or  DESQ- 
view-specific  programs,  you  need 
some  of  the  API  tools  Quarterdeck 
provides.  Although  dvmake  only 
uses  the  API  C  Library,  QOS  also  pro¬ 
vides  an  API  Reference,  Turbo  Pascal 
Library,  API  Debugger,  and  Panel 
Designer. 

The  API  reference  is  the  basis  for 
the  libraries,  and  includes  the  assem¬ 
bly  language  hooks  required  to  use 
the  API,  and  a  manual  that  describes 
the  concepts  embodied  in  the  API. 
You  could  get  by  with  only  this 
reference,  but  you  can  save  a  lot  of 
time  by  also  purchasing  one  of  the 
libraries. 

The  C  and  Turbo  Pascal  Libraries 
provide  the  same  functions  as  the 
reference,  but  uses  C  or  Pascal  rather 
than  assembly  language.  The  C  Li¬ 
brary  supports  compilers  available 
from  Borland,  Microsoft,  Lattice,  Meta¬ 
ware,  and  Watcom,  and  use  either  the 
ANSI  C  definition  or  the  more  tradi¬ 
tional  K&R  definition.  The  Turbo  Pas¬ 
cal  Library  supports  version  4.0  and 
later. 


The  API  Debugger  is  neither  a 
source-level  nor  an  assembly-level  de¬ 
bugger.  It  allows  you  to  debug  multi¬ 
ple  tasks,  trace  and  break  on  various 
types  of  API  calls,  and  display  the 
contents  of  memory  or  the  registers 
used  in  the  calls.  The  source  debug¬ 
gers  provided  with  the  supported  lan¬ 
guages  are  unable  to  debug  multiple 
tasks  running  under  DESQview,  so 
debugging  can  be  difficult. 

The  API  Debugger  was  unable  to 
let  me  find  out  why  a  window  run¬ 
ning  dvmake  would  disappear  when 
the  program  completed.  It  would  also 
make  itself  the  foreground  applica¬ 
tion  whenever  dvmake  started  a  new 
application  window,  which  made  it 
impossible  to  debug  some  keyboard- 
related  problems. 

The  Panel  Designer  is  handy  if  you 
need  to  design  help  or  message  win¬ 
dows,  selection  boxes,  or  menus. 
dvmake  only  has  one  menu,  and  you 
can  get  the  same  results  with  library 
calls,  so  I  decided  to  ignore  the  Panel 
Designer  for  this  project. 
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(continued  from  page  30) 
derstanding  of  the  DESQview  API.  The 
API  allows  you  to  access  numerous 
“objects”  such  as  windows,  keyboards, 
and  mouse  pointers.  As  I’ve  already 
mentioned,  you  can  start  or  stop  sepa¬ 
rate  threads  of  control  known  as  “tasks.” 
The  API  also  provides  mailboxes  for 
intertask  communication  or,  as  we  use 
them,  for  semaphores. 

Semaphores  are  extremely  important 
in  parallel  programs  because  they  guar¬ 
antee  that  only  one  task  can  access  a 
device  or  data  structure  at  a  time. 
dvmake  uses  them  to  ensure  that  only 
one  task  accesses  a  given  queue  at  any 
time.  If  several  tasks  attempted  to  get 
an  item  from  a  queue  at  the  same  time, 
they  might  all  get  the  same  item,  rather 
than  separate  items  that  they  really  want. 

Mailboxes  are  treated  as  semaphores 
by  using  two  API  mailbox  functions, 
mal_lock(  )  and  mal_unlock(  ).  If  a  mail¬ 
box  is  currently  locked,  any  tasks  that 
attempt  to  lock  it  are  suspended  until 
it  becomes  unlocked,  at  which  time  the 
first  task  that  tried  to  lock  it  succeeds. 

All  API  objects  are  known  by  their 
handle,  an  unsigned  long  integer.  Each 
object  is  accessed  using  that  object’s 
functions.  Window  function  names  start 
with  win_,  task  functions  with  tsk_ , 
mailbox  functions  with  mal_,  applica¬ 


tion  functions  with  app_,  and  so  on. 
API  functions  that  do  not  fit  one  of  the 
object  categories  start  with  api_. 

Meet  Your  Maker 

The  make( )  function  is  only  concerned 
with  finding  the  target  files  in  MkQueue 
that  have  all  of  their  dependents  avail¬ 
able.  It  removes  a  target  from  the  queue, 
runs  through  the  target’s  dependent  list 
( depends_on ),  and  either  puts  the  tar¬ 
get  back  in  MkQueue  (if  the  target  has 
unmade  dependents)  or  gets  ready  to 
start  making  the  target. 

Making  a  target  requires  an  applica¬ 
tion  window  capable  of  executing  the 
commands  listed  in  the  mkfile  and  an¬ 
other  task  to  issue  all  of  the  commands 
to  the  application  window.  The  appli¬ 
cation  window  is  simply  a  DOS  shell 
that  waits  for  commands  to  be  entered 
through  the  keyboard. 

The  API  function,  app_start( ),  takes 
as  an  argument  a  pointer  to  a  program 
information  file  (PIF)  that  has  been 
either  loaded  into  memory  from  disk 
or  created  in  memory,  which  pif_init(  ) 
does.  The  PIF  structure  has  the  same 
layout  as  the  DVP  files  that  DESQview 
creates  for  applications  in  the  Open 
Window  menu. 

The  app_start(  ^function  has  several 
problems  that  need  to  be  addressed. 


DESQview  can  only  start  as  many  pro¬ 
grams  as  can  fit  in  RAM.  When  it  at¬ 
tempts  to  start  a  program  when  there 
is  not  enough  RAM,  DESQview  swaps 
other  programs  to  disk  to  make  room, 
causing  those  programs  to  stop  what¬ 
ever  they  were  doing. 

You  should  set  System  Swapping  in 
the  Rearrange-Tune  Performance  menu 
to  No  to  avoid  the  performance  penalty 
of  swapping.  Or  you  can  simply  set 
the  Swapping  option  to  No  for  the  win¬ 
dow  in  which  you  run  dvmake.  If  you 
don’t,  dvmake  may  get  swapped  to 
disk,  leaving  the  open  application  win¬ 
dows  idle. 

Another  problem  with  app_start(  )  is 
that  whenever  it  is  called,  any  DESQ¬ 
view  menus  that  are  being  displayed 
are  removed  from  the  screen  as  if  you 
had  escaped  out  of  them.  Because 
make(  )  sits  in  a  loop  while  attempting 
to  start  applications,  you  are  essentially 
forbidden  access  to  any  of  DESQview’s 
menus,  including  resizing  or  moving 
windows. 

To  access  DESQview  menus,  you 
must  first  enter  DESQview  with  “Exdev” 
via  the  menu  that  is  put  on  the  screen 
by  dvmenu( ).  When  you  select  the 
menu  option,  the  makeC ) function  stops 
calling  app_  start( )  until  you  either 
quit  or  deselect  the  option.  This  does 
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not  stop  the  other  tasks  from  running, 
it  merely  keeps  any  new  tasks  from 
starting. 

The  final  problem  I  had  with  app_ 
start! )  is  that  the  application  window 
it  creates  always  becomes  the  fore¬ 
ground  window.  This  can  be  partially 
overcome  by  forcing  the  application 
to  the  background  with  the  app _go- 
back( )  API  call.  Even  with  the  small 
time  delay  between  the  two  calls,  the 
new  application  window  can  “eat”  some 
keystrokes,  including  dvmake ,  that  you 
may  have  typed  into  the  foreground 
window. 

After  the  application  window  is  open, 
another  task  is  created  that  runs  the 
dispatch(  )  function  dispatch(  )  sends 
commands  to  the  application  by  plac¬ 
ing  the  keystrokes  directly  into  the  ap¬ 
plication’s  keyboard  buffer.  It  accom¬ 
plishes  this  by  using  the  key_write( ) 
API  call. 

dispatch( )  also  plays  a  key  role  in 
how  you  see  the  output  from  the  vari¬ 
ous  commands  that  are  running  con- 


dvmenu( ) 
task 


main 


dependencies! ) 
make_queue( ) 
startup! ) 


output! ) 


make( ) 
task 


1  1  1 

application 

I  I  1 
dispatch! ) 

windows 

_ 1 _ 1 _ 1 _ 

tasks 

_ i  i  i _ ■ 

finishup! ) 


main( ) 

I 


Figure  1:  Control-flow  diagram  showing  parallel  tasks 


What  Makes  make  Make 


The  concept  of  what  make  does  is 
simple,  but  is  best  explained  with  an 
example.  For  the  sake  of  continuity, 
I  repeat  the  example  provided  by  Al¬ 
len  Holub  in  the  August  1985  DDJ. 
Allen  originally  wrote  mk  (“a  make 
with  half  of  it  missing”),  upon  which 
dvmake  is  based. 

Suppose  you  want  to  create  an 
executable  program  called  farm.exe. 
farm.exe  is  based  upon  three  object 
files,  farm.obj,  cow.obj,  and  pig.obj, 
all  of  which  are,  in  turn,  based  upon 
C  source  files.  All  three  source  files 
have  an  #include  <stdio.h>  statement, 
and  both  cow.c  and  pig.c  have  an 
#include  <animals.b>  statement. 

If  you  change  cow.c,  you  need  to 
recompile  it  to  create  a  new  cow.obj, 
and  then  link  this  with  the  other  ob¬ 
ject  files  to  create  farm.exe.  If  you 
change  something  in  animals. h,  you 
need  to  repeat  the  same  process  for 
both  cow.c  and  pig.c  because  they 
“depend”  upon  animals.h. 

You  describe  the  dependencies  in  a 
makefile,  or  in  dvmake s  case,  a  mkjile. 
You  also  include  in  the  mkfile  the  com¬ 
mands  to  be  executed  to  either  re¬ 
compile  or  relink  the  appropriate  files. 
dvmake  reads  the  mkfile,  figures  out 
what  has  changed,  decides  what  needs 
to  be  updated,  and  executes  the  com¬ 
mands.  A  mkfile  for  the  above  pro¬ 


gram  is  shown  in  Figure  3-  mkfiles 
have  four  parts: 

•  You  designate  a  line  as  a  comment 
by  placing  a  #  sign  in  column  1  of  the 
line. 

•  ‘Targets”  are  files  that  dvmake  has  to 
decide  whether  or  not  to  make.  You 
specify  targets  by  typing  their  names 


#  Make  farm.exe  using  the  turbo  c 

compiler 

farm.exe:  cow.obj  pig.obj  farm.obj 
tlink  /x  farm  cow  pig, farm, ,cc 

pig.obj:  pig.c  animals.h  stdio.h 
fee  -me  -c  pig 

farm.obj:  farm.c  stdio.h 
tcc  -me  -c  farm 

cow.obj:  cow.c  animals.h  stdio.h 
tcc  -me  -c  cow 

#  Null  targets  not  needed  in  a  "real" 

makefile 

#  but  required  for  dvmake 
animals.h: 

stdio.h: 

pig.c: 

cow.c: 

farm.c: 


Figure  2:  dvmake  being  executed 


followed  immediately  by  a  colon. 

•  On  the  same  line  as  the  target,  you 
list  the  “dependencies.”  Dependen¬ 
cies  are  any  files  that  the  target  de¬ 
pends  upon;  that  is,  if  the  depend¬ 
ency  file  changes,  you  want  the  target 
file  updated.  A  target  is  not  required 
to  have  any  dependencies,  and  if  it 
has  none,  it  is  always  made. 

•  On  the  line  or  lines  immediately 
after  the  target  line,  you  list  the  com¬ 
mands  required  to  make  the  target. 
There  may  be  as  few  as  zero,  and 
up  to  MAXBLOCK commands  listed. 
An  empty  line  is  required  to  termi¬ 
nate  the  command  block  and  sepa¬ 
rate  it  from  further  target  lines. 

All  lines  may  be  continued  to  the 
next  line  by  ending  with  a  \  charac¬ 
ter,  just  as  in  C.  For  example 

This  is\ 
one  line) 
of  text. 

For  those  of  you  who  are  make  aficio¬ 
nados,  note  that  I  do  not  mention 
macros.  Macros  allow  you  to  simplify 
many  of  the  command  lines.  Don’t 
fret  over  this  loss,  however,  because 
as  you  will  see  in  Table  1,  dvmake 
won’t  be  your  primary  make  utility. 

—  M.S. 
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(continued  from  page  34) 
currently.  Rather  than  forcing  you  to 
make  sense  of  output  being  displayed 
in  each  of  the  application  windows, 
dispatch( )  attempts  to  redirect  each 
command’s  output  to  a  temporary  file. 
The  output( )  function  is  responsible 
for  displaying  the  temporary  files  in  the 
main  window.  The  output  is  displayed 
in  a  reasonable  order,  and  you  can 
then  redirect  it  to  any  file  you  choose. 

Making  Something 

Running  dvmake  is  extremely  simple, 
although  there  are  many  cautionary 
notes.  You  can  run  dvmake  in  a  DOS 
window  with  64K  or  more  RAM  avail¬ 
able  to  it.  The  window  must  be  non¬ 
swappable,  have  about  15K  of  system 
memory  (setable  on  the  Advanced  Op¬ 
tions  screen  from  Change  a  Program), 
be  able  to  run  in  the  background,  not 
write  directly  to  the  screen,  and  share 
the  CPU  when  in  the  foreground. 

Because  dispatch(  )  sends  commands 
to  application  windows  through  the 
keyboard,  any  programs  you  use  can¬ 
not  intercept  keyboard  input.  If  they 
do,  the  commands  that  dispatch( )  sends 
may  be  received  by  your  program 
rather  than  the  application  window, 
and  will  therefore  not  be  executed  as 
DOS  commands. 

Most  development  tools  allow  you 
to  specify  all  needed  parameters  on  the 
command  line,  which  you  must  do. 
There  is  little  reason  to  run  several 
programs  at  the  same  time  if  all  of  them 
are  expecting  input  from  you,  because 


Program 

Time 

(seconds) 

dvmake 

332 

make  (DESQview) 

278 

make  (DOS) 

131 

Table  1:  dvmake  comparison  with  make 


you  can  only  type  into  one  of  them  at 
a  time. 

The  command  to  run  the  program  is: 
dvmake  l-w]  [-k  nnn]  [target],  and  all 
three  parameters  are  optional.  The  -w 
switch  allows  you  to  see  the  applica¬ 
tion  windows  rather  than  the  default 
of  hiding  them.  The  -k  nnn  switch 
allows  you  to  specify  the  amount  of 
memory  to  give  to  each  application 
window  if  the  default  of  256K  is  either 
not  enough  or  too  much.  You  can  spec¬ 
ify  which  target  file  to  make  by  adding 
its  name  to  the  command  line. 

You  must  have  the  DESQview  API 
C  Library  to  compile  the  program,  al- 
athough  I  have  included  a  runnable 
version  on  this  month’s  source  code 
disk.  Be  sure  to  compile  the  program 
with  byte-alignment  ON,  or  else  the 
PIF  structure  will  not  be  correct. 

The  Bad  News 

I  forewarned  that  running  multiple  tasks 
on  a  single-CPU  computer  was  ineffi¬ 
cient;  I  must  slightly  modify  Jerry 
Pournelle’s  Law  from  “One  user  per 
CPU”  to  “One  task  per  CPU.” 

To  test  dvmake,  I  had  it  make  the 
Small  C  compiler  using  the  Small  C 
compiler  and  Borland  International’s 
Turbo  Assembler  and  linker.  I  ran  the 
program  using  DESQview,  Version  2.24, 
on  my  Dell  Model  310  (20MHz  386) 
with  2  Mbytes  of  memory  and  Quarter¬ 
deck’s  QEMM  memory  manager.  1  also 
compared  dvmakd s  time  with  Borland’s 
make  program  running  under  DOS 
alone  and  as  the  only  task  under  DESQ¬ 
view.  Table  1  shows  the  results.  Com¬ 
paring  the  times  for  Borland’s  make 
shows  how  much  overhead  is  involved 
to  simply  have  DESQview  available. 
There  was  not  much  additional  over¬ 
head  to  run  multiple  tasks  under 
dvmake.  For  those  of  you  who  are 
interested,  I  was  able  to  get  all  four 
parts  of  Small  C  compiling  at  once. 


Extending  the  Program 

You  can  improve  dvmake  in  any  num¬ 
ber  of  ways,  many  of  which  I  consid¬ 
ered  doing,  but  rejected  because  the 
program  would  have  ended  up  all  make 
and  little  DESQview. 

You  may  consider  adding  the  afore¬ 
mentioned  optimized  scheduling  algo¬ 
rithm,  although  as  I  mentioned,  you 
will  get  little  more  than  the  satisfaction 
of  knowing  that  the  program  is  not 
wasting  its  time. 

A  more  useful  addition  would  be 
some  type  of  parameter  for  each  target 
file  that  specifies  the  amount  of  RAM 
to  allocate  for  its  application  window. 
You  could  then  tailor  each  window  to 
the  programs  that  make  the  target,  and 
get  more  tasks  running  concurrently. 

Final  Impressions 

dvmake  should  satisfy  everyone’s  de¬ 
sire  to  put  their  computer  through  its 
paces.  Those  of  you  with  33MHz  386s 
and  8  Mbytes  of  RAM  should  be  able 
to  slow  it  down  to  about  half  the  speed 
of  the  original  PC,  creating  more  lei¬ 
surely  development  cycles. 

Overall,  I  was  impressed  with  how 
the  DESQview  API  performed.  As  the 
source  code  shows,  it’s  fairly  simple  to 
create  multitasking  programs.  This  is  a 
far  cry  from  the  two-page  “Hello,  World” 
programs  using  OS/2,  but  then  again, 
you  still  have  to  shoehorn  your  pro¬ 
grams  into  640K. 
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Circle  Reader  Service  No.  2. 


1=D0S=(  128K  )= 


C:\TURBOCSDU> dvmake  -w  -k  272 


j  |c:vturboc\du>s 

2 - DUMAKE-TASK - 


Nicrosoft(R)  MS-DOS(R)  Version  3.30 

(C)Copyright  Microsoft  Corp  1981-1987 


C: STURBOCSDU) 

C:\TURB0CMW>\ 

tcc  -me  -c  cow  >  C : MURBOCSDVSDVMK0000 . $$$ 


•Access  DU  A4| 
Quit  Q 


Figure  3:  mkfile  program 
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Concurrent  C 

for  Real-Time  Programming 

C  for  parallel  processing 


N.H.  Gehani  and  W.D.  Roome 


Concurrent  C  is  an  upward- 
compatible  extension  of  C 
that  provides  parallel  pro¬ 
gramming  facilities  with  im¬ 
plementations  available  for 
several  versions  of  the  Unix  sys¬ 
tem  (that  is,  System  V  and  BSD 
4.2)  on  a  variety  of  computers.  Con¬ 
current  C  has  also  been  imple¬ 
mented  on  different  kinds  of  mul¬ 
tiprocessors  such  as  a  number  of 
independent  computers  connected 
by  a  local  area  network  (Ethernet). 

A  Concurrent  C  program  is  struc¬ 
tured  as  a  set  of  processes  that 
interact  with  each  other  by  send¬ 
ing  messages.  Messages  are  sent 
to  and  replies  received  from  an¬ 
other  process  by  calling  transac¬ 
tions  associated  with  the  process. 

To  avoid  confusion  with  “database 
transactions,"  we’ll  use  the  term 
“transaction”  to  mean  a  Concurrent  C 
process  interaction.  Transactions  are 
like  remote  procedure  calls  with  one 
important  difference  —  the  receiving  pro¬ 
cess  can  schedule  acceptance  of  the 
calls.  Transactions  can  be  synchronous 
or  asynchronous.  Synchronous  trans¬ 
actions  implement  the  extended  ren¬ 
dezvous  concept  (as  in  the  Ada  lan¬ 
guage):  Two  processes  interact  by  first 
synchronizing,  then  exchanging  infor¬ 
mation  (bidirectional  information  trans- 


Narain  and  William  are  the  architects 
of  Concurrent  C  and  authors  of  The 
Concurrent  C  Programming  Language 
(Silicon  Press).  They  can  be  reached 
at  AT&T  Bell  Labs,  600 Mountain  Ave., 
Mu rray  Hill,  NJ  07974. 


fer),  and  finally  by  continuing  their  in¬ 
dividual  activities.  A  process  calling  a 
synchronous  transaction  is  forced  to 
wait  (unless  it  times  out)  until  the  called 
process  accepts  the  transaction  and  per¬ 
forms  the  requested  service.  With  asyn¬ 
chronous  transactions,  the  caller  does 
not  wait  for  the  called  process  to  ac¬ 
cept  the  transaction;  instead  the  caller 
continues  with  other  activities  after  is¬ 
suing  the  transaction  call.  Information 
transfer  in  asynchronous  transactions 
is  unidirectional,  from  the  calling  pro¬ 
cess  to  the  called  process.  Concurrent 
C,  as  a  compile-time  option,  also  works 
with  C++. 

Our  objectives  in  enhancing  C  with 
concurrent  programming  facilities  were 
to  provide  a  tool  for  writing  programs 


that  run  on  genuinely  parallel  hard¬ 
ware  and  to  provide  a  test  bed  for 
experimenting  with  distributed 
programming  facilities.  In  this  arti¬ 
cle,  we’ll  describe  Concurrent  C 
and  then  use  it  to  write  a  non¬ 
trivial  real-time  program  (a  tty  con¬ 
troller).  We  assume  that  you  are 
familiar  with  the  C  language,  so 
we  only  describe  the  Concurrent 
C  extensions  to  C. 

Concurrent  C  Characteristics 

Concurrent  C  extends  C  for  paral¬ 
lel  programming  by  providing  fa¬ 
cilities  for  specifying  process  types; 
creating  processes;  specifying  the 
processor  on  which  a  process 
is  to  run;  specifying,  querying,  and 
changing  process  priorities;  syn¬ 
chronous  transactions;  asynchro¬ 
nous  transactions;  delays  and  time¬ 
outs;  interrupt  handling;  waiting  for  a 
set  of  events  such  astransactions;  ac¬ 
cepting  transactions  in  a  user-specified 
order;  process  abortion;  and  collective 
termination. 

To  give  you  a  flavor  of  Concurrent 
C,  we’ll  show  you  the  definition  of  a 
process  that  buffers  messages  (charac¬ 
ters  in  this  example).  Producer  pro¬ 
cesses  (pp  call  the  buffer  process  to 
put  messages  in  the  buffer,  and  con¬ 
sumer  processes  (cp  call  it  to  get  mes¬ 
sages  from  the  buffer,  as  shown  in 
Figure  1.  A  process  definition  in  Con¬ 
current  C  consists  of  a  specification  (or 
type)  and  a  body.  Example  1  shows  the 
specification  of  the  buffer  process. 

The  buffer  process  has  two  synchro- 
(continued  on  page  40) 


38 

756 


Dr.  Dobb’s Journal,  November  1989 


(continued  from  page  38) 
nous  transactions:  put  and  get.  Charac¬ 
ters  are  put  into  the  buffer  by  calling 
put,  if  the  buffer  is  full,  a  call  to  put 
will  not  be  accepted.  Transaction  get 
is  used  to  take  characters  from  the 
buffer;  if  the  buffer  is  empty,  a  call  to 
get  will  not  be  accepted  until  a  charac¬ 
ter  is  available. 

The  direction  of  information  transfer 
is  not  dependent  on  which  process 
makes  the  transaction  call.  In  this  ex¬ 
ample,  the  process  calling  transaction 
put  sends  characters  to  the  buffer  pro¬ 
cess  while  the  process  calling  get  gets 
characters  from  the  buffer  process. 

Transactions  put  and  geto(  the  buffer 
process  are  synchronous  in  that  the 
calling  processes  are  blocked  until  the 
transaction  call  is  accepted  and  exe¬ 
cuted.  Transaction  calls  can  be  declared 
to  be  asynchronous  (by  using  the  key¬ 
word  async  instead  of  the  transaction 
result  type),  in  which  case  the  calling 
process  is  not  blocked.  Asynchronous 
transaction  calls  do  not  return  a  result. 

Synchronous  transaction  calls  can  be 
used  for  bidirectional  information  trans¬ 
fer:  Arguments  are  used  to  send  infor¬ 
mation  to  the  called  process  and  the 
transaction  result  is  used  to  return  in¬ 
formation  to  the  calling  process.  Syn¬ 
chronous  transaction  calls  can  also  be 
used  to  synchronize  execution. 

The  buffer  process  type  can  be  used 
just  like  the  predefined  types  to  declare 
variables,  function  types,  and  so  on;  for 
instance,  process  buffer  buf  b[10].  Ex¬ 
ample  2  shows  the  body  of  the  buffer 
process  that  implements  a  circular  buffer. 

The  buffer  process  allocates  space 
for  the  buffer  and  then  repeatedly  exe- 


Figure  1:  The  Concurrent  C  buffer 
process 


process  spec  buffer (int  max) 

{ 

trans  void  put (int  c) ; 
trans  int  get(); 

}; 

Example  1:  Specification  of  the  buffer 
process 
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cutes  a  select  statement  that  is  used  to 
wait  for  a  set  of  alternative  events.  This 
statement  has  two  alternatives,  sepa¬ 
rated  by  the  keyword  or.  Each  alterna¬ 
tive  starts  with  a  Boolean  test  and  is 
followed  by  an  accept  statement.  The 
Boolean  test  is  called  a  “guard”  and 
gives  the  conditions  under  which  that 
alternative  can  be  chosen.  For  exam¬ 
ple,  the  guard  for  the  first  alternative  is 
true  whenever  the  buffer  process  has 
space  to  store  a  character,  and  the  guard 
for  the  second  alternative  is  “true"  when¬ 
ever  the  buffer  process  has  characters 
to  give  out.  Transaction  calls  are  ac¬ 
cepted  using  the  accept  statement. 

When  the  select  statement  is  exe¬ 
cuted,  it  selects  one  alternative,  exe¬ 
cutes  all  statements  in  that  alternative, 
and  skips  the  other  alternative.  For  an 
accept  alternative  to  be  selected,  its 
guard  must  be  true  and  there  must  be 
a  pending  transaction  call  that  satisfies 
the  leading  accept  statement.  If  both 
alternatives  are  eligible,  the  select  state¬ 
ment  picks  one  randomly.  If  both  guards 
are  true  but  no  transaction  calls  are 
waiting,  the  select  statement  waits  for 
the  first  call  of  either  type. 

Initially  the  buffer  is  empty  and  only 
the  first  guard  is  true.  Consequently, 
the  select  statement  waits  for  a  put  trans¬ 
action  call  to  arrive  and  then  executes 
the  first  alternative.  The  buffer  process 
then  loops  back  and  executes  the  select 
statement  again.  Now  both  guards  are 
true,  so  it  waits  for  the  next  put  or  get 
transaction  call  to  arrive. 

Processes  are  created  (instantiated) 
using  the  create  operator;  for  example, 
buf  =  create  buffer(1024).  The  create 
operator  returns  the  process  id  of  the 
newly  created  process.  When  creating 
a  process,  the  processor  on  which  the 
process  is  to  run  and  the  process  prior¬ 
ity  can  also  be  specified. 

Processes  communicate  by  means  of 
transaction  calls  that  have  the  form  pro¬ 
cess-id.  transaction-name! arguments). 
For  example,  character  ‘a’  is  sent  to  the 
buffer  process  with  the  transaction  call 
buf.put('a)  and  is  retrieved  from  the 
buffer  process  with  the  call  c  =  buf 
get(  ).  Transaction  calls  behave  like  func¬ 
tion  calls.  For  example,  get  returns  the 
character  taken  from  the  buffer  as  a 
value  of  type  char.  In  general,  a  trans¬ 
action  call  is  allowed  wherever  a  func¬ 
tion  call  is  allowed. 

Transaction  calls  can  also  be  made 
using  transaction  pointers  that  encap¬ 
sulate  the  process  id  and  the  transac¬ 
tion  name  as  illustrated  by  the  program 
segment  in  Example  3. 

Transaction  pointers  are  similar  to 
function  pointers  except  that  their  dec¬ 
larations  are  prefixed  by  the  keyword 
trans.  Because  a  transaction  pointer 


does  not  include  the  process  type,  a 
transaction  pointer  can  refer  to  transac¬ 
tions  of  different  process  types,  pro¬ 
vided  these  transactions  have  the  same 
parameter  and  return-value  types. 

Concurrent  C  also  supports  timed 
(synchronous)  transaction  calls  that  al¬ 
low  the  calling  process  to  withdraw  the 
transaction  call  if  it  is  not  accepted 
within  the  specified  period. 

As  discussed  earlier,  transaction  calls 
are  accepted  with  the  accept  statement. 
By  default,  these  calls  are  accepted  in 
FIFO  order.  The  order  in  which  these 
calls  are  accepted  can  be  changed  with 
the  by  clause.  The  suchthat  clause  al¬ 
lows  the  selection  of  the  transaction 
call  to  be  based  on  the  arguments  of 
the  transaction  and  on  the  state  of  the 
called  process. 

In  general,  a  select  statement  can  have 
an  arbitrary  number  of  alternatives,  not 
just  two  alternatives  as  shown  in  the 
buffer  example.  The  alternatives  of  the 
select  statement  can  be  used  for  accept¬ 
ing  transaction  calls,  timing  out,  collec¬ 
tive  termination  of  all  the  processes 
leading  to  program  termination,  or  exe¬ 
cution  of  arbitrary  Concurrent  C  state¬ 
ments.  For  any  execution  of  the  select 
statement,  Boolean  expressions  can  be 
used  to  mask  out  one  or  more  of  the 
alternatives. 

Real-Time  Programming  Facilities 

Concurrent  C  allows  transactions  to  be 
accepted  in  a  user-specified  order;  thus 
the  user  can  accept  urgent  transaction 
calls  first.  Specifically,  transaction  call 
acceptance  can  be  based  on  the  trans¬ 
action  name,  the  order  in  which  trans¬ 
action  calls  are  received,  transaction 
arguments,  and  the  state  of  the  called 
process. 

Asynchronous  message  passing  pro¬ 
vides  maximum  flexibility  because  pro¬ 
cesses  can  compute  and  perform  mes¬ 
sage  sends  and  receives  in  parallel  in 
any  way  they  want.  A  process  sending 
a  message  is  not  blocked  until  the  re¬ 
ceiver  gets  around  to  accepting  the  mes¬ 
sage;  this  allows  the  sender  to  attend 
to  other,  possibly  critical,  events.  Asyn¬ 
chronous  message  passing  is  especially 
important  in  situations  where  the  inter¬ 
process  communication  time  is  high 
(as  in  case  of  multiprocessors).  Asyn¬ 
chronous  message  passing  also  allows 
pipelining  of  multiple  messages  from 
the  same  process  and  allows  the  re¬ 
ceiving  process  to  accept  the  messages 
in  the  most  appropriate  order. 

Concurrent  C  provides  facilities  for 
specifying,  querying,  and  changing 
process  priorities.  Process  priorities  are 
specified  when  creating  a  process,  but 
the  priority  can  be  changed  at  any  time. 

(continued  on  page  43) 
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Processes  that  need  to  respond  quickly 
to  events  such  as  interrupts,  which  need 
immediate  attention,  are  given  high 
priorities. 

Concurrent  C  provides  facilities  for 
timed  synchronous  transaction  calls. 
This  allows  a  process  to  withdraw  a 
transaction  call  if  it  has  not  been  ac¬ 
cepted  within  the  specified  period.  A 
process  can  also  time-out  if  a  transac¬ 
tion  call  does  not  arrive  within  a  speci¬ 
fied  period.  Time-outs  prevent  a  pro¬ 
cess  from  being  blocked  for  an  unduly 
long  period. 

An  important  aspect  of  real-time  pro¬ 
gramming  is  interrupt  handling.  The 
implementation-dependent  function  c_ 
associate  is  used  to  indicate  that  the 
specified  interrupt  should  be  converted 
to  a  call  to  the  specified  transaction. 
To  avoid  losing  interrupts,  it  is  impor¬ 
tant  that  they  (the  associated  transac¬ 
tions)  are  handled  quickly.  Delay  in 
handling  interrupts  can  occur  because 
of  the  overhead  in  converting  the  inter¬ 
rupt  to  a  transaction  call,  the  delay  in 
scheduling  the  driver  process,  and  the 
delay  in  accepting  the  call. 

These  items  are  implementation-  and 
application-dependent.  In  many  cases, 
by  giving  the  interrupt  handling  pro¬ 
cess  a  high  priority  and  designing  this 
process  to  give  preference  to  accepting 
interrupt  transactions,  interrupts  can  be 
handled  within  real-time  constraints. 

A  Display-Terminal  Driver  Example 

Suppose  that  you  are  writing  the  soft¬ 
ware  for  an  embedded  system  —  one 
that  runs  on  a  dedicated  microproces¬ 
sor.  Examples  of  embedded  systems 
are  an  industrial  process  controller,  a 


Example  2:  The  body  of  the  buffer 
process  which  implements  a  circular 
buffer 


Example  3:  Transaction  calls  can  be 
made  using  transaction  pointers 


robot  controller,  or  the  control  pro¬ 
gram  for  a  VCR.  Let’s  suppose  a  display 
terminal  is  connected  to  your  system, 
and  occasionally  you  want  to  write  mes¬ 
sages  to  that  display  and  wait  for  the 
user  to  type  a  reply.  Your  program  runs 
on  a  bare  machine  —  there  is  no  oper¬ 
ating  system,  so  you  have  to  write  all 
the  software  for  controlling  the  display. 

First  we'll  give  a  simplified  descrip¬ 
tion  of  the  device  (alas,  real  devices  are 
not  this  simple,  but  if  you  follow  this 
example,  you  should  have  no  trouble 
with  real  hardware).  The  device  inter¬ 
face  consists  of  two  8-bit  registers,  the 
input  and  output  character  buffers,  and 
two  flag  bits,  input-ready  and  output- 
ready.  These  are  in  the  processor’s  mem¬ 
ory  and  can  be  accessed  like  any  other 
memory  locations.  Whenever  the  output- 
ready  bit  is  on,  the  program  can  write 
a  character  into  the  output  character 
register.  The  hardware  then  turns  the 
output-ready  bit  off  and  sends  the  char¬ 
acter  to  the  display.  When  the  charac¬ 
ter  has  been  sent,  the  hardware  turns 
the  output-ready  bit  back  on,  and  the 
software  can  write  another  character. 
At  9600  baud,  it  takes  about  1  millisec¬ 
ond  to  output  a  character;  at  1200  baud, 
it  takes  about  8.3  milliseconds.  When 
the  user  types  a  character  on  the  key¬ 
board,  the  hardware  places  that  char¬ 
acter  in  the  input  character  register  and 
turns  on  the  input-ready  bit.  The  pro¬ 
gram  can  then  read  the  character  from 
the  register.  When  that  happens,  the 
hardware  turns  off  the  input-ready  bit 
until  the  user  types  the  next  character. 
Once  the  user  has  typed  a  character, 
our  program  must  read  that  character 
from  the  input  register  before  the  user 
types  another  character;  if  not,  the  char¬ 
acter  will  be  lost. 


Figure  2:  Processes  in  the  TTY 
subsystem 
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The  hardware  also  generates  an  input- 
ready  interrupt  when  it  turns  the  input- 
ready  bit  on,  and  an  output-ready  in¬ 
terrupt  when  it  turns  the  output-ready 
bit  on. 

Note  that  the  terminal  is  really  two 
independent  devices:  A  display  for  out¬ 
put  and  a  keyboard  for  input.  When 
the  user  types  a  character,  the  hard¬ 
ware  does  not  automatically  display 
that  character  on  the  screen.  Instead, 
our  software  must  “echo”  that  charac¬ 
ter  to  the  display.  Furthermore,  most 
display  devices  have  separate  carriage 
return  and  line  feed  operations;  when 
the  user  types  Return,  our  software 
should  send  a  carriage  return  and  a  line 
feed  to  the  display.  We  would  also  like 
to  give  the  user  a  few  creature  com¬ 
forts:  Backspace  should  erase  the  pre¬ 
vious  character,  Ctrl-C  (for  example) 
should  kill  the  line  that  the  user  has 
typed,  Ctrl-S  should  stop  output  so  the 
user  can  read  the  display,  and  Ctrl-Q 
should  restart  output. 

The  simple  way  to  output  characters 
to  the  display  is  to  repeatedly  test  the 
output-ready  bit  until  it’s  on,  write  the 
character  to  the  output  register,  and 
repeat  until  all  the  characters  are  writ¬ 
ten.  This  is  called  “wait-loop”  I/O.  The 
disadvantage  is  that  the  system  cannot 
do  anything  else  until  the  output  is 
complete.  Sometimes  this  is  acceptable, 
but  usually  it  isn’t.  And  even  if  wait- 
loop  I/O  is  acceptable  for  output,  it 
probably  will  not  be  for  input  —  the 
user  types  too  slowly! 

We  need  a  solution  that  allows  input 
from  the  keyboard  and  output  to  the 
display  to  overlap  with  other  proces¬ 
sing —  we  need  concurrent  program¬ 
ming.  The  solution  is  to  use  several 
processes  that  form  a  subsystem  of  our 
program  and  provide  display  input  and 
output  services  to  the  other  processes 
in  our  program.  For  historical  reasons, 
we’ll  call  these  processes  the  “TTY 
driver”  subsystem. 

Figure  2  illustrates  the  interaction  be¬ 
tween  the  processes.  Characters  typed 
by  the  user  flow  down  on  the  left  from 
the  keyboard  hardware  to  the  ttylnput 
process,  where  they  are  taken  by  other 
processes  in  our  program.  Characters 
to  be  displayed  flow  up  on  the  right 
from  other  processes  to  the  ttyOutput 
process  and  then  to  the  display  hard¬ 
ware.  Process  ttyOutput  handles  out¬ 
put  to  the  display,  and  process  ttylnput 
is  the  input  buffer  process.  These  pro¬ 
cesses  form  the  “client  interface”  to  the 
TTY  subsystem,  while  other  processes 
(“clients”)  in  the  program  call  put  of 
ttyOutput  to  send  characters  to  the  dis¬ 
play,  and  call  get  of  ttylnput  to  read 
characters  typed  on  the  keyboard.  Pro¬ 
cesses  ttyLine  and  ttyReader  are  inter¬ 
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nal  processes  (they  interact  only  with 
other  processes  of  the  TTY  subsystem) 
and  will  be  described  later.  The  specifica¬ 
tion  of  the  TTY  subsystem  processes 
is  shown  in  Listing  One  (page  100). 

Characters  are  output  by  calling  trans¬ 
action  put  of  ttyOutput;  its  arguments 
are  the  number  of  characters  and  a 
pointer  to  the  start  of  the  string.  Trans¬ 
action  put  queues  the  characters  for 
output;  the  transaction  returns  before 
the  characters  are  sent  to  the  display. 
Transaction  ready  is  called  when  an 
output-ready  interrupt  occurs,  stop  tem¬ 
porarily  stops  the  output  to  the  display, 


A  concurrent 
programming  language 
such  as  Concurrent  C 
lets  you  turn  a 
concurrent  program 
problem  into  a  set  of 
sequential 

programming  problems 


and  start  restarts  the  output.  Process 
ttyOutput  accepts  put  transaction  calls 
even  when  the  output  is  stopped;  the 
characters  are  queued  until  output  is 
resumed. 

We  require  the  processes  that  call 
transaction  put  to  end  a  line  with  a 
carriage  return  and  line-feed  charac¬ 
ters;  this  simplifies  the  ttyOutput  pro¬ 
cess. 

Process  ttylnput  is  the  input  buffer 
process.  The  characters  in  this  buffer 
have  been  “cooked:”  They  have  been 
echoed  to  the  display,  backspace  and 
line-kill  processing  have  been  per¬ 
formed,  and  so  on.  If  characters  are 
available  in  the  buffer,  transaction  get 
returns  the  next  character.  If  the  buffer 
is  empty  and  the  argument  is  1 ,  then 
get  waits  for  a  character  to  arrive.  If  the 
argument  is  0,  then  pel  returns  -1  im¬ 
mediately.  Thus  get(O)  is  non-block¬ 
ing.  Transaction  put  inserts  a  character 
into  the  input  buffer. 

Any  number  of  processes  can  output 
characters  at  the  same  time.  Process 
ttyOutput  guarantees  that  the  charac¬ 
ters  written  by  one  put  transaction  call 
will  be  printed  together  on  the  display. 


So  if  several  processes  output  data  at 
the  same  time,  as  long  as  each  put 
transaction  sends  one  line,  the  lines 
will  be  interleaved  in  an  arbitrary  fash¬ 
ion,  but  the  characters  in  each  line  will 
stay  together.  If  several  processes  try 
to  get  characters  from  ttylnput  at  the 
same  time,  they  will  get  characters  on 
a  first-come,  first-served  basis.  This  is 
probably  not  what  you  want.  We  as¬ 
sume  that  the  processes  cooperate 
among  themselves  to  ensure  that  only 
one  process  tries  to  read  characters  at 
a  time  —  usually  this  occurs  naturally. 

Process  ttyReader  is  a  simple  buffer 
manager;  it  takes  characters  from  the 
hardware  input  register  as  soon  as  the 
user  types  them,  and  saves  them  in  a 
buffer.  Transaction  ready  of  this  pro¬ 
cess  is  called  when  an  input-ready  in¬ 
terrupt  occurs,  and  process  ttyLine  calls 
get  to  get  characters  from  the  buffer. 
The  process  ttyLine  has  no  transac¬ 
tions;  it  gets  characters  from  ttyReader ; 
echoes  them  to  ttyOutput ,  handles  back¬ 
space  and  line-kills,  and  so  on.  When 
ttyLine  gets  a  full  line,  it  sends  the 
characters  in  that  line  to  the  ttylnput 
process. 

Function  ttyReply  (see  Listing  Two, 
page  100)  illustrates  how  to  use  these 
processes.  It  first  prints  the  msg  argu¬ 
ment  on  the  display  and  then  waits  for 
the  user  to  type  a  reply  line,  which  the 
function  saves  in  the  reply  argument. 
If  the  user  does  not  type  a  reply  within 
30  seconds,  the  function  prints  a  nasty 
message  and  starts  over.  This  function 
uses  the  timed-transaction  call 

within  30  ?  ttyln.get(l) :  -1 

If  the  ttyln  process  accepts  the  get 
transaction  call  within  30  seconds,  the 
value  of  this  expression  is  the  value 
returned  by  the  process.  If  the  process 
does  not  accept  the  geltransaction  call, 
then  the  call  is  automatically  withdrawn, 
the  second  expression  (-/)  is  evalu¬ 
ated,  and  its  value  becomes  that  of  the 
expression.  So  if  the  user  types  a  char¬ 
acter  within  30  seconds,  the  function 
breaks  out  of  the  loop  and  reads  the 
rest  of  the  line.  If  not,  the  function 
prints  a  nasty  message  and  repeats. 

Implementation 

Function  ttylnit  (Listing  Three,  page 
100)  creates  the  TTY  subsystem  pro¬ 
cesses  and  saves  their  ids  in  global 
variables.  Normally,  main  will  call  tty¬ 
lnit  when  the  program  starts.  Notice 
that  we  have  specified  priorities  for 
some  of  the  processes.  If  no  priority  is 
specified,  a  process  is  created  with  pri¬ 
ority  0.  Process  ttyOutput  is  created 
with  priority  1,  so  that  when  it  is  ready  — 
that  is,  when  the  display  is  ready  for  a 
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character  —  the  ttyOutput  process  will 
be  scheduled  before  the  other  processes. 
Process  ttyReader  is  given  priority  2 
because  it  is  even  more  important  that 
we  take  a  character  from  the  input  re¬ 
gister  as  fast  as  possible. 

Function  c_associate  arranges  to  call 
a  transaction  when  an  interrupt  occurs. 
The  first  argument  is  a  transaction 
pointer  specifying  the  process  and  trans¬ 
action  to  be  called.  The  second  argu¬ 
ment  specifies  the  interrupt.  Listing  Four, 
page  100,  gives  some  definitions  that 
are  common  to  all  of  the  processes  in 
the  TTY  subsystem. 

Process  ttyReader(Usling  Five,  page 
100)  is  a  variant  of  the  buffer  manager 
in  Example  2.  It  loops  forever,  waiting 
for  either  a  ready  or  a  get  transaction. 
Transaction  get  takes  a  character  from 
the  buffer  and  returns  it,  just  as  in  the 
buffer  manager.  Transaction  ready  is 
automatically  called  when  the  hard¬ 
ware  generates  an  input-ready  interrupt. 
ttyReader  then  calls  the  uartGetChar 
function  (the  hardware  interface  to  the 
device  is  often  called  a  Universal  Asyn¬ 
chronous  Receiver/Transmitter  or  UART) 
to  get  a  character  from  the  input  regis¬ 
ter.  If  it  is  a  start  or  stop  character,  the 
process  calls  the  appropriate  transaction 
of  the  ttyOutput  process.  Otherwise,  if 
there  is  space  in  the  buffer,  the  process 
saves  the  character;  if  not,  it  discards 
the  character. 

Note  that  when  the  buffer  is  full,  we 
discard  characters  rather  than  not  ac¬ 
cepting  ready  transactions.  We  do  this 
so  that  we  can  always  accept  a  start 
character.  Suppose  that  the  user  types 
a  stop  character  and  then  continues 
typing.  The  ttyOutput  process  will  even¬ 
tually  fill  up  its  buffer  and  will  not 
accept  put  transactions  until  output  is 
restarted.  Because  ttyLine  calls  put  to 
print  the  characters  entered  at  the  key¬ 
board,  ttyLine  will  eventually  stop  until 
output  is  restarted.  Because  ttyLine  is 
the  only  process  that  takes  characters 
from  the  ttyReader  process’  buffer,  the 
ttyReader  buffer  will  eventually  fill  up. 
At  that  point  the  system  will  be  frozen 
until  the  user  types  a  “start"  character. 
If  ttyReader  stops  accepting  characters 
when  its  buffer  is  full,  then  the  user 
could  never  type  a  start  character,  and 
the  system  would  be  deadlocked.  That 
is  why  ttyReader  always  accepts  char¬ 
acters  typed  by  the  user,  even  if  it  has 
to  discard  them. 

Process  ttyLine  (Listing  Six,  page  100) 
maintains  a  buffer  containing  the  line 
that  the  user  is  currently  typing.  ttyLine 
repeatedly  gets  a  character  from  the 
ttyReader  process,  handles  that  charac¬ 
ter,  and  if  the  line  is  complete,  sends  the 
line  to  the  ttylnput  process  and  clears 
the  buffer.  For  example,  when  given 


an  "erase”  character  (backspace),  the 
process  outputs  a  backspace,  blank,  and 
backspace  to  erase  the  last  character  on 
the  display,  and  then  erases  the  last 
character  in  the  line  buffer. 

The  input  processing  is  not  sophisti¬ 
cated.  For  example,  in  many  display 
drivers,  a  special  character,  such  as  back¬ 
slash  (  \  ),  indicates  that  the  next  char¬ 
acter  is  to  be  treated  as  a  regular  char¬ 
acter.  ttyLine  does  not  do  that,  but  it 
would  be  relatively  easy  to  add  it.  Add¬ 
ing  this  feature  is  a  sequential  pro¬ 
gramming  problem,  not  a  concurrent 
programming  one.  A  concurrent  pro¬ 
gramming  language  such  as  Concur¬ 
rent  C  lets  you  turn  a  concurrent  pro¬ 
gram  problem  into  a  set  of  sequential 
programming  problems  —  namely  the 
processes  —  that  you  can  then  solve 
independently. 

Process  ttylnput  (Listing  Seven,  page 
100)  manages  the  input  buffer.  It  is  al¬ 
most  identical  to  the  buffer  process  in 
Example  2.  The  only  addition  is  a  sec¬ 
ond  accept  statement  for  the  get  trans¬ 
action.  The  guards  on  those  two  accept 
statements  are  mutually  exclusive;  The 
first  guard  is  true  only  if  the  buffer  has 
characters,  the  second  is  true  only  if  the 
buffer  is  empty.  The  second  accept  state¬ 
ment  has  a  such  that  clause  that  Concur¬ 
rent  C  evaluates  for  each  pending  trans¬ 
action  call.  If  the  expression  is  true  (non¬ 
zero),  Concurrent  C  accepts  that  call; 
otherwise,  Concurrent  C  holds  the  trans¬ 
action  call  so  that  it  can  be  accepted 
later.  Thus  if  the  buffer  has  characters, 
the  process  accepts  a  get  transaction 
regardless  of  the  value  of  the  argument. 
When  the  buffer  is  empty,  the  process 
only  accepts  get  transactions  whose  ar¬ 
guments  are  0 —  that  is,  the  non-lock¬ 
ing  get  requests.  Therefore  ttylnput  im¬ 
mediately  accepts  any  get(O)  transac¬ 
tion  call;  if  the  buffer  has  a  character, 
the  process  returns  it;  otherwise,  ttyLn- 
put  returns  -1.  On  the  other  hand,  a 
get(l)  ca\\  will  only  be  accepted  when 
the  buffer  has  a  character. 

Process  ttyOutputi Listing  Eight,  page 
100)  manages  the  output  buffer.  It  re¬ 
peatedly  waits  for  one  of  four  possible 
transaction  calls  and  sends  a  character 
to  the  display  if  the  display  is  ready, 
output  has  not  been  stopped,  and  there 
is  a  character  in  the  buffer.  Transaction 
ready  is  called  when  the  device  gener¬ 
ates  an  output-ready  interrupt.  Func¬ 
tion  uartPutChar  writes  a  character  to 
the  output  register.  Note  how  we  use 
a  suchthat  clause  with  the  put  transac¬ 
tion  to  accept  the  call  only  if  there  is 
enough  space  in  the  buffer.  Also  note 
that  the  process  accepts  put  calls  even 
when  output  is  stopped,  as  long  as 
there  is  space  in  the  buffer. 

At  press  time,  AT&T  is  planning  to 


make  Concurrent  C  a  product  that  will 
be  available  in  the  near  future.  The 
reader  interested  in  Concurrent  C  can 
call  1-800-828-UNIX  to  check  on  the 
availability  of  Concurrent  C. 
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Linking 

While  The  Program 
Is  Running 

Run-time  dynamic  linking  in  OS/2 

Andrew  Schulman 


"In  theory  anyway  linking  to  a  target 
<t>  can  he  achieved  at  the  earliest  when¬ 
ever  it  becomes  feasible  to  make  <t> 
known.  It  is,  in  fact,  even  more 
interesting  to  consider  until  bow  late 
linking  can  be  postponed.  ” 

—  Elliott  I.  Organick 
The  Multics  System:  An  Examination 
of  its  Structure  ( 1972) 

“ The  evolution  of  loaders  is  interesting 
because  it  is  an  example  of  a  trend 
common  to  many  areas  of  both  soft¬ 
ware  and  hardware,  the  trend  to  delay 
binding  as  long  as  possible.  ” 

—  Robert  M.  Graham 
Principles  of  Systems  Programming 

(1975) 


Once  upon  a  time,  there  was 
no  such  thing  as  linking,  or 
at  least  no  such  thing  as  a 
“linkage  editor.”  As  long  as 
there  was  no  separate  or  in¬ 
dependent  compilation,  there  was  no 
need  for  a  program  that  combines  frag¬ 
ments  of  programs.  But  as  soon  as  there 
were  “linkers,”  it  became  interesting 
to  see  how  long  linking  could  be  de¬ 
ferred.  (“Never  do  today  what  you  can 
put  off  until  tomorrow.”) 

Every  professional  programmer  has 
heard  that  OS/2  is  built  on  “dynamic 
linking,”  a  standardized  mechanism  for 
attaching  add-ins  to  the  operating  sys¬ 
tem.  OS/2,  itself,  consists  largely  of  add¬ 
ins;  for  example,  the  Presentation  Man- 
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ager’s  (PM)  graphical  windowed  envi¬ 
ronment  is  a  collection  of  OS/2  dynamic- 
link  libraries  (DLLs),  as  is  the  OS/2 
kernel  application  program  interface 
(API). 

The  operation  of  dynamic  linking  is 
largely  transparent  to  the  programmer. 
As  David  Cortesi  explained  in  his  De¬ 
cember  1987  DDJ article  “Dynamic  Link¬ 
ing  in  OS/2:  Built-in  facilities  for  the 
third-party  extension  of  OS/2,”  a  pro¬ 
grammer  using  a  procedure  in  a  DLL 
declares  it  just  as  he  would  declare  any 
other  external  reference;  calls  to  such 
a  procedure  look  the  same  as  calls  to 
a  routine  in  a  “normal”  static-link  .LIB 
library.  The  only  immediately  visible 
difference  is  a  smaller  executable  file. 
The  actual  code  for  the  procedure  is 
kept  in  the  DLL,  not  copied  into  your 
executable  file  as  in  normal  linking. 
OS/2  does  all  the  work  of  dynamically 
linking  to  the  DLL  code. 

But  there  is  another  form  of  dynamic¬ 
linking  that  is  not  transparent.  Called 
“run-time  dynamic  linking,"  this  method 
of  linking  requires  you  carry  out  “by 
hand"  the  work  normally  done  by 
LINK.EXE  and  OS/2.  In  exchange,  you 
get  to  defer  linking  until  very  late  —  in 
fact,  linking  takes  place  while  the  pro¬ 
gram  is  running! 

Why  Would  You  Want  to  Do  That? 

Because  computing  consists  largely  of 
“solutions  in  search  of  a  problem,”  and 
of  building  features  that  no  one  has  yet 
asked  for,  you  frequently  encounter 
facilities  that  are  nifty  but  not  useful. 
So,  before  we  get  into  how  they  work, 
we  d  better  determine  what  run-time 
dynlinks  are  for  in  the  first  place. 

The  ability  to  defer  linking  so  that  it 
occurs  during  run-time  can  be  used  in 


any  application  in  which  users  can  do 
programming  while  the  application  is 
running.  Examples  include  any  inter¬ 
preted  language,  an  Emacs  text  editor 
with  an  embedded  language,  a  data¬ 
base  manager  or  spreadsheet  with  a 
LOAD/CALL  add-in  facility,  or  a  de¬ 
bugger  with  an  “execute  statement” 
menu  option.  A  straight  object-code 
compiler  is  not  an  example  because 
the  programming  is  done  before  the 
compiler  is  run. 

There  is  a  close  parallel  between 
“delayed  linking”  and  what  in  object- 
oriented  programming  (OOP)  is  called 
“late  binding.”  (The  two  are  not  syn¬ 
onymous,  however.)  With  OOPs,  late 
(delayed)  binding  turns  a  selector  into 
the  actual  method  to  handle  a  mes¬ 
sage.  In  OS/2,  delayed  linking  takes 
commands  a  user  issues  at  run-time 
and  turns  them  into  actual  function  calls. 

In  both  OOPs  and  OS/2,  it  is  defi¬ 
nitely  not  the  program’s  responsibility 
to  maintain  the  table  that  associates 
symbolic  names  with  actual  code,  be¬ 
cause  that  would  constitute  early  bind¬ 
ing.  Your  program’s  responsibility  is 
to  pass  the  symbolic  names  through, 
without  interpreting  them.  This  means 
that  with  both  OOPs  and  OS/2  run¬ 
time  dynamic  linking,  a  program  can 
use  facilities  that  didn’t  even  exist  when 
the  program  was  compiled. 

There  is  more  than  an  analogy  be¬ 
tween  OS/2  delayed  linking  and  OOPs 
delayed  binding.  Some  object-oriented 
systems,  such  as  the  Andrew  Toolkit 
and  Class  C  preprocessor  developed 
at  Carnegie-Mellon  University,  use  de¬ 
layed  linking  in  order  to  implement 
dynamic  demand  loading  and  linking 
of  classes  in  running  applications.  (For 
a  discussion  of  the  connection  between 
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(continued  from  page  46) 
dynamic  binding  and  dynamic  linking, 
see  Philippe  Gautron  and  Marc  Shapiro, 
“Two  Extensions  to  C++:  A  Dynamic 
Link  Editor  and  Inner  data,”  Usenix 
Proceedings  C++  Workshop,  Santa  Fe, 
New  Mexico  1987).  Because  of  its  sup¬ 
port  for  run-time  dynlinks,  OS/2  is  a 
perfect  platform  for  building  OOPs 
environments. 

The  Importance  of  Being  ASCIIZ 

“Our future plans  include:  .  .  Program¬ 
matic  interface:  Some  programs,  par¬ 
ticularly  based  on  interpretive  languages 
such  as  Lisp,  can  dynamically  gener¬ 
ate  dynamic  references.  We  would  like 
to  support  the  handling  of  such  refer¬ 
ences  through  a  common  mechanism, 
and  thus  wish  to  provide  a  program- 
accessible  interface  to  the  services  now 
provided  invisibly.  ” 

—  Robert  A.  Gingell,  et  al., 
Shared  Libraries  in  SunOS  (,  1987). 

OS/2’s  programmatic  interface  for  dy¬ 
namic  linking  under  program  control 
is  built  upon  the  functions  listed  in 
Table  1  that  comprise  the  OS/2  module 
manager.  Of  these,  DosLoadModule  and 
DosGetProcAddr  are  the  crucial  func¬ 
tions.  In  fact,  with  these  two  functions 
alone  we  can  access  the  others,  for 
with  these  two  functions  we  can  in  fact 
access  any  function  in  an  OS/2  DLL. 

Those  of  you  familiar  with  Microsoft 
Windows  will  detect  the  similarity  to 
LoadLibrary(  )  and  GetProcAddress(  ), 
and  those  familiar  with  the  Macintosh 
can  consider  OS/2’s  DosGetProcAddr 
combination  of  the  toolbox  a  Named 
ResouvceC  )  Gerand  GetTrapAddressC ). 
And  programmatic  access  to  shared  librar¬ 
ies  is  planned  for  the  forthcoming  re¬ 
lease  4.0  of  Unix  System  V  ( Unix  Re¬ 
view,  August  1989). 

Run-time  dynlinks  illustrate  the  im¬ 
portance  of  ASCII  strings  in  OS/2.  Nearly 
any  object  in  OS/2  can  have  an  ASCIIZ 
(zero-terminated  ASCII  string)  name  as¬ 
sociated  with  it.  The  well-known 
“named  pipes”  of  the  LAN  Manager  are 
one  example.  Just  as  most  systems  make 
it  easy  to  access  a  file  if  you  know  its 
name,  OS/2  also  makes  it  easy  to  ac¬ 
cess  pipes,  semaphores,  queues,  or 
shared  memory  blocks  if  you  know 
their  names  (see  Ray  Duncan,  “Inter¬ 
process  Communications  in  OS/2,”  June 
1989  DDf).  Likewise,  with  run-time  dyn- 


DosLoadModule 

DosGetProcAddr 

DosFreeModule 

DosGetModName 

DosGetModHandle 


Table  1:  The  OS/2  module  manager 


links,  if  you  have  the  ASCIIZ  name  of 
a  routine,  you  can  load  the  code  for  the 
routine  and  derive  its  equivalent  func¬ 
tion  pointer. 

Given  the  ASCIIZ  name  of  a  DLL, 
DosLoadModule  loads  the  DLL  and  re¬ 
turns  a  handle  to  it.  This  module  han¬ 
dle  can  then  be  passed,  along  with  the 
ASCIIZ  name  of  a  procedure  exported 
from  the  DLL,  to  DosGetProcAddr, 
which  returns  the  function  pointer  cor¬ 
responding  to  the  procedure  name. 

A  function  which,  given  an  ASCIIZ 
string,  returns  a  function  pointer,  is 
typical  of  interpreters  and  debuggers. 
Here  we  find  it  at  the  core  of  an  operat¬ 
ing  system. 

Furthermore,  OS/2  is  providing  more 
than  just  a  functional  interface  to  a 
symbol  table.  Ralph  Griswold,  inven¬ 
tor  of  the  string-oriented  programming 
languages  SNOBOL  and  Icon,  makes 
the  point  that  run-time  dynamic-link¬ 
ing  "takes  two  forms:  1.  Connecting 
the  string  name  of  a  function  with  resi¬ 
dent  code  for  it  —  that  is,  doing  at  run¬ 
time  what  usually  is  done  at  compile¬ 
time,  and;  2.  Actually  loading  non¬ 
resident  code  for  a  named  function. 
The  latter  is,  of  course,  more  difficult 
to  implement  than  the  former."  OS/2 
provides  the  second  variety  of  delayed 
linking,  which  is  a  superset  of  the  first. 

While  OS/2  provides  a  method  for 
turning  ASCIIZ  names  into  function  point¬ 
ers,  possibly  by  loading  the  code  for 
the  function,  it  does  not  provide  any 
method  for  actually  calling  the  func¬ 
tion.  It  provides  “directory  assistance,” 
but  won't  dial  the  number  for  you. 
Instead,  the  function  pointer  returned 
from  DosGetProcAddrshou\d  be  passed, 
together  with  any  arguments  the  pro¬ 
cedure  expects,  to  whatever  facility  your 
language  provides  for  indirect  far  calls. 

Using  the  OS/2  Module  Manager 

CALLDLL1.C  (Listing  One,  page  102)  is 
a  short  example  of  how  this  works. 
When  this  rather  contrived  example 
runs,  it  links  to  the  file  ALIAS.DLL. 
(ALIAS  is  a  handy  command-line  editor 
for  OS/2,  written  by  Andrew  Estes,  and 
modelled  after  Chris  Dunford’s  CED 
for  MS-DOS.)  CALLDLL1.C  calls  two 
procedures  provided  by  ALIAS:  First,  a 
command-line  synonym  is  added  to 
ALIAS’S  synonym  table,  then  we  ask 
ALIAS  to  display  the  table. 

If  DosLoadModule  returns  anything 
other  than  0,  it  was  unable  to  load  the 
requested  module.  It  will  also  fill  a 
buffer  with  the  name  of  the  offending 
module  if  you  provide  such  a  buffer  (in 
CALLDLL1.C,  I  didn't).  This  sounds  silly, 
because  the  offending  module  is  the 
same  as  the  module  you  asked  to  be 


loaded  —  but  that’s  not  actually  the  case; 
DLLs  can  call  other  DLLs.  Note  also 
that  DosLoadModule  should  be  passed 
the  name  of  the  module,  (that  is,  ALIAS), 
not  the  name  of  the  file  (for  example, 
ALIAS.DLL),  except  when  accessing  a 
DLL  not  located  along  your  LIBPATH. 
In  that  case  use  the  full  pathname.  (For 
example, 

"C:\  \OS2\  \ALIAS\  \ALIAS.DLL" 

In  Listing  One,  I’m  using  hard-wired 
strings  instead  of  hard-wired  function 
pointers  (  LLST_SYN  instead  of  List_ 
Syn( ) ).  This  helps  to  illustrate  how 
run-time  dynamic  linking  works,  but 
generally  it  is  pointless  to  trade  one 
form  of  inflexibility  for  another.  Instead 
of  embedding  string  literals  like  ALIAS 
and  /J571SL7Vdirectly  in  the  code,  usu¬ 
ally  we’ll  use  a  string-valued  variable 
or  an  expression  that  yields  a  string. 

This  example  isn’t  quite  as  foolish 
as  it  first  appears.  Had  this  program 
accessed  List_Syn( )  using  load-time  dy¬ 
namic  linking,  OS/2  would  refuse  to 
even  load  the  program  on  a  machine 
that  didn’t  have  ALIAS:  “SYS1804:  The 
system  cannot  find  the  file  ALIAS.”  But 
by  using  run-time  dynamic  linking,  the 
program  itself  detects  the  absence  of 
the  DLL  and  can  respond  in  some  ap¬ 
propriate  way.  This  is  an  additional 
benefit  of  run-time  dynamic  linking  over 
load-time  ("eager")  dynamic  linking. 
Load-time  dynamic  links  are  hard-wired; 
they’re  actually  not  all  that  dynamic. 

There  is  one  “gotcha”  involved  with 
calling  DosGetProcAddr,  which  trips  ev¬ 
erybody  up  at  least  once:  It  is  case- 
sensitive.  In  Listing  One.  I  passed  the 
the  function  name  ADDSYN  to  DosGet¬ 
ProcAddr.  DosGetProcAddr  would  have 
failed  on  “AddSyn"  or  “addsyn,”  re¬ 
turning  ERROR_PROC_NOT_FOUND. 
The  name  you  use  must  match  exactly 
the  name  exported  from  the  DLL.  To 
get  a  listing  of  these  names,  you  can 
use  Microsoft's  EXEHDR  utility.  Un¬ 
fortunately  there  is  no  OS/2  API  call 
to  enumerate  the  procedures  a  DLL 
exports  (though  you  can  write  enum- 
proc  ( /yourself). 

Generally,  routines  that  use  the  Pas¬ 
cal  calling  convention  will  be  exported 
in  ALL  CAPS,  though  Modula-2  compil¬ 
ers  for  OS/2  produce  export  names 
that  look  like  Module$ProcName  or  Mod- 
ule_ProcName.  DLL  routines  using  the 
cdecl  calling  convention  will  generally 
be  exported  in  _lowercase,  with  a  lead¬ 
ing  underscore. 

There’s  one  other  trick  to  using  Dos¬ 
GetProcAddr.  Unfortunately,  while  the 
OS/2  kernel  masquerades  as  DOS- 
CALLS.DLL,  this  pseudomodule  does 
not  export  ASCIIZ  names.  Every  other 
OS/2  module  (including  KBDCALLS  and 
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VIOCALLS)  exports  them,  but  DOS- 
CALLS  provides  only  “ordinal  numbers.” 

Once  you  know  the  ordinal  number 
for  a  DOSCALL  function,  you  can  pass 
it  to  DosGetProcAddr  in  one  of  two  forms: 
Take  the  example  of  DosGetProcAddr 
itself,  whose  ordinal  number  is  45 

DosGetProcAddr/ module,  "#45", 
&dosgetprocaddr); 

dosgetprocaddrC  module, 
MAKEP(0,45),  &dosgetprocaddr); 

Aside  from  the  annoying  special  case 
of  DOSCALLS,  DosGetProcAddr  is,  in 
effect,  a  “named”  equivalent  to  the  MS- 
DOS  GetVect operation.  But  while  DOS 
GetVect  is  complemented  by  SetVect, 
and  likewise  GetTrapAddress  on  the 
Macintosh  is  complemented  by  SetTrap - 
Address ,  in  OS/2  there  is  no  DosSet- 
ProcAddr.  Instead,  individual  modules 
are  responsible  for  supplying  their  own 
mechanism  for  plug-in  replacements. 
The  KBD-,  MOU-,  and  VIO-based  sub¬ 
systems  in  OS/2  can  be  replaced  us¬ 
ing  KbdRegister,  MouRegister,  and 
VioRegister.  There  is  no  such  thing  as 
DosRegister. 

When  finished  with  a  module  a  pro¬ 
gram  can  call  DosFreeModule.  This  is 
unnecessary  if  the  program  is  about  to 
terminate  anyway.  DosFreeModule  dec¬ 
rements  a  reference  count  that  OS/2 
keeps  for  DLLs:  When  the  count  goes 
down  to  zero,  the  DLL  is  released  from 
memory  (remember  that  multiple  ap¬ 
plications  may  be  using  a  DLL  at  the 
same  time).  After  calling  DosFreeModule , 
a  program  still  has  the  function  point¬ 
ers  returned  from  DosGetProcAddr,  but 
they  are  no  longer  valid. 

While  C  is  generally  used  to  illustrate 
run-time  dynlinks,  similar  programs  can 
be  written  in  any  other  language  for 
which  an  OS/2  version  is  available. 
CALLDLL.MOD  (Listing  Two,  page  102) 
is  a  Modula-2  equivalent  to  Listing  One. 

I  used  JPI  TopSpeed  Modula-2  here. 
Because  of  the  non-standardization  of 
Modula-2  equivalent  code  for  Stony 
Brook  Modula-2  or  Logitech  Modula-2 
would  look  slightly  different.  CALLDLL 
.LSP  (Listing  Three,  page  102)  is  the 
same  program  again,  this  time  written 
in  OS2XLISP.  This  version  is  so  short 
not  only  because  of  the  expressive  power 
of  Lisp,  but  because  OS2XLISP  itself  is 
built  around  run-time  dynamic  linking. 

DosLoadModule  and  DosGetProcAddr 
are  equally  important.  Usually  the  func¬ 
tion  name  is  viewed  as  more  of  a  vari¬ 
able  than  the  module  name,  but  in  fact 
it  often  works  the  other  way  around; 
the  function  name  can  stay  the  same 
while  the  module  name  varies.  For  in¬ 
stance,  you  might  have  the  same  func¬ 
tion  BitBltC )  implemented  in  a  VGA 


DLL,  an  EGA. DLL,  and  so  on.  There  is 
an  analogy  here  to  polymorphism  in 
object-oriented  programming,  where  the 
same  generic  operation  can  be  applied 
to  objects  of  different  classes  in  an  in¬ 
heritance  chain:  The  OS/2  module  is 
like  an  OOPs  class,  and  the  functions 
within  a  module  are  like  the  selectors 
implemented  by  that  class.  Just  as  in 
OOPs,  the  run-time  system  transforms 
a  class/selector  pair  into  a  single  out¬ 
put,  the  method,  so  OS/2  run-time  dyn¬ 
links  transform  a  module/function  name 
pair  into  a  single  output,  the  function 
pointer. 

A  Higher  Level 

It’s  convenient  to  say  that  DosGetProc¬ 
Addr  takes  an  ASCIIZ  name  and  re¬ 
turns  the  corresponding  function  pointer 
but,  as  Listings  One  and  Two  show, 
that’s  not  exactly  how  it  looks.  Instead, 
as  with  all  OS/2  kernel  functions,  Dos¬ 
GetProcAddr  returns  only  an  error  code. 
Because  most  high-level  languages  pro¬ 
vide  only  one  retval,  any  other  infor¬ 
mation,  such  as  the  function  pointer 
we  are  actually  interested  in,  must  be 
passed  back  in  VAR  parameters. 

We  think  of  DosGetProcAddr  in  this 
way: 

FUNCPTR  DosGetProcAddr 
(HANDLE  module,  ASCIIZ  procname); 

But  the  way  OS/2  provides  DosGetProc¬ 
Addr  actually  looks  like  this: 

ERRCODE  DosGetProcAddr 

(ASCIIZ  faiibuf,  WORD  size, 
ASCIIZ  procname,  FUNCPTR 

*p_procname); 

Compared  with  MS-DOS  functions, 
OS/2  functions  look  high-level.  Whereas 
DOS  functions  are  invoked  by  stuffing 
registers  and  doing  an  INT  21,  OS/2 
functions  are  invoked  by  putting  argu¬ 
ments  on  the  stack  and  doing  a  FAR 
CALL.  But  this  should  not  delude  us 
into  thinking  that  the  OS/2  API  actually 
is  high-level,  only  the  parameter  pass¬ 
ing  mechanism  is  high  level. 

There  is  no  rule  saying  we  have  to 
use  the  OS/2  facilities  in  the  “raw”  form 
in  which  Microsoft  and  IBM  provide 
them,  however.  In  fact,  aside  from  demo 
programs  like  those  in  Listings  One 
and  Two,  OS/2  facilities  should  never 
be  used  directly.  For  reasons  of  port¬ 
ability,  readability,  maintainability,  and 
various  other  “bilities,”  which  I’ve  for¬ 
gotten,  code  that  directly  depends  on 
OS/2  should  be  isolated  from  applica¬ 
tion-level  code.  Present  company  ex¬ 
cluded,  distrust  any  programmer  who 
puts#include  “os2.h”  in  the  main  mod¬ 
ule  of  their  program.  OS/2  may  have 
that  HLL  look,  but  putting  DosGetProc- 
Addr( )  in  the  middle  of  main( )  is  the 
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same  as  putting  int86( 0x21 ,  &r,  &r)  in 
the  middle  of  main(  ). 

PROC1.C  (Listing  Four,  page  102) 
provides  a  level  of  abstraction  on  top 
of  the  OS/2  Module  Manager.  This  file 
^includes  “os2.h,”  but  a  program  that 
uses  run-time  dynlinks  doesn’t.  Instead, 
it  ^includes  “procaddr.h”  (see  Listing 
Five,  page  102). 

While  the  functions  in  Listing  Four 
are  only  two  lines  each,  they  add  con¬ 
siderable  expressive  power  over  the 
native  OS/2  versions.  Now,  we  can  say 
things  as  shown  in  Example  1. 

PFN  is  the  typedef  that  OS/2  pro¬ 
vides  for  pascal  function  pointers.  Why 
does  getprocaddr(  )  in  Listing  Four  in¬ 
stead  return  a  ULONG  (4-byte  unsigned 
number)?  The  answer  is:  Partially  as  a 
reminder  that  a  far  function  pointer  is 
just  a  4-byte  number,  but  mainly  be¬ 
cause  the  Microsoft  C  compiler  dislikes 
casting  pascal  function  pointers  to  cdecl 
or  vice  versa,  though  it  accepts  casting 
between  a  function  pointer  and  a 
ULONG  (it  correctly  warns  about  “dif¬ 
ferent  levels  of  indirection”). 

The  C  program  in  Listing  Six,  page 
102  (CALLDLL2.C)  uses  the  higher-level 
routines  in  Listing  Four;  it  dynamically 
links  to  _printf  in  CRTLIB.DLL,  the  "C 
run-time  library  in  a  DLL”  provided 
with  Microsoft  C  5.1.  The  file  size  is  a 
sure  sign  that  something  strange  is  go¬ 
ing  on  here:  We’re  calling  printf!  )  but 
CALLDLL2.EXE  is  only  1817  bytes!  One 
odd  property  of  CRTLIB.DLL  is  that 
you  can  run-time  dynamically  link  to 
it  only  if  you  are  also  load-time  dy¬ 
namically  linked  to  it;  this  is  because 
an  undocumented  function  in  CRT¬ 
LIB.DLL  ( _CRT_INIT)  is  used  to  initial¬ 
ize  the  C  run-time  library. 

Note  that  CALLDLL2.C  does  not  in¬ 
clude  <stdio.h>,  even  though  it  calls 
printf( ).  printf(  )  is  coming  to  us  only 
at  run-time.  There’s  no  point  in  telling 
the  linker  about  it,  much  less  the  com¬ 
piler  and  preprocessor!  This  is  a  diffi¬ 
cult  point  to  sink  in:  the  only  reason 
CALLDLL2.C  is  able  to  use  printf! )  is 
because  it  passed  the  string  CRTLIB  to 
loadmodule! )  and  the  string  _  print 'f 
to  getprocaddr( ). 

Some  of  the  lines  in  CALLDLL2.C  are 
numbered  to  make  discussion  easier. 
Line  1  shows  the  simple  call  (printf)! ). 
Line  2  uses  the  newer  ANSI  C  style  for 
calling  through  a  function  pointer,  in 
which  pfn( )  is  the  same  as  ( *pfn)(  ). 
This  matches  Modula-2,  in  which  the 
syntax  for  indirect  calling  through  a 
procedure  pointer  is  indistinguishable 
from  a  “normal”  call.  In  Line  3,  print/ 
displays  its  own  address,  using  %Fp. 
printf!  )  returns  the  number  of  charac¬ 
ters  printed.  Line  4  makes  sure  that  we 
really  can  get  this  retval. 
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String  Invocation 

“The  general  format  of  a  procedure 
call  is 

expression!  parameters) 

Usually  we  use  the  declared  proce¬ 
dure  name  as  the  expression,  but  there 
is  nothing  to  prevent  us  from  writing 
an  arbitrarily  complicated  expression.  ” 
—  Martin  Richards  and 
Colin  Whitby-Strevens 
BCPL:  The  Language  and 
its  Compiler  ( 1980) 

Line  5  of  Listing  Six  is  a  little  odd,  but 
it  best  represents  what  we’re  actually 
doing: 

((CFN)  getprocaddrOoadmodule 

(“CRTLIB"), "_printf’’))(“Goodbye’’); 

The  pointer  to  printf  is  just  the  retval 
from  gelprocaddr;  we  call  p;7'«//fhrough 
this  function  retval.  The  assembly  equiva¬ 
lent  is  shown  in  Example  2.  What’s 
going  on  here  is  "string  invocation.” 
Essentially,  we’re  not  calling  printf 
through  a  pointer  (which  is  just  a  tem¬ 
porary  unnamed  value  on  the  stack), 
we’re  calling  printf  through  its  ASCIIZ 
name.  The  string  function  names  that 
appear  in  "string  invocation"  are  part 
of  the  larger  class  of  objects,  “execut¬ 
able  strings”  (the  DDE_EXECUTE strings 
used  in  OS/2  and  Windows  Dynamic 
Data  Exchange  are  executable  strings). 
Syntactic  sugar  for  this  might  be:  “CRT- 
LIB. _printf  '  ( '  'Goodbye ' '); 

Because  (  )  is  a  binary  operator  be¬ 
tween  a  function  and  the  set  of  its 
arguments,  this  weird  syntax  could  be 
implemented  in  C++  by  overloading 


Example  1:  Expressive  functions 


the  (  )  function-invocation  operator.  Ac¬ 
tually,  the  Icon  programming  language 
(successor  to  SNOBOL)  offers  just  this 
syntax,  in  which  “write' '(“Goodbye”) 
is  equivalent  to  write( “Goodbye”). 

At  this  point,  we  had  better  ask  again, 
“Of  what  possible  use  is  that?”  Because 
run-time  dynamic  linking  means  that 
an  ASCIIZ  string  can  be  used  in  place 
of  the  name  of  a  procedure,  any  ex¬ 
pression  that  yields  such  a  string  can 
also  be  used.  The  procedure  to  be  in¬ 
voked  is  just  as  much  a  variable  as  the 
arguments  it  takes. 

The  module  name  and  function  name 
are  just  strings,  why  hard-wire  them 
into  the  executable?  Why  not  pass  them 
on  the  command  line?  Let  argvfl]  be 
passed  to  loadmodule( )  and  argv[2] 
be  passed  to  getprocaddr!  ).  Let  argv[3 
.  .argcj  hold  any  arguments  expected 
by  the  function  whose  name  we’ve  put 
in  argv[2].  The  result  is  a  general-pur¬ 
pose  program  in  which  the  function  to 
be  invoked  and  the  arguments  to  be 
passed  to  it  are  completely  up  in  the  air 
until  the  program  runs.  This  is  exactly 
what  we're  going  to  do:  Write  a  mini 
C  interpreter,  in  very  few  lines  of  code, 
using  OS/2  run-time  dynlinks. 

Mini  Tiny  Small  C 

The  mini-interpreter's  syntax  is  shown 
in  Figure  1  where  fargs  .  .  .  ]  are  zero 
or  more  arguments  to  the  function,  and 
each  one  is  either  a  string,  a  character, 
an  unsigned  word,  a  long  or  a  float. 
CALLDLL.C  (Listing  Seven,  page  102) 
uses  some  dumb,  but  generally  effec¬ 
tive,  rules  to  figure  out  the  type  of  an 
argument.  [%mask]  is  an  optional 
printf(  )  mask  that  both  designates  the 
type  of  the  function’s  return  value,  and 


POSH  "Goodbye" 

PUSH  "_printf " 

PUSH  "CRTLIB" 

CALL  loadmodule 
;  loadmodule  consumed  ’’CRTLIB" 

;  and  produced  handle  to  crtlib 
CALL  getprocaddr 

;  getprocaddr  consumed  crtlib-handle  and  "_printf" 
;  and  produced  pointer  to  printf  on  top  of  stack 
;  "Goodbye"  is  still  on  stack 
CALL  [top  of  stack] 

POP  retval  from  _printf 


Example  2:  Assembly  language  equivalent 
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WORD  alias  =  loadmodule ( "ALIAS") ; 

PFN  listsyn  =  (PFN)  getprocaddr (alias,  "LIST_SYN") ; 
if  (listsyn) 

(‘listsyn) () ; 
f reemodule (alias) ; 

or: 

PFN  listsyn; 

if  (listsyn  =  (PFN)  procaddr ("ALIAS",  "LIST_SYN")) 
(‘listsyn)  () ; 
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(continued  from  page  52) 
displays  that  return  value.  For  instance, 
%s  tells  CALLDLL  that  a  function  re¬ 
turns  a  4-byte  value,  which  should  be 
printed  out  as  a  string.  The  default  retual 
mask  is  %u,  which  gets  a  two  -  byte 
retual  and  displays  it  as  an  unsigned 
word.  Example  3  lists  some  legal  calls 
to  the  interpreter. 

This  is  truly  a  general-purpose  pro¬ 
gram:  It  can  write  to  the  screen,  beep 
the  speaker,  get  the  square  root  of  -1, 
get  the  HWND  of  the  active  window 
in  PM,  or  perform  pretty  much  any 
action  put  in  a  DLL. 

For  the  most  part,  CALLDLL  is  an  ig¬ 
norant  “pass-through.”  The  intelligence 
for  associating  the  strings  VIOCALLS 
and  VIOWRTTTY  with  the  function 
VioWrtTty( ),  for  example,  is  located 
entirely  within  OS/2's  module  manager. 
CALLDLL  blindly  passes  the  first  two 
arguments  on  the  command-line  to 
DosLoadModule  and  DosGetProcAddr. 

Ignorance  is  bliss:  The  more  ignorant 
the  pass-through  is,  the  more  powerful. 
Because  CALLDLL  does  no  interpreta¬ 
tion  on  module  and  function  names,  it 
can  be  used  to  call  functions  that  didn't 
even  exist  when  CALLDLL  was  com¬ 
piled.  This  is  the  same  flexibility  as 
provided  by  “  late  binding”  in  OOPs: 
Instead  of  using  a  switchi )  statement 
associating  specific  actions  with  vari¬ 
ous  run-time  symbols,  a  program  sim¬ 
ply  passes  the  symbol  through  and  the 
system  determines  what  action  to  call. 

Now,  if  CALLDLL  represents  the  ideal 
dumb  pass-through,  what  are  those 
su’itch(  )  statements  in  Listing  Seven? 

While  the  module  and  function 
names  are  passed  through  to  OS/2,  the 
functions  args  and  retual  are  a  different 
matter.  Once  OS/2  has  given  us  back 
a  function  pointer,  we’re  on  our  own. 
Almost  all  the  code  in  CALLDLL. C  is 
devoted  to  pushing  arguments  on  the 
stack  before  the  function  is  called,  and 
getting  back  a  retual  afterwards. 

Here  we  run  into  a  problem  with  all 
high-level  languages:  There  is  no  com¬ 
pletely  general  procedure  pointer.  C 


(actually,  pre-ANSI  C  without  proto¬ 
types)  can  easily  handle  functions  with 
different  numbers  and  types  of  argu¬ 
ments  gated  through  the  same  function 
pointer,  but  even  C  won’t  multiplex 
functions  with  different  types  of  return 
values  through  the  same  function 
pointer.  Pushing  a  function’s  arguments, 
calling  the  function  and  getting  its  re¬ 
turn  value  are  too  tightly  coupled. 

In  the  underlying  assembly  language 
there  is  a  completely  general  function 
pointer,  because  the  various  compo¬ 
nents  of  function  calling  are  clearly 
separated: 

PUSH  param(s) 

PUSH  func 

CALL  [top  of  stack] 

RETRIEVE  retval(s) 

Forth  is  probably  the  only  HLL  that 
naturally  splits  function  calls  up  in  this 
way.  In  order  to  write  the  mini-inter¬ 
preter,  I  needed  to  simulate  this  in  C. 

Jiggling  the  Stack 

The  first  step  is  to  write  a  function  to 
push  its  argument  on  the  stack  and  to 
leave  it  there.  In  his  book,  The  Pro¬ 
grammer's  Essential  OS/2  Handbook , 
David  Cortesi  shows  how  to  write  such 
a  function  for  Pascal:  “The  gimmick  is 
simple:  return  without  clearing  the 
stack!”  To  do  this  in  C,  the  function 
uses  the  Pascal  calling  convention.  Here 
is  the  entire  function: 

VOID  NEAR  PASCAL  push(  )  I  I 

Given  C’s  relaxed  type  checking,  this 
can  be  called  with  any  type  of  argu¬ 
ment.  The  compiler  dutifully  pushes 
the  argument  onto  the  stack  and  there 
it  stays. 

To  handle  multiple  arguments,  CALL¬ 
DLL. C  uses  a  “push  loop/'  push( )  is 
called  for  each  command-line  argument, 
working  upwards  for  the  Pascal  calling 
convention  and  downwards  for  cdecl. 
Note  that  push ( )  must  be  called  from 
within  the  same  function  that’s  going 


calldll  <module  name>  function  name  or  ordinal  number>  [args  .  .  .]  [%mask] 


Figure  1:  Syntax  for  the  mini-interpreter 


calldll  viocalls  VIOWRTTTY  "hello  world"  11  0 
calldll  doscalls  DosBeep  2000  300 

calldll  doscalls  50  2000  300  ;  DOSBEEP 

calldll  doscalls  DosMkDir  \foobar  0L 

calldll  doscalls  DosRmDir  \foobar  0L 

calldll  pmwin  WINQUERYACTIVEWINDOW  1L  0  %lu 

calldll  crtlib  _printf  "goodbye  world:  %lu"  666L 

calldll  crtlib  SQRT  -1.0  %f 

calldll  crtlib  _toupper  'b'  %c 

calldll  jpilib  FIO$Exists  12  CALLDLL . EXE 


Example  3:  Legal  calls  to  the  interpreter 
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to  make  the  indirect  call  to  consume 
the  arguments  on  the  stack.  For  this 
reason,  CALLDLL.C  calls  push(  )  from 
within  a  PUSH_ARG(  )  macro  that  gets 
expanded  inline. 

Now  the  arguments  are  on  the  stack. 
To  get  the  correct  return  value,  our 
generic  function  pointer  /must  be  cast 
to  the  appropriate  type  of  function 
pointer.  It  is  called  with  no  arguments 
because  its  arguments  are  already  on 
the  stack  as  shown  in  Example  4. 

CALLDLL  does  nothing  with  f<  )'s  re¬ 
turn  value  except  print  it  (using  what¬ 
ever  print/  mask  the  user  supplied). 
The  invocation  of  f(  )  takes  place  as 
an  argument  to  print f. 

Finally,  it  is  the  responsibility  of  the 
caller  of  a  cdecl  function  to  pop  the 
arguments  off  the  stack,  so  we  need  a 
pop(  )  function,  I  couldn’t  write  this  in 
C,  so  it  is  supplied  by  POP. ASM  (Listing 
Eight,  page  104). 

Naming  DOSCALLS 

I  said  earlier  that  the  DOSCALLS  pseu¬ 
domodule  (the  API  exported  by  the 
OS/2  kernel)  is  an  anomaly  in  that  its 
routines  (such  as  DosGetProcAdclr  Dos- 
AllocSeg,  or  DosOperi)  do  not  have 
ASCIIZ  names  present  at  run-time. 

You  can  easily  correct  this  deficiency. 
Instead  of:  calldll  DOSCALLS  50  2000 
300,  you  can  say:  calldll  DOSCALLS 
DosBeep  2000  300. 

PROC2.C  (Listing  Nine,  page  104) 
shows  a  new  version  of  the  higher- 
level  run-time  dynamic-linking  routines. 
Solving  the  DOSCALLS  problem  is  an¬ 
other  reason  to  have  our  own  level  on 
top  of  OS/2  —  we  can  use  it  to  iron 
out  such  inconsistencies.  PROC2.H  is 
the  external  interface  to  PROC2.C,  and 
is  shown  in  Listing  Ten  (page  106). 

In  the  new  version  erf  getprocaddri  ), 
if  an  ASCIIZ  name  is  passed  in  for 
a  function  in  DOSCALLS,  the  function 
getdoscall( )  does  a  binary  search  of 
a  table  that  associates  ASCIIZ  names 
with  function  pointers. 

Where  does  this  table  come  from? 
(Warning!  Extremely  boring  material 
ahead!)  Listing  Eleven  (page  106)  is  an 
AWK  script  that  massages  the  file 
BSEDOS.H  into  a  table  of  DOSCALLS. 
The  AWK  output,  DOSCALLS. C,  is  not 
reproduced  here,  because  it  is  boring. 
If  you  don't  have  AWK  but  want  to 
produce  your  own  DOSCALLS. C,  you 
can  use  any  decent  text  editor  on  a 
copy  of  BSEDOS.H.  The  thing  is  to  turn 
lines  like: 

USHORT  APIENTRY  DosGetProc- 
AddrlHMODULE,  PSZ,  PPFN); 

into  lines  like: 

‘ 1  DosGetProcAddr’  ’ ,  DosGetProcAddr. 


Unfortunately  this  table  introduces 
a  touch  of  "early  binding"  into  an  other- 
wisewait-until-the-last-possible-moment- 
to-do-it  program. 

A  DLL  for  Handling  DLLs 

There  is  one  last  step  in  the  develop¬ 
ment  of  the  routines  in  PROC2.C:  Put 
them  in  a  DLL.  Listing  Twelve  (page 
106)  shows  PROCADDR.DEF,  which 
defines  the  DLL  for  the  OS/2  linker.  All 
the  data  in  PROCADDR.DLL  is  shared  — 
multiple  clients  ofPROCADDR.DLL  use 
the  same  version  of  the  DOSCALLS 
table. 

Once  PROC2.C  is  in  a  DLL,  we  can 
even  call  these  routines  from  the 
CALLDLL  command  line.  For  those  who 
like  this  sort  of  thing,  this  is  the  sort  of 
thing  that  they  like: 

C  >  calldll  PROCADDR  PROCADDR 
PROCADDR PROCADDR  % 
Fp044F:00A0 

This  calls  the  function  procaddrf  )  in 
PROCADDR.DLL,  passing  it  the  parame¬ 
ters  PROCADDR  and  PROCADDR,  so 
that  the  address  of  procaddrf  )  itself  is 
printed  out. 

Because  it  is  extremely  stupid, 
CALLDLL  is  general-purpose  and  pow¬ 
erful.  On  the  other  hand,  because 
CALLDLL  knows  nothing  about  the  rou¬ 
tines  that  it  calls,  it  can  t  check  the 
arguments  passed  on  the  command¬ 
line.  For  example,  CALLDLL  DOSCALLS 
DOSGETINFOSEG  1L  2L  is  wrong.  But 
because  OS/2  runs  under  protected 
mode  this  isn't  too  bad.  Instead  of  crash¬ 
ing  your  machine,  OS/2  just  terminates 
CALLDLL  and  displays  the  ever-popu- 
lar  GP  Fault  dump. 

If  this  were  a  genuine  interpreter 
that  tried  to  execute  more  than  one  line 
of  user  code,  this  would  be  a  big  prob¬ 
lem.  Even  though  the  error  lies  in  the 
user’s  code,  OS/2  terminates  the  inter¬ 
preter  because,  as  far  as  it's  concerned, 
that's  what  caused  the  general-protec¬ 
tion  violation.  It  would  seem  the  only 
choice  for  OS/2  interpreters  is  either 
to  verify  all  user  input,  or  to  let  OS/2 
close  you  down  because  of  bad  user 
input.  In  fact,  there  is  a  way  to  catch 
GP  faults  in  OS/2,  using  DosPTracef  ), 
but  this  is  a  subject  for  another  article. 

Other  improvements  could  be  made 
to  CALLDLL:  Interpreting  multiple  lines 
of  code  from  a  file,  putting  function 
results  into  variables,  taking  the  ad¬ 


dress  of  variables  (for  example,  how 
would  one  properly  call  DosGetln- 
foSegt).  These  are  left  as  an  exercise 
for  the  reader. 

Extensible  OS/2 

Richard  Stallman’s  original  article  on 
Emacs  (“EMACS:  The  Extensible,  Cus¬ 
tomizable,  Self-Documenting  Display 
Editor,”  Proceedings  of  the  ACM 
SIGPLAN  SIGOA  Symposium  on  Text 
Manipulation,  June,  1981)  is  sort  of  the 
manifesto  of  extensible  systems.  One 
of  the  requirements  he  sets  forth  is  that 
“an  on-line  extensible  system  must  be 
able  to  accept,  and  then  execute,  new 
code  while  it  is  running."  Stallman  goes 
on  to  argue  that  what  one  needs  is  a 
good  language  (Lisp,  for  example)  rather 
than  a  good  operating  system  with  dy¬ 
namic  linking  (such  as  Multics).  In  fact, 
there  is  no  conflict  here,  because  OS/2 
is  as  extensible  an  operating  system  as 
Lisp  is  a  language. 

Compiling  and  linking  are  processes 
of  throwing  away  information.  But  dy¬ 
namic  linking  relies  on  the  presence  at 
run  time  of  names  usually  discarded 
in  compiling  or  linking.  Keeping  the 
ASCIIZ  names  of  functions  around  in 
DLLs  means  that  executables  under  OS/ 
2  have  moved  a  little  closer  to  the  type 
of  “object  code"  found  in  interpreted 
environments  and  debuggers. 

Should  OS/2  succeed,  run-time  dyn- 
links  will  play  an  important  role  in  the 
construction  of  extensible  languages 
and  of  products  with  embedded  lan¬ 
guages  and  add-in  facilities.  For  a  sys¬ 
tem  built  around  add-in  DLLs,  run-time 
dynamic  linking  is  the  ultimate  Add-In 
Manager. 

Availability 

All  source  code  for  articles  in  this  issue 
is  available  on  a  single  disk.  To  order, 
send  $14.95  (Calif,  residents  add  sales 
tax)  to  Dr.  Dobb’s Journal,  501  Galves¬ 
ton  Dr..  Redwood  City,  CA  94063,  or 
call  800-356-2002  (from  inside  Calif.) 
or  800-533-4372  (from  outside  Calif.). 
Please  specify  the  issue  number  and 
format  (MS-DOS,  Macintosh,  Kaypro). 

DDJ 

(Listings  begin  on  page  102.) 

Vote  for  your  favorite  feature/article. 

Circle  Reader  Service  No.  4. 


switch  (retval_typ) 

{ 

case  typ_string:  printf(mask,  ( (STRFN)  f)());  break; 

case  typ_word:  printf(mask,  f());  break; 

} 


Example  4:  Arguments  already  on  the  stack 
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Container  Object 

Types  in  Turbo  Pascal 


Extend  the  power  of  Turbo  Pascal  by 
“containerizing”  data  structures 


Anders  Hejlsberg 


In  modern  programming,  most  ap¬ 
plications  depend  heavily  on  data 
structuring  methods  that  lie  far  be¬ 
yond  the  built-in  functionality  of  a 
programming  language.  In  fact, 
large  portions  of  typical  applications 
are  devoted  to  the  maintenance  of  data 
structures,  such  as  linked  lists,  dynamic 
arrays,  binary  trees,  and  so  on.  But  even 
so,  few,  if  any,  programming  languages 
provide  built-in  support  for  data  struc¬ 
tures  other  than  simple  records  and  ar¬ 
rays.  As  a  result,  scores  of  programmers 
are  forced  to  "invent  the  wheel”  over 
and  over  again  as  they  write  and  debug 
the  necessary  data  structure  manage¬ 
ment  code  for  each  new  application. 
Among  the  key  benefits  of  object  ori¬ 
ented  programming  (OOP)  is  the  abil¬ 
ity  to  create  Container  Object  Types 
which,  when  packaged  in  library  mod¬ 
ules,  essentially  extend  the  underlying 
programming  language  with  new  ways 
of  structuring  data.  Using  Container  Ob¬ 
ject  Types,  a  programmer  needn’t  worry 
about  insertion  and  deletion  on  linked 
lists,  balancing  of  binary  trees,  sorting 
of  arrays,  and  so  on;  all  such  algo¬ 
rithms  can  be  implemented  once  and 
for  all  in  a  library  of  Container  Object 
Types.  In  this  article.  I'll  demonstrate 
how  to  implement  and  use  a  number 
of  Container  Object  Types  in  Turbo 


Anders  is  the  chief  architect  of  Turbo 
Pascal,  nowin  its  fifth  generation.  An¬ 
ders  is  currently  working  on  Turbo  Pas¬ 
cal  and  other  core  technology  products 
at  Borland  Int.,  Scotts  Valley,  Calif. 


Pascal  5.5.  In  particular,  I’ll  implement 
Container  Object  Types  for  linked  lists 
and  binary  trees,  and  show  how  these 
structures  can  be  used  in  a  Pascal  cross- 
reference  generator  program. 

Container  Object  Types 

You  may  think  you  know  nothing  about 
Container  Object  Types,  when  in  fact 
you  probably  use  them  in  every  pro¬ 
gram  you  write.  The  Pascal  array  type, 
for  instance,  is  an  example  of  a  con¬ 
tainer  type  (although  not  an  object- 
oriented  one).  An  array  contains  a  num¬ 
ber  of  elements  of  a  specific  type,  and 
allows  access  to  those  elements  through 
indices.  And  a  Container  Object  Type 
is  just  that:  A  type  that  contains  a  num¬ 
ber  of  elements  and  allows  access  to 
those  elements  in  some  way. 

Consider,  for  example,  a  linked  list. 
It  consists  of  a  number  of  nodes,  each 
of  which  contains  a  link  that  points  to 
the  next  node  in  the  list.  To  access  the 
list,  one  follows  links  down  the  chain 
of  nodes.  Both  the  linked  list,  and  the 
array  contain  a  number  of  elements 
and  allow  access  to  those  elements  in 
some  way. 

Many  other  data  structures  are  natu¬ 
ral  candidates  for  implementation  as 
container  types.  Stacks  (last-in,  first- 
out),  queues  (first-in,  first-out),  trees, 
dynamic  arrays,  and  hash  tables,  like 
linked  lists  and  arrays,  all  share  the 
ability  to  store  and  access  data  ele¬ 
ments  and  could  be  profitably  “con¬ 
tainerized.” 

While  some  applications  may  be  able 
to  get  along  with  fixed-sized  arrays, 


most  programs  require  structures  that 
dynamically  resize  themselves,  that  have 
the  ability  to  sort  themselves,  and  so 
on.  When  the  number  of  elements  in  a 
structure  isn’t  known  beforehand,  and 
when  access  to  the  elements  is  strictly 
sequential,  a  linked  list  is  probably  more 
appropriate  than  a  fixed-size  array.  Like¬ 
wise,  when  elements  have  to  be  sorted, 
a  binary  tree  may  be  a  better  choice.  It 
seems  strange,  then,  that  most  program¬ 
ming  languages  only  provide  a  couple 
of  container  types  (such  as  array  and 
record),  when  indeed  there  are  many 
others  to  consider.  Wouldn’t  it  be  nice, 
for  example,  to  be  able  to  declare  a 
“list  of  Windows,”  a  “queue  of  Trans¬ 
actions,”  or  a  "tree  of  Identifiers.”  With 
Container  Object  Types,  you  can  do 
just  that,  although  the  syntax  may  be  a 
little  different. 

Container  Object  Types  allow  lists, 
stacks,  queues,  trees,  and  other  data 
structures  to  be  made  truly  generic, 
almost  as  if  they  were  language  exten¬ 
sions.  Just  as  procedures  and  functions 
in  units  (such  as  Dos,  Overlay,  and 
Graph )  are  extensions  to  the  set  of 
built-in  routines  (such  as  WriteLn, 
ReadLn ,  Length ,  and  Sqrt)  of  Turbo 
Pascal,  units  with  Container  Object 
Types  can  act  as  extensions  to  the  built- 
in  array  and  record  types. 

The  benefits  are  numerous.  First  of 
all,  Container  Object  Types  save  time, 
because  you  don’t  have  to  write  and 
debug  code  to  manage  data  structures 
over  and  over  again.  Such  code  can 
be  written  and  debugged  once,  and 
then  reused  in  any  number  of  applica- 
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(continued  from  page  56) 
tions.  Second,  Container  Object  Types 
can  save  space  and  can  reduce  errors. 
Imagine,  for  example,  an  application 
that  uses  linked  lists  for  a  number  of 
different  purposes.  There  might  be  a 
linked  list  of  windows  (the  desktop), 
a  linked  list  of  menus  (the  menu  bar) 
with  linked  lists  of  menu  items,  and  so 
on.  Instead  of  having  separate  linked- 
list  managers  for  windows,  menus,  and 
menu  items,  there  can  be  one  generic 
Container  Object  Type  that  manages 
them  all,  with  a  resulting  reduction  in 
code  space  and  potential  bugs.  Finally, 
if  all  linked  lists  in  an  application  are 
derived  from  one  Container  Object 
Type,  then  any  optimizations  made  to 
that  container  will  improve  performance 
throughout  the  entire  application. 

Implementing  and  Using  Container 
Object  Types 

When  it  comes  to  implementation,  Con¬ 
tainer  Object  Types  are  no  different 
than  ordinary  object  types.  A  container 
type  has  data  fields  and  methods,  and 
it  can  inherit  from  other  object  types. 
The  methods  of  a  Container  Object 
Type  provide  access  to  the  data  stored 
in  the  container.  Where  brackets  ([  ]) 
are  used  to  access  an  array,  method 
calls  are  used  to  access  a  container.  A 
linked  list  container,  for  example,  will 
have  methods  to  insert,  append,  and 
remove  elements,  and  methods  to  get 
at  the  first,  last,  next,  and  previous  ele¬ 
ments  in  the  list. 

Implementing  a  Container  Object  Type 
is  a  true  exercise  in  data  abstraction. 
When  you  write  code  for  the  methods 
of  a  Container  Object  Type,  you  deal 
only  with  the  structure  of  the  data  in 
the  container,  not  with  the  data  itself. 
Just  as  you  can  index  an  array  without 
knowing  exactly  what  the  array  con¬ 
tains,  you  can  insert,  append,  and  re¬ 
move  elements  on  a  linked  list  without 
knowing  exactly  what  the  elements  are. 
But  you  do  need  to  know  something 
about  the  elements.  In  the  case  of  an 
array,  you  need  to  know  the  size  of 
each  element,  and  in  the  case  of  a 
linked  list,  you  need  to  know  where 
to  find  the  link  to  the  next  element.  The 
key  is  to  know  just  enough  about  the 
elements  to  access  them,  but  not  more. 

Such  partial  knowledge  of  container 
elements  is  achieved  through  abstract 
element  types.  Each  element  on  a  linked 
list  needs  a  pointer  to  the  next  element 
in  the  list: 

type 

ListNodePtr  =  AListNode; 

ListNode  =  object 
Next:  ListNodePtr; 

end; 


CONTAINER  OBJECT  TYPES 


If  each  element  on  the  linked  list  is  an 
object  type  derived  from  ListNode ,  then 
each  element  is  guaranteed  to  have  a 
Next  link.  For  example,  a  linked  list 
element  that  contains  an  integer  value 
could  be  defined  as: 

type 

IntNodePtr  =  AintNode; 

IntNode  =  object(ListNode) 
Value:  Longint; 

end; 


The  ListNode  type  is  known  as  an  ab¬ 
stract  type.  It  exists  only  so  that  other 
types  can  be  derived  from  it,  but  is 


Container  Object  Types 
allow  lists,  stacks, 
queues,  trees,  and  other 
data  structures  to  be 
made  truly  generic, 
almost  as  if  they  were 
language  extensions 


otherwise  useless,  because  it  contains 
no  data.  IntNode ,  on  the  other  hand, 
contains  useful  data,  and  because  it  is 
derived  from  ListNode ,  it  inherits  the 
Next  field,  and  can  act  as  a  ListNode  in 
a  linked  list.  Of  course,  you  can  derive 
other  types  from  ListNode ,  such  as 
StringNode,  WindowNode ,  and  Menu- 
Node ,  all  of  which  can  be  put  on  a 
linked  list. 

Given  the  ListNode  type,  now  imple¬ 
ment  a  Container  Object  Type  that  “con¬ 
tains”  it.  In  this  case,  I'll  show  a  simple 
last-in,  first-out  stack  of  ListNodes ,  which 
has  methods  to  Push  and  Pop  elements: 

type 

StackList  =  object 
First:  ListNodePtr; 
procedure  Push(N:  ListNodePtr); 
function  Pop:  ListNodePtr; 

end; 

To  “push”  an  element  onto  the  stack, 
the  new  element  is  inserted  at  the  be¬ 
ginning  of  the  list: 


procedure  StackList. Push(N ListNodePtr) ; 
begin 

NA.Next  :=  First; 

First  :=  N; 

end; 

To  “pop”  an  element,  return  the  first 
element  on  the  list  and  remove  that 
element  from  list: 

function  StackList. Pop:  ListNodePtr; 
begin 

Pop  :=  First; 

if  First  <>  nil  then  First  :=  FirstA.Next; 
end; 

Here’s  a  simple  program  fragment  that 
uses  the  StackList  container  type: 

var 

S:  StackList; 

P:  IntNodePtr; 

begin 

S.Push(P); 

P  :=  IntNodePtr(S.Pop); 

end; 

Notice  in  particular  that  a  typecast  is 
required  to  assign  the  result  of  Pop  to 
P,  but  that  it  is  not  required  to  pass  P 
to  Push.  From  the  compiler’s  point  of 
view,  Push  and  Pop  operate  only  on 
elements  of  type  ListNode — in  fact, 
Push  and  Pop  know  nothing  about  the 
existence  of  an  IntNode  type.  When 
passing  P  to  Push ,  the  compiler  can 
guarantee  that  P  is  a  ListNode ,  because 
IntNode  is  derived  from  ListNode.  But 
going  the  other  way  and  assigning  the 
result  of  Pop  to  P,  the  compiler  can 
make  no  such  assumption.  The  pointer 
to  a  ListNode  returned  by  Pop  is  not 
known  at  compile  time  to  be  also  a 
pointer  to  an  IntNode.  Because  I  have 
only  Pushed  pointers  to  IntNodes,  how¬ 
ever,  I  can  safely  convert  the  return 
value  by  using  a  typecast. 

Such  typecasts  are  quite  common  in 
applications  that  use  Container  Object 
Types.  The  compiler  doesn’t  know  what 
is  in  the  container,  but  the  application 
does,  and  it  can  safely  promote  the 
elements. 

The  Contain. PAS  Unit 

To  demonstrate  the  implementation  of 
Container  Object  Types  in  Turbo  Pas¬ 
cal  5.5,  I  have  provided  Contain. PAS, 
which  is  shown  in  Listing  One  (see 
page  108).  The  Contain  unit  imple¬ 
ments  a  linked  list  container  and  a  bi¬ 
nary  tree  container. 

The  Base  type  is  an  abstract  object 
type  that  serves  as  the  ultimate  ances¬ 
tor  of  all  these  object  types.  The  only 
thing  it  declares  is  a  destructor  called 
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“Done3,”  and  in  itself,  the  Base  type  is 
quite  useless,  though  objects  derived 
from  Base  are  guaranteed  to  always 
have  destructors. 

The  List  type  implements  a  linked 
list  container,  which  contains  elements 
that  are  derived  from  the  ListNode  type. 
The  Lists  Last  field  points  to  the  last 
ListNode  in  the  list,  and  the  Next  field 
of  the  last  ListNode  points  to  the  first 
node,  which  then  points  to  the  next 
node,  and  so  on.  Storing  the  list  in  a 
circular  fashion  like  this  allows  the  effi¬ 
cient  implementation  of  both  an  Insert 
and  an  Append  method;  if  a  pointer  to 
the  first  element  of  the  list  had  been 
stored  instead,  the  Append  method 
would  become  very  inefficient,  because 
it  would  have  to  traverse  the  entire  list 
before  appending  the  new  element. 
Also  because  of  the  circular  structure, 
each  ListNode  can  itself  provide  a  Prev 
method,  which  returns  the  previous 
node  by  traversing  the  entire  circle. 

The  Init  constructor  initializes  the 
list  by  setting  the  Last  field  to  nil,  and 
the  Done  destructor  disposes  the  list 
by  disposing  each  node.  The  Insert , 
Append ,  and  Remove  methods  are  used 
to  insert,  append,  and  remove  nodes. 
Notice  how  Remove  doesn’t  dispose 
the  node,  but  rather  just  removes  it 
from  the  list.  First,  Last ,  Next,  and  Prev 
are  used  to  traverse  the  list;  they  all 
return  nil  to  indicate  the  end  of  the 
iteration.  First  and  Next  are  used  to 
step  forward  through  the  list,  and  Last 
and  Prev  are  used  to  step  backwards. 
The  latter  is  a  rather  slow  process, 
though,  because  finding  the  previous 

Regardless  of  the 
complexity  of  the  objects 
managed ,  the  basic 
object  type  never  needs 
to  be  modified  at  the 
source  level 

node  requires  traversing  the  entire  list. 

The  ForEach  method  applies  an  ac¬ 
tion  to  each  node  in  the  list.  The  action 
is  specified  in  the  form  of  a  procedure 
parameter,  which  must  be  compatible 
with  the  ListAction  procedure  type.  Start¬ 
ing  with  the  first  element  in  the  list, 
the  Action  procedure  is  called  for  each 
element.  The  ForEach  method  is  an 
alternative  to  the  First/ Next  methods. 


Writing: 

L.ForEach(SomeAction); 

corresponds  to  writing: 

P  :=  L.First; 
while  P  <  >  nil  do 
begin 

SomeAction(P); 

P  :=  L.Next(P); 
end; 

The  action  may  be  to  dispose  of  the 
element  (which  is  why  the  actual  source 
code  in  ForEach  calls  the  Next  method 
before  calling  the  Action  procedure). 
An  example  of  the  use  of  ForEach  is 
the  Delete  method,  which  uses  ForEach 
to  dispose  of  the  entire  list  of  elements. 

The  Tree  type  implements  a  sorted 
binary  tree,  which  contains  elements 
that  are  derived  from  the  TreeNode  type. 
Each  node  in  the  tree  has  a  key  value 
that  is  used  to  automatically  sort  nodes 
as  they  are  inserted  into  the  tree.  The 
Tree’s  Root  field  points  to  the  root  of 
the  tree,  and  the  Left  and  Right  fields 
of  each  TreeNode  point  to  nodes  whose 
key  values  are  less  than  and  greater 
than  the  key  value  of  the  node  itself. 
The  Tree  does  not  allow  duplicate  key 
values. 

Of  particular  interest  is  the  Tree's 
Compare  and  GetKey  methods.  These 
methods  are  virtual,  and  are  meant  to 
be  overridden  by  users  of  the  Tree  type. 
The  GetKey  method  is  passed  a  pointer 
to  a  TreeNodeand  must  return  a  pointer 
to  the  key  value  field  in  the  node.  The 
Compare  method  is  passed  two  such 
key  value  pointers,  and  must  return  -1, 
0,  or  1,  indicating  Keyl  <  Key2,  Keyl 
=  Key2,  and  Keyl  >  Key2,  respectively. 
The  default  GetKey  method  simply  re¬ 
turns  a  pointer  to  the  node  itself,  which 
in  some  cases  is  sufficient.  The  default 
Compare  method,  however,  always  re¬ 
turns  0  (indicating  equivalence),  which 
of  course  is  useless  because  every  node 
will  appear  to  be  identical  to  every  other 
node.  The  Compare  method  therefore 
must  be  overridden  with  an  implemen¬ 
tation  that  actually  compares  the  keys. 

The  Insert  method  inserts  a  new  node 
into  the  tree  unless  a  node  with  the 
same  key  value  already  exists.  The  Find 
method  returns  a  pointer  to  a  node 
with  a  given  key  value,  or  nil  if  no  such 
node  exists.  Both  Insert  and  Find  are 


implemented  through  the  more  gen¬ 
eral  Search  method.  Search  scans  the 
tree  for  a  node  with  a  particular  key 
value,  and  returns  a  pointer  to  the  node. 
If  the  node  doesn’t  exist,  a  user-speci¬ 
fied  function  is  called.  The  user  func¬ 
tion  may  create  a  new  node  and  return 
a  pointer  to  it,  in  which  case  that  new 
node  is  entered  into  the  tree.  Alterna¬ 
tively,  the  user  function  may  return  nil, 
in  which  case  no  new  node  is  created. 
In  either  case,  the  result  of  the  user 
function  also  becomes  the  result  of  the 
Search  method.  The  user  function  is 
specified  as  a  function  parameter  to 
Search ,  and  the  type  of  the  parameter 
must  be  compatible  with  the  TreeCreate 
function  type. 

Like  the  List  container  type,  the  Tree 
container  type  has  a  ForEach  method 
that  applies  an  action  to  all  nodes  in 
the  tree,  in  the  order  in  which  the  nodes 
are  sorted.  The  action  is  specified  in 
the  form  of  a  procedure  parameter, 
which  must  be  compatible  with  the 
TreeAction  procedure  type.  The  action 
may  be  to  dispose  of  the  node  (which  is 
why  the  Traverse  procedure  in  ForEach 
copies  the  Right  pointer  into  a  tempo¬ 
rary  before  calling  the  Action  proce¬ 
dure).  An  example  of  the  use  of  ForEach 
is  the  Delete  method,  which  uses 
ForEach  to  dispose  of  the  entire  tree. 

As  an  example  of  the  use  of  the  Tree 
type,  consider  implementing  a  binary 
tree  with  nodes  that  contain  a  string 
and  are  ordered  according  to  the  value 
of  the  string: 

StrPtr  =  AString; 

StrNodePtr  =  AStrNode; 

StrNode  =  object(TreeNode) 

Value:  StrPtr; 

end; 

To  create  a  tree  of  such  StrNode  ele¬ 
ments,  a  StrTree  type  is  derived  from 
the  generic  Tree  type,  and  the  Compare 
and  GetKey  methods  are  overridden: 

StrTree  =  object(Tree) 
function  Compare(Keyl,  Key2: 

Pointer):  Integer;  virtual; 
function  GetKey(N:  TreeNodePtr): 

Pointer;  virtual; 

end; 

The  GetKey  method  returns  a  pointer 
to  the  string  value  in  the  node.  Notice 
how  a  typecast  is  required  to  promote 
the  node  from  a  TreeNode  to  a  StrNode. 

function  StrTree.GetKey(N: 

TreeNodePtr):  Pointer; 

begin 

GetKey  :=  StrNodePtr(N)A. Value; 
end; 
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(continued  from  page  62) 

The  Compare  method  likewise  type¬ 
casts  the  key  pointers  into  string  point¬ 
ers,  and  compares  the  string  values: 

function  StrTree.Compare(Keyl,Key2: 

Pointer):  Integer; 

begin 

if  StrPtr(Keyl)A  <  StrPtr(Key2)A  then 
Compare  :=  —  1  else 
if  StrPtr(Keyl)A  >  StrPtr  (Key2)A 
then  Compare  :=  1  else 
Compare  :=  0; 

end; 

The  Crossref.PAS  Program 

Now  that  a  Container  Object  Type  mod¬ 
ule  has  been  implemented,  I'll  show  a 
program  that  actually  uses  those  con¬ 
tainer  types.  The  Crossref.PAS  program 
(see  Listing  Two,  page  109)  uses  linked 
lists  and  binary  trees  to  generate  a  cross- 
reference  listing  of  a  Pascal  source  file. 
A  listing  of  the  source  file  with  line 
numbers  and  a  list  of  all  identifiers  in 
the  source  file  is  produced,  and  each 
identifier  is  followed  by  a  list  of  num¬ 
bers  of  the  lines  that  reference  the  iden¬ 
tifier. 

To  run  the  CrossRef  program,  use  a 
command  line  such  as  this: 

CROSSREF  MYPROG.PAS 

This  generates  a  cross-reference  listing 
of  MYPROG.PAS  on  the  screen.  Be¬ 
cause  CrossRef  writes  to  the  standard 
Output  file,  the  cross-reference  can  be 
redirected  to  a  file.  For  example: 

CROSSREF  MYPROG.PAS  >MY- 

PROG  .CRF 

Within  the  Cm«)?e/prograrn,  the  Line- 
Ref  object  type  is  used  to  track  line 
numbers  of  references  to  a  particular 
identifier.  It  is  derived  from  the  ListNode 
type,  so  that  reference  line  numbers 
can  be  kept  on  a  linked  list. 

An  IdentRefo bject  represents  an  iden¬ 
tifier  and  the  line  numbers  of  all  the 
lines  that  reference  it.  The  identifier  is 
stored  in  the  Name  field  as  a  pointer 
to  a  string,  and  the  line  numbers  are 
kept  on  a  linked  list  using  the  Lines 
field.  The  IdentRef  type  is  derived  from 
the  TreeNodelype,  so  that  all  identifiers 
can  be  kept  in  a  sorted  binary  tree. 

The  IdentTree  type  implements  a  tree 
of  LdentRef  objects.  It  is  derived  from 
the  generic  Tree  type,  and  the  Compare 
and  GetKey  methods  are  overridden  to 
extract  and  compare  key  values  from 
LdentRef  objects.  In  particular,  GetKey 
returns  the  Name  string  pointer  stored 
in  each  IdentRef  and  Compare  com¬ 
pares  the  strings. 

The  general  flow  of  the  CrossRef pro- 
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gram  is  as  follows:  First  the  identifier 
tree  is  initialized  using  the  Ldents.Init 
constructor.  Then  the  Input  and  Out¬ 
put  files  are  prepared  and  are  assigned 
buffers.  Next,  all  Turbo  Pascal  reserved 
words  are  inserted  into  the  tree,  so  that 
they  can  be  ignored  in  the  cross-refer¬ 
ence  listing.  The  ProcessFile  procedure 
processes  the  input  file  and  produces 
a  source  listing  with  line  numbers,  and 
the  Printldents  procedure  prints  the 
identifier  cross  reference.  Finally,  the 


Such  partial  knowledge 
of  container  elements 
is  achieved  through 
abstract  element  types 


Idents.Done  destructor  is  called  to  dis¬ 
pose  of  the  entire  cross-reference  tree. 

The  InsertKeyWord  procedure  uses 
a  recursive  binary  iteration  to  insert  the 
reserved  words  into  the  tree.  This  en¬ 
sures  optimal  distribution  of  the  key¬ 
word  entries  in  the  tree;  if  a  straight  for 
loop  had  been  used  to  insert  the  key¬ 
words,  the  tree  would  become  a  worst- 
case  unbalanced  tree,  because  the  key¬ 
words  are  sorted  alphabetically  in  the 
KeyWord  table. 

The  ProcessFile  procedure  “tokenizes” 
the  input  stream  to  isolate  identifier 
references.  It  ignores  strings,  hex-num¬ 
bers,  and  comments,  and  calls  Getldent 
to  process  each  identifier.  Getldent,  af¬ 
ter  reading  the  identifier,  uses  the  Search 
method  to  find  or  create  a  correspond¬ 
ing  IdentRef  node.  The  Newldent  pro¬ 
cedure  is  called  if  Search  cannot  locate 
the  identifier  in  the  tree,  and  Newldent 
then  creates  a  new  IdentRef  with  one 
LineRef  in  the  Lines  list. 

Because  the  tree  contains  only  ob¬ 
jects  of  type  IdentRef  the  result  of  the 
Search  method  call  in  Getldent  can  be 
typecast  to  the  IdentRefPtr  type.  If  the 
resulting  IdentRef  has  an  empty  Lines 
list,  it  is  a  reserved  word,  and  such 
references  are  ignored.  Otherwise,  if 
the  line  number  of  the  last  reference 
on  the  Lines  list  is  not  the  current  line 
number,  then  a  new  LineRef  object  is 
added  to  the  list. 

The  Printldents  procedure  calls  Print- 
Ref for  each  IdentRef  object  in  the  Idents 
tree.  PrintRef  ignores  the  IdentRef  if  the 
Lines  list  is  empty,  indicating  a  reserved 
word;  otherwise,  it  prints  the  identifier, 


and  calls  PrintLine  for  each  LineRef  in 
the  Lines  list.  PrintLine  prints  the  refer¬ 
ence  line  number  with  a  maximum  of 
RefPerLine  references  per  line.  Again, 
notice  the  typecasts  in  both  PrintRef 
and  PrintLine,  which  promote  the  ge¬ 
neric  TreeNode  and  ListNode  types  into 
the  specific  IdentRef  and  LineRef  types. 

Conclusion 

The  ability  to  add  new  data  types  that 
behave  such  as  built-in  data  types  makes 
it  possible  to  extend  Pascal  itself  to 
behave  like  a  more  abstract  language. 
One  only  needs  to  provide  a  generic 
object  type  for  stacks,  linked  lists,  or 
queues.  Then  anyone  can  use  the  ob¬ 
ject’s  operations  simply  by  creating  a 
type  definition  for  the  objects  to  be 
manipulated.  Objects  that  are  to  be  man¬ 
aged  can  be  as  simple  as  a  stack  of 
integers  or  as  complex  as  a  list  of  win¬ 
dows  open  on  a  desktop  complete  with 
text  buffers,  scroll  bars,  and  mouse  sup¬ 
port. 

Regardless  of  the  complexity  of  the 
objects  managed,  the  basic  object  type 
never  needs  to  be  modified  at  the  source 
level.  Because  the  behavior  of  object 
types  can  be  extended  and  modified 
through  inheritance,  users  of  object  li¬ 
braries  only  need  the  interface  specifi¬ 
cation  to  modify  the  behavior  of  de¬ 
rived  objects.  Object  libraries  differ  sub¬ 
stantially  from  the  conventional  libraries 
provided  by  third-party  vendors,  where 
access  to  source  code  is  a  critical  issue. 
As  programmers  become  less  concerned 
with  source  code  availability,  I  think 
there  will  be  two  different  types  of 
programming  projects  —  projects  that 
provide  object  libraries  and  projects 
that  use  them.  Builders  of  object  librar¬ 
ies  are  assured  that  they  can  provide 
truly  reusable  code.  Users  of  object 
libraries  will  experience  tremendous 
productivity  boosts  by  inheriting,  rather 
than  reinventing  the  wheel  every  time 
they  need  data  structure  management 
code  for  a  new  application. 

Availability 
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Extensible 

Hashing 

A  keyed  random  access  method  for  disk  files 


Steve  Heller 


Next  to  every  DOS  program¬ 
mer’s  terminal  must  be  a  for¬ 
tune  cookie  with  a  fortune  that 
reads  “640K  is  the  mother  of 
invention.”  And  if  you’ve  ever 
had  to  manage  large  files  of  records, 
you’ve  probably  cracked  this  cookie 
more  than  once. 

The  goal  of  this  article  is  to  show 
how  you  can  retrieve  any  record  in  a 
multimegabyte  file  with  one  disk  ac¬ 
cess,  and  any  record  in  any  size  file 
with  a  maximum  of  two  accesses. 
KRAM.PAS,  Listing  One,  page  116,  (writ¬ 
ten  using  Turbo  Pascal  5.0)  allows  any 
record  in  a  file  of  up  to  approximately 
1.4  Mbytes  of  user  data  to  be  retrieved 
with  one  disk  access.  But  before  we 
look  at  the  code,  let’s  examine  the  ba¬ 
sic  algorithm. 

Extensible  Hashing 

Extensible  hashing  uses  a  record’s  key 
to  compute  a  hash  code.  The  first  n 
bits  of  the  hash  code  ( n  =  10  in 
KRAM.PAS)  are  used  as  an  index  into 
a  table  of  block  numbers.  All  records 
whose  hash  codes  are  the  same  in  their 
first  n  bits  are  stored  in  the  same  block. 
For  faster  access,  a  possible  optimiza¬ 
tion  is  to  use  the  full  hash  code  again 
to  look  up  the  record  within  the  block. 
This  is  especially  valuable  when  using 
large  data  blocks,  as  a  significant  amount 
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of  time  can  be  consumed  in  the  search 
for  empty  slots  when  adding  records. 

When  a  block  is  full,  it  must  be  split 
into  two  new  blocks.  The  distribution 
of  records  between  the  two  new  blocks 
is  based  on  one  more  bit  of  the  full 
hash  code  than  was  used  before  the 
split.  For  example,  if  the  hash  code 
used  to  look  up  the  record  in  the  old 
block  was  4  bits  long,  with  the  value 
1011,  then  the  first  new  block  would 
contain  records  with  hash  codes  of 
10110,  and  the  second  new  block  would 
contain  records  with  hash  codes  of  101 1 1 . 

Index-in-Memory 

There  are  two  ways  of  extending  the 
capacity  of  a  KRAM  file.  For  maximum 
speed  and  simplicity  of  programming, 
you  can  keep  the  entire  index  table  in 
memory,  writing  it  out  to  the  KRAM  file 
only  when  it  is  modified  as  blocks  are 
split,  as  is  done  in  KRAM.PAS.  This 
“index-in-memory”  approach,  however, 
limits  the  maximum  size  of  the  files 
that  you  can  use:  For  example,  if  you 
are  willing  to  set  aside  about  140K  bytes 
for  the  index  and  the  data  buffers,  you 
could  retrieve  any  record  from  a  file  of 
about  128  Mbytes  in  one  access. 

The  other  possibility  is  to  keep  the 
index  table  mostly  on  disk  in  the  KRAM 
file,  and  read  portions  of  it  into  mem¬ 
ory  as  needed.  This  requires  two  disk 
accesses,  one  for  the  index  and  one  to 
retrieve  the  data,  but  only  16K  bytes 
of  memory  would  suffice  for  any  size 
file.  Of  course,  as  a  compromise,  you 
could  keep  a  few  of  the  most  recently 
used  index  records  in  memory.  This 
would  reduce  the  number  of  accesses 


to  the  index  if  your  references  tend  to 
be  repetitious. 

While  discussing  the  code,  I  will  men¬ 
tion  other  possible  extensions  and  op¬ 
timizations  that  were  not  included  in 
the  code,  primarily  because  the  listings 
would  have  become  too  large. 

Data  Structures 

First,  let’s  examine  the  data  structures 
used  to  keep  track  of  the  current  status 
of  a  KRAM  file.  The  sizes  of  these  struc¬ 
tures  are  parameterized  so  that  you  can 
adapt  them  to  your  particular  applica¬ 
tion.  This  is  important  primarily  when 
you  use  the  “index-in-memory”  ap¬ 
proach,  as  the  maximum  file  size  is 
then  limited  by  the  number  of  index 
entries  and  the  size  of  each  data  block. 
The  maximum  data  storage  available 
in  this  case  can  be  approximated  by 
the  formula: 

DATASIZE*INDEXCOUNT*.67; 

DATASIZE  refers  to  the  number  of  bytes 
in  a  data  block,  and  INDEXCOUNT  re¬ 
fers  to  the  number  of  entries  in  the 
index.  (Note  that  INDEXCOUNT  must 
be  a  power  of  two  because  it  must 
have  one  entry  for  each  possible  hash 
code  of  the  maximum  length  allowed.) 

The  constant  .67 is  an  approximation 
of  the  packing  factor  or  the  proportion 
of  the  file  that  is  occupied  by  data 
records  assuming  random  keys.  The 
exact  value  of  the  packing  factor  de¬ 
pends  on  the  distribution  of  keys,  but 
shouldn’t  vary  much  from  this  value. 

For  example,  if  you  needed  to  store 
(continued  on  page  69) 
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(continued  from  page  66) 

100,000  100-byte  records  for  a  total  data 
storage  requirement  of  10  Mbytes,  you 
could  set  INDEXCOUNT  to  8192  and 
DATASIZE  to  2048,  giving  a  maximum 
accessible  file  size  of  16  Mbytes.  This 
provides  an  approximate  storage  ca¬ 
pacity  of  11.2  Mbytes. 

The  memory  requirement  for  the  data 
and  index  buffers  in  the  “index-in- 
memory”  approach  is: 

( 2’TNDEXCOUNT)  +  (3*DATASIZE); 

as  three  data  buffers  are  required  when 
splitting  a  block.  The  example  of  100,000 
100-byte  records  would  require  2*8192 
+  3*2048,  or  22K  bytes  of  memory  for 
the  index  and  data  buffers. 

Initialization 

Kramlnit  is  used  to  create  a  new  KRAM 
file.  Once  created,  Kramlnit  initializes 
the  first  data  block  to  all  zeros,  and  sets 
all  pointers  in  the  index  block  to  point 
to  that  first  data  block.  Kramlnit  also 
initializes  the  parameter  block,  which 
contains  the  data  length,  the  key  length, 
and  the  current  high  block  number. 

Once  the  file  has  been  initialized, 
call  KramOpen  to  open  the  file,  read 
the  parameter  block  and  the  index  block 
into  memory,  and  allocate  space  for 
the  temporary  data  block.  The  declara¬ 
tion  for  the  FileRec  record  type  shows 
how  the  file  information  is  associated 
with  the  file  pointer. 

Turbo  Pascal  5.0  represents  an  un¬ 
typed  file  as  a  record  type,  called  ''File¬ 
Rec.”  The  UserData  field,  however,  is 
never  accessed  by  Turbo  Pascal,  and 
is  free  for  user-written  routines  to  store 
data  in.  Therefore,  I  have  redefined 
that  field  as: 

UserData:  array  [1  .  .  4]  OF  pointer; 

Currently,  only  the  first  element  is  used 
to  store  the  address  of  the  KramParam 
block  for  the  file.  Therefore,  any  num¬ 
ber  of  KRAM  files  may  be  open  at  once, 
subject  to  system  limitations  on  file  han¬ 
dles,  with  only  the  file  handle  itself 
being  passed  to  the  KRAM  routines. 

Adding  Records  to  the  File 

KramAdd  is  used  to  write  records  to 
the  KRAM  file.  KramAdd  returns  TRUE 
if  the  record  was  added  successfully 
(the  key  was  not  a  duplicate  of  one  in 
the  file),  and  FALSE  otherwise. 

KramAdd  first  calls  HashCode  with 
the  key  value  to  calculate  which  index 
entry  corresponds  to  the  record  to  be 
stored.  It  then  retrieves  the  block  num¬ 
ber  pointed  to  by  that  index  entry.  If 
that  block  is  not  the  one  currently  in 
memory,  it  must  be  retrieved  from  disk. 


A  possible  optimization  here  is  to  keep 
more  than  one  data  block  in  memory, 
discarding  the  least  recently  used  block 
when  its  buffer  is  needed  for  another 
block. 

The  next  task  is  to  discover  whether 
the  key  is  a  duplicate  of  one  already 
in  the  block,  and  if  not,  whether  there 
is  an  empty  slot  in  the  block  to  store 
the  new  record.  If  an  empty  slot  is 
found  (and  there  is  no  duplication), 
then  the  data  is  moved  from  the  func¬ 
tion  arguments  KeyValue  and  DataValue 
to  that  slot. 

If  no  empty  slot  is  available,  and 

The  distribution  of 
records  from  the  full 
block  to  the  two  tem¬ 
porary  buffers  depends 
on  the  updated  entries 
in  the  index  table 


there  is  no  duplication  of  keys,  we 
must  split  this  block  to  make  room  for 
the  new  record.  The  first  subtask  here 
is  to  scan  the  index  table  to  determine 
which  index  entries  are  affected  by  the 
split  (that  is,  which  index  entries  point 
to  this  block).  Note  that  if  only  one 
index  entry  points  to  this  block,  the 
block  cannot  be  split  because  one  en¬ 
try  cannot  point  to  more  than  one  block. 
Splitting  a  block  under  these  condi¬ 
tions  would  cause  one  of  the  new  blocks 
to  be  inaccessible. 

To  prevent  this  from  occurring,  page 
the  index  from  disk,  allowing  it  to  be 
increased  in  size  as  needed.  When  us¬ 
ing  a  paged  index,  you  should  also 
keep  in  each  data  block  a  record  of  the 
number  of  bits  of  the  key  that  are  used 


to  access  that  block.  This  way,  you 
won’t  have  to  page  through  a  large 
part  of  the  index  table  to  find  out  which 
entries  are  affected  by  a  split.  For  ex¬ 
ample,  if  a  data  block  contains  all  re¬ 
cords  with  a  hash  code  starting  with 
the  5  bits  11101,  splitting  it  would  af¬ 
fect  all  index  entries  that  start  with  11101. 
After  determining  that  at  least  two  en¬ 
tries  point  to  this  block,  allocate  an¬ 
other  block  to  accommodate  the  over¬ 
flow,  and  update  the  higher  numbered 
half  of  the  affected  entries  so  they  point 
to  the  new  block.  Next,  allocate  two 
temporary  block  buffers,  LowDataPtr a 
and  HighDataPtr a  (so  called  because 
they  will  receive  the  records  with  lower- 
and  higher-hash  codes,  respectively). 
Next,  initialize  them  to  zeros  so  they 
are  ready  to  receive  the  records  from 
the  full  block. 

The  distribution  of  records  from  the 
full  block  to  the  two  temporary  buffers 
depends  on  the  updated  entries  in  the 
index  table.  The  key  of  each  record  is 
used  to  calculate  the  hash  code  for  that 
record  and  the  block  number  is  looked 
up  in  the  index  table.  If  the  block  num¬ 
ber  in  the  table  is  the  same  as  the  block 
number  of  the  full  block,  the  record 
will  end  up  in  the  old  block  when  we 
are  through  because  the  old  block  num¬ 
ber  was  kept  for  the  first  (lower)  half 
of  the  updated  index  table  entries. 

For  example,  suppose  that  before 
block  12  became  full,  the  relevant  sec¬ 
tion  of  the  index  table  looked  like  that 
shown  in  Figure  1. 

If,  after  the  split,  the  highest  block 
number  in  use  was  22,  the  table  would 
look  like  that  shown  in  Figure  2. 

All  records  with  hash  codes  from  100 
to  103  would  remain  in  block  12,  and 
records  with  hash  codes  from  104  to 
107  would  be  moved  to  block  23. 

After  the  records  have  been  moved 
to  their  new  places  in  LowDataPtr a 
and  HighDataPtr a,  the  file  is  updated. 
First,  the  old  block  (now  approximately 
half-empty)  is  written  back  to  its  old 
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Element 

Number 

Value 

100 

12 

101 

12 

102 

12 

103 

12 

104 

12 

105 

12 

106 

12 

107 

12 

Figure  1:  The  index  table  before  a  split 


Element 

Number 

Value 

100 

12 

101 

12 

102 

12 

103 

12 

104 

23 

105  , 

23 

106 

23 

107 

23 

Figure  2:  The  index  table  after  a  split 
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position.  Next,  the  new  block  is  added 
to  the  end  of  the  file.  The  parameter 
and  index  buffers  are  then  written  back 
to  the  file  to  keep  the  high  block  num¬ 
ber  and  index  tables  up-to-date.  Fi¬ 
nally,  we  return  to  the  top  of  the  WHILE 
loop  to  handle  the  insertion  of  the  rec¬ 
ord,  now  that  there  is  room  in  the  block 
it  belongs  in. 

KramClose  does  what 
its  name  implies;  it 
closes  the  file,  after 
making  sure  that 
anything  that  has  been 
changed  is  written  out 
to  the  file 


The  Rest  of  the  Code 

KramRead  is  basically  the  same  as 
KramAdd  (except  that  it  doesn’t  have 
to  deal  with  the  splitting  of  blocks)  and 
requires  little  explanation.  KramClose 
does  what  its  name  implies;  it  closes 
the  file,  after  making  sure  that  anything 
that  has  been  changed  is  written  out 
to  the  file.  Be  sure  to  call  this  routine 
if  you  have  added  any  records  to  the 
file.  Kramlnfo  is  a  procedure  that  you 
can  call  to  find  out  the  key  and  data 
lengths  of  a  KRAM  file. 

HashCode  takes  the  key  of  a  record 
and  returns  a  32-bit  hash  code,  from 
which  the  calling  program  extracts  the 
number  of  bits  it  needs  to  access  the 
index  table.  SeekBlock takes  a  data  block 
number  and  positions  the  file  to  enable 
that  block  to  be  read  or  written. 

The  main  program  is  a  driver  that 
illustrates  how  to  call  these  routines.  It 
will  read  an  ASCII  file  of  lines,  each 
consisting  of  a  string  key  and  numeric 
data,  optionally  initializing  and  loading 
the  KRAM  file.  Then  it  will  retrieve  all 
the  records,  checking  that  they  all  exist 
and  have  the  same  data  in  them  as 
when  they  were  created.  The  data  I 
used  for  testing  is  the  same  as  the  rec¬ 
ord  numbers  of  the  keys;  the  test  rec¬ 
ords  were  created  by  a  small  test  data 
generating  program,  KRAMDATA.PAS 
(see  Listing  Two,  page  121). 

In  many  applications,  it  is  necessary 
to  be  able  to  delete  records  from  a 
KRAM  file.  The  simplest  way  to  do  this 
is  to  zero  out  the  key  and  data  of  the 


record  you  want  to  delete,  so  that 
KramAdd  can  reuse  its  slot.  This  would 
not  work  properly,  however,  if  you 
decided  to  use  hashing  to  speed  up  the 
lookup  within  a  block.  In  that  case, 
you  could  change  the  key  to  some¬ 
thing  that  would  not  occur  in  your 
application,  such  as  FFh.  You  would 
then  change  KramAdd  to  reuse  a  slot 
that  had  that  value,  and  change  the 
block-splitting  function  to  ignore  rec¬ 
ords  that  had  that  key.  Thus,  whenever 
a  block  was  split,  any  deleted  records 
that  had  not  already  been  reused  would 
disappear. 

Conclusion 

Lest  you  get  the  impression  that  KRAM 
files  are  the  best  possible  organization 
for  keyed  access,  I  should  mention  two 
limitations  of  KRAM  files,  which  make 
them  unsuitable  for  certain  applications. 
First,  this  is  not  an  indexed  sequential 
access  method,  but  truly  a  keyed  ran¬ 
dom  access  method.  There  is  no  con¬ 
venient  way  of  retrieving  the  records 
other  than  by  supplying  the  exact  key 
for  the  record  you  need. 

The  second  limitation  is  that  KRAM 
files  are  not  very  efficient  in  their  use 
of  disk  storage.  You  can  expect  that  a 
file  containing  1  Mbyte  of  your  data 
will  occupy  approximately  1.5  Mbytes 
on  the  disk.  This  is  an  unavoidable  side 
effect  of  the  dynamic  storage  alloca¬ 
tion  method  that  gives  KRAM  files  their 
tremendous  speed.  If  these  limitations 
do  not  adversely  affect  your  applica¬ 
tion,  KRAM  files  are  probably  the  best 
way  of  organizing  data  that  requires 
random  access  by  key. 

By  the  way,  a  shareware  version  of 
KRAM  is  also  available.  For  more  infor¬ 
mation,  contact  Chrysalis  Software  Cor¬ 
poration,  at  the  address  at  the  begin¬ 
ning  of  this  article.  Registered  users 
will  receive  an  updated  version  of  the 
program,  incorporating  all  of  the  op¬ 
timizations  and  extensions  mentioned 
in  this  article. 

Availability 

All  source  code  for  articles  in  this  issue 
is  available  on  a  single  disk.  To  order, 
send  $14.95  (Calif,  residents  add  sales 
tax)  to  Dr.  Dobbs  Journal ,  501  Galves¬ 
ton  Dr.,  Redwood  City,  CA  94063,  or 
call  800-356-2002  (from  inside  Calif.) 
or  800-533-4372  (from  outside  Calif.). 
Please  specify  the  issue  number  and 
format  (MS-DOS,  Macintosh,  Kaypro). 
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Optimizing  in  a 

Parallel  Environment 


Data  independence  is  the  key  to  performance 


The  emerging  class  of  small,  rela¬ 
tively  inexpensive  multiple- 
processor  workstation  comput¬ 
ers  provides  a  degree  of  raw 
computing  power  that  seriously 
challenges  the  computing  power  of¬ 
fered  by  minisupercomputers.  The  avail¬ 
ability  of  the  appropriate  software 
tools  —  language  extensions,  paralleliz¬ 
ing  compilers,  and  parallel  environment 
debuggers  and  profilers  —  makes  it  pos- 
sibletoexploit  this  multiprocessor  architec¬ 
ture  in  a  straightforward  manner. 

This  article  explores  the  SGI  parallel¬ 
ization  scheme  that  Silicon  Graphics 
has  implemented  in  its  Power  Series 
two-processor  and  four-processor  work¬ 
stations  and  their  accompanying  soft¬ 
ware  development  tools.  I  use  a  test 
program  to  take  you  through  this  explora¬ 
tion  process.  First,  I’ll  introduce  the 
syntax,  highlighting  coding  problems 
and  solutions.  Next,  I’ll  describe  the 
actual  implementation  of  the  paralleli¬ 
zation  scheme.  Finally,  I’ll  show  the 
bottom  line  for  high-performance  com¬ 
puting,  and  confirm  that  performance 
gains  are  possible  with  the  SGI  scheme 
if  one  is  mindful  of  its  limitations. 

SGI  Parallelization  Scheme 

My  exploration  strategy  centers  around 
the  DO  loop.  If  the  iterations  of  the  loop 
are  independent  from  each  other,  then 
the  loop  can  be  divided  among  n  avail¬ 
able  processors,  and  can  run  roughly 
n  times  faster.  These  separate  execut¬ 
ing  processes  are  known  as  “threads.” 
This  parallelization  scheme  is  not  in- 
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tended  for  use  with  complex,  indepen¬ 
dently  executing  routines  (although  a 
separate  set  of  Unix  tools  exists  to  ac¬ 
complish  that). 

The  goal  here  is  to  accelerate  the 
speed  of  more  common  forms  of  code. 
For  instance,  consider  the  two  DO  loops 
in  Figure  1 .  The  scalar  DO  loop  is  trans¬ 
formed  into  a  parallel  loop  by  the  in¬ 
clusion  of  a  parallelization  directive  im¬ 
mediately  before  the  DO  statement. 

The  program  is  parallelized  after  com¬ 
pilation  with  the  -mp  option.  The  par¬ 
allelization  directive  affects  only  the 
DO  loop  that  immediately  follows  that 
directive.  The  directive  resembles  a  For¬ 
tran  comment,  and  is  ignored  by  the 
compiler  when  the  -mp  option  is  not 
used.  More  importantly,  the  directive 
is  ignored  by  other  platforms  that  do 
not  have  multiple  processors. 

The  syntax  allows  for  LOCAL,  SHARE, 
and  LASTLOCAL  declarations  to  restrict 
the  scope  of  variables  and  improve 
program  performance  (see  sidebar  1, 
page  74).  LOCAL  variables  are  local¬ 
ized  to  each  thread.  SHARE  variables 
are  in  common  between  executing 
threads.  LASTLOCAL  variables  are 


Scalar: 

do  i  =  1 ,  n 
a(i)  =  b(i)  *  c(i) 
enddo 

Parallel: 

c$doacross  local(i),  sharefa,  b,  c,  n) 
do  i  =  1 ,  n 

a(i)  =  b(i)  *  c(i) 
enddo 

Figure  1:  A  scalar  and  a  parallel  DO 
loop 


treated  like  LOCAL  except  that  the  value 
of  the  variable  in  the  thread,  which 
finishes  last,  is  made  available  to  code 
past  the  parallelized  loop. 

A  variety  of  Fortran  statements,  in¬ 
cluding  subroutines,  functions,  and  in- 
trinsics,  are  allowed  inside  of  parallel¬ 
ized  loops.  The  only  restriction  is  that 
the  statements  must  have  no  side  ef¬ 
fects  —  the  statements  must  depend 
upon  input  in  the  passed  arguments, 
they  cannot  modify  common  data,  and 
they  cannot  use  static  data.  All  of  the 
intrinsic  functions  that  are  supplied  in 
the  library  meet  this  requirement  and 
can  be  used  safely. 

The  one  construct  that  is  forbidden 
is  branching  outside  the  DO  loop.  Typi¬ 
cally,  this  construct  is  a  logical  test  that 
causes  premature  termination  of  the 
loop.  It  doesn’t  make  sense  to  use  a 
conditional  exit,  which  may  behave  dif¬ 
ferently  for  each  thread  in  a  parallel 
environment. 

Additionally,  a  number  of  functions 
that  are  unique  to  the  parallel  environ¬ 
ment  are  available  to  help  the  execut¬ 
ing  program  work  more  efficiently  with¬ 
in  the  multiprocessor  environment.  The 
straightforward  syntax  of  these  func¬ 
tions,  (which  retains  the  algorithm  in 
its  original  form),  along  with  transpar¬ 
ency  to  other  platforms,  facilitate  im¬ 
plementation.  (This  is  especially  useful 
for  programmers  who  do  not  wish  to 
master  the  details  of  systems-level  pro¬ 
gramming.)  The  syntax  is  conservative 
in  the  sense  that  the  loop  code  itself 
needs  no  restructuring;  the  addition  of 
the  directive  (and  the  optional  addition 
of  the  scope  declarations)  are  the  only 
requirements.  The  retention  of  the  ba¬ 
sic  algorithm  maintains  clarity  and  aids 
in  the  transformation  of  scalar  code. 
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(continued  from  page  72) 

The  parallel  implementation  restruc¬ 
tures  the  code  during  compilation  into 
separate  slaved  processes  for  the  paral¬ 
lelized  loop  (see  sidebar  2,  page  76). 
The  parallelized  program  is  under  soft¬ 
ware  control  during  execution,  and  can 
create  as  many  processes  as  are  appro¬ 
priate  for  the  machine  on  which  the 
code  is  executing.  (The  number  of  pro¬ 
cesses  can  range  from  1,  for  a  single 
processor  system,  to  4.)  The  sensing 
and  adjustment  is  automatic  so  that 
separate  versions  of  a  program  need 
not  be  created  for  a  multiplatform  envi¬ 
ronment.  This  feature  offers  a  great 
deal  of  flexibility  to  programmers  who 
use  networked  NFS  systems,  in  which 
a  single  executable  can  go  to  any  target 
machine.  In  practice,  this  works  well, 
although  parallelized  programs  that  run 
on  single  processor  systems  execute 
more  slowly  due  to  the  system  over¬ 
head. 

Data  Dependency 

The  primary  limitation  of  a  parallelized 
program  is  “data  dependency,"  in  which 
one  of  several  currently  executing  threads 
alters  data  that  can  be  read  by  any 
other  executing  thread,  producing  non¬ 
sensical  results.  When  this  method  of 
parallelization  is  used,  many  common 


coding  situations  become  unusable  un¬ 
less  they  are  recognized,  and  then  so¬ 
lutions  are  applied. 

Consider,  for  example,  the  DO  loop 
in  Example  1 .  The  process  of  successful 
parallelization  requires  each  iteration 
of  the  loop  to  be  data-independent  of 
any  other  iteration  of  the  loop.  In  this 
way,  the  loop  can  be  broken  into  n 
separate  parallel  processes,  or  can  even 
be  left  scalar,  without  affecting  the  re¬ 
sults.  As  long  as  the  code  in  the  loop 
for  all  values  of  the  index  is  run,  re¬ 
gardless  of  the  order  or  grouping  of  the 
code,  the  outcome  is  the  same. 

Data  dependency  occurs  when  a  vari¬ 
able  is  modified  (or  could  be  modified) 
by  one  executing  thread,  while  at  the 
same  time,  other  executing  threads  may 
be  reading  or  modifying  the  same  vari¬ 
able.  The  value  of  the  variable  becomes 
unpredictable,  causing  the  code  in  the 
loop  to  produce  results  that  vary  from 
the  scalar  and  also  vary  from  nin  to  mn. 

In  the  DO  loop  in  Example  2,  the 
array  variable  arr  references  a  value 
that  is  not  current  with  the  index.  The 
variable  is  manipulated  and  then  as¬ 
signed  to  arri i).  Other  threads  can  write 
to  arri i-1),  and  arri i)  can  be  referenced 
by  other  threads.  The  iterations  are  not 
truly  independent.  When  the  DO  loop 
is  parallelized,  the  parallel  version  can- 


Parallelization 

Directives 

> 

Each  directive  begins  in  column  1 
and  behaves  as  a  comment  unless 
multiprocessing  is  enabled  during 
compilation  (-mp  option).  Code 
containing  directives  is  generally  port¬ 
able  except  to  platforms,  which  use 
a  similar  scheme  such  as  the  CRAY. 

Variables  referenced  in  the  scope 
arguments  are  by  name  only;  declara¬ 
tion  is  done  in  the  usual  manner  at 
the  top  of  the  program.  Default  scope 
declaration  is  SHARE  for  all  unde¬ 
clared  variables  and  for  variables 
appearing  in  COMMON  blocks,  ex¬ 
cept  the  DO  loop  index,  which  is 
LASTLOCAL.  Variables  can  only  ap¬ 
pear  in  one  scope  argument. 

CSDOACROSS  [LOCAL(list. . .), 
SHARE(Ust . .),  LASTLOCAL(list . .)] 

This  is  the  principal  directive  used 
to  select  a  loop  for  parallelization. 
It  immediately  proceeds  the  selected 
loop  and  any  of  three  optional  scope 
arguments.  CSDOACROSS  directives 
do  not  nest  and  subsequent  nested 
directives  are  ignored. 

LOCAL(list ...  7  are  all  variables 
local  to  each  separately  executing 
thread.  All  LOCAL  variables  must  be 
explicitly  declared,  and  all  data  types, 
including  arrays,  can  be  of  type  LO¬ 
CAL. 

SHAREOist ...  7  are  all  variables 
in  common  to  all  executing  threads 
and  the  remainder  of  the  program. 
SHARE  variables  are  typically  arrays, 
while  nonarray  variables  can  be  used 
if  read  only,  to  avoid  data  depend¬ 
ency. 

LASTLOCAL(list .  .  .  7  are  local  vari¬ 
ables  in  which  the  last  executing 
thread  returns  its  value  for  use  past 
the  parallelized  block.  The  value  re¬ 
turned  is  not  always  the  assumed 
value  and  great  caution  must  be  used 
especially  if  load  balancing  between 
threads  is  not  even. 

C$& —  This  is  treated  as  a  continu¬ 
ation  line  for  lengthy  parallelization 
directives. 

C$ — This  is  used  to  selectively 
include  lines  or  blocks  of  code  dur¬ 
ing  parallelization.  Typically,  this  is 
used  to  mask  lines  that  are  parallel 
specific  or  call  routines  from  the 
parallel  library.  — B.B. 
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(continued  from  page  74) 
not  guarantee  the  same  result  that  is 
guaranteed  by  use  of  the  scalar  version 
of  the  loop.  This  type  of  data  depen¬ 
dence  is  known  as  “recurrence.” 

Data  dependency  inhibits  paralleli¬ 
zation  and  does  not  yield  the  perfor¬ 
mance  inherent  in  the  machine.  The 
solution  to  the  problem  of  data  depen¬ 
dency  is  recognition  of  its  existence, 
followed  by  modification  of  the  algo¬ 
rithm.  A  simple  modification  of  the  al¬ 
gorithm  isn’t  always  possible  to  do, 
and  not  all  algorithms  can  be  parallel¬ 
ized.  In  short,  the  ability  to  break  data 
dependency  is  algorithm-specific.  Most 
algorithms  must  be  approached  as  spe¬ 
cial  cases. 

Many  different  types  of  dependency 
can  prevent  parallelization.  A  number 
of  common  situations  have  data  de¬ 
pendencies  that  can  be  generalized.  In 
addition,  other  situations  have  data  de¬ 
pendencies  that  are  not  obvious.  Once 
again,  the  key  is  recognition  of  the  exis¬ 
tence  of  data  dependency,  especially 


when  existing  scalar  code  is  adapted  to 
the  parallel  environment.  When  parallel¬ 
ization  is  not  possible,  the  solution  usu¬ 
ally  involves  major  restructuring  of  the 
algorithm. 

Recurrence 

The  data  dependency  case  discussed 
in  the  previous  section  is  an  example 
of  recurrence.  Modified  values  recur 
during  the  execution  cycle  of  the  threads 
that  are  associated  with  a  parallelized 
loop,  causing  unpredictable  results. 
There  is  no  general  way  to  parallelize 
loops  in  which  recurrence  occurs.  One 
possible  solution  is  to  rewrite  the  algo¬ 
rithm.  If  the  recurrence  occurs  in  the 
inner  loop  of  nested  loops,  a  solution 
is  to  parallelize  the  outer  loop. 

To  see  how  this  works,  consider  the 
parallelization  shown  in  Figure  2.  If  x 
is  used  only  inside  of  the  loop  and  the 
value  of  x  is  assigned  before  x  is  used, 
then  the  loop  can  be  declared  a  local 
variable,  and  can  be  parallelized.  If  the 
value  of  x  is  not  assigned  first,  then  x 


becomes  data  dependent  upon  the  value 
of  xfrom  other  iterations.  The  loop  can¬ 
not  be  parallelized  by  declaring  x  to 
be  LOCAL. 

Figure  3  presents  another  example  of 
data  dependence,  where  the  value  of 
indx  is  passed  between  iterations,  caus¬ 
ing  data  dependency  to  occur.  Although 
indx  is  used  inside  of  the  loop,  the  value 
of  indx  is  read  before  indx  is  assigned, 
so  indx  cannot  be  a  local  variable. 
Dependency  can  also  be  created  by  the 
manner  in  which  indx  is  determined, 
but  the  determination  of  indx  in  this 
particular  case  is  independent. 

If  the  variable  can  be  determined 
uniquely  for  each  iteration,  so  that  a 
value  for  the  variable  is  not  passed 
from  iteration  to  iteration,  then  the  loop 
can  be  parallelized.  The  value  of  indx 
in  Figure  3  is  determined  only  from  the 
loop  index  i.  In  order  to  arrive  at  this 
solution,  the  original  algorithm  was  re¬ 
written  and  is  no  longer  straightfor¬ 
ward.  This  solution,  then,  is  highly  al¬ 
gorithm-dependent. 

The  next  example  of  indirect  index¬ 
ing  is  shown  in  Figure  4.  The  problem 
is  seen  in  the  last  line  of  the  loop.  The 
value  of  iix  is  dependent  upon  the 
values  stored  in  the  ixoffset  and  indexx 
arrays,  and  cannot  be  guaranteed  to 
be  independent  from  iteration  to  itera¬ 
tion.  This  problem  is  different  from  the 
loop  carried  value  problem  because 
the  value  of  iix  is  looked  up,  rather 
than  calculated.  Unless  the  contents  of 
(continued  on  page  79) 


array  variable  references  a  value  that 
is  not  current  with  the  index 


Local  Variables: 

do  i  =  1 ,  n 
x  =  a(i)**3 
b(i)  =  x  *  b(i) 
enddo 

The  variable  x  is  dependent.  Without  an 
explicit  declaration  as  LOCAL,  this  loop 
cannot  be  parallelized. 

c$doacross  localfi,  x) 
do  i  =  1 ,  n 
x  =  a(i)**3 
b(i)  =  x  *  b(i) 
enddo 


Figure  2:  The  effect  of  data  depend¬ 
ency  with  LOCAL  variables 


Parallel  Implementation 


Upon  encountering  a  C$DOACROSS 
statement,  the  compiler  creates  a  new 
subroutine  that  represents  the  loop 
and  its  contained  functionality,  and 
then  replaces  the  loop  with  a  call  to 
the  library  routine  MP_MULTL.  The 
new  subroutine  is  named  by  prepend¬ 
ing  an  underscore  to  the  name  of  the 
routine  that  originally  called  the  loop 
and  then  appending  an  underscore 
and  a  number  to  that  name.  The  num¬ 
ber  that  is  appended  starts  at  1,  and 
is  incremented  for  each  CSDOACROSS 
contained  in  the  original  routine.  The 
new  subroutine  handles  variables  de¬ 
clared  as  LOCAL  as  local  variables. 
Variables  declared  as  SHARE  are  re¬ 
solved  by  reference  back  to  the  origi¬ 
nal  routine.  Any  required  additional 
variables  are  local. 

The  new  routine  is  called  with  four 
arguments:  The  starting  value  of  the 
index,  the  maximum  number  of  exe¬ 
cutions  of  the  loop,  the  increment 
value  of  the  index,  and  a  unique  pro¬ 
cess  ID  number.  The  remainder  of 
the  routine  consists  of  the  parallel¬ 
ized  DO  loop.  The  DO  loop  is  restruc¬ 
tured  (see  Listing  Two,  page  123)  in 
order  to  permit  multiple  copies  of  the 
new  routine  running  in  parallel  to 
work  with  independent  sections  of 
the  DO  loop.  The  code  of  the  new 
subroutine  is  written  once  and  the 
portion  of  the  DO  loop  that  is  ma¬ 
nipulated  is  controlled  by  the  calling 


routine,  MP_MULTL.  This  permits  a 
great  deal  more  run-time  flexibility 
than  is  available  when  hard-coded 
routines  are  used. 

At  run  time,  the  parallelization  is 
effected  by  a  master  routine,  which 
handles  all  of  the  scalar  code.  At  the 
point  in  the  code  when  the  DO  loop 
would  have  been  executed,  the  mas¬ 
ter  routine  passes  the  name  of  the 
new  process  to  MP_MULTJ,  along  with 
the  starting  value  of  the  DO  loop  in¬ 
dex,  the  number  of  cycles,  and  the 
index  increment,  MP_MULTI  divides 
the  loop  according  to  the  number  of 
available  processors,  and  then  invokes 
the  new  process  that  number  of  times, 
with  each  new  process  as  a  slave 
routine.  Additional  routines  manage 
interprocess  signalling  and  synchro¬ 
nization.  The  slave  subprocesses  do 
not  have  to  run  in  synchronization 
with  each  other.  When  the  last  slave 
process  is  completed,  control  returns 
to  the  master  routine  at  the  point  past 
the  loop. 

This  parallelization  scheme  is  very 
flexible.  Parallelized  code  can  run  on 
a  single  processor  system  without 
change,  while  dynamically  adapting 
to  the  number  of  available  heads.  At 
the  other  extreme,  the  number  of 
threads  can  be  limited  dynamically  by 
setting  the  environment  variable  NUM_ 
THREADS  to  a  number  less  than  the 
maximum  number  of  available  heads. 

—  B.B. 
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(continued  from  page  76) 
indexx  and  ixoffset  are  known  to  not 
introduce  dependency,  iix  must  be  con¬ 
sidered  dependent. 

Indirect  indexing  is  also  a  great  source 
of  mn-time  bugs  that  are  nearly  impossi¬ 
ble  to  find.  The  solution  is  to  remove 
the  data-dependent  element  and  place 
it  into  a  nonparallelized  loop.  The  ar¬ 
ray  index  for  the  second  loop  is  now 
the  only  task  of  the  first  loop,  and  is 
stored  in  array  elements  indexed  by  i. 


Scalar: 

index  =  0 
do  i  =  1 ,  n 

indx  =  indx  +  i 
a(i)  =  b(indx) 
enddo 

Parallel: 

c$doacross  local(i,  indx) 
do  i  =  1 ,  n 

indx  =  (i  *  (i  +  1))/2 
a(i)  =  b(indx) 
enddo 

Figure  3:  Example  of  loop-carried  val¬ 
ues  (complicated  indexing) 


Scalar: 

do  i  =  1 ,  n 

ix  =  indexx(i) 
iix  =  ixoffset(ix) 
total(iix)  =  total(iix)  +  delta 
enddo 

Parallel: 

c$doacross  local(ix,  i) 
do  i  =  1 ,  n 

ix  =  indexx(i) 
iix(i)  =  ixoffset(ix) 
enddo 

do  i  =  1 ,  n 

total(iix(i))  =  total(iix(i))  +  delta 
enddo 

Figure  4:  Example  of  indirect  indexing 


Scalar: 

total  =  0.0 
do  i  =  1 ,  n 

total  =  total  +  a(i) 
enddo 

Parallel: 

c$doacross  local(i,  k) 

do  k  =  1 ,  4  I  assume  no  more  than  4 

processors 

sub_total(k)  =  0.0 
do  i  =  k,  n,  4 

sub_total(k)  =  sub_total(k)  +  a(i) 
enddo 
enddo 

total  =  0.0 
do  i  =  1 ,4 

total  =  total  +  sub_total(i) 
enddo 


which  is  common  to  both  loops.  Half 
of  the  original  loop  is  now  parallelized, 
but  performance  may  be  an  issue  if  n 
is  small.  Rewriting  the  loop,  or  even 
leaving  the  original  loop  as  a  nonparal¬ 
lelized  loop,  should  be  considered  if 
performance  suffers  in  the  two-loop 
case.  Note  that  data  dependency  is  still 
present  in  the  second  loop. 

“Sum  reduction”  (Figure  5)  is  a  com¬ 
mon  procedure  that  is  highly  data- 
dependent.  The  implementation  of  sum 
reduction  is  similar  to  the  implementa¬ 
tion  of  the  loop-carried  variable  case. 
In  the  case  of  sum  reduction,  however, 
the  value  of  total  is  presumably  used 
outside  of  the  loop  (while  indx  was 
only  used  inside  of  the  loop). 

The  solution  to  the  data  dependency 
of  sum  reduction  is  similar  to  the  solu¬ 
tion  used  for  the  indirect  indexing  case: 
Subtotals  are  determined,  permitting  the 
loop  to  be  parallelized,  and  the  loop 
is  followed  by  a  grand  summation  loop. 
The  original  loop  is  converted  into  the 
inner  loop  of  a  nested  pair  of  loops. 
Parallelization  then  takes  place  on  the 
outer  loop,  which  then  divides  the  in¬ 
ner  loop  into  the  maximum  number  of 
parallel  processes. 

Unlike  the  example  of  indirect  in¬ 
dexing,  which  contains  two  loops  of 
roughly  equal  size,  the  bulk  of  the  origi¬ 
nal  loop  in  this  case  is  parallelized  and 
followed  by  a  small  grand  summation 
loop.  In  order  to  prevent  cache  and 
performance  problems,  the  threads  in¬ 
terleave  the  array  and  are  not  handled 
as  a  set  of  contiguous  blocks.  The  solu¬ 
tion  to  sum  reduction  can  also  be  made 
more  efficient  and  more  general.  An 
example  of  this  approach  is  shown  in 
TEST.F  (Listing  One,  page  122). 

Performance  Issues 

A  number  of  issues  can  affect  the  per¬ 
formance  of  parallel  schemes.  Foremost 
among  these  issues  are  overhead,  cach¬ 
ing,  and  load  balancing. 

The  CPU  overhead  is  approximately 
100  cycles  for  loop  parallelization.  The 
loop  must  iterate  more  than  about  50 
times  in  order  to  recover  that  overhead. 
Otherwise,  small  parallelized  loops  will 
run  slower  than  the  speed  of  scalar  loops. 

Two  solutions  can  be  employed:  En¬ 
closing  the  maximum  amount  of  work 
in  the  parallelized  loop,  and  using  mul¬ 
tiple  versions  of  a  loop.  The  paralleli¬ 
zation  process  can  accommodate  a  wide 
range  of  normal  Fortran  functionality, 
including  IF .  .  .  THEN .  .  .  ELSE  .  .  . 
ENDIF  blocks,  other  loops,  function 
calls,  subroutine  calls,  and  even  GOTXDs. 
If  data  dependency  does  not  introduce 
restrictions,  the  inclusion  of  as  much 
functionality  in  the  loop  as  possible 
cuts  down  on  overhead  and  keeps  the 


Figure  5:  Example  of  sum  reduction 
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highest  number  of  threads  in  action  to 
improve  performance.  This  solution  also 
means  that  outer  loops  should  be  ex¬ 
amined  preferentially  to  inner  loops 
so  that  the  greatest  amount  of  code  is 
parallelized. 

The  other  solution  to  the  problem 
of  CPU  overhead  is  to  write  both 
parallel  and  scalar  versions  of  a  loop, 
and  place  them  in  an  IF  .  .  ( index  gt. 
threshold) .  .  .  THEN .  .  .  (do  parallel)  .  .  . 
ELSE .  .  .  (do  scalar)  .  .  .  ENDIF  block. 
This  is  a  good  approach  for  maximizing 
program  performance  when  the  value 
of  the  index  varies  across  the  threshold 
value  of  roughly  50  iterations. 

These  multi-processor  machines  have 
exceptionally  large  data  caches.  If  pro¬ 
grams  are  not  written  with  the  cache 
in  mind,  performance  can  suffer  sig¬ 
nificantly.  In  practical  terms,  when  a 
multidimensional  array  is  referenced 
inside  nested  loops,  the  leftmost  index 
of  the  array  must  be  varied  fastest  by 
the  innermost  loop  so  that  memory  is 
addressed  as  contiguously  as  possible. 
(Fortran  stores  arrays  in  column  order, 
so  the  arrays  must  be  referenced  in 
what  always  seems  to  me  to  be  a  back¬ 
wards  order.  I  will  say  more  about  cache 
effects  later.) 

The  parallelization  process  handles 
load  balancing  by  dividing  the  target 
DO  loop  into  equal  pieces,  based  upon 
the  number  of  available  threads  (usu¬ 
ally  the  same  number  as  the  number  of 
available  processors).  If  the  loop  con¬ 
tains  IF  blocks,  or  variable-sized  inner 
loops  (as  is  the  case  in  the  next  exam¬ 
ple),  then  the  execution  time  for  each 
thread  can  be  random.  As  a  conse¬ 
quence,  if  the  work  of  the  parallelized 
loop  is  not  performed  equally,  time  is 
wasted  as  completed  threads  wait  for 
the  slower  threads  to  finish.  The  execu¬ 
tion  of  the  code  that  follows  the  loop 
will  not  occur  until  all  of  the  threads  are 
completed.  The  load  is  not  balanced, 
and  the  penalty  is  increased  execution 
time  due  to  the  idle  processors. 

The  code  in  Example  3  is  a  particu¬ 
larly  vicious  example  of  load  imbal¬ 
ance.  Assume  that  the  outer  loop  is 
parallelized.  The  duration  of  the  exe¬ 
cution  of  the  inner  loop  varies  accord¬ 
ing  to  the  value  of  the  index  of  the 
outer  loop.  Although  the  outer  loop’s 
index  is  divided  into  ranges  of  equal 
size,  the  threads  associated  with  the 
ranges  that  have  larger  values  of  the 
index  will  take  longer  to  complete. 

As  Example  4  shows,  a  solution  is 
to  use  index  i  to  break  the  outer  loop 
into  interleaving  blocks,  such  that  each 
thread  has  a  range  of  values  of  i.  No 
thread  has  only  the  large  values  of  land 
the  resulting  longer  execution  time.  The 
result  is  that  all  threads  execute  in  about 


the  same  amount  of  time.  The  load  is 
balanced.  The  only  concern  is  that  the 
process  of  interleaving  can  disrupt  con¬ 
tiguous  memory  blocks,  which  can  po¬ 
tentially  degrade  cache  performance. 

Data  dependency 
inhibits  parallelization 
and  does  not  yield  the 
performance  inherent 
in  the  machine 


The  Bottom  Line 

The  real  test  of  the  efficiency  of  the 
SGI  parallelization  scheme  is  with  the 
clock.  The  goal  of  the  scheme  is  faster 
execution,  which  allows  larger  and  more 
complex  problems  to  be  addressed. 

A  short  test  program  was  developed 
that  reflects  the  types  of  tasks  I  would 
like  to  speed  up  in  my  own  work.  It 
fills  and  manipulates  large,  multidimen¬ 
sional  arrays  using  nested  DO  loops, 
and  generates  a  grand  total  via  sum 
reduction.  The  nested  loops  allow  me 
to  examine  alternative  parallelization 
strategies.  The  grand  total  number  serves 
as  a  behavior  reference  for  different 
cases. 

Three  cases  were  tested:  A  purely 
scalar  case  (SCA),  an  inner  loops  paral¬ 
lelized  case  (IN),  and  an  outer  loop 
parallelized  case  (OUT).  To  test  each  of 
the  cases,  the  appropriate  *  comments 
were  removed  in  order  to  unmask  the 
desired  compiler  directives. 

Each  program  was  compiled  at  opti- 


Example  4:  Load  balancing 


mization  level  2.  This  level  is  primarily 
loop  optimization,  and  currently  is  the 
maximum  level  of  optimization  that  is 
permitted  for  the  -mp  option.  I  have 
found  that  programs  compiled  at  opti¬ 
mization  level  1  typically  perform  about 
40  percent  slower  than  programs  that 
are  compiled  at  level  2,  making  it  es¬ 
sential  to  compile  at  the  higher  optimi¬ 
zation  level. 

Both  a  two-headed  4D/120s  system 
and  a  four-headed  4D/240s  system  were 
evaluated.  The  various  configurations 
are  listed  in  Table  1.  Instead  of  listing 
aggregate  power,  I  prefer  to  list  the 
power  per  processor.  This  gives  an  hon¬ 
est  view  of  these  machines  and  reflects 
nominal  scalar  performance.  The  pro¬ 
cessing  power  is  relative  to  the  old 
standard  of  scientific  computing  —  the 
VAX  1 1/780  —  as  being  1  mips  by  defi¬ 
nition.  These  13  and  20  mips  numbers 
are  real! 

I  have  broken  down  the  timing  re¬ 
sults  into  the  categories  of  User,  Sys¬ 
tem,  and  Total  (wall  clock).  The  times 
were  determined  by  using  the  Unix 
time  utility,  and  were  determined  on 
machines  free  of  competing  tasks.  The 
speedup  is  relative  to  scalar,  and  re¬ 
flects  the  number  of  processors  that 
contribute  to  the  job.  The  times  be¬ 
tween  the  two-processor  and  four-pro¬ 
cessor  systems  are  not  comparable  be¬ 
cause  the  CPU  and  clock  rates  are  very 
different  for  each  system. 

All  versions  of  TEST.F  are  well-be¬ 
haved.  Each  version  returns  a  value  of 
0.518e+8  for  the  grand  total,  which  in- 


do  i  =  1,  n 

do  j  =  1,  i 

a(j,  i)  =  a(j,  i)  *  xmult 

enddo 

enddo 

Example  3'-  An  example  of  load 
imbalance 


num_threads  =  mp_numthreads () 
c$doacros.s  local (i,  j,  k) 

do  k  =  1,  num_threads 

do  i  =  k,  n,  num_threads 
do  j  =  1,  i 

a ( j ,  i)  =  a(j,  i)  *  xmult 

enddo 

enddo 

enddo 


model 

4D/120S 

4D/240S 

processors 

2 

4 

processor 

MIPS  R2000 

MIPS  R3000 

clock  speed  (MHz) 

16 

25 

processing  power  (mips) 

2x13 

4x20 

FPU 

2xR2010 

4xR3010 

Mflops  (double  precision) 

2x1.5 

4x3.0 

data  cache  (Kbytes/processor) 

64 

64 

ram  (Mbytes,  nonstandard) 

32 

64 

Table  1:  Platforms 
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(continued  from  page  80) 
dicates  correct  operation  under  both 
scalar  and  parallel  modes.  The  value  of 
ITEST  that  is  typically  returned  is  ran¬ 
dom,  and  ranges  between  0  and  5  (ex¬ 
cept  in  the  IN  case,  when  it  returns  an 
enormous  integer  value  that  reflects 
the  increased  cycling  time  being  meas¬ 
ured,  as  it  should).  The  random  nature 
of  the  value  of  ITEST,  which  is  declared 
as  type  LASTLOCAL,  suggests  that  cau¬ 
tion  must  be  used  in  the  interpretation 
and  use  of  LASTLOCAL  values. 

The  speedup,  as  shcrwn  in  Tables  2 
and  3,  is  impressive.  In  both  processor 
tests,  the  difference  between  the  IN 
and  OUT  tests  likely  reflects  load  bal¬ 
ancing,  but  is  small,  regardless.  This 
suggests  that  parallelizationof  the  most 
time-dependent  code,  rather  than  of 
the  largest  quantity  of  most  code,  is  the 
real  issue.  Outer  loops  that  enclose 
much-varied  code  can  be  far  more  dif¬ 
ficult  to  parallelize  than  inner  loops, 
due  to  the  occurence  of  data  depen¬ 
dency.  The  difference  between  IN  and 
OUT  suggests  that  no  significant  per¬ 
formance  penalty  may  exist  if  time- 
dependent  inner  loops  are  preferen¬ 
tially  parallelized.  The  results  also  sug¬ 
gest  that  no  generalization  is  safe,  and 
that  a  variety  of  coding  possibilities 
should  be  examined. 

Cache  Tests 

While  experimenting  with  TEST.F,  I  un¬ 
covered  a  performance  issue  that  is 
apparently  uncommon  to  programming 
on  PC-class  machines:  Data  cache  man¬ 
agement.  Although  the  issue  of  data 
cache  management  is  common  to  both 
scalar  and  parallel  programming  envi¬ 
ronments,  the  observed  effects  of  mis¬ 
management  of  the  cache,  and  their 
cure,  are  important  enough  to  high¬ 
light  separately  because  they  affect  per¬ 
formance.  The  cure  is  the  proper  use 
of  array  indexing. 


Intentional  cache  mismanagement 
leads  to  significant  performance  degra¬ 
dation.  Management  in  this  context  con¬ 
sists  of  the  maximization  of  the  use  of 
existing  data  in  the  cache,  and  the  mini¬ 
mization  of  data  movement  into  the 
cache  from  regular  memory.  The  amount 
of  the  reuse  of  existing  cache  data  is 
commonly  referred  to  as  the  “hit  rate”. 
Better  performance  is  obtained  from 
optimizing  the  hit  rate. 

In  practical  terms,  the  hit  rate  can 
be  increased  by  addressing  memory 
contiguously.  Memoiy  references  of  this 
sort  typically  consist  of  array  variables 
in  which  contiguous  blocks  of  values 
can  be  moved  into  the  cache  with  less 
overhead  than  is  required  in  order 
to  move  single  values  into  the  cache 
multiple  times.  Keep  in  mind  that 
in  Fortran,  multidimensional  arrays 
are  stored  in  column  order;  the  left¬ 
most  index  represents  contiguous  mem¬ 
ory  addresses.  Therefore,  nested  DO 
loops  must  vary  the  leftmost  index  of 
a  two-dimensional  array  fastest,  so  the 
references  are  to  contiguous  memory 
locations. 

Cache  mismanagement  was  tested 
by  reversing  the  array  index  variables, 
and  by  reversing  the  array  size  declara¬ 
tions.  The  array  sizes  guarantee  that 
the  arrays  cannot  be  wholly  contained 
in  the  cache  and  that  the  movement  of 
data  into  the  cache  is  handled  via  the 
movement  of  individual  array  elements. 

The  reason  why  cache  management 
is  a  concern  is  shown  in  Table  4.  Note 
that  the  speedup  for  parallelization  is 
less,  due  to  increased  system  overhead, 
while  the  slowdown  relative  to  the 
speed  observed  for  proper  array  index¬ 
ing  is  substantial.  This  translates  to  an 
additional  day  added  to  the  time  re¬ 
quired  to  perform  a  three-day  simula¬ 
tion,  which  is  a  significant  penalty.  The 
effects  of  cache  mismanagement  may 
be  inconsequential  for  tasks  that  have 


case 

user 

sys 

total 

speedup 

SCA 

40.4 

2.1 

42.5 

1.00 

IN 

21.0 

0.8 

21.8 

1.95 

OUT 

21.8 

1.0 

22.8 

1.86 

Table  2:  Two-processor  results  (sec.) 


case 

user 

sys 

total 

speedup 

SCA 

25.6 

1.0 

26.6 

1.00 

IN 

7.1 

0.2 

7.3 

3.64 

OUT 

6.4 

0.5 

6.9 

3.86 

Table  3:  Four-processor  results  (sec.) 


case 

user 

sys 

total 

speedup 

slowdown 

SCA 

45.7 

6.9 

52.6 

1.00 

1.24 

OUT 

22.8 

7.0 

29.7 

1.77 

1.31 

Table  4:  Two-processor  reversed-array  indexing  (sec.) 
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small  memory  requirements.  In  the  case 
of  large  memory  requirements,  the  pen¬ 
alty  for  improper  use  of  the  cache  can 
be  considerable. 

Conclusion 

Will  the  application  of  these  tools  to 
real  programs  translate  to  significant 
performance  gains,  as  shown  by  TEST.F? 
This  will  very  likely  depend  upon  the 
individual  program.  In  the  case  of  one 
program  that  is  important  to  my  own 
work,  I  have  created  significant  speed 
enhancements  by  the  parallelization  of 
key  routines  found  by  profiling.  An 
additional  increase  in  speed  is  also  pos¬ 
sible  by  paying  attention  to  load  bal¬ 
ancing  and  cache  management. 

Number  crunching  has  never  been 
cheap.  Not  everyone  has  access  to  a 
supercomputer,  and  not  every  prob¬ 
lem  can  justify  the  cost.  Al  Cameron, 
who  writes  the  “Engineering/Science” 
column  for  MIPS  magazine,  advocates 
the  use  of  workstations  dedicated  to 
running  one  problem  around  the  clock 
for  long  periods  of  time  as  a  low-cost 
alternative  to  supercomputing.  I  share 
his  opinion,  but  this  solution  is  clearly 
acceptable  only  if  you  can  afford  to 
wait.  Machines  such  as  the  Power  Se¬ 
ries  from  Silicon  Graphics  provide  the 
raw  power  needed  for  numerically  in¬ 
tensive  computing,  plus  the  software 
tools  needed  to  extract  that  power.  With 
properly  parallelized  programs,  the  wait 
is  considerably  shorter. 
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DATA-FLOW  MULTITASKING 


Listing  One  (Text  begins  on  page  16.) 

/*  quad  eq.c  - 

(  /*  Calculate  numerator  *7 

while  (y(indexl).a  !=  0.0) 

*  Calculate  roots  of  quadratic  equation:  ax  +  bx  +  c  =  0 
*/ 

while  ((det  ==  0.0)  !!  (num  !=  0.0))  rq$sleep{0, Astatus) ? 
index2++; 

♦include  "stdio.h" 

♦include  "rmx.h" 

num  =  pow(det,  0.5)  -  y[indexl).b; 
det  =  0.0; 

♦include  "raath.h" 

rq$delete$task (0, Astatus) ;  /*  Delete  self  */ 

♦define  NUM_VALS  100 

' 

unsigned  status? 

struct  coeffs  (double  a,  b,  c; 1  y[NUM  VALS+1]; 

double  det; 
double  num; 

while  (y(index2].a  !=  0.0) 

double  res; 

while  (num  ==  0.0)  rqSsleep (0, Astatus) ; 

/*  Calculate  determinant  */ 

res  =  num  /  (2  *  y [index2] .a) ; 

determinant (i) 

printf ("Coeffs  =  % . If , % . If , % . If  Root  =  %7.2f\n", 

y[index2].a,  y[index2].b,  y[index2].c,  res); 

det  =  y[i].b  *  y[i].b  -  4  *  y(i) .a  *  y[i].c; 

) 

) 

printf ("\n") ; 

rq$delete$task (0, Astatus) ;  /*  Delete  self  */ 

/*  Calculate  numerator  */ 

) 

numerator (i) 
unsigned  i; 

/******************************  Main  program  ******************************/ 

( 

num  =  pow(det,0.5)  -  y[i].b? 

main  () 

{ 

unsigned  i; 

/*  Calculate,  print  result  */ 

unsigned  short  pri; 

result  (i) 
unsigned  i; 

( 

/*  Create  input  data.  Done  for  convenience.  Could  have  read  the  data 
*  from  any  input  device. 

res  =  num  /  (2  *  y(i].a); 

*/ 

printf  ("Coeffs  =  %.  If ,  % .  If,  % .  If  Root  =  %7.2f\n", 

for  (i  =  1;  i  <  NUM  VALS;  i++) 

y[i] • a , y [ i J . b, y ( i J .c, res) ; 

(y[i].a  =  (double) i;  y[i].c  =  (double) i;  y[i].b  =  3* (double) i; ) 

main  () 

( 

y [ NUM_VALS ] . a  =  0.0;  /*  0.0  indicates  end  of  input  data  */ 

/*  Place  a  pointer  to  any  variable  in  union  "ptr  u",  so  the  data  segment 

unsigned  i; 

of  this  program  becomes  known. 

/*  Create  input  data.  Done  for  convenience.  Could  have  read  the  data 

*/ 

*  from  any  input  device. 

ptr_u. pointer  =  Astatus; 

for  (i  =  1;  i  <  NUM  VALS;  i++) 

/*  Find  the  priority  level  that  iRMX  accords  the  main  task  */ 

(y[i].a  =  (double)i;  y[i].c  =  (double)i;  y[i].b  =  3* (double) i; ) 

pri  =  rq$get$priority  (NULL,  Astatus); 

/*  Compute  the  roots  */ 

/* 

*  Spawn  the  operation  tasks.  All  have  the  same  priority  as  main. 

for  (i  -  1;  i  <  NUM  VALS;  i++) 

*/ 

( 

task  t  =  rq$create$task  (pri,  (long)det  task,  ptr  u. ptr. sel, 

determinant (i) ; 

0L,  1024,  1,  Astatus); 

numerator (i) ; 

if  (status  !=  0)  printf ("det  task  create  error  =  %u\n", status) ; 

result  (i) ? 

1 

task  t  =  rq$create$task  (pri,  (lonq)num  task,  ptr  u. ptr. sel, 

printf ("\n") ; 

0L,  1024,  1,  Astatus); 

1  End  Listing  One 

if  (status  ! =  0)  printf ("num_task  create  error  =  %u\n", status) ; 

task  t  =  rq$create$task  (pri,  (long) res  task,  ptr  u. ptr. sel, 

Listing  Two 

0L,  1024,  1,  Astatus); 

if  (status  ! =  0)  printf ("res  task  create  error  =  %u\n", status) ; 

/**********************,*******.**************,********.****,********, **...**\ 

*  dflow.c  - 

/* 

*  Compute  the  roots  of  a  quadratic  equation  using  multitasking 

*  Lower  main  task's  priority  so  main()  will  be  idled  by  OS  while  other 

*  and  data  flow  concepts. 

*  tasks  do  computations.  Will  return  here  when  input  data  is  exhausted. 

*  Operating  System:  iRMX  II.  Compiler:  iC-286  V3.2 

*/ 

\************************************* ************  *********************** **»*/ 

rq$set$priority  (NULL,  (pri+1),  Astatus); 

♦include  "stdio.h" 

♦include  "rmx.h" 

. . . 

♦include  "math.h" 

rq$sleep(10,  Astatus);  /*  Let  other  tasks  complete  */ 

printf ("\n  Done!  \n”); 

♦define  NUM_VALS  100 

} 

unsigned  status,  task  t; 

FILE  *fp; 

End  Listing  Two 

/*  "union"  used  to  decompose  a  pointer  into  segment : offset  */ 
typedef  struct  (unsigned  offset;  unsigned  sel; )  ptr  s; 
union  (  unsigned  ‘pointer;  ptr  s  ptr;  )  ptr  u; 

Listing  Three 

/* 

*  This  code  is  similar  to  "res  task()"  in  dflow.c,  except 

/*  Input  data  area  */ 

struct  coeffs  (double  a,  b,  c; )  y [NUM  VALS+1); 

*  that  the  computed  result  is  output  to  a  file  instead  of  the  (default) 

*  console  screen. 

/*  hDETm  mailbox  - 

*  This  code  could  be  added  to  dflow.c  along  with  two  statements  in 

*  Output  from  main  task;  input  to  num  task 

*  main()  to:  1.  create  a  "res  task2()"  task,  and  2.  open  a  file  for 

*/ 

*  output  with  fp  as  its  file  pointer.  By  so  doing,  the  I/O  delay  involved 

double  det  =  0.0; 

*  in  waiting  for  console  output  could  be  overlapped  with  file  output  delays, 

unsigned  indexl  =  0; 

*  thus  speeding  up  the  program.  Of  course,  the  results  would  then  be 

*  distributed  between  the  console  and  the  output  file. 

/*  "NUM"  mailbox  - 

*/ 

*  Output  from  num  task;  input  to  res  task 

*/ 

res  task2() 

double  num  =  0.0; 

(  /*  Calculate  result,  print  to  file  */ 

unsigned  index2  =0; 

double  res; 

/A***********************  Computational  tasks  *************************/ 

while  (y[index2].a  !=  0.0) 

det  task() 

while  (num  ==  0.0)  rqSsleep (0, Astatus) ; 

{  /*  Calculate  determinant  */ 

res  =  num  /  (2  *  y [index2] .a) ; 

unsigned  i; 

num  =  0.0; 

for  (i  =  1;  y[i].a  !=  0.0;  i++) 

fprintf (fp,  "Coeffs  =  % . If , % . If , % . If  root  =  %7.2f\n", 

( 

y[index2].a,  y[index2].b,  y[index2].c,  res); 

while  (det  !=  0.0)  rq$sleep (0, &status) ; 
indexl ++? 

det  =  y[i].b  *  y[i].b  -  4  *  y[i].a  *  y [i] .c; 

} 

) 

num  task  () 

) 

rq$delete$task (0, Astatus) ;  /*  Delete  self  */ 

) 

End  Listings 
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PARALLEL  MAKE 


Listing  One  (Text  begins  on  page  28.) 

/* - 

*  DVMAKE,  adapted  by  Mark  Streich 

*  Original  Mk  by  Allen  Holub,  Doctor  Dobb's  Journal,  August  1985 

*  Some  functions  may  be  specific  to  Borland  Int'l.  Turbo  C  2.0. 

*  DESQview  2.01  (or  later),  and  API  C  Library  required. 

*  Compile  with  byte  alignment  ON. 

*  Run  from  within  a  non-swappable  DOS  window  with  at  least  64K 

*  of  memory,  15K  of  system  memory,  runs  in  the  background  and 

*  shares  the  cpu  when  in  the  foreground.  On  non-386  systems, 

*  you  will  have  to  say  that  it  does  not  write  directly  to  the  screen. 
*/ 


♦include  <stdio.h>  /*  forprintfO,  sprintfO,  etc.  */ 
♦include  <io.h>  /*  for  open(),  close (),  getftimeO  */ 
♦include  <fcntl.h>  /*  for  0_RD0NLY  used  in  open()  */ 
♦include  <string.h>  /*  for  various  string  functions  */ 
♦include  <stdarg.h>  /*  for  variable  argument  err{)  */ 
♦include  "dvapi.h"  /*  provided  by  DESQview  API  */ 

/* - DEFINES - */ 

♦define  MAXLINE  127  /*  Maximum  DOS  command  line  length  */ 
♦define  MAXBLOCK  16  /*  Max  number  of  lines  in  an  action  */ 
♦define  MAXDEP  32  /*  Max  number  of  dependencies  */ 
♦define  MAXFNM  64  /*  Max  length  of  file  name/dir  */ 
♦define  COMMENT  /*  Delimits  a  comment  */ 
♦define  MAKEFILE  "mkfile"  /*  Name  of  makefile  */ 
♦define  OLDTIME  0x0  /*  the  Beginning  of  Time  (very  old)  */ 
♦define  NEWTIME  OxFFFFFFFFL  /*  the  End  of  Time  (very  young)  */ 

♦define  DV_VER  0x201  /*  DESQview  version  required:  2.01  */ 
♦define  STKSIZE  512  /*  size  of  tasks'  local  stack  */ 
♦define  NORMAL  0  /*  normal  status  state  */ 
♦define  ACCESSDV  1  /*  access  DESQview,  so  no  new  tasks  */ 
♦define  ABORT  2  /*  kill  of  all  processes  */ 


/* - 

*  iswhite(c) 

*  skipwhite(s) 

*  skipnonwhite (s) 

*  waitwhile (event) 
*/ 


evaluates  true  if  c  is  white  space. 

skips  the  character  pointer  s  past  any  white  space. 

skips  s  past  any  non-white  characters. 

gives  up  task's  time  slice  while  event  is  true. 


♦define  iswhite(c)  ((c)=='  '  !!  (c) — =' \t ' ) 

♦define  skipwhite(s)  while (  iswhite(*s)  )  ++s; 
♦define  skipnonwhite (s)  while!  *s  &&  !iswhite(*s)  )  ++s; 
♦define  waitwhile (event)  while(  event  )  api_pause(); 


/* -  TYPEDEFS  - 

*  The  entire  mkfile  is  read  into  memory  before  it's  processed.  It's 

*  stored  in  a  binary  tree  composed  of  the  following  structures: 

*  depends_on  and  do_this  are  argv-like  arrays  of  pointers  to  character 

*  pointers.  The  arrays  are  null  terminated  so  no  count  is  required. 

*  The  time  field  is  a  32  bit  ulong  consisting  of  the  date  and  time 

*  fields  returned  from  DOS.  The  date  and  time  are  concatanated  with 

*  the  date  in  the  most  significant  bits  and  the  time  in  the  least 

*  significant.  This  way  they  can  be  compared  as  a  single  number. 

*/ 


typedef  struct 

i 

_tn 

/*  node  for  dependencies  */ 

struct  _tn 

* Inode ; 

/*  pointer  to  left  sub-tree 

*/ 

struct  _tn 

*rnode; 

/*  pointer  to  right  sub-tree 

*/ 

char 

*being_made; 

/*  name  of  file  being  made 

*/ 

char 

**depends_on; 

/*  names  of  dependent  files 

V 

char 

**do_this; 

/*  Actions  to  be  done  to  make  file 

*/ 

ulong 

time; 

/*  time  &  date  last  modified 

*/ 

ulong 

apphan; 

/*  what  app  is  making  this  item 

*/ 

char 

made; 

/*  flag  indicating  made  or  not 

*/ 

int 

tsknum; 

/*  what  task  number  was  assigned 

*/ 

} 

TNODE; 


typedef  struct  _qn 
( 

/*  queue  of  items  */ 

void  ‘item; 

struct  qn  ‘next; 

/*  item  in  queue  *. 

/*  next  item  in  the  queue  *, 

QNODE; 

typedef  struct  /*  definition  of  Program  Information  File  (PIF)  */ 


byte  control_byte2; 


char  open_keys [2] ; 
uint  script_size; 
uint  auto_pause; 

byte  color_mapping; 
byte  swappable; 
char  reserved2 [ 3 ] ; 
byte  auto_close; 
byte  disk_reqd; 
byte  reserved3; 
byte  shared_mem; 
byte  physical_rows; 
byte  physical_cols; 
uint  max_expanded_mem; 
byte  control_byte3; 


byte  key_conflict; 
byte  graphics_pages; 
uint  system_mem2; 
byte  initjnode; 
char  reserved4 [22] ; 


/*  control  byte  2,  encoded  as  follows: 

40H  -  uses  command  line  parameters 
20H  -  swaps  interrupt  vectors  */ 

/*  keys  to  use  for  Open  Window  menu  */ 

/*  size  of  script  buffer  in  bytes  */ 

/*  pause  after  this  many  tests  for  input 
during  one  clock  tick  (normally  0)  */ 

/*  non-zero  to  disable  auto  color  mapping  */ 

/*  non-zero  if  application  is  swappable  */ 

/*  should  be  zero  */ 

/*  non-zero  to  automatically  close  on  exit  */ 

/*  non-zero  if  diskette  required  */ 

/*  MUST  HAVE  VALUE  OF  1  */ 

/*  non-zero  if  program  uses  shared  system  mem*/ 
/*  initial  size  of  physical  window  */ 

/*  max  amount  of  expanded  mem  avail  to  app  */ 

/*  control  byte  3,  encoded  as  follows: 

80H  -  automatically  assigns  position 
20H  -  honor  maximum  memory  value 
10H  -  disallow  Close  command 
08H  -  foreground-only  when  in  graphics 
04H  -  don't  virtualize  */ 

/*  keyboard  conflict  (0-4,  usually  0)  */ 

/*  ♦  graphics  pages  used  */ 

/*  system  memory  -  overrides  system_mem  */ 

/*  initial  screen  mode,  normally  0FFH  */ 


)  PIF;  /*  note  that  the  sizeof(PIF)  MUST  be  416,  or  else  we've  made  a  typo  */ 


/■ 


GLOBAL  VARIABLES 


static 

TNODE 

‘Root  =  NULL; 

/* 

Root  of  file-name  tree 

*/ 

static 

FILE 

‘Makefile; 

/* 

Pointer  to  opened  makefile 

*/ 

static 

int 

Inputline  =  1; 

/* 

current  input  line  number 

*/ 

static 

char 

‘First  =  NULL; 

/* 

Default  file  to  make 

*/ 

static 

char 

ShowWin  =  0; 

/* 

Display  tasks? 

*/ 

static 

char 

Parallel  =  0; 

/* 

Are  we  multitasking  yet? 

*/ 

static 

char 

Status  =  NORMAL 

/* 

processing  status 

*/ 

static 

char 

CurDir [MAXFNM] ; 

/* 

Directory  called  from 

*/ 

static 

char 

Error [MAXLINE]  =  " 

;  /* 

Error  saved  for  later  printing 

static 

int 

RunCnt  =  0; 

/* 

how  many  tasks  running 

*/ 

static 

int 

MemSize  =  256; 

/* 

default  task  memory  size 

*/ 

static 

int 

ReDirLen  =  0; 

/* 

length  of  redirection  file 

*/ 

static 

QNODE 

•MkQueue  =  NULL; 

/* 

queue  of  items  to  make 

*/ 

static 

QNODE 

•TskQueue  =  NULL; 

/* 

queue  of  tasks  to  run 

*/ 

static 

QNODE 

‘OutQueue  =  NULL; 

/* 

queue  of  files  to  output 

*/ 

static 

ulong 

TskQueueLock; 

/‘ 

semaphore  for  TskQueue 

*/ 

static 

ulong 

OutQueueLock; 

/* 

semaphore  for  OutQueue 

*/ 

static 

ulong 

AiiocLock; 

/* 

semaphore  for  malloc/free 

*/ 

static 

ulong 

Ma inWin; 

/* 

handle  of  Main  Window 

*/ 

static 

ulong 

MenuTsk; 

/* 

handle  of  Menu  Task 

*/ 

static 

ulong 

MakeTsk; 

/* 

handle  of  Make  Task 

*/ 

static 

PIF 

Pif; 

/* 

default  Prog  Info  File 

*/ 

static 

int 

Lpif ; 

/* 

length  of  the  PIF 

*/ 

void  err(  char 

*msg,  ...  ) 

/*  print  the  message  and  optional  parameter  and  either 

*  step  immediately  if  we  haven't  started  up  parallel  tasks, 

*  or  just  set  our  status  to  ABORT  and  stop  later 

V 


static  char  temp [MAXLINE] ; 
va_list  argptr; 

/*  Print  the  error  message,  if  we  haven't  already,  and  abort  */ 
if  (! strlen (Error) ) 

( 

/*  print  the  location  of  the  error  in  the  mkfile  */ 
sprintf (Error, "Mk  ( % s  line  %d) :  ",  MAKEFILE,  Inputline  ); 
va_start (argptr, msg) ; 

vsprintf (temp, msg, argptr) ;  /*  print  the  error  message  */ 

va_end (argptr) ; 

streat (Error, temp) ;  /*  and  concatenate  the  two  */ 

) 

if  (Parallel)  /*  are  we  multitasking?  */ 

( 

/*  notify  everyone  that  there  are  problems,  but  don't  stop  yet  */ 
api_beginc () ; 

Status  =  ABORT; 
api_endc ( ) ; 

) 

else  /*  net  multitasking,  so  we  can  STOP  */ 


char  reservedl [2 ] ; 
char  prog_title [30] ; 
uint  maxmem; 
uint  minmem; 
char  program [64]; 
char  def_drive; 
char  def_dir[64]; 
char  params [64] ; 
byte  init_screen; 
byte  text_pages; 
byte  first_intr; 
byte  last_intr; 
byte  logical_rows; 
byte  logical_cols; 
byte  init_row; 
byte  init_col; 
uint  system_mem; 
char  shared  prog [ 64 ] ; 
char  shared_data [64] ; 
byte  control_bytel; 


/*  blank  filled  */ 

/*  max  memory  size  in  k-bytes  */ 

/*  command  to  start  program,  0-terminated  */ 
/*  'A',  'B',  ...,  or  blank  */ 

/*  default  directory,  0-terminated  */ 

/*  parameters,  0-terminated  */ 

/*  screen  mode  (0-7)  */ 

/*  ♦  of  text  pages  used  */ 

/*  #  of  first  interrupt  vector  to  save  */ 

/*  ♦  of  last  interrupt  */ 

/*  logical  size  of  window  buffer  */ 

/*  initial  row  to  display  window  */ 

/*  system  memory  in  k-bytes  */ 

/*  shared  program  file  name,  0-terminated  */ 
/*  shared  program  data,  0-terminated  */ 

/*  control  byte  1,  encoded  as  follows: 

80H  -  writes  direct  to  screen 

4 OH  -  foreground  only 

2 OH  -  uses  math  coprocessor 

10H  -  accesses  system  keyboard  buffer 

01H  -  swappable  */ 


fprintf (stderr, "%s", Error) ; 
mal_f ree (TskQueueLock) ; 
mal_free (OutQueueLock) ; 
mal_free (AiiocLock) ; 

apiexit () ; 
exit  (1) ; 


/*  print  the  error  message  */ 

/*  get  rid  of  our  semaphores  */ 


/*  tell  DESQview  we're  done  */ 
/*  and  STOP  */ 


/* -  MEMORY  ROUTINES  - */ 

void  *gmem(  int  numbytes  ) 

( 

/*  Get  numbytes  from  malloc.  Print  an  error  message  and 

*  abort  if  malloc  fails,  otherwise  return  a  pointer  to 

*  the  memory.  Uses  semaphores  because  malloc ()  not  re-entrant. 
*/ 

void  *p; 

extern  void  *malloc(); 


(continued  on  page  92) 
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PARALLEL  MAKE 


Listing  One  (Listing  continued,  text  begins  on  page  28.) 


) 


mal_lock (AllocLock) ; 
p  =  malloc (numbytes) ; 
mal_unlock (AllocLock) ; 

if  (p  ==  NULL) 

err ("Out  of  memory"); 

return (  p  ) ; 


/*  get  access  to  heap  */ 
/*  grab  some  memory  */ 
/*  free  access  to  heap  */ 

/*  were  we  successful  */ 


void  fmem(  void  *ptr  ) 

I 

/*  Frees  memory  pointed  to  by  ptr.  */ 
extern  void  free(); 

mal_lock (AllocLock) ;  /*  get  access  to  heap  */ 

if  (ptr)  free (ptr);  /*  free  the  memory  if  ptr  not  NULL  */ 

mal_unlock (AllocLock) ;  /*  free  access  to  heap  */ 


QUEUE  ROUTINES 


/*  add  item  to  the  queue  */ 


void  enqueue (QNODE  **queue,void  ‘item) 

{ 

QNODE  ‘qptr; 

/*  get  memory  for  new  node  */ 

if  (  (qptr  =  (QNODE  *)  gmem(sizeof (QNODE) ) )  ==  NULL  ) 
err ("Out  of  memory”); 

else 

( 

qptr->item  =  item;  /*  add  the  item  */ 

qptr->next  =  ‘queue;  /*  point  to  the  next  item  in  the  queue,  if  any* 
‘queue  =  qptr;  /*  point  to  the  new  front  of  the  queue  */ 

} 

) 

void  ‘dequeue (QNODE  “queue)  /*  return  an  item  from  the  queue  */ 

{ 

QNODE  ‘qptr,  *qptr2  -  NULL; 
void  ‘iptr; 


if  (‘queue  ==  NULL) 
return (  NULL  ) ; 

else 


/*  is  the  queue  empty? 


/*  find  the  end  of  the  queue  */ 

for  (qptr  *  ‘queue;  qptr->next  !=  NULL;  qptr  =  qptr->next) 

qptr2  =  qptr;  /*  qptr2  points  to  qptr's  predecessor  */ 


iptr  =  qptr->item; 


/*  get  the  item  to  return  */ 

/*  remove  the  last  item  from  the  queue  */ 


f mem (  qpt  r  ) ; 
if  (qptr2  ! =  NULL) 

qptr2->next  =  NULL; 

else 

‘queue  =  NULL;  /*  nothing  left  in  queue  */ 


return (  iptr  ); 


/*  return  a  pointer  to  the  item  removed  »/ 


int  inMkQueue (char  *being_made) 


/*  see  if  "being_made"  item  is  already  in  the  MkQueue  */ 

QNODE  ‘qptr; 

if  (MkQueue  !=  NULL)  /*  is  the  queue  empty?  */ 

for  (qptr  =  MkQueue;  qptr  !=  NULL;  qptr  =  qptr->next) 

if  (strcmp ( ( (TNODE  *) qptr->item) ->beingjnade, being  jnade)  ==  0) 
return(l);  /*  being_made  is  in  the  queue  */ 


return (  0  ) ; 


/*  MkQueue  is  empty  or  beingjnade  not  in  it  */ 


} 

/* - INITIALIZE  PIF - */ 

void  init_pif(PIF  *pif,int  *lenpif,char  ‘title, int  rows, int  cols) 

/*  Initialize  the  Program  Information  File  to  start  the  new  application. 
*  By  default  it  is  just  a  non-swappable  dos  window  with  256K. 


‘lenpif  =  sizeof(PIF); 

/*  set  defaults  now,  and  particulars  later  */ 
memset (pif->reservedl,  0,2) ; 

memset (pif->prog_title, '  ',30);  /*  blank  filled  »/ 
strncpy (pif->prog_title, title,  strlen (title) )  ; 


pif->maxmem  =  MemSize; 
pif->minmem  =  MemSize; 
strcpy (pif->program, "") ; 
pif->def_drive  =  CurDir [0]; 
strcpy (pif->def_dir,CurDir+2) ; 
strcpy (pif->params, "") ; 
pif->init_screen  =  0x7F; 
pif->text_pages  =  1; 
pif->first_intr  =  0; 
pif->last_intr  =  255; 
pif->logical_rows  =  rows; 
pif->logical_cols  =  cols; 
pif->init_row  =  0; 
pif->init_col  =  0; 
pif->system_mem  =  0; 
pif->shared_prog[0)  =  0; 
pif->shared_data (0]  =  0; 
pif->control_bytel  =  0x20; 


/*  memory  required  for  app  in  k-bytes  */ 

/*  command  to  start  program,  0-terminated*/ 
/*  '  ',  'A',  'B\  ...  */ 

/*  default  directory,  0-terminated  */ 

/*  parameters,  0-terminated  */ 

/*  screen  mode  (0-7)  (??)  */ 

/*  #  of  text  pages  used  */ 

/*  #  of  first  interrupt  vector  to  save  */ 

/*  #  of  last  interrupt  */ 

/*  logical  size  of  window  buffer  */ 

/*  initial  row  to  display  window  */ 

/*  system  memory  in  k-bytes  */ 

/*  shared  program  file  name,  0-terminated*/ 
/*  shared  program  data,  0-terminated  */ 

/*  control  byte  1,  encoded  as  follows: 

80H  -  writes  direct  to  screen 

40H  -  foreground  onlay 

20H  -  uses  math  coprocessor 


pif->control_byte2  =  0x40(0x20;  /’ 


memset (pif->open_keys, '  ',2);  /’ 
pif->script_size  =  256;  /’ 
pif->auto_pause  =  0;  /’ 

pif->color_mapping  =0;  /' 
pif->swappable  =0;  /’ 
memset (pif->reserved2, 0, 3) ;  /' 
pif->auto_close  =0;  /’ 
pif->disk_reqd  =  0;  /’ 
pif->reserved3  =1;  /’ 
pif->shared_mem  =0;  /' 
pif->physical_rows  =0;  /’ 
pif->physical_cols  =  0;  / 1 
pif->max_expanded_mem  =  65535u;  /’ 
pif->control_byte3  =  0x80(0x10;  /’ 


pif->key_conflict  =  0;  /’ 
pif->graphics_pages  =0;  /’ 
pif->system_mem2  =0;  /’ 
pif-oinitjnode  =  OxFF;  /’ 
memset (pif->reserved4, 0, 22) ; 


10H  -  accesses  system  keyboard  buffer 
01H  -  swappable  */ 
control  byte  2,  encoded  as  follows: 

40H  -  uses  command  line  parameters 
20H  -  swaps  interrupt  vectors  */ 
keys  to  use  for  Open  Window  menu  */ 
size  of  script  buffer  in  bytes  */ 
pause  after  this  many  tests  for  input 
during  one  clock  tick  (normally  0)  */ 
non-zero  to  disable  color  mapping  */ 
non-zero  if  application  is  swappable  */ 
should  be  zero  */ 

non-zero  to  close  on  program  exit  */ 
non-zero  if  diskette  required  */ 

MUST  HAVE  VALUE  OF  1  */ 

non-zero  if  prog  uses  shared  memory  */ 

initial  size  of  physical  window  */ 

0's  allow  DV  to  set  */ 
max  amt  of  expanded  mem  avail  to  app  */ 
control  byte  3,  encoded  as  follows: 

80H  -  automatically  assigns  position 
20H  -  honor  maximum  memory  value 
10H  -  disallow  Close  command 
08H  -  foreground-only  when  in  graphics 
04H  -  don't  virtualize  */ 
keyboard  conflict  (0-4,  usually  0)  */ 

#  graphics  pages  used  */ 

system  memory  -  overrides  systemjnem  */ 

initial  screen  mode,  normally  0FFH  */ 


GENERATE  TEMP  FILE  NAME  ■ 


char  *gen_name (int  tsknum, int  cmdnum) 

{ 

/*  Generate  a  new  output  file  name,  d: \dir\DVMKxxyy. $$$,  where 
d:\dir\  is  the  directory  in  which  the  "dvmake"  was  started, 
xx  =  task  number,  and  yy  =  command  number  (both  in  hex) . 
Returns  a  pointer  to  the  newly  allocated  file  name. 


char  *new_name; 
char  tsk_cmd(5J; 


generated  name  */ 
task/command  number  string  */ 


if  (  (new_name  =  (char  *)  gmem (MAXFNM) ) 
err ("Out  of  memory"); 

else 

I 

strcpy (new_name,CurDir) ; 


/*  directory  name  */ 


if  (CurDir [strlen (CurDir) -1) 
strcat(new  name,"\\"); 
strcat (new_name, "DVMK" ) ; 


!=  'W') 

/*  add  backslash  to  dir  */ 

/*  first  4  chars  of  name  */ 


sprintf (tsk_cmd, "%02x%02x", tsknum, cmdnum) ; 

strcat (new_name, tsk_cmdl ;  /*  last  4  chars  of  name  */ 


strcat (newjiame, ".$$$"); 

1 

return (  new  name  ) ; 


/*  add  an  extension  */ 


int  dvmenu (  void  ) 


display  a  menu  to  control  the  status  of  the  make,  and  don't 
quit  until  someone  wakes  me  up  with  tsk_post (MenuTsk) 


ulong  kbd,win;  /* 
ulong  whichobj;  /* 
char  *kbuf;  /* 
int  klen,  /* 

state;  /* 


handles  for  keyboard,  window  */ 
handle  of  object  that  has  input  */ 
message  buffer  */ 
message  length  */ 
state  of  selected  item  */ 


/*  this  string  defines  the  contents  of  the  menu  */ 
static  char  mkmenuf)  =  "\ 

Access  DV  A  \ 

Quit  Q  "; 

static  char  mkmenutbl [ ]  = 

I 

ftab (2, FTH_KEYSELECT+FTH_MODIFIED+FTH_AUTORESET, 0,0,  9,  2)  , 
0,0,0, 13, FTE_SELECT, 'A' ,1,0, 

1, 0, 1, 13, FTE_SELECT, ' Q' ,1,0, 


win  =  winjiew ("DVMAKE", 6,2, 14) ; 
win_logattr (win, 1) ; 
win_attr  (win, 1) ; 
win_disallow (win, ALW_HSIZE) ; 
win_disallow (win, ALW_VSIZE) ; 
win_swrite (win, mkmenu) ; 
win_stream (win, mkmenutbl) ; 
fld_marker (win, 175) ; 

kbd  =  key  jiew ( ) ; 
key_open (kbd, win) ; 
key_addto (kbd, KBF_FIELD) ; 


get  a  new  window  */ 

and  set  its  logical  attributes  */ 


/*  do  not  allow  resizing  menu  */ 

/*  write  the  contents  and  */ 

/*  field  table  to  the  menu  window  */ 
/*  set  the  selected  field  marker  */ 

/*  get  a  keyboard  for  the  menu  */ 

/*  and  put  it  into  field  mode  */ 


/*  put  and  display  the  menu  in  the  top  right  corner  of  the  main  window  */ 
win_poswin (win, MainWin, PSW_LEFT, 0, PSW_RIGHT, 0,0); 
win_unhide (win)  ; 

win_top  (win);  /*  make  sure  it's  the  one  on  top  */ 

/*  go  until  someone  wakes  me  up  with  tsk_post (MenuTsk)  */ 
for  (whichobj  =  0;  whichobj  !=  tskjneO;  ) 

{ 

/*  wait  for  something  to  show  up  in  our  object  queue  */ 
if  ((whichobj  =  obq_read())  ==  kbd) 

{ 

key_read(kbd, &kbuf , sklen) ;/*  see  what  field  was  selected  */ 
state  =  qry_type (win, (int)  *kbuf);  /*  is  it  ON  or  OFF  */ 
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Listing  One  ( Listing  continued,  text  begins  on  page  28.) 


if  ( (int)  *kbuf  ==  1  &&  /*  was  "Access  DV"  toggled?  */ 

Status  !=  ABORT) 

I 

apibeginc () ;  /*  make  sure  err()  hasn't  aborted  */ 

if  (Status  !=  ABORT)  /*  in  the  interim  */ 

Status  =  (state  ==  FLT_SELECT  ?  ACCESSDV  :  NORMAL); 
api_endc(); 

} 

else  /*  selected  "Quit"  */ 

I 

Status  *  ABORT; 

fld_reset (win) ;  /*  show  only  Quit  as  selected  */ 

f ld_type (win, 2, FLT_SELECT) ; 

) 

} 

I 

/*  get  rid  of  menu  window,  keyboard  */ 
key_free (kbd) ; 
winf ree (win) ; 


/* - GET  TIME  ROUTINE 


static  char  *buf; 

char  *bp; 

int  c,  lastc; 

/*  Two  buffers  are  used.  Here,  we  are  getting  a  worst-case  buffer 

*  that  will  hold  the  longest  possible  line.  Later  on  we'll  copy 

*  the  string  into  a  buffer  that's  the  correct  size. 

*/ 

if  (  (bp  =  buf  =  (char  *)  gmem (maxline) )  ==  NULL  ) 
return  (  NULL  ) ; 

whiled) 

I 

/*  Get  the  line  from  fp.  Terminate  after  maxline 
*  characters  and  ignore  \n  followina  a  \. 

*/ 

Inputline++;  /*  Update  input  line  number  */ 

for  (  lastc=0;  (c  =  fgetc(fp))  !=  EOF  &&  c!='\n';  lastc=c) 
if  (  — maxline  >  0  ) 

*bp++  =  c; 


ulong  gtime(  char  ‘file  ) 

I 

/*  Return  the  time  and  date  for  file,  or  if  the  file 

*  does  not  exist,  assume  it  is  very  old 

*  The  DOS  time  and  date  are  concatanated  to  form  one 

*  large  number. 

*  THIS  ROUTINE  IS  NOT  PORTABLE  (because  it  assumes  a  32 

*  bit  ulong  to  provide  for  the  time  functions) . 


short  handle; 

struct  ftime  time; 

ulong  utime  -  0; 

char  xtern*searchpath () ; 


/*  Place  to  remember  file  handle  */ 
/*  date/time  structure  */ 
/*  use  to  convert  time  to  ulong  */ 
/*  search  PATH  for  the  file,  */ 
/*  defined  in  TURBO  C's  dir.h  */ 


if  ((handle  =  open (searchpath (file) ,0_RD0NLY) )  ==  -1) 

1 

/*  File  doesn't  exist.  Return  a  very  old  date  &  time  */ 
return {  OLDTIME  ); 

) 

else 

( 

/*  File  exists,  so  get  the  time  */ 
if  (  getftime (handle, &time)  ) 

err("DOS  returned  error  from  date/time  request"); 

if  (  close (handle)  ) 

err ("DOS  returned  error  from  file  close  request"); 


/*  pack 

the  time 

utime 

=  (ulong) 

utime 

=  (ulong) 

utime 

=  (ulong) 

utime 

=  (ulong) 

utime 

=  (ulong) 

utime 

=  (ulong) 

into  an  unsigned 
time. ft  year  « 
time. ft_month  << 
time.ftday  « 
time.ft_hour  « 
time.ft_min  « 
time. ft_t sec; 


long  for  comparisons 
25; 

21; 

16; 

11; 

5; 


*/ 


return (  utime  ); 


CHAR  STORAGE 


char  “stov(  char  *str,  int  maxvect  ) 

( 

/*  "str"  is  a  string  of  words  separated  from  each  other  by 

*  white  space.  Stov  returns  an  argv-like  array  of  pointers 

*  to  character  pointers,  one  to  each  word  in  the  original 

*  string.  The  white  space  in  the  original  string  is  replaced 

*  with  nulls.  The  array  of  pointers  is  null-terminated. 

*  "Maxvect"  is  the  number  of  vectors  in  the  returned 

*  array.  The  program  is  aborted  if  it  can't  get  memory. 

*/ 


if  (  ! (  c  ==  ' \n'  &&  lastc  ==  '\\')  ) 
break; 

else  if  (  maxline  >  0  )  /*  erase  the  \  */ 

— bp; 

> 

*bp  =  0; 

if  (  (c  ==  EOF  &&  bp  =“  buf)  ! ! 

(bp  =  (char  *)  gmem((int)  (bp-buf ) +1 ) )  ==  NULL  ) 

( 

/*  If  EOF  was  the  first  character  on  the  line  or 

*  malloc  fails  when  we  try  to  get  a  buffer,  quit/ 

*/ 

f mem (buf ) ; 
return  {  NULL  ) ; 


strcpyl  bp,  buf  );  /*  Copy  the  worst-case  buffer  to  the  one  */ 

/*  that  is  the  correct  size  and  ...  */ 

fmem(  buf  );  /*  free  the  original,  worst-case  buffer,  */ 

return (  bp  );  /*  returning  a  pointer  to  the  copy.  */ 

) 

/* - - - - V 


char  “getblockl  FILE  *fp  ) 

I 

/*  Get  a  block  from  standard  input.  A  block  is  a  sequence  of 

*  lines  terminated  by  a  blank  line.  The  block  is  returned  as 

*  an  array  of  pointers  to  strings.  Ac  most  MAXBLOCK  lines  can 

*  be  in  a  block.  Leading  white  space  is  stripped. 

V 

char  *p,  ‘lines [MAXBLOCK) ,  “blockv  =  lines; 
int  blockc  =  0; 

do  ( 

if  (  (p  =  getline (MAXLINE, fp) )  ==  NULL) 
break; 

skipwhite (p) ; 

if  (  ++blockc  <=  MAXBLOCK  ) 

*blockv++  =  p; 

else 

err("action  too  long  (max  =  %d  lines) ", MAXBLOCK) ; 

}  while  (  *p  ) ; 

/*  Copy  the  blockv  array  into  a  safe  place.  Since  the  array 

*  returned  by  getblock  is  NULL  terminated,  we  need  to 

*  increment  blockc  first. 

*/ 


char  “vect,  “vp; 

vp  =  vect  =  (char  **)  gmem(  (maxvect  +  1)  *  sizeof(str) 
while  (  ‘str  &&  — maxvect  >=  0  ) 

{ 

skipwhite  (str) ; 

*vp++  =  str; 
skipnonwhite (str) ; 
if  {  *str  ) 

*str++  =  0; 


*vp  =  0; 
return (  vect  ); 


blockv  =  (char  **)  gmem(  (blockc  +  1)  *  sizeof (blockv[0) )  ) ; 
movmem(  lines,  blockv,  blockc  *  sizeof (blockv [0) )  ); 
blockv [blockc]  =  NULL; 

return (  blockv  ) ; 

) 

/* - - - */ 

TNODE  ‘makenode (  void  ) 

{ 

/*  Create  a  TNODE,  filling  it  from  the  mkfile,  and  return  a 

*  pointer  to  it.  Return  NULL  if  there  are  no  more  objects 

*  in  the  makefile. 

V 


/* - 

char  ‘getline (  int  maxline,  FILE  *fp  ) 

{ 

/*  Get  a  line  from  the  stream  pointed  to  by  fp. 

*  "Maxline"  is  the  maximum  input  line  size  (including  the 

*  terminating  null.  A  \  at  the  end  of  line  is 

*  recognized  as  a  line  continuation,  (the  lines 

*  are  concatanated).  Buffer  space  is  gotten  from  gmem(). 

*  If  a  line  is  longer  than  maxline  it  is  truncated  (i.e. 

*  all  characters  from  the  maxlineth  until  a  \n  or  EOF  is 

*  encountered  are  discarded. 

*  Returns:  NULL  on  a  malloc  failure  or  end  of  file. 

*  A  pointer  to  the  malloced  buffer  on  success. 


char  ‘line,  *lp; 

TNODE  ‘nodep; 

/*  First,  skip  past  any  blank  lines  or  comment  lines. 

*  Return  NULL  if  we  reach  end  of  file. 

*/ 

do  { 

if  (  (line  -  getline (MAXLINE, Makefile) )  ==  NULL  ) 
return (  NULL  ); 

}  while  (  ‘line  ==  0  : :  ‘line  ==  COMMENT  ); 

/*  At  this  point  we've  gotten  what  should  be  the  dependency 

*  line.  Position  lp  to  point  at  the  colon. 

*/  (continued  on  page  97) 
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listing  One  (Listing  continued,  text  begins  on  page  28.) 

for  (  lp  =  line;  *lp  &&  *lp  !=  lp++  ) 


/*  If  we  find  the  colon  position,  Ip  to  point  at  the  first 
*  non-white  character  following  the  colon. 

*/ 

if  (  *lp  ) 

err(  "missing  /*  This  will  abort  the  program  */ 

else 

for  (  *lp++  =  0;  iswhite (*lp) ;  lp++  ) 


/*  Allocate  and  initialize  the  TNODE  */ 


nodep  =  (TNODE  *)  gmem(  sizeof (TNODE)  ); 

nodep->lnode  =  NULL; 

nodep->rnode  =  NULL; 

nodep->being_made  =  line; 

nodep->time  =  gtimel  line  ); 

nodep->depends_on  =  stov (  lp,  MAXDEP  ) ; 

nodep->do_this  =  getblock(  Makefile  ); 

nodep->made  =  1;  /*  assume  has  already  been  made,  but  later  change*/ 

nodep->apphan  =  0; 

nodep->tsknum  =  0; 

return  (  nodep  ) ; 

} 

/* - TREE  ROUTINES - */ 


TNODE  *find(  char  *key,  TNODE  ‘root  ) 

{ 

/*  If  key  is  in  the  tree  pointed  to  by  root,  return  a  pointer 
*  to  it,  else  return  0. 

*/ 

int  notequal; 

if  (  ! root  ) 

return (  0  ) ; 

if  (  (nctequal  =  strcmp(root->being_made, key) )  ==  0  ) 
return (  root  ) ; 

return  (  find(  key,  (notequal  >  0)  ?  root->lnode  :  root->rnode)  ); 

) 


/* - •/ 

int  tree(  TNODE  ‘node,  TNODE  “rootp  ) 

{ 

/*  If  node's  key  is  in  the  tree  pointed  to  by  rootp,  return  0 
*  else  put  it  into  the  tree  and  return  1. 

*/ 

int  notequal; 


char  “linev  =  &zero; 

if  (  (snode  =  find(what,  Root))  ==  NULL  ) 

err("Don't  know  how  to  make  <%s>\n",  what  ); 

if  (  !* (linev  =  snode->depends_on) )  /*  If  no  dependencies  */ 

++doaction;  /*  always  do  the  action  */ 

for  (  ;  ‘linev;  linev++  )  /*  Process  each  dependency  */ 

( 

makequeue (  ‘linev  ); 

if  (  (dnode  =  find(*linev.  Root))  ==  NULL  ) 

err ("Don't  know  how  to  make  <%s>\n",  ‘linev  ); 

if  (  snode->time  <=  dnode->time  ) 

( 

/*  If  dependent  node  is  more  recent  (time  is  greater) 

*  than  the  source  node,  do  something.  If  the  times 

*  are  equal,  assume  that  neither  file  exists  but  that 

*  the  action  will  create  them,  and  do  the  action. 

*/ 

++doaction; 

} 

} 

if  (  doaction  )  /*  are  we  going  to  do  anything  */ 

{ 

/*  are  there  any  commands,  and  is  this  node  not  in  MkQueue  */ 
if  (  snode->do_this  &&  *snode->do_this  &&  “snode->do_this  && 

! inMkQueue (snode->being_made)  ) 

{ 

snode->time  =  NEWTIME;  /*  Assume  the  time  will  change  */ 
snode->made  =  0;  /*  This  item  has  not  been  made  yet  */ 

enqueue (&MkQueue, snode) ;  /*  Add  to  list  of  things  to  make  */ 

) 

) 

) 

/* - DISPATCH  TASK - */ 


int  dispatch (  void  ) 

( 

/*  Grab  a  job  from  the  TskQueue,  send  all  of  the  commands  to  that 
*  application  through  its  keyboard,  close  the  app,  and  return. 

*/ 


TNODE 

char 

char 

int 

ulong 

static  int 

void 


‘snode;  / 
“linev;  / 
‘outfnm;  / 
cmdcnt ;  / 
keyhan;  / 
taskcnt  =0;  / 


send_keys (ulong  keyhan, 


*  Source  file  node  pointer  */ 

*  Command  to  execute  */ 

*  file  to  redirect  output  to  */ 

*  how  many  commands  were  redirected  : 

*  handle  for  keyboard  */ 

*  give  each  task  a  unique  identifier 
char  ‘keys); 


/ 


*/ 


mal_lock (TskQueueLock) ;  /*  grab  the  task  queue  */ 

snode  =  (TNODE  *)  dequeue (STskQueue) ;  /*  get  a  task  from  the  queue  */ 

mal_unlock (TskQueueLock) ;  /*  let  go  of  the  task  queue  */ 


if  (  ‘rootp  ==  NULL  ) 

{ 

‘rootp  =  node; 
return (  1  ) ; 

) 

if  (  (notequal  =  strcmp(  (‘rootp) ->being_made,  node->being_made) )  ==  0  ) 
return (  0  ) ; 


keyhan  =  key_of (snode->apphan) ;  /*  get  keyboard  handle  */ 

api_beginc () ; 

snode->tsknum  =  taskcnt ++;  /*  assign  a  new  task  number  */ 

api_endc () ; 

/*  get  window  to  "escape  out  of"  any  commands  that  creeped  in  at  startup*/ 
send_keys (keyhan, "\xlB") ;  /*  "\xlB"  is  the  Escape  key  character  */ 


return (  tree(  node,  notequal  >  0  ?  & (‘rootp) ->lnode  :  & (‘rootp) ->rnode) ) ; 

} 

/* - */ 


for  (linev  =  snode->do_this,  cmdcnt  =  0; 

‘linev  &&  “linev  &&  Status  !=  ABORT;  linev++) 

( 

send_keys (keyhan, ‘linev) ;  /*  send  the  command  */ 


int  dependencies (  voic  ) 

{ 

/*  Manufacture  the  binary  tree  of  objects  to  make.  First 

*  is  a  pointer  to  the  first  target  file  listed  in  the 

*  makefile  (ie.  the  one  to  make  if  one  isn't  explicitly 

*  given  on  the  command  line.  Root  is  the  tree's  root  pointer. 
*/ 

TNODE  ‘node; 

if  (  (node  =  makenodeO)  !=  NULL  ) 

{ 

/*  has  First  been  assigned  a  value  yet?  */ 
if  (First  ==  NULL) 

First  =  node->being_made; 

if  (  ! tree (node,  &Root)  ) 

err("Can't  insert  first  node  into  tree  ! ! ! \ n " ) ; 

while  (  (node  =  makenodeO)  !=  NULL  ) 
if  {  !tree(  node,  &Root  )  ) 
fmem (  node  ) ; 
return!  1  ); 


return  (  0  ) ; 

} 

/* - CREATE  MAKE  QUEUE - */ 

void  make_queue (  char  ‘what  ) 

{ 

/*  Simulate  a  sequential  make,  building  up  a  queue  of  items  to  make. 
*  The  dependency  tree  is  descended  recursively. 

*/ 

TNODE  ‘snode;  /*  Source  file  node  pointer  */ 

TNODE  ‘dnode;  /*  dependent  file  node  pointer  */ 

int  doaction  =0;  /‘If  true  do  the  action  */ 

static  char  ‘zero  =  (char  *)0; 


/*  if  the  command  doesn't  already  redirect  output,  do  so  */ 
if  (strchr (‘linev, '>' )  ==  NULL  &&  strlen (‘linev) +ReDirLen  <  MAXLINE) 


/*  get  a  new  output  file  */ 
if  ((outfnm  =  gen_name ( (int) 
1 

send_keys (keyhan, "  >  "); 
send_keys (keyhan, outfnm) 
fmem (outfnm) ; 

) 

else 

— cmdcnt;  /* 

} 

send_keys (keyhan, "\r") ;  /* 

) 

send_keys (keyhan, "exit\r") ;  /* 

waitwhile (api_isob j (snode->apphan) ) ; 

snode->made  =1;  /* 

if  (cmdcnt  >  0)  /* 

( 

mal_lock (OutQueueLock) ;  /* 

enqueue (SOutQueue, snode) ;  /* 

mal_unlock (OutQueueLock) ;  /* 

) 

api_beginc () ;  /* 

— RunCnt;  /* 

api_endc ( ) ; 


snode->tsknum, cmdcnt ++) )  !=  NULL) 

/*  send  a  redirect  command  */ 

/*  free  up  the  temp  file  name  */ 

we  couldn't  redirect  anything  */ 

send  return  key  to  run  the  command  */ 

make  window  exit  itself  when  done  */ 
/*  and  wait  for  task  to  go  away  */ 

show  that  this  item  was  made  */ 

were  any  commands  redirected?  */ 

get  access  to  output  queue  */ 
add  to  output  list  */ 
free  access  to  queue  */ 

this  task  is  done,  so  */ 
update  #  of  running  tasks  */ 


void  send_keys (ulong  keyhan,  char  ‘keys) 

( 


/*  send  string  to  keyboard,  pausing  every  5  characters  to  avoid 

*  overflowing  any  buffers.  You  could  try  different  values,  but 

*  5  seems  to  be  a  reasonable  compromise  between  speed  and  making 

*  sure  no  keys  are  lost. 

*/ 


(continued  on  page  98) 
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PARALLEL  MAKE 


listing  One  ( Listing  continued,  text  begins  on  page  28.) 

int  keyctr; 

for  (  linev  =  onode->do  this,  counter  =  0; 

‘linev  &&  “linev;  linev++  ) 

if  (keys  !=  NULL) 

printf  ("\n%s\n", ‘linev) ;  /*  print  the  command  executed  */ 

while  (*keys) 

( 

/*  make  sure  dvmake  was  able  to  redirect  output  */ 

waitwhile (key  sizeof (keyhan) ) ;  /*  wait  for  keyboard  space  */ 

if  (strchr (‘linev, '>' )  ==  NULL  && 

for  (keyctr  =  0;  ‘keys  &&  keyctr  <  5;  keyctr++) 

strlen (‘linev) +ReDirLen  <  MAXLINE) 

key  write (keyhan, keys++, 1, 0) ;  /*  send  a  single  keystroke  */ 

( 

) 

/*  get  the  file  name  and  open  the  file  */ 

} 

infnm  =  gen  name((int)  onode->tsknum, counter++) ; 

/* - MAKE  TASK - */ 

/*  lock  access  to  memory  (fopen()  gets  memory)  */ 

int  make{  void  ) 

mal_lock (AllocLock) ; 

/*  Actually  execute  the  commands.  Items  are  removed  from  the 

if  (infnm  ==  NULL  ::  (infile  =  fopen (infnm, "r") )  ==  NULL) 

*  MkQueue  queue,  and  placed  back  on  the  queue  if  its  dependents 

( 

*  haven't  been  made  yet.  This  task  runs  in  parallel  with  others. 

mal_unlock (AllocLock) ;  /*  free  access  to  memory  */ 

TNODE  ‘snode;  /*  Source  file  node  pointer  */ 

/*  not  a  drastic  error,  but  tell  user  */ 
printf ("Can' t  open  %s\n", infnm) ; 

char  “linev;  /*  Command  to  execute  */ 

) 

char  doaction;  /*  Should  we  do  anything?  */ 

else  /*  we  successfully  opened  the  temporary  file  */ 

char  ‘stack;  /*  stack  for  dispatch ()  tasks  */ 

( 

/*  while  there  are  still  items  to  make  */ 

while  {  (snode  =  (TNODE  *)  dequeue (iMkQueue) )  !=  NULL  &&  Status  !=  ABORT  ) 

( 

mal_unlock (AllocLock) ;  /*  free  access  to  memory  */ 

/*  copy  the  file  to  stdout  */ 

while  ( (ch  =  fgetc (infile) )  !=  EOF) 

/*  make  sure  all  dependents  have  been  made  before  acting  */ 

putchar (ch) ; 

for  (linev  =  snode->depends  on,  doaction  =  1;  ‘linev;  linev++  ) 
if  (! (find (‘linev, Root) ->made) ) 

/*  get  access  to  memory  (fclose()  releases  memory)  */ 

doaction  =  0; 

mal_lock (AllocLock) ; 

if  { (doaction) 

fclose (inf ile) ;  /*  close,  and  */ 

{ 

remove (infnm) ;  /*  erase  the  temporary  file  */ 

enqueue (&MkQueue, snode) ;  /*  put  the  item  back  on  the  queue  */ 

api_pause();  /*  and  give  up  our  time  slice  */ 

mal  unlock (AllocLock) ;  /*  free  access  to  memory  */ 

) 

else 

{ 

fmem (infnm) ; 

/*  put  the  item  on  the  task  queue,  and  start  up  its  dispatch  */ 

) 

mal  lock (TskQueueLock) ;  /*  grab  the  task  queue  */ 

) 

enqueue (STskQueue, snode) ;  /*  put  a  task  on  the  queue  */ 

) 

mal_unlock (TskQueueLock) ;  /*  let  go  of  the  task  queue  */ 

) 

/*  get  stack  space  for  the  command  dispatcher  */ 

/*  if  user  aborts,  get  rid  of  remaining  temporary  files  */ 

if  (  (stack  =  (char  *)  gmem(STKSIZE) )  ==  NULL  ) 

if  (Status  ==  ABORT) 

err ("Out  of  memory"); 

( 

/*  keep  trying  to  start  a  new  application 
*  unless  user  aborts  or  wants  to  access  DESQview  menu 
*/ 

while  (  Status  !=  NORMAL  : 1 

waitwhile (api_isobj (MakeTsk) ); /»  wait  for  make()  to  stop  first  */ 

mal_lock (OutQueueLock) ;  /*  gain  access  to  queue  */ 

while  (  (onode  =  (TNODE  *)  dequeue (&OutQueue) )  !=  NULL  ) 

(snode->apphan  =  app  start  ( (char  *)  &Pif,Lpif))  ==  0  ) 

for  (  linev  =  onode->do  this,  counter  =  0; 

•linev  &&  “linev;  linev++  ) 

if  (Status  ==  ABORT)  /*  get  out  now!  */ 

if  (strchr (‘linev,  '>' )  ==  NULL  &&  /*  could  we  redirect?  */ 

strlen (‘linev) +ReDirLen  <  MAXLINE) 

else  if  (RunCnt  ==  0  &&  /*  can't  we  even  get  1  running?  */ 

if  ((infnm  =  gen  name ((int)  onode->tsknum, counter++) )  !=NULL) 

Status  ==  NORMAL  &&  snode->apphan  ==  0) 

1 

err ("Cannot  start  a  single  process"); 

remove (infnm) ;  /»  erase  the  temporary  file  */ 

else 

fmem(infnm);  /*  and  free  up  the  memory  */ 

api_pause();  /*  just  give  up  our  time  slice  */ 

) 

if  (snode->apphan  !=  0) 

) 

mal  unlock (OutQueueLock) ;  /*  free  access  to  queue  */ 

} 

/*  either  hide  or  put  the  application  in  the  background  */ 
if  (ShowWin) 

/*- 

-  INITIALIZE  ROUTINES - - -*/ 

app_goback (snode->apphan) ; 

else 

int 

controlbrk(  void  )  /*  handles  control-break  interrupts  */ 

app  hide (snode->apphan) ; 

[ 

return)  1  );  /*  return  non-zero  to  continue  running  */ 

/*  start  up  another  command  dispatcher,  with  no  window  */ 

) 

tsk_new (dispatch, stack, STKSIZE, "",0, 0, 0) ; 

/*- 

- */ 

api_beginc () ; 

++RunCnt;  /*  we've  started  another  task  */ 

void  getoptions (int  argc,char  *argv(]) 

api  endc ( ) ; 

1 

int  i; 

) 

) 

char  *getcwd();  /*  defined  in  dir.h  */ 

) 

void  ctrlbrkO;  /*  defined  in  dos.h  */ 

waitwhile (RunCnt  >  0);  /*  wait  for  all  tasks  to  finish  */ 

TskQueueLock  =  mal  new();  /*  semaphore  for  TskQueue  */ 

) 

OutQueueLock  =  mal  new{);  /*  semaphore  for  OutQueue  */ 

/* - OUTPUT  TASK - */ 

void  output (  void  ) 

( 

AllocLock  =  mal  new();  /*  semaphore  for  malloc/free  */ 

/*  get  the  current  directory,  used  to  save  output  files  */ 
if  (getcwd(CurDir, MAXFNM)  ==  NULL) 

err ("Cannot  get  current  directory"); 

/*  Send  files  (created  by  redirecting  output  to  DVMKxxyy . $$$)  to 

*  standard  output  in  same  order  they  were  created,  keeping  all 

ReDirLen  =  strlen (CurDir) +16;  /*  length  of  redirection  file  name  */ 

*  output  for  a  given  dependency  together. 

*/ 

/*  initialize  the  control-break  handler  to  call  controlbrkf)  */ 

TNODE  ‘onode;  /*  Output  node  pointer  */ 

ctrlbrk (controlbrk) ; 

FILE  ‘infile;  /*  file  to  read  input  from  */ 

char  ‘infnm;  /*  file  name  of  input  */ 

for  (i  =  1;  i  <  argc;  i++)  /*  get  the  command  line  switches  */ 

char  “linev;  /*  pointer  to  commands  */ 

{ 

int  ch, counter; 

/*  windows  switch  */ 

/*  loop  until  everything  is  finished  */ 

if  (strcmp (argv(i] , "-w")  ==  0  ! !  strcmp (argv [i] , "-W")  ==  0) 

ShowWin  =  1; 

while  ((api  isobj (MakeTsk)  !!  OutQueue  !=  NULL)  &&  Status  !=  ABORT) 

{ 

/*  memory  size  switch  */ 

mal  lock (OutQueueLock) ;  /*  get  access  to  output  queue  */ 

else  if  (strcmp (argvfi] , "-k")  ==  0  ! !  strcmp (argv [i] , "-K")  ==  0) 

if  (  (onode  =  (TNODE  *)  dequeue (SOutQueue) )  ==  NULL  ) 

if  (i  <  argc  -  1) 

mal  unlock (OutQueueLock) ;  /*  free  access  to  queue  */ 

if  ( (MemSize  =  atoi (argv [++i] ) )  <=  0) 

api  pause();  /*  and  give  up  our  time  slice  */ 

err ("Invalid  memory  size  parameter  for  -k  switch"); 

)  /*  because  there's  nothing  to  output  */ 

) 

else 

else 

{ 

err ("Missing  memory  size  parameter  for  -k  switch"); 

mal_unlock (OutQueueLock) ;  /*  free  access  to  queue  */ 

} 

98 


Dr.  Dobb’s Journal,  November  1989 

785 


/*  help  switch  */ 

else  if  (strcmp(argv[i] , M-h")  ==011  strcmp(argv[i] ,  "-H")  ==  0) 
{ 

printf ("dvmake  [ — w J  [-k  nnn]  [ — h]  [target] \n") ; 
printf("  -w  switch  displays  windows  \n“); 
printf ("  -k  switch  sets  task  memory  to  nnn  K-bytes  \n"); 
printf ("  -h  switch  displays  help  message  \n"); 

} 

/*  anything  else  with  -  or  /  must  be  mistake  */ 
else  if  (argv(i) [0]  ==  II  argv[i] (0)  ==  '/') 
err("Invalid  command  switch:  %s" , argv [i] ) ; 

/*  anything  else  must  be  the  first  item  to  make  */ 
else 
( 

if  (  (First  =  (char  *)  gmem (strlen (argvji] ) +1) )  ==  NULL) 
err ("Out  of  memory"); 
strcpy (First, argv [i] ) ; 

) 

) 

} 

/* -  START  PARALLEL  TASKS  - */ 

void  startup (  void  ) 

( 

char  *mkstack,  /*  stacks  for  various  tasks  */ 

"menustack; 

MainWin  =  win  me();  /*  get  handle  of  main  window  */ 

/*  initialize  a  PIF  buffer  with  appropriate  window  size  */ 
if  (ShowWin) 

init_pif (SPif , iLpif , "  DVMAKE  TASK  ",25,80); 

else 

init_pif (SPif , &Lpif , "  DVMAKE  TASK  ",1,1); 

/*  get  stack  space  for  the  parallel  tasks  */ 

if  (  (mkstack  -  (char  *)  gmem(STKSIZE) )  ==  NULL  :: 

(menustack  =  (char  *)  gmem(STKSIZE) )  ==  NULL  ) 
err("Out  of  memory"); 

/*  we  are  now  in  Parallel  mode  */ 

Parallel  -  1; 

/*  start  a  task  to  track  a  menu,  with  no  title  or  window  */ 

MenuTsk  -  tsk_new (dvmenu, menustack, STKSIZE, "", 0, 0, 0) ; 

/*  start  a  task  to  make  the  items,  with  no  title  or  window  */ 
MakeTsk  =  tsk_new (make, mkstack, STKSIZE, "",0,0,0); 


/* - - STOP  PARALLEL  TASKS - */ 

void  finishup(  void  ) 

i 

/*  get  dvmenu ()  to  stop  by  posting  its  Object  Queue  */ 
tsk_post (MenuTsk) ; 

/*  wait  for  everything  to  really  finish  */ 
waitwhile(api_isobj (MakeTsk)  ::  api_isobj (MenuTsk) ) ; 


MAIN  PROGRAM 


main(  int  argc,  char  *argv[)  ) 

( 

/*  if  DESQview  is  not  running  or  version  is  too  low,  display  a  message  */ 
if  (api_init()  <  DV_VER) 


{ 


printf  ("dvmake  requires  DESQview  version  %d.%02d  or  later\n" 
DV_VER/256,  DV_VER%256)  ; 

return  (  1  ) ; 


api_level (DV_VER) ; 
getoptions(  argc,  argv  )  ; 


/*  tell  DV  what  extensions  to  enable  */ 
/*  get  command  line  arguments  */ 


if  (  (Makefile  =  fopen (MAKEFILE,  "r"))  ==  NULL  ) 
err ("can't  open  %s\n",  MAKEFILE  ); 


if  (  ! dependencies ()  ) 


fclose (Makefile) ; 
err ("Nothing  to  make"); 


/*  is  there  anything  in  the  mkfile  */ 


fclose (Makefile)  ; 
make_queue(  First  ); 

if  (MkQueue  !=  NULL) 
( 

startup () ; 
output  ()  ; 
f inishup () ; 


/*  simulate  the  sequential  make  */ 

/*  does  anything  need  to  be  made?  */ 

/*  start  parallel  tasks  */ 

/*  display  output  from  tasks  */ 

/*  stop  parallel  tasks  */ 


mal_free (TskQueueLock) ; 
mal_free (OutQueueLock) ; 
mal  f ree (AllocLock) ; 


/*  get  rid  of  our  semaphores  */ 


if  (Status  ==  ABORT)  /*  print  the  error  message  */ 
fprintf (stderr, "%s", Error) ; 

api_exit();  /*  tell  DESQview  we're  done  */ 

return (  Status  ==  ABORT  ?  1  :  0  ) ; 


End  Listing 
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CONCURRENT  C 


Listing  One  ( Text  begins  on  page  38. ) 

Listing  Six 

(file  tty.h) 

♦include  "concurrentc . h" 

process  spec  ttyOutput () 

1 

♦include  "tty.h" 

♦include  "defs.h" 

crans  void  putfint  nc,  char  *pc) ; 
trans  async  readyO,  start!),  stopO; 

process  body  ttyLineO 

int  n  =  0,  putline  =  0,  i; 

process  spec  ttylnput () 

char  c,  buff[M  LineLen); 

trans  void  put (char  c) ; 

while  (1)  ( 

trans  int  getdnt  wait); 

switch  (c  =  ttyRdr. get  0 )  ( 

1; 

case  EraseChar: 

ttyOut .put (3,  "\b  \b"); 

process  spec  ttyReaderf) 

if  (n  >  0) 

trans  async  readyf); 

break; 

trans  char  get  ( ) ; 

case  KillChar: 
if  (n  >  0) 

ttyOut .put (2,  "\r\n"); 

process  spec  ttyLineO; 

n  =  0; 
break; 

process  ttylnput  ttyln; 

case  ' \r' : 

process  ttyOutput  ttyOut; 
process  ttyReader  ttyRdr; 

End  Listing  One 

ttyOut .put (2,  "\r\n"); 
buf f [n+  +  l  =  ' \n' ; 

Listing  Two 

putline  -  1; 
break; 

♦include  "concurrentc .h" 

default : 

((include  "tty.h" 

ttyOut .put (1 ,  &c) ; 
buff[n++]  =  c; 

void  ttyReply (msg,  reply) 

if  (n  >=  M  LineLen) 

char  *msg,  *  reply; 

putline  =  1; 

( 

break; 

int  c; 

1 

char  ’nasty  =  "\r\nWAKE  UP!\r\n"; 

if  (putline)  1 

for  (i  =0;  i  <  n;  i++) 

while  (1)  ( 

ttyln. put  (buff [i) ) ; 

ttyOut .put (strlen (msg) ,  msg); 
c  =  within  30  ?  ttyln. get  (1)  :  -1; 
if  (c  ! =  -1) 
break; 

ttyOut .put (strlen (nasty) ,  nasty) ; 

putline  =  n  =  0; 

I 

1 

1 

End  Listing  Six 

) 

while  (c  ! =  ' \n' )  ( 

Listing  Seven 

*reply++  =  c; 

c  =  ttyln .get  ( 1 ) ; 

1 

’reply  =  ' \ 0 ' ; 

•.nclude  "tty.h" 

♦include  "defs.h" 

) 

End  Listing  Two 

process  body  ttylnput 0 

Listing  Three 

I 

int  n  =  0,  in  =  0,  out  =  0; 

((include  "concur rente . h" 

char  buf f [M  InBuff )  ; 

((include  "tty.h" 

while  (1)  | 

void  ttylmt  ( ) 

select  ( 

i 

(n  <  M  InBuff)  : 

ttyOut  =  create  ttyOutput  ()  prionty(l); 

accept  put (c) 

c  associate (ttyOut . ready, ) ; 

buff [in)  =  c; 

ttyRdr  -  create  ttyReader ()  priority (2); 

in  =  (in  ♦  1)  *  M  RdrBuff; 

c  associate (ttyRdr . ready, ) ; 

n+  +  ; 

ttyln  =  create  ttylnput (); 

or  (n  >  0) : 

create  ttyLine ( ) ; 

) 

End  Listing  Three 

accept  get (wait) 

treturn  buff [out ) ; 
out  =  (out  +  1)  i  M_RdrBuff; 

Listing  Four 

or  (n  ==  0)  : 

accept  get (wait)  suchthat  (Iwait) 

(File  defs.h) 

treturn  -1; 

((define  M_RdrBuff  2048 
((define  M  OutBuff  2048 

1 

1 

((define  M_InBuff  1024 
((define  M  LineLen  1024 

End  Listing  Seven 

((define  StcpChar  0x13  /*  ctl-S  */ 

((define  StartChar  0x11  /*  ctl-Q  V 
((define  EraseChar  'Ab'  /*  backspace  */ 

Listing  Eight 

#def ine  KillChar  0x03  /*  ctl-C  */ 

♦include  "concurrentc. h" 

Listing  Five 

End  Listing  Four 

♦include  "tty.h" 

♦include  "defs.h" 

process  body  ttyOutput!) 

♦include  "concurrentc . h" 

♦include  "tty.h" 

( 

int  n  =  0,  in  =  0,  out  =  0; 

♦include  "defs.h" 

int  running  =  1,  ttyrdy  =  1,  i; 
char  buff[M  OutBuff); 

process  body  ttyReader!) 

( 

while  (1)  | 

ir.t  n  =  0,  in  =  0,  out  =  0; 

select  i 

char  c,  buff[M  RdrBuff]; 

accept  start  () 

running  =  1; 

while  (1)  ( 

or  accept  stop!) 

select  | 

running  =  0; 

accept  ready() ; 

or  accept  ready!) 

c  =  uartGetChar  () ; 

ttyrdy  =  1; 

if  (c  ==  StartChar)  ( 

or  accept  put(nc,  pc)  suchthat  (n+nc  <= 

M  OutBuff)  ( 

ttyOut .start () ; 

for  (l  =  0;  l  <  nc;  i  +  H  [ 

1  else  if  (c  ==  StopChar)  ( 

buf  f [ in]  =  pc [ l ] ; 

ttyOut. stop!) ; 

in  =  (in  +  1)  T  M  OutBuff; 

)  else  if  (n  <  M  RdrBuff)  ( 

) 

buff [in)  =  c; 

n  +=  nc; 

in  =  (in  +  1)  *  M_RdrBuff; 
n  +  +  ; 

) 

1 

) 

if  (ttyrdy  &&  running  &&  n  >  0)  ( 

or  (n  >  0)  : 

uart Put Char (buf  f [out ] )  ; 

accept  get  ( ) 

out  =  (out  +1)  »  M  OutBuff; 

treturn  buff [out) ; 

n--; 

out  =  (out  +  1)  *  M  RdrBuff; 

1 

1 

1 

End  Listing  Five 

ttyrdy  =  0; 

1 

1 

1 

End  Listings 
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Listing  One  (Text  begins  on  page  46.) 

/* 

calldlll.c  —  run-time  dynamic  linking  to  Estes's  ALIAS.DLL 
cl  -Lp  calldlll.c 
*/ 

♦include  <stdlib.h> 

♦include  <stdio.h> 

♦define  INCL_DOSMODULEMGR 
♦include  "os2.h" 

♦define  NIL  ((void  far  *)  0) 

void  fail (char  *msg)  (  puts(msg);  exit(l);  } 

void  main () 

{ 

unsigned  (far  pascal  *addsyn) (char  far  *msg); 
unsigned  (far  pascal  ‘listsyn) (void) ; 
unsigned  alias; 

if  (DosLoadModule (NIL,  0,  "ALIAS",  Salias)  !=  0) 
fail  ("can't  find  ALIAS"); 

DosGetProcAddr (alias,  "ADDSYN",  fcaddsyn) ; 

DosGetProcAddr (alias,  "LIST_SYN",  slistsyn); 

(*addsyn) ("ep  \\os2\\eps\\epsilon") ; 

(‘listsyn) () ; 

DosFreeModule (alias) ; 

) 

End  Listing  One 


Listing  Two 

MODULE  calldll; 

(*  JPI  TopSpeed  Modula-2  for  OS/2  *) 

(*  run-time  dynamic  linking  to  Estes's  ALIAS.DLL  *) 

FROM  InOut  IMPORT  WriteString,  WriteLn; 

IMPORT  Dos; 

PROCEDURE  fail  (msg  :  ARRAY  OF  CHAR) ; 

BEGIN 

WriteString (msg) ;  WriteLn;  HALT; 

END  fail; 

VAR 

addsyn  :  PROCEDURE  (ADDRESS)  :  CARDINAL; 
listsyn  :  PROCEDURE  ()  :  CARDINAL; 
alias  :  CARDINAL; 

ret  :  CARDINAL;  (*  ignored  retval  *) 

BEGIN 

IF  (Dos . LoadModule (NIL,  0,  "ALIAS",  alias)  ♦  0)  THEN 
fail ("can't  find  ALIAS"); 

END; 

ret  :=  Dos .GetProcAddr (alias,  "ADDSYN",  PROC (addsyn) ) ; 
ret  :=  Dos .GetProcAddr (alias,  "LIST_SYN",  PROC (listsyn) ) ; 

(*  In  the  next  line,  the  string  _must  be  passed  as  an 
ADDRESS,  not  as  an  ARRAY  OF  CHAR:  Modula-2  passes  open 
arrays  as  _six_  bytes  on  the  stack  —  two  bytes  for  the 
length,  followed  by  the  address  of  the  arra y  itself  — 
but  OS/2  DLL's  generally  expect  only  the  string  itself 
(zero-terminated  of  course) .  *) 

ret  :=  addsyn (ADR ( "ep  \os2\eps\epsilon") ) ; 

ret  : =  listsyn () ; 

ret  :=  Dos .FreeModule (alias)  ; 

END  calldll. 

End  Listing  Two 

listing  Three 

;  calldll. lsp 

;  OS2XLISP  run-time  dynamic  linking  to  Estes's  ALIAS.DLL 

(define  alias  (loadmodule  "ALIAS")) 

(if  (zerop  alias) 

(error  "can't  find  ALIAS")) 

(call  (getprocaddr  alias  "ADDSYN")  "ep  \os2\eps\epsilon") 

(call  (getprocaddr  alias  "LIST_SYN")) 

(freemodule  alias) 


End  Listing  Three 


Listing  Four 

/* 

procl.c  —  implements  higher-level  access  to  OS/2  run-time  dynlinks 
cl  -c  -Lp  procl.c 
*/ 

♦define  INCL_DOSMODULEMGR 
♦include  "os2.h" 

♦include  "procaddr.h" 

♦define  NIL  ( (void  far  *)  0) 

WORD  loadmodule (ASCI I Z  name) 

{ 

WORD  h; 

return  DosLoadModule (NIL,  0,  name,  (PHMODULE)  Sh)  ?  0  :  h; 


ULONG  getprocaddr (WORD  module,  ASCIIZ  name) 

( 


ULONG  pf; 

return  DosGetProcAddr (module,  name,  (PPFN)  &pf )  ?  0  :  pf; 

} 

ULONG  procaddr (ASCIIZ  module,  ASCIIZ  name) 

( 

return  getprocaddr (loadmodule (module) ,  name); 

) 

BOOL  freemodule (WORD  h) 

I 

return  (!  DosFreeModule (h) ) ; 

1  End  Listing  Four 


Listing  Five 

/• 

procaddr.h  --  higher-level  access  to  OS/2  run-time  dynlinks 
*/ 

typedef  unsigned  WORD; 
typedef  unsigned  short  BOOL; 
typedef  unsigned  long  ULONG; 
typedef  char  ‘ASCIIZ; 

WORD  loadmodule (ASCIIZ  name) ; 

ULONG  getprocaddr (WORD  module,  ASCIIZ  name); 

ULONG  procaddr (ASCIIZ  module,  ASCIIZ  name); 

BOOL  freemodule (WORD  handle); 

End  Listing  Five 


Listing  Six 

/* 

calldll2.c  --  run-time  dynamic  linking  to  CRTLIB.DLL,  using  PROC1.C 
requires  MSC  5.1  CRTEXE.OBJ 

cl  -AL  -c  calldll2.c  procl.c 

link  /nod/noi  crtexe.obj  calldll2  prod, calldll2, , crtlib. lib  os2; 
output : 

Hello  from  calldll2 

Hello  again,  using  new  ANSI  C  style 

_printf  lives  at  03EF:1098 

printf  returned  27 

Goodbye 

*/ 

♦include  "procaddr.h" 

typedef  ULONG  (far  cdecl  *CFN)(); 

main(int  argc,  char  *argv[]) 

( 

WORD  (far  cdecl  ‘printf)  (); 

WORD  crtlib; 

WORD  ret; 


crtlib  =  loadmodule ("CRTLIB") ; 

printf  =  (CFN)  getprocaddr (crtlib,  "_printf" ); 

(‘printf)  ("Hello  from  %s\n",  argv[0]);  /*  1  */ 

printf ("Hello  again,  using  new  ANSI  C  styleNn");  /*  2  */ 

ret  =  printf ("_printf  lives  at  %Fp\n",  printf);  /*  3  */ 

printf ("printf  returned  %d\n",  ret);  /*  4  */ 


((CFN)  getprocaddr (loadmodule ("CRTLIB") , "_printf") ) ("Goodbye") ;  /*  5  */ 

freemodule (crtlib) ; 

I 

End  Listing  Six 

Listing  Seven 

/* 

calldll3.c  --  run-time  dynamic  linking  from  the  command-line 
requires  MSC  5.1  CRTEXE.OBJ,  uses  proc2.obj  or  procaddr.dll 
doesn't  include  "os.h" 

to  use  proc2.obj: 

cl  -AL  -c  -Gs2  -Ox  -W2  calldll3.c  proc2.c 

link  /nod/noi  crtexe.obj  calldll3  proc2, calldll3 .exe, , crtlib. lib  os2.1ib; 

to  use  procaddr.dll  (IMPLIB  procaddr . lib) : 
cl  -AL  -c  -Gs2  -Ox  -W2  calldll3 . c 

link  /nod/noi  crtexe.obj  calldll3, calldll3, , procaddr . lib  crtlib. lib  os2.1ib; 
to  run: 

calldll3  cmodule  name>  <function  name  or  ordinal  number>  [args...]  [%mask] 
examples: 

calldll3  VIOCALLS  VIOWRTTTY  "hello  world"  5  0 
calldll3  doscalls  DosMkDir  \foobar  0L 
calldll3  doscalls  DosRmDir  \foobar  0L 
calldll3  DOSCALLS  DosBeep  2000  300 

calldll3  DOSCALLS  50  2000  300  ;  DosBeep 

calldll3  CRTLIB  _printf  "goodbye  world:  %lu"  666L  "  [ %d ] " 
calldll3  CRTLIB  ACOS  -1.0  %.15f 
calldll3  CRTLIB  SQRT  -1.0  %f 
calldll3  CRTLIB  _toupper  'b'  %c 
calldll3  PROCADDR  LOADMODULE  PROCADDR  %X 
*/ 

♦include  <mt\stdlib.h> 

♦include  <mt\stdio.h> 

♦include  <mt\string.h> 

♦include  "local. h" 

tinciude  "Proc2.h"  ( continued  on  page  104) 
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Listing  Seven  (Listing  continued,  text  begins  on  page  46.) 

typedef  enum  {  typ_string,  typ_byte,  typ_word,  typlong,  typfloat  )  TYPE; 

TYPE  NEAR  type (char  *arg) ; 

TYPE  NEAR  retval_type (char  *s) ; 

VOID  fail (char  *msg)  (  puts (msg) ;  exit(l);  } 

/* 

push()  :  see  Cortesi,  Programmer's  Essential  OS/2  Handbook,  pp. 136-137 

*/ 

VOID  NEAR  PASCAL  push()  (  ) 
extern  WORD  pop (void); 

♦define  PUSH_ARG (arg)  \ 

(  \ 

switch  (type (arg))  \ 

(  \ 


case 

typ_string: 

push (arg) ; 

c 

+= 

2;  break; 

\ 

case 

typ_byte : 

push (arg [1] ) ; 

c 

+= 

1;  break; 

\ 

case 

typ  word: 

push (atoi (arg) ) ; 

c 

+= 

1;  break; 

\ 

case 

typ_long: 

push (atol  (arg) ) ; 

c 

+= 

2;  break; 

\ 

case 

typ  float: 

push (atof (arg) ) ; 

c 

+= 

4;  break; 

\ 

1  \ 


♦define  SYNTAX_MSG  \ 

"syntax:  calldll3  <module  name>  <func  name  or  ord^>  (args...)  (%mask]” 

main(int  argc,  char  *argv[)) 

( 

FN  f; 

TYPE  retval_typ  =  typ_word; 
char  ‘mask  =  ”%u"; 

WORD  module; 

BOOL  is_cdecl; 
int  i,  c; 

if  (argc  <  3) 

fail (SYNTAX_MSG) ; 

/*  handle  optional  printf  mask  */ 
if  (strchr (argv(argc-l) ,  '%')) 

retval_typ  =  retval_type (mask  =  argv[ — argc]); 

if  ((module  =  loadmodule (argv[l] ) )  ==  0) 
fail ("can't  load  module"); 

/*  pass  ASCIIZ  string  or  ordinal  number  */ 

f  =  getprocaddr (module,  isdigit (argv(2] [0] )  ?  atol (argv[2] )  :  argv[2]); 
if  (!  f) 

fail ("can't  get  function"); 

is_cdecl  =  !  (strcmp (strupr (argv [ 1 ] ) ,  "CRTLIB")); 

/*  push  in  reverse  order  for  cdecl  */ 
if  (is_cdecl) 

{ 

for  (i=argc-l,  c=0;  i>=3;  i — ) 

PUSH_ARG(argv(i] ) ; 

1 

else 


for  (i=3;  i<argc;  i++) 

PUSH_ARG(argv[i] ) ; 

) 

/*  args  are  on  the  stack  :  call  (*f)()  and  print  retval  */ 
switch  (retval_typ) 

{ 


case  typ_string: 
case  typ_byte: 
case  typ_word: 
case  typ_long: 
case  typ_float: 


printf (mask,  ( (STRFN)  f ) ( ) ) ;  break; 
printf (mask,  ((BYTEFN)  f ) ( ) ) ;  break; 
printf (mask,  f());  break; 
printf (mask,  ( (LONGFN)  f )  ( ) ) ;  break; 
printf (mask,  ( (FLOATFN)  f )  ( ) ) ;  break, 


) 


if  (is_cdecl) 

for  (i=0;  i<c;  i++) 
pop ( ) ; 

f reemodule (module) ; 
return  0; 


/* 

typed  uses  some  dumb  rules  to  determine  the  type  of  an  argument: 
if  first  character  of  arg  is  a  digit  or  '-' 

and  if  arg  contains  '.'  then  it's  a  floating-point  number 
else  if  last  character  is  an  'L'  then  it's  a  long 
else  it's  a  unsigned  word 
else  if  first  character  is  an  apostrophe 
it's  a  single-byte  character 
otherwise 

it's  a  string 

*/ 

TYPE  NEAR  type (char  *arg) 

I 

if  (isdigit (arg [ 0] )  !!  (arg[0]  ==  '-'  &&  isdigit (arg l 1 J )) ) 
f 

char  *p  =  arg; 
while  (*p) 

if  (*p++  ==  ' . ' ) 

return  typ_float; 

return  (‘ — p  ==  ' L' )  ?  typ_long  :  typ_word; 

) 

else 

return  (arg[0]  ==  ' \ ' ' )  ?  typ_byte  :  typstring; 


/* 


retval_type ( )  uses  a  printf  ()  mask  (e.g.,  %s  or  %1X)  to  determine 
type  of  return  value 

*/ 

TYPE  NEAR  retval_type (char  *s) 

( 

while  (*s) 

{ 

switch  (*s) 

{ 

case  's'  :  return  typ_string;  break; 
case  'c'  :  return  typ_byte;  break; 
case  'p'  :  case  '1'  :  case  'I'  :  case  'O'  :  case  'U'  : 
return  typ_long;  break; 

case  'e'  :  case  'E'  :  case  'f'  :  case  'g'  :  case  'G'  : 
return  typ_float;  break; 

) 

s++; 

1 

/*  still  here  */ 
return  typ_word; 


End  Listing  Seven 


Listing  Eight 

;  pop. asm 

DOSSEG 
.MODEL  large 
.CODE  pop_text 
PUBLIC  _pop,  _sp 

_pop  proc  far 

;  save  away  far  return  address 
pop  cx 
pop  bx 

;  pop  word  off  stack  and  return  it  in  AX 
pop  ax 

;  push  far  return  address  back  on  stack 
push  bx 
push  cx 
ret 

_pop  endp 

;  useful  for  testing 
_sp  proc  far 
mov  ax,sp 
ret 

_sp  endp 
end 

End  Listing  Eight 


Listing  Nine 

/* 

proc2.c 

to  make  procaddr.dll: 

cl  -Alfu  -c  -Gs2  -Ox  -W2  -DDLL  proc2.c 

link  /nod/noi  proc2, procaddr .dll, , llibcdll . lib  os2, procaddr .def ; 
implib  procaddr. lib  procaddr. def 
copy  procaddr.dll  \os2\dll 
*/ 

♦include  <string.h> 

♦ifdef  DLL 

int  _acrtused  =  0; 

♦endif 

♦define  INCL_DOS 
♦include  "os2.h" 

♦include  "local. h" 

♦include  "proc2.h" 

typedef  struct  ( 
char  ‘name; 

USHORT  (API ENTRY  *f)  ()  ; 

)  DOSCALLS; 

/* 

include  table  generated  from  BSEDOS.H  with  AWK  script  DOSCALLS. AWK 
table  looks  like: 

LOCAL  DOSCALLS  NEAR  dos [ ]  =  ( 

0, 

"DosGetHugeShift",  DosGetHugeShift, 

"DosGetlnfoSeg",  DosGetlnfoSeg, 

i’; 

DOSCALLS. C  also  contains  ♦define  NUM_DOSCALLS 

*/ 

♦include  "doscalls.c" 

LOCAL  FN  NEAR  getdoscall (ASCIIZ  name); 

LOCAL  USHORT  NEAR  doscalls  =  0; 

WORD  pascal  loadmodule (ASCIIZ  name) 

( 

WORD  h; 

return  DosLoadModule ( (void  far  *)  0,  0,  name,  (PHMODULE)  sh)  ?  0  :  h; 

} 

/*  (continued  on  page  106) 
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Listing  Nine  (Listing  continued ,  text  begins  on  page  46.) 

if  name  is  actually  a  four-byte  ordinal  number,  use  it  as  is 
otherwise  if  module  is  not  DOSCALLS,  use  it  as  is 

otherwise  if  module  is  DOSCALLS,  get  ordinal  number  and  use  it  instead 

*/ 

FN  pascal  getprocaddr (WORD  module,  ASCIIZ  proc) 

{ 

FN  f; 

if  (!  doscalls)  doscalls  =  loadmodule ("DOSCALLS") ; 

if  ((module  ==  doscalls)  &&  FP_SEG (proc) ) 
return  getdoscall (proc) ; 

else 

return  DosGetProcAddr (module,  proc,  (PPFN)  if)  ?  0  :  f; 


FN  pascal  procaddr (ASCIIZ  module,  ASCIIZ  proc) 

{ 

return  getprocaddr (loadmodule (module) ,  proc) ; 

) 

BOOL  pascal  f reemodule (WORD  h) 

( 

return  (!  DosFreeModule (h) ) ; 

} 


/* 

do  binary  search  of  table,  looking  for  name,  returning  function  ptr 

*/ 

LOCAL  FN  NEAR  getdoscall (ASCIIZ  name) 

{ 

signed  cmp,  mid; 

signed  base  =1,  top  =  NUM_D0SCALLS+1; 

name  =  strupr (name) ; 

for  {;;) 

{ 

mid  =  (base  +  top)  /  2; 

cmp  =  strcmp(name,  strupr (dos (mid) .name) ) ; 


if  (cmp  ==  0) 

else  if  (mid  -=  base) 
else  if  (cmp  <  0) 
else  if  (cmp  >  0) 

} 

} 

End  Listing  Nine 


return  (FN)  dos [mid]. f; 
return  0; 
top  =  mid; 
base  =  mid; 


Listing  Ten 

/* 

proc2 .h 
*/ 

extern  WORD  pascal  loadmodule (ASCIIZ  name); 
extern  FN  pascal  getprocaddr (WORD  module,  ASCIIZ  proc); 
extern  FN  pascal  procaddr (ASCIIZ  module,  ASCIIZ  proc); 
extern  BOOL  pascal  f reemodule (WORD  handle); 


Listing  Eleven 


End  Listing  Ten 


♦  doscalls. awk 

♦  creates  doscalls. c  from  bsedos.h 

♦  doscalls. c  is  ((included  by  proc2.c 

♦  C>sort  -b  +2  \os2\inc\bsedos . h  I  awk  -f  doscalls. awk  >  doscalls. c 

♦  bsedos.h  contains  prototypes  such  as: 

I  USHORT  APIENTRY  DosCreateThread (PFNTHREAD,  PTID,  PBYTE); 

♦  doscalls. awk  turns  these  into  string  name/function  ptr  pairs: 

♦  "DosCreateThread",  DosCreateThread, 


BEGIN  f  init()  } 

END  {  fini()  ) 

$2  “  /APIENTRY/  &&  $3  ~  /Dos/  (  doscall ($3)  ) 

function  init()  ( 

print  "/*  doscalls. c  */" 

print  "LOCAL  DOSCALLS  NEAR  dos [ )  =  {" 

print  "\"\", \t0, " 

) 


function  fini()  ( 
print  ")  ;  " 

print  "#def ine  NUM_DOSCALLS\t", 
) 

function  doscall (s)  { 
gsub(/\(/,  "  ",  s) 
split (s,  arr) 

print  "\"“  arr[l]  "\",  "  arr[l] 
num_doscalls++ 

I 


num  doscalls 


#  replace  open  paren  with  space 

#  tokenize 

#  print  with  and  without  quotes 


End  Listing  Eleven 


Listing  Twelve 

;  procaddr. def 


LIBRARY  PROCADDR 

DESCRIPTION  'Run-Time  Dynamic  Linking' 

DATA  SINGLE  SHARED 

PROTMODE 

EXPORTS 

LOADMODULE 

GETPROCADDR 

PROCADDR 

FREEMODULE 


End  Listing  Twelve 


Listing  Thirteen 

/* 

local. h  —  miscellaneous  definitions 

*/ 


typedef  unsigned  short  WORD; 
typedef  unsigned  short  BOOL; 
typedef  char  far  ‘ASCIIZ; 
typedef  unsigned  long  ULONG; 
typedef  double  FLOAT; 
typedef  WORD  (far  *FN) (); 
typedef  ASCIIZ  (far  *STRFN)(); 
typedef  char  (far  ‘BYTEFN) ( ) ; 
typedef  WORD  (far  *WORDFN)(); 
typedef  ULONG  (far  ‘LONGFN) ( ) ; 
typedef  FLOAT  (far  pascal  ‘FLOATFN) ( ) ; 

♦define  FP_SEG(p)  ((WORD)  ((ULONG)  (p)  »  16)) 
♦define  FP_OFF(p)  ((WORD)  (p) ) 

♦define  isdigit (c)  ((c)  >=  '0'  &&  (c)  <=  '9') 


♦ifndef  NEAR 
♦define  NEAR  near 

♦define  PASCAL  pascal 

♦define  VOID  void 

♦endif 


♦define  LOCAL  static 


End  Listings 
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listing  One  (Text  begins  on  page  56.) 

Last  :=  nil; 
end; 

unit  Contain; 

destructor  List. Done; 

($S-} 

begin 

Delete; 

interface 

end; 

type 

procedure  List .Append (N:  ListNodePtr); 
begin 

(  Base  object  type  } 

Insert (N) ; 

Last  :=  N; 

Base  ■  object 

end; 

destructor  Done;  virtual; 

end; 

procedure  List. Delete; 
begin 

{  Abstract  linked  list  node  type  } 

ForEach (DelListNode)  ; 

Last  :=  nil; 

ListNodePtr  =  AListNode; 

end; 

ListNode  =  object (Base) 

Next:  ListNodePtr; 

function  List. Empty:  Boolean; 

function  Prev:  ListNodePtr; 

begin 

end; 

Empty  :*  Last  =  nil; 
end; 

{  Linked  list  iteration  procedure  type  ) 

procedure  List .ForEach (Action :  ListAction); 

ListAction  *  procedure (N:  ListNodePtr); 

var 

(  Linked  list  type  ) 

P,  Q:  ListNodePtr; 
begin 

ListPtr  ■  AList; 

P  :=  First; 
while  P  <>  nil  do 

List  -  object (Base) 

begin 

Last:  ListNodePtr; 

Q  :=  P; 

constructor  Init; 

P  :=  Next (P) ; 

destructor  Done;  virtual; 

Action (Q) ; 

procedure  Append (N:  ListNodePtr); 

end; 

procedure  Delete; 

end; 

function  Empty:  Boolean; 

procedure  ForEach (Action:  ListAction); 

function  List. First:  ListNodePtr; 

function  First:  ListNodePtr; 

begin 

procedure  Insert (N:  ListNodePtr); 

if  Last  ■  nil  then  First  :=  nil  else  First  :=  Last A. Next; 

function  NextfN:  ListNodePtr):  ListNodePtr; 

end; 

function  Prev(N:  ListNodePtr):  ListNodePtr; 

procedure  Remove(N:  ListNodePtr); 

procedure  List . Insert (N:  ListNodePtr); 

end; 

begin 

if  Last  =  nil  then  Last  :=  N  else  NA.Next  :■  LastA.Next; 

{  Abstract  binary  node  type  ) 

Last A. Next  :-  N; 
end; 

TreeNodePtr  =  ATreeNode; 

TreeNode  =  object (Base) 

function  List. Next (N:  ListNodePtr):  ListNodePtr; 

Left,  Right:  TreeNodePtr; 

begin 

end; 

if  N  =  Last  then  Next  :=  nil  else  Next  :=  NA.Next; 
end; 

{  Binary  tree  iteration  procedure  type  ) 

function  List.Prev(N:  ListNodePtr):  ListNodePtr; 

TreeAction  =  procedure(N:  TreeNodePtr); 

begin 

if  N  =  First  then  Prev  :=  nil  else  Prev  :=  NA.Prev; 

(  Binary  tree  node  creation  procedure  type  } 

end; 

TreeCreate  =  function (Key :  Pointer):  TreeNodePtr; 

procedure  List . Remove (N:  ListNodePtr); 
var 

{  Binary  tree  type  ) 

P:  ListNodePtr; 
begin 

TreePtr  =  ATree; 

if  Last  <>  nil  then 

Tree  =  object (Base) 

begin 

Root:  TreeNodePtr; 

P  :=  Last; 

constructor  Init; 

while  (PA.Next  <>  N)  and  (PA.Next  <>  Last)  do  P  :=  PA.Next; 

destructor  Done;  virtual; 

if  PA.Next  =  N  then 

function  Compare (Keyl ,  Key2:  Pointer):  Integer;  virtual; 

begin 

procedure  Delete; 

PA.Next  :=  NA.Next; 

function  Empty:  Boolean; 

if  Last  =  N  then  if  P  =  N  then  Last  :=  nil  else  Last  :=  P; 

function  Find(Key:  Pointer):  TreeNodePtr; 

end; 

procedure  ForEach (Action:  TreeAction); 

end; 

function  GetKey(N:  TreeNodePtr):  Pointer;  virtual; 

end; 

procedure  Insert (N:  TreeNodePtr); 

function  Search (Key:  Pointer;  Create:  TreeCreate): 

{  Tree  methods  ( 

TreeNodePtr; 

end; 

var 

NewTreeNode:  TreeNodePtr; 

implementation 

($F+) 

(  Base  methods  } 

function  GetTreeNode (Key :  Pointer):  TreeNodePtr; 

destructor  Base. Done; 

begin 

begin 

GetTreeNode  :=  NewTreeNode; 

end; 

end; 

(  ListNode  methods  ) 

procedure  DelTreeNode (N:  TreeNodePtr); 
begin 

function  ListNode. Prev:  ListNodePtr; 

Dispose (N,  Done); 

var 

end; 

P:  ListNodePtr; 

begin 

{ $F- } 

P  :=  Self; 

while  PA.Next  <>  Self  do  P  :=  PA.Next; 

constructor  Tree. Init; 

Prev  :=  P; 

begin 

end; 

Root  :=  nil; 

(  List  methods  ) 

end; 

($F+) 

destructor  Tree. Done; 
begin 

procedure  DelListNode (N:  ListNodePtr); 

Delete; 

begin 

end; 

Dispose (N,  Done); 

end; 

function  Tree. Compare (Keyl,  Key2:  Pointer):  Integer; 
begin 

f$F-} 

Compare  :=  0; 
end; 

constructor  List. Init; 
begin 

108 


Dr.  Dobb’s Journal,  November  1989 

791 


procedure  Tree. Delete; 
begin 

ForEach (DelTreeNode) ; 

Root  :=  nil; 
end; 

function  Tree. Empty:  Boolean; 
begin 

Empty  :=  Root  =  nil; 
end; 

function  Tree. Find (Key:  Pointer):  TreeNodePtr; 
begin 

NewTreeNode  :=  nil; 

Find  :=  Search (Key,  GetTreeNode) ; 
end; 

procedure  Tree. ForEach (Action:  TreeAction) ; 

procedure  Traverse (P:  TreeNodePtr); 
var 

R:  TreeNodePtr; 
begin 

if  P  <>  nil  then 
begin 

R  :=  PA. Right; 

Traverse (PA. Left) ; 

Action (P) ; 

Traverse (R) ; 
end; 
end; 

begin 

Traverse  (Root) ; 
end; 

function  Tree.GetKey (M:  TreeNodePtr):  Pointer; 
begin 

GetKey  :=  N; 
end; 

procedure  Tree. Insert (N:  TreeNodePtr); 
begin 

NewTreeNode  :=  N; 

N  :=  Search (GetKey (N) ,  GetTreeNode); 
end; 

function  Tree. Search (Key:  Pointer;  Create:  TreeCreate) : 

TreeNodePtr; 

procedure  Traverse(var  P:  TreeNodePtr); 
var 

C:  Integer; 
begin 

if  P  =  nil  then 
begin 

P  :=  Create (Key I ; 

PA.Left  :=  nil; 

PA. Right  :=  nil; 

Search  :=  P; 
end  else 
begin 

C  :=  Compare (Key,  GetKey(P)); 
if  C  <  0  then  Traverse(PA .Left)  else 
if  C  >  0  then  Traverse (PA .Right)  else 
Search  :=  P; 

end; 

end; 

begin 

Traverse (Root) ; 
end; 

end. 

End  Listing  One 


IOBuffer  =  array [ 1 .. IOBufSize]  of  Char; 


(  Identifier  string  } 

IdentPtr  =  A Ident; 

Ident  =  string(MaxIdentLen] ; 


{  Line  reference  object  ) 

LineRefPtr  =  ALineRef; 

LineRef  =  object (ListNode) 

LineNo:  Integer; 

constructor  Init(Line:  Integer); 
end; 

{  Identifier  reference  object  ) 

IdentRefPtr  =  AIdentRef; 

IdentRef  =  object (TreeNode) 

Lines:  List; 

Name:  IdentPtr; 
constructor  Init(S:  Ident); 
destructor  Done;  virtual; 
end; 

{  Identifier  tree  ) 

IdentTreePtr  =  AIdentTree; 

IdentTree  =  object (Tree) 

function  Compare (Keyl,  Key2:  Pointer):  Integer;  virtual; 
function  GetKey(N:  TreeNodePtr):  Pointer;  virtual; 
end; 

const 

(  Turbo  Pascal  reserved  words  ) 

KeyWordCount  =  52; 

Keyword:  array (1 . .KeyWordCount]  of  string[15]  =  ( 

'ABSOLUTE',  'AND',  'ARRAY',  'BEGIN',  'CASE',  'CONST', 

' CONSTRUCTOR' ,  ' DESTRUCTOR' ,  ' DIV' ,  ' DO' ,  ' DOWNTO' ,  ' ELSE' , 
'END',  'EXTERNAL',  'FILE',  'FOR',  'FORWARD',  'FUNCTION', 
'GOTO',  'IF',  'IMPLEMENTATION',  'IN',  'INLINE',  'INTERFACE', 
'INTERRUPT',  'LABEL',  'MOD',  'NIL',  'NOT',  'OBJECT',  'OF', 

' OR' ,  ' PACKED' ,  ' PROCEDURE' ,  ' PROGRAM' ,  ' RECORD' ,  ' REPEAT' , 
'SET',  'SHL',  'SHR',  'STRING',  'THEN',  'TO',  'TYPE',  'UNIT', 
'UNTIL',  'USES',  'VAR',  'VIRTUAL',  'WHILE',  'WITH',  ' XOR' ) ; 


var 

Idents:  IdentTree; 
LineCount:  Integer; 
RefCount:  Integer; 
InputBuffer:  IOBuffer; 
OutputBuffer :  IOBuffer; 

{  LineRef  constructor  ) 

constructor  LineRef . Init (Lii 
begin 

LineNo  :=  Line; 
end; 

(  IdentRef  constructor  ) 


(  Tree  of  IdentRef  objects  ) 

{  Current  line  number  ) 

{  Counter  used  by  PrintLine  } 
(  Standard  input  buffer  ) 

(  Standard  output  buffer  ) 


:  Integer); 


constructor  IdentRef . Init (S:  Ident); 
begin 

Lines. Init; 

GetMem(Name,  Length (S)  +  1); 

NameA  :=  S; 
end; 

{  IdentRef  destructor  ) 
destructor  IdentRef .Done; 
begin 

FreeMem (Name,  Length (NameA)  +  1); 
Lines. Done; 
end; 


Listing  Two 

program  CrossRef; 
!$S-} 

f$M  8192,8192,6553601 


(  Compare  keys  of  two  IdentRef  objects  in  an  IdentTree  ) 

function  IdentTree. Compare (Keyl,  Key2:  Pointer):  Integer; 
begin 

if  IdentPtr (Keyl) A  <  IdentPtr  ( Key 2 ) A  then  Compare  :=  -1  else 
if  IdentPtr (Keyl) A  >  IdentPtr  (Key2) A  then  Compare  :=  1  else 
Compare  :=  0; 
end; 


uses  Contain; 


const 

MaxIdentLen  =  20;  {  Maximum  identifier  length  ) 

LineNoWidth  =  6;  {  Width  of  line  numbers  in  listing  ) 

RefPerLine  =  8;  {  Line  numbers  per  line  in 

cross-reference  ) 

IOBufSize  =  4096;  {  Input/Output  buffer  size  ) 

Formfeed  =  #12; 

EndOfLine  =  #13; 

EndOfFile  =  #26; 

type 

{  Input/Output  buffer  ) 


(  Return  the  key  of  an  IdentRef  object  in  an  IdentTree  ) 

function  IdentTree. GetKey (N:  TreeNodePtr):  Pointer; 
begin 

GetKey  :=  IdentRefPtr (N) A .Name; 
end; 

1  Insert  keywords  in  identifier  tree  ) 

procedure  InsertKeyWord (L,  R:  Integer); 
var 

I:  Integer; 
begin 

I  :=  (L  +  R)  div  2; 

Idents . Insert (New (IdentRefPtr,  Init (Keyword [I] ) ) ) ; 
if  L  <  I  then  InsertKeyWord (L,  I  -  1); 
if  I  <  R  then  InsertKeyWord (I  +  1,  R) ; 
end; 
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{ $F+ } 

(  Create  and  return  a  new  identRef  object  } 

function  Newldent (Key :  Pointer):  TreeNodePtr; 
var 

P:  IdentRefPtr; 
begin 

New(P,  Init (IdentPtr (Key) A) ) ; 

PA. Lines. Append (New (LineRefPtr,  Init (LineCount) ) ) ; 

Newldent  :=  P; 
end; 

($F-) 

(  Process  input  file  and  print  listing  ) 

procedure  ProcessFile; 
var 

Ch:  Char; 

1  Get  next  character  from  input  file  ) 

procedure  GetChar; 

begin 

if  Eof  then  Ch  :=  EndOfFile  else 
begin 

if  Ch  =  EndOfLine  then 
begin 

Inc (LineCount) ; 

Write (LineCount :  LineNoWidth,  '); 
end; 

if  not  Eoln  then 
begin 

Read(Ch) ; 

Write (Ch) ; 

if  (Ch  >=  'a')  and  (Ch  <=  'z')  then  Dec(Ch,  32); 
end  else 
begin 
ReadLn; 

WriteLn; 

Ch  :=  EndOfLine; 
end; 
end; 
end; 

(  Get  next  token  from  input  file  ) 
procedure  GetToken; 

{  Get  identifier  from  input  file  and  enter  into  tree  ) 

procedure  Getldent; 
var 

Name:  Ident; 

P:  LineRefPtr; 
begin 

Name  :  =  "  ; 
repeat 

if  Length (Name)  <  MaxIdentLen  then 
begin 

Inc (Name [0] ) ; 

Name [Length (Name) ]  :=  Ch; 
end; 

GetChar; 

until  ((Ch  <  '0')  or  (Ch  >  '9'))  and 

((Ch  <  'A')  or  (Ch  >  'Z'))  and  (Ch  <>  '_'); 
with  IdentRefPtr (Idents.Search(  Name,  Newldent) )A  do 
if  not  Lines. Empty  then 

if  LineRefPtr (Lines. Last) A.LineNo  <>  LineCount  then 
Lines .Append (New (LineRefPtr,  Init (LineCount) ) ) ; 

end; 

begin  (  GetToken  } 
case  Ch  of 

'A'  .  .'V  ,  '_'  : 

Getldent; 

repeat 

repeat 

GetChar; 

until  (Ch  =  "  " )  or  (Ch  =  EndOfFile); 

GetChar; 

until  (Ch  <>  ''''); 

'$'  : 
repeat 
GetChar; 

until  ( (Ch  <  '0')  or  (Ch  >  '9'))  and 
((Ch  <  'A')  or  (Ch  >  'F')); 

begin 

repeat 

GetChar; 

until  (Ch  =  ')')  or  (Ch  =  EndOfFile); 

GetChar; 

end; 

'  ('  : 
begin 
GetChar; 

if  Ch  =  ' *'  then 
begin 
GetChar; 
repeat 

while  (Ch  <>  '*')  and  (Ch  <>  EndOfFile)  do  GetChar; 
GetChar; 

until  (Ch  =  ')')  or  (Ch  =  EndOfFile); 


GetChar; 

end; 

end; 

else 

GetChar; 

end; 

end; 

begin  f  ProcessFile  ) 

Ch  :=  EndOfLine; 

GetChar; 

while  (Ch  <>  EndOfFile)  do  GetToken; 

Write (FormFeed,  EndOfLine); 
end; 

($F+) 

f  Print  a  LineRef  object  ) 

procedure  PrintLine(N:  ListNodePtr) ; 
begin 

if  RefCount  =  RefPerLine  then 
begin 
WriteLn; 

Write ('  MaxIdentLen  +  1); 

RefCount  :=  0; 
end; 

Inc (RefCount) ; 

Write (LineRefPtr (N) A . LineNo:  LineNoWidth) ; 
end; 

(  Print  an  IdentRef  object  ) 

procedure  PrintRef(N:  TreeNodePtr); 
begin 

with  IdentRefPtr (N)A  do  if  not  Lines. Empty  then 
begin 

Write (NameA,  '  MaxIdentLen  +  1  -  Length (NameA) ) ; 
RefCount  :=  0; 

Lines. ForEach (PrintLine) ; 

WriteLn; 

end; 

end; 


($F-) 

(  Print  identifier  tree  ) 

procedure  Printldents; 
begin 

I dents .ForEach (PrintRef) ; 

Write (FormFeed,  EndOfLine); 
end; 

begin  (  CrossRef  ) 

Idents. Init; 

LineCount  :=  0; 

if  Pos('.',  ParamStr(l))  =  0  then 
Assign (Input,  ParamStr(l)  +  '.PAS') 
else 

Assign (Input,  ParamStr (1) ) ; 

Reset  (Input) ; 

SetTextBuf (Input,  InputBuf fer) ; 
SetTextBuf (Output,  OutputBuf fer) ; 
InsertKeyWord(l,  KeyWordCount) ; 
ProcessFile; 

Printldents; 

Idents. Done; 
end. 


End  listings 
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Listing  One  (Text  begins  on  page  66.) 

(Use  this  procedure  to  initialize  a  new  KRAM  file.  It  sets  up  the) 

(key  length  and  the  data  length  according  to  the  input  arguments.) 

(KRAM.PAS  -  A  Keyed  Random  Access  Method  for  Turbo  Pascal  5.0.) 

(The  high  data  block  number  is  set  to  1  and  data  block  #1  is) 

(Copyright  (c)  1989  by  Chrysalis  Software  Corp.  All  rights  reserved.) 

(initialized  to  zeroes  (an  empty  block).  The  index  block  is  set  to) 

(Written  by  Steve  Heller.) 

(all  l's,  so  that  all  accesses  will  go  to  the  empty  data  block.) 

($V-) 

VAR 

KramFile: file; 

program  KramTest; 

Index  :  KramlndexType; 

Data  :  KramDataType; 

uses  Crt; 

Params  :  KramParamType; 
i  :  integer; 

const 

PARAMSIZE  =  128;  (the  size  of  the  parameter  block,  in  bytes) 

BEGIN 

DATASIZE  =  2048;  (the  size  of  a  data  block,  in  bytes) 

Assign (KramFile, FileName) ; 

INDEXCOUNT  =  1024;  (the  number  of  index  entries.  Must  be  a  power  of  2.) 

Rewrite (KramFile, 1) ; 

INDEXSIZE  =  INDEXCOUNT  *  Sizeof (integer) ;  (the  size  of  the  index  block) 

FillChar (Params .Dummy, SizeOf (Params .Dummy) , 0) ; 

type 

KramDataType  =  array [1. .DATASIZE]  of  byte; 

Params .KeyLength  :=  KeyLength; 

KramDataPtr  =  "KramDataType; 

Params. DataLength  :=  DataLength; 

KramlndexType  =  array (1 .. INDEXCOUNT]  of  integer; 

KramlndexPtr  =  "KramlndexType; 

(the  highest  data  block  number  in  use  is  #1) 

Params. HighBlock  :=  1; 

(The  variant  record  type  below  is  used  so  that  we  can  add  new) 

(parameters  if  needed,  without  changing  the  size  of  the  parameter) 

BlockWrite (KramFile, Params, SizeOf (Params) ) ; 

(block  in  the  data  file.) 

KramParamType  =  record 

(Initialize  the  index  block  to  all  l's,  as  only  data  block  #1  exists) 

case  integer  of 

0:  ( 

FOR  i  :-  1  TO  INDEXCOUNT  DO 

Index [i]  :=  1; 

(the  items  below  are  saved  from  one  run  to  another) 

KeyLength: integer; 

BlockWrite (KramFile, Index, SizeOf (Index) ) ; 

DataLength : integer; 

HighBlock: integer; 

(Initialize  the  first  data  block  to  all  zeroes) 

(the  items  above  are  saved  from  one  run  to  another) 

FOR  i  :-  1  TO  DATASIZE  DO 

(the  ones  below  are  valid  only  during  the  current  run) 

Data(i]  :=  0; 

CurrentBlock : integer; 

BlockModified: boolean; 

BlockWrite (KramFile, Data, SizeOf (Data) ) ; 

DataPtr: KramDataPtr; 

IndexPtr : KramlndexPtr; 

) ; 

1:  (Dummy : array (1 . .PARAMSIZE]  of  byte); 

Close (KramFile) ; 

END; 

end; 

KramParamPtr  =  A KramParamType; 

PROCEDURE  KramOpen(VAR  KramFile : file; KramFileName: string) ; 

FileRec  =  RECORD 

(Use  this  procedure  to  open  the  file.  It  reads  the  parameter  block) 

Handle  ;  word; 

(and  the  index  block  from  the  beginning  of  the  file  and  allocates) 

Mode  :  word; 

(space  for  the  data  block.) 

RecSize:  word; 

Private:  array  [1..26]  OF  byte; 

VAR 

RecsRead  :  integer; 

(note:  this  is  a  nonstandard  declaration) 

ParamPtr  :  KramParamPtr; 

UserData:  array  [1..4]  OF  pointer; 

BEGIN 

Name  :  array  [0..79]  OF  char; 

END; 

Assign (KramFile, KramFileName) ; 

Reset (KramFile, 1) ; 

FUNCTION  HashCode (Key  :  string) :longint; 

New (ParamPtr) ; 

(Use  this  function  to  calculate  a  pseudo-random  number  based  on  the) 

KramParamPtr (FileRec (KramFile) .UserData (1) )  :=  ParamPtr; 

(value  of  its  argument.  The  result  is  used  to  determine  which  index) 

(entry  will  be  used  to  access  the  record  with  the  given  key.  The) 

BlockRead (KramFile, ParamPtrA, SizeOf (KramParamType) , RecsRead) ; 

(algorithm  used  here  is  appropriate  for  ASCII  key  values,  as  it  uses) 

IF  RecsRead  <>  SizeOf (KramParamType)  THEN 

(the  low  five  bits  of  each  byte  of  the  key.) 

BEGIN 

WriteLn (' Invalid  KRAM  file:  ', KramFileName) ; 

VAR 

Halt  (1) ; 

i  :  integer; 

END; 

result  :  longint; 

tempi  :  longint; 

New (ParamPtrA . IndexPtr) ; 

temp2  :  longint; 

New (ParamPtrA .DataPtr) ; 

bytetemp  :  byte; 

ParamPtrA. CurrentBlock  :=  0; 

BEGIN 

BlockRead (KramFile,  ParamPtrA . IndexPtrA, 

SizeOf (KramlndexType) ,  RecsRead) ; 

result  :=  0; 

FOR  i  :=  1  TO  length (Key)  DO 

IF  RecsRead  <>  SizeOf (KramlndexType)  THEN 

BEGIN 

BEGIN 

WriteLn (' Invalid  KRAM  file:  ', KramFileName) ; 

tempi  :=  result  shl  5; 

Halt  (1) ; 

temp2  :=  result  shr  27; 

END; 

result  :=  tempi  or  temp2; 

bytetemp  :=  ord(Key[i]); 

END; 

result  :=  result  xor  bytetemp; 

END; 

PROCEDURE  KramClose (var  KramFile : file) ; 

HashCode  :=  result; 

(Use  this  procedure  to  close  the  file  after  use.  It  also  deallocates) 

END; 

(the  dynamic  storage  used  for  the  parameter,  index,  and  data  blocks.) 

PROCEDURE  SeekBlock (VAR  KramFile  :  file;  BlockNum  :  integer); 

(for  example,  you  MUST  close  the  file  to  ensure  that  all  the  records) 

(have  been  written  to  the  file.) 

(Use  this  procedure  to  position  the  file  pointer  to  a  particular  data) 

(block.  In  order  to  do  this,  we  must  skip  the  parameter  block  and  } 

(the  index  block.  Also  note  that  the  first  data  block  is  #1.) 

ParamPtr  :  KramParamPtr; 

VAR 

BEGIN 

BlockPosition  :  longint; 

BEGIN 

ParamPtr  :=  KramParamPtr (FileRec (KramFile) .UserData [1] ) ; 

SeekBlock (KramFile, ParamPtrA .CurrentBlock)  ; 

BlockWrite (KramFile, ParamPtr" .DataPtrA,  DATASIZE) ; 

BlockPosition  :=  PARAMSIZE  +  INDEXSIZE  +  (DATASIZE  *  (BlockNum-1) ) ; 

Seek (KramFile,  BlockPosition) ; 

Dispose (ParamPtr" .DataPtr)  ; 

Dispose (ParamPtr" . IndexPtr) ; 

Dispose (ParamPtr) ; 

PROCEDURE  Kramlnit (FileName  :  string;  KeyLength,  DataLength:  integer); 

(continued  on  page  118) 
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Listing  One  (Listing  continued,  text  begins  on  page  66.) 

Close (KramFile) ; 

END; 

FUNCTION  KramAdd(VAR  KramFile  :  file;  KeyValue  :  string; 

DataValue  ;  string) rboolean; 

(Use  this  procedure  to  add  records  to  a  KRAM  file  that  has  been  opened) 
(by  KramOpen.  You  must  supply  the  file  pointer  that  was  returned  by} 
(KramOpen  in  "KramFile", the  key  in  "KeyValue",  and  the  data  in} 
("DataValue".  The  algorithm  is  known  as  "extensible  hashing".} 

VAR 

ParamPtr  :  KramParamPtr; 

LowDataPtr  ;  KramDataPtr; 

HighDataPtr  :  KramDataPtr; 

HashVal  :  longint; 

BlockNumber  :  integer; 

TempBlockNumber  :  integer; 

RecordLength  :  integer; 
i,j,k  ;  integer; 

SlotFound:  boolean; 

FoundFirst  :  boolean; 

FoundLast  :  boolean; 

FirstBlock  :  integer; 

LastBlock  :  integer; 

MidBlock  :  integer; 

KramFileName  :  string; 

TempKeyValue  :  string; 

OldOffset  :  integer; 

LowOffset  ;  integer; 

HighOffset  :  integer; 

Duplicate  :  boolean; 

KeepLooking  :  boolean; 

BEGIN 

ParamPtr  :=  KramParamPtr (FileRec (KramFile) .UserData[l] ) ; 

KramFileName  FileRec (KramFile) .Name; 

RecordLength  :=  ParamPtrA .KeyLength  +  ParamPtr* .DataLength; 

REPEAT 

HashVal  HashCode (KeyValue)  and  (INDEXCOUNT  -  1); 

BlockNumber  :=  ParamPtr* . IndexPtr* [HashVal+1 ) ; 

IF  ParamPtr* .CurrentBlock  <>  BlockNumber  THEN 
BEGIN 

IF  (ParamPtr*. BlockModif ied) 
and  (ParamPtr* .CurrentBlock  <>  0)  THEN 
BEGIN 

ParamPtr*. BlockModif ied  :=  FALSE; 

SeekBlock (KramFile,  ParamPtr* . CurrentBlock) ; 

BlockWrite (KramFile, ParamPtr* .DataPtr*, DATASIZE) ; 

END; 

SeekBlock (KramFile, BlockNumber) ; 

BlockRead (KramFile, ParamPtr* .DataPtr*, DATASIZE) ; 

ParamPtr* .CurrentBlock  :=  BlockNumber; 

END; 


Duplicate  :=  FALSE; 

KeepLooking  :=  TRUE; 

SlotFound  :=  FALSE; 
i  :=  1; 

OldOffset  :=  1; 

(initialize  length  of  temporary  string  used  for  comparison) 

TempKeyValue (0)  :=  char (ParamPtr* .KeyLength) ; 

WHILE  KeepLooking  AND  (i  <=  DATASIZE  DIV  RecordLength)  DO 
BEGIN 

IF  ParamPtr*. DataPtr* (OldOffset)  =  0  THEN 
BEGIN 

KeepLooking  :=  FALSE; 

SlotFound  :=  TRUE; 

END 

ELSE 

BEGIN 

Move (ParamPtr*. DataPtr* [OldOffset] , TempKeyValue [1} , ParamPtr* 

.KeyLength) ; 

IF  TempKeyValue  =  KeyValue  THEN 
BEGIN 

Duplicate  :=  TRUE; 

KeepLooking  :=  FALSE; 

END 

ELSE 

BEGIN 

OldOffset  :=  OldOffset  +  RecordLength; 
i  :=  i  +  1; 

END; 

END; 

END; 

IF  SlotFound  THEN 
BEGIN 

Move (KeyValue [1 ] , ParamPtr* . DataPtr* [OldOffset] , 

ParamPtr* .KeyLength) ; 

Move (DataValue [ 1 ] , 

ParamPtr* .DataPtr* [OldOf f set+ParamPtr* .KeyLength] , 

ParamPtr* .DataLength) ; 

(continued  on  page  120) 
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Listing  One  (Listing  continued,  text  begins  on  page  66.) 

ParamPtrA .BlockModified  :=  TRUE; 

END 

ELSE  IF  Duplicate  =  FALSE  THEN 
BEGIN 

{First  we  must  determine  how  many  index  entries  are  affected) 

{by  the  split) 

FoundFirst  :=  FALSE; 

FoundLast  :=  FALSE; 

LastBlock  :=  INDEXCOUNT; 

FOR  i  :=  1  TO  INDEXCOUNT  DO 
BEGIN 

IF  (ParamPtr*. IndexPtr* [i]  =  BlockNumber) 
and  {not  FoundFirst)  THEN 
BEGIN 

FirstBlock  :=  i; 

FoundFirst  :=  TRUE; 

END; 

IF  (ParamPtrA . IndexPtrA [i]  <>  BlockNumber) 
and  FoundFirst  and  (not  FoundLast)  THEN 
BEGIN 

LastBlock  :=  i  -  1; 

FoundLast  :=  TRUE; 

END 

END; 

IF  FirstBlock  >=  LastBlock  THEN 
(we  are  out  of  room) 

BEGIN 

WriteLn('KRAM  file:  ' , KramFileName, '  is  full.'); 

Halt  (1) ; 

END; 

(Now  we  have  to  allocate  another  block  for  the  split.) 

ParamPtrA.HighBlock  :  =  ParamPtrA .HighBlock  +  1; 

MidBlock  :=  (FirstBlock  +  LastBlock  -  1)  DIV  2; 

{We  will  assign  the  items  that  have  the  higher  hash  code) 

(to  the  new  block) 

FOR  i  :=  MidBlock+1  TO  LastBlock  DO 

ParamPtrA . IndexPtrA [i]  :=  ParamPtrA .HighBlock; 

(Now  we  have  to  go  through  all  the  items  in  the  block  to  be  split) 

(and  assign  them  to  the  old  block  or  the  new  one  according  to  their) 

{new  hash  codes,  1  bit  longer  than  the  previous  ones.  An  extra) 
{temporary  block  makes  this  easier.) 

New(LowDataPtr) ; 

New(HighDataPtr) ; 

FillChar (LowDataPtrA, SizeOf (LowDataPtrA) , 0) ; 

FillChar (HighDataPtrA, SizeOf (HighDataPtrA) , 0) ; 

OldOffset  :=  1; 

LowOffset  :=  1; 

HighOffset  :=  1; 

FOR  i  :=  1  TO  DATASIZE  DIV  RecordLength  DO 
BEGIN 

Move (ParamPt r A . DataPtr A [OldOffset ] , TempKeyValue [ 1 ) , 
ParamPtrA.KeyLength) ; 

TempKeyValue [0]  :=  char (ParamPtr* .KeyLength) ; 

HashVal  :  =  HashCode (TempKeyValue)  and  (INDEXCOUNT  -  1); 
TempBlockNumber  :=  ParamPtr* . IndexPtr* [HashVal+1 ] ; 

IF  TempBlockNumber  =  BlockNumber  THEN 
{send  to  the  lower  one) 

BEGIN 

Move (ParamPtrA .DataPtrA [OldOffset] , 

LowDataPtrA [LowOffset] , RecordLength) ; 

LowOffset  :=  LowOffset  +  RecordLength; 

END 

ELSE 

BEGIN 

Move (FaramPtrA .DataPtrA [OldOffset] , 

HighDataPtrA [HighOffset ], RecordLength) ; 

HighOffset  :=  HighOffset  +  RecordLength; 

END; 

OldOffset  :=  OldOffset  +  RecordLength; 

END; 

SeekBlock (KramFile, BlockNumber) ; 

BlockWrite (KramFile, LowDataPtrA, DATASIZE) ; 

SeekBlock (KramFile, ParamPtr A . HighBlock) ; 

BlockWrite (KramFile,  HighDataPtrA,  DATASIZE)  ; 

Dispose (LowDataPtr) ; 

Dispose (HighDataPtr) ; 

{Make  sure  the  same  block  isn't  used  the  the  next  time  we  have  to) 

{expand  the  file.  Also  note  that  the  data  block  is  out  of  date.) 
ParamPtrA .CurrentBlock  :=  0; 

Seek (KramFile, 0) ; 

BlockWrite (KramFile, ParamPtrA, SizeOf (KramParamType) ) ; 

BlockWrite (KramFile, ParamPtr A . IndexPtr A , 

SizeOf (KramlndexType) ) ; 

END; 

UNTIL  SlotFound  or  Duplicate; 

IF  Duplicate  THEN 
KramAdd  :=  FALSE 
ELSE 

KramAdd  :=  TRUE; 

END; 

FUNCTION  KramRead(var  KramFile: file;  KeyValue:  string; 


var  DataValue:  string) :boolean; 

{Use  this  function  to  read  records  from  a  KRAM  file  that  has  been) 
(opened  by  KramOpen.  You  must  supply  the  key  in  "KeyValue"  and  the) 
{file  pointer  that  was  returned  by  KramOpen  in  "KramFile".  The  data) 
{stored  under  that  key  will  be  returned  in  "DataValue".  The  return) 
{value  is  TRUE  if  the  record  was  found,  and  FALSE  if  it  wasn't.) 

VAR 

ParamPtr  :  KramParamPtr; 

HashVal  :  longint; 

BlockNumber  :  integer; 

RecordLength  :  integer; 
i,j,k  :  integer; 

SlotFound:  boolean; 

KeepLooking  :  boolean; 

KramFileName  :  string; 

TempKeyValue  :  string; 

DataOffset  :  integer; 

BEGIN 

ParamPtr  :=  KramParamPtr (FileRec (KramFile) .UserData [ 1] ) ; 
KramFileName  :=  FileRec (KramFile) .Name; 

RecordLength  :=  ParamPtr A .KeyLength  +  ParamPtr* .DataLength; 

HashVal  HashCode (KeyValue)  and  (INDEXCOUNT  -  1); 

BlockNumber  :=  ParamPtr* . IndexPtr* [HashVal+1] ; 

IF  ParamPtr* .CurrentBlock  <>  BlockNumber  THEN 
BEGIN 

IF  (ParamPtr*. BlockModified) 
and  (ParamPtr* .CurrentBlock  <>  0)  THEN 
BEGIN 

ParamPtr* .BlockModified  :=  FALSE; 

SeekBlock (KramFile, ParamPtr*. CurrentBlock) ; 

BlockWrite (KramFile, ParamPtr* .DataPtr*, DATASIZE) ; 

END; 

SeekBlock (KramFile, BlockNumber) ; 

BlockRead (KramFile, ParamPtr* . DataPtr*, DATASIZE)  ; 

ParamPtr* .CurrentBlock  :=  BlockNumber; 

END; 


KeepLooking  :=  TRUE; 

SlotFound  :=  FALSE; 
i  :-  1; 

DataOffset  :=  1; 

{initialize  length  of  temporary  string  used  for  comparison) 
TempKeyValue [0]  :=  char (ParamPtr* .KeyLength) ; 

WHILE  KeepLooking  AND  (i  <=  DATASIZE  DIV  RecordLength)  DO 
BEGIN 

IF  ParamPtr* .DataPtr* [DataOffset]  =  0  THEN 
KeepLooking  :=  FALSE 
ELSE 
BEGIN 

Move (ParamPtr* .DataPtr* [DataOffset] , TempKeyValue [1] , ParamPtr* 

.KeyLength) ; 

IF  TempKeyValue  =  KeyValue  THEN 
BEGIN 

SlotFound  :=  TRUE; 

KeepLooking  :=  FALSE; 

END 

ELSE 

BEGIN 

DataOffset  :=  DataOffset  +  RecordLength; 

i  :=  i  +  1; 

END; 

END; 

END; 


IF  SlotFound  THEN 
BEGIN 

Move (ParamPtr* .DataPtr* [DataOf fset+ParamPtr* . KeyLength] , 
DataValue [ 1 ] , ParamPtr* . DataLength) ; 

DataValueJO]  :=  char (ParamPtr* .DataLength) ; 

KramRead  :=  TRUE; 

END 

ELSE 

KramRead :=  FALSE; 

END; 


PROCEDURE  Kramlnfofvar  KramFile : file;  var  KeyLength:  integer; 
var  DataLength:  integer); 

(Use  this  procedure  to  get  the  key  and  data  lengths  from  a  KRAM  file  that  has) 
(been  opened  by  KramOpen.  You  must  supply  the  file  pointer  that  was  returned) 
{by  KramOpen  in  "KramFile".) 


ParamPtr  :  KramParamPtr; 

BEGIN 

ParamPtr  :=  KramParamPtr (FileRec (KramFile) .UserData [1] ) ; 
KeyLength  :=  ParamPtr* .KeyLength; 

DataLength  :=  ParamPtr* .DataLength; 
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VAR 

KramTestFile  :  file; 

FileName  :  string; 

DataFileName  :  string; 

KeyLength  :  integer; 

DataLength  :  integer; 

KraraFile  :  file; 

Ok  :  boolean; 

InputFile  :  text; 

Key  :  string; 

RecNum  :  integer; 

TestRecNum  :  integer; 

RecNumStr  :  string; 

InputFileBuf  :  array  [1.. 10240]  of  char; 
Create  :  string; 

Status  :  integer; 

ReadStatus  :  boolean; 

AddStatus  :  boolean; 

Temp  :  string; 

Data  :  string; 

TempKey  :  string; 

TempData  :  string; 


ReadLn (InputFile, Temp) ; 

Key  :=  copy (Temp, 1,  KeyLength) ; 

TempData  :=  copy (Temp, KeyLength+1, DataLength) ; 

ReadStatus  :=  KramRead (KramTestFile, Key, Data) ; 

IF  Not  ReadStatus  THEN 
BEGIN 
WriteLn; 

WriteLn('Key  ', TempKey, '  not  found.'); 

END; 

IF  TempData  <>  Data  THEN 
BEGIN 
WriteLn; 

WriteLn (' Record  number  ', RecNum, '  does  not  match'); 
END; 

END; 


Close (InputFile) ; 
KramClose (KramTestFile) ; 


End  listing  One 


ClrScr; 

WriteLn ('KRAM. PAS  -  A  Keyed  Random  Access  Method  for  Turbo  Pascal  5.0.'); 

WriteLn ('Copyright  (c)  1989  by  Chrysalis  Software  Corp.  All  rights  reserved.'); 
WriteLn ('Written  by  Steve  Heller.'); 

WriteLn; 

WriteLn {'This  program  is  shareware:  if  you  find  it  useful,  you  should'); 

WriteLn ('register  it  by  sending  a  check  in  the  amount  of  $39.95,  '); 

WriteLn ('payable  to  Chrysalis  Software  Corporation,  to  the  following  adddress' ) ; 
WriteLn; 

WriteLn (' Chrysalis  Software  Corporation'); 

WriteLn ('P.  0.  Box  0335'); 

WriteLn ('Baldwin,  NY  11510'); 

WriteLn; 

WriteLn ('Registered  users  will  receive  an  updated  version  of  the  program,'); 
WriteLn (' incorporating  all  of  the  optimizations  and  extensions  mentioned'); 
WriteLn('in  this  article.'); 

WriteLn; 

Write {'Please  hit  ENTER  to  continue.'); 

ReadLn (FileName) ; 

ClrScr; 

Write ('Please  enter  the  name  of  the  data  file  to  be  used  for  input:  '); 
ReadLn (DataFileName) ; 

Write ('Please  enter  the  name  of  the  KRAM  file:  '); 

ReadLn (FileName) ; 

Write ('Create  the  KRAM  file  (Y/N) :  '); 

ReadLn (Create) ; 

IF  (Create (1]  =  '  Y' )  or  (Created)  =  'y' )  THEN 
BEGIN 

Write (' Please  enter  the  key  length:  '); 

ReadLn (KeyLength) ; 

Write ('Please  enter  the  data  length:  '); 

ReadLn (DataLength) ; 

Assign (InputFile, DataFileName) ; 

Reset (InputFile)  ; 

SetTextBuf (InputFile, InputFileBuf) ; 

Kramlnit (FileName, KeyLength,  DataLength) ; 

KramOpen (KramTestFile, FileName) ; 

RecNum  :=  0; 

AddStatus  :=  TRUE; 

WHILE  NOT  EOF (InputFile)  DO 
BEGIN 

IF  RecNum  Mod  10  =  0  THEN 
Write (RecNum: 5) ; 

RecNum  :=  RecNum  +  1; 

ReadLn (InputFile,  Temp) ; 

Key  :=  Copy (Temp,  1,  KeyLength) ; 

Data  :=  Copy (Temp, KeyLength+1 , length (Temp) ) ; 

AddStatus  :=  KramAdd (KramTestFile, Key, Data) ; 

IF  AddStatus  =  FALSE  THEN 
BEGIN 
WriteLn; 

WriteLn ('Unable  to  add  key:  ',Key); 

END; 

END; 


Listing  Two 


{ KRAMDATA . PAS  -  generates  data  for  KRAM  testing) 
(890226:1245) 

VAR 

s  :  String[255); 
t  :  Text; 
n  :  Longlnt; 
i  :  Longlnt; 
j  :  Integer; 

KeyLength  :  Integer; 

DataLength  :  Integer; 

FName  :  String [80); 


Write ('Name  of  data  file  to  be  generated:  '); 
ReadLn (FName) ; 

Write ('Number  of  items  to  generate:  '); 

ReadLn (n) ; 

Write (' Length  of  Keys:  '); 

ReadLn (KeyLength) ; 

Write (' Length  of  Data:  '); 

ReadLn (DataLength) ; 

Assign (t,Fname) ; 

Rewrite  (t) ; 

FOR  i  :=  1  TO  N  DO 
BEGIN 

IF  i  =  1000*int (i/1000)  THEN  Write(i:10); 
s  :  =  "  ; 

FOR  j  :=  1  TO  KeyLength  DO 
s  :=  s  +  chr(random(26)+65) ; 

Write (t,s) ; 

WriteLn (t, i :DataLength)  ; 

END; 


End  Listings 


WriteLn; 

Close (InputFile) ; 

KramClose (KramTestFile) ; 

END; 

Assign (InputFile, DataFileName) ; 

Reset (InputFile) ; 

SetTextBuf (InputFile, InputFileBuf) ; 

KramOpen (KramTestFile, FileName) ; 

Kramlnfo (KramTestFile, KeyLength, DataLength) ; 
RecNum  :=  0; 

WHILE  NOT  EOF (InputFile)  DO 
BEGIN 

IF  RecNum  Mod  10  =  0  THEN 
Write (RecNum: 5)  ; 

RecNum  :=  RecNum  +  1; 
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EXAMINING  ROOM 


Listing  One  (Text  begins  on  page  72.) 

program  test 

*  purpose  is  to  test  SGI  parallelization  scheme  for  loop  selection, 

*  numerically-intensive  calculations,  and  total  reduction.  See  text 

*  for  details. 

parameter  (MAXFIRST=250,  MAXSECOND=250,  MAXTHIRD=10) 
real*8  a (MAXTHIRD, MAXSECOND, MAXFIRST) 
real*8  b (MAXTHIRD, MAXSECOND, MAXFIRST) 
real*8  sub_total (MAXFIRST) ,  partial_total (4) 
real*8  d (MAXTHIRD),  c,  tmp  !  local  variables 
real*8  dist (MAXSECOND, MAXFIRST) ,  grand_total 
real*8  grand_total  !  test  for  proper  operation 

logical  parallel  !  selects  2-version  loops 

integer*4  iflag  !  used  to  show  LASTLOCAL  value 

data  parallel  /.false./ 

data  sub_total,  iflag  /MAXFIRST*0.0,  0/ 

*  outer  loop:  contains  both  interior  loops 


*  C$doacross  local (k, j,i, tmp, d,c) ,  share (a, b, sub_total, dist ) , 

*  C$S  lastlocal (iflag) 

do  i  =  1,  MAXFIRST 

*  first  inner  loop:  fills  arrays  a  and  b 


C$10  format (lx, ' grand  total  =  ' ,gl0 . 3, ' threads  = 
C$20  format (lx, ' parallel  iflag  =  ',il0) 

30  format (lx, ' grand  total  =  ',gl0.3) 

40  format (lx, ' scalar  iflag  =  ' , i 1 0 ) 
end 


Listing  Two 

(source  code) 

subroutine  example (a,  b,  c,  n) 
integer*4  n 

real*4  a(n),  b(n),  c(n) 

(additional  code) 

c$doacross  local (i,  x) 
do  i=l,  n 

x  =  a(n)  *  b(n) 
c (n)  =  x**2 
enddo 

(additional  code) 

return 

end 

(the  loop  is  transformed  to) 


*  C$doacross  local  (j,k,c) ,  share (i, a, b) 

do  j  =  1,  MAXSECOND 
do  k  -  1,  MAXTHIRD 

a(k,j,i)  -  dsqrt (dfloat (i* j*k) ) 
c  -  1.0  -  a (k, j, i) 

if  (c  .le.  0.0  .and.  i  .It.  j*k)  then 
c  =  -c 
else 

c  =  c**2 
endif 

b(k,j,i)  =  32* (dcos (c) **5) *dsin (c) - 

1  32* (dcos (c) **3) *dsin (c) + 

2  6*dcos(c) *dsin(c) 
enddo 

enddo 

*  seond  inner  loop:  determines  distance  and  starts  summation 


*  c$doacross  local ( j, k, d, tmp) ,  share (i, a, b, dist , sub_total) , 

*  c$&  lastlocal (if lag) 


subroutine  _example_l ( 

1  _local_start, 

2  _local_ntrip, 

3  _incr, 

4  _my_threadno) 

integer*4  _local_start,  _local_ntrip,  incr, 

integer*4  i  !  declared  local 

real*4  x  !  declared  local 

integer* 4  _tmp  !  created  local 

i  =  _local_start 
do  _tmp  =  1,  _local_ntrip 
x  =  a  (i)  *  b(i) 

c(i)  =  x**2 
i  =  i  +  _incr 
enddo 
return 
end 


index  starting 
number  of  loop 
index  increment 
unique  process 


do  j-l,  MAXSECOND 
tmp  =  0.0 

do  k  =  1,  MAXTHIRD 

d(k)  =  a (k, j, i)  -  b(k, j, i) 
enddo 

do  k  =  1,  MAXTHIRD 
tmp  =  tmp  +  d(k) **2 
enddo 

dist  ( j, i)  =  dsqrt (tmp) 
if  (dist ( j , i)  .le.  0.1)  iflag  =  iflag  +  1 
sub_total(j)  =  sub_total(j)  +  dist(j,i) 
enddo 
enddo 

*  the  next  section  is  an  example  of  sum  reduction  optimized  to  the 

*  parallel  environment  and  the  use  of  a  more  efficient  2  loop  summation 

*  if  -mp  option  is  active,  parallel  is  set  to  .true,  which  then 

*  selects  the  parallel  version 


C$  parallel  =  .true. 
grand_tot.al  =  0.0 

if  (parallel)  then  !  parallel  version 

C$  num_threads  =  mp_numthreads () 

ichunk  =  (MAXFIRST  +  (num_threads  -  1) ) /num_threads 

C$doacross  local (k,j), 

C$&  share (num_threads,partial_total, sub_total, ichunk) 

do  k  =  1,  num_threads  !  this  loop  is  parallelized 
partial_total (k)  =0.0 

do  j  =  k*ichunk  -  ichunk  +  1,  min (k* ichunk, MAXFIRST) 
partial_total (k)  =  partial  total  (k)  +  sub_total(j) 
enddo 
enddo 

do  j  =  1,  num_threads  !  smaller  loop  handled  as  scalar 
grand_total  =  grand_total  +  partial_total ( j) 
enddo 

else  !  the  scalar  version 

do  j  =  1,  MAXFIRST 

grand_total  =  grand_total  +  sub_total(j) 
enddo 
endif 


if  (parallel)  then 


c$ 

write 

(M0) 

grand_total,  num  threads 

c$ 

write  1 
else 

(*,20) 

iflag 

write  i 

(*,30) 

grand_total 

write  i 
endif 
stop 

(*,40) 

iflag 

,  14) 

End  Listing  One 


value 

executions 
ID  number 
_my_threadno 


End  Listings 
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PROGRAMMING  PARADIGMS 


Two  Early  Neural 
Net  Implementations 


There  is  exciting  work  being  done 
in  neural  networks,  such  as  the 
artificial  retina  project  that  Fran¬ 
cis  Crick  is  involved  with.  Unfor¬ 
tunately,  most  of  the  readily  accessible 
implementations  of  neural  network  al¬ 
gorithms  are  unimpressive.  The  reason 
is  that,  for  most  of  us,  a  “readily  acces¬ 
sible”  implementation  of  an  algorithm 
is  one  that  runs  on  a  sequential  ma¬ 
chine,  and  neural  networks  are  inher¬ 
ently  nonsequential.  They  are,  as  Dave 
Parker  defined  them  here  last  month, 
parallel  implementations  of  minimiza¬ 
tion  algorithms.  The  algorithms  them¬ 
selves  can  be  interesting  to  examine, 
and  last  month  we  looked  at  some  of 
these  algorithms,  especially  Parker’s 
own  PC  implementation  of  the  back 
propagation  algorithm.  But  we  did  not 
address  the  other  half  of  the  issue:  The 
parallel  implementation. 

This  month  we'll  look  at  two  early 
implementations  of  neural  nets.  Both 
were  remarkable  successes  in  their  tar¬ 
get  domains.  Both,  interestingly,  used 
analog  devices  to  implement  parallel 
algorithms  in  largely  discrete  systems. 
Both  addressed  the  canonical  neural 
net  problem  of  visual  pattern  classifica¬ 
tion,  but  not  in  the  same  way.  And  both 
pose  some  challenges  for  current  neu¬ 
ral  net  implementations. 

Michael  Swaine 

MINOS  II 

MINOS  I  and  its  successors,  MINOS  II 
and  III,  were  built  at  SRI  under  contract 
from  the  U.S.  Army  over  a  period  from 
1958  to  1967.  Little  was  ever  published 
in  the  general  press  regarding  these 
machines,  but  they  were  described  in 
contemporary  documents,  all  unclassi¬ 
fied  and  available  to  the  curious.  That 
point  is  worth  making  because  of  the 
controversy  over  Minsky  and  Papert’s 
attack  on  neural  net  research  in  their 


1969  book  Perceptrons.  Information  on 
the  MINOS  project  was  at  least  accessi¬ 
ble  to  Minsky  and  Papert  before  they 
wrote  Perceptrons ,  and  there  is  evi¬ 
dence  that  Minsky  had  visited  the  SRI 
labs  and  was  aware  of  the  project’s 
objectives  and  results  in  the  1960s. 

The  stated  objective  of  the  MINOS 
work  was  “to  conduct  a  research  study 
and  experimental  investigation  of  tech¬ 
niques  and  equipment  characteristics 
suitable  for  practical  application  to  gra¬ 
phical  data  processing  for  military  re¬ 
quirements.”  I  take  that  to  mean  “to 
find  workable  algorithms  and  architec¬ 
tures  for  military  image  processing.” 
Or:  “See  if  you  can  build  us  a  machine 
to  spot  tanks  in  aerial  recon  photos.” 
The  SRI  team  approached  the  problem 
by  building  artificial  neurons  out  of 
multi-aperture  magnetic  cores  and  link¬ 
ing  them  in  a  network  under  the  con¬ 
trol  of  a  learning  algorithm.  Or:  They 
implemented  a  minimization  algorithm 
in  a  parallel  architecture.  Or:  They  built 
a  neural  net. 

As  illustrated  in  Figure  1,  MINOS  II 
most  clearly  shows  the  organization  of 
the  machines.  MINOS  II  consists  of  four 
units:  An  optical  preprocessor,  an  adap¬ 
tive  unit,  a  training/comparator  unit, 
and  an  output  unit.  The  preprocessor 
(see  Figure  2)  takes  the  data  in  the  form 
of  a  series  of  static  image  frames  from 
slides,  film,  or  a  TV  camera,  and  com¬ 
presses  each  frame  to  a  100-bit  word, 
which  it  passes  to  the  adaptive  unit. 
The  adaptive  unit,  a  neural  net,  per¬ 
forms  the  classification,  and  is  called 
adaptive  because  it  learns. 

There  are  two  phases  in  the  opera¬ 
tion  of  the  machine:  Training  and  clas¬ 
sifying.  The  training/comparator  unit 
is  only  active  during  the  training  phase, 
when  it  accepts  correct  responses  as 
input,  compares  them  to  the  responses 
generated  by  the  adaptive  unit,  and 
adjusts  parameters  called  weights  in 
the  adaptive  unit,  based  on  the  com¬ 


parison.  The  output  unit  displays  the 
results. 

The  preprocessor  contains  a  32  x  32 
array  of  lenses  in  front  of  a  photo¬ 
graphic  plate,  each  lens  reading  in  par¬ 
allel  from  a  storage  tube.  The  tube  gets 
its  data  from  a  television  camera  (there 
are  also  provisions  for  reading  from 
slides  and  film),  so  the  preprocessor  is 
essentially  reading  a  digitized  real-world 
image  off  a  “dumb”  retina.  As  Figure  3 
shows,  the  photographic  plate  has  a 
mask  for  each  of  the  1024  images,  and 
a  photocell  associated  with  each  image/ 
mask  generates  a  binary  signal  based 
on  the  amount  of  light  transmitted.  The 
preprocessor  then  employs  some  algo¬ 
rithm,  usually  a  task-specific  algorithm, 
to  reduce  the  1024  bits  to  a  single  100- 
bit  code  for  input  to  the  adaptive  unit. 
The  algorithm  is  generally  not  very  so¬ 
phisticated,  because  the  goal  is  not  true 
pattern  classification,  which  comes  later, 
but  simply  gross  data  reduction  with¬ 
out  losing  features  of  the  data  that  will 
be  needed  later  for  the  pattern  classifi¬ 
cation. 

The  adaptive  unit  is  made  up  of  thresh¬ 
old  logic  units  (TLUs)  in  two  layers. 
Each  TLU  computes  a  weighted  sum 
of  its  binary  inputs  and  generates  a 
binary  output,  which  is  1  if  the  weighted 
sum  exceeds  some  threshold,  and  -1 
otherwise.  Physically,  these  TLUs  are 
magnetic  cores.  The  inputs  to  the  63 
TLUs  in  the  first  layer  are  the  100  bits 
of  the  code  word  supplied  by  the  pre¬ 
processor;  that  is,  the  preprocessed  rep¬ 
resentation  of  an  input  image  frame. 
These  63  TLUs  feed  the  nine  TLUs  in 
the  second  layer,  each  second-layer  TLU 
taking  input  from  seven  first-layer  TLUs 
and  computing  a  majority-rule  func¬ 
tion,  outputting  a  1  only  if  a  majority 
of  its  inputs  are  Is.  The  use  of  these 
second-level  “committee”  TLUs  facili¬ 
tates  having  the  machine  respond  cor¬ 
rectly  without  requiring  that  every  TLU 
do  so.  (continued  on  page  128) 
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(continued  from  page  124) 

The  nine  second-level  TLUs  provide 
for  29,  or  512  different  outputs,  so  the 
machine  is  capable  of  classifying  its 
input  patterns  into  any  of  512  cate¬ 
gories.  During  the  training  phase,  the 
correct  9-bit  classification  is  input  for 
each  input  pattern,  and  the  training/ 
comparator  unit  compares  the  output 
of  the  adaptive  unit  with  this  correct 
answer.  If  they  are  not  equal  (as  they 
usually  will  not  be  early  in  training)  the 
training  algorithm  traces  back  through 
the  adaptive  unit’s  TLU  outputs  to  ad¬ 
just  weights  so  that  the  correct  response 
will  result  the  next  time  this  input  pat¬ 
tern  is  presented.  It  first  looks  at  second- 
level  TLUs,  then  at  the  first-level  TLUs 
feeding  the  incorrect  second-level  TLUs. 
The  algorithm  works  so  as  to  change  as 
few  weights  as  possible,  and  to  change 
those  weights  that  have  to  be  changed 
by  the  smallest  amount.  (The  weights, 
it  should  be  noted,  are  analog  values.) 

Testing  of  the  complex  MINOS  ma¬ 
chines  must  have  been  trying.  The  re¬ 
ports  on  the  work  mention  experiments 
terminated  because  of  things  like  mal¬ 
functioning  slide  projectors.  The  hard- 
earned  results  are  interesting. 

In  a  test  that  explored  its  ability  to 
pick  out  objects  against  a  noisy  back¬ 


ground,  MINOS  II  was  given  aerial  pho¬ 
tos,  some  of  which  showed  tanks,  and 
was  trained  to  pick  out  the  photos  with 
tanks.  It  learned  to  classify  a  set  of  50 
photos  after  28  iterations  of  the  set.  It 


Figure  1:  Organization  of  MINOS  II 


was  then  presented  with  a  new  set  of 
photos,  and  classified  32  out  of  34  of 
them  correctly,  at  least  one  of  its  two 
errors  being  “reasonable;"  —  one  a  hu¬ 
man  classifier  might  have  made  as  well. 


Figure  2:  Functional  diagram  of  optical  preprocessor 
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Another  test  employed  more  catego¬ 
ries,  requiring  MINOS  II  to  classify  stan¬ 
dard  military  map  symbols,  presented 
in  a  variety  of  orientations,  into  15  cate¬ 
gories.  With  a  total  of  30  symbols,  MI¬ 
NOS  II  was  trained  to  infallible  perfor¬ 
mance  on  this  set  in  40  iterations.  With 
75  symbols,  which  meant  five  different 
orientations  for  each  symbol,  it  had 
not  yet  learned  the  classifications  in  75 
iterations,  at  which  time  a  slide  projec¬ 
tor  problem  terminated  the  experiment. 
How  good  was  MINOS  II?  It’s  hard  to 
say.  William  Huber,  who  was  the  pro¬ 
ject  monitor  for  the  Army  for  the  dura¬ 
tion  of  the  project,  cited  one  complicat¬ 
ing  factor  in  his  1967  paper  on  the 
work:  The  system’s  tendency  to  “train 
around”  defective  operations,  much  as 
the  human  brain  relearns  over  new 
pathways  after  cells  are  damaged.  One 
day  a  power  plug  fell  out  of  the  wall 
and  the  machine  was  short  one  power 
supply;  the  only  evidence  of  this  was 
that  training  took  a  couple  more  itera¬ 
tions  than  usual.  Measures  of  perfor¬ 
mance  are  also  fairly  meaningless  when 
the  exact  task  cannot  easily  be  recon¬ 
structed  on  a  conventional  computer. 

One  thing  is  certain:  MINOS  I  knew, 
in  I960,  how  to  solve  the  XOR  problem 
that  typified  Minsky  and  Papert’s  dev¬ 
astating  critique  of  neural  networks  in 
Perceptrons.  In  fact,  the  MINOS  team 
used  a  generalization  of  the  XOR  prob¬ 
lem  as  a  routine  test  for  the  machine. 

The  generalization  of  the  XOR  prob¬ 
lem  was  to  differentiate  a  horizontal 
bar  from  a  vertical  one  anywhere  in  the 
pixel  figure,  and  the  retina  was  taken 
to  be  an  8  x  8,  toroidally  connected 
field,  with  the  right  edge  contiguous 
with  the  left,  the  top  with  the  bottom. 
The  toroidal  extension  allowed  eight, 
rather  than  five,  positions  in  each  ori¬ 
entation. 

There’s  one  challenge  for  any  cur¬ 
rent  neural  net:  Solve  the  toroidal  XOR 
problem. 

ADAM  I 

The  history  of  the  ADAM  project  is  so 
poorly  documented  as  to  be  lost  in 
legend;  I  couldn’t  find  the  date  on  which 
the  project  was  begun,  there  are  no 
reliable  contemporary  descriptions  from 
that  period,  and  there  have  been  acri¬ 
monious  debates  over  the  genesis  of 
the  device.  The  ADAM  I  has  always 
been  a  favorite  topic  in  the  popular 
press,  though,  and  it  has  been  reex¬ 
amined  recently  in  the  computer  sci¬ 
ence  literature  in  the  light  of  the  resur¬ 
gence  of  interest  in  neural  networks. 
ADAM  I  was  one  of  the  most  successful 
neural  net  implementations  ever.  It  was 
also  extremely  complex;  current  neural 
net  implementations  tend  to  be  much 


simpler,  and  this  is  probably  appropri¬ 
ate,  but  there  is  much  that  can  be  learned 
from  a  study  of  the  ADAM  I  architecture. 

Visual  images  are  generated  in  ADAM 
I  by  a  lens  that  projects  scenes  onto  a 
grid  of  photoreceptive  cells.  These  cells, 
along  with  two  layers  of  other  cells 
connected  in  a  network,  form  the  re¬ 
ceptor  net,  which  in  turn  connects  to  a 
highly  parallel  central  processing  sys¬ 
tem  that  in  a  sequential  machine  would 
be  called  the  CPU,  but  in  ADAM  I  is 
called  the  CNS  (central  neural  system?). 

There  are  actually  two  separate  and 
redundant  receptor  nets  to  provide  two 
images  for  further  processing.  This  sys¬ 
tem  of  organization  provides  the  raw 
data  for  the  perception  of  depth. 

There  is  a  high  degree  of  organiza¬ 
tion  and  differentiation  at  the  level  of 
the  receptor  net.  There  are  two  kinds 
of  photoreceptive  cells,  responding  to 
different  wave  lengths  of  light,  and  the 
receptors  have  many-to-one  and  one-to- 
many  connections  with  cells  in  the  next 
level.  These  intermediate  cells  usually 
have  many-to-one  but  sometimes  have 
one-to-many  connections  with  the  last 
layer  of  cells  in  the  receptor  net.  Then 
there  are  cells  that  carry  signals  be¬ 
tween  two  photoreceptive  cells,  allow¬ 
ing  interaction  and  inhibition,  and  there 
are  also  cells  that  carry  signals  back  to 
the  photoreceptors  from  lower  cells. 

This  complex  organization  permits 
a  lot  of  processing  and  transformation 
of  the  image  in  the  receptor  net  itself, 
yet  it  does  not  alter  the  overall  topogra¬ 
phy  of  the  initial  image.  The  main  pur¬ 
pose  of  the  receptor  net,  as  with  MI¬ 
NOS  II’s  preprocessor,  is  data  reduction. 
By  the  time  the  data  gets  through  the 
receptor  net,  the  number  of  bits  trans¬ 
mitted  has  been  reduced  by  a  factor  of 
1000.  The  receptors  are  extremely  sen¬ 
sitive,  responding  to  one  quantum  of 
light  energy,  and  despite  the  1000-fold 
data  reduction,  the  entire  system  is  also 
very  responsive:  Six  quanta  striking  six 
different  receptors  can  be  enough  to 
trigger  an  output  response. 


ADAM  I  was  not  the  first  device  to 
employ  this  general  kind  of  receptor- 
net  organization:  The  earlier-still  FROG 
I  showed  a  high  degree  of  specializa¬ 
tion  in  cells  in  its  receptor  net,  with 
four  or  five  kinds,  each  extracting  cer¬ 
tain  local  features  from  its  bitmap  in¬ 
put.  One  such  feature  was  the  center- 
surround  pattern,  which  responds  to  a 
pattern  consisting  of  a  small  dark  patch 
on  the  image,  surrounded  by  a  lighter 
area.  Other  specialized  cells  responded 
to  changes  from  one  image  to  another; 
that  is,  movements  of  objects  in  the 
imaging  field.  In  FROG  I  the  CNS  re¬ 
flected  the  four  or  five  cell  types  of  the 
receptor  net  and  allowed  the  system 
to  recognize  four  or  five  classes  of  vi¬ 
sual  phenomena.  In  a  sense,  that’s  all 
the  discriminating  it  could  do. 

Some  such  specialized  cells  were  re¬ 
tained  at  the  lower  levels  in  later  mod¬ 
els,  including  ADAM  I,  but  in  the  evo¬ 
lution  of  the  architecture,  many  such 
functions  migrated  higher  in  the  sys¬ 
tem,  to  the  CNS.  In  ADAM  I,  there  is  a 
faithful  reconstruction  at  the  CNS  level 
of  the  topology  of  the  received  image, 
but  only  a  few  of  the  cells  in  the  CNS 
use  the  information  in  this  form.  Most 
CNS  cells,  in  several  levels  deep,  do 
more  complex  processing  of  features 
of  the  image.  They  do  edge  detection 
and  center-surround  identification,  for 
example. 

ADAM  I,  which  has  not  yet  gone  out 
of  production,  could  solve  some  re¬ 
markably  difficult  classification  prob¬ 
lems.  One  problem  that  the  ADAM  I 
architecture  solves  is  to  count  the  num¬ 
ber  of  ADAMs  in  a  complex  scene  dis¬ 
played  in  low  resolution.  I’ll  let  you 
solve  the  problem  for  yourself. 

You  might  try  that  recognition  task 
on  your  favorite  neural  net. 

TThen  again,  maybe  you  just  did. 
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Figure  3-  Sampling  by  multiple  images  and  masks 
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C  PROGRAMMING 


C++  and  Linked 
Lists 


This  month  I'm  venturing  further 
into  C++  with  a  new  class,  the 
LinkedList.  Programmers  have 
been  using  the  linked  list  data 
structure  for  years.  It  allows  you  to 
store  an  unknown  number  of  data  items 
in  a  table  where  the  entries  do  not 
need  to  be  adjacent  in  memory.  It  also 
solves  the  problems  encountered  with 
standard  arrays  when  the  entries  have 
different  sizes.  Here’s  how  the  linked 
list  works. 

A  linked  list  data  structure  links  a  list 
of  data  items  together  with  a  set  of 
pointers.  The  list  itself  has  a  pointer  to 
the  first  and  last  entries  in  the  list.  These 
pointers  are  called  the  “list  head.”  A 
linked  list  consists  of  the  list  head  and 
the  data  entries.  Each  data  entry  in  the 
list  has  a  pointer  to  the  one  just  previ¬ 
ous  to  it  and  a  pointer  to  the  one  just 
past  it.  The  first  and  last  pointers  in  the 
list  head  are  initially  NULL.  They  are 
initialized  with  non-NULL  values  when 
the  first  item  is  added  to  the  list.  The 
first  item  in  the  list  has  a  NULL  previous- 
item  pointer,  and  the  last  item  in  the 
list  has  a  NULL  next-item  pointer. 

To  traverse  a  linked  list  in  a  forward 
sequence,  you  start  with  the  value  in 
the  first-item  pointer  from  the  list  head. 
If  that  pointer  is  NULL,  the  list  is  empty. 
Otherwise,  it  points  to  the  first  data 
item.  That  item  has  a  pointer  to  the 
next  data  item.  You  move  forward  by 
using  the  next-item  pointer  in  each  suc¬ 
cessive  item  until  you  find  an  item  with 
a  NULL  next-item  pointer,  meaning  you 


Al  Stevens 


are  at  the  end  of  the  list.  A  reverse- 
sequence  route  through  the  list  works 
the  same  way  but  starts  with  the  last- 
item  pointer  in  the  list  head  and  uses 
the  previous-item  pointer  in  the  items. 

To  add  an  item  to  the  end  of  the  list, 
you  make  its  previous-item  pointer  point 
to  where  the  last-item  pointer  points, 
and  you  make  the  last-item  pointer  point 
to  the  new  item.  You  must  also  make 


the  next-item  pointer  in  what  was  the 
last  item  point,  with  its  next-item  pointer, 
to  the  new  item. 

Deleting  an  entry  from  a  linked  list 
is  a  matter  of  breaking  and  repairing 
the  next-last  chain.  The  deleted  item’s 
previous  item  must  now  point  to  the 
deleted  item's  next  item  and  vice  versa. 
Of  course,  you  must  test  if  the  deleted 
item  is  the  first  or  last  (or  both)  and 
repair  the  first  and  last  pointers  in  the 
list  head  accordingly. 

That’s  what  a  linked  list  is.  They  all 
work  pretty  much  the  same.  Where 
they  differ  is  in  the  format  of  the  data 
items  they  manage.  As  such,  the  linked 
list  is  a  good  candidate  to  be  a  generic 
C++  class,  and  I’m  sure  that’s  not  a  new 
idea. 

Listing  One,  page  152  and  Listing 
Two,  page  152,  are  linklist.h  and  link- 
list,  cpp,  the  source  files  that  implement 
the  LinkedList  class. 

To  use  the  LinkedList  class,  you  in¬ 
clude  linklist.h  in  your  program.  Sur¬ 
rounding  a  data  structure  with  the  prop¬ 
erties  of  a  linked  list  is  simply  a  matter 
of  declaring  a  LinkedList  object  and 
adding  those  structures  as  entries  to 
the  list.  The  data  structure  itself  can  be 
as  simple  as  a  character  and  as  com¬ 
plex  as  a  new  class.  When  you  pass  its 
address  and  size  to  the  linked  list  mem¬ 
ber  function  (method)  that  adds  en¬ 
tries,  you  control  the  data  in  a  linked 
list.  Here  is  how  you  declare  a  list: 

LinkList  mylist; 

That’s  all  there  is  to  it.  Until  the  class 
goes  out  of  scope,  the  list,  empty  at 
first,  exists.  Here  is  how  you  add  data 
entries  to  the  list: 

my  list .  addentry  (&data ,  sizeof(data ) ) ; 

If  you  declare  a  list  and  then  begin  to 
add  entries,  they  will  be  added  in  turn 
at  the  end  of  the  list.  Each  new  entry 
follows  the  one  just  before  it,  and  is  at 
the  end  until  another  one  comes  along. 

If  you  traverse  a  list  and  then  add  an 


entry  while  positioned  in  the  middle  of 
the  list,  the  entry  will  be  added  just  past 
the  one  you  most  recently  retrieved.  If 
you  are  positioned  at  the  start  of  the  list, 
the  entry  will  be  added  as  the  first  one. 

To  retrieve  an  entry  from  a  linked 
list,  you  meander  through  the  list  for¬ 
wards  or  backwards  and  look  at  the 
data  values  within  each  entry.  Each  of 
the  member  functions  that  pass  through 
the  list  returns  a  pointer  to  the  list  entry 
that  it  found.  Here  are  the  methods  for 
traversing  the  list: 

void  *getfirst(void); 

void  ’getnext(void); 

void  *getprev(void); 

void  *getlast(void); 

void  *getcurr(void); 

You  would  call  one  of  them  in  this 
manner: 

char  *cp  =  mylist. getfirst( ); 

Each  of  these  member  functions  re¬ 
turns  a  pointer  to  the  data  value  of  the 
found  entry.  You  can  assign  these  re¬ 
turned  values  to  a  pointer  to  whatever 
you  have  in  the  list.  If  the  list  is  empty 
or  a  list  scan  reaches  the  end  or  begin¬ 
ning,  the  function  returns  a  NULL 
pointer. 

To  delete  an  entry,  you  navigate  to 
it  and  call  the  member  function  that 
deletes  the  current  entry.  Here  is  the 
call  for  that  operation: 

mylist. delete_entry(  ); 

Listing  Three,  page  152  is  demolist.cpp, 
a  C++  program  that  uses  the  LinkedList 
class  to  collect  and  manipulate  a  list  of 
names.  The  program  uses  the  string 
class  from  last  month,  and  the  first  thing 
I  realized  was  that  the  string  class  needs 
a  member  function  that  returns  the  size 
of  the  string.  Now  this  is  the  time  when 
a  rigorously  controlled  object-oriented 
project  would  likely  build  a  derived 
class  just  to  add  that  feature.  But,  be¬ 
cause  we  are  not  so  rigorous,  and  not 
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controlled  at  all,  we’ll  just  add  the  func¬ 
tion  to  our  original  string  class.  Refer 
to  strings. h  from  last  month,  and  insert 
these  lines  with  the  member  functions: 

// - return  the  length  of  a  string 

int  length! void) 

I  return  strlen(sptr)+l;  1 

The  demolist  program  prompts  you  to 
type  some  names  into  a  string.  It  adds 
each  name  you  type  to  a  LinkedList. 
When  you  are  done,  you  type  “end," 
and  the  program  displays  a  menu.  You 
can  display  the  names,  insert  a  new 
name  at  the  current  location,  move  for¬ 
ward  and  backward  through  the  list, 
and  delete  the  current  name. 

C++  Compilers 

The  C++  code  for  the  past  few  months 
works  with  Zortech  C++.  I  compiled 
and  ran  the  string  code  from  last  month 
with  two  other  PC  compilers,  Intek  C++ 
and  Guidelines  C++.  These  compilers 
are  ports  of  the  AT&T  C++  1.2  release, 
and,  as  such,  are  really  language  trans¬ 
lators.  You  need  a  compiler  as  well  as 
to  compile  the  C  code  that  the  C++ 
translator  builds  from  your  C++  source 
code. 

Intek  C++  has  versions  that  work 
with  Watcom  C,  Turbo  C,  Microsoft  C, 
and  MetaWare  High  C.  The  Intek  com¬ 
piler  works  only  on  a  386  machine 
with  extended  memory.  I  had  to  dis¬ 
able  my  Expanded  Memory  Manager 
to  use  Intek  C++,  and  I  found  one 
serious  bug:  The  compiler  driver  pro¬ 
gram  only  works  every  other  time  you 

A  linked  list  data 
structure  links  a  list  of 
data  items  together  with 
a  set  of  pointers 

run  it.  It  needs  a  control  file,  which  it 
builds  if  it  does  not  find  it.  After  the 
compile  is  done,  if  the  compile  goes 
to  completion,  the  compiler  process 
deletes  the  file.  The  problem  is  that  if 
the  file  is  not  there,  the  program  builds 
it  but  aborts.  If  the  file  is  there,  the 
program  uses  it  and  deletes  it.  There¬ 
fore,  the  program  works  only  every 
other  time.  The  technical  support  peo¬ 
ple  at  Intek  were  not  aware  of  this 


problem  and  seemed  to  think  there 
was  something  wrong  with  my  setup. 
Only  after  I  told  them  the  exact  se¬ 
quence  of  steps  to  reproduce  the  prob¬ 
lem  did  they  acknowledge  and  prom¬ 
ise  to  fix  it.  I  got  around  it  with  a  batch 
file  that  saves  and  restores  the  critical 
control  file.  Because  of  the  hardware 
requirements  and  the  price  ($495  plus 
the  price  of  your  compiler),  I  don't  see 
much  of  a  future  for  this  product  in  the 
PC  world. 

Guidelines  C++  is  cheaper  ( $295)  than 
Intek  and  does  not  require  a  386  or 
extended  memory.  You  do  need  to 
add  the  price  of  a  compiler,  however. 
Guidelines  C++  is  available  to  work 
with  Microsoft  C  only,  although  they 
tell  me  a  Turbo  C  version  will  be  in¬ 
cluded  when  they  release  their  port  of 
the  AT&T  C++  2.0  release,  which  should 
have  occurred  by  the  time  you  read 
this.  I  found  no  problems  with  Guide¬ 
lines  C++  other  than  those  imposed 
by  C++  1.2  itself.  The  AT&T  translator 
is  not  aware  of  the  ANSI  C  treatment 
of  void  pointers  against  real  pointers. 
ANSI  C  allows  a  function  to  have  a 
prototype  that  specifies  a  void  pointer. 
The  calling  function  can  pass  any  kind 
of  pointer,  and  the  called  function  deals 
with  it  as  though  it  were  a  character 
pointer.  Similarly,  a  function  that  is  pro¬ 
totyped  to  return  a  void  pointer  can 
be  called  to  assign  its  value  to  any  kind 
of  data  pointer.  This  convention  allows 
you  to  use  functions  such  as  malloc 
and  memcpy  without  needing  casts.  It 
also  allows  the  NULL  global  to  be  #de- 
fined  as  a  void  pointer  with  the  value 
zero.  The  AT&T  C++  1.2  translator  gags 
on  such  doings,  and  so  the  code  in  this 
month’s  column  works  with  neither  In¬ 
tek  nor  Guidelines  C.  I  gagged  at  put¬ 
ting  all  those  casts  in,  being  spoiled 
by  my  use  of  ANSI-conforming  compil¬ 
ers  of  late,  and  so  I  decided  to  stick 
with  Zortech  C++  until  the  others  come 
out  with  C++  2.0. 

The  Zortech  C++  compiler  is  a  real 
bargain  when  compared  to  the  others. 
It  has  a  list  price  of  $150,  and  you  do 
not  need  another  compiler  to  use  it.  It 
is  built  to  work  with  the  new-style  ANSI 
conventions.  (A  C  compiler  comes  with 
the  package.)  Its  disadvantage  is  that 
it  is  not  a  pure  port  of  the  AT&T  code; 
it  does  not  share  the  same  bugs  and 
features  with  the  rest  of  the  C++  world, 
and  so  your  code  will  not  be  as  port¬ 
able  as  you  might  want  it  to  be. 

The  ANSI  Corner:  Protests,  Trigraphs, 
Escape  Sequences,  and  Strings 

Do  you  wonder  why  it  takes  so  long 
to  get  a  language  standard  approved? 
The  ANSI  X3J11  committee  is  nearing 
six  years  defining  the  standard  for  the 


C  language.  Perhaps  this  story  will  help 
to  explain  why. 

Many  years  ago,  I  worked  for  a  small 
consulting  firm.  We  bid  on  a  govern¬ 
ment  contract  that  disqualified  as  bid¬ 
ders  any  manufacturers  of  computing 
equipment.  The  government  awarded 
the  job  to  a  large  firm,  and  my  boss 
wrote  a  letter  of  protest  saying  the  win¬ 
ning  bidder  should  have  been  disquali¬ 
fied  because  they  manufactured  tele¬ 
type  machines,  then  a  common  con¬ 
sole  terminal  device.  Such  a  protest 
automatically  invokes  a  bureaucratic 
procedure  of  response  and  usually  de¬ 
lays  the  work  until  the  matter  is  closed. 
Every  time  we  got  an  official  reply,  we 
simply  wrote  another  letter,  keeping 
the  wheels  of  inquiry  turning  while  the 
wheels  of  progress  were  stuck.  I  asked 
him  why  he  bothered.  He  said  that  the 
letters  cost  him  only  his  time,  while  the 
rewards  were  in  knowing  that  he  had 
thrown  a  monkey  wrench  into  the 
works.  And,  as  he  said,  “.  .  .  just  be¬ 
cause  they  p***ed  me  off.” 

The  ANSI  X3J 1 1  committee  has  simi¬ 
larly  irritated  a  C  programmer,  a  Mr. 
Russell  Hansberry,  and  he  has  re¬ 
sponded  in  turn  with  an  appeal  that 
challenges  the  validity  of  X3J1  l's  work. 
Like  the  nuisance  letters  of  my  whimsi¬ 
cal  boss  of  yore,  this  appeal  has  further 
delayed  approval  of  the  proposed  C 
standard. 

The  first  problem  was  that  Hans- 
berry’s  original  comments  were  over¬ 
looked  by  the  committee,  probably  lost 
in  the  shuffle.  The  committee,  having 
mislaid  the  letter,  failed  to  prepare  the 
required  formal  response  before  sub¬ 
mitting  the  draft  standard  to  X3,  and 
so  the  letter’s  author  could  and  did 

Do  you  wonder  why  it 
takes  so  long  to  get  a 
language  standard 
approved ? 

demand  that  the  committee  back  up 
and  address  his  concerns. 

X3J11  considered  each  of  the  points 
in  the  letter  and  voted  to  disapprove 
them  all.  There  was  much  ado  and 
flapdoodle,  but  the  disapproval  pre¬ 
vailed  by  democratic  action.  Most  peo¬ 
ple  who  embrace  the  concepts  of  a 
self-governing  free  society  would  have 
accepted  majority  rule  and  retreated. 
Hansberry,  apparently  deciding  that  de¬ 
mocracy  was  not  working  in  his  favor, 
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chose  instead  to  attack  on  other  fronts. 
Justice  is  never  swift  where  people  are 
free.  Hansberry  exercised  his  rights  and 
filed  an  appeal  that  raised  40  technical 
and  procedural  issues  in  an  apparent 
attempt  to  invalidate  all  of  the  commit¬ 
tee’s  work.  X3  voted  in  August  in  a 
reconsideration  ballot,  and  no  negative 
votes  were  cast,  so  the  technical  issues 
of  Hansberry 's  appeal  were  effectively 
defeated.  The  procedural  issues,  how¬ 
ever,  still  remain,  and  they  must  be 
addressed  before  approval  is  final.  If 
X3  votes  down  these  issues,  Hansberry 
can  still  appeal  to  ANSI.  Some  of  his 
concerns  have  merit,  but  others  are 
aimed  at  changing  the  language  in  ways 
that  would  endanger  existing  code.  In 
the  meantime,  the  rest  of  us  are  waiting 
for  an  approved  standard  for  the  C 
language. 

Maybe  next  year.  .  .  . 

ANSI  Additions 

Although  the  original  charter  for  the 
ANSI  C  standard  specification  was  to 
document  a  standard  for  existing  prac¬ 
tice  of  the  C  language,  the  proposed 
draft  does  add  some  features  to  the  C 
language.  The  most  notable  of  these  is 
the  new-style  function  definitions  and 
declarations,  called  “prototypes,"  which 
were  adopted  from  C++.  Other  new 
features  are  useful,  too,  but  could  pos¬ 
sibly  go  unnoticed  unless  you  took  the 
time  to  learn  them.  Among  these  addi¬ 
tions  are  trigraphs,  hexadecimal  escape 
sequences,  a  few  new  character  con¬ 
stants,  and  adjacent  string  literals. 

Trigraphs 

Trigraphs  aren't  as  useful  as  the  other 
additions,  but  you’ll  need  to  know  about 
them  because  you  might  trip  over  them 
some  day.  A  trigraph  is  a  way  to  ex¬ 
press  those  characters  that  C  uses  ex¬ 
tensively  but  that  do  not  exist  in  some 
non-ASCII  character  sets,  most  notably 
a  set  defined  by  the  International  Stan¬ 
dards  Organization  as  ISO  646.  There 
are  nine  such  characters  that  ISO  646 
does  not  include.  These  are  *,  [,  ],  I,  ), 
\,  1 ,  ,  and  a.  Try  writing  a  C  program 
without  them.  To  allow  users  of  ISO 
646  to  program  in  C,  ANSI  has  intro¬ 
duced  the  use  of  trigraphs  as  a  way  to 
express  these  characters.  A  trigraph  is 
two  question  marks  followed  by  a  char¬ 
acter  that  does  exist  in  ISO  646  and 
that  resembles  the  missing  character. 
These  are  the  trigraphs  for  the  missing 
characters: 


Trigraph  Replaces 

??=  # 

??(  [ 

??/  \ 

??)  1 

??■  A 

??<  I 

??!  ! 

??>  1 

??-  ~ 

Write  a  program  with  these  trigraphs, 
and  it  would  probably  win  one  of  those 
stupid  obfuscated  C  contests  (or  a  beau¬ 
tiful  APL  contest).  Nonetheless,  the  us¬ 
ers  of  those  other  character  sets  should 
not  be  denied  the  language,  and  so 
some  accommodation  was  needed.  The 
trigraphs  are  an  inelegant  but  work¬ 
able  solution.  Most  of  us  will  never 
need  to  know  about  trigraphs  except 
to  deal  with  the  rare  occasion  when 
we  want  to  put  "??”  into  a  string  while 
the  compiler  wants  to  turn  it  into  a 
trigraph.  (Use  “?  \  ?”.) 

Escape  Sequences 

In  the  C  lexicon,  an  escape  sequence 
is  a  value  in  a  constant  or  string  literal 
that  begins  with  the  backslash  charac¬ 
ter  and  that  translates  into  a  character 
value.  You  already  know  about  octal 
escape  sequences.  They  have  been  in 
traditional  K&R  C  since  the  beginning. 
You  can  code  a  character  constant  with 
an  octal  value  like  this: 

char  c  =  A  10T; 

The  backslash  character  followed  by 
an  octal  digit  (0  to  7)  tells  the  compiler 
that  the  digits  following  the  backslash 
form  a  character  value  from  an  octal 
expression.  With  ANSI-conforming  com¬ 
pilers  you  can  now  also  express  char¬ 
acter  constants  by  using  hexadecimal 
digits  as  shown  here: 

char  c  =  ’  \  x  41’; 

The  backslash-x  escape  sequence  tells 
the  compiler  that  the  digits  that  follow 
will  be  a  hexadecimal  character  con¬ 
stant.  Both  examples  just  given  form 
the  character  value  for  the  ASCII  A’ 
and  would  be  better  expressed  in  this 
manner: 

char  c  =  A'; 

With  an  octal  escape  sequence,  you 
are  allowed  from  one  to  three  octal 
digits  (0  to  7)  to  form  the  value.  This 
gives  you  a  theoretical  maximum  value 


of  A 777'  or  511.  ANSI  specifies,  how¬ 
ever,  that  a  character  constant  cannot 
exceed  the  range  of  an  unsigned  char, 
which,  on  a  PC  is  8  bits  wide  or  a 
maximum  of  A  377’  or  255.  Machines 
that  have  wide  characters  can  have  char¬ 
acter  constants  that  extend  to  that  limit, 
but  the  three-digit  limit  for  octal  con¬ 
stants  still  applies,  so  the  maximum  for 
wide  characters  is  51 1  regardless  of  the 
wide  character’s  width. 

While  an  octal  escape  sequence  can 
have  no  more  than  three  digits,  a  hexa¬ 
decimal  character  constant  can  have 
any  number  of  hex  digits  following  the 
backslash-x  escape  sequence.  It,  too, 
is  restricted  to  the  maximum  value  of 
the  unsigned  char,  so  its  limit  on  a 
computer  with  an  8-bit  character  is 
‘  \  xf  f  ’  or  wider  if  wide  characters  are 
implemented.  Other  character  sets  might 
have  much  wider  character  sizes,  so 
ANSI  does  not  define  a  theoretical  limit 
for  the  hexadecimal  character  constant, 
thus  allowing  for  the  expression  of  all 
character  constant  values  in  those  cul¬ 
tures  (Japan,  for  example)  where  there 
are  far  more  than  256  characters  in  the 
character  set. 

Several  common  character  values  can¬ 
not  be  expressed  with  single  alpha¬ 
betic,  numeric,  or  graphic  characters. 
The  Escape  and  Carriage  Return  char¬ 
acters  are  two  examples.  You  could 
express  these  characters  with  octal  or 
hexadecimal  character  constants,  but 
such  expressions  would  not  be  port¬ 
able  to  machines  with  incompatible  char¬ 
acter  sets.  ANSI  provides  for  escape 
sequences  for  some  but  not  all  of  the 
non-displayable  characters.  The  values 
shown  here  are  in  the  standard  for 
some  of  the  character  constants  that 
have,  in  the  ANSI  view,  universal  appli¬ 
cation: 

’  \  a’  audible  alarm 
’  \  b’  backspace 
’  \  f’  form  feed 
’  \  n’  newline 
’  \  r'  carriage  return 
’  \  t’  horizontal  tab 
’  \  v’  vertical  tab 

The  ‘  \  a’  and  ‘  \  v’  were  added  by  X3J1 1 . 

They  were  not  a  part  of  the  K&R 
definition,  but  the  committee  added 
them  to  the  standard  because  they  have 
universal  application.  Most  console  de¬ 
vices  have  a  bell  (BEL  in  ASCII)  charac¬ 
ter  that  sounds  an  audible  alarm,  and 
many  printers  will  respond  to  a  vertical 
tab  character.  ANSI  decided  not  to  in¬ 
clude  ‘  \  e’  for  the  Escape  character 
because  some  character  sets  —  EBCDIC, 
for  example  —  have  no  equivalent 
character. 

Some  displayable  ASCII  characters 
have  meaning  in  the  context  of  a  char- 
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acter  constant  or  string  literal.  To  allow 
you  to  represent  these  characters,  ANSI 
provides  the  following  escape  se¬ 
quences  to  provide  portable  expres¬ 
sions  of  their  values: 

’  \  ”  single  quote 
’  \  double  quote 
’  \  ?’  question  mark 
’  \  \  ’  backslash 

The  single  quote  needs  the  backslash 
in  a  character  constant  but  will  work 

The  first  problem  was 
that  Hansberry’s 
original  comments  ivere 
overlooked  by  the 
committee,  probably  lost 
in  the  shuffle 


either  way  in  a  string  literal.  Conversely, 
the  double  quote  needs  the  backslash 
in  a  string  literal  but  works  either  way 
in  a  character  constant. 

The  ‘  \  ?’  is  specified  in  the  ANSI 
draft  to  accommodate  its  expression 
in  character  sets  that  require  the  trigra¬ 
phs  discussed  earlier.  To  get  a  double 
question  mark  in  a  string,  you  code 
“?  \  ?”. 

Although  the  draft  is  not  specific  at 
this  point,  if  a  backslash  is  followed 
by  anything  other  than  an  octal  digit 
or  one  of  the  characters  ?,  ’<  ",  a,  b,  f, 
n,  r,  t,  v,  x,  or  \  ,  the  lonely  backslash 
is  ignored  (unless  nothing  follows  it 
on  the  line,  in  which  case  the  string  is 
assumed  to  continue  in  the  first  posi¬ 
tion  of  the  next  line).  At  least  that  is  a 
convention  followed  by  most  so-called 
ANSI-conforming  compilers. 

Strings 

You  can  put  octal  and  hexadecimal 
escape  sequences  into  character  string 
literals  as  well,  making  these  usages 
possible,  all  of  which  deliver  the  same 
string  value. 

char  *cp  =  "  \  lOlphids"; 

char  *cp  =  "  \  x4lphids"; 

char  *cp  =  "Aphids"; 

An  octal  escape  sequence  in  a  string 
continues  until  the  compiler  finds  a 
non-octal  digit  or  hits  the  third  octal 
digit.  A  hexadecimal  escape  sequence 
continues  for  as  long  as  the  compiler 


finds  hexadecimal  digits.  Compilers 
should  warn  you  if  the  character  values 
formed  exceed  the  upper  limit  of  a 
character  on  the  computer. 

Obviously,  the  third  format  is  what 
you  would  use  for  the  value  given  in 
the  example  above,  but  there  are  occa¬ 
sions  where  you  will  want  string  values 
that  contain  characters  not  represented 
by  displayable  characters.  The  control 
strings  that  command  an  ANSI  video 
terminal  use  an  Escape  sequence  to  let 
the  terminal  know  that  a  command  is 
coming.  To  clear  the  screen  on  an  ANSI 
terminal  (or  a  PC  with  ANSI. SYS  in¬ 
stalled),  you  can  use  this  statement: 

printfC"  \  33(2  J  "); 

The  “  \  33”  is  an  octal  escape  sequence 
that  forms  the  single  character  value 
for  the  Escape  character.  Suppose  your 
command  string  needed  to  have  the 
Escape  character  followed  by  “345”. 
This  string  would  not  work: 

printfC  \  333  45"); 

The  compiler  would  treat  the  third  '3’ 
as  part  of  the  octal  character  constant 
and  would  build  a  string  that  began 
with  the  character '  \  333’  followed  by 
"45".  Because  octal  character  constants 
are  limited  to  three  digits,  you  can  code 
the  string  this  way: 

printfC  \  0  333  45  "); 

The  leading  zero  does  the  trick  by  forc¬ 
ing  the  \  033  into  the  maximum  three 
digits.  (Users  of  Turbo  C  2.0  should  be 
aware  that  a  bug  in  the  compiler  makes 
it  think  that  all  the  digits  in  the  string 
are  part  of  the  octal  constant.) 

Here  is  the  clear-screen  statement 
with  a  hexadecimal  escape  sequence: 

printfC  \  xlb  [2  J"); 

The  “  \  xlb”  is  the  hexadecimal  es¬ 
cape  sequence  for  the  Escape  charac¬ 
ter.  Suppose  now  that  you  wanted  the 
Escape,  “345”  string  used  above.  This 
would  not  work: 

printfC  \  x  lb  3  45"); 

The  compiler  would  assume  that  all 
the  digits  following  the  “  \x"  are  part 
of  the  character  constant  because  hexa¬ 
decimal  character  constants  can  be 
wider  than  two  digits.  A  compiler  for 
an  8-bit  character  machine  should  is¬ 
sue  a  warning  for  this  example,  be¬ 
cause  the  value  exceeds  the  range  of 
the  unsigned  character.  It  should  not, 
however,  assume  that  you  meant  it  to 
be  Escape,  “345”  just  because  you 


have  8-bit  characters.  Such  a  conven¬ 
tion  would  promote  the  development 
of  non-portable  code.  So,  how  do  you 
get  it  to  work?  You  could  write  it  this 
way: 

printfC  %  d  3  4  5",  V  xlb'); 

That  would  work,  but  only  where  you 
are  using  the  print/- style  formatted  out¬ 
put.  Suppose  you  wanted  to  write  the 
string  with  the  puts  function  instead  of 
print/  For  that  purpose  ANSI  intro¬ 
duced  the  adjacent  string  literal. 

Adjacent  String  Literals 

If  you  code  two  string  literals  side-by- 
side,  they  are  concatenated  as  one  null- 
terminated  string.  Here  is  a  familiar  ex¬ 
ample: 

printfCHello," "  world"); 

This  feature  has  several  advantages. 
You  can  express  long  string  literals  more 
legibly  by  breaking  them  into  several 
adjacent  strings  and  putting  each  part 
on  its  own  line.  But,  even  better,  the 
problem  of  the  hexadecimal  character 
escape  sequence  is  solved.  Now  we 
can  do  this: 

printfC  \  xlb"  "345"); 

And,  finally,  a  more  descriptive  way  of 
coding  the  string  is  this: 

^define  ESCAPE  "  \  xlb" 

printf( ESCAPE  "345"); 

Nobody  Says  the  S  Word. . . . 

One  other  thing  X3JH  added  to  our 
culture  was  the  word,  “stringizing,” 
which  they  coined  to  mean  something 
new  for  the  C  preprocessor.  It’s  an 
awful  word  but  a  useful  feature.  I’ll  use 
the  feature,  but  I’ll  never  use  the  word 
again  except  maybe  to  tell  you  how 
awful  it  is.  Next  month  I’ll  explain  the 
feature  with  the  awful  S  word. 

Availability 

All  source  code  for  articles  in  this  issue 
is  available  on  a  single  disk.  To  order, 
send  $14.95  (Calif,  residents  add  sales 
tax)  to  Dr.  Dobb’s  Journal,  501  Galves¬ 
ton  Dr.,  Redwood  City,  CA  94063,  or 
call  800-356-2002  (from  inside  Calif.) 
or  800-533-4372  (from  outside  Calif.). 
Please  specify  the  issue  number  and 
format  (MS-DOS,  Macintosh,  Kaypro). 

DDJ 

(Listings  begin  on  page  152.) 

Vote  for  your  favorite  feature/article. 
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STRUCTURED  PROGRAMMING 


Poly  Want  An 
Object ? 


The  toughest  nut  to  crack  in  OOP’s 
very  full  bowl  of  new  concepts 
is  certainly  polymorphism ,  which 
sounds  more  like  a  developmen¬ 
tal  defect  in  parrots  than  a  program¬ 
ming  technique.  Its  very  mystical  -  magi¬ 
cal  (dare  I  say  legendary?)  sound  makes 
it  irresistible  to  marketing  types  and 
other  hypesters,  few  of  whom  can  even 
pronounce  it,  much  less  tell  you  what 
it  means. 

Tersely  put,  polymorphism  is  the  abil¬ 
ity  of  different  objects  to  respond  in 
their  own  way  to  a  single  directive.  I’m 
reminded  of  that  point  in  Cole  Porter’s 
Kiss  Me,  Kate  where  Lois  sings,  “I’m 
always  true  to  you,  Darling,  in  my 
fashion  . .  As  Cole  Porter  fans  know, 
being  true  means  one  thing  to  most 
people  and  quite  something  else  again 
to  Lois. 

But  that’s  polymorphism  in  a  nut¬ 
shell.  If  each  object  in  a  group  of  five 
objects  has  a  method  that  edits  the 
object’s  internal  data  you,  the  program¬ 
mer  (as  the  user  of  the  objects)  don’t 
have  to  know  the  specifics  of  editing 
each  type  of  data  within  each  of  the 
five  objects.  One  command  —  Edit  — 
can  be  given  to  any  of  the  five  objects. 
Each  object  will  respond  to  that  com¬ 
mand  by  executing  an  editing  routine 
custom  written  to  serve  its  own  data. 
An  object  containing  string  data  might 
execute  a  simple  line  editor.  An  object 
containing  Boolean  data  might  allow 
its  data  to  be  flipped  between  its  two 
alternate  states  on  presses  of  the  space 
bar.  An  object  containing  a  color  value 
might  place  a  color  chart  on  the  screen 
and  allow  the  user  to  edit  colors  by 
bouncing  a  pointer  along  the  edges  of 
the  chart. 


Jeff  Duntemann,  KI6RA 


It’s  all  editing  —  but  each  object  al¬ 
lows  the  editing  to  be  done  in  its  own 
fashion. 

Reading  the  Mail 

OK  —  so  what?  You  can  always  write 
up  an  editing  routine  for  each  type  of 
data  you  deal  with  and  then  CASE  your 
way  to  the  correct  editor  for  each  type 
of  data  you  encounter: 


CASE  DataType  OF 

DBoolean  :  EditBooleanData; 

DString  :  EditString; 

DInteger  :  EditlntegerData; 

ColorValue  :  EditColorValue; 

etc.  .  . 

You  don’t  need  object-oriented  pro¬ 
gramming  to  do  that. 

True.  But  let’s  consider  an  advanced 
network-based  electronic  mail  system. 
People  can  send  you  letters,  drawings, 
images,  even  digitized  voice  mail  over 
the  cable.  When  something  comes  in 
over  the  net  for  you,  an  icon  appears 
in  your  in-basket  area.  To  read  the 
mail,  you  have  to  (in  effect)  edit  each 
of  the  different  items  of  mail.  Letters 
can  be  edited  in  a  text  editor;  images 
in  an  image  editor.  Voice  mail  has  to 
be  sent  to  a  digital  analog  converter. 
So  far,  so  good  —  you’ve  got  tools  for 
each  of  those  kinds  of  mail.  But .  .  .  what 
happens  when  you  receive  a  technical 
drawing  in  a  vector  format  that  you 
haven’t  seen  before?  If  you  don’t  have 
a  tool  for  it,  you  can’t  read  it.  In  other 
words,  you  must  be  able  to  anticipate 
every  different  kind  of  mail  that  comes 
down  the  cable. 

Now,  if  you  received  complete  ob¬ 
jects  from  the  net  instead  of  just  data, 
you  could  simply  point  at  an  incoming 
object  of  uncertain  type  and  say,  “Mr. 
Oddball  Object,  start  your  editor.’’  The 
object  obeys.  It  brought  its  own  editor 
along  via  encapsulation,  and  it  knows 
how  to  invoke  its  editor.  Up  pops  the 
window  and  away  you  go,  reading  a 
type  of  mail  you’ve  never  encountered 
before. 

(Side  note:  Executing  objects  received 
over  a  net  like  this  would  require  run¬ 
time  dynamic  linking  and  may  not  be 
possible  using  Turbo  Pascal  in  its  cur¬ 
rent  form.  Such  a  system,  however,  is 
certainly  within  the  realm  of  object- 
oriented  programming  as  we  will  know 
it  within  a  few  years.) 

That’s  what  polymorphism  is  good 
for:  It  decreases  coupling  to  the  point 
where  a  system  can  accommodate  the 
unexpected.  If  all  elements  of  a  system 
conform  to  certain  high-level  standard 
directives,  the  details  of  implementing 
those  directives  can  be  left  to  the  individ¬ 


ual  objects  without  having  to  “inform” 
the  rest  of  the  system  how  to  deal  with 
those  objects  in  a  detailed  way. 

In  other  words,  if  every  element  of 
the  system  knows  what  it  means  to 
“edit,”  none  of  the  elements  need  to 
know  how  to  edit  anything  except 
itself. 

Each  object  is  thus  true  to  the  system 
specs  in  its  fashion. 

Bound  for  Glory 

That,  however,  is  simply  what  poly¬ 
morphism  is.  How  to  do  it  is  another 
question.  All  object-oriented  languages 
are  capable  of  polymorphism  (in  fact, 
if  a  language  can't  polymorph  it’s  not 
object-oriented)  and  each  one  imple¬ 
ments  polymorphism  in  a  slightly  dif¬ 
ferent  way.  In  this  column  I’ll  be  de¬ 
scribing  Turbo  Pascal’s  mechanisms  be¬ 
cause  I  understand  them.  Once  I  figure 
out  what  QuickPascal  is  doing  beneath 
the  surface  (which  is  not  covered  in 
their  rather  thin  little  manual)  I’ll  try  to 
explain  its  innards  as  well. 

Polymorphism  depends  utterly  on  an¬ 
other  new  concept  called  “late  bind¬ 
ing.”  Binding  has  always  existed  in  Pas¬ 
cal,  but  like  one  hand  clapping  no  one 
took  much  notice  until  there  was  an¬ 
other  way  to  go  about  it. 

Binding  is  simply  the  process  by 
which  the  caller  of  a  routine  is  given 
that  routine’s  address.  In  traditional  Pas¬ 
cal  and  C,  binding  happens  at  compile 
time,  or  at  link  time,  if  a  link  step  is 
present.  (Turbo  and  QuickPascal  both 
compile  and  link  in  one  pass,  so  com¬ 
pilation  and  linking  are  actually  the 
same  process.)  The  name  of  the  called 
routine  in  the  code  is  replaced  by  that 
routine’s  address.  Thus  a  link  between 
the  two  is  created  early  in  the  program’s 
life,  and  we  call  it  “early  binding.” 

Until  object-oriented  extensions  to 
Pascal  and  C  were  developed,  early 
binding  was  all  the  binding  there  was. 
Early  binding  requires  that  all  possible 
procedure  calls  be  known  at  compile 
time,  precluding  anything  like  the  elec¬ 
tronic  mail  system  we  described  ear¬ 
lier.  In  an  early-bound  system,  the  un¬ 
expected  is  anathema  —  all  data  and 
all  code  must  be  understood  before  the 
program  is  ever  run. 

(continued  on  page  145) 
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Virtual  Method  Tables 

Turbo  Pascal’s  system  for  achieving  late 
binding  is  elegant  and  about  as  fast  as 
such  a  system  is  likely  to  be.  It  works 
like  this: 

All  normal  procedure  calls  in  Turbo 
Pascal  are  early  bound.  So  are  calls  to 
all  object  methods  that  are  not  declared 
as  virtual.  Virtual  methods  in  Turbo 
Pascal  are  methods  that  are  late  bound 
rather  than  early  bound.  The  new  re¬ 
served  word  VIRTUAL  is  present  imme¬ 
diately  after  the  header  of  all  virtual 
methods. 

Not  all  objects  contain  virtual  meth¬ 
ods.  Methods  default  to  being  static , 
and  are  treated  the  same  way  as  ordi¬ 
nary  procedure  calls.  Unless  you  hang 
the  reserved  word  VIRTUAL  after  a 
method  declaration,  that  method  re¬ 
mains  static  and  early  bound. 

All  objects  that  do  contain  virtual 
methods  also  contain  a  little  something 
extra:  An  invisible  data  structure  called 
a  “virtual  method  table”  (VMT).  Each 
object  type  with  virtual  methods  has 
one  virtual  method  table,  stored  at  the 
beginning  of  the  data  segment.  The 
commonest  mistake  in  understanding 
Turbo  Pascal's  late  binding  machinery 
is  to  believe  that  each  object  instance 
has  its  own  virtual  method  table.  Not 
true  —  if  you  have  50  objects  of  object- 
type  Circle ,  all  50  use  the  same  VMT. 
Remember:  The  type  owns  the  VMT  — 
not  the  instance! 

The  VMT  is  nothing  more  than  a 
table  of  32-bit  addresses.  There  is  one 
“slot”  in  the  VMT  for  each  virtual 
method  —  defined  or  inherited  —  in  the 
VMT’s  object  type.  (Actually,  the  first 
32  bits  of  the  VMT  contain  non-address 
information,  including  the  size  of  the 
object  that  owns  the  VMT.  We’ll  get 
back  to  that  later  on,  in  connection 
with  constructors  and  destructors.) 

Figure  1  summarizes  this  admittedly 
complicated  and  difficult  behind-the- 
scenes  machinery. 

The  VMT  structure  in  the  data  seg¬ 
ment  is  created  at  compile  time,  when 
the  definition  of  the  object  that  owns 
it  is  encountered  by  the  compiler.  The 
addresses  in  the  VMT  (Bullet  1  on  Fig¬ 
ure  1)  are  also  written  at  compile  time, 
and  never  change.  This  is  another  source 
of  misunderstanding,  the  feeling  that 
somehow  the  addresses  in  the  VMT  are 
swapped  around  at  runtime.  Again,  not 
so:  The  VMT  itself  is  fully  created  and 
filled  at  compile  time  and  does  not 
change  in  any  way  after  that! 

The  VMT  is  created  in  the  lowest 
portion  of  the  data  segment,  but  it  is 
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present  in  the  .EXE  image  file  that  Turbo 
Pascal  writes  to  disk.  (More  than  code 
is  written  to  disk  as  part  of  the  .EXE 
file  —  typed  constants  are  placed  there 
as  well.) 

"How  Much,  Bui  Not  What  of " 

Remember  Bullwinkle’s  famous  recipe 
for  hush-a-boom?  (Jay  Wardian’s  car¬ 
toon  explosion  that  made  no  noise 
while  blowing  up. )  He  had  in  fact  only 
half  the  piece  of  paper  containing  the 
recipe,  leading  to  his  memorable  line, 
“I  know  how  much,  but  not  what  of.” 
Late  binding  is  a  lot  like  bringing  the 
two  halves  of  Bullwinkle’s  recipe  to¬ 
gether.  The  VMT  is  one  half,  (the  “what 
of’)  fully  created  and  ready  to  go  in 
the  data  segment  at  compile  time.  The 
other  half  of  the  recipe  (the  “how 
much”)  resides  in  an  instance  of  an 
object  type;  in  other  words,  in  a  vari¬ 
able  of  that  type. 

There  is  a  link  to  the  VMT  inside 
every  object  instance.  The  link  is  actu¬ 
ally  the  16-bit  offset  of  the  VMT  within 
the  data  segment.  This  link  is  shown 
in  Figure  1  as  the  arrow  marked  with 
Bullet  2.  Because  Turbo  Pascal  has  only 
one  data  segment,  we  can  use  a  1 6-bit 
offset  rather  than  a  full  32-bit  seg¬ 
ment  :  offset  address. 

This  link  does  not  exist  at  compile 
time,  but  must  be  set  up  after  the  pro¬ 
gram  begins  running.  The  setup  is  ac¬ 
complished  by  a  special  kind  of  method 
called  a  “constructor.”  Constructors  were 
originally  invented  for  C++,  and  are 
one  of  numerous  concepts  borrowed 
from  C++  by  Borland  for  its  object  ex¬ 
tension  to  Turbo  Pascal.  Every  object 
type  that  has  virtual  methods  must  also 
have  a  constructor.  And,  even  more 
important,  every  object  instance’s  con¬ 
structor  must  be  called  before  any  vir¬ 
tual  method  in  that  instance  can  be 
called. 

This  is  serious  business.  What  the 
constructor  does  is  connect  an  object 
instance  with  its  VMT,  which  contains 
the  addresses  of  all  the  object’s  virtual 
methods.  Without  that  essential  link 
between  the  instance  and  its  VMT, 
Turbo  Pascal’s  late  binding  machinery 
will  pull  a  nonsense  address  out  of  thin 
air  instead  of  from  the  VMT.  If  you  try 
to  call  an  object  instance’s  virtual  method 
before  calling  that  instance's  construc¬ 
tor,  execution  will  launch  off  into  no¬ 
where,  and  your  system  will  crash  hard. 
At  compile  time,  a  call  to  an  object 
instance’s  virtual  method  is  not  given 
the  address  of  the  virtual  method.  In¬ 
stead,  it  is  given  the  number  of  the 
VMT  slot  that  contains  the  address  of 
the  code  implementing  the  virtual 
method.  When  the  call  is  made.  Turbo 
Pascal  finds  the  VMT  through  the  link 


in  the  instance,  and  fetches  the  address 
from  the  VMT  slot  specified  in  the  code 
generated  to  implement  the  call.  Then 
an  8086  CALL  is  made  to  that  address. 

Voila!  The  two  parts  of  the  recipe  are 
brought  together,  and  the  making  of 
silent  explosives  can  begin.  This  time 
for  sure,  Rocky! 

Family  Resemblances 

Now  that’s  just  how  late  binding  works; 
we  haven't  quite  gotten  to  applying  it 
to  polymorphism  yet.  Polymorphism 
is  the  what ,  remember,  and  late  bind¬ 
ing  the  how. 

Polymorphism  depends  on  a  prop¬ 
erty  of  inheritance:  That  a  pointer  to  a 
parent  type  may  also  legally  point  to 
any  child  type  of  that  parent  type.  Con¬ 
sider,  for  example,  the  following  ob¬ 
ject  hierarchy: 

Mail 

LReply 

Llmage 

^Secret 

If  we  define  a  pointer  to  type  Mail,  that 
pointer  could  legally  point  to  any  of 
the  others  beneath  Mail  in  the  hierar¬ 
chy.  Similarly,  a  pointer  defined  as  point¬ 
ing  to  Reply  could  also  point  to  either 
Image  or  Secret,  but  not  to  Mail.  This 
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extended  assignment  compatibility,  like 
inheritance,  moves  only  down  the  ob¬ 
ject  hierarchy,  never  up. 

I’ve  sketched  out  the  VMTs  of  these 
four  hypothetical  object  types  in  Figure 
2.  Keep  Figure  2  handy  during  the  fol¬ 
lowing  discussion. 

Inheritance  passes  all  data  and  meth¬ 
ods  defined  within  Mail  down  to  all  the 
types  descended  from  Mail.  If  Mail  de¬ 
fines  four  methods,  those  four  methods 
are  also  present  in  Mail's  child  types. 
Now  here's  the  critical  fact:  Any  method 
held  in  common  by  all  four  object  types 
may  be  called  through  a  pointer  to  type 
Mail.  That’s  polymorphism,  whether 
the  light  has  gone  on  in  your  head  yet 
or  not.  But  it  will,  it  will. 

Suppose  you  have  a  linked  list  of 
nodes  containing  pointers  to  type  Mail-. 

TYPE 

MailPtr  =  AMail; 

NodePtr  =  ANode; 

I  Node  in  the  linked  list:  I 

Node  =  RECORD 

Message  :  MailPtr; 
Next  :  NodePtr; 

END; 

If  any  kind  of  electronic  mail  message 
is  defined  as  a  child  object  of  type 
Mail,  then  any  message  could  be  added 
to  that  linked  list.  Remember,  a  MailPtr 
can  point  to  type  Mail  or  to  any  child 
type  of  Mail.  To  edit  your  mail,  you 
would  simply  traverse  the  linked  list, 
and  call  the  Edit  method  of  each  object 
pointed  to  by  the  MailPtr  pointer  named 
Message: 

VAR 

Current,  ListRoot  :  NodePtr; 


Current  :=  ListRoot; 

WHILE  Current  <  >  NIL  DO 
BEGIN 

CurrentA.MessageA.Edit; 

I  Virtual  method  call:  I 
Current  :=  CurrentA.Next 
END; 


For  pointers  pointing  to  Mail  ob¬ 
jects,  Mail. Edit  is  executed.  For  point¬ 
ers  pointing  to  Reply  objects,  Reply. Edit 
is  executed.  For  pointers  pointing  to 
Image  objects,  Image. Edit  is  executed, 
and  so  on.  However,  nowhere  in  the 
code  shown  here  is  there  any  admit¬ 
tance  at  all  that  there  is  any  type  of 
object  in  the  list  other  than  type  Mail. 
Once  a  pointer  to,  say,  a  Reply  object 
is  assigned  to  a  MailPtr  pointer,  the 
source  code  treats  the  Reply  object  as 
though  it  were  a  Mail  object.  Only 


through  late  binding  does  a  call  to  the 
Edit  method  get  routed  to  the  correct 
edit  method  —  that  is,  the  Edit  method 
belonging  to  type  Reply. 

So  there  you  have  it:  Polymorphism 
allows  you  to  make  one  virtual  method 
call  to  several  different  types  of  object, 
and  each  object  then  responds  as  it 
should,  by  using  the  method  implemen¬ 
tation  written  to  serve  its  own  needs. 

Message  Passing,  Turbo-Style 

It’s  often  been  said  that  Turbo  Pascal 
5.5  does  not  support  message  passing, 
and  in  the  strictest  terms  that’s  true.  In 
true  Smalltalk-style  message  passing  a 
message  is  sent  to  an  object,  and  the 
object  takes  total  responsibility  for  call¬ 
ing  the  correct  method  in  response  to 
the  message.  In  Turbo  Pascal,  by  con¬ 
trast,  we  call  the  methods  directly. 

Well .  .  .  yes  and  no.  Certainly  we 
call  static  methods  directly.  However, 
when  we  call  a  virtual  method,  we 
might  think  of  the  call  as  a  message 
sent  to  Turbo  Pascal's  late  binding  ma¬ 
chinery:  “I  want  to  cal!  the  method 
accessed  through  slot  4  of  the  virtual 
method  table.”  The  late  binding  ma¬ 
chinery  then  fetches  the  address  from 
VMT  slot  4  and  makes  the  call.  It’s 
certainly  message  passing  stripped  to 
the  bone,  but  it's  just  indirect  enough 
to  qualify  in  my  book,  and  thinking  of 
the  VMT  mechanism  as  a  sort  of  mes¬ 
sage  passing  can  be  helpful  in  under¬ 
standing  just  what  it  is  that  the  VMT 
does  for  a  living. 

Think  of  It  as  Polymorphism  in  Action 

Coming  up  with  a  short,  working,  real¬ 
istic  example  of  polymorphism  in  ac¬ 
tion  is  difficult.  Demonstrating  poly¬ 
morphism  requires  multiple  object  types 
and  multiple  method  implementations, 
which  can  add  up  to  a  lot  of  code. 
Listing  One,  page  154,  is  about  as  brief 
a  demo  of  polymorphism  as  I  could 
concoct  without  moving  to  totally  arti¬ 
ficial  situations;  you  know,  one-line 
methods  that  display  “Hi  boss!  This  is 
the  Edit  method!”  on  the  screen  when 
you  execute  them.  The  FIELDS. PAS  unit 
is  conceptually  similar  to  the  FORMS 
.PAS  unit  provided  as  a  demo  program 
with  Turbo  Pascal  5.5,  but  simpler  and 
shorter.  FIELDTST.PAS  (Listing  Two, 
page  159)  is  a  short  program  that  exer¬ 
cises  the  FIELDS. PAS  unit. 

FIELDS. PAS  defines  the  short  object 
hierarchy  shown  below: 

TextPosition 

1-Field 

BooleanField 
TextField 
1-IntField 

Of  the  object  types  shown  here, 


TextPosition  and  Field  are  abstract  ob¬ 
ject  types,  that  is,  types  that  exist  only 
to  be  inherited  from,  or  to  act  as  heads 
of  polymorphic  families.  You  never  ac¬ 
tually  create  instances  of  abstract  ob¬ 
ject  types.  Notice  in  Listing  One  that 
most  of  type  Field s  methods  are  stubs 
that  do  nothing.  The  stubs  are  there  so 
that  Fields  children  can  override  them 
with  working  substitutes.  Stubs  or  not, 
slots  exist  in  Fields  VMT  for  each  of  its 
virtual  methods,  and  those  slots  are 
inherited  by  all  of  Fields  children. 

A  field  is  an  object  containing  data 
and  the  means  to  display  and  edit  that 
data  on  the  screen.  Type  Field  is  ab¬ 
stract,  and  contains  no  data  of  its  own. 
Each  of  its  children  represents  a  differ¬ 
ent  kind  of  data:  string  data,  Boolean 
data,  and  integer  data.  Type  Field  and 
all  its  children  have  three  virtual  meth¬ 
ods:  Show,  Hide,  and  Edit.  Show  dis¬ 
plays  the  field's  data  at  its  current  screen 
position,  and  Hide  erases  it  from  that 
position.  Edit  allows  the  user  to  modify 
the  data  in  an  appropriate  way. 

Listing  One  was  written  to  be  bla¬ 
tantly  obvious  rather  than  clever.  No¬ 
tice  these  things: 

•  The  Show,  Hide ,  and  Edit  virtual  meth¬ 
ods  for  Field  are  stubs.  They  are  there 
only  to  reserve  places  in  the  VMT,  so 
that  the  “real”  versions  belonging  to 
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Fields,  child  types  can  be  invoked 
through  a  pointer  to  type  Field. 

•  Note  the  absence  of  method  Intfield 
Hide.  Integers  are  edited  on-screen  as 
strings,  and  erasing  a  string  from  the 
screen  (which  is  all  that  it  takes  to  hide 
an  IntField s  data)  is  done  the  same 
way  for  any  child  type  of  TextField. 
Therefore,  IntField  simply  uses  its  par¬ 
ent’s  Hide  method.  No  special  qualifi¬ 
cation  is  called  for  in  Turbo  Pascal. 
When  IntField  invokes  a  method  that 
it  doesn’t  itself  define,  Turbo  Pascal 
goes  “up  the  tree’’  and  uses  the  first 
method  it  finds  with  the  correct  identi¬ 
fier,  in  this  case  TextField. Hide. 

•  Note  that  every  constructor  calls  the 
constructor  of  its  parent  type  before 
doing  anything  else.  This  is  a  critical 
rule  of  “good  style’’  in  OOP:  Let  each 
object  type  perform  its  own  initialization. 
This  isolates  initialization  code  where 
it  has  to  happen,  and  doesn't  force  you 
to  go  searching  for  initialization  code 
outside  of  the  object  type  when  it  comes 
time  to  change  it  somehow. 

•  Note  that  constructors  are  never  vir¬ 
tual.  A  constructor  call,  because  it  sets 
up  that  all-important  link  to  the  VMT, 
must  be  static  because  it  cannot  de¬ 
pend  on  the  VMT  to  get  the  constructor 
code’s  address! 

With  all  of  that  in  mind,  I'll  leave  the 
rest  of  digesting  Listing  One  up  to  you. 
Listing  Two  is  where  the  polymorphism 
happens,  and  it  deserves  a  closer  look. 

Objects  Linder  Construction 

Listing  Two  defines  an  array  of  four 
FieldPtr  pointers,  which  point  to  type 
Field.  These  pointers  are  given  objects 
on  the  heap  through  calls  to  New ,  as 
with  any  dynamically-allocated  data 
item.  The  Turbo  Pascal  5.5  twist  is  the 
New  syntax.  New  can  now  be  used  as 
a  function,  much  the  same  as  malloc 
in  C: 

<  pointer  var  >  :=  New(  <its  pointer  type  >); 

Note  that  this  applies  to  all  uses  of 
New ,  not  only  those  with  OOP  connec¬ 
tions. 

No,  the  OOP  twist-within-a-twist  is 
the  invocation  of  constructors  from 
within  the  NewczVr. 

<  pointer  to  object  >  :=  New(  Compatible 

object  type  >, 
Constructor  call>); 

This  syntax  allows  you  to  allocate  and 
initialize  an  object  with  one  statement, 
and  do  it  without  having  to  use  a  tem¬ 
porary  pointer  variable  to  hold  the  al¬ 
located  object. 

Note  well  that  the  type  of  the  pointer 
on  the  left  side  of  the  assignment  state¬ 


ment  only  has  to  be  compatible  with 
(not  identical  to!)  the  pointer  type  given 
in  the  New  call: 

FieldArrayll]  :=  New(TextFieldPtr  .  .  . 

Here,  FieldArrayll]  is  type  FieldPtr, 
whereas  New  calls  out  a  pointer  of  type 
TextFieldPtr.  Because  TextField  is  a  child 
of  Field,  their  pointers  are  compatible. 
Me  allocates  an  object  of  type  TextField 
on  the  heap,  while  returning  a  pointer 
of  type  Field  to  FieldArrayll].  Thus  the 
New  call  is  setting  up  the  pointers  to 


allow  polymorphism  as  well.  That’s  a 
lot  of  mileage  from  a  single  New  call! 

A  reminder:  You  must  call  the  con¬ 
structor  of  each  object  instance  before 
using  that  instance.  Turbo  Pascal  5.5 
includes  an  extension  of  range-check¬ 
ing  to  help  you  during  development. 
With  the  $R+  compiler  directive  in  force, 
a  call  to  a  virtual  method  made  from 
an  uninitialized  instance  of  an  object 
generates  a  range  error  rather  than  DOS 
McNuggets.  As  with  range  checking  in 
general,  use  it  during  development,  then 
turn  it  off  once  you're  satisfied  things 


Early  Binding 


Code  calling  procedure  Foo  is  given 
Foo's  address  by  the  compiler  at 
compile  time.  This  process  is  called 
binding. 


Foo{x  :  Byte); 


Late  Binding 

The  link  between  an  object  instance 
and  its  object  type's  VMT  is  created 


♦  PROCEDURE  Foo(X  :  Byte)! 


When  a  virtual  method  is  actually  called,  the  link  to  the  VMT  enables 
the  runtime  code  to  look  up  the  called  method's  address  in  the  VMT 
given  the  offset  of  the  method's  address  within  the  VMT.  Thus 
bindirv-at  method  invocation  time- is  as  late  as  it  could  possibly  be! 


Figure  1 :  Early  versus  late  binding 


Polymorphism 

Gizmo  is  a  pointer  to 
Mail,  but  it  can  be  made 
to  point  to  any  of  Mail's 
child  types  as  well. 


Here,  Gizmo's  referent  is  of  type  Secret, 
yet  all  methods  Secret  has  in  common  with 
Mail  are  accessible  through  Gizmo. 


Gizmo  :  "Mail; 
Reply 


Secret 


Image 


Mail 


Print 

Print 

Print 

Print 

All  these 
methods 

are 

accessible 

through 

Gizmo 

Show 

Show 

Show 

Show 

Hide 

Hide 

Hide 

Hide 

Edit 

Edit 

Edit 

Edit 

Send 

Send 

Send 

Compress 

Compress 

Expand 

Expand 

Encrypt 

Decrypt 

Figure  2:  Polymorphism 
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are  correct.  (And,  of  course,  when  things 
blow  up,  the  first  thing  to  do  is  turn  the 
damned  thing  back  on  again  and  see 
how  wrong  you  were!) 

Freedom  of  Expression 

Once  you  understand  the  amazing  so¬ 
phistication  of  the  underlying  mecha¬ 
nism,  the  polymorphic  calls  themselves 
almost  seem  an  afterthought: 

FOR  I  :=  1  TO  4  DO 

FieldArray'VShow; 

FOR  I  :=  1  TO  4  DO 
FieldArrayA.Edit; 

The  first  statement  steps  through  the 
objects  attached  to  the  array  and  dis¬ 
plays  their  initial  data  on  the  screen 
through  the  Show  virtual  method.  The 
second  steps  through  the  array  again, 
this  time  editing  each  object  in  turn 
through  the  Edit  virtual  method. 

The  major  advantage  to  polymor¬ 
phism  is  that  it  encourages  a  unified 
high-level  way  of  looking  at  an  appli¬ 
cation,  or  at  least  at  families  of  objects. 
Dealing  polymorphically  with  objects 
emphasizes  their  similarities  (that  is,  all 
data-intensive  objects  need  editing)  with¬ 
out  letting  the  details  of  their  differ¬ 
ences  get  in  the  way  of  understanding 


and  using  them. 

I’ll  be  talking  about  polymorphism 
in  many  different  contexts  in  future 
columns.  Digitalk  has  just  released  its 
Smalltalk/V  PM  for  Presentation  Man¬ 
ager,  and  I’ll  (with  some  luck)  get  a 
chance  to  describe  it  in  detail  in  my 
next  column.  Conquering  the  complex¬ 
ity  of  PM’s  API  is  probably  the  most 
important  single  job  for  polymorphism 
that  I  can  think  of  right  now,  and  at  first 
glance  Smalltalk/V  PM  does  it  beauti¬ 
fully.  Stay  tuned. 

Get-TUG-Gether  '89 

The  Turbo  User  Group  has  quietly  and 
with  less  notice  than  it  deserves  been 
supporting  users  of  Borland  languages 
for  almost  five  years.  This  year,  Don 
Taylor  and  the  crew  have  raised  their 
profile  considerably  by  instituting  Get- 
TUG-Gether,  a  programmer’s  confer¬ 
ence  and  party  to  equal  anything  I  have 
ever  attended  in  that  vein. 

The  narrowness  of  the  focus  helps. 
I  was  not  beset  by  Unix  evangelists 
speaking  in  their  peculiar  form  of 
tongues  (“awk!  grep!  yacc!”ala  Bill  the 
Cat)  nor  pinstriped  salesmen  pushing 
mainframe  computers  the  size  of  small 
counties  in  Arkansas.  Instead,  we  were 
a  group  of  100  or  so  Turbo  hackers 
trading  insights  and  having  a  good  time. 


Half  a  dozen  Turbo  product  vendors 
displayed  and  demonstrated  their  cur¬ 
rent  releases,  and  I  signed  books  for 
Judy  Overbeek’s  Rockland  Press.  Solid 
technical  sessions  and  small-group  dis¬ 
cussion  sections  rounded  out  the  pro¬ 
gram.  Remarkable  (for  Seattle)  weather, 
a  great  pool,  and  the  spectacularly  dedi¬ 
cated  TUG  staff  made  it  the  best  hacker 
gathering  in  recent  memory. 

There  will  be  another  Get-TUG- 
Gether  next  summer,  from  June  29  - 
July  1  and  Don  has  promised  more 
technical  tutorials,  particularly  for  non¬ 
experts.  (I  have  already  committed  to 
presenting  “Pascal  Pointers  for  Begin¬ 
ners”  in  conjunction  with  a  book  I’ll 
be  writing  on  that  subject.)  It’s  cheap, 
it’s  educational,  and  it  feels  good.  For¬ 
get  the  invitation-only  Elitist  Hackers 
conference  in  Silicon  Valley;  this  is  the 
future. 


Products  Mentioned 

Turbo  Pascal  5  5 
Borland  International 
1800  Green  Hills  Road 
Scotts  Valley,  CA  95066 
408-438-8400 

Standard  package:  $149.95 
Professional  package:  $250 

Smalltalk/V  PM 
Digitalk  Inc. 

9841  Airport  Blvd. 

Los  Angeles,  CA  90045 

213-645-1082 

$495 

Turbo  User  Group  (TUG) 
TUG  Lines  newsletter 
P.O.  Box  1510 
Poulsbo,  WA  98370 
BBS:  206-697-1151 
Membership:  $27  US; 

$32  Canada/Mexico; 

$39  elsewhere 


Availability 

All  source  code  for  articles  in  this  issue 
is  available  on  a  single  disk.  To  order, 
send  $14.95  (Calif,  residents  add  sales 
tax)  to  Dr.  Dobbs  Journal ,  501  Galves¬ 
ton  Dr.,  Redwood  City,  CA  94063,  or 
call  800-356-2002  (from  inside  Calif.) 
or  800-533-4372  (from  outside  Calif.). 
Please  specify  the  issue  number  and 
format  (MS-DOS,  Macintosh,  Kaypro). 

DDJ 


(Listings  begin  on  page  154.) 

Vote  for  your  favorite  feature/article. 
Circle  Reader  Service  No.  12. 
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listing  One  (Listing  continued,  text  begins  on  page  133  ) 

>PrevEntry; 

LastEntry  =  CurrEntry->PrevEntry; 

#ifndef  LINKLIST 

if  (CurrEntry->PrevEntry  !=  NULL) 

CurrEntry->PrevEntry->NextEntry  =  CurrEntry- 

♦define  LINKLIST 

>NextEntry; 

else 

FirstEntry  =  CurrEntry->NextEntry; 

class  LinkedList  { 

delete  CurrEntry->entrydata; 

ListEntry  ‘hold  =  CurrEntry->NextEntry; 

typedef  struct  list  entry  [ 

delete  CurrEntry; 

struct  list  entry  ‘NextEntry; 

CurrEntry  =  hold; 

struct  list  entry  *PrevEntry; 

void  *entrydata; 

}  ListEntry; 

//  -  get  the  first  entry  in  the  list 

ListEntry  *LastEntry; 

void  ‘LinkedList : rgetfirst (void) 

ListEntry  *CurrEntry; 

CurrEntry  =  FirstEntry; 

// - constructor 

return  CurrEntry  ==  NULL  ?  NULL  :  CurrEntry->entrydata; 

LinkedList (void) 

{  FirstEntry  =  LastEntry  =  CurrEntry  =  NULL;  ) 

//  -  get  the  next  entry  in  the  list 

LinkedList (void) ; 

void  ‘LinkedList : : getnext (void) 

// - add  an  entry 

( 

if  (CurrEntry  —  NULL) 

void  addentry (void  ‘newentry,  int  size); 

//  -  delete  the  current  entry 

CurrEntry  =  FirstEntry; 

void  delete  entry (void); 

//  -  get  the  first  entry  in  the  list 

CurrEntry  =  CurrEntry->NextEntry; 

void  *getfirst (void) ; 

return  CurrEntry  ==  NULL  ?  NULL  :  CurrEntry->entrydata; 

II  -  get  the  next  entry  in  the  list 

void  ‘getnext (void) ; 

//  -  get  the  previous  entry  in  the  list 

void  *getprev (void) ; 

void  ‘LinkedList : :getprev (void) 

//  -  get  the  last  entry  in  the  list 

void  *getlast (void) ; 

if  (CurrEntry  «=  NULL) 

//  -  get  the  current  entry  in  the  list 

CurrEntry  =  LastEntry; 

void  ‘getcurr (void) 

(return  CurrEntry==NULL  ?  NULL  ;  CurrEntry->entrydata; ) 

>; 

CurrEntry  =  CurrEntry->PrevEntry; 

return  CurrEntry  ==  NULL  ?  NULL  :  CurrEntry->entrydata; 

) 

#endif 

End  Listing  One 

//  -  get  the  last  entry  in  the  list 

void  ‘LinkedList : :getlast (void) 

( 

Listing  Two 

CurrEntry  =  LastEntry; 

return  CurrEntry  ==  NULL  ?  NULL  :  CurrEntry->entrydata; 

} 

//  -  linklist.cpp 

♦include  <string.h> 

End  Listing  Two 

♦include  "linklist.h" 

//  -  linked  list  destructor 

Listing  Three 

LinkedList : :~LinkedList (void) 

{ 

//  -  demolist.cpp 

ListEntry  ‘thisentry  =  FirstEntry; 

while  (thisentry  !=  NULL)  ( 

♦include  <stream.hpp> 

♦include  "strings. h" 

delete  thisentry->entrydata; 

♦include  "linklist.h" 

ListEntry  *hold  =  thisentry; 
thisentry  =  thisentry->NextEntry; 

void  collectnames (LinkedListS  namelist); 

delete  hold; 

int  menu (void); 

1 

void  displaynames (LinkedListS  namelist); 

) 

void  stepforward(LinkedListS  namelist); 

// - add  an  entry  to  the  list 

void  stepbackward (LinkedListS  namelist); 
string  insertname (LinkedListS  namelist); 

void  LinkedList :: addentry (void  ‘newentry,  int  size) 

{ 

void  main (void) 

/* - build  the  new  entry - */ 

( 

ListEntry  ‘thisentry  =  new  ListEntry; 

cout  «  "Enter  some  names  followed  by  \"end\”\n"; 

thisentry->entrydata  =  new  char (size); 

// - a  linked  list  of  names 

memcpy (thisentry->entrydata,  newentry,  size); 

LinkedList  namelist; 

if  (CurrEntry  ==  NULL)  ( 

collectnames (namelist) ; 
int  key  =  0; 

thisentry->PrevEntry  =  NULL; 

while  (key  !=  6)  ( 

//  -  adding  to  the  beginning  of  the  list 

switch  (key  =  menu())  { 

if  (FirstEntry  !=  NULL)  ( 

case  1: 

/*  -  already  entries  in  this  list  -  */ 

displaynames (namelist) ; 

thisentry->NextEntry  =  FirstEntry; 

break; 

FirstEntry->PrevEntry  =  thisentry; 

case  2: 

) 

stepforward (namelist) ; 

else  f 

break; 

//  -  adding  to  an  empty  list 

case  3: 

thisentry->NextEntry  =  NULL; 

stepbackward (namelist) ; 

LastEntry  =  thisentry; 

break; 

) 

case  4: 

FirstEntry  =  thisentry; 

insertname (namelist) ; 

1 

break; 

else  ( 

case  5: 

// - inserting  into  the  list 

namelist . delete  entry (); 

thisentry->NextEntry  =  CurrEntry->NextEntry; 

break; 

thisentry->PrevEntry  =  CurrEntry; 

case  6: 

if  (CurrEntry  ==  LastEntry) 

cout  «  "Quitting..."; 

//  -  adding  to  the  end  of  the  list 

break; 

LastEntry  =  thisentry; 

default : 

else 

break; 

//  -  inserting  between  existing  entries 

1 

CurrEntry->NextEntry->PrevEntry  =  thisentry; 

} 

CurrEntry->NextEntry  =  thisentry; 

) 

CurrEntry  =  thisentry; 

void  collectnames (LinkedListS  namelist) 

// - delete  the  current  entry  from  the  list 

// - until  the  user  types  "end" 

while  (insertname (namelist)  !=  "end") 

void  LinkedList: :delete_entry (void) 

1 

if  (CurrEntry  !=  NULL)  { 

int  menu (void) 

if  (CurrEntry->NextEntry  !=  NULL) 

CurrEntry->NextEntry->PrevEntry  =  CurrEntry- 
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cout  «  "\nl  =  display  the  names"; 

cout  «  "\n2  =  step  forward  through  the  names"; 

cout  «  "\n3  =  step  backward  through  the  names"; 

cout  «  "\n4  =  insert  a  name"; 

cout  «  "\n5  =  delete  the  current  name"; 

cout  «  "\n6  =  quit"; 

cout  «  "\nEnter  selection:  "; 

int  key; 

cin  »  key; 

return  key; 

} 

//  -  read  the  names  in  a  list  and  display  them 

void  displaynames (LinkedListS  namelist) 

{ 

cout  «  " - NAME  LIST - \n"; 

char  ‘name  =  namelist .getfirst () ; 
while  (name  ! -  NULL)  { 

cout  «  name  «  "\n"; 
name  =  namelist. getnext () ; 

} 

cout  «  " - - \n”; 

} 

// - step  forwarcj  through  the  list  of  names 

void  stepforward(LinkedList&  namelist) 

{ 

char  ‘name  =  namelist .getnext () ; 

cout  «  (name  ?  name  :  "—  End  of  list  — ")  «  "\n"; 

} 

//  -  step  backwardward  through  the  list  of  names 

void  stepbackward(LinkedList&  namelist) 

( 

char  ‘name  =  namelist. getprev() ; 

cout  «  (name  ?  name  :  Beginning  of  list  — ")  «  "\n"; 


// - insert  a  name  into  the  list 

string  insertname (LinkedList&  namelist) 

{ 

cout  «  "Enter  a  name:  "; 

//  -  a  string  to  hold  one  name 

string  name (80); 

// - read  a  name 

cin  »  name. stradr () ; 

// - add  it  to  the  list 

if  (name  !=  "end") 

namelist. addentry (name. stradr () ,  name. length () ) ; 
return  name; 


End  Listings 


Listing  One  (Text  begins  on  page  142.) 


Unit  Fields; 
INTERFACE 

USES  Crt; 
CONST 

IntChars  = 
TextChars  = 
Visible  = 
Invisible  = 


['O'. .'9','-']; 

[#0.  .#255]; 

True; 

False; 


ABSTRACT ! 


TYPE 

StringlO  =  String [10]; 

String80  =  String[80]; 

CharSet  =  SET  OF  Char; 

PositionPtr  *  "TextPosition; 

TextPosition  = 

OBJECT 

X,Y  :  Integer;  (  Coordinates  of  location  on 

CONSTRUCTOR  Init (InitX, InitY  :  Integer); 

FUNCTION  XPos  :  Integer; 

FUNCTION  YPos  :  Integer; 

END; 

FieldPtr  *  AField; 

Field  =  (  ABSTRACT!  } 

OBJECT (TextPosition) 

VisibleState  :  Boolean;  {  True  =  Field  is  displayed 
CONSTRUCTOR  Init (InitX, InitY  :  Integer; 

InitVisible  :  Boolean) ; 

IsVisible  :  Boolean; 

MoveTo (NewX, NewY  :  Integer); 

Show;  VIRTUAL; 

Hide;  VIRTUAL; 

Edit;  VIRTUAL; 


FUNCTION 

PROCEDURE 

PROCEDURE 

PROCEDURE 

PROCEDURE 

END; 


TextFieldPtr  =  ATextField; 
TextField  = 

OBJECT (Field) 

StringData  :  String80; 
FieldLength  :  Integer; 
CONSTRUCTOR  Init (InitX, InitY 
InitVisible 


i  For  ordinary  text  strings 


FUNCTION 

PROCEDURE 

PROCEDURE 

PROCEDURE 

END; 


InitText 
InitLength 
GetData  :  String80; 
Show;  VIRTUAL. 

Hide;  VIRTUAL, 

Edit;  VIRTUAL, 


Integer; 
Boolean; 
String80; 
Integer) ; 


BooleanFieldPtr  =  ABooleanField; 
BooleanField  = 

OBJECT (Field) 

Toggle  :  Boolean; 

TrueString, FalseString  :  String80; 
CONSTRUCTOR  Init (InitX, InitY  :  Integer; 

InitVisible  : 
InitToggle  : 
InitTrueStr, 
InitFalseStr 
Getdata  :  Boolean; 

Show;  VIRTUAL; 

Hide;  VIRTUAL; 

Edit;  VIRTUAL; 


FUNCTION 

PROCEDURE 

PROCEDURE 

PROCEDURE 

END; 


Boolean; 

Boolean; 


String80) ; 


IntFieldPtr  =  AIntField; 

IntField  = 

OBJECT (TextField) 

IntVal  :  Integer; 

CONSTRUCTOR  Init ( InitX, InitY 
InitVisible 
InitlntVal  : 

FUNCTION  GetData  :  Integer; 
PROCEDURE  Show;  VIRTUAL; 

PROCEDURE  Edit;  VIRTUAL; 

END; 


IMPLEMENTATION 


Integer; 
Boolean; 
Integer) ; 


VAR 

Blanker  :  String80; 


FUNCTION  MaxLength (Stringl, String2  :  String)  :  Integer; 
BEGIN 

IF  Length (Stringl)  >  Length (String2)  THEN 
MaxLength  :=  Length (Stringl) 

ELSE 

MaxLength  :=  Length (String2); 

END; 


PROCEDURE  ShowBlanks (NumberOf Blanks  :  Integer) ; 
BEGIN 

Write (Copy (Blanker, 1, NumberOf Blanks) ) ; 

END; 


the  screen  } 


} 
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PROCEDURE  HighLight (X, Y, TargetLength  :  Integer;  TargetText  :  String); 


BEGIN 

GotoXY (X, Y) ;  ShowBlanks (TargetLength) ; 
GotoXY (X, Y) ;  Write (TargetText ) ; 

El$D; 

PROCEDURE  UhUh; 

BEGIN 

Sound (35);  {  Make  first  grunt  } 

Delay (100) ; 

NoSound; 

Delay (50);  (  Delay  between  grunts  ) 

Sound(35);  {  Make  second  grunt  } 

Delay (100) ; 

NoSound; 

Delay (50);  (  Delay  after  second  grunt  } 

END; 


PROCEDURE  GetLine (X, Y  :  Integer; 


VAR  MyLine  ; 

String80; 

MaxWidth  : 

Integer; 

LegalChars  : 

CharSet) ; 

VAR 

Ch 

Char; 

Quit, Done 

Boolean; 

TempLine 

String; 

WorkPoint 

Integer; 

PROCEDURE  DisplayLine; 
BEGIN 

GotoXY (X,Y) ; 

Write (TempLine) ; 

END; 


BEGIN 

Quit  :=  False;  Done  :=  False; 

TempLine  :=  MyLine; 

DisplayLine; 

REPEAT 

IF  KeyPressed  THEN 
BEGIN 

WorkPoint  :=  (WhereX-X)  +  1; 

Ch  :=  ReadKey; 

CASE  Ord (Ch)  OF 

0  :  BEGIN  (  If  the  first  char  is  0,  there's  more...  } 

Ch  :»  ReadKey;  (  Get  the  second  portion  ) 

CASE  Ord(Ch)  OF 
71  :  GotoXY (X,Y);  (  Home  } 

79  :  GotoXY (X  +  Length (TempLine) , Y) ; 

75  :  IF  WorkPoint  <=  1  THEN  Uhuh  {  Left  Arrow  } 

ELSE 

BEGIN 

Dec (WorkPoint) ; 

GotoXY (X+WorkPoint-1,  Y)  ; 

END; 

83  :  BEGIN  {  Del  ) 

Delete (TempLine, WorkPoint, 1) ; 

DisplayLine; 

Write ('  '); 

GotoXY (X+WorkPoint-1, Y) ; 

END; 

END  {  case  } 

END; 

8  :  IF  WorkPoint  <=  1  THEN  Uhuh 
ELSE 
BEGIN 

Dec (WorkPoint) ; 

Delete (TempLine, WorkPoint, 1) 

DisplayLine; 

Write ('  '); 

GotoXY (X+WorkPoint-1, Y) ; 

END; 

13  :  Done  :=  True;  {  Enter  ) 

27  :  Quit  :=  True;  (  Esc  ) 

32.. 254  :  IF  Ch  IN  LegalChars  THEN 

IF  Length (TempLine)  >=  MaxWidth  THEN  UhUh 
ELSE 
BEGIN 

Insert (Ch, TempLine, WorkPoint) ; 

DisplayLine; 

GotoXY (X+WorkPoint , Y) ; 

END 

ELSE  Uhuh; 

END  (  case  } 

END; 

UNTIL  Done  OR  Quit; 

IF  Done  THEN  MyLine  j=  TempLine; 

END; 


{  All  of  the  following  routines  are  method  implementations  ) 

! - ) 


CONSTRUCTOR  TextPosition . Init (InitX, InitY  :  Integer); 
BEGIN 

X  :=  InitX;  Y  :=  InitY; 

END; 


FUNCTION  TextPosition .XPos  :  Integer; 

BEGIN 

XPos  :=  X; 

END; 


FUNCTION  TextPosition. YPos  :  Integer; 

BEGIN 

YPos  :=  Y; 

END; 


CONSTRUCTOR  Field. Init (InitX, InitY  :  Integer; 

InitVisible  :  Boolean) ; 

BEGIN 

TextPosition. Init (InitX, InitY) ; 

VisibleState  :=  InitVisible; 

END; 


FUNCTION  Field. IsVisible  :  Boolean; 
BEGIN 

IsVisible  :=  VisibleState; 

END; 


PROCEDURE  Field. MoveTo (NewX, NewY  :  Integer); 
BEGIN 

IF  IsVisible  THEN  Hide; 

X  :=  NewX; 

Y  :=  NewY; 

IF  IsVisible  THEN  Show; 

END; 


PROCEDURE  Field. Show; 

BEGIN 

END; 


PROCEDURE  Field. Hide; 

BEGIN 

END; 


PROCEDURE  Field. Edit; 

BEGIN 

END; 


CONSTRUCTOR  TextField. Init (InitX, InitY 

Integer; 

InitVisible 

Boolean; 

InitText 

Strmg80; 

InitLength 

Integer) ; 

BEGIN 

Field. Init (InitX, InitY, InitVisible) ; 
StringData  :=  InitText; 

FieldLength  :=  InitLength; 

IF  InitVisible  THEN  Show; 

END; 

FUNCTION  TextField. Getdata  :  String80; 

BEGIN 

Getdata  :=  StringData; 
END; 


PROCEDURE  TextField. Show; 
BEGIN 

GotoXY (XPos, YPos) ; 

Write (StringData) ; 
VisibleState  :=  True; 
END; 


PROCEDURE  TextField. Hide; 
BEGIN 

GotoXY (XPos, YPos) ; 
ShowBlanks (FieldLength) ; 
VisibleState  :=  False; 
END; 


(  Move  left  one  position  I 
(  Delete  a  char  in  string  ) 
{  Re-display  the  string  ) 

{  Erase  the  last  char  } 

{  And  put  the  cursor  back  ) 
{  to  the  correct  position  } 


PROCEDURE  TextField. Edit; 
VAR 

AttributeStash  :  Byte; 
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BEGIN 

IF  IsVisible  THEN 
BEGIN 

AttributeStash  :=  TextAttr; 

TextAttr  :=  $70; 

HighLight (XPos, YPos, FieldLength, StringData) ; 

GetLine (XPos,  YPos, StringData, FieldLength, TextChars) ; 
TextAttr  :=  AttributeStash; 

HighLight (XPos, YPos, FieldLength,  StringData) ; 

END; 

END; 


CONSTRUCTOR  BooleanField. Init (InitX, InitY  :  Integer; 

InitVisible  :  Boolean; 
InitToggle  :  Boolean; 
InitTrueStr, 

InitFalseStr  :  String80); 

BEGIN 

Field. Init (InitX, InitY, InitVisible) ; 

Toggle  :=  InitToggle; 

TrueString  :=  InitTrueStr; 

FalseString  :=  InitFalseStr; 

IF  InitVisible  THEN  Show; 

END; 


FUNCTION  BooleanField. Getdata  :  Boolean; 
BEGIN 

Getdata  :=  Toggle; 

END; 


PROCEDURE  BooleanField. Show; 

BEGIN 

GotoXY (XPos, YPos) ; 

IF  Toggle  THEN  Write (TrueString) 
ELSE  Write (FalseString) ; 
VisibleState  :=  True; 

END; 


PROCEDURE  BooleanField. Hide; 

BEGIN 

GotoXY (XPos, YPos) ; 

IF  Toggle  THEN  ShowBlanks (Length (TrueString) ) 
ELSE  ShowBlanks (Length (FalseString) ) ; 
VisibleState  :=  False; 

END; 


PROCEDURE  BooleanField. Edit; 

VAR 

Ch  :  Char; 

Done, Quit  :  Boolean; 

SaveState  :  Boolean; 

AttributeStash  :  Byte; 

BEGIN 

IF  IsVisible  THEN  (  Only  edit  if  it's  visible...  ) 

BEGIN 

SaveState  :=  Toggle;  Done  :=  False;  Quit  :=  False; 
AttributeStash  :=  TextAttr;  TextAttr  :=  $70; 

HighLight (XPos, YPos, MaxLength (TrueString, FalseString) ,  "  ) ; 
Show; 

REPEAT 

IF  KeyPressed  THEN 
BEGIN 

Ch  :=  ReadKey; 

CASE  Ord (Ch)  OF 

0  :  Ch  :=  ReadKey; 

13  :  Done  :=  True; 

27  :  Quit  :=  True; 

ELSE  BEGIN 
Hide; 

Toggle  :=  NOT 
Show; 

END; 

END;  (  CASE  ) 

END; 

UNTIL  Done  OR  Quit; 

IF  Quit  THEN 
BEGIN 
Hide; 

Toggle  :=  SaveState; 

Show; 

END; 

TextAttr  :=  AttributeStash; 

HighLight (XPos, YPos, MaxLength (TrueString, FalseString) , ' ' ) ; 
Show; 

END; 

END; 


(  If  there's  a  keystroke  waiting  } 

(  go  get  it. . .  ) 
f  and  parse  it.  ) 

(  Get  second  half  of  extended  char;  ignore  it) 
(  Enter  means  accept  current  state  of  Toggle) 

(  Esc  means  restore  Toggle  as  it  was  on  entry) 
(  Another  other  ASCII  key:  Flip  Toggle  ) 

(  Erase  the  current  state  string  ) 

Toggle;  {  Flip  Toggle  to  its  opposite  state) 
1  Display  the  alternate  state  string  ) 


(  Erase  current  display  of  state  string  ) 
(  Restore  original  state  of  Toggle  ) 

(  And  re-display  it  ) 


CONSTRUCTOR  IntField . Init (InitX, InitY  :  Integer; 

InitVisible  :  Boolean; 
InitlntVal  :  Integer) ; 


VAR 

Workstring  :  StcinglO; 

BEGIN 

Str (InitlntVal  :  6, Workstring) ; 

TextField. Init (InitX, InitY, InitVisible, Workstring, 6) ; 
IntVal  :=  InitlntVal; 

IF  InitVisible  THEN  Show; 

END; 


FUNCTION  IntField. Getdata  :  Integer; 
BEGIN 

Getdata  :=  IntVal; 

END; 


PROCEDURE  IntField. Show; 

BEGIN 

Str (IntVal  :  6,  Stringdata)  ,• 

TextField.Show; 

END; 

, - 1 

(  Notice  that  there  is  NO  IntField. Hide !  The  mechanism  for  erasing  ) 
{  an  integer  field  is  no  different  from  erasing  any  string  field,  ) 
(  so  objects  of  type  IntField  use  the  Hide  method  inherited  from  } 

(  TextField.  ) 

, - ) 


PROCEDURE  IntField. Edit; 

VAR 

WorkValue, ErrorPos  :  Integer; 

AttributeStash  :  Byte; 

BEGIN 

IF  IsVisible  THEN  (  Only  edit  an  object  if  it's  visible...  ) 

BEGIN 

AttributeStash  :=  TextAttr; 

TextAttr  :=  $70; 

Str  (IntVal  :  6, StringData) ;  (  Convert  the  integer  value  to  a  string  ) 
HighLight (XPos,  YPos, Length (StringData) , Stringdata) ; 

REPEAT  {  And  edit  the  string  until  it's  right  ) 

GetLine (XPos, YPos, StringData, FieldLength, IntChars) ; 

Val (Stringdata, WorkValue, ErrorPos) ; 

IF  ErrorPos  <>  0  THEN  Uhuh; 

UNTIL  ErrorPos  =  0; 

IntVal  :=  WorkValue; 

TextAttr  :=  AttributeStash; 

HighLight (XPos, YPos, Length (StringData) , StringData) ; 

END; 

END; 


BEGIN 

FillChar (Blanker, SizeOf (Blanker) , '  ' ) ; 

Blanker [0]  :=  Chr(80); 

END. 

End  listing  One 


Listing  Two 

USES  Crt, 

Fields;  (  Published  in  DDJ  November  1989  ) 

CONST 

Female  =  Truer- 
Male  =  NOT  Female; 

VAR 

FieldArray  :  ARRAY[1..4)  OF  FieldPtr; 

I  :  Integer; 

BEGIN 

ClrScr; 

Writeln  (' Patient  name:  '); 

Writeln('  sex:  '); 

Writeln ('  age:  '); 

Writeln ('  Physician:  '); 

(  Initialize  the  objects  on  the  heap  &  provide  initial  values:  ) 

FieldArray [ 1 ]  :=  New (TextFieldPtr, Init(15, 1, Invisible, 'Jones, Tom' , 40) ) ; 
FieldArray [2]  :=  New (BooleanFieldPtr, Init (15, 2, Invisible, 

Female, ' Female' , 'Male' ) ) ; 

FieldArray [3)  :=  New (IntFieldPtr, Init (15, 3, Invisible, 42) ) ; 

FieldArray [4]  :=  New (TextFieldPtr, Init (15, 4, Invisible, 'Dr.  Asimov' , 40) ) ; 

{  First  display  initial  values  through  polymorphic  calls  to  Show:  ) 

FOR  I  :=  1  TO  4  DO  FieldArray [ I ] * . Show; 

(  Now  edit  each  one  through  a  polymorphic  call  to  the  Edit  method:  ) 

FOR  I  :=  1  TO  4  DO  FieldArray [ I ] * . Edit ; 

END. 

End  Listings 
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OF  I  N  T  E  R  EST 


IEEE  Software  magazine  lias  announced 
a  December  31  deadline  for  the  third 
annual  Gordon  Bell  Prize  for  outstand¬ 
ing  achievements  in  the  application  of 
parallel  processing  to  scientific  and  en¬ 
gineering  problems. 

The  prize  is  sponsored  by  Gordon 
Bell,  vice  president  of  engineering  at 
Ardent  Computer  Systems;  the  judging 
is  administered  by  IEEE  Software ,  which 
is  published  by  the  IEEE  Computer  So¬ 
ciety,  the  international  professional  or¬ 
ganization  of  the  Institute  of  Electrical 
and  Electronics  Engineers  Inc. 

Two  $1000  prizes  will  be  awarded 
to  the  two  best  entries  of  three  catego¬ 
ries.  In  the  performance  category,  the 
submitted  program  must  run  faster  than 
any  other  comparable  engineering  or 
scientific  application.  Judges  will  con¬ 
sider  the  megaflop  rate  based  on  actual 
operation  counts  or  the  solution  of  the 
same  problem  with  properly  tuned  code 
on  a  machine  of  known  performance 
as  suitable  evidence. 

In  the  price/performance  category, 
the  entrant  must  show  that  the  applica¬ 
tion  divided  by  the  cost  of  the  system 
is  better  than  any  other  entry.  Perfor¬ 
mance  measurement  is  the  same  for 
the  performance  category.  Price  will 
be  the  list  price  of  the  computational 
engine  (CPUs,  including  adequate  mem¬ 
ory  to  run  the  program).  Peripherals 
and  software  need  not  be  included  in 
the  price.  Entrants  must  submit  the  out¬ 
put  from  a  Linpack  100  x  100  bench¬ 
mark  showing  a  speedup  of  at  least  5 
megaflops. 

The  compiler  parallelization  category 
is  for  the  compiler/application  that  gen¬ 
erates  the  most  speedup,  which  will  be 
measured  by  the  execution  time  with¬ 
out  automatic  parallelization  divided 
by  the  execution  with  automatic  paral¬ 
lelization.  A  third  run  that  uses  com¬ 
piler  directives  to  improve  parallelization 
may  also  be  submitted.  For  entry  infor¬ 
mation,  contact: 

1989  Gordon  Bell  Prize 
c/o  IEEE  Software 
10662  Los  Vaqueros  Cir. 

Los  Alamitos,  CA  90720-2578 


TurboPower  has  released  Object  Pro¬ 
fessional  1.0,  a  library  of  object-ori¬ 
ented  routines  that  enhances  the  pro¬ 
ductivity  of  OOP  in  Turbo  Pascal  5.5 
by  providing  more  than  30  high-level 
object  types  with  more  than  1000  meth¬ 
ods  and  routines  in  the  categories  of 
user-interface  design,  data  manipula¬ 
tion,  and  low-level  system  access.  Ob¬ 
ject  Professional  takes  advantage  of  all 
of  Turbo  Pascal  5.5's  advanced  object- 
oriented  features,  including  construc¬ 
tors,  destructors,  and  static  methods. 

Object  Professional  allows  interfaces 
ranging  from  text-mode  Presentation 
Manager  look-alikes,  to  Lotus-style  menu 
bars,  to  your  own  look  and  feel  design. 
The  window  object  is  the  root  of  the 
hierarchy,  and  supports  overlapping, 
resizeable  text  windows  with  support 
for  scroll  bars,  and  other  mouse  opera¬ 
tions.  Additional  object  types  inherit 
the  window's  functionality,  and  offer 
data  entry  fields,  full-screen  forms,  pull¬ 
down  and  horizontal-bar  menu  systems, 
pick  lists,  file  selection  boxes,  and  more. 
Generalized  capabilities  for  stacks,  linked 
lists,  and  virtual  arrays  are  also  offered. 

Object  Professional's  system-oriented 
routines  provide  capabilities  like  TSR 
management,  interrupt  service  routines, 
EMS  and  extended  memory  manage¬ 
ment,  enhanced  keyboard  support,  BCD 
arithmetic,  and  others.  The  TSR  man¬ 
ager  is  new,  and  swaps  to  disk  or  EMS, 
squeezing  complex  pop-up  programs 
into  as  little  as  5K  of  normal  RAM  space. 
Although  we  haven’t  had  a  chance  to 
fiddle  with  Object  Professional  yet,  Tur¬ 
boPower  has  a  reputation  for  good  prod¬ 
ucts,  good  prices,  and  good  people. 
We  ll  be  reviewing  Object  Professional 
before  long  to  see  if  this  trend  contin¬ 
ues  with  this  latest  product. 

Object  Professional  1.0  is  based  on 
the  Turbo  Professional  5.0  toolkit,  which 
TurboPower  will  continue  to  sell  and 
support,  and  which  compiles  and  runs 
without  modification  under  Turbo  Pas¬ 
cal  5  5.  Object  Professional  sells  for 
$150,  and  includes  complete  source 
code,  documentation,  and  a  royalty- 
free  license  to  develop  commercial  ap¬ 
plications.  Reader  service  no.  20. 
TurboPower  Software 
P.O.  Box  66747 
Scotts  Valley,  CA  95066-0747 
408-438-8608 

Quarterdeck  Office  Systems  has  an¬ 
nounced  QRAM,  a  tool  for  organizing 
and  allocating  memory  resources  for 
8088/86-based  PCs  and  AT-style  286 
PCs.  QRAM  gives  XT-  and  AT-class  PCs 
with  EMS  4.0  or  EEMS  memory  the  ca¬ 
pacity  to  load  programs  into  high  mem¬ 
ory  (between  640K  and  1024K),  previ¬ 
ously  unavailable  to  DOS.  The  ability 


ter  load  LAN  drivers,  TSRs,  and  mouse 
drivers  into  high  memory  allows  con¬ 
ventional  DOS  memory  to  be  used  by 
applications.  QRAM  is  the  only  prod¬ 
uct  available  that  adds  load-high  capa¬ 
bility  on  top  of  any  EMS  4.0  or  EEMS 
driver.  It  costs  $59.95.  Reader  service 
no.  21. 

Quarterdeck  Office  Systems 
150  Pico  Blvd. 

Santa  Monica,  CA  90405 
213-392-9851 

A  set  of  productivity  tools  for  Turbo  C 
and  Turbo  Pascal  programmers  has  been 
released  by  Mostly  Mice  Software  Inc. 
The  menuing  and  mouse  driver  tools, 
which  are  patches  to  the  Turbo  pro¬ 
gramming  environment,  make  all  Turbo 
C  2.0  and  Turbo  Pascal  5.5  commands 
and  functions  available  through  pull¬ 
down  menus.  Programmers  can  then 
]X)int-and-sh(X)t  at  commands,  then  drop 
them  into  a  program. 

Additionally,  the  tools  allow  you  to 
highlight  blocks  of  text  from  within  an 
Edit  window  by  dragging  the  mouse, 
to  switch  between  Edit  and  Watch  win¬ 
dows  by  pointing-and-shooting,  and  to 
work  in  either  25  or  43/50  line  mode. 
The  drivers  work  within  DESQview  and 
can  be  used  with  all  Microsoft-compat¬ 
ible  mice. 

The  Turbo  drivers,  like  other  Mostly 
Mice  products  (menuing  and  mouse 
drivers  for  Lotus,  Wordstar,  WordPer¬ 
fect,  etc.),  are  developed  by  indepen¬ 
dent  programmers  around  the  country 
who  work  on  a  royalty  basis  with  Mostly 
Mice.  Company  president  Simeon  Ber¬ 
man  told  DDJ,  “I'm  interested  in  evalu¬ 
ating  other  people's  work  for  our  fam¬ 
ily  of  products,  not  just  mouse  drivers.'' 

The  Turbo  C  and  Turbo  Pascal  Menu¬ 
ing  and  Mouse  Drivers  (both  include  a 
KEY.COM  keyboard  analyzer)  sell  for 
$29. 95  each.  Reader  service  no.  22. 
Mostly  Mice  Software,  Inc. 

125  Gates  Ave. 

Montclair,  NJ  07042 

201-746-9256  for  technical  information 

800-283-4080  for  orders 

Digitalk  Inc.  is  now  shipping  Smalltalk/ 
V  PM,  the  first  programming  environ¬ 
ment  for  OS/2  Presentation  Manager. 
An  object-oriented  environment  that  is 
fully  integrated  with  PM,  Smalltalk/V 
PM  can  be  used  to  prototype  and  de¬ 
liver  user-interface  intensive  applica¬ 
tions,  such  as  database  front  ends,  CASE 
tools,  and  financial  models. 

Jim  Anderson,  president  of  Digitalk, 
claims  that  the  technology  behind  this 
product  “prevents  PM  from  becoming 
a  massive  knot  of  complications.” 

The  first  and  only  fully  compiled  Small- 
(continued  on  page  165) 
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talk,  this  product  gives  developers  a 
responsive  environment  and  access  to 
PM  features.  Smalltalk/V  PM  allows  the 
programmer  to  take  advantage  of  the 
unique  benefits  of  PM  without  sacrific¬ 
ing  performance. 

The  source  code  is  compatible  with 
Smalltalk/V  286  and  Smalltalk/V  Mac 
products,  which  allows  portability  of 
applications  between  different  environ¬ 
ments.  The  developer  can  use  browsers 
to  navigate  through  code  and  explore 
PM.  Digitalk  claims  that  the  system  is 
crash  proof,  which  encourages  an  ex¬ 
perimental  style  of  programming.  It  sells 
for  $499.95,  and  includes  a  user  man¬ 
ual  and  tutorial  for  learning  object- 
oriented  programming.  Jeff  Duntemann 
plans  on  looking  further  into  this  prod¬ 
uct  in  his  December  1989  “Structured 
Programming”  column.  Reader  service 
no.  23- 
Digitalk  Inc. 

9841  Airport  Blvd. 

Los  Angeles,  CA  90045 
213-645-1082 

The  MasPar  Computer  Corpora¬ 
tion’s  family  of  computers  has,  in  addi¬ 
tion  to  the  standard  Unix  environment, 
a  graphical,  interactive  programming 
environment  called  the  MasPar  Program¬ 
ming  Environment  (MPPE).  A  versa¬ 
tile  set  of  tools  that  enables  users  to 
apply  data  parallel  programming  al¬ 
gorithm  techniques  to  large  numbers 
of  processors,  the  MPPE  helps  over¬ 
come  design  barriers  that  hamper  ap¬ 
plication  development  in  other  multi¬ 
ple  processor  systems.  The  MPPE  is 
designed  to  operate  over  network- 
based  systems  using  the  X-Window 
system  protocol  layer,  and  permits  pro¬ 
grammers  to  develop  and  debug  ap¬ 
plications  using  the  windowing  capa¬ 
bility  of  a  workstation. 

The  key  tool  is  an  “on-demand” 
source-level  debugger.  Others  include 
browsers,  animators,  and  visualizers, 
and  are  accessed  by  a  graphical  user 
interface.  Designed  for  programming, 
adaptation,  and  debugging  of  compu- 
tationally-intensive  applications,  these 
tools  supposedly  bring  a  new  level  of 
programmer  productivity  to  high-end 
computing. 

The  MPPE  provides  program  devel¬ 
opment,  check-out,  debug,  and  anima¬ 
tion  facilities  that  are  geared  to  the 
task  of  data  parallel  programming.  An 
integrated  editor,  data  display  facility, 
and  symbolic  debugger  allow  a  pro¬ 
grammer  to  move  freely  between  exe¬ 
cution,  check  out,  what-if  analysis,  and 
code  modification.  A  browse  capabil¬ 
ity  immediately  answers  questions  such 
as  “where  is  this  subroutine  called?” 


and  “where  is  this  block  COMMON 
referenced?” 

With  the  MPPE  a  programmer  can 
see  how  code  actually  executes  in  a 
variety  of  situations,  including  hard¬ 
ware  utilization  for  optimization  and 
tuning,  and  aggregation  of  individual 
data  cells  into  high-level  abstractions. 
MPPE  is  available  for  all  MasPar- 
supported  languages.  Reader  service 
no.  34. 

MasPar  Computer  Corporation 
749  North  Mary  Avenue 
Sunnyvale,  CA  94086 
408-736-3300 

The  Whitewater  Group  has  released 
the  Whitewater  Resource  Toolkit  for 
Microsoft  Windows,  which  allows  pro¬ 
grammers  to  manage  a  Windows  appli¬ 
cation’s  look  and  feel,  and  to  create 
Windows  resources  such  as  dialog 
boxes,  bitmaps,  cursors,  icons,  and  pull¬ 
down  menus.  Programmers  can  also 
create  keyboard  accelerators  and  string 
resources. 

According  to  Whitewater’s  Hope  Gil¬ 
lespie,  “One  of  the  major  difficulties 
facing  the  Windows  programmer  using 
conventional  tools  is  the  time-consum¬ 
ing  edit-compile-link  development  cy¬ 
cle.  The  Whitewater  Resource  Toolkit’s 
interactivity  allows  programmers  to  im¬ 
mediately  see  the  results  of  their  pro¬ 
gramming  from  within  Windows,  greatly 
increasing  their  productivity.” 

The  toolkit  is  a  stand-alone  applica¬ 
tion  that  complements,  but  does  not 
require,  the  Microsoft  Windows  Soft¬ 
ware  Development  Kit  (SDK)  and  its 
resource  compiler  (RC).  It  is  compat¬ 
ible  with  all  Windows  resource  file  for¬ 
mats,  and  can  generate  RC-compatible 
script  and  bitmap  files.  It  has  bitmap, 
cursor,  icon,  menu,  dialog,  string  table, 
and  accelerator  tables  editors. 

Completely  written  in  Actor,  the  tcxrlkit 
is  geared  toward  C  programmers,  Mi¬ 
crosoft  SDK  users,  and  Actor  program¬ 
mers.  It  requires  Microsoft  Windows 
and  will  run  on  the  IBM  PC/AT,  PS/2, 
and  compatibles  with  1  Mbyte  of  RAM, 
a  hard  disk,  graphics  display  of  EGA 
or  better  and  adapter,  mouse,  and  DOS 
2.0  or  higher.  It  includes  full  support 
for  the  Lotus/Intel/Microsoft  Expanded 
Memory  Specification  EMS  3-2,  and  sells 
for  $195. 

At  the  same  time,  The  Whitewater 
Group  announced  WinTrieve,  a  Micro¬ 
soft  Windows-based  file  indexed  man¬ 
ager,  which  is  a  comprehensive  set  of 
tools  for  building  custom  data  manage¬ 
ment  procedures  into  Microsoft  Win¬ 
dows  applications.  Zack  Urlocker,  man¬ 
ager  of  developer  relations,  claims  it 


“allows  programmers  to  create  Win¬ 
dows  applications  that  access  database 
information  faster  and  with  less  pro¬ 
gramming  than  ever  before.” 

WinTrieve  has  an  ISAM  (indexed  se¬ 
quential  access  method)  server,  a  C 
application  programming  interface  (API) 
library,  and  an  Actor  class  library.  The 
ISAM  server  provides  a  method  for  stor¬ 
ing  and  retrieving  data  based  on  in¬ 
dexes,  and  includes  random  and  se¬ 
quential  access,  concurrent  multiple  file 
access,  automatic  updating  of  indexes, 
file  and  record  level  locking,  multiple 
indexes,  journaling  across  multiple  files, 
and  transaction  commit  and  rollback. 

The  C  API  library  has  C  functions  that 
can  access  the  ISAM  server,  and  effec¬ 
tively  hides  the  ISAM  server  while  mini¬ 
mizing  responsibility  for  session  initia¬ 
tion  and  termination. 

WinTrieve  requires  Microsoft  Win¬ 
dows  and  the  IBM  XT,  AT,  PS/2,  and 
compatibles,  a  hard  disk,  graphics  dis¬ 
play  and  adapter,  and  DOS  2.0  or  higher. 
It  uses  90K  of  memory  running  as  a 
separate  application,  and  includes  full 
support  for  the  Lotus/Intel/Microsoft 
Expanded  Memory  Specification  EMS 
3.2.  When  used  with  C,  it  requires  640K, 
and  with  Actor,  1  Mbyte  of  RAM.  It  sells 
for  $395.  Reader  service  no.  24. 

The  Whitewater  Group 
600  Davis  St. 

Evanston,  IL  60201 

312-328-3800 

800-869-1144 

Oasys  Inc.  has  announced  a  Green 
Hills  C++  compiler  which,  claims  the 
company,  is  the  only  C++  compiler 
that  supports  cross-  and  native-mode 
development.  The  compiler  supports 
K&R  C  and  is  ANSI  C  compliant. 

In  addition  to  providing  OOP  fea¬ 
tures  such  as  data  abstraction,  type  check¬ 
ing,  and  overloading  of  function  names 
and  operators,  the  Green  Hills  C++  com¬ 
piler  also  provides  classes  with  scope, 
and  overloading  new  and  arrow  opera¬ 
tors.  Green  Hills  has  also  built  its  stan¬ 
dard  optimizing  techniques,  such  as 
inlining,  loop  unrolling,  and  register 
caching,  into  the  compiler. 

Initially,  the  system  will  run  on  Sun-3 
systems,  though  Oasys  says  that  it  will 
be  ported  to  Unix  workstation  and  mini¬ 
computer  platforms  in  the  near  future. 
Reader  service  no.  25. 

Oasys  Inc. 

230  Second  Ave. 

Waltham,  MA  02154 
617-890-7889 
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More  on  the  Numbers  Game 

When  HyperCard  first  appeared  and  its  supporters  proclaimed  that  user  programming  had 
come  to  the  Mac,  I  was  among  'em.  We  weren’t  wrong:  There  are  a  lot  of  ordinary  folks 
using  HyperCard  and  its  scripting  language,  HyperTalk;  but  HyperCard’s  lack  of  integration 
with  anything  else  (it’s  not  part  of  the  system,  it  doesn’t  interact  with  other  applications  in  any 
interesting  way,  and  it  can’t  run  under  MultiFinder  effectively  on  mere  mortals’  machines)  all  limit 
its  value  as  a  user  programming  tool. 

As  it  turns  out,  HyperCard’s  greatest  contribution  to  user  programming  could  turn  out  to  have 
nothing  to  do  with  HyperTalk  or  stacks.  At  MacWorld  Expo  in  Boston  I  spent  some  time  talking 
with  developers  from  Software  Ventures,  publishers  of  Microphone,  and  Informix,  publishers  of 
Wingz.  Both  companies  are  making  extensive  use  of  XCMDs  or  XFCNs,  the  external  commands  or 
functions  first  developed  to  allow  developers  to  extend  HyperTalk. 

Microphone  III  supports,  in  its  scripting  language,  virtually  all  the  external  command  functionality 
of  HyperCard.  XCMDs  written  for  HyperCard  stacks  can  be  plugged  into  Microphone  directly, 
without  modification.  Wingz  takes  a  different  approach,  using  only  XFCNs  to  extend  its  HyperScript 
language  (I  saw  an  SQL  interface  made  up  of  XFCNs).  This  represents  not  so  much  a  user 
programming  approach  as  evidence  that  XFCNs  are  becoming  a  kind  of  lingua  franca  for  Macintosh 
programming.  Perhaps  the  packaging  for  the  version  of  HyperCard,  when  it  finally  appears,  will 
proclaim  that  HyperCard  also  supports  XCMDs  and  XFCNs. 

“Statistical  thinking,"  H.G.  Wells  once  wrote,  “will  one  day  be  as  necessary  for  efficient 
citizenship  as  the  ability  to  read  and  write."  That  day  has  dawned  on  an  American  citizenry  —  both 
illiterate  and  innumerate. 

I  have  mentioned  here  the  important  book  Innumeracy ,  by  John  Allen  Paulos.  Paulos  describes 
the  innumeracy  problem  more  clearly  than  anyone  else  I've  encountered,  with  many  appropriate 
and  entertaining  examples  of  innumeracy  in  the  fourth  estate. 

I  recently  came  across  a  couple  of  instances  of  innumeracy  that  show  how  important  it  is  to 
question  the  numbers  that  are  presented  to  you  every  day,  and  how  often  you  can  reject  them  on 
the  basis  of  simple  plausibility  checks. 

In  a  New  York  Times  magazine  piece  on  Steve  Jobs  last  August,  the  writer  said  that  Jobs  often 
overprojected  sales  of  the  Macintosh  during  its  development  phase,  sometimes  by  as  much  as  90 
percent.  The  implication  was  that  Jobs  could  be  wildly  optimistic  about  the  Mac,  and  independent 
evidence  certainly  supports  that  implication.  I  haven’t  checked  the  90  percent  figure  with  Apple 
because  I’m  only  interested  here  in  plausibility,  but  is  it  plausible?  Is  a  90  percent  sales  overprojection 
on  a  product  as  innovative  as  the  Mac  evidence  of  wild  enthusiasm?  I  don’t  think  so,  especially 
because  the  90  percent  figure  is  given  as  the  worst  overprojection  Jobs  made,  Don’t  you  suspect 
that  actual  sales  for  the  first  year  were  x  thousand  units,  and  that  Jobs  had  once  projected  sales  of 
lOx  thousand  units?  That  would  be  an  overprojection  of  900  percent,  a  figure  consistent  with  Jobs’ 
evangelical  enthusiasm  for  the  Mac.  I  may  be  misjudging  the  Times  writer,  but  this  is  exactly  the 
sort  of  confusion  about  percentages  that  often  appears  in  newspapers. 

A  second  implausible  use  of  numbers  appeared  in  Paulos’s  own  book.  Paulos  describes  a  safety 
index,  a  measure  of  risk  that  he  would  like  to  see  attached  to  risky  activities  when  they  are  discussed 
in  the  press.  His  safety  index  is  the  base-10  logarithm  of  the  number  of  deaths  (or  other  appropriate 
risky  outcome)  per  year  attributed  to  the  activity.  Inasmuch  as  one  person  in  5300  dies  each  year 
in  the  U.S.  from  a  car  crash,  Paulos  derives  a  safety  index  for  driving  (actually,  for  being  in  a  moving 
vehicle)  of  log  5300,  or  3-7.  He  similarly  derives  a  safety  index  of  2.9  for  smoking,  so  smoking  has 
a  lower  safety  index,  and  is  less  safe  than  riding  in  a  car.  Whether  your  smoking  is  a  greater  risk 
to  your  health  than  your  driving  would  depend  on  other  factors,  such  as  how  much  you  do  of  each, 
and  under  what  conditions,  but  the  index  does  seem  to  provide  some  useful  information.  (In 
practice,  you'd  probably  want  to  use  log(l+incidence)  to  avoid  negative  indices.) 

In  his  discussion  of  the  index,  Paulos  makes  the  interesting  assertion:  "[Mjalaria's  index  is  orders 
of  magnitude  lower  in  most  of  the  world  than  it  is  in  the  United  States."  Let’s  examine  the  plausibility 
of  that  claim.  It’s  clear  from  reading  the  rest  of  the  book  that  when  Paulos  uses  the  expression  “order 
of  magnitude,"  he  means  a  power  of  10.  “Orders  of  magnitude,”  then,  means  at  least  a  power  of 
100.  For  two  safety  indices  to  differ  by  a  power  of  100,  the  associated  incidences  of  malaria  deaths 
must  differ  by  a  factor  of  10100.  This  (literally  astronomical)  number  does  not  look  to  me  like  a 
figure  that  could  arise  from  any  conceivable  empirical  data. 

Paulos  says  that  he  uses  his  middle  name  in  his  writing  so  that  no  one  will  confuse  him  with  the 
Pope.  If  he  just  doesn’t  want  to  be  thought  infallible,  this  example  will  do. 

Michael  Swaine 
editor-at-large 
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Hindsight  and 
The  Crystal  Ball 


Over  the  past  few  months,  Mike  Floyd  has  immersed  himself  in  object-oriented  program¬ 
ming  in  its  various  guises,  becoming  our  in-house  expert  on  the  subject  in  the  process. 
Because  this  month ’s  theme  is  object-oriented  programming,  it  seems  natural  that  Mike 
shares  some  of  what  he  sees  as  the  promise  and  the  pitfalls  of  OOP.  — J.E. 


Earlier  this  year,  just  prior  to  the  release  of  Turbo  Pascal  5.5,  we  asked  Anders  Hejlsberg,  chief 
architect  of  Turbo  Pascal,  if  Borland  was  going  to  follow  the  path  of  C++  and  distinguish 
Object  Pascal  from  structured  Pascal:  Was  Borland  adding  to  the  product  line  with  TOP  (Turbo 
Object  Pascal)?  Anders'  reply  made  perfect  sense.  “Adding  objects  to  Turbo  Pascal  is  simply  the 
next  step  in  the  evolution  of  the  language,”  he  said.  “From  this  moment  on,  Turbo  Pascal  is  an 
object-oriented  language.” 

So,  is  this  what  we  can  expect  to  see  in  terms  of  programming  and  programming  languages  over 
the  coming  decade?  If  not,  what  does  the  future  of  programming  —  object-oriented  or  otherwise  — 
hold?  (Trying  to  answer  questions  such  as  these  is  much  like  driving  down  the  highway  with  your 
eyes  fixed  on  the  rearview  mirror  —  you  spend  more  time  worrying  about  where  you’ve  been 
without  having  a  clue  as  to  where  you’re  going.) 

Other  questions  come  to  mind  too.  Will  C  merge  with  C++  and  become  D?  Although  this  seems 
a  natural  next  step  for  C,  there  are  many  pressures  that  may  keep  it  from  happening,  particularly 
the  challenge  of  gening  a  standard  through  ANSI. 

One  big  question  is, “Where  will  the  next  set  of  development  tools  come  from?”  Programmers 
who  have  grown  used  to  having  sophisticated  tools  aren’t  willing  to  return  to  the  dark  ages  that 
existed  before  development  environments,  debugging  facilities,  and  library  support.  But  for  a 
number  of  reasons,  OOP  tools  have  been  relatively  slow  forthcoming.  Until  these  tools  begin  to 
emerge,  many  programmers  will  be  reluctant  to  make  the  move  to  OOP.  Traditionally,  third-party 
vendors  have  filled  the  gap,  but  the  lack  of  a  standard  or  dominant  environment  and  the  past 
experience  of  putting  out  tools  too  early  has  made  third-party  developers  gun  shy.  Indeed,  market 
pressure  from  users  and  competing  vendors  may  force  some  of  the  big  guys  to  continually  pack 
their  class  libraries  with  more  bang  for  the  buck,  thereby  limiting  market  opportunities  for  smaller 
tool  developers  even  more. 

Some  of  the  burden  falls  on  the  shoulders  of  the  individual  programmer.  After  all,  an  object- 
oriented  system  is  extensible.  In  Smalltalk,  you  don’t  write  source  code,  you  add  components  to 
the  system.  Likewise,  languages  such  as  C++  and  Object  Pascal  encourage  the  programmer  to  weld 
homegrown  components  with  canned  objects  to  create  new  tools  for  the  workbench.  For  the 
optimistic  programmer,  this  is  a  time  of  Renaissance;  for  others,  a  time  of  chaos. 

For  those  of  us  at  DDJ,  this  month’s  issue  is  not  just  the  last  one  of  the  year,  but  the  last  of  the 
decade.  It  may  be  appropriate,  then,  that  object-oriented  programming  is  the  theme  that  takes  the 
next  decade  into  the  next  century. 

But,  lest  you  think  DDJ  is  adding  to  the  object-oriented  hype  (OOH?),  think  again.  One  size  fits 
all?  We’re  not  so  sure.  You  may  want  to  pay  particular  attention  to  Scott  Guthery  as  he  tries  on  the 
“Emperor’s  New  Clothes.”  And  OOP  may  not  be  the  only  bully  on  the  block  either,  at  least 
according  to  Ronald  Fischer,  who  believes  that  Functional  Programming  may  influence  the  way 
we  program  over  the  next  decade.  Ah,  well.  If  nothing  else,  it’ll  be  interesting  to  see  what  unravels 
in  the  rearview  mirror  over  the  next  ten  years. 
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Striding  Forth  With  Mini- 
Interpreters 

Dear  DDJ, 

“Roll  your  own  Mini-Interpreters,”  by 
Michael  Abrash  and  Dan  Illowsky  in 
the  September  DDJ  was  fun  to  read. 
What  they  have  done,  essentially,  is 
show  how  to  make  a  Forth-like  pro¬ 
gram  without  even  Forth’s  overhead. 
Forth  is  legendary  for  producing  ex¬ 
tremely  compact  code  within  the  Forth 
environment.  The  authors  went  them 
one  better  by  eliminating  even  that. 

What  the  article  doesn’t  mention,  is 
that  there  is  nothing  to  prevent  high- 
level  language  compilers  from  emitting 
this  type  of  threaded  code.  All  that  is 
required  is  to  forego  separate  compila¬ 
tion  and  process  the  entire  application, 
including  all  subprograms  and  perhaps 
even  the  run-time  library,  via  a  globally 
optimizing  compiler  (GOC). 

A  GOC  knows  the  list  of  all  subpro¬ 
grams  and  the  entire  calling  tree.  It  can 
automatically  build  one  or  more  jump 
vector  tables,  and  compose  the  inter¬ 
preted  data  streams.  Because  of  the 
low  overhead  of  procedure  calls,  even 
tiny  sequences  such  as  A=B+C  could 
be  generated  as  threaded  calls  rather 
than  as  direct  machine  code.  Thus,  sub¬ 
program  granularity  much  finer  than 
the  application  code  is  possible,  and 
the  compiler  would  be  able  to  trade  off 
code-size  versus  execution-speed  over 
an  extraordinary  range. 

Recent  press  reports  show  that  even 
the  giants  like  Lotus  and  Ashton-Tate 
are  killing  themselves  trying  to  make 
their  code  fit  the  640K  limits  of  DOS. 
Assuming  that  others  have  similar  prob¬ 
lems,  there  could  be  quite  a  market  for 
GOCs.  Attention  compiler  vendors! 
Here’s  a  chance  to  make  more  money. 

Of  course,  global  optimization  has 
its  cost;  namely  glacial  compilation 
speed.  The  right  way  to  use  it  would 
be  to  develop  the  application  on  a  386 
in  protected  mode,  using  fast  compil¬ 
ers  and  whatever  memory  is  needed. 


It  should  remain  in  this  environment 
even  through  beta  testing,  until  the  code 
can  be  frozen.  Then,  assuming  a  bullet¬ 
proof  and  bug  free  GOC,  it  can  be 
compiled  once  more  with  global  opti¬ 
mization.  The  compiler  must  be  in¬ 
structed  about  just  how  compact  the 
program  must  be.  For  example,  “take 
this  program,  which  needs  843K  for 
code  using  MSC,  and  compile  it  to  fit 
in  no  more  than  403K  while  minimiz¬ 
ing  the  impact  on  speed.”  Who  cares 
if  it  takes  a  week  or  so  to  finish?  The 
GOC  could  even  be  run  as  a  service 
bureau,  compiling  on  a  Cray,  and  charg¬ 
ing  as  much  as  one  dollar  per  line  for 
a  compile.  If  it  works,  it  would  be  well 
worth  it. 

Dick  Mills 

Burlington,  Vermont 

Where  There’s  Smoke,  There’s  Ire 

Dear  DDJ , 

The  article  in  the  September  1989  DDJ 
entitled  “Roll  Your  Own  Minilanguages 
with  Mini-Interpreters”  by  Abrash  and 
Illowsky  offended  me.  No,  not  by  the 
content;  by  the  title.  No,  “roll  your  own” 
is  not  just  an  expression. 

I  hold  cigarette  smokers  (and  smok¬ 
ers  of  anything  else)  in  very  low  re¬ 
gard.  Next  time,  try  some  synonyms 
like  “create,”  “devise,”  or  “construct” 
that  have  far  fewer  connotations. 

Bob  Bryla 

Barrington,  Illinois 

More  Kudos  for  Abrash  and 
IUowsky 

Dear  DDJ, 

A  few  remarks  on  a  couple  of  subjects. 
One:  Since  the  word  polymorphism  is 
being  bandied  about  a  lot  these  days, 
the  following,  “loosely  typed”  defini¬ 
tion  may  prove  interesting. 

Polymorphism  is  a  polysyllabic  noun 
used  to  “encapsulate”  the  idea  that:  1) 
to  treat  “loosely  coupled”  items,  you 
use  “loosely  typed”  variables;  and  2) 
“loosely  typed”  variables  can’t  be  bound 
until  run-time,  an  activity  often  referred 
to  by  way  of  another  buzzword,  “late- 
binding.” 

Two:  Several  hips  and  half  as  many 
hoorays  for  the  Abrash  and  Illowsky 
article  in  the  September  issue.  The  most 
exciting  thing  about  assembly  language 
is  not  the  control  it  gives  one  over  the 
machine,  nor  the  reduction  in  memory 
requirements  and  execution  time.  As 
Abrash  and  Illowsky  point  out,  the  most 
exciting  thing  about  assembly  language 
is  that  it  gives  you  as  much  control  over 
the  design  of  your  program  logic  and 
data  layout  as  you’re  ever  likely  to  get. 

To  which  I  would  like  to  add:  If  you 
want  even  more  control,  you  need  your 
own  assembler,  perhaps  your  own  edi¬ 


tor,  and  even  your  own  operating 
system  —  only  for  your  own  private 
use,  of  course  (that  way  there’s  no  ef¬ 
fective,  market-oriented  argument 
against  actually  tackling  the  job).  As  a 
fantastic  learning  experience,  working 
on  any  of  them  would  be  hard  to  beat. 
Let’s  hope  DDJhas  more  .ASM  goodies 
in  the  queue. 

Mark  Rhyner 

Chicago,  Illinois 

LZW  Patent  Issues 

Dear  DDJ, 

“LZW  Data  Compression,”  by  Mark  Nel¬ 
son  (DDJ,  October  1989)  is  a  nice  ex¬ 
position  on  the  LZW  algorithm.  But 
before  your  readers  decide  to  use  this 
method  in  any  application  (except  per¬ 
haps  for  purely  personal  use),  they 
should  know  that  the  algorithm  is  pat¬ 
ented. 

Terry  Welch  is  listed  as  the  inventor 
of  U.S.  Patent  4,558,302,  “High  Speed 
Data  Compression  and  Decompression 
Apparatus  and  Method,”  December 
1985,  assigned  to  Sperry  Corporation 
(now  Unisys).  The  Unix  compress  util¬ 
ity  and  several  commercial  and  share¬ 
ware  programs  are  apparently  infring¬ 
ing  on  this  patent  (unless  they  have 
licensed  it  from  Unisys). 

If  you  wish  to  use  this  method  in  a 
commercial  setting,  you  should  con¬ 
tact  Unisys  for  a  license,  or  at  least 
consult  your  legal  counsel  first. 

Ray  Gardner 

Englewood,  Colorado 

Mark  responds:  When  I  wrote  the  LZW 
article  I  was  unaware  of  any  patent 
on  the  algorithm.  The  issue  has  just 
surfaced  in  the  press  because  of  con¬ 
cern  in  CCITT  Group  7  over  approval 
of  the  BTLZ  algorithm  for  data  com¬ 
pression  in  the  V.42bis  modem  stan¬ 
dard.  Unisys,  British  Telecom,  and  IBM 
apparently  all  have  some  claim  on  the 
algorithm.  Robert  Bramson,  a  patent 
attorney  for  Unisys,  has  been  quoted 
as  saying  they  will  license  the  algo¬ 
rithm  for  a  one-time  fee  of  $20, 000. 

I  have  not  seen  the  Unisys  patent,  so 
I  don’t  know  what  their  specific  claims 
are.  However,  I  am  not  aware  of  any 
attempt  by  Unisys  to  show  infringe¬ 
ment  by  software  developers.  The  BTLZ 
algorithm  seems  to  be  concerned  with 
hardware  implementations.  In  the  event 
that  they  do  pursue  their  claim  with 
software  developers,  they  will  be  very 
busy,  as  there  are  literally  hundreds  of 
potentially  infringing  programs  in  the 
commercial  marketplace  alone.  And 
they  certainly  cannot  claim  a  compre¬ 
hensive  patent  on  basic  LZ  compres¬ 
sion,  as  Terry  Welch,  the  patent  holder, 
(continued  on  page  12) 
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(continued  from  page  8) 
was  not  the  inventor. 

I  agree  with  Mr.  Gardner  that  any¬ 
one  who  intends  to  use  LZW  compres¬ 
sion  in  a  commercial  product  would 
be  wise  to  consult  legal  counsel  first. 

Finally,  I  would  like  to  suggest  that 
DDJ  readers  begin  a  letter-writing  cam¬ 
paign  directed  to  members  of  Congress, 
the  ACM,  and  the  IEEE.  The  current 
confusion  over  copyright  and  patent 
issues  in  the  software  development  world 
only  serves  to  stifle  both  creativity  and 
productivity.  At  present  the  only  way 
questions  regarding  the  validity  of  copy¬ 
rights  and  patents  are  being  answered 
is  through  random  decisions  from  le¬ 
gal  proceedings.  Copyright  and  patent 
laws  both  need  to  be  updated  to  work 
properly  in  the  1990s. 

Small  Is  Better 

Dear  DDJ, 

Jeff  Duntemann  is  the  second  person  I 
have  encountered  in  print  this  month 
who  characterizes  the  evolution  of 
S/370  mainframes  as  moving  toward 
the  role  of  a  gigantic  file  server.  The 
other  guy  is  the  CEO  of  my  present 
work  situation. 

A  recent  discussion  (warm,  not 
heated)  with  a  fellow  systems  grunt 
who  specializes  in  network  supports 
Jeffs  observation  that  the  mainframe 
“empire”  is  resisting  the  enhancement 
and  distribution  of  processing  that  mi¬ 
cros  bring  to  the  4  techno-brews  we 
build  and  support.  His  positions  are  1) 
most  databases  cannot  be  distributed, 
2)  the  lack  of  standardized  protocols 
and  network  architectures  eliminate 
most  advantages  of  micro  local  pro¬ 
cessing,  and  3)  ancient  business  prac¬ 
tices,  banking  for  example,  do  not  mesh 
well  with  modem  data  processing  tech¬ 
nologies.  Well,  some  of  that  is  true  yet 
anyone  who  has  jumped  into  micro 
coding  from  a  mainframe  environment 
knows  the  euphoria  of  megalomaniacal 
control,  has  been  amazed  by  the  low 
cost  of  quality  software  tools,  and  has 
embraced  the  heady  vision  of  a  com¬ 
puter-literate  society  where  program¬ 
ming  arts  will  be  as  second  nature  as 
reading  and  writing. 

IBM  and  compatible  vendors  con¬ 
tinue  to  eliminate  the  need  for  systems 
support  through  automated  operations, 
packaged  operating  system  installation/ 
maintenance,  4GL  database  administra¬ 
tion,  system  managed  storage,  and  of 
course  function  suction  into  microcode, 
as  Jeff  has  observed.  Systems  program¬ 
ming  at  the  operating  system  level  has 
been  reduced  to  configuration  man¬ 
agement  to  a  great  degree.  S/370  main¬ 
frames  are  becoming  turnkey  and  self¬ 
configuring,  a  welcomed  release  from 


drudgery  and  business  risk.  As  a  result, 
we  systems  programmers  who  were 
first  attracted  to  the  science,  art,  and 
technology  of  S/370  become  increas¬ 
ingly  bored  with  the  whole  mainframe 
world.  Some  organizations  have  tried 
to  cut  this  boredom  by  inventing  pro¬ 
jects  based  on  ALC  for  their  program¬ 
mers  to  play  with,  usually  having  artifi¬ 
cial  and  redundant  purposes.  What  a 
waste  of  talent. 

My  AT-class  system  is  booted,  the 
coffee  is  fresh,  Turbo  C  faithfully  awaits 
my  attention  as  the  word  processor 
gets  stroked.  It  is  Sunday  morning,  the 
sky  is  gray  with  rain,  my  desk  is  strewn 
with  reference  books  and  product  cata¬ 
logs.  An  application  that  has  never  ex¬ 
isted  before  occupies  my  background 
wetware  as  these  lines  are  written;  plans 
for  system  expansion  pop  up  like 
menus.  I  am  a  happy  programmer  do¬ 
ing  happy  things:  I  am  learning,  creat¬ 
ing,  imagining. 

Come  Monday  morning  I  will  return 
to  my  small,  crowded  office  and  turn 
my  concerns  to  DASD  management. 
There  will  be  performance  statistics  to 
analyze  and  a  time  sheet  to  keep  cur¬ 
rent.  A  product  analysis  report  will  be 
written,  a  meeting  attended.  Decisions 
will  be  made  slowly  and  safely,  actions 
will  be  delayed  to  an  ever-shrinking 
outage  window.  I  will  think  occasion¬ 
ally  about  the  20  MIPS  processor,  the 
four-volume  database,  the  worldwide 
network.  Problems  will  occur  and  so¬ 
lutions  will  be  defined.  I  will  cover  my 
behind  and  not  rock  the  boat  too  vio¬ 
lently  because  this  is  how  you  survive 
in  the  business  world. 

Meanwhile  there  is  a  whole  popula¬ 
tion  of  micro  programmers  out  there 
who  are  thinking  at  a  level  not  known 
in  the  mainframe  world  in  recent  years, 
whose  mainframe  concerns  amount  to 
a  hill  of  beans.  They  want  access  and 
nothing  more.  At  their  fingertips  are 
megabytes  of  main  storage,  gigabytes 
of  disk  storage,  CASE  tools,  multitasking, 
hundreds  of  colors,  thousands  of  bauds. 
Me,  I  will  hit  ENTER  at  my  graphics 
tube  and  wait  for  GDDM  to  get  a  few 
cycles.  I  will  print  a  document  and 
receive  it  an  hour  later.  I  will  scurry  to 
the  machine  room  to  check  a  main 
console;  scurry  to  a  meeting  and  strug¬ 
gle  to  stay  interested,  write  a  memo, 
update  a  time  sheet.  I  will  return  home 
to  boot  my  personal  system  and  again 
become  a  happy  programmer. 

Business  in  general  wants  the  turn¬ 
key  mainframe.  There  is  nothing  wrong 
with  this  other  than  it  puts  me  and 
many  other  systems  folks  out  on  the 
street  with  unmarketable  knowledge. 
Notice  I  did  not  write  “skills”  —  we  all 
have  tremendously  marketable  skills. 


S/370  knowledge  is  a  good  base  for 
OS/2;  assembler  knowledge  a  good 
base  for  micro  assembler;  SAS  and  other 
high-level  language  knowledge  a  good 
base  for  Pascal,  C,  and  others.  Our 
skills  are  inherent:  Love  of  science,  art, 
and  technology;  the  ability  to  make  a 
machine  do  what  we  want;  enough 
business  savvy  to  survive  these  many 
years  in  data  processing.  So  bring  on 
the  turnkey  mainframe;  bring  on  the 
local  area  network;  bring  on  distrib¬ 
uted  processing;  and  give  me  back  my 
machine!  Let  me  build  the  better  sys¬ 
tem,  create  the  never  before  seen  ap¬ 
plication,  make  this  puppy  run  like  it 
never  ran  before.  Get  me  out  of  the 
erector-set  mentality  of  canned  soft¬ 
ware,  black  box  hardware,  and  Big 
Blue  strategy. 

For  my  colleagues  who  find  all  this 
ranting  quite  unbecoming  of  a  profes¬ 
sional,  I  would  advise  opening  up  those 
purse  strings  and  getting  a  home  micro 
system.  Get  some  development  soft¬ 
ware,  build  a  reference/tutorial  library. 
Cook  up  some  application  interesting 
to  you  and  develop  it.  It  does  not  mat¬ 
ter  if  the  program  ever  sells.  It  matters 
that  it  is  your  program,  does  what  you 
want,  and  that  you  learn  the  amazing 
cost,  function,  and  performance  char¬ 
acteristics  of  the  micro  computer.  Then 
and  only  then  will  we  ever  have  mean¬ 
ingful  discussions  on  the  viability  of 
distributed,  local,  and  personal  com¬ 
puting. 

Two  really  smart  people  in  one  month 
comparing  mainframes  to  file  servers. 
Doesn’t  that  tell  you  something? 

Ray  A.  Kampa 

Chantilly,  Virginia 

Unix  Help  Wanted 

Dear  DDJ, 

I  would  like  to  describe  a  problem  I 
recently  encountered  with  the  Unix  sys¬ 
tem  Bourne  shell.  It  seems  that  there 
is  a  subtle  interaction  between  path 
searching,  file  permission  flags,  and 
file  hashing.  A  friend  asked  me  to  do  a 
regression  test  for  him  after  he  made 
some  last  minute  changes  to  his  pro¬ 
gram.  Using  FTP,  I  imported  a  copy  of 
the  last  minute  version.  (An  official  beta 
test  version  was  already  installed  on 
my  system.)  A  quick  test  showed  that 
no  errors  had  been  introduced  by  the 
changes.  In  fact,  I  could  detect  no  dif¬ 
ference  at  all  between  the  beta  and  last 
minute  versions.  I  reported  to  my  friend 
that  everything  looked  fine.  Hours  later, 
he  dropped  by  to  demonstrate  some 
exciting  feature.  Having  difficulty  find¬ 
ing  this  feature  in  my  copy  of  his  pro¬ 
gram,  he  concluded  that  I  had,  in  fact, 
been  testing  the  official  beta  version. 
What  had  happened? 
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(continued  from  page  12) 

My  friend  and  I  reasoned  that  two 
things  had  occurred.  First,  FTP  had 
stripped  the  execute  permission  from 
my  copy.  Second,  and  heretofore  un¬ 
known  to  me,  the  path  search  function 
only  finds  files  that  have  execute  per¬ 
mission  set.  It  encounters  the  named 
file  without  execute  permission,  it  con¬ 
tinues  its  hunt  for  an  executable  ver¬ 
sion.  (If  the  official  beta  test  version 
had  not  been  installed,  I  would  have 
received  the  error  message:  “name:  exe¬ 
cute  permission  denied.”) 

Being  resourceful,  my  friend  and  I 
proceeded  to  reset  the  execute  permis¬ 
sion  flag  using  the  chmod  command. 
And,  when  we  tried  to  execute  the 
program  again,  the  path  search  func¬ 
tion  still  yielded  the  official  beta  test 
version.  Now  what  had  happened? 

Hashing!  The  Bourne  shell  of  System 
V  has  a  thing  called  file  hashing  that 
speeds  up  path  searches.  The  shell  re¬ 
members  where  in  your  search  path  it 
was  that  invoked  commands  were  last 
found.  So  even  though  path  searching 
would  have  worked  properly  now,  it 
was  not  being  used.  1116  hash  memory 
can  be  erased  with  the  “hash  -  r”  com¬ 
mand. 

Now,  at  last,  my  copy  of  the  program 
was  being  tested.  Unfortunately,  it  was 
time  to  go  home,  and  the  actual  pro¬ 
gram  test  had  to  wait  until  the  next 
day.  (Yes!  Non-trivial  errors  were  dis¬ 
covered  and  I  had  to  retract  my  earlier 
thumbs  up.) 

Perhaps  the  Unix  developers  would 
consider  a  revision  to  the  System  V 
specification  and  redesign  the  path 
searching  algorithm.  Would  it  cause 
any  problem,  I  wonder,  if,  instead  of 
looking  for  EXECUTABLE  FILES,  the 
path  search  function  looks  for  ANY 
FILE  whose  name  is  identical  to  that 
entered  on  the  command  line.  This 
might  generate  more  error  messages, 
but  users  could  be  more  confident  that 
path  searching  has  resolved  to  the  ex¬ 
pected  version  of  a  file. 

Steve  Haffner 

Issaquah,  Washington 

Graphics  Programming  Fix 

Dear  DDJ, 

As  you  probably  have  been  made 
aware,  there  was  a  typo  in  one  of  the 
listings  for  Kent  Porter’s  “Graphics  Pro¬ 
gramming”  column  in  the  July  issue. 
The  typo  caused  a  program  to  loop  in 
a  recursive  call,  which  would  either 
cause  a  system  bang  or  exhausted  stack 
space. 

The  typo  was  in  the  program  RE¬ 
SIZE,  in  the  subroutine  drawstar.  In 
this  subroutine,  the  first  call  to  draw_rect 
should  have  its  dy  argument  be  (30) 


not  (-30).  This  causes  the  intended  rec¬ 
tangle  to  be  lower  than  the  arguments 
to  the  following  floodfill  anticipated. 
Instead  of  filling  an  object,  the  floodfill 
routine  tries  to  fill  the  viewport. 

This  first  error  revealed  two  other 
errors  in  earlier  listings  that  had  not 
been  noticed  because  filling  a  view¬ 
port  had  never  been  tested. 

The  first  is  in  the  EGAPIXEL  routine. 
It  checks  incorrectly  if  a  pixel  is  within 
the  vuport.  It  checks  if  the  pixel  is 
“greater  than  or  equal”  to  the  vuport 
instead  of  just  “greater  than”.  If  a  pixel 
is  in  the  vuport,  it  can  be  equal  to  the 
limit.  This  caused  the  floodfill  to  reject 
the  last  fill  line  as  outside  the  vuport 
and  make  a  recursive  call  in  the  reverse 
direction,  starting  an  endless  loop. 

The  EGAPIXEL  routine  does  not 
check  if  the  pixel  is  less  than  the  vuport. 
This  is  why  the  endless  loop  doesn’t 
happen  until  the  fill  hits  the  bottom. 
Depending  on  someone’s  needs,  the 
test  can  be  either  fixed  for  both  cases 
or  dropped  completely. 

The  second  error  is  in  FLOODFILL. 
The  variable  dir  is  not  needed  at  all.  It 
can  be  fixed  as  -1  in  the  first  loop  and 
+1  in  the  second.  The  third  loop  can 
be  dropped  completely.  With  these 
changes,  there  is  no  need  to  add  a 
check  in  floodfill  for  the  error  return 
condition  from  EGAPIXEL.  Also  this 
change  speeds  up  the  fill  routine  by 
about  20  percent. 

John  Horvath 

Acton,  Massachusetts 

Subscrib-er  to  Subscrib-ee 

Dear  DDJ , 

I  have  been  a  fan  of  Jeff  Duntemann 
since  the  late  Borland  Turbo  Technix. 
His  October  column  comparing  OOP 
word  definitions  in  various  languages 
was  a  beauty.  However,  I  would  like 
to  play  turnabout. 

In  defining  binding  he  uses  the  terms 
caller  and  call-ee.  I  quibble  with  call-ee. 

There  is  a  parent-child  sequence  that 
goes  something  like  telegraphy,  tele¬ 
phony,  radio,  electronics,  computers. 
We  have  inherited  much  terminology 
from  our  ancestor  technologies.  Since 
time  immemorial  (or  at  least,  since  the 
beginnings  of  telephone  and  telegraph 
switchboards)  the  terms  caller  and  called 
have  been  used.  These  are  pronounced 
call-lerr  and  call-ledd.  Each  word  has 
two  equally  stressed  syllables. 

John  P.  Reid 

Bear,  Delaware 
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Network  Graphs  in 

Object  Pascal 


Linked  Lists  as  reusable  objects 


Steven  Kienle 


The  origins  of  OOP  and  the  emer¬ 
gence  of  OOP  features  in  a  num¬ 
ber  of  programming  languages 
are  well  known.  The  propo¬ 
nents  of  Ada  and  Modula-2 
claim  that  OOP  is  part  of  the  design  of 
these  languages.  C,  the  language  of  the 
systems  developer,  has  also  been  caught 
up  in  the  OOP  wave,  spawning  C++ 
and  Objective  C.  Most  recently,  the  Ap¬ 
ple-developed  OOP  dialect  of  Pascal 
has  gained  momentum  now  that  Mi¬ 
crosoft  and  Borland  have  both  added 
support  of  objects  into  their  respective 
Pascal  offerings. 

In  this  article,  I  will  discuss  how 
Object  Pascal  implements  objects  and 
methods,  and  I’ll  describe  a  program 
that  creates  a  network  graph.  I’ll  also 
look  back  at  the  objects  that  were  cre¬ 
ated  in  this  program  and  give  examples 
of  how  they  can  be  reused  in  other 
programs.  This  article  assumes  that  you 
are  familiar  with  OOP  in  general,  and 
that  you  have  a  knowledge  of  standard 
Macintosh  data  types  and  toolbox  calls 
such  as  Point,  Kect,  LineTo,  and  Fra- 
meRect. 

The  Network  Graph  Program 

The  network  graph  program  creates 


Steve  has  been  a  professional  program¬ 
mer  since  1983  and  has  written  sev¬ 
eral  programs  that  are  available  on  the 
CompuServe  Macintosh  forums,  includ¬ 
ing  the  Turing  Machine  Editor  and 
Face  Manager  programs.  He  can  be 
reached  at  2314  Waverly,  Kalamazoo, 
MI  49007  or  through  CompuServe  at 
72330,111. 


and  manipulates  a  simple  network 
graph.  This  program  allows  the  user 
to  create  and  remove  vertices  and  edges, 
and  to  move  vertices  around.  The  graph 
is  created  in  a  window  that  allows  scroll¬ 
ing  in  two  directions,  up  to  the  current 
size  of  the  page.  The  graph  is  created 
by  using  tools  available  in  a  pallet  win¬ 
dow.  For  simplicity,  the  program  doesn’t 
support  such  features  as  saving  the 
graph  to  disk,  and  it  doesn’t  support 
the  Edit  menu  items. 

The  code  for  the  section  of  the  pro¬ 
gram  that  handles  object  types  and 
method  definitions  is  provided  in  List¬ 
ing  One  (see  page  104).  The  execut¬ 
able  program,  complete  code,  and  associ¬ 
ated  MPW  (Macintosh  Programming 


Workbench)  support  files  are  available 
through  DDJ  or  from  the  author.  (See 
the  author  biography  for  more  infor¬ 
mation  —  Ed.) 

OOP  is  really  programming  from  the 
data  up,  rather  than  from  the  functions 
down.  OOP  strives  to  encapsulate  the 
data  of  the  problem  and  to  define  meth¬ 
ods  for  manipulating  that  data.  In  the 
case  of  the  network  graph  program, 
the  first  step  in  using  OOP  is  to  define 
the  data  object  that  you  wish  to  create, 
which  is  a  network  graph.  The  mathe¬ 
matical  definition  for  a  graph  is  “an 
object  created  by  two  sets.  The  first  set 
consists  of  vertices,  and  the  second  set 
contains  edges.”  From  this  definition, 
we  quickly  derive  three  different  ob¬ 
jects:  the  graph,  the  vertices,  and  the 
edges. 

Digging  a  bit  deeper  into  the  defini¬ 
tion  reveals  that  the  vertices  and  edges 
are  collected  into  sets.  Pascal  does  not 
allow  the  use  of  nonscalars  in  sets.  As 
a  result,  I  used  a  linked  list  to  imple¬ 
ment  a  set,  and  added  two  more  ob¬ 
jects,  Graphlist  and  GraphNode,  to  sup¬ 
port  the  linked  list. 

GraphNode  is  a  fairly  simple  object  — 
it  only  has  a  Next  link.  GraphNodP s 
methods  include  Draw,  DrawAll,  Erase, 
EraseAll,  Free,  and  FreeAll.  Free,  which 
is  similar  to  the  example  presented  in 
the  sidebar,  erases  the  node  and  then 
frees  it  from  memory.  Draw  and  Erase 
are  null  and  serve  as  place  holders  for 
the  methods  in  the  descendant  objects. 

DrawAll,  EraseAll,  and  FreeAll  de¬ 
serve  a  bit  more  attention.  They  use  the 
Next  link  to  pass  a  message  to  the  next 
GraphNode  in  the  list,  and  then  call  the 
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appropriate  method.  These  methods 
use  inherited  code  and  allow  only  one 
method  call  to  cause  a  complete  re¬ 
draw,  erasure,  or  freeing  of  a  GraphList. 
Note  that  because  the  Next  instance  vari¬ 
able  is  a  GraphNode,  you  can  use  Next 
in  a  reference  to  another  method  call. 


This  approach  is  shown  in  the  SELF.Next 
.EraseAll  type  statements,  which  read 
as:  “Look  at  myself,  get  the  Next  in¬ 
stance  variable’s  value,  and  send  that 
object  instance  the  EraseAll  message.” 

GraphList  holds  the  head  pointer  of 
the  GraphNode  link  list.  This  object 


handles  the  special  case  of  removing  a 
GraphNode  from  the  list,  and  also  dem¬ 
onstrates  code  reusability.  Because  we 
need  a  list  of  Vertices  and  Edges,  the 
creation  of  a  GraphList  object  class  cre¬ 
ates  one  common  location  for  the  list- 
manipulation  routines.  The  GraphList 


In  order  to  add  OOP  to  Pascal,  Apple 
modified  Pascal  to  create  Object  Pas¬ 
cal  (or  Clascal  —  Class  Pascal  —  as  it 
was  first  called).  These  changes  were 
made  on  the  Pascal  that  was  designed 
for  the  graphical-interface-based  com¬ 
puter  Apple  was  developing  at  the 
time:  The  Lisa.  Even  though  the  Lisa 
no  longer  exists,  Object  Pascal  con¬ 
tinues  to  gain  momentum. 

The  major  change  to  Pascal  in  Ob¬ 
ject  Pascal  is  the  addition  of  the  Ob- 
ject type.  In  Object  Pascal,  the  classes 
of  OOP  are  defined  in  the  Type  decla¬ 
ration  section  as  belonging  to  the  Ob¬ 
ject  type.  The  format  for  the  Object 
statement  is  similar  to  the  format  for 
the  Record  statement,  but  the  declara¬ 
tion  of  the  Object  statement  contains 
two  additional  parts:  the  Base  Object 
and  the  Method  declarations.  The  for¬ 
mat  is  shown  in  the  railroad  diagram 
in  Figure  1 . 

The  Base  Object  enables  the  use 
of  class  inheritance  in  Object  Pascal. 
To  make  a  new  object  type  a  descen¬ 
dant  of  another  object  type,  place  the 
parent’s  object  type  name  into  the 
parentheses. 

The  method  declarations  in  Object 
Pascal  are  similar  to  the  forward  pro¬ 
cedure  and  function  declarations  in 
Pascal.  List  the  procedure  or  function 
declarations  in  the  block,  which  is 
where  new  methods  on  this  object 
must  be  declared.  Optionally,  an  Over¬ 
ride  statement  may  follow  a  method 
declaration  in  order  to  replace  an  in¬ 
herited  method. 

Most  implementations  of  Object  Pas¬ 
cal  include  a  base  object  type  that 
provides  some  simple  methods.  For 
example,  my  Pascal  compiler  calls  its 
base  object  TObject.  TObject  provides 
base  methods  for  Clone  and  Free. 
Clone  makes  a  copy  of  an  object  in¬ 
stance,  and  Free  frees  an  object  in¬ 
stance  from  memory. 

The  code  for  each  Object’s  meth¬ 
ods  must  be  included  somewhere  in 
the  code  section  of  the  program.  This 
is  handled  in  a  similar  fashion  to  other 
procedure  and  function  definitions, 
except  that  the  procedure  or  function 
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name  is  prefixed  with  the  Object  Type 
name.  Whenever  instance  variables 
are  used  in  method  definitions,  the 
variables  are  prefixed  with  the  spe¬ 
cial  SELF  reference.  This  prefix  tells 
the  compiler  to  use  the  values  for 
those  variables  in  the  object  instance 
that  called  this  method.  Listing  Two 
(page  108)  provides  a  sample  Circle 
class’s  type  declaration  and  procedure 
definitions.  Note  that  Circle  inherits 
Clone  and  Free  from  TObject. 

You  declare  a  variable  that  is  to  be 
used  as  an  instance  of  the  Object  type 
in  the  same  way  that  you  declare  a 
Record  variable.  The  catch  is  that  un¬ 
til  a  new  instance  is  created,  that  vari¬ 
able  doesn’t  reference  a  valid  object 
instance.  The  standard  Pascal  NEW() 
procedure  is  used  for  creating  an  ob¬ 
ject  instance.  Once  an  object  instance 
is  created,  the  instance  variables  are 
referenced  in  the  same  way  that  Rec¬ 
ord  variables  are  referenced.  To  call 
an  object’s  method,  prefix  the  method 
name  with  the  instance  variable.  An 
example  of  declaring  and  using  a  Cir¬ 
cle  object  instance  is  shown  in  Listing 
Three,  page  108. 

As  the  example  program  stands 
now,  the  circle  will  be  drawn  in  a 
window  even  after  the  instance  is 
freed.  If  this  result  is  not  desired  two 


Figure  1:  Railroad  diagram  showing 
the  format for  the  Object  statement 


options  are  available:  Add  a  call  to 
Circle.Erase  before  the  call  to  Cir- 
cle.Free,  or  override  the  Free  inher¬ 
ited  from  the  TObject  class.  To  imple¬ 
ment  the  second  choice,  use  the  Over¬ 
ride  statement  in  the  method  dec¬ 
laration  section  of  the  Circle  Object 
Typte  definition. 

Override  provides  a  way  to  change 
an  inherited  method.  Object  Pascal 
also  allows  the  new  method  to  call 
the  inherited  method  through  the  in¬ 
herited  statement.  The  use  of  the  In¬ 
herited  statement  allows  small  changes 
to  be  made  to  a  method,  while  leav¬ 
ing  the  inherited  code  available  and 
contained  in  the  parent  object.  Listing 
Four,  page  108,  adds  a  Free  method 
to  the  Circle  Object  Type  and  shows 
how  to  use  the  Override  and  Inher¬ 
ited  statements.  Note  the  use  of  the 
SELF  reference  here  to  call  another 
method  for  the  same  object  instance. 
These  changes  cause  the  example  pro¬ 
gram  to  erase  the  circle  when  the 
instance  is  freed. 

Through  the  use  of  inheritance  and 
overriding,  several  related  object  types 
can  have  the  same  procedure  name, 
such  as  Draw ,  and  implement  the 
procedure  differently.  This  factor  alone 
is  a  benefit,  but  it’s  not  the  only 
strength  of  Object  Pascal.  Object  Pas¬ 
cal  also  links  each  object  instance  to 
the  object  type  methods  so  that  it’s 
possible  to  create  methods  in  the  an¬ 
cestor  of  several  types  that  can  be 
implemented  without  making  changes 
in  the  children.  Listing  Five  (see  page 
108)  shows  an  example  of  this. 

You  may  already  be  noticing  that 
Object  Pascal  does  not  support  data 
hiding.  This  failure  follows  from  the 
way  that  Pascal  itself  was  designed. 
While  the  newer  versions  of  Pascal 
provide  some  indirect  data  hiding 
through  the  use  of  Units,  the  instance 
variables  are  still  available  to  the  call¬ 
ing  program.  While  I  admit  the  im¬ 
portance  of  data  hiding,  I  don’t  feel 
an  impact  from  its  loss  in  Object  Pas¬ 
cal.  A  lot  of  the  benefits  of  data  hiding 
can  be  realized  through  careful  pro¬ 
gramming  practices.  —  S.K. 
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(continued  from  page  18) 
object  only  contains  a  FirstNode  in¬ 
stance  variable.  The  methods  include 
AddNode,  RemoveNode,  Draw ,  Erase, 
and  Free. 

Draw  and  Erase  make  the  process 
of  redrawing  a  complete  graph  easier. 
These  methods  call  DrawAll  and 
EraseAll  for  FirstNode.  Free  also  calls 
FreeAll  for  FirstNode ,  but  then  calls  the 
inherited  Free  method  in  order  to  de¬ 
stroy  the  list  object  instance.  AddNode 
and  RemoveNode  perform  the  manipu¬ 
lations  on  the  list.  AddNode  takes  as 
an  argument  a  GraphNode  object  in¬ 
stance  and  makes  this  object  the  new 
FirstNode.  RemoveNode  also  takes  a 
GraphNode  object  instance  as  an  argu¬ 
ment.  RemoveNode  finds  and  removes 
the  appropriate  GraphNode  from  the 
list. 

Note  that  the  Vertex  object  type, 
which  is  maintained  in  a  list,  is  based 
upon  the  GraphNode  object  type.  There¬ 
fore,  Vertex  inherits  the  Next  instance 
variable  and  the  Draw ,  DrawAll ,  Erase, 
EraseAll,  Free,  and  FreeAll  methods. 
Draw  and  Erase  must  then  be  overrid¬ 
den.  Examine  these  overridden  meth¬ 
ods  and  note  that  information  about 
where  the  Vertex  is  centered  and  how 
large  the  Vertex  should  be  made  is 
required.  For  the  network  graph  pro¬ 


gram,  the  Vertex  is  a  circle  with  a  radius 
of  10.  This  creates  one  new  instance 
variable  called  Center.  Draw  and  Erase 

Pascal  does  not  allow 
the  use  of  nonscalars 
in  sets.  Therefore,  I  used 
a  linked  list  to 
implement  a  set,  and 
added  two  more  objects, 
GraphList  and 
GraphNode,  to  support 
the  linked  list 


now  create  or  erase  the  10-point  radius 
circle  around  Center.  You  could  set  the 
Center  instance  variable  by  accessing 
the  instance  variable  itself.  But  in  order 


to  support  the  OOP  methodology  as 
best  as  possible,  I’ve  added  a  SetCenter 
method. 

Edge  is  directly  related  to  the  Vertex 
object  type.  Edge  connects  two  Ver¬ 
tices.  As  a  result,  I’ve  added  two  new 
instance  variables,  FromVertex  and 
ToVertex.  As  with  Vertex,  Edge  is  main¬ 
tained  in  a  list  and  GraphNode  is  the 
base  object.  Again,  Draw  and  Erase 
have  been  overridden.  Draw  draws  a 
line  from  the  center  of  From  Vertex  to 
the  center  of  ToVertex.  To  keep  the 
Vertex  objects  looking  clean,  I  modi¬ 
fied  the  Vertex  Draw  method  to  erase 
the  circle  and  then  frame  it;  the  edges 
now  start  and  end  at  the  edge  of  the 
vertex  frame.  Erase  sets  the  drawing 
pattern  to  white,  and  then  calls  Draw. 
This  approach  allows  Draw  to  be  modi¬ 
fied  in  descendant  objects,  while  Erase 
continues  to  work  unchanged. 

Edge  also  uses  the  SetFrom  and  SetTo 
methods  to  erase  the  old  Edge,  and  to 
redraw  the  FromVertex  or  ToVertex  to 
which  it  is  attached.  Edge  is  dependent 
upon  two  Vertex  instances,  so  if  either 
of  those  instances  move,  Edge  must  be 
redrawn.  An  apparently  simple  solu¬ 
tion  would  be  to  modify  the  Vertex 
SetCenter  method.  But  Vertex  has  no 
knowledge  of  which  Edge  instances 
are  connected  to  it,  so  trying  to  locate, 


erase,  and  redraw  those  Edge  instances 
would  force  external  knowledge  into 
the  object.  Therefore,  the  Graph  ob¬ 
ject,  which  has  knowledge  of  Edges 
and  Vertices,  handles  this  problem. 

The  Graph  object  is  based  upon  TOb- 
ject.  Graph  consists  of  two  sets,  so  it 
needs  instance  variables  that  point  to 
its  list  of  vertices  and  edges.  We  can 
start  the  method  list  with  some  obvious 
methods:  Draw,  Erase,  Free  (which  is 
overridden),  AddVertex,  RemoveVertex, 
AddEdge,  and  RemoveEdge.  Draw  and 
Erase  call  the  EdgeList  and  VertexList 
instances  of  both  the  GraphList  object 
and  the  Draw  and  Erase  messages.  The 
order  is  important  here,  because  I  have 
designed  the  Draw  methods  for  the 
Edges  instances  to  be  drawn  first.  Simi¬ 
larly,  Free  frees  the  EdgeList  and  then 
the  VertexList. 

With  each  event,  the  Macintosh  pro¬ 
vides  the  location  at  which  the  event 
occurred.  This  means  that  in  the  case 
of  the  AddVertex,  AddEdge,  Remove- 
Edge,  and  RemoveVertex,  only  the  lo¬ 
cation  of  the  mouse  is  available.  Thus, 
these  methods  take  a  point  as  their 
argument.  AddVertex  adds  a  vertex  at 
the  specified  location. 

Note  that  because  the  AddNode 
method  of  the  GraphList  object  takes 


a  GraphNode  as  an  argument,  the  Ver¬ 
tex  object  instance  cannot  be  used  di¬ 
rectly  in  the  call.  This  is  a  result  of  the 
strict  type  constraints  of  Pascal,  rather 
than  a  result  of  how  Object  Pascal  is 
implemented.  This  limitation  can  be 
overcome  by  typecasting  the  object  in¬ 
stance.  This  concept,  which  is  borrowed 
from  C,  allows  the  compiler  to  accept 
the  technique  of  sending  a  Vertex  ob¬ 
ject  instance  to  AddNode.  This  trick  is 
required  because  I  defined  a  common 
GraphList  object,  rather  than  defining 
VertexList  and  EdgeList,  which  would 
be  identical  except  for  what  they  are 
linking.  The  trick  is  required  for  the 
compiler  only;  the  object  instance  is 
not  modified  in  any  way. 

AddEdge  is  very  similar  to  AddVertex. 
Instead  of  taking  a  location,  AddEdge 
takes  two  Vertex  object  instances  and 
creates  an  Edge  instance  that  links  them 
together. 

RemoveEdge  removes  an  Edge  object 
instance.  This  means  that  we  need  a 
way  to  determine  the  Edge  instance  at 
a  given  point.  Look  ahead  a  bit  and 
note  that  RemoveVertex  also  needs  to 
locate  an  object  instance  based  upon 
a  location.  To  do  this,  we  add  Ptln- 
Node  and  FindNode  to  the  GraphNode 
object  type  and  add  FindNode  to  the 
GraphList  object  type.  The  methods  be¬ 


long  here  because  both  descendant  ob¬ 
ject  types  require  it.  PtlnNode  returns 
True  if  the  point  is  considered  to  be  in 
the  object  instance,  and  returns  False 
otherwise.  GraphNode.  FindNode  checks 
if  the  point  is  in  the  present  object 
instance.  If  the  point  is  in  the  present 
object  instance,  GraphNode. FindNode 
returns  itself;  otherwise,  the  checking 
down  the  list.  The  GraphList. FindNode 
method  initiates  the  search  at  the 
FirstNode  of  the  list  and  returns  the 
result. 

In  order  to  support  PtlnNode,  we 
need  to  define  the  region  covered  by 
the  object  instance.  I  use  the  term  “re¬ 
gion”  on  purpose,  because  the  Mac 
Toolbox  has  a  routine,  PtlnRgn,  that 
does  the  processing  for  us.  To  create 
this  region,  I  added  a  new  instance 
variable  to  the  GraphNode  object  type, 
called  HotRegion.  The  SetRegion  method 
creates  the  appropriate  region.  In  the 
case  of  the  Vertex  object,  this  region  is 
the  circle  that  the  Vertex  creates  on  the 
screen.  In  the  case  of  the  Edge  object, 
a  region  is  created  that  follows  the  line 
but  is  eight  pixels  wide. 

The  addition  of  HotRegion,  which  is 
location  dependent,  forces  a  change 
in  some  of  the  other  methods.  As  the 
center  of  a  Vertex  instance  or  an  end 
point  of  an  Edge  instance  is  set,  the 
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(continued  from  page  22) 

HotRegion  must  be  recreated.  I  modi¬ 
fied  SetCenter,  SetFrom,  and  SetTo  to 
reflect  this  requirement.  Note  that  the 
Free  method  of  GraphNode  frees  the 
region. 

After  the  support  methods  are  added 
to  GraphNode ,  Vertex ,  and  Edge ,  we 
can  return  to  RemoveEdge.  This  method 
first  finds  the  Edge  instance  in  which 
the  point  is  located  and  removes  that 
Edge  from  EdgeList. 

The  Remove  Vertex  method  is  similar 
to  RemoveEdge,  but  requires  some  ad¬ 
ditional  support  in  the  GraphNode  and 
Edge  object  types.  RemoveVertex  first 
finds  the  Vertex  instance  in  which  the 
point  is  located.  The  method  then  re¬ 
moves  all  Edge  instances  that  are  con¬ 
nected  to  that  Vertex  instance. 

Finding  all  such  instances  can  be  done 
in  this  method  or  through  a  method 
on  the  Edge  object.  Because  the  list 
traversal  logic  has  been  isolated  in  the 
GraphNode  object,  I  chose  to  add  the 
finding  logic  into  the  GraphNode  ob¬ 
ject  but  leave  the  instance  removal  in 
RemoveVertex.  This  approach  involves 
the  creation  of  Connected  and  FindCon- 
nected  methods  in  the  GraphNode  ob¬ 
ject  type.  The  FindConnected  method 
also  must  be  included  in  the  GraphList 
object  type.  In  GraphNode,  Connected 
always  returns  False;  but  the  Edge  ob¬ 
ject  overrides  this  and  returns  True  if 
Edge  is  connected  to  the  Vertex  in¬ 
stance.  FindConnected  finds  the  first 
connected  instance  in  the  list. 

These  routines  enable  you  to  find 
and  remove  the  Edge  instances  con¬ 
nected  to  a  given  Vertex  instance.  Once 
all  the  appropriate  Edge  instances  are 
removed,  the  Vertex  object  instance  it¬ 
self  can  be  removed. 

At  this  point,  the  special  processing 
required  for  SetCenter  can  also  be  im¬ 
plemented.  To  do  this,  a  SetVertexCen- 
ter  method  was  added  to  the  Graph 
object  type.  The  purpose  of  the  addi¬ 
tional  processing  beyond  the  Vertex. 
SetCenter  call  is  to  find  all  of  the  con¬ 
nected  edges,  and  to  both  erase  these 
edges  before  and  then  redraw  them 
after  the  SetCenter  call.  FindConnected 
allows  you  to  move  through  EdgeList 
and  find  all  of  the  connected  Edge  in¬ 
stances.  The  complexity  of  adding  the 
special  processing  to  the  Graph  object 
type,  rather  than  to  the  Vertex  type, 
makes  the  program  much  cleaner  and 
more  self  contained. 

Two  methods  have  been  added  to 
make  the  program  conform  more  closely 
to  the  Macintosh  interface  guidelines. 
These  methods  allow  a  Vertex  instance 
to  be  moved  with  the  mouse  and  allow 
an  Edge  instance  to  be  added  with  the 
mouse. 
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The  step  of  implementing  MoveVertex 
in  the  Graph  object  is  fairly  easy.  Given 
a  point  from  which  the  move  is  start¬ 
ing,  find  the  Vertex  at  the  point.  Use 
the  Macintosh  Toolbox  routine  Drag- 
GrayRgn  to  let  the  user  pull  the  Hot- 
Region  around  the  screen.  I  have  sepa¬ 
rated  the  Mac-specific  code  into  the 
DragRegion  function,  which  is  not  in¬ 
cluded  in  the  listings  with  this  article 
(but  is  available  online.  If  the  drag  is 
completed  with  a  move,  the  new  cen¬ 
ter  of  the  Vertex  instance  is  determined, 
and  the  Graph. SetVertexCenter method 
is  called  to  move  the  Vertex  instance 
to  the  new  location. 

The  code  for  LinkVertices  is  also 
straightforward.  First,  check  the  loca¬ 
tion  to  see  if  it  contains  a  Vertex  in¬ 
stance,  and  then  call  a  DragGrayLine 
procedure  to  find  where  the  mouse  is 
released.  If  the  mouse  is  released  in  a 
Vertex  instance  that  is  different  from 
the  first  Vertex  instance,  then  the 
Graph  .Add-Edge  routine  is  called  to 
add  the  new  Edge  instance.  DragGray¬ 
Line  follows  the  mouse  around  the  win¬ 
dow,  trailing  a  gray  line  between  the 
current  location  and  the  starting  loca¬ 
tion  until  the  mouse  button  is  released. 
DragGrayLine  then  returns  the  loca¬ 
tion  of  the  mouse. 

Reusable  Objects 

GraphNode  implements  a  linked  list 
with  some  graphing  methods  associ¬ 
ated  with  it.  GraphList  maintains  a  list 
of  GraphNode  instances.  The  Vertex 
and  Edge  object  types  are  based  upon 
the  GraphNode  type,  and  implement 
the  vertices  and  edges  of  the  network 
graph.  The  Graph  object  is  the  actual 
network  graph  and  provides  methods 
to  support  and  modify  the  graph  in¬ 
stance. 

As  written,  the  Graph  object  is  some¬ 
what  restrictive.  At  the  least,  it  allows 
several  instances  of  network  graphs  to 
be  handled  by  the  same  program.  Graph 
can  also  be  used  at  the  base  for  addi¬ 
tional  types  of  graphs,  such  as  directed 
graphs,  weighted  graphs,  and  so  on. 

One  type  of  network  graph  that  1 
want  to  mention  is  the  Cartesian  graph, 
which  is  what  most  people  think  about 
when  you  say  “graph."  By  placing  ver¬ 
tices  carefully,  and  adding  edges  that 
connect  one  vertex  to  the  next  one 
down  the  X  axis,  we  can  create  a  pro¬ 
gram  that  graphs  a  set  of  data  points 
fairly  quickly.  By  using  several  Graph- 
based  objects,  several  sets  of  data  can 
be  plotted  in  the  same  window.  At  the 
same  time  a  separation  of  the  sets  can 
be  maintained,  which  is  useful  when 
data  sets  are  edited  independently. 

Additional  methods  can  be  added 
to  the  Graph-based  object  to  provide 


for  greater  functionality.  A  method  of 
traversing  the  graph,  based  upon  some 
algorithm,  is  an  example  of  this  ap¬ 
proach.  In  fact,  I’ve  written  a  Turing 
Machine  Editor  that  is  based  upon  these 
objects. 

Note  that  objects  such  as  the  Vertex 
object  type  can  be  used  in  several  ways. 
Many  of  these  uses  are  listed  indirectly 
earlier  this  article  during  the  discussion 
of  the  Graph  object  type.  Vertex  can 
also  be  used  as  a  base  object  type. 
Naturally,  you  can  change  the  way  in 
which  the  object  is  drawn.  This  change 
can  give  rise  to  different  ways  of  show¬ 
ing  each  vertex  in  the  window.  The 
drawing  method  can  even  be  selected 
by  an  instance  variable  in  order  to  al¬ 
low  a  graph  to  contain  several  different 
types  of  vertices.  If  you  create  a  Vertex- 
based  class  that  doesn’t  draw  at  all,  then 
you  have  a  way  to  generate  line  art. 
Note  that  many  of  these  uses  for  Vertex 
type  objects  can  be  implemented  within 
or  without  the  Graph  object  itself. 

Edge  is  intimately  tied  to  the  Vertex 
class,  so  Edge  can  only  be  used  in 
conjunction  with  that  type.  Still,  vari¬ 
ations  on  this  class  can  be  useful  in 
themselves.  Such  variations  could  in¬ 
clude  different  ways  of  drawing  the 
edge,  such  as  drawing  the  edge  as  an 
arc  or  a  gray  bar. 

Finally,  the  GraphList  and  GraphNode 
classes  actually  implement  a  list  struc¬ 
ture  for  objects  that  are  drawn,  con¬ 
nected,  and  selected,  so  these  classes 
provide  many  opportunities  for  reuse. 
Any  program  that  creates  or  manipu¬ 
lates  lists  of  graphical  objects,  such  as 
an  object-oriented  drawing  program, 
is  a  candidate  for  use  of  the  GraphList 
and  GraphNode  object  types. 

Availability 

All  source  code  is  available  on  a  single 
disk  and  online.  To  order  the  disk, 
send  $14.95  (Calif,  residents  add  sales 
tax)  to  Dr.  Dobb’s Journal,  501  Galves¬ 
ton  Dr.,  Redwood  City,  CA  94063,  or 
call  800-356-2002  (from  inside  Calif.) 
or  800-533-4372  (from  outside  Calif.). 
Please  specify  the  issue  number  and 
format  (MS-DOS,  Macintosh,  Kaypro). 
Source  code  is  also  available  online 
through  the  DDJ  Forum  on  Compu¬ 
Serve  (type  GO  DDJ).  The  DDJ  Listing 
Service  (603-882-1599)  supports  300/ 
1200/2400  baud,  8-data  bits,  no  parity, 
1-stop  bit.  Press  SPACEBAR  when  the 
system  answers,  type:  listings  (lower¬ 
case)  at  the  log-in  prompt. 

DDJ 

(Listings  begin  on  page  104.) 

Vote  for  your  favorite  feature/article. 

Circle  Reader  Service  No.  1. 
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Writing  Filters 

In  an  Object-Oriented  Language 


Object-oriented  programming  with  Actor  makes  writing 
filter-type  programs  easy 


Marty  Franz 


A  filter  is  a  program  that  copies 
one  file  into  another  file  while 
processing  it  in  some  way.  Fil¬ 
ters  are  a  common  type  of  pro¬ 
gram.  For  example,  you  can 
think  of  a  C  language  compiler  as  a 
filter,  because  it  reads  an  input  file  (in 
this  case,  a  C  source  program),  pro¬ 
cesses  it  (translates  it),  and  creates  an 
output  file  (the  object  program).  A  list¬ 
ing  generator  is  another  example  of  a 
filter:  It  reads  an  input  file,  processes  it 
by  paginating  it,  and  outputs  it  to  a 
printer.  Because  filters  are  a  common 
type  of  program,  they  have  a  common 
structure.  This  article  discusses  how 
the  facilities  in  an  object-oriented  lan¬ 
guage,  such  as  Actor,  makes  writing 
filter  programs  easy,  using  several  com¬ 
mon  classes  and  methods. 

Object-Oriented  Programming 

Object-oriented  programming  (OOP) 
treats  a  program  as  a  set  of  objects, 
with  the  code  and  data  that  are  needed 
to  make  an  object  exhibit  appropriate 


Marty  Franz  is  a  software  specialist  for 
Allen  Testproducts  in  Kalamazoo  Michi¬ 
gan.  He  also  is  a  free-lance  author 
whose  articles  have  appeared  in  nu¬ 
merous  computer  magazines.  Marty  is 
the  author  o/’Object-Oriented  Program¬ 
ming  featuring  Actor  published  by  Scott 
Foresman  &  Co.,  from  which  this  arti¬ 
cle  is  excerpted. 


behavior  fused  together  in  the  program. 
By  dividing  a  program  into  objects  that 
embody  both  data  and  operations,  the 
structure  of  the  program  more  closely 
represents  the  structure  of  the  problem 
being  solved.  As  a  result,  object-ori¬ 
ented  programs  are  more  easily  writ¬ 
ten,  read,  and  maintained  than  pro¬ 
grams  in  a  procedural  language. 

The  creation  of  abstract  data  types 
is  an  important  task  in  object-oriented 
programming.  This  means  the  actual 
implementation  of  an  object  is  encap¬ 


sulated  by  high-level  operations.  Ob¬ 
jects  therefore  have  a  clear  separation 
into  a  public  and  private  protocol.  For 
example,  a  queue  object  that  defines  a 
public  protocol  based  on  the  opera¬ 
tions  of  adding  data  to  or  removing 
data  from  the  queue.  The  queue  may 
be  written  as  an  array  with  separate 
variables  (called  “instance”  variables) 
that  maintain  the  first  and  last  positions 
in  the  queue,  but  how  this  is  done  is 
private  to  the  queue  object.  By  adher¬ 
ing  to  the  public  protocol  elsewhere 
in  the  program,  you  could  later  change 
the  implementation  of  the  queue  (to  a 
threaded  list,  for  example)  and  not 
change  the  rest  of  the  program  that 
used  the  queue. 

Programming  in  an  object-oriented 
language  involves  creating  objects  and 
then  sending  them  messages  to  do 
things.  Messages  in  Actor  resemble  func¬ 
tion  calls  in  other  programming  lan¬ 
guages,  but  they  are  not.  The  first  pa¬ 
rameter  in  the  message  is  actually  the 
receiver  object  of  the  message.  The 
receiver  object  determines  how  to  re¬ 
spond  to  the  message.  Different  ob¬ 
jects  can  respond  in  different  ways  to 
the  same  message  name,  a  property 
called  “polymorphism.”  Polymorphism 
allows  many  objects  within  a  program 
to  respond  to  the  same  common  proto¬ 
col,  which  makes  the  program  easier 
to  understand.  It  also  allows  you  to 
write  more  general,  reusable  code,  be- 
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(continued  from  page  28) 
cause  you  don’t  have  to  worry  about 
the  types  of  objects  you’re  dealing  with 
as  long  as  they  follow  the  same  public 
protocol. 

Within  an  object,  methods  are  de¬ 
fined  that  determine  how  the  object 
will  respond  to  a  given  message.  Meth¬ 
ods  in  Actor  resemble  functions  or  pro¬ 
cedures  in  C  or  Pascal:  They  have  local 
variables  and  use  control  structures  such 
as  do- while  and  if-then-else.  Blocks  can 
be  defined  along  with  methods.  You 
can  think  of  these  as  methods  without 
names  that  can  be  treated  as  separate 
objects  and  passed  to  objects  as  parts 
of  messages. 

In  most  object-oriented  languages, 
objects  are  organized  hierarchically  into 
classes.  Classes  descend  from  one  an¬ 
other  in  a  kind  of  family  tree,  with  the 
most  general  classes  being  at  the  top. 
All  classes  have  a  common  ancestor 
called  the  “grandfather  class.”  In  Actor, 
the  grandfather  class  is  the  Object  class. 
The  Object  class  specifies  safe  default 
behavior  for  all  objects,  such  as  what 
to  do  when  an  unknown  message  is 
received  (in  this  case,  print  an  error 
message).  As  subclasses  descend  from 
classes,  they  inherit  the  functions  of 
their  parent  class.  This  allows  the  pro¬ 
grammer  to  use  existing  behavior  in  his 
new  objects,  specifying  only  what’s  dif- 


initialize  regular  expression 

open  input  file 

open  output  file 

while  not  at  end  of  input  file 

read  line  from  input 
process  it 

end  while 
close  input  file 
close  output  file 

Figure  1:  Grep  and  Reviser  have  simi¬ 
lar  main  functions 


ferent  for  the  new  application.  This 
“programming  by  difference"  means 
that  less  duplicate  code  needs  to  be 
written. 

Actor  provides  a  rich  set  of  classes 
as  part  of  the  base  language,  including 
Boolean  values  (which  are  similar  to 
Booleans  in  Pascal),  files,  Strings  (simi¬ 
lar  to  strings  in  Basic  but  with  a  16K 
character  limit),  and  Ordered  and  Sorted 
Collections  for  data  structures  such  as 
arrays  and  queues.  Actor  also  provides 
a  set  of  classes  for  conveniently  creat¬ 
ing  and  handling  Microsoft  Windows 
objects,  such  as  windows,  dialog  boxes, 
and  scroll  bars.  I’ll  use  the  text-based 
objects  in  Actor  only  to  demonstrate 
how  inheritance  and  classes  can  make 
writing  common  utility  programs  much 
easier. 

Plan  of  Attack 

My  goal  in  this  article  is  to  develop  two 
filter  programs  using  Actor  classes  and 
methods.  The  first  program  is  an  object- 
oriented  version  of  the  Unix  utility  grep, 
which  searches  for  and  prints  all  occur¬ 
rences  of  a  regular  expression  in  a  file. 
(The  word  “Grep”  is  a  twisted  acronym 
for  “globally  search  for  regular  expres¬ 
sion.”)  I’ll  then  extend  Grep  in  order 
to  replace  the  pattern  with  a  new  string. 
This  second  program  is  called  Reviser. 
By  using  Actor’s  inheritance  wisely,  the 
Reviser  program  will  be  extremely  easy 
to  write  once  Grep  is  working. 

By  using  a  straightforward  loop  in  a 
procedural  language,  you  could  sim¬ 
ply  create  a  Grep  function  and  a  Reviser 
function  and  write  both  programs.  This 
is  a  direct,  but  not  very  compact  solu¬ 
tion.  A  close  look  at  this  problem  re¬ 
veals  the  many  similarities  between  the 
two  programs.  The  most  obvious  is 
that  the  main  function  for  both  of  them 
is  the  same,  as  illustrated  in  Figure  1. 

For  Grep,  the  output  file  is  the  dis¬ 
play  where  you  want  to  see  the  lines 
of  text  that  match  the  regular  expres¬ 


sion.  For  the  Reviser  program,  the  out¬ 
put  file  is  another  file  that  holds  the 
revised  text.  The  Reviser  differs  from 
Grep  in  its  output  file,  and  in  the  pro¬ 
cessing  that’s  done  to  each  line.  Grep 
searches  the  line  for  the  expression 
and  copies  it  to  the  output  file  if  it 
matches,  while  Reviser  goes  a  step  fur¬ 
ther  and  changes  it  before  copying  it 
to  the  output  file. 

As  I  said  earlier,  both  Grep  and  Re¬ 
viser  are  examples  of  a  filter,  a  program 
that  reads  an  input  file  and  filters  it  by 
some  sort  of  processing  into  an  output 
file.  The  input  file  can  be  filtered  a 
character  or  a  line  at  a  time.  For  the 
purpose  of  this  article,  a  line  at  a  time 
is  sufficient. 

Because  this  is  such  a  common  de¬ 
sign  for  a  program,  it’s  worthwhile  to 
first  develop  a  Filter  class  of  objects 
that  can  be  used  to  write  the  Grep  and 
Reviser  programs  with.  Later  on,  you 
can  add  more  types  of  filters  using  this 
class  and  save  a  great  deal  of  code. 

Further,  because  the  Reviser  is  so 
similar  to  Grep,  you  should  be  able  to 
inherit  most  of  its  functions  from  Grep, 
add  the  part  that  uses  change(-  ),  and 
send  the  output  to  a  file  instead  of  the 
display.  This  will  save  even  more  code. 

This  approach  will  save  the  time  and 
effort  of  developing  both  the  Grep  and 
Reviser  from  scratch.  The  first  step  is 
to  develop  the  Filter  class,  and  then 
develop  the  Grep  so  it  uses  a  Filter 
Most  of  the  Grep  can  then  be  inherited 
in  order  to  write  the  Reviser. 

The  RegularExpression  Class 

Before  writing  the  Filter  class,  how¬ 
ever,  let’s  take  a  closer  look  at  the 
problem  of  searching  for  strings  in  the 
file.  This  is  an  important,  common  func¬ 
tion  in  both  Grep  and  Reviser.  Search¬ 
ing  for  literal  strings  is  easy,  but  also 
limiting  at  times.  It  would  be  useful  to 
search  not  only  for  a  literal  string,  such 
as  Fred,  but  also  for  the  four-letter  words 
that  begin  with  the  letter  “F.”  This  is 
especially  true  when  editing  programs, 
because  you  might  have  used  “If’  in 
one  place  and  “if’  somewhere  else. 
You  want  to  be  able  to  search  for  both 
by  entering  a  single  string  expression. 

A  convenient  notation  for  these  types 
of  string  searches  exists,  and  can  be 
implemented  here.  Borrowed  from  the 
Unix  world,  these  are  called  “regular 
expressions.”  You  already  use  a  regu¬ 
lar  expression  when  entering  a  wild¬ 
card  file  specification  in  MS-DOS,  such 
as  DEL*.*. 

This  regular  expression  format  will 
be  a  bit  more  limited  than  that  of  MS- 
DOS,  but  still  powerful,  and  will  allow 
regular  expression  strings  to  contain 
I  normal  alphanumeric  characters,  plus 


Character 

Meaning 

? 

match  any  character 

% 

match  the  start  of  the  string 

$ 

match  the  end  of  the  string 

Table  1:  Some  special  characters 

Character 

Meaning 

?  match  any  character 

%  match  the  start  of  the  string 

$  match  the  end  of  the  string 

[  begin  list 

]  end  list 

exclude  set  of  characters  from  match 
_ \ _ take  next  character  literally _ 

Table  2:  Characters  in  regular  expressions 
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(continued  from  page  30) 

the  special  characters  (sometimes  called 

metacharacters)  listed  in  Table  1. 

For  example,  the  regular  expression 
F???  matches  any  string  that  started 
with  the  letter  F  and  was  followed  by 
three  characters.  The  regular  expres¬ 
sion  %F???$  matches  any  string  that 
consists  only  of  these  characters,  noth¬ 
ing  else. 

You  can  match  sets  of  characters  by 
using  the  metacharacters  t  ]  to  enclose 
a  set.  For  example,  the  string  Flaeiou]?? 
will  match  any  four-character  string  that 
starts  with  the  letter  F  and  is  followed 

The  facilities  in  an 
object-oriented 
language  such  as  Actor 
make  writing  filter 
programs  easy,  using 
several  common  classes 
and  methods 


first  by  a  vowel,  and  then  by  any  two 
characters.  If  the  first  character  in  the 
set  is  tilde  (-),  then  the  remaining  char¬ 
acters  enclosed  by  [  ]  are  excluded  from 
matching.  For  example,  the  string  F[~ri]?? 
matches  any  strings  that  start  with  F 
but  are  not  followed  by  r  or  i.  Sets  can 
include  ranges  of  characters:  For  exam¬ 
ple,  the  set  [A-Za-z]  matches  all  the 
upper  and  lowercase  alphabetic  char¬ 
acters. 

When  searching  for  strings  that  con¬ 
tain  metacharacters,  a  backslash  (  \  ) 
will  specify  one  of  the  other  meta¬ 
characters  literally  afterwards.  Table  2 
provides  the  complete  list  of  meta¬ 
characters  supported. 

This  is  an  ambitious  project,  but  the 
rewards  will  be  worth  the  effort  as  the 
use  of  this  class  can  add  efficient  pat¬ 
tern  matching  to  virtually  any  text- 
based  program.  The  key,  however,  is 
to  make  the  pattern  allow  for  fast  search¬ 
ing  and  compact  representation. 

Although  it’s  tempting  to  use  one  of 
the  predefined  Ordered  or  Sorted  Col¬ 
lection  classes  in  the  Actor  language 
when  writing  this  class,  this  is  slow  and 
wasteful  of  storage  for  large  patterns 
and  requires  a  lot  of  searching.  The 
best  approach  is  to  encode  and  embed 


the  characters  shown  in  Table  2  as 
control  characters  in  the  pattern  string. 
This  allows  the  encoded  patterns  to 
be  stored  anywhere  a  String  can  be 
stored,  and  searched  rapidly  with  char¬ 
acter-by-character  comparisons. 

I  call  this  class  RegularExpression.  It 
contains  a  String  as  an  instance  vari¬ 
able  (the  encoded  pattern),  and  a 
Boolean  that  determines  whether  the 
case  of  an  alphabetic  character  is  sig¬ 
nificant.  You  must  immediately  write 
several  methods  that  access  the  instance 
variables  without  resorting  to  dot  nota¬ 
tion:  setPattern( )  allows  you  to  send 
a  previously  encoded  pattern  to  the 
RegularExpression  as  the  new  pattern 
to  use,  and  setCaseMatchC )  allows  you 
to  set  the  Boolean  instance  variable 
that  determines  if  upper  and  lowercase 
versions  of  the  same  character  are  to 
be  treated  as  equal.  So  you  can  save 
an  encoded  pattern  for  later  use,  pat - 
tern( )  will  return  the  pattern  instance 
variable.  This  allows  a  single  RegularEx¬ 
pression  instance  to  handle  multiple 
patterns. 

The  first  hurdle  is  encoding  the  pat¬ 
tern.  This  is  done  by  makePattern( ). 
It  loops  through  the  String  that  is  the 
regular  expression,  building  another 
String  that  is  the  encoded  pattern.  When 
it  finds  a  metacharacter  in  the  source, 
it  places  a  control  character  into  the 
pattern  that  will  be  used  later  for  com¬ 
parisons.  These  control  characters  are 
kept  in  a  header  file  called  REGULARE.H 
(see  Listing  One,  page  112)  and  can 
be  changed  later  if  necessary. 

Building  the  pattern  is  a  big  job.  It 
requires  another  message,  fillSet( ),  which 
takes  a  set  enclosed  in  [  ]  and  encodes 
it.  Use  an  INCLUDE_SET  or  OMIT_SET 
character  for  the  set  delimiter  (depend¬ 
ing  on  whether  the  characters  that  fol¬ 
low  match),  followed  by  a  character 
that  is  the  number  of  characters  in  the 
set,  and  then  by  the  characters  them¬ 
selves.  If  a  -  (hyphen)  was  used  to 
indicate  a  range  of  characters,  such  as 
A  -  Z,  this  set  is  expanded  and  copied 


Figure  2:  Encoding  a  regular  expression 


into  the  pattern  string.  This  is  done 
when  the  pattern  is  built,  and  it  won’t 
be  repeated  when  matching  is  per¬ 
formed  because  this  would  slow  down 
the  program  considerably.  A  sample 
encoded  pattern  is  shown  in  Figure  2. 

Though  this  seems  like  a  lot  of 
trouble,  the  result  is  that  you  can  com¬ 
pare  a  String  against  a  pattern  in  a 
running  program  by  characters  only, 
which  are  efficiently  handled.  There  is, 
however,  a  limit  of  255  characters  in  a 
set  enclosed  by  [  ],  because  that’s  the 
largest  count  you  can  place  in  a  single 
character. 

The  comparison  of  a  RegularExpres¬ 
sion  against  a  String  is  handled  by 
match( ).  It  calls  aMatch( ),  which 
matches  the  encoded  pattern  against 
every  possible  substring  in  the  source 
string.  If  case  matching  is  enabled  icase- 
Match  is  non  -nil),  then  match( )  con¬ 
verts  the  pattern  and  source  to  upper¬ 
case  before  calling  aMatch.  The  method 
aMatcbC )  in  turn  calls  oneMatcbC ), 
which  matches  a  single  character  in  the 
pattern  against  a  single  character  in  the 
string.  When  a  comparison  fails,  one- 
Match( )  fails,  and  aMatch  goes  on  to 
the  next  string. 

Because  of  the  way  the  pattern  is 
encoded,  a  control  character  always 
determines  what  type  of  comparison 
to  perform.  Even  a  single  character  has 
an  A_CHAR  control  character  preced¬ 
ing  it,  which  directs  oneMatcbC )  to 
compare  it  against  a  single  character 
in  the  source.  As  a  result  of  this  prop¬ 
erty,  oneMatcbC )  can  use  a  select/case 
statement  to  handle  each  type  of  con¬ 
trol  character.  Two  instance  variables, 
arrow  and  cursor,  hold  the  indexes  of 
the  source  string  and  the  pattern  dur¬ 
ing  the  matching  process. 

In  Actor,  constants  such  as  A_CHAR 
can  be  placed  in  separate  files  for  eas¬ 
ier  maintenance,  just  as  in  C.  For  the 
RegularExpression  class,  the  header  file 
is  called  REGULARE.H.  The  header  file 
and  class  file  for  this  class  are  in  Listing 
Two  (page  112). 

You  can  test  this  code  by  first  load- 
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ing  the  header  file  and  the  class  file,  | 
then  typing: 

Fred  :=  new(RegularExpression,  "F???"); 
match(Fred,  "My  name  is  Fred"); 

11 

If  the  pattern  was  found  in  the  source 
string,  I  could  have  simply  returned 
true  or  false.  Instead,  match! )  returns 
the  position  in  the  source  string  where 
the  match  occurred,  or  nil  if  it  didn’t. 
Including  this  extra  touch  allows  the 
source  string  to  be  edited.  The  other 
methods  in  RegularExpression  make  the 
change( )  method  easy  to  write  and 
allow  a  string  matching  the  pattern  to 
be  replaced  by  another: 

changeCFred,  "My  name  is  Fred",  "Sam"); 
My  name  is  Sam 

The  search-and-replace  function  of  a 
word  processor  or  text  editor  becomes 
easy  to  write  with  a  RegularExpression 
class. 

The  Filter  Class 

It’s  important  to  be  able  to  create  and 
compare  regular  expressions  before  mov¬ 
ing  on  to  the  Filter  class.  Looking  at  the 
structure  of  a  filter  program,  (including 
Grep  and  Reviser)  we  can  see  it  follows 
the  general  design  shown  in  Figure  3. 
The  phrases  “initialize  processing,”  “pro¬ 
cess  line,”  and  “terminate  processing” 
will  vaiy  from  program  to  program. 
Also  notice  that  the  input  and  output 
files  from  the  previous  iteration  of  the 
design  have  now  become  objects.  Poly¬ 
morphism  allows  an  object  to  be  used 
in  place  of  an  input  or  output  file  as 
long  as  it  obeys  the  protocol  of  a  File , 
adding  even  more  generality  to  the  idea 
of  a  Filter. 

In  order  to  change  the  parts  of  the 
Filter  that  will  vary  from  program  to 
program,  blocks  can  be  used  to  pass 
the  class-independent  processing  parts 
to  the  Filter.  This  design  requires  three 
blocks,  one  for  each  of  the  processing 
phrases.  The  first  is  initBlock,  because 
it  receives  control  before  the  input  and 
output  files  are  opened.  Its  job  is  to 
initialize  anything  needed  by  the  ob¬ 
ject  using  the  Filter.  The  second  block 
is  processBlock.  It  receives  the  string 
read  from  the  input  object,  plus  the 
output  object,  and  does  whatever  pro¬ 
cessing  is  needed  by  the  Filter.  The 
third  is  closeBlock,  which  is  called  be¬ 
fore  the  input  and  output  objects  are 
closed.  It  performs  any  cleanup  and 
termination  the  Filter  needs. 

The  file  for  the  Filter  class  is  in  List¬ 
ing  Three,  page  114.  The  run( d  method 
actually  does  the  Filter’s  processing, 
according  to  the  design  in  Figure  3-  It 


also  calls  checkError! )  at  the  proper 
times  to  ensure  that  the  input  and  out¬ 
put  objects  are  opened  correctly,  and 
that  the  end  of  the  input  object  hasn’t 
been  reached. 

Like  the  RegularExpression  class  be¬ 
fore  it,  the  Filter  class  is  not  particularly 
useful  by  itself  —  it  needs  a  Grep  class 
to  take  advantage  of  the  Filter’s  gener¬ 
ality. 

The  Grep  and  Reviser  Classes 

The  Grep  class  will  be  a  descendant  of 
Object ,  because  it  must  use  behavior 
from  three  other  classes:  Files,  Regu- 
larExpressions,  and  Filters.  If  Grep  is 
made  a  descendant  of  one  of  these,  the 
others  will  lend  a  lot  of  code  and  un¬ 
wanted  behavior.  Make  it  a  unique  class 
and  use  all  three  of  the  other  objects 
as  instance  variables. 

The  goal  of  the  Grep  class  is  to  create 
a  Filter  and  provide  it  with  the  initBlock , 
processBlock,  and  closeBlock  needed  to 
search  a  file  for  a  regular  expression, 
and  to  print  the  lines  that  contain  it. 
Formulating  the  blocks  is  easy:  The 
blocks  will  simply  call  the  start( ),  pro¬ 
cess!  X  and  finish ( )  messages  in  the 


initialize  processing 
open  the  input  object 
open  the  output  object 
while  not  at  end  of  input  object 

read  a  line  from  input  object 
process  line 
end  while 

terminate  processing 
close  input  object 
close  output  object 

Figure  3:  Structure  of  a  typical  filter 
program 


Figure  4:  Sample  Grep  output 


Grep  class.  Deciding  what  these  three 
messages  should  do  takes  a  bit  more 
time. 

The  finish ( )  method  is  the  easiest. 
It  simply  prints  a  count  of  the  lines  that 
were  found  in  the  file.  It  doesn’t  even 
have  to  do  that,  but  this  is  easily  ac¬ 
complished  with  an  instance  variable 
(called  matches )  that  keeps  a  count  of 
the  lines  that  match. 

The  start ( )  method  opens  the  input 
file  that  was  passed  as  an  argument 
when  the  Grep  object  was  initialized 
with  init( ).  It  also  prints  a  message 
that  tells  the  user  that  the  program  has 
started,  and  lists  the  name  of  the  file 
being  searched. 

The  process ( )  method  takes  the  string 
read  from  the  input  file  and  compares 
it  against  a  RegularExpression  pattern 
held  in  an  instance  variable.  If  it  matches, 
it  prints  the  line  with  Printline ( )  and 
increments  the  matches  instance  vari¬ 
able.  If  not,  it  doesn’t  do  anything. 

Finally,  the  init( )  method  is  respon¬ 
sible  for  setting  up  the  Filter  and  Regu¬ 
larExpression  objects  and  the  blocks 
that  the  Filter  will  use.  Two  other  in¬ 
stance  variables  are  initialized  by  init! }. 
fileName,  which  holds  the  name  of  the 
file  being  searched,  and  pattern,  the 
RegularExpression  used  as  the  search 
pattern. 

Three  other  messages  in  this  class 
might  puzzle  you.  They  are:  create! ), 
close! X  and  checkError! ).  All  return 
self.  These  are  here  because  the  Filter 
object  treats  the  Grep  object  as  the  out¬ 
put  file.  The  output  isn’t  being  written 
to  a  real  file,  but  to  a  Grep  object  that 
checks  the  lines  read  from  the  input 
file  against  the  regular  expression.  For 
this  deception  to  work,  the  Grep  class 
must  support  the  File  object’s  public 
protocol,  even  down  to  checkError! ). 


mmn 

IgKBMaiMi 

TrTl 

Actor  Workspace 


File  Edit  Doit!  Inspect!  Browse! 
Cleanup!  Show  Room!  Utility  Templates 
Demos ! 


RegularExpression: setPattern 
RegularExpression: init  compi 
RegularExpression: patternSiz 
RegularExpression: fillSet  co 
RegularExpression: makePat ter 
1930  bytes  used. 

16176  bytes  available. 

FilterClass: new  compiling... 

Filter: run  compiling... 

Filter: init  compiling... 

436  bytes  used. 

15718  bytes  available. 

GrepClass: run  compiling... 

Grep:close  compiling... 

Grep: checkError  compiling... 

Grep:create  compiling... 

Grep: finish  compiling... 

Grep:process  compiling... 

Grep:start  compiling... 

Grep:init  compiling... 

560  bytes  used. 

15138  bytes  available. 

Searching  file:  readme.txt 
The  Whitewater  Group 

The  newest  version  of  this  file  will  always  be  present  on  The  Whitewater 
2  lines  matched  pattern.  . 


load ("cl asses \regulare. els") ; 
SourceFile("classes\regulare.  els") 
load("classes\f ilter . els") ; 
SourceFile("classes\f ilter . els") 
load ("class esNgrep.  els") ; 
SourceFile(”classes\grep. els") 
runCGrep,  "readme.txt",  "[ Ww]hitewater") ; 
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Because  these  messages  don’t  have  to 
do  anything  (the  Grep  has  already  been 
created,  and  it  can’t  be  closed),  they  can 
return  self.  This  is  a  common  technique 
in  object-oriented  programming,  another 
use  for  fall-through  methods  and  poly¬ 
morphism:  Making  one  object  obey  the 
protocol  of  another  so  they  can  be 
used  interchangeably.  The  Grep  class 
file  is  shown  in  Listing  Four,  page  114. 

A  new( )  method  is  defined  in  this 
class  that  will  allow  you  to  create  and 
initialize  a  Grep  with  a  single  message, 
with  which  you  specify  the  name  of  the 
file  and  the  regular  expression  to  search 
for  as  arguments: 

run(Grep,  "README.TXT1,  "[Wwjhite- 

water1'); 

The  sample  output  from  Grep  is  shown 
in  Figure  4. 

Reviser  can  now  be  written.  Most  of 
Reviser  is  already  done,  because  it  does 
the  same  thing  as  Grep  except  the  pro- 
cess( )  method.  In  a  Reviser ;  the  line 
read  from  the  input  file  must  be  searched 
using  matchC ),  then  changed  if  the 
pattern  is  found,  and  then  written  to 
the  output  file  in  either  case.  Therefore 
Reviser  should  be  a  descendant  of  Grep. 

The  output  file  needs  instance  vari¬ 
ables  for  its  name  and  object,  and  an 
instance  variable  for  the  text  that’s  go¬ 
ing  to  be  substituted  when  the  pattern 
is  found.  The  other  instance  variables 
will  be  inherited  from  Grep. 

The  start( )  and  finish( )  messages 
use  the  Grep  versions  of  these  mes¬ 
sages  and  do  their  own  unique  pro¬ 
cessing.  Early  binding  notation  indi¬ 
cates  that  the  Grep  version  of  start  should 
be  called: 

Astart(self:Grep,  inFile); 

In  the  Grep  class,  the  create( ),  check- 
ErrorJ ),  and  close( )  methods  didn’t  have 
to  do  anything,  because  the  output  file 
was  really  a  Grep.  In  Reviser  they  have 
to  function  as  File  methods,  and  are 
passed  on  to  the  Me  class  by  the  newFile 
instance  variable. 

With  inheritance,  the  code  for  the 
Reviser  is  even  shorter  than  for  the 
Grep.  The  class  file  is  shown  in  Listing 
Five,  page  115.  The  Reviser  inherits  the 
run()  message  from  Grep ,  so  it  can 
be  used  with  a  single  message: 

run(Reviser,  "README.TXT",  "[Fflred", 

"Sam"); 

Though  building  the  RegularExpres- 
sion  and  Filter  classes  took  a  while, 
Actor’s  polymorphism  and  inheritance 
can  now  be  used  to  write  tools  such 
as  Grep  and  Reviser  easily.  Both  of 


these  utilities  take  much  longer  to  de¬ 
velop  in  procedural  programming  lan¬ 
guages,  because  the  functions  of  the 
Filter  and  Grep  classes  cannot  be  easily 
separated. 

Availability 

All  source  code  is  available  on  a  single 
disk  and  online.  To  order  the  disk, 
send  $14.95  (Calif,  residents  add  sales 
tax)  to  Dr.  Dobb's  Journal ,  501  Galves¬ 
ton  Dr.,  Redwood  City,  CA  94063,  or 
call  800-356-2002  (from  inside  Calif.) 
or  800-533-4372  (from  outside  Calif.). 
Please  specify  the  issue  number  and 
format  (MS-DOS,  Macintosh,  Kaypro). 
Source  code  is  also  available  online 
through  the  DDJ  Forum  on  Compu¬ 
Serve  (type  GO  DDJ).  The  DDJ  Listing 
Service  (603-882-1599)  supports  300/ 
1200/2400  baud,  8-data  bits,  no  parity, 
1-stop  bit.  Press  SPACEBAR  when  the 
system  answers,  type:  listings  (lower¬ 
case)  at  the  log-in  prompt. 
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A  Home  Brew 

C++  Parser 

Designing  your  own  C++  compiler 
begins  with  a  good  parser 


John  M.  Dlugosz 


When  it  comes  to  C++,  still 
relatively  few  tools  are  avail¬ 
able.  This  fact  is  never  more 
apparent  than  when  you 
need  a  cross-reference  util¬ 
ity.  If,  for  instance,  you  want  to  exam¬ 
ine  the  function  foo( ),  you’ll  discover 
that  the  function  could  appear  any¬ 
where  in  your  program.  In  other  lan¬ 
guages,  it’s  simple  to  find  a  function  by 
using  a  text-search  utility,  but  func¬ 
tions  may  be  overloaded  in  C++  — 
you  might  find  seven  functions  named 
foo( ).  You  must  then  know  which  of 
those  functions  might  be  in  scope.  In 
order  to  do  so,  you  need  to  know 
about  the  class  hierarchy.  In  addition, 
you  may  need  to  know  the  types  of  the 
parameters. 

That  is  usually  no  big  deal  —  but  in 
extreme  cases,  for  example,  you  might 
not  know  that  adding  a  Windmill  and 
an  int  generates  a  result  of  type  excep- 
tion_node.  In  short,  you  have  to  parse 
the  entire  file  down  to  the  primitive 
level,  maintain  a  symbol  table,  and  fig¬ 
ure  out  class  relationships  —  you  prac¬ 
tically  have  to  compile  the  program! 

For  the  purposes  of  this  article,  I’ll 
describe  a  parser  generator.  A  table- 
driven  parser,  such  as  Paul  Mann’s  LALR 
Parser  Generator,  takes  a  statement  of 
the  grammar  (see  CPP.GRM,  Listing 


John  is  a  free-lance  writer  and  soft¬ 
ware  developer.  His  upcoming  book: 
Advanced  C  and  Object-Oriented  Pro¬ 
gramming,  (MIS)  will  be  released  in 
mid-1990.  He  can  be  reached  at  P.O. 
Box  867506,  Plano,  TX  75086;  or  on 
CompuServe  at  74066,3717. 


One,  page  116),  and  produces  tables. 
So,  let’s  start  with  the  grammar. 


How's  Your  Grammar 

The  grammar  specification  is  really  a 
language-design  language.  As  the  source 
is  being  parsed,  the  parser  calls  actions 
in  the  program.  This  can  be  viewed  as 
an  event-driven  machine.  The  parser 
sends  messages  to  the  rest  of  the  pro¬ 
gram.  The  way  in  which  the  grammar 
is  specified  determines  what  messages 
are  sent,  when  they  are  sent,  and  in 
what  order.  This  is  the  key  to  using 
LALR  to  build  a  full  parser  program. 

Look  at  the  grammar  in  the  declara¬ 
tion  class.  A  declaration  starts  with  a 
storage  class,  followed  by  a  type  and 
the  item  being  declared.  In  addition,  a 


declaration  contains  asterisks,  paren¬ 
theses,  and  brackets,  as  well  as  key¬ 
words  such  as  near,  far,  const,  and 
volatile.  The  basic  form  of  the  declara¬ 
tion  is  shown  below: 

Declaration  -»  StorageClass  Type 

Declarator ; 

A  declarator  can  be  a  simple  name,  or 
it  can  be  another  declarator  modified 
by  adding  “(  )”  (function  call),“[  ]”  (vec¬ 
tor),  “*”  (pointer),  or  (reference) 
symbols. 

A  declarator  is  put  together  in  very 
much  the  same  manner  as  an  expres¬ 
sion.  A  declarator  contains  operators 
with  different  levels  of  precedence, 
along  with  parentheses  used  for  group¬ 
ing  purposes.  So,  the  grammar  for  dec¬ 
larations  can  be  modeled  on  the  gram¬ 
mar  of  expressions. 

Productions 

In  order  to  achieve  the  right  order  of 
precedence  (including  the  use  of  pa¬ 
rentheses  for  grouping  purposes)  you 
need  three  levels  of  productions.  The 
innermost  level  (Decl3)  is  the  simple 
Dname.  The  next  layer  ( Decl2 )  is  postfix 
operators  “(  )”  and  “[  ].”  The  outermost 
level  (Declarator)  is  prefix  operators 
“*”  and  To  provide  for  grouping, 
the  innermost  layer  can  start  over  again 
with  a  declarator  in  parentheses.  The 
three  levels  of  productions  are  shown 
in  Figure  1. 

Reach  Attribute  is  either  a  near  or  far 
keyword,  or  is  empty.  Const/Volatile? 
is  the  keyword  const,  the  keyword  vola- 
(continued  on  page  43) 
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(continued  from  page  40  ) 
tile ,  neither,  or  both.  Reach  Attribute 
appears  immediately  to  the  left  of  the 
item  that  it  modifies  (in  this  case  a 
pointer  or  reference).  The  const  key¬ 
word  appears  just  after  a  “*”  (or  “&”) 
to  indicate  that  the  item  that  is  pointing 
is  constant. 

So,  how  does  this  triple-decker  defi¬ 
nition  work?  Consider  the  test  case  *x[J. 
The  is  read,  and  matches  the  sec- 

A  type_node  can  refer 
to  a  simple  type  such 
as  int  or  char,  or  to 
fancy  types  such  as 
arrays  and  pointers 


ond  line  of  the  declarator.  So  x[  1  must 
match  the  rest  of  that  line,  which  is 
expecting  another  declarator.  Because 
the  is  in  the  outer  level  and  the  “[  ]” 
is  in  the  inner  level,  the  “*”  has  prece¬ 
dence.  Now  x[]  doesn’t  look  like  any¬ 
thing  under  declarator,  but  a  declarator 
can  be  a  Decl2.  If  this  is  a  Decl2,  it  can 
be  turned  into  a  declarator  when  it  is 
finished.  And  sure  enough,  Decl3 11  is 
listed  under  Decl2.  The  x  matches  Decl3, 
and  an  action  is  triggered.  Then  the 
Decl2[ J  is  finished,  and  an  action  is 
triggered.  Now  the  declarator  is  fin¬ 
ished,  and  another  action  is  triggered. 

Consider  the  order  in  which  the  pro¬ 
gram  receives  its  actions  —  the  name 
x,  the  modifier  Vector,  and  the  modifier 
Pointer.  Notice  that  the  order  of  prece¬ 
dence  is  built  into  the  grammar,  and  is 
the  only  order  possible. 

The  grammar  sends  the  modifiers  in 
the  correct  order  to  the  program.  The 


program  builds  a  representation  of  the 
object  in  response  to  these  messages. 

Keeping  Track  of  It 

All  of  the  information  about  the  source 
being  processed  is  kept  in  nodes.  Dif¬ 
ferent  kinds  of  nodes  are  derived  from 
a  base  class  node  (Listing  Two,  NODE 
.HPP,  page  116).  One  of  the  derived 
nodes  is  a  type_node.  A  type_nodec an 
refer  to  a  simple  type  such  as  int  or 
char ,  or  to  fancy  types  such  as  arrays 
and  pointers.  These  fancy  types  corre¬ 
spond  to  the  four  modifiers.  As  a  result, 
your  code  contains  an  array  of  some¬ 
thing^  a  function  that  returns  Some¬ 
thing:*,  a  pointer  to  something:*,  and 
a  reference  to  Something:*.  If  the  pri¬ 
mary  type  is  one  of  these  four  modi¬ 
fiers,  the  to_what  field  points  to  an¬ 
other  type  node.  In  this  way,  compli¬ 
cated  types  are  stored  in  a  linked  list. 
The  type_node: :print( )  function  in 
NODE.CPP  shows  this  structure  clearly. 

All  of  the  actions  called  by  the  parser 
are  in  the  file  ACTIONS. CPP  (Listing 
Three,  page  118).  The  actions  are  de¬ 
fined  with  an  ellipsis  so  that  the  C++ 
compiler  will  generate  right-to-left  pass¬ 
ing  with  the  caller  clearing  the  stack, 
which  is  what  the  parser  (written  in  C) 
is  expecting  to  call. 

The  working_type  structure  contains 
all  of  the  information  about  the  item 
being  parsed.  The  first  message  is  for 
the  storage  class,  which  is  stored  for 
future  reference.  The  next  item  in  work- 
ingjtype  is  the  type,  which  is  also  stored. 
A  const  (or  volatile )  keyword  can  ap¬ 
pear  on  either  side  of  the  type.  (Notice 
that  the  action  is  called  even  if  the 
production  is  empty.)  As  a  result,  a  pair 
of  calls  to  the  ConstVol  action  take 
place.  ConstVol  can  be  called  in  several 
places,  so  these  calls  simply  stack  the 
values  received.  The  purpose  for  Const¬ 
Vol  is  recognized  later,  and  the  values 
for  this  addition  are  popped  from  the 
stack  when  it  is  ready  for  them. 


Atoms 

The  first  call  in  the  declarator  is  a  call 
to  Dname.  This  call  looks  up  the  last 
scanned  token  and  stores  the  name. 
(In  the  case  of  abstract  declarators,  the 
name  can  be  empty.)  The  name  is  stored 
in  an  atom  table,  and  the  atom  number 
is  used  by  the  rest  of  the  program.  The 
atom  table  can  be  used  in  the  same 
way  that  an  array  of  strings  is  used  — 
when  the  atom  table  is  subscripted  with 

In  other  languages,  it’s 
simple  to  find  a 
function  by  using  a 
text-search  utility,  but 
functions  may  be 
overloaded  in  C++ 


an  int ,  it  gives  a  string.  But,  when  the 
atom  table  is  subscripted  with  a  string, 
it  gives  the  number!  This  second  tech¬ 
nique  is  known  as  an  “associative  ar¬ 
ray”  and  is  quite  handy.  When  a  string 
that  is  not  in  the  table  is  given,  that 
string  is  added  to  the  table  and  a  new 
number  is  assigned.  The  files  ATOM- 
.CPP  (Listing  Four,  page  120)  and 
ATOM. HPP  (Listing  Five,  page  120)  pro¬ 
vide  more  details. 

See  How  They  Run 

As  explained  earlier,  the  type  is  stored 
as  a  linked  list.  Dname  starts  off  a 
declaration,  and  a  new  list  is  created. 
type_root  is  the  head  of  the  list,  and 
this_type  is  the  tail  end.  Each  modifier 
adds  a  link  and  moves  the  tail  down. 

When  TypeModifier  is  called,  the  cor¬ 
rect  primary  (function,  array,  pointer, 
or  reference)  is  stored  in  the  node, 
along  with  other  information  specific 
to  that  type.  Then  a  new  node  is  added, 
and  the  pointer  is  moved  down  to  that 
node.  In  the  expression  *x[],  Dname 
gets  a  name  of  x  and  creates  the  first 
node;  TypeModifier(2)  then  sticks  in 
array  of,  chains  on  another  node  in  the 
to_what  field,  and  moves  the  this_type 
pointer  to  point  to  the  new  node.  Type- 
Modifier(3)  then  plugs  in  pointer  to 
and  adds  on  another  link.  The  linked 
list  now  reads  (starting  at  the  root) 
array  of  pointer  to  <garbage>. 

When  the  declarator  is  finished,  a 
call  to  the  Declaration  is  made.  This 


Declarator 

->  Decl2 

->  ReachAttribute  *  Const/Volatile?  Declarator 

=>  TypeModifier  3 

->  ReachAttribute  &  Const/Volatile?  Declarator 

=>  TypeModifier  4 

Decl2 

->  Decl2  ( Arg-Declaration-List ) 

=>  TypeModifier  1 

->  Decl2  [  ConstExp?  ] 

=>  TypeModifier  2 

->  Decl3 

Decl3 

->  Dname  =>  Dname  1 

->  (  Declarator ) 

Figure  1:  Productions  used  to  determine  the  order  of  precedence 
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(continued  from  page  44) 
call  takes  the  base  type  (stored  way 
back  when  with  the  call  to  StoreType ) 
and  fills  it  into  the  current  node.  For 
example,  if  the  line  read  static  int  x*[ ];, 
then  the  result  is  array  of  pointer  to 
int.  Other  stuff  is  filled  in,  and  the  com¬ 
plete  declaration  is  ready. 

The  declaration  must  be  stored  in  a 
symbol  table  for  later  reference.  The 
type,  along  with  the  storage  class  ( static ) 
and  the  name  (x),  is  sent  to  store_ 
thing( ).  Basically,  that’s  now  the  end 
of  the  story  —  the  parser  continues. 

The  storage  class  and  type  are  still 
remembered,  so  declarators  that  are 
separated  with  commas  use  the  same 
values.  Each  declarator  is  sent  to 
store_thing( )  when  the  declarator  is 
encountered.  The  parser  starts  over  with 
StoreStorage  for  a  new  line,  or  with 
Dname  if  several  declarators  are  con¬ 
tained  in  the  same  statement  (that  is, 
extern  char  a ,  *b,  &c;  share  “extern 
char”). 

In  DEFINE. CPP  (Listing  Six,  page 
120),  store_thing( )  handles  the  “thing” 
after  the  “thing”  is  parsed.  Up  to  now, 
the  only  kind  of  node  used  was  a 
type_node.  Now,  another  kind  of  node 
is  introduced  —  a  def_node.  def_node 
holds  the  complete  definition,  which 
is  built  from  the  type,  the  storage  class, 
and  the  name,  and  is  stored  in  a  list  of 
defjnodes. 

Look  back  at  NODE.HPP,  and  notice 
that  all  of  the  nodes  are  in  a  taxonomy. 
A  list  of  nodes  is  also  very  useful.  A  list 
of  base  class  nodes  can  hold  any  kind 
of  node,  but  it  is  better  to  use  lists  with 
pedigree.  To  do  so,  node_list  class  is 
defined  to  handle  the  maintenance  of 
a  variable-sized  array  of  nodes,  and  a 
dummy  class  is  derived  from  node_list 
for  each  required  pedigree.  This  dummy 
class  contains  an  in-line  function  that 


accesses  the  correct  element  and  casts 
the  elements  to  the  proper  type.  The 
use  of  a  macro  allows  a  list  (for  what¬ 
ever  type  is  needed)  to  be  defined  in  a 
single  statement.  (Note  the  use  of  the 
token-pasting  operator  in  the  macro 
definition.) 

After  the  entire  file  is  parsed,  the  list 
contains  several  entries.  The  AllDone- 
Now  action  is  a  simple  loop  that  prints 
out  the  list.  The  C++  definitions  are 
spit  back  out  in  English-like  phrases. 

Nested  Definitions 

You  may  now  be  wondering  about 
nested  definitions.  Consider  a  case  such 
as  int  (*p)(int  x[ ]);.  In  this  example  the 
parameter  list  is  parsed  after  Dname 
for  the  pointer  modifier,  p,  and  before 
the  function  modifier.  This  itself  con¬ 
tains  a  definition.  Look  at  the  grammar 
for  Arg-Declaration-List —  this  nonter¬ 
minal  grammar  appears  between  the 
parentheses  in  the  function  modifier 
(see  Figure  2). 

Start-Nested-Type  and  End-Nested- 
Type  are  empty  productions,  and  exist 
only  to  call  the  NestedType  action  at  the 
right  place.  This  action  saves  the  state 
of  the  definition  parse  in  progress,  and 
then  restores  the  state  again.  This  sec¬ 
ond  step  is  very  simple  because  all  of 
the  information  is  stored  in  a  structure. 
The  structure  is  placed  into  a  linked  list 
and  a  fresh  structure  is  created.  The 
end  call  puts  the  old  structure  back. 

The  argument-declaration  is  similar 
to  Declaration ,  except  that  it  is  sepa¬ 
rated  with  commas.  The  same  action 
Declaration  is  called  when  an  argument- 
declaration  is  finished,  with  the  pa¬ 
rameter  defined  as  2  instead  of  1 .  This 
change  causes  the  completed  defini¬ 
tion  to  be  placed  into  a  different  list. 
This  new  list  is  also  stackable,  because 
a  parameter  may  itself  be  a  pointer  to 


struct  Cl  *  p; 

int  *p=  "hello  there!"; 

int  *names[  ]; 

union  FOO  *p; 

const  char  *  const  *(*w)( )[  ]; 

char  a,b,*c,&d; 

int  too  (int  a,  char*  b); 


Figure  3:  The  test  data  for  the  parser 

a  function.  The  NestedType( )  action 
calls  parameter_list( ),  which  creates  a 
new  list  to  store  the  upcoming  parame¬ 
ters.  The  end  call  then  pops  the  list  off, 
restoring  any  list  that  was  in  progress. 
This  completed  list  is  placed  in  a  global 
variable,  which  is  read  by  TypeModi- 
fier( )  and  will  be  the  next  action  called. 

This  mechanism  for  nested  types  is 
also  used  for  processing  class  mem¬ 
bers.  Notice  that  the  Const/Vol  stack 
works  across  nested  types.  Consider 
char  * const  CpXchar  const*  s);,  which 
is  a  pointer  to  a  function  that  returns  a 
pointer.  The  first  const  is  used  by  the 
last  modifier  call,  and  stays  on  the  stack 
while  the  nested  type  is  being  parsed. 

Conclusion 

This  program  is  a  far  cry  from  a  full 
compiler,  but  the  program’s  framework 
can  be  easily  expanded  to  include  ad¬ 
ditional  language  elements.  The  first 
feature  that  you  should  add  to  the  pro¬ 
gram  is  the  use  of  initializers.  (The  gram¬ 
mar  presented  in  Figure  3  contains  ini¬ 
tializers,  but  no  actions  are  called  yet.) 
As  you  can  see,  a  small  amount  of  code 
can  produce  a  very  robust  program. 

Availability 

All  source  code  is  available  on  a  single 
disk  and  online.  To  order  the  disk, 
send  $14.95  (Calif,  residents  add  sales 
tax)  to  Dr.  Dobb’s  Journal ,  501  Galves¬ 
ton  Dr.,  Redwood  City,  CA  94063,  or 
call  800-356-2002  (from  inside  Calif.) 
or  800-533-4372  (from  outside  Calif.). 
Please  specify  the  issue  number  and 
format  (MS-DOS,  Macintosh,  Kaypro). 
Source  code  is  also  available  online 
through  the  DDJ  Forum  on  Compu¬ 
Serve  (type  GO  DDJ).  The  DDJ  Listing 
Service  (603-882-1599)  supports  300/ 
1200/2400  baud,  8-data  bits,  no  parity, 
1-stop  bit.  Press  SPACEBAR  when  the 
system  answers,  type:  listings  (lower¬ 
case)  at  the  log-in  prompt. 

DDJ 

(Listings  begin  on  page  116.) 

Vote  for  your  favorite  feature/article. 

Circle  Reader  Service  No.  8. 


Arg-Declaration-List 

->  Start-Nested-Type  A-Decl-List?  Elipses?  End-Nested-Type 

Start-Nested-Type  ->  =>  NestedType  1 

End-Nested-Type  ->  =>  NestedType  0 

A-Decl-List? 

-> 

->  A-Decl-List 
A-Decl-List 

->  A-Decl-List ,  Argument-Declaration 
->  Argument-Declaration 

Argument-Declaration 

->  StorageClass  Type_w/const  Declarator  =>  Declaration  2 
Figure  2:  The  grammar  for  Arg-Declaration-List 
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Writing  Correct 
Software 

Assertion  and  exception  techniques  can  aid  in  class 

correctness 


Bertrand  Meyer 


My  aim  in  designing  Eiffel  was 
to  produce  a  major  program¬ 
ming  language  for  the  1990s, 
catering  to  the  needs  of  those 
software  engineers  willing  to 
do  what  it  takes  to  produce  high-qual¬ 
ity  software.  A  key  aspect  of  Eiffel, 
which  makes  it  original  in  the  world 
of  object-oriented  languages,  and  in 
the  world  of  programming  languages 
at  large,  is  its  strong  emphasis  on  tech¬ 
niques  that  help  produce  highly  reli¬ 
able  software. 

Although,  there  are  many  more  as¬ 
pects  to  Eiffel  (including  those  described 
in  my  book  Object-Oriented  Software 
Construction,  Prentice-Hall,  1988)  the 
reliability  features  deserve  a  presenta¬ 
tion  of  their  own.  That  is  the  focus  of 
this  article.  I  will  show  how  it  is  possi¬ 
ble  to  write  software  that  programmers 
(and  users)  can  place  a  much  higher 
degree  of  confidence  in  than  that  writ¬ 
ten  with  traditional  techniques.  In  par¬ 
ticular,  I  will  discuss  the  all  important 
notion  of  assertion  —  the  specification 
element  included  within  the  software 
itself.  This  will  lead  to  a  systematic 
view  of  exception  handling,  and  a  look 
at  techniques  (such  as  those  offered 
by  Ada)  that  I  find  somewhat  unsafe. 

Why  All  the  Fuss? 

The  issue  is  simple.  It  is  great  to  have 


Bertrand  is  the  president  of  Interactive 
Software  Engineering  and  is  the  main 
designer  of  the  Eiffel  language.  His  book, 
Object-Oriented  Software  Construction, 
was  published  by  Prentice  Hall  in  1988. 
He  can  be  reached  at  805-685-1006, 
or  through  e-mail  as  Bertrand  at 
Eiffel.com. 


flexible  software  that  is  easy  to  build 
and  easy  to  maintain,  but  we  also  need 
to  be  concerned  that  the  software  does 
what  it  is  supposed  to  do. 

From  reading  most  of  the  object- 
oriented  literature,  one  would  think  this 
is  not  a  problem.  Correctness  concerns 
are  hardly  ever  mentioned.  Actually,  it 
is  unfair  just  to  pick  on  object-oriented 
programming.  Take  any  standard  text¬ 
books  you  have  on  programming,  al¬ 
gorithms,  data  structures,  and  similar 
topics.  See  how  many  of  them  list  “cor¬ 
rectness,"  “reliability,"  “invariant,”  or 
“assertion”  in  their  indexes.  I  have  quite 
a  few  textbooks  on  my  shelves,  but 
could  not  find  many  that  passed  this 
simple  test. 

This  apparent  disregard  for  correct¬ 
ness  issues  cannot  last  forever.  Even 


barring  the  occurrence  of  a  major  ca¬ 
tastrophe  resulting  from  faulty  software, 
sooner  or  later  someone  will  call  the 
software  engineers’  bluff  and  ask  them 
exactly  why  they  think  their  systems 
will  perform  as  announced.  It  is  diffi¬ 
cult  to  answer  that  question  convinc¬ 
ingly  given  the  current  state  of  the  art. 

Eiffel  won’t  provide  the  magical  key 
to  the  kingdom  of  software  reliability. 
No  existing  method  or  tools  will.  I  do 
believe,  however,  that  the  Eiffel  tech¬ 
niques  are  an  important  step  in  the 
right  direction. 

If  you  are  expecting  a  sermon  telling 
you  to  improve  your  software’s  reli¬ 
ability  by  adding  a  lot  of  consistency 
checks,  you  are  in  for  a  few  surprises. 
I  suggest  that  one  should  usually  check 
less.  According  to  conventional  soft¬ 
ware  engineering  wisdom,  “defensive 
programming”  is  considered  to  be  a 
programmer’s  best  shot  at  reliability.  I 
believe  that  defensive  programming  is 
a  dangerous  practice  that  defeats  the 
very  purpose  it  tries  to  achieve.  To 
program  defensively  is  one  of  the  worst 
pieces  of  advice  that  can  be  given  to  a 
programmer. 

That  more  checking  can  make  soft¬ 
ware  less  reliable  may  seem  foolish. 
Remember,  though,  that  in  science  com¬ 
mon  sense  is  not  always  the  best  guide. 
If  you  have  ever  hit  a  wooden  table 
with  your  fist,  you  probably  found  it 
hard  to  believe  the  physics  professor 
who  told  you  that  matter  is  a  set  of  tiny 
atoms  with  mostly  nothing  in-between. 

Expressing  the  Specification 

The  ideas  that  help  achieve  correctness 
in  Eiffel  are  much  older  than  Eiffel  it- 
(continued  on  page  52) 
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(continued  from  page  48) 
self.  They  come  from  work  on  program 
proving  and  formal  specification.  Oddly 
enough,  research  on  these  topics  has 
remained  estranged  from  most  “real- 
world”  software  development.  Part  of 
the  reason,  at  least  in  the  United  States, 
is  the  widespread  view  that  formal  speci¬ 
fication  and  verification  are  specialized 
research  topics  whose  application  is 
mostly  relevant  to  “mission-critical”  soft¬ 
ware.  Correctness,  however,  should  be 
a  universal  concern.  Eiffel  looked  at  speci¬ 
fication  and  verification  work  to  see 
how  much  of  it  could  be  made  part  of 
a  standard  programming  methodology. 

Eiffel  is  a  production  language  and 
environment.  It  is  not  a  research  vehi¬ 
cle.  Eiffel  relies  on  the  technology  of 
the  last  part  of  the  twentieth  century. 
It  has  to  work  now.  This  means  that  no 
miracles  can  be  expected.  In  fact,  the 
techniques  are  modest  and  almost  naive. 
They  are  the  result  of  an  engineering 
trade-off  between  what  is  desirable  in 
an  ideal  world  and  what  can  realisti¬ 
cally  be  implemented  today.  But  they 
make  a  big  difference  and  I  can’t  un¬ 
derstand  why  no  widespread  language, 
other  than  Eiffel,  has  made  any  signifi¬ 
cant  attempt  in  a  similar  direction. 

The  basic  idea  is  rather  trivial.  Cor¬ 
rectness  is  a  relative  notion.  No  soft- 


Obligations 

Benefits 

Author 

Bring  in  manuscript 
before  March  1st 

Get  published  text 
before  May  1st 

Publisher 

Publish  before 

May  1st 

No  need  to  do 
anything  if  no 
manuscript  is 
received  before 

March  1st 

Figure  1:  Contract  between  a 
publisher  and  an  author 


Obligations 

Benefits 

Client 

Call  the  routine  on 
two  circles  that 
intersect 

Obtain  as  result  of 
the  function  a 
point  that  is  on 
both  circles 

Routine 

Find  a  point  that  is 
on  both  circles 

No  need  to  return 
anything  meaningful 
if  the  circles  do  not 
intersect 

Figure  3-'  A  routine  contract 


ware  element  is  correct  or  incorrect  per 
se;  it  is  correct  or  incorrect  only  con¬ 
cerning  a  particular  specification,  or 
statement  of  its  purpose.  Correct  ele¬ 
ments  cannot  be  written  unless  the  time 
is  taken  to  express  all  or  part  of  this 
specification. 

Writing  the  specification  will  not  guar¬ 
antee  that  it  is  met.  But  the  presence 
of  a  specification,  even  one  that  is  only 
partially  spelled  out,  goes  a  surpris¬ 
ingly  long  way  toward  helping  pro¬ 
duce  elements  that  satisfy  their  correct¬ 
ness  requirements. 

This  idea  was  captured  by  the  title 
of  an  article  by  Harlan  Mills,  then  of 
IBM,  published  in  1975:  “How  to  Write 
Correct  Programs  and  Know  Why.”  If 
you  are  a  serious  software  engineer, 
you  don’t  just  want  to  hope  that  your 
programs  are  correct  because  you  have 
been  careful,  and  done  a  lot  of  testing, 
and  so  on.  You  need  precise  argu¬ 
ments  that  document  the  correctness 
of  your  software. 

In  Eiffel,  such  arguments  are  ex¬ 
pressed  as  assertions  —  elements  of  for¬ 
mal  specification  that  can  be  attached 
to  software  components,  classes  and 
their  routines. 

The  Contract 

Let’s  look  at  routines  first.  A  routine  is 
the  description  of  some  computation 
on  the  instances  of  a  class,  made  avail¬ 
able  by  that  class  to  its  clients  (to  other 
classes  relying  on  its  services).  How 
do  we  specify  the  purpose  of  a  routine? 

The  view  I  find  most  helpful  is  that 
a  routine  provides  clients  with  a  way 
to  contract  out  for  a  certain  task  that 
the  client’s  designer  finds  advantageous 
not  to  implement  within  the  text  of  the 
client.  This  is  the  same  way  that  we 
humans  at  times  contract  out  for  part 
or  all  of  a  task  that  we  need  to  perform. 

Human  contracts  have  two  impor¬ 
tant  properties: 

•  Each  party  expects  some  benefits  and 
is  prepared  to  incur  some  obligations 
in  return.  What  is  an  obligation  for 
one  party  is  a  benefit  for  the  other. 

•  The  obligations  and  benefits  are 
spelled  out  in  a  contract  document. 

Figure  1  illustrates  an  example  of  a 
contract  between  a  publisher  and  an 
author.  The  author’s  obligation  is  to 
bring  in  a  manuscript  before  March  1st. 
The  benefit  to  the  author  is  that  the 
manuscript  will  be  published  before 
May  1st.  The  publisher’s  obligation  is 
to  publish  the  manuscript  before  the 
second  date. 

The  publisher  is  not  bound  by  any 
obligation  if  the  author  violates  his  part 
of  the  deal.  In  such  a  case  the  publisher 


may  still  publish  the  manuscript,  but 
does  not  have  to.  The  situation  is  out¬ 
side  of  the  contract’s  bounds. 

Routine  as  Contract 

Specifying  a  routine  is  based  on  the 
transposition  of  these  observations  to 
software.  First,  we  need  the  equivalent 
of  the  contract  document.  It  bewilders 
me  that  no  such  concept  exists  in  stan¬ 
dard  approaches  to  software  construc¬ 
tion. 

The  specification  consists  of  two 
parts: 

•  The  precondition  of  a  routine  states 
the  obligations  of  clients,  which  are 
also  the  benefits  for  the  routine  itself. 

•  The  postcondition  states  the  obliga¬ 
tions  of  the  routine,  which  are  also 
the  benefits  for  the  clients. 

The  precondition  is  a  set  of  initial  con¬ 
ditions  under  which  the  routine  oper¬ 
ates.  Ensuring  the  precondition  at  the 
time  of  any  call  to  the  routine  is  the 
clients’  responsibility. 

The  postcondition  is  a  set  of  final 
conditions  the  routine  is  expected  to 
ensure.  Ensuring  the  postcondition  at 
return  time  (if  the  precondition  was 
met  on  entry)  is  the  routine’s  responsi¬ 
bility. 

The  concept  of  a  contract  is  one  of  the 
most  useful  aids  to  understanding  Eif¬ 
fel  programming.  The  role  of  contracts 
in  Eiffel  can  be  compared  to  what  mes¬ 
sage  passing  represents  in  Smalltalk. 

Figure  3  illustrates  this  idea.  The  func¬ 
tion  intersect  1  in  a  class  CIRCLE  (as¬ 
sumed  to  be  part  of  some  graphic  pack¬ 
age)  returns  one  of  the  two  intersecting 
points  of  two  circles  (see  Figure  2). 
We  will  look  at  how  to  associate  the 
precondition  and  the  postcondition  to 
the  text  of  the  function  in  the  actual 
Eiffel  class.  In  this  example: 

•  The  precondition  is  that  the  two  rec¬ 
tangles  should  intersect. 

•  The  postcondition  is  that  the  function 
result  is  a  point  that  is  on  both  circles. 

Contract  Variants 

This  is  not  the  only  possible  specifica¬ 
tion.  Programmers  may  feel  uneasy 
about  the  just  mentioned  “demanding” 
form  of  the  routine,  which  only  works 
in  some  cases.  Instead,  a  tolerant  ver¬ 
sion  implementing  a  different  contract 
may  be  designed.  For  example: 

•  There  is  no  precondition.  More  pre¬ 
cisely,  the  precondition  is  true,  and 
automatically  satisfied  by  any  client. 
Here,  the  routines  will  be  applicable 
in  all  cases. 

•  The  postcondition  is  more  difficult 


52 


Dr.  Dobb’s  Journal,  December  1989 

837 


(continued  from  page  52) 
to  express  in  this  case.  Either  the  two 
circles  intersect  and  the  function  result 
is  a  point  on  both  circles;  or  the  two 
circles  do  not  intersect,  the  function 
result  is  an  arbitrary  point,  and  an  error 
message  has  been  displayed  some¬ 
where.  The  awkwardness  of  stating  the 
postcondition  in  such  a  way  is  the  first 
sign  of  why  “demanding”  versions  are 
often  better. 

Expressing  the  Contract 

Let’s  see  how  the  preconditions  and 
postconditions  will  be  integrated.  List¬ 
ing  One,  page  125,  shows  what  a  class 
CIRCLE  might  look  like.  Assume  the 
availability  of  a  class  PO/ATdescribing 
points,  and  a  function  distance ,  such 
that  pi. distance  (p2)  is  the  distance 
between  any  two  points  (pi  and  p2). 

Result  is  a  predefined  variable  which, 
in  a  function,  denotes  the  result  of  that 
function.  Create  is  the  initialization  pro¬ 
cedure.  It  is  automatically  exported. 

The  precondition  of  a  routine,  if  any, 
is  given  by  the  require  clause.  The  post¬ 
condition  is  given  by  the  ensure  clause. 
Preconditions  and  postconditions  are 
assertions  —  logical  constraints  ex¬ 
pressed  as  one  or  more  Boolean  ex¬ 
pressions,  separated  by  semicolons. 
They  are  essentially  equivalent  to 
Boolean  ANDs,  but  allow  assertion  com¬ 
ponents  to  be  identified  individually. 
These  components  can  be  tagged  for 
even  better  identification.  For  exam¬ 
ple,  consider  Listing  Two,  page  125. 

Note  that  the  first  clause  in  this  pre¬ 
condition  (as  well  as  clauses  in  the 
preconditions  of  inside  and  outside ) 
express  that  the  argument  must  be  non¬ 
void.  Void  is  a  predefined  language 
feature  expressing  whether  there  is  an 
object  associated  with  a  certain  refer¬ 
ence. 

Uses  of  Assertions 

Along  with  invariants  (discussed  later), 
preconditions  and  postconditions  play 
a  fundamental  role  in  the  design  of 
Eiffel  classes.  They  show  the  purpose 
of  routines  and  the  constraints  on  their 
uses.  A  brief  look  at  any  well-designed 
set  of  Eiffel  classes  shows  how  wide 
their  application  is.  The  Basic  Eiffel 
Library,  which  covers  fundamental  data 
structures  and  algorithms,  is  an  exam¬ 
ple  of  a  set  of  carefully  designed  classes 
that  come  fully  loaded  with  expressive 
assertions. 

The  first  application  of  assertions, 
perhaps  the  most  powerful,  is  as  a  con¬ 
ceptual  design  aid  for  producing  reli¬ 
able  software.  In  this  role,  precondi¬ 
tions  and  postconditions  directly  sup¬ 
port  the  goal  stated  earlier:  Writing  cor¬ 
rect  software  and  knowing  why  it  is 
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correct.  When  a  routine  is  written,  its 
goal  (contract)  is  expressed.  If  this  goal 
cannot  be  expressed  in  a  formal  way, 
it  should  still  be  expressed  as  formally 
as  possible. 

Documentation  is  another  key  appli¬ 
cation  of  assertions.  One  of  the  most 
pervasive  myths  of  software  engineer¬ 
ing  literature  is  the  idea  that  document¬ 
ing  software  is  a  worthy  goal.  Instead, 
documentation  should  be  viewed  as 
an  evil,  made  necessary  by  the  insuffi¬ 
cient  abstraction  level  of  current  tools, 
techniques,  and  languages.  It  is  an  evil 
not  just  because  documentation  is  tedi¬ 
ous  to  produce,  but  also  because  it  is 
almost  impossible  to  maintain  the  con¬ 
sistency  of  a  software  system  with  its 
documentation  throughout  the  system’s 
evolution.  Incorrect  or  out-of-date  docu¬ 
mentation  is  often  worse  than  no  docu¬ 
mentation  at  all. 

In  an  ideal  world,  software  should 
be  self-documenting,  with  no  need  for 
outside  documentation.  Failing  this  pro¬ 
grammer’s  Eden,  we  should  strive  to 
have  as  little  need  for  external  docu¬ 
mentation  as  possible.  Documentation 
should  be  deduced  from  the  software 
itself.  “Self-documenting  software”  does 
not  mean  that  the  software  is  its  own 
documentation.  Instead,  self-document¬ 
ing  software  should  contain  part,  or 
(ideally)  all,  of  its  documentation,  cor¬ 
responding  to  various  levels  of  abstrac¬ 
tion,  which  can  be  extracted  by  auto¬ 
matic  tools. 

Preconditions  and  postconditions 
play  a  key  role  because  they  document 
the  essential  properties  of  routines:  What 
each  routine  expects  and  what  each 
ensures  in  return.  The  Eiffel  environ¬ 
ment  provides  an  automatic  tool  that 
yields  the  documentation  of  a  class 
based  on  its  assertion.  This  tool,  the 
class  abstracter,  is  implemented  by  a 
command  called  “short.”  Applying  short 
to  a  class  yields  the  description  neces¬ 
sary  to  determine  whether  the  class  can 
be  used  in  a  certain  situation,  and,  if 
so,  how  to  use  it  effectively. 

The  result  of  short  applied  to  class 
CIRCLE  would  be  of  the  form  shown 
in  Listing  Three,  page  125. 

As  shown  in  this  example,  short 
keeps,  as  a  complement  to  formal  as¬ 
sertions,  the  natural  language  header 
comments  of  routines,  if  present,  at  a 
well-defined  place.  Only  exported  fea¬ 
tures  are  kept  by  short. 

short  provides  documentation  “for 
free”  —  it  is  extracted  from  the  soft¬ 
ware.  short  is  the  major  tool  for  docu¬ 
menting  Eiffel  classes.  A  companion 
tool,  good ,  produces  high-level  system 
documentation  in  graphic  form,  show¬ 
ing  the  class  structure  with  client  and 
inheritance  relationships.  Remember, 


though,  that  short  is  meaningless  with¬ 
out  the  presence  of  assertions  in  the 
language. 

Invariants 

Preconditions  and  postconditions  can 
be  used  in  a  non-object-oriented  con¬ 
text.  Another  use  of  assertions  that  is 
inseparable  from  the  object-oriented 
approach  is  the  class  invariant.  This  is 
an  optional  clause  of  Eiffel  classes.  An 
invariant  is  a  consistency  constraint  that 
applies  to  all  instances  of  the  class. 

In  the  CIRCLE  example,  the  invariant 
clause  might  state  the  following  asser¬ 
tion: 

radius  >=  0; 
inside  (center) 

In  larger  examples  the  invariants  can 
be  much  more  extensive. 

Invariants  can  be  viewed  as  general 
clauses  that  are  implicitly  added  to  all 
contracts  of  a  certain  class,  without  be¬ 
ing  expressly  repeated  for  each  of  these 
contracts.  The  precise  definition  of  the 
class  invariant  is  that  it  is  an  assertion 
that: 

•  Must  be  ensured  by  the  Create  of  the 
class 

•  Must  be  preserved  by  every  exported 
routine  of  the  class 

In  principle,  we  could  do  away  with 
the  invariant  by  adding  its  clauses  to 
the  precondition  and  postcondition  of 
every  exported  routine,  and  to  the  post¬ 
condition  of  the  Create.  But,  besides 
making  these  assertions  unduly  repeti¬ 
tive,  this  would  be  losing  sight  of  the 
role  of  the  invariant  as  a  global  integ¬ 
rity  constraint  on  the  class,  independent 
of  a  particular  routine. 

The  two  properties  used  earlier  to 
define  the  invariant  imply  that  the  in¬ 
variant  is  satisfied  in  all  observable  states 
in  the  life  of  every  instance  of  the  class. 
Observable  states  are  those  immedi¬ 
ately  following  the  Create ,  and  before 
and  after  application  of  exported  rou¬ 
tines.  The  life  of  a  typical  object  is 
pictured  in  Figure  4,  with  observable 
states  marked  as  square  blocks.  The 
idea  of  an  observable  state  is  important 
in  the  context  of  parallel  programming. 

In  spite  of  its  name,  an  invariant  is 
not  necessarily  satisfied  at  all  times.  It 
may  be  temporarily  violated  during  exe¬ 
cution  of  exported  routines,  so  long  as 
it  is  restored  for  the  next  observable 
state. 

An  invariant  captures  the  semantic 
properties  of  a  class,  independently  of 
its  current  implementation,  by  a  set  of 
attributes  and  routines.  These  proper¬ 
ties  must  be  understood  in  a  software 
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engineering  context  in  which  software 
is  always  subject  to  change.  Invariants 
can  help  bring  some  order  to  a  con¬ 
stantly  changing  environment  by  ex¬ 
pressing  what  does  not  change  in  a 
class  —  the  basic  semantics  of  the  class. 

Invariants  can  play  a  major  part  in 
establishing  a  scientific  basis  for  soft¬ 
ware  activities  that  currently  rest  on  a 
rather  shaky  basis:  Quality  assurance, 
regression  testing,  and  maintenance. 
Because  an  invariant  expresses  the  es¬ 
sential  semantics  of  a  class  that  should 
be  preserved  through  successive  modi¬ 
fication  and  extension,  it  provides  a 
framework  for  making  QA  and  associ¬ 
ated  activities  more  systematic. 

Limitations  of  Assertions 

The  Eiffel  assertion  techniques  are  only 
partial.  The  assertion  sublanguage  is 
based  on  Boolean  expressions  with 
some  extensions.  Sometimes  more  is 
needed,  such  as  first-order  predicates. 
In  the  CIRCLE  class  it  would  be  nice  to 
have  the  invariant  express  that  no  point 
can  be  both  inside  and  outside  the 
circle,  or  that  any  such  point  must  also 
be  “on”  the  circle.  The  notation  for  this 
could  be: 

for  p:  POINT  then 

inside  (p)  and  outside  (p) 
implies  on  (p) 

end 

This  is  not  possible  in  current  Eiffel, 
although  properties  involving  quantifi¬ 
ers  (“for  all,”  “there  exists”)  can  some¬ 
times  be  expressed  through  Boolean 
expressions  involving  function  calls. 
These  function  calls  require  some  care. 
Other  limitations  of  assertions  are  due 
to  the  reference-based  dynamic  model 
used  for  objects. 

The  mechanism  is  the  result  of  an 
engineering  trade-off.  Though  limited, 
assertions  are  a  tremendous  asset  in 
Eiffel  programming. 


Figure  4:  The  life  of  a  typical  object 


Assertions  and  Inheritance 

Assertions  also  play  an  important  role 
in  the  context  of  inheritance.  Invariants 
are  always  inherited.  When  a  routine 
is  redefined,  its  precondition  may  be 
weakened,  but  not  strengthened.  Its 
postcondition  may  be  strengthened  but 
not  weakened.  To  understand  these 
rules,  the  contracting  metaphor  must 
be  viewed  in  the  context  of  inheri¬ 
tance,  redefinition  (subcontracting),  and 
dynamic  binding. 

Monitoring  Assertions 

The  question  of  what  happens  when  an 
assertion  is  violated  (such  as  if  intersect  1 
is  called  on  two  circles  that  do  not 
intersect)  is  secondary.  The  main  ques¬ 
tion  is:  How  can  we,  as  responsible 
software  professionals,  make  sure  that 
we  produce  software  that  is  correct? 

The  tendency  to  reverse  the  priori¬ 
ties  and  ask  the  secondary  question 
first  is  a  sign  of  how  insecure  most  of 
us  in  the  software  engineering  profes¬ 
sion  feel  about  our  techniques  and  tools. 
This  article  won’t  reverse  this  situation. 
Still,  we  must  get  our  priorities  straight. 

The  answer  to  what  happens  when 
an  assertion  is  violated  depends  on 
how  you  have  compiled  your  class.  If 
you  have  made  the  effort  of  spelling 
out  the  mental  hypotheses  that  under¬ 
lie  the  correctness  of  your  software, 
you  could  expect  a  theorem  prover  to 
check  the  software  against  these  hy¬ 
potheses.  Unfortunately,  this  is  beyond 
today’s  technology.  The  next  best  thing 
to  static  proof  is  run-time  monitoring. 
If  you  compile  a  class  under  the  ALL_ 
ASSERTIONS  mode,  all  assertions  (pre¬ 
conditions,  postconditions,  invariants) 
are  checked  at  the  appropriate  times 
during  execution.  If  one  is  found  to 
be  violated,  an  exception  is  triggered. 
Unless  you  have  made  explicit  provi¬ 
sions  to  handle  it,  the  exception  will 
result  in  program  termination  with  a 
clear  message  identifying  the  context 
of  the  failure. 

There  is  never  a  good  reason  to  com¬ 
pile  a  class  under  any  option  other 
than  ALL_ASSERTTONS,  except  perfor¬ 
mance.  If  you  are  sure  your  software 
is  correct  and  do  not  want  to  incur  the 
overhead  of  checking,  use  the  NO_AS- 
SERTION_CHECK  mode.  If  a  bug  does 
remain,  though,  you  are  on  your  own. 
The  default  is  an  intermediate  mode, 
which  generates  code  that  checks  pre¬ 
conditions  only.  Switching  modes  may 
be  needed  a  number  of  times  during 
development.  This  switch  is  easy.  Only 
the  last  stage  of  compilation  is  repeated 
for  the  corresponding  class. 

Run-time  monitoring  of  assertions  pro¬ 
vides  a  powerful  debugging  mecha¬ 
nism.  Assertions  are  a  way  to  make 


explicit  the  otherwise  implicit  mental 
assumptions  that  lie  behind  our  soft¬ 
ware.  It  is  typical  for  a  bug  to  cause 
one  of  these  assumptions  to  be  vio¬ 
lated.  When  this  occurs,  run-time  moni¬ 
toring  will  catch  the  violation.  This  de¬ 
bugging  technique  takes  on  its  full  mean¬ 
ing  in  the  object-oriented  context.  I 
used  it  when  using  the  Algol  W  com¬ 
piler  in  the  seventies.  Its  superiority 
over  usual  debugging  methods  is  hard 
to  imagine  until  you  have  actually  ap¬ 
plied  it. 

Defensive  is  Offensive 

If  a  routine  has  a  precondition  p,  de¬ 
fensive  programming  would  mean  that 
the  text  of  the  routine  should  test  again 
for  p,  in  case  the  client  forgot.  For  in¬ 
stance,  consider  Listing  Four,  page  125. 

The  form  as  shown  in  Listing  Four 
is  never  acceptable.  It  is  a  sloppy  style 
of  programming  in  which  responsibil¬ 
ity  for  ensuring  various  consistency  con¬ 
ditions  (contract  clauses)  have  not  been 
clearly  assigned.  Because  the  contract 
is  unclear,  the  scared  programmer  in¬ 
cludes  redundant  checks  “just  in  case.” 
This  is  a  self-defeating  policy.  Com¬ 
plexity  is  the  single,  worst  enemy  of 
software  reliability.  The  more  redun¬ 
dant  checks,  the  more  complex  the 
software  becomes,  and  the  greater  the 
risk  of  introducing  new  errors. 

Reliability  is  not  obtained  by  cow¬ 
ardly  adding  even  more  checks,  but 
by  precisely  delineating  whose  responsi¬ 
bility  it  is  to  ensure  each  consistency 
requirement.  A  party  in  a  contract  may 
fail  to  meet  the  requirement  imposed 
on  it.  This  is  precisely  what  a  bug  is. 
The  solution,  however,  is  not  to  make 
the  software  structure  more  complex 
by  introducing  redundant  checking, 
which  only  makes  matters  worse.  For 
fault-tolerant  design,  you  should  be  able 
to  rely  on  a  general-purpose  run-time 
checking  mechanism.  In  Eiffel,  this 
mechanism  is  the  monitoring  of  asser¬ 
tions  as  described  above. 

With  redundant  checking  being  un¬ 
acceptable,  we  still  face  a  choice  be¬ 
tween  the  “demanding”  (strong  pre¬ 
condition)  style  and  the  “tolerant”  (no 
precondition)  style,  with  the  intermedi¬ 
ate  spectrum.  Mathematically,  tolerant 
routines  represent  total  functions  and 
demanding  routines  represent  partial 
functions.  Which  one  to  use  depends 
on  the  circumstances.  The  closer  a  rou¬ 
tine  is  to  uncontrolled  “end  users,”  the 
more  tolerant  it  should  be.  But  even 
with  general-purpose  library  routines, 
there  is  a  strong  case  for  demanding 
routines. 

With  a  strong  precondition,  a  rou¬ 
tine  can  concentrate  on  doing  a  well- 
defined  job  and  doing  it  well,  rather 
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being  concerned  with  other  things.  The 
intersect  1  routine  becomes  a  mess  if  it 
isn’t  assumed  that  the  circles  do  inter¬ 
sect.  Tolerant  routines  must  address 
user  interface  concerns  for  which  the 
routines  do  not  have  the  proper  con¬ 
text.  The  intersectl  routine  must  ad¬ 
dress  problems  of  geometrical  algorith- 
mics  (computing  the  intersection  of  two 
intersecting  circles  in  the  best  possible 
way).  It  is  difficult  to  reconcile  these 
two  aspects  in  a  single  routine.  The 
solution  that  will  ensure  reliability  more 
certainly  than  blindly  checking  all  con¬ 
straints  all  the  time,  is  to  separate  the 
checking  and  the  computation. 

Conventional  wisdom,  which  says 
“never  assume  anything,  anywhere,” 
is  wrong  and  dangerous.  Its  perva¬ 
siveness  can  only  be  explained  by  the 
absence  of  any  notion  of  contract  in 
standard  approaches  to  programming. 
If  clients  have  no  precise  specification 
of  the  conditions  they  are  supposed  to 
observe,  they  can’t  be  trusted  to  ob¬ 
serve  these  conditions  and  there  is  no 
choice  but  to  include  as  many  consis¬ 
tency  checks  as  possible.  In  a  system¬ 
atic  approach  to  software  construction, 
however,  the  contract  is  clearly  and 
adequately  expressed,  independently 
of  its  implementation,  through  asser¬ 
tions.  By  using  the  short  command  to 
let  client  designers  see  this  contract, 
you  can  concentrate  on  doing  your  job 
rather  than  checking  theirs. 

Considered  in  the  perspective  of  other 
engineering  disciplines,  the  often  rec¬ 
ommended  ban  on  “partial”  routines 
seems  absurd.  If  you  ask  an  electrical 
engineer  to  design  an  amplifier  that 
will  work  for  any  input  voltage,  or  a 
mechanical  engineer  to  build  a  bridge 
that  will  hold  any  load,  they  will  laugh 
at  you.  Any  engineering  device  has 
preconditions.  There  really  is  no  good 
reason  why  software  routines  should 
be  required  to  be  total. 

The  reference  to  electronic  compo¬ 
nents  is  not  coincidental.  One  of  the 
most  exciting  advantages  of  object- 
oriented  techniques  is  the  ability  to 
work  from  libraries  of  standardized, 
off-the-shelf,  reusable  components. 
These  components  are  similar  to  hard¬ 
ware  components  used  in  electrical  en¬ 
gineering.  These  libraries  cannot  be 
successful  unless  the  components  are 
specified  in  a  precise  and  standardized 
way.  Trying  to  sell  a  class  without  its 
invariant,  preconditions  and  postcon¬ 
ditions  is  like  trying  to  sell  an  amplifier 
without  its  engineering  specs. 

Programming  by  Prayer 

Assertions  are  not  a  way  to  program 
the  handling  of  special  cases.  An  ex¬ 


ception  violation  is  not  an  expected 
situation  that  you  want  to  handle  sepa¬ 
rately  from  the  others  —  it  is  the  mani¬ 
festation  of  a  bug.  To  handle  special 
cases,  there  is  not  much  substitute  for 
what  you  learned  on  day  two  of  Intro¬ 
duction  To  Programming  100  —  the 
if .  .  .  then  .  .  .  else  construct. 

There  seems  to  be  another  pervasive 
myth  in  the  industry  that  one  can  forget 
about  special  cases  through  a  form  of 
faith  healing.  This  can  be  called  “pro¬ 
gramming  by  prayer."  In  Ada,  the  sa¬ 
cred  word  is  raise.  Whenever  you  en¬ 
counter  a  situation  that  threatens  to 
disrupt  the  spiritual  harmony  of  your 
program,  kneel  down  and  say,  raise 
some _except ion  and  a  saint  or  angel 
will  come  and  take  your  worries  away. 

It  doesn’t  work  this  way.  The  “an¬ 
gel”  has  to  be  programmed,  and  usu¬ 
ally  by  you.  Postponing  a  problem  does 
not  solve  it. 

In  Ada,  after  a  raise,  a  chain  of  calls 
that  led  to  the  exception  is  explored, 
in  reverse  order,  until  a  block  is  found 
that  includes  an  exception  clause  of 
the  form: 
exception 
when 

some_exception=>some_action; 

when 

other_exception=>other_action; 

One  of  the  when  branches  names  the 
current  exception.  Then  the  code 
some_action  is  executed  and  control 
returns  to  the  handling  block’s  caller. 

If  your  aim  was  to  make  your  soft¬ 
ware  simpler  by  separating  the  pro¬ 
cessing  of  "normal”  and  “special”  cases, 
you  will  be  disappointed.  Special  cases 
will  not  go  away  through  the  raise  at¬ 
tempt  at  absolution.  Such  as  old  sins, 
they  will  come  back  to  haunt  you  in 
your  exception  clauses.  In  the  program 
text,  such  clauses  are  far  away  from  the 
source  of  the  exception.  They  usually 
lack  the  proper  context  to  deal  with  the 
exception. 

There  are  two  cases  of  exception 
handling.  One  is  when  the  exception 
must  be  handled  identically  for  all  calls 
of  the  routine.  This  type  of  exception 
is  much  better  handled  by  an  if  .  .  . 
then  .  .  .  else  .  .  .  clause  in  the  routine 
itself.  In  other  words,  the  routine  should 
be  made  more  tolerant. 

The  second  is  when  the  handling  of 
the  special  case  is  different  for  each 
client.  This  can  be  achieved  by  protect¬ 
ing  each  call  with  an  if  .  .  .  then  .  .  . 
else.  The  routine  itself  remains  demand¬ 
ing.  In  either  case  no  special  control 
structure  is  needed. 

Exceptions 

Once  the  naive  faith  in  exceptions  as 


exorcism  has  been  dispelled,  there  is 
still  room  for  an  exception  mechanism. 
Exceptions  should  not  be  used  as  con¬ 
trol  structures.  They  have  no  advantage 
over  standard  control  structures,  and  have 
many  drawbacks.  Some  mechanism  is 
needed  however,  to  deal  with  an  op¬ 
eration  that  might  fail  in  such  a  way 
that  it  is  difficult  or  impossible  to  check 
for  with  a  standard  control  structure. 
Following  are  three  main  examples: 

1.  Bugs.  By  definition,  a  bug  is  unex¬ 
pected.  If  you  were  able  to  test  for  its 
occurrence,  you  would  correct  the  bug 
in  your  software,  not  handle  it  at  run 
time.  If,  in  spite  of  your  best  efforts,  a 
bug  does  occur,  you  still  want  the  abil¬ 
ity  to  recover  from  it  somehow  at  run 
time,  even  if  only  to  terminate  the  exe¬ 
cution  gracefully. 

2.  Uncheckable  consistency  conditions. 
Some  preconditions  may  be  impossi¬ 
ble  to  check  as  part  of  an  if .  .  .  then  .  .  . 
else,  either  because  they  are  too  com¬ 
plex  to  express  formally,  or  because 
the  applicability  of  an  operation  can 
only  be  ascertained  by  attempting  the 
operation  and  seeing  if  it  fails.  For  ex¬ 
ample,  a  write  to  disk  operation  may 
fail,  but  it  is  not  useful  to  ask  first  and 
then  write.  The  only  way  to  know  if 
you  can  write  is  to  attempt  to  write. 
Then,  if  something  goes  wrong,  you 
must  be  able  to  recover.  Another  ex¬ 
ample,  in  an  interactive  system,  is  the 
implicit  precondition  that  the  user  will 
not  hit  the  BREAK  key.  Obviously,  you 
cannot  test  for  the  occurrence  of  such 
events. 

3.  Impractical  to  check  before  each  call. 
These  are  operations  for  which  express¬ 
ible  preconditions  exist  in  principle, 
but  for  which  it  is  impractical  to  check 
before  each  call.  For  example,  few  pro¬ 
grammers  want  to  protect  every  addi¬ 
tion  by  a  test  for  non-overflow,  or  ev¬ 
ery  object  allocation  ( Create )  by  a  check 
that  enough  memory  remains.  As  in  the 
previous  case,  but  for  practical,  rather 
than  theoretical  reasons,  you  want  to 
be  able  to  attempt  the  operation,  pro¬ 
ceed  as  if  everything  went  all  right,  but 
recover  if  something  goes  wrong. 

These  three  cases  are  ones  for  which 
exceptions  are  needed.  They  are  not 
“special”  or  expected  algorithmic  cases, 
but  abnormal  situations  that  cannot  be 
properly  handled  by  standard  algo¬ 
rithmic  techniques. 

In  Eiffel,  an  exception  occurs  in  the 
following  situations: 

•  Assertion  violations  (if  monitored). 

The  violation  of  an  assertion  is  al¬ 
ways  a  bug.  A  violated  precondition 

reflects  a  bug  in  the  client;  a  violated 
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(continued  from  page  58) 
postcondition  reflects  a  bug  in  the 
routine. 

•  Hardware  or  operating  system  sig¬ 
nals,  such  as  arithmetic  overflow,  mem¬ 
ory  exhaustion,  and  so  forth. 

•  An  attempt  to  apply  an  operation  to 
a  non-existent  object  (Void  reference). 

•  Failure  of  a  called  routine. 

The  range  of  such  exceptions  is  much 
less  extensive  in  Eiffel  because  of  the 
disciplined  nature  of  the  language.  In 
particular,  the  static  typing  mechanism 
of  Eiffel  implies  that  for  a  correctly 
compiled  system  there  is  no  exception 
for  a  “feature  applied  to  an  object  that 
cannot  handle  it  (a  message  sent  to  an 
object  that  cannot  process  it).” 

Dealing  with  Exceptions 

What  happens  when  an  exception  oc¬ 
curs?  The  Ada  answer  is  dangerous. 
Because  you  can  do  essentially  any¬ 
thing  you  like  in  a  when  clause,  there 
is  no  guarantee  that  you  will  achieve 
anything  remotely  resembling  the  origi¬ 
nal  purpose  of  the  routine  that  failed. 

To  obtain  a  satisfactory  solution,  it 
is  necessary  to  think  in  terms  of  the 
contract  that  a  routine  is  meant  to  en¬ 
sure.  The  routine  initially  tries  to  satisfy 
its  contract  by  following  a  certain  strat¬ 
egy,  implemented  by  the  routine’s  body 
(the  do  clause).  An  exception  occurs 
when  this  strategy  fails.  In  the  disci¬ 
plined  approach,  only  two  courses  of 
action  make  sense: 

•  The  routine  (contractor)  may  have  a 
substitute  strategy.  If  so,  it  should  bring 
the  target  object  back  to  a  stable  state 
and  use  this  strategy.  This  is  the  re¬ 
sumption  case. 

•  If  no  substitute  strategy  is  available, 
the  routine  should  bring  the  target  ob¬ 
ject  back  to  a  stable  state,  concede 
failure,  and  pass  the  exception  to  its 
client.  This  is  the  failure  case. 


Figure  5:  An  exception  history  table 
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In  the  exception  history  table  shown 
in  Figure  5,  some  exceptions  are  dealt 
with  in  each  of  these  two  modes.  The 
table,  shown  as  it  is  printed  at  run  time, 
is  divided  into  periods,  separated  by 
double  lines.  Each  period,  except  the 
last,  ended  with  a  retry. 

The  absence  of  a  clear-cut  choice 
between  resumption  and  retry  is  what 
makes  the  Ada  mechanism  too  gen¬ 
eral,  and  hence  dangerous.  Some  Ada 
examples  show  cases  in  which  a  rou¬ 
tine  reacts  to  an  exception,  fails  to  cor¬ 
rect  the  cause  of  the  exception,  and 
returns  to  its  caller  without  signalling 
the  exception.  This  is  extremely  dan¬ 
gerous. 

Eiffel  enforces  the  choice  between 
resumption  and  retry.  The  key  idea  is 
that  of  routine  failure  —  a  routine  may 
succeed  or  fail.  If  it  fails  to  achieve  its 
contract,  it  may  either  try  again  or  give 
up.  It  should  not  conceal  the  failure 
from  its  caller. 

This  explains  the  fourth  case  in  the 
earlier  list  of  Eiffel  exceptions.  The  fail¬ 
ure  of  a  routine  automatically  triggers 
an  exception  in  its  caller.  This  is  imple¬ 
mented  by  the  optional  routine  clause 
rescue.  If  present,  the  rescue  clause  is 
executed  whenever  an  exception  oc¬ 
curs  during  the  routine’s  execution. 

If  a  rescue  clause  is  executed  to  the 
end,  the  routine  terminates  by  failing. 
As  noted,  this  automatically  raises  an 
exception  in  the  caller,  whose  own 
rescue  clause  should  handle  it.  If  a 
routine  has  no  rescue  clause,  as  will 
typically  be  the  case  with  most  rou¬ 
tines,  then  it  is  considered  to  have  an 
empty  rescue  clause  —  any  exception 
occurring  during  the  execution  of  the 
routine  leads  to  immediate  failure  and 
an  exception  in  the  caller.  If  no  routine 
in  the  call  chain  has  a  rescue  clause, 
the  entire  execution  fails  and  an  appro¬ 
priate  message,  recording  the  history 
of  recent  exceptions  in  reverse  order, 
is  printed.  Note  the  use  of  assertion 


Object 

Class 

Routine 

Name  of  exception 

Effect 

2FB44 

INTERFACE 

m_creation 

Feature  "quasijnverse”: 
Applied  to  void  reference 

Retry 

2F188 

MATH 

quasijnverse 

“positive_or null": 

Fail 

(from  BASIC  MATH) 

Precondition  violated 

2F188 

MATH 

raise 

“Nega  tive_  value 

Fail 

(from  EXCEPTIONS) 

Programmer  exception 

2F188 

MATH 

filter 

“Nega  tive_  value 
Programmer  exception 

Fail 

2F321 

MATH 

new_matrlx 

“square_matrix": 

Fail 

(from  BASIC  MATH) 

Invariant  violated 

2FB44 

INTERFACE 

create 

Routine  failure 

Fail 

tags,  when  present,  in  the  messages 
shown  in  Figure  5. 

Not  all  exceptions  cause  failure.  A 
rescue  clause  may  execute  a  retry  in¬ 
struction,  in  which  case  the  body  ( do 
clause)  of  the  routine  must  be  tried 
again,  presumably  because  a  substitute 
strategy  is  available.  This  is  the  resump¬ 
tion  case. 

For  example,  consider  the  routine 
in  Listing  Five,  page  125,  for  attempting 
to  write  to  disk,  from  a  generic  class  C. 

Here  it  is  assumed  that  the  actual 
write  is  performed  by  a  lower-level  ex¬ 
ternal  routine  attempt-to- write,  written 
in  another  language,  over  which  we 
have  no  control.  If  this  routine  fails,  it 
triggers  an  exception,  which  is  caught 
by  the  rescue  clause.  This  results  in  a 
retry.  Local  routine  variables  are  initial¬ 
ized  on  routine  entry.  An  integer  vari¬ 
able  such  as  attempts ,  is  initialized  to  0. 

The  routine  write  never  fails.  Its  con¬ 
tract  says,  “write  if  you  can,  otherwise 
record  your  inability  to  do  so  by  setting 
the  value  of  attribute  write_successful 
to  false,  so  that  the  client  can  deter¬ 
mine  ■what  happened.”  It  is  always  pos¬ 
sible  to  satisfy  such  a  contract. 

The  version  of  write  shown  in  Listing 
Six,  page  125  is  a  variant  of  the  class 
that  does  not  include  attribute  write_ 
successful.  It  may  succeed  or  fail. 

In  this  version,  after  five  attempts, 
the  routine  terminates  through  the  bot¬ 
tom  of  its  rescue  clause.  This  means 
the  routine  fails,  triggering  an  excep¬ 
tion  in  the  caller.  This  contract  is  more 
restrictive  than  the  one  shown  in  List¬ 
ing  Three.  It  requires  that  the  routine 
be  able  to  write.  If  this  contract  cannot 
be  fulfilled,  the  only  exit  is  through 
failure. 

Formal  Requirements 

The  deeper  meaning  of  the  rescue 
clause  can  be  understood  in  the  object- 
oriented  context,  and  with  reference 
to  the  contract  of  a  routine,  as  expressed 
by  assertions. 

The  following  expresses  the  require¬ 
ments  on  a  contractor  that  implements 
software  element  e. 

IP)  e  IQ]  ' 

This  means  the  contractor  must  write  e 
in  such  a  way  that,  whenever  Pis  satis¬ 
fied  on  entry,  Q  will  be  satisfied  on 
exit.  The  stronger  P  is,  the  easier  the 
contractor’s  job  (more  can  be  assumed); 
the  stronger  Q  is,  the  harder  the  con¬ 
tractor’s  job  is  (more  must  be  produced). 

Consider  routine  r  with  body  do, 
precondition  pre,  and  postcondition 
post,  in  a  class  with  invariant  INV.  The 
(continued  on  page  63) 

Dr.  Dobb  s  Journal,  December  1989 

841 


EIFFEL 


(continued  from  page  60) 
requirement  on  the  author  of  the  do 
clause  is: 

(pre  andINV)  do  I  post  and  INV) 

In  other  words,  the  invariant  and  the 
precondition  can  be  assumed,  the  in¬ 
variant  must  be  preserved,  and  the  post¬ 
condition  must  be  ensured.  Now,  con¬ 
sider  a  branch  rescue ,  of  the  rescue 
clause,  not  ending  with  a  retry.  The 
requirement  here  is: 

{true)  do  I  INV) 

The  input  condition  is  the  weakest 
possible  (hardest  from  the  contractor’s 
viewpoint),  because  an  exception  may 
occur  in  any  state.  The  rescue  clause 
must  be  prepared  to  work  under  any 
condition,  but  the  output  condition  only 
includes  the  invariant.  Ensuring  the  in¬ 
variant  brings  the  object  back  to  a  sta¬ 
ble  state.  Integrity  constraints  play  a 
similar  role  in  data  base  systems.  The 
rescue  clause  is  not,  however,  con¬ 
strained  to  ensure  the  entire  postcondi¬ 
tion.  This  is  the  sole  responsibility  of 
the  do  clause.  If  the  contractor  satisfies 
the  routine’s  contract,  there  is  no  need 
for  the  rescue  clause. 

This  shows  the  clear  separation  of 
concerns  between  the  do  clause  and 
the  rescue  clause.  The  former  is  re¬ 
sponsible  for  achieving  the  contract 
when  possible.  The  latter  takes  over  in 
case  the  do  clause  falters.  The  rescue 
clause  restarts  the  do  clause  under  im¬ 
proved  conditions,  or  closes  the  store 
after  putting  things  in  order.  The  re¬ 
quirements  on  the  rescue  clause  are 
both  harder  (a  weaker  precondition) 
and  easier  (a  weaker  postcondition). 

Fine-Tuning  the  Mechanism 

Those  are  the  basics  of  Eiffel  exception 
handling.  In  practice,  some  fine-tuning 
may  be  needed  for  particular  applica¬ 
tions.  This  is  done  not  through  the 
language  itself,  but  through  the  library 
class  EXCEPTIONS.  Classes  needing  the 
corresponding  facilities  should  inherit 
this  class. 

It  is  sometimes  necessary  to  treat 
various  exceptions  differently.  Attrib¬ 
ute  exception  in  class  EXCEPTIONS  has 
the  value  of  the  code  of  the  last  excep¬ 
tion  that  occurred.  Exception  codes  are 
integer  symbolic  constants  (attributes) 
defined  in  that  class.  Examples  include 
Precondition  (precondition  violated) 
and  other  assertion-related  exceptions, 
Nojobject,  No_more_memory ,  operat¬ 
ing  system  signals  ( Sighup  and  so  on.) 
and  others.  A  rescue  clause  may  con¬ 
tain  a  test  of  the  form: 


if  exception=No_more_  memory 
then  .  .  .  elsif  and  so  on. 

Generally,  it  is  wise  to  resist  the  temp¬ 
tation  to  attach  too  much  meaning  to 
the  precise  nature  of  an  exception.  An 
exception  usually  points  to  a  symp¬ 
tom,  rather  than  a  cause. 

For  programmers  who  want  to  define 
and  raise  their  own  exceptions,  the  rou¬ 
tine  raise  is  available  in  class  EXCEP¬ 
TIONS.  The  default  handling  of  certain 
exceptions,  especially  operating  sys¬ 
tem  signals,  can  be  changed  by  rede¬ 
fining  certain  routines  from  class  EX¬ 
CEPTIONS.  By  using  class  EXCEPTIONS, 
application  software  can  access  infor¬ 
mation  about  the  last  exception.  This 
information  includes  the  exception  type, 
its  meaning  expressed  as  a  plain  Eng¬ 
lish  string,  and  so  on.  This  is  particu¬ 
larly  useful  for  printing  informative  er¬ 
ror  messages. 

Why  Nof  Make  It  Right? 

Reliability  is  a  primary  concern  in  any 
serious  view  of  software  construction. 
In  the  object-oriented  approach,  it  is 
even  more  essential.  Reusability  of  soft¬ 
ware  is  meaningless  unless  the  reusable 
components  are  correct  and  robust. 
Static  typing  is  an  important  aspect  of 
Eiffel’s  contribution  to  this  goal  (see 
the  article  “You  Can  Write,  but  Can 
You  Type?”  in  the  March  1989  issue  of 
the  Journal  of  Object-Oriented  Program¬ 
ming  for  more  on  this  subject). 

The  assertion  and  exception  tech¬ 
niques  described  in  this  article  provide 
the  complement  to  static  typing.  They 
don’t  absolutely  guarantee  that  your 
classes  will  be  correct  and  robust,  but 
they  sure  can  help. 

Availability 

All  source  code  is  available  on  a  single 
disk  and  online.  To  order  the  disk, 
send  $14.95  (Calif,  residents  add  sales 
tax)  to  Dr.  Dobb’s  Journal,  501  Galves¬ 
ton  Dr.,  Redwood  City,  CA  94063,  or 
call  800-356-2002  (from  inside  Calif.) 
or  800-533-4372  (from  outside  Calif.). 
Please  specify  the  issue  number  and 
format  (MS-DOS,  Macintosh,  Kaypro). 
Source  code  is  also  available  online 
through  the  DDJ  Forum  on  Compu¬ 
Serve  (type  GO  DDJ).  The  DDJ  Listing 
Service  (603-882-1599)  supports  300/ 
1200/2400  baud,  8-data  bits,  no  parity, 
1-stop  bit.  Press  SPACEBAR  when  the 
system  answers,  type:  listings  (lower¬ 
case)  at  the  log-in  prompt. 

DDJ 

(Listings  begin  on  page  125.) 

Vote  for  your  favorite  feature/article. 
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The  QuickPascal  in 

QuickPascal 


A  look  at  how  the  windows  in  QP’s  User  Interface  use  their 
own  object-oriented  technology 


Joseph  Mouhanna  and  Michael  Vose 


Writing  the  user  interface  for 
a  compiler  imposes  a  dif¬ 
ferent  set  of  problems  than 
creating  a  code  generator. 
Presenting  the  applications 
programmer  with  an  orderly  set  of  win¬ 
dows  and  menus  streamlines  his  inter¬ 
action  with  the  compiler.  When  de¬ 
signing  this  interface,  the  compiler’s 
authors  need  to  consider  visual  ele¬ 
ments,  and  not  machine  internals. 

A  windowing  user  interface  uses  a 
limited  number  of  variations  on  a  few 
visual  elements.  These  elements  include 
windows,  dialog  boxes,  and  menus. 
When  these  components  are  analyzed, 
one  realizes  that  dialog  boxes  and 
menus  are  specialized  windows. 

Therefore,  a  windowing  interface 
lends  itself  to  the  hierarchical  structure 
of  object-oriented  programming  (OOP). 
The  match  between  graphical  user  in¬ 
terfaces  and  OOP  emerges  because  the 
techniques  of  OOP  allow  the  creation 
of  new  windows  as  children  of  existing 
windows.  Doing  this  requires  little  ad¬ 
ditional  code.  With  a  few  generic  win¬ 
dow  classes,  specialized  subclasses  im- 
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plementing  variations  on  the  overall 
window  theme  can  be  created. 

Microsoft  used  QuickPascal  itself  to 
write  the  QuickPascal  user  interface. 
They  did  so  to  obtain  the  many  advan¬ 
tages  of  OOP.  In  addition  to  code  reus¬ 
ability,  OOP  techniques  cut  down  on 
debugging  and  testing  time.  By  mixing 
object-oriented  and  standard  program¬ 
ming,  Microsoft  produced,  in  a  short 
span  of  time,  a  user  interface  that  will 
be  easy  to  update  for  future  releases 
of  QuickPascal. 

Design  Considerations 

Good  OOP  design  uses  a  top-down 
approach  to  creating  programs.  Ob¬ 
jects  are  derived  from  general  classes, 


and  then  inheritance  is  used  to  create 
ever  more  specialized  child-class  ob¬ 
jects  for  special  purposes.  OOP’s  use 
of  inheritance  makes  code  reusable  and, 
as  a  result,  substantially  reduces  the 
size  of  programs.  OOP  techniques  re¬ 
duce  debugging  time  by  encouraging 
the  use  of  hundreds  of  small,  simple 
methods,  rather  than  a  few  large,  com¬ 
plex  procedures  or  functions  as  in  stan¬ 
dard  structured  programming. 

One  or  more  parent  classes  for  the 
application  reside  at  the  top  of  the  OOP 
design  hierarchy.  The  QuickPascal  user 
interface  uses  a  parent  window  class 
and  a  parent  event-handling  class.  These 
parent  classes  contain  the  information 
and  methods  basic  to  all  windows,  as 
well  as  information  about  the  event¬ 
handling  functions  of  the  user  inter¬ 
face.  The  inheritance  of  these  general 
qualities  and  actions  by  child  classes 
allows  the  building  of  all  the  objects 
needed  to  implement  a  consistent  user 
interface. 

Child  classes  inherit  the  properties 
of  their  parents  without  the  writing  of 
a  lot  of  additional  code.  Using  classes 
and  objects  also  streamlines  event  han¬ 
dling.  Window  environments  written 
in  classical  languages  usually  use  very 
large  CASE  statements  to  handle  all 
possible  events  for  each  window  type. 
Microsoft  Windows  applications,  for  ex¬ 
ample,  frequently  sport  CASE  statements 
with  a  dozen  or  more  elements.  An 
object-oriented  event  handler  lets  the 
different  window  types  inherit  all  the 
general  event  handling  characteristics 
of  their  parents,  and  only  adds  the  new 
code  needed  to  handle  special  events. 
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(continued  from  page  64) 

This  inheritance  usually  makes  code 
much  more  compact  and  efficient  than 
the  more  conventional  programming 
approach. 

However,  this  is  not  always  true.  A 
standard  OOP  event  handler  might  send 
a  “redraw  yourself’  message  to  a  win¬ 
dow  previously  covered  by  a  dialog 
box  or  pull-down  menu.  QuickPascal 
does  not  always  follow  this  standard 
approach  for  one  simple  reason  — 
speed.  Instead,  QuickPascal’s  event  han¬ 
dler  sometimes  stores  in  a  buffer  a  copy 
of  the  image  that  lies  underneath  the 
dialog  box.  When  the  dialog  box  dis¬ 
appears,  the  event  handler  transfers  the 
image  stored  in  the  buffer  back  onto 
the  screen. 

QuickPascal  uses  this  buffer-image  tech¬ 
nique  to  make  its  user  interface  more 
responsive.  Redrawing  an  image  from 
a  buffer  updates  only  the  portion  of  the 
screen  that  has  changed.  Telling  a  win¬ 
dow  object  to  redraw  itself  means  re¬ 
drawing  the  entire  image,  which  is  much 
more  time  consuming.  The  buffer-im¬ 
age  technique  is  an  “optimization”  of 
OOP  practice. 

This  optimization  addresses  the  few 
problems  that  result  from  using  OOP 
techniques.  If  creating  a  class  and  an 
associated  method  to  perform  a  task 
requires  more  bytes  or  machine  time 
than  a  standard  procedure,  sticking  with 
a  more  traditional  procedure  may  im¬ 
prove  a  program’s  performance. 

For  this  reason,  QuickPascal’s  user 
interface  does  not  use  objects  and  their 
associated  methods  to  the  exclusion 
of  standard  procedures.  Where  stan¬ 
dard  procedures  complete  a  task  with 
less  programming  overhead  than  a 
method,  QuickPascal’s  interface  uses 
conventional  procedures. 

The  Parent  Classes 

QuickPascal’s  user  interface  code  uses 
two  elementary  classes.  The  subclasses 
used  to  spawn  the  objects  that  com¬ 
prise  the  user  interface  are  derived  from 
these  classes.  One  parent  class  receives 
information  from  the  keyboard  and 
mouse  (input),  and  the  other  displays 
information  on  the  screen  (output). 
These  two  parent  classes  comprise  the 
top  of  the  class  hierarchy. 

The  primary  elements  of  these  classes 
include  event  handling  for  input,  and  a 
variety  of  windows,  dialog  boxes,  and 
menus  for  screen  output.  These  basic 
parts  interact  as  indicated  in  Figure  1. 

The  two  parent  classes  in  the  Quick¬ 
Pascal  environment  are  called  TWin- 
dow  and  TApplication.  These  names 
are  familiar  to  anyone  who  has  pro¬ 
grammed  in  Object  Pascal  or  with  the 
Macintosh’s  MacApp  class  library.  The 


T  in  these  class  names  means  “type,” 
and  is  a  naming  convention  established 
by  Apple  Computer.  The  TWindow  c\s^s 
and  its  descendants  handle  all  screen 
drawing,  including  windows,  menus, 
and  dialog  boxes.  The  TApplication 
class  and  its  children  interpret  keyboard 
and  mouse  events  and  send  them  to 
the  appropriate  window  object.  All  of 
the  code  classes  in  the  QuickPascal 
user  interface  devolve  from  these  par¬ 
ent  classes,  as  shown  in  Figure  2. 

The  TWindow  class  (see  Listing  One, 
page  126)  contains  variables  and  meth¬ 
ods  basic  to  all  window  functions.  These 
events  include  opening,  drawing,  mov¬ 
ing,  mounting,  unmounting,  printing, 
coloring,  scrolling,  responding  to  mouse 
events,  and  closing  windows.  Mount¬ 
ing  refers  to  bringing  a  window  to  the 
front  of  the  screen  and  making  it  the 


active  window. 

TWindow  serves  only  as  a  parent  to 
other  classes.  QuickPascal’s  user 
interface  code  declares  no  objects  di¬ 
rectly  from  TWindow.  TWindou/s  child 
classes  —  TDialogBox ,  TDocument,  T- 
MenuBar ,  and  TSubMenu  —  create  their 
own  distinct  types  of  windows,  and  all 
of  the  QuickPascal  interface  window 
objects  are  derived  from  these  child 
classes. 

The  TWindow  definition  contains 
mouse  handling  methods  that  are  com¬ 
prised  simply  of  BEGIN  and  END  state¬ 
ments.  The  child  classes  of  TWindow 
inherit  these  blank  methods  and  over¬ 
ride  them  with  their  own  mouse  han¬ 
dling  method  definitions.  This  poly¬ 
morphism  allows  a  TApplication  ob¬ 
ject  to  send  the  same  message  to  any 
TWindow  object  (described  shortly.) 


Figure  2:  The  QuickPascal  user  interface’s  object  family  tree 
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The  type  of  the  TWindow-derived  ob¬ 
ject  —  dialog  box,  document,  or 
menu  —  doesn’t  matter.  Each  of  these 
objects  specifies  how  to  deal  with  these 
mouse-event  messages. 

The  TWindow  Child  Classes 

Most  of  the  dialog  box  objects  used  by 
the  QuickPascal  user  interface  come 
from  the  TWindow  child  class  TDialog¬ 
Box.  This  child  class  inherits  all  the 
qualities  of  TWindow,  and  adds  new 
methods  for  drawing  buttons,  edit  fields, 
and  list  boxes  (see  Listing  Two,  page 
126).  It  stores  the  window’s  current 
state  (open,  closed,  waiting  for  input, 
and  so  on)  in  its  instance  variables. 

Because  the  QuickPascal  interface 
uses  some  specialized  dialog  boxes, 
several  other  child  classes  exist  to  deal 
with  those  selected  cases.  One  of  these 
child  classes  is  TFileDialogBox. 

While  inheriting  all  the  method  func¬ 
tionality  it  needs  from  TDialogBox ,  TFile- 
DialogBox  adds  two  more  instance  vari¬ 
ables.  These  variables  store  the  default 
and  current  document  extension  and 
the  path  to  the  current  directory.  These 
new  variables  make  the  file  dialog  box 
especially  convenient  to  use.  Without 
them,  a  user  would  have  to  reenter  the 
path  name  every  time  a  file  dialog  box 
opened,  and  the  default  document  ex¬ 
tension  would  always  be  the  same  re¬ 
gardless  of  the  most  recently  used  ex¬ 
tension. 

TPrintDialogBox  also  adds  instance 
variables  to  store  pointers  to  the  cor¬ 
rect  document  and  to  the  text  block 
location.  They  tell  QuickPascal  what 
window  to  print  from  and  what  text  to 
print  in  the  active  window. 

Help  dialog  boxes  use  TDialogBox! s 
methods,  but  need  instance  variables 
to  describe  the  help  topic  called  and 
to  indicate  the  help  page,  the  first  line 
of  the  page,  and  the  number  of  lines 
on  a  page. 

The  BP  in  TBPDialogBox  means 
“Break  Point.”  This  object  is  used  by 
QuickPascal  to  let  the  user  set  break 
points  in  the  code  they  are  editing.  The 
break  point  dialog  box  adds  three  in¬ 
stance  variables  to  the  ones  it  inherits 
from  TDialogBox.  The  additional  vari¬ 
ables  store  a  break  point  location,  the 
condition  on  which  to  halt  execution, 
and  the  type  of  break  point  (condi¬ 
tional  and  unconditional). 

Dialog  boxes  that  need  custom  key¬ 
board  and  mouse  actions  use  the  TModi- 
fyDialogBox  class.  Each  of  the  meth¬ 
ods  in  this  class  overrides  the  methods 
of  its  parent. 

TDocument  its  children  produce 
the  screen  items  traditionally  consid¬ 
ered  windows:  The  program  editing 
windows,  the  QuickPascal  Advisor  help 


window,  and  the  debug  window.  TDocu- 
ment  and  its  children  control  all  editing 
windows.  The  TDocument class  clearly 
shows  the  advantages  of  OOP.  It  greatly 
simplifies  the  moderately  complex  task 
of  creating  a  custom  text  editor.  TDocu¬ 
ment  builds  on  TWindouls  basic  ac¬ 
tions  by  adding  the  methods  necessary 

Good  OOP  design  uses 
a  top-down  approach 
to  creating  programs 


for  editing  text.  TDocuments  child 
classes  then  modify  the  editor  features 
they  inherit  to  suit  their  own  needs. 

The  TDocument  class  treats  docu¬ 
ments  (program  files,  help  files,  and 
others)  as  a  series  of  lines  made  up  of 
separate  characters.  TDocument  uses 
instance  variables  to  track  the  relevant 
data  about  a  document.  The  source 
code  for  TDocu  ment  demonstrates  how 
easy  it  can  be  to  design  a  custom  file 
format.  All  that’s  required  is  the  decla¬ 
ration  of  a  new  child  of  TDocument 
with  an  altered  data  structure.  Quick¬ 
Pascal  will  read  files  that  use  this  new 
structure  as  long  as  the  GetPhysLine 
method  still  returns  a  single  line  of  text. 

THelpWindow  is  identical  to  TDocu¬ 
ment  except  that  it  overrides  the 
GetPhysLine  method.  THelpWindoul s 
version  of  GetPhysLine  retrieves  data 
from  QuickPascal’s  help  (,HLP)  files. 

THelpWindow  also  makes  minor 
changes  to  the  GetChar  and  LeftMouse- 
Press  methods  to  keep  any  user  activi¬ 
ties  from  altering  the  contents  of  the 
help  screen.  All  other  window-related 
activities  function  normally. 

The  TEditWindow  class  describes 
QuickPascal’s  standard  editing  window, 
in  which  users  write  their  programs. 
The  methods  of  this  class  override  TDocu¬ 
ments  GetChar,  LeftMousePress,  and 
DrawScreen  methods.  This  class  in¬ 
cludes  three  new  methods,  which  take 
care  of  opening  files,  closing  files,  and 
saving  data  to  a  file. 

A  menu  bar  is  a  specialized  window. 
TMenuBar  inherits  all  of  TWindouls 
methods  without  modification,  with  one 
exception:  TMenuBar  alters  the  Draw- 
Window  method  to  handle  special 
Menu  cases,  such  as  graying  out  of 
menu  items  that  cannot  be  accessed, 
colors,  menu  text,  and  so  on.  TMenuBar 
also  uses  a  pointer  to  any  TMainAppli 
objects,  the  principal  object  perform- 
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(continued  from  page  66) 
ing  menu  management. 

A  submenu  is  the  pull-down  portion 
of  a  menu.  It  is  the  part  that  appears 
when  a  user  clicks  on  an  item  in  the 
menu  bar.  Like  TMenuBar ,  TSubMenu 
ovenides  the  DrawWindow  method  it 
inherits  from  TWindow.  It  also  uses  a 
pointer  to  an  object  of  type  TMain- 
Appli  to  obtain  other  menu  manage¬ 
ment  functions. 

The  TApplication  Children 

The  TApplication  class  is  a  good  exam¬ 
ple  of  a  parent  class  serving  as  the  basis 
for  other  classes.  QuickPascal’s  user 
interface  declares  objects  from  the  child 
classes  of  TApplication ,  but  does  not 
declare  any  objects  directly  from  TAp¬ 
plication  itself. 

When  a  window  object  of  the  TWin¬ 
dow  subclass  TDialogBox  (or  one  of  its 
descendants)  opens,  an  object  of  class 
TDialogBoxAppli  also  opens  to  handle 
events  within  a  dialog  box.  TDialogBox¬ 
Appli  overrides  its  inherited  GetEvents, 
HandleEvents,  and  DrawStatusLinemerh- 
ods  in  order  to  handle  events  special 
to  dialog  boxes.  TDialogBoxAppli  also 
adds  an  instance  variable  that  points 
to  the  type  of  dialog  box  created. 

Dialog  box  objects  from  both  win¬ 


dow  and  application  classes  exist  only 
as  long  as  the  dialog  box  remains  open. 
When  the  dialog  box  closes,  QuickPas- 
cal  disposes  of  both  objects. 

Telling  a  window  object 
to  redraw  itself  means 
redrawing  the  entire 
image 


Like  TApplication ,  TMainAppli  illus¬ 
trates  one  of  the  principles  of  good 
OOP  design.  TMainAppli  serves  pri¬ 
marily  as  a  foundation  for  its  child, 
EditAppli ,  but  remains  general  enough 
to  allow  for  easy  future  expansion.  If 
Microsoft  decides  to  add  another  type 
of  window  to  the  QuickPascal  user  in¬ 
terface,  TMainAppli  will  make  it  easy 
to  add  a  new  event  handling  class  for 
that  window. 

EditAppli  handles  the  bulk  of  the 
events  in  the  QuickPascal  environment. 


It  keeps  track  of  the  number  of  open 
windows,  plus  the  handle  of  the  active 
window,  and  watches  for  menu  activ¬ 
ity.  EditApplis  objects  work  with  the 
window  objects  for  TDocument, 
TMenuBar ;  and  TSubMenu.  EditAppli 
inherits  almost  all  its  methods  and  in¬ 
stance  variables  from  TMainAppli. 

Interacting  Objects 

TWindow  and  its  child  classes  work  in 
tandem  with  the  TApplication  classes. 
Every  TWindow-derived  object  has  a 
companion  TApplication-derived  ob¬ 
ject  that  handles  the  events  for  that 
window.  A  TApplication  object  can  be 
associated  with  more  than  one  TWin¬ 
dow  object.  TApplication  and  its  chil¬ 
dren  have  instance  variables  that  store 
mouse  events,  and  timer  events,  and 
the  current  state  of  the  keyboard.  The 
children’s  methods  acquire  and  dispatch 
these  various  events. 

TApplication’ s  child  classes  manage 
special  event  handling  features  (such 
as  TDialogBoxAppli  not  allowing  mouse 
clicks  outside  of  a  dialog  box).  TAppli¬ 
cation,  however,  has  methods  to  pro¬ 
cess  all  the  normal  user  activities  that 
occur  in  a  window  and  passes  those 
methods  on  to  its  child  classes  through 
inheritance. 


The  TApplication  classes  and  TWin¬ 
dow  classes  work  closely  together. 
When  QuickPascal  opens  and  initial¬ 
izes  a  new  TApplication- derived  object 
and  its  corresponding  TWindow-derived 
object(s),  the  methods  set  up  a  loop 
between  the  objects.  The  TApplication 
object’s  GetEvents  method  waits  until 
either  a  keyboard  or  mouse  event  oc¬ 
curs.  When  something  happens,  Get¬ 
Events  sets  its  instance  variables  and 
then  ends.  The  TApplication  object  then 
transfers  control  to  its  associated  TWin¬ 
dow  ob\ect,  activating  its  HandleEvents 
method.  The  TWindow-derived  object’s 
methods  (My  Window. LmousePress,  for 
example)  checks  the  state  of  the  win¬ 
dow’s  instance  variables  and  responds 
to  the  event  that  just  occurred.  This 
usually  results  in  a  call  back  to  one  of 
the  TWindow-derived  methods,  but  can 
also  mean  transferring  control  to  the 
compiler  or  to  some  other  activity. 

How  It  All  Works 

A  look  at  a  fragment  of  the  QuickPas¬ 
cal  interface  code  provides  a  glimpse 
into  this  object-oriented  universe.  List¬ 
ing  Three  (page  127)  shows  a  class 
definition,  an  instance  of  an  object, 
and  the  use  of  that  object  within  a 
Pascal  procedure.  The  first  part  of  List¬ 


ing  Three  illustrates  how  child  classes 
become  defined,  inheriting  behavior 
from  their  parent  classes  and  overrid¬ 
ing  the  methods  of  those  parents  where 
necessary. 

The  two  instances  of  EditWindow 
in  the  definition  of  class  EditWindow 
set  up  a  linked  list  of  edit  windows 
that  can  be  open  at  the  same  time. 
EditWindoio- class  objects  use  (among 
others)  the  OpenFile  method,  which 
specifies  what  happens  when  an  ob¬ 
ject  of  this  class  needs  to  open  a  file. 
OpenFile  names  the  object  of  type  Edit¬ 
Window  for  which  it  can  open  a  file  (in 
this  case,  Edit). 

As  the  code  fragment  in  Listing  Three 
shows,  a  class  is  first  defined  by  de¬ 
scribing  its  methods  and  naming  its 
instance  variables.  Next,  an  object  of 
that  class  is  created.  This  process  is 
similar  to  declaring  a  variable.  Then, 
some  memory  for  the  named  object  is 
allocated  using  the  New  keyword  and 
the  name  of  the  object.  Finally,  a  mes¬ 
sage  is  sent  to  the  object  by  calling  one 
of  its  methods  from  within  the  main 
body  of  a  program. 

Using  this  technique,  code  modules 
that  are  easy  to  debug  and  modify  can 
be  built.  The  internal  operation  of  an 
object  can  later  be  changed  without 
worrying  about  “breaking”  the  rest  of 


your  program  in  its  interaction  with  the 
changed  object.  Also,  new  versions  of 
existing  objects  can  be  created  by  de¬ 
fining  a  child  class  with  new  or  over¬ 
riding  methods.  The  building  blocks 
that  classes  and  objects  provide  make 
creating  programs  a  lot  less  risky  than 
it  used  to  be. 

Availability 

All  source  code  is  available  on  a  single 
disk  and  online.  To  order  the  disk, 
send  $14.95  (Calif,  residents  add  sales 
tax)  to  Dr.  Dobb’s Journal,  501  Galves¬ 
ton  Dr.,  Redwood  City,  CA  94063,  or 
call  800-356-2002  (from  inside  Calif.) 
or  800-533-4372  (from  outside  Calif.). 
Please  specify  the  issue  number  and 
format  (MS-DOS,  Macintosh,  Kaypro). 
Source  code  is  also  available  online 
through  the  DDJ  Forum  on  Compu¬ 
Serve  (type  GO  DDJ).  The  DDJ  Listing 
Service  (603-882-1599)  supports  300/ 
1200/2400  baud,  8-data  bits,  no  parity, 
1-stop  bit.  Press  SPACEBAR  when  the 
system  answers,  type:  listings  (lower¬ 
case)  at  the  log-in  prompt. 

DDJ 

(Listings  begin  on  page  126.) 

Vote  for  your  favorite  feature/article. 

Circle  Reader  Service  No.  5. 
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An  Object-Oriented 

Logic  Simulator 

Wire-wrapping  and  breadboarding  made  easy 


Kenneth  E.  Ayers 


As  a  bench  technician  in  a  re¬ 
search  and  development  labo¬ 
ratory,  my  primary  job  was  to 
build  prototype  circuits  with 
digital  logic  devices,  and  to 
make  sure  that  the  prototypes  worked. 

After  migrating  into  the  world  of  soft¬ 
ware,  I  saw  no  reason  why  my  com¬ 
puter  could  not  simulate  those  same 
digital  logic  circuits.  When  1  discov¬ 
ered  object-oriented  programming,  I  be¬ 
came  more  and  more  convinced  that  it 
was  both  possible  and  practical. 

The  project,  which  I  named  LogicLab, 
was  intended  from  the  start  to  simulate 
not  just  logic  devices,  but  the  complete 
bench  environment.  LogicLab  was  re¬ 
quired  to  provide  the  simulated  equiva¬ 
lent  of  four  aspects  of  that  environment: 

1.  A  well-stocked  parts  cabinet  con¬ 
taining  standard  integrated  circuit 
(IC)  devices  (74LS00,  and  so  forth); 

2.  A  method  to  connect  the  pins  of  the 
ICs  together  (commonly  called  a 
“breadboarding  system”); 

3.  A  source  of  signals  (clocks,  pulses, 
switches,  and  so  on)  that  could  be 
used  to  simulate  inputs  to  the  circuit; 

4.  A  logic  analyzer  that  I  could  use  to 
monitor  the  activity  within  my  cir¬ 
cuit  for  debugging  purposes. 


Ken  Ayers  is  a  self-educated  software 
engineer.  He  is  currently  employed  by 
Industrial  Data  Technologies  of  Wester¬ 
ville,  Ohio.  His  interests  include  com¬ 
puter  graphics,  machine  intelligence, 
and  OOP  systems.  He  can  be  reached 
at  7825  Larchwood  St.,  Dublin,  OH 
4301 7. 


At  first  glance,  these  four  simulations 
appear  simple.  If  implemented  prop¬ 
erly,  they  would  indeed  emulate  the 
workbench  environment.  But  when 
these  simulations  were  expanded  to 
the  level  of  detail  required  for  an  effec¬ 
tive  implementation,  the  task  seemed 
overwhelming. 

I  had  previously  considered  tackling 
this  project  with  a  combination  of  C 
and  assembly  language,  and  estimated 
that  the  time  required  to  produce  a 
prototype  in  those  languages  would 
be  about  8  to  12  months.  When  I  used 
Smalltalk  to  write  LogicLab,  I  had  a 
working  version  of  the  project  in  roughly 
100  hours!  I  spent  much  of  that  time 
learning  to  use  the  incredibly  complete 


environment  provided  with  Smalltalk/ 
V.  The  environment  includes  more  than 
100  classes  and  some  2000  methods, 
and  source  code  is  provided  for  every¬ 
thing  (except  the  compiler  itself!).  After 
building  the  prototype,  I  invested  an¬ 
other  150  (or  so)  hours  on  the  project 
in  order  to  give  LogicLab  a  major  over¬ 
haul  that  improved  both  performance 
and  the  user  interface. 

A  Glance  Inside  LogicLab 

The  heart  of  LogicLab  —  the  simula¬ 
tion  kernel  —  is  shown  in  Listing  One 
(page  130).  The  system  also  includes 
more  than  20  object  classes.  Nearly  all 
of  these  object  classes  correspond  di¬ 
rectly  to  real-life  counterparts  on  the 
design  bench.  Some  of  the  typical  simu¬ 
lated  devices  are  a  toggle  switch  (List¬ 
ing  Two,  page  136),  a  pulser  switch 
(Listing  Three,  page  136),  and  a  logic 
device  (Listing  Four,  page  137).  Other 
simulated  devices  include  buttons, 
switches,  logic  probes,  input  signals,  a 
logic  analyzer,  and  an  assortment  of 
logic  devices.  A  list  of  the  class  hierar¬ 
chy  for  LogicLab  is  given  in  Figure  1. 
Figure  2  shows  a  typical  display  pro¬ 
duced  by  LogicLab’s  logic  analyzer. 

LogicLab  is  organized  into  two  dis¬ 
crete  application  phases.  The  first  phase 
is  the  breadboard.  In  this  phase,  the 
user  installs  devices  into  the  circuit  and 
makes  the  connections  between  pins. 
This  process  is  very  similar  to  the  pro¬ 
cess  of  wire-wrapping,  and  is  driven  by 
a  series  of  pop-up  menus  and  prompts 
for  device  names  and  pin  numbers. 

The  second  application  phase  in  Logic- 
(continued  on  page  75) 
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Lab  is  the  logic  analyzer.  In  a  hardware 
workbench  environment,  the  logic  ana¬ 
lyzer  is  used  as  a  testing  and  debugging 
tool.  The  logic  analyzer  has  a  number 
of  probes  (LogicLab’s  logic  analyzer 
has  eight  probes)  that  can  be  connected 
to  various  points  in  the  circuit  (usually 
to  pins  on  ICs).  While  the  circuit  is 
operating,  the  logic  analyzer  records 
and  displays  the  states  monitored  by 
each  probe.  The  output  is  a  timing 
diagram  that  illustrates  the  relationships 
between  signals  in  the  circuit.  A  techni¬ 
cian  uses  this  information  to  determine 
if  the  circuit  is  functioning  properly.  If 
the  circuit  is  not  functioning  properly, 
this  information  is  used  to  identify  where 
a  problem  (a  bug!)  might  be  found. 

Because  LogicLab  is  a  simulation, 
the  process  of  using  the  logic  analyzer 
is  handled  a  little  bit  differently  than 
in  a  hardware  circuit.  LogicLab  simu¬ 
lates  time  in  discrete  steps.  In  essence, 
LogicLab  examines  all  of  the  IC  input 
pins  and  calculates  the  corresponding 
output  states.  After  LogicLab  completes 
the  calculation,  it  pretends  that  one 
nanosecond  (a  billionth  of  a  second) 
has  passed,  and  then  repeats  the  pro¬ 
cess. 

Between  nanoseconds,  LogicLab  per¬ 
forms  housekeeping  chores  —  such  as 
updating  the  timebase,  recording  the 
states  at  the  probes,  and  updating  the 
timing  diagram  display. 

The  State  Connection 

One  object  class  —  theLogicNode  class  — 
performs  the  majority  of  the  work  dur¬ 
ing  a  simulation.  This  class  simulates 
the  electrical  connections  within  a  cir- 
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Figure  1:  LogicLab’s  class  hierarchy 
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cuit.  Each  pin  of  a  simulated  logic  de¬ 
vice  (most  devices  have  14, 16,  or  more 
pins)  is  associated  with  a  LogicNode; 
each  input  signal  has  a  LogicNode;  and 
the  private  data  for  each  switch  or  push¬ 
button  device  includes  a  LogicNode. 

The  LogicNode  class  is  a  good  ex¬ 
ample  to  use  for  demonstrating  the  close 
correspondence  between  physical  ob¬ 
jects  and  their  software  counterparts. 
Figure  3  shows  the  conceptual  organi¬ 
zation  of  pins  on  an  IC. 

A  characteristic  of  hardware  logic  de¬ 
vices  is  that  a  change  in  an  input  signal 
requires  a  finite  amount  of  time  before 
the  corresponding  change  appears  at 
the  output.  This  delay  is  known  as  the 
“propagation  delay.”  The  length  of  the 
propagation  delay  is  determined  by  ex¬ 
amining  the  specifications  (data  sheets) 
for  a  particular  type  of  device. 

In  a  hardware  logic  device,  the  propa¬ 
gation  delay  occurs  within  the  logic 
elements  (transistors,  diodes,  and  so 
forth)  inside  the  device.  Because  of 
different  signal  path  lengths  within  an 
IC,  the  propagation  delay  at  an  output 
can  often  differ,  based  upon  which 
input  signal  is  present.  (For  example, 
in  a  typical  flip-flop,  the  delay  from  the 
reset  input  to  the  data  output  is  differ¬ 
ent  than  the  delay  from  the  clock  input 
to  the  data  output.) 

To  accommodate  this  phenomenon, 


I  have  modeled  the  propagation  delay 
as  an  integral  part  of  the  electrical  con¬ 
nection  rather  than  as  a  part  of  the 
device.  When  a  new  IC  object  is  cre¬ 
ated,  each  of  its  pins  is  assigned  a  delay 
value  by  the  initialization  method  for 
that  device  class. 

Each  LogicNode  maintains  a  record 
of  both  its  internal  and  its  external  state. 
In  this  case,  the  “external  state”  is  the 
(high  or  low)  state  that  actually  ap¬ 
pears  at  the  pin  of  the  device.  The 
“internal  state”  is  the  state  that  is  pre¬ 
sent  at  the  logical  elements  of  the  de¬ 
vice.  Each  LogicNode  also  keeps  a  rec¬ 
ord  of  its  most  recent  internal  state. 
This  extra  state  record  is  essential  to 
the  simulation  of  edge-triggered  de¬ 
vices,  such  as  flip-flops  and  counters. 

In  the  case  of  LogicNodes  that  are 
associated  with  output  pins,  a  change 
in  the  internal  state  (as  the  result  of  a 
logical  computation)  triggers  a  propa¬ 
gation  delay  counter.  If  the  internal 
and  external  states  are  still  different 
when  the  counter  reaches  zero,  the 
internal  state  appears  at  the  output  — 
that  is,  the  internal  state’s  value  is  stored 
in  the  node’s  external  state  variable. 
During  each  simulation  cycle,  an  out¬ 
put  state  is  broadcast  to  all  other  nodes 
to  which  that  node  is  connected. 

This  brings  us  to  another  point.  An 
isolated  IC  pin  is  of  little  use.  An  IC  pin 
must  be  connected  to  other  pins,  input 
signals,  or  output  devices  in  order  to 


Figure  2:  A  typical  display  produced  by  LogicLab’s  logic  analyzer 
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(continued  from  page  76) 
perform  a  useful  function.  Each  of  Logic- 
Lab’s  simulated  pins  maintains  a  list  of 
the  other  LogicNodes  that  form  its  con¬ 
nection  chain.  The  node’s  private  data 
contains  the  identity  of  its  successor 
and  its  predecessor  nodes.  This  infor¬ 
mation  allows  an  output  pin  to  access 
all  of  the  input  pins  that  are  affected 
by  the  output  pin’s  signal. 

Listing  Five  (page  138)  is  the  source 
code  for  the  output  method  imple¬ 
mented  in  the  LogicNode  class.  This 
method  detects  changes  in  the  node’s 
internal  state,  times  the  propagation 
delay,  and  broadcasts  the  current  ex¬ 
ternal  state  along  the  node’s  connec¬ 
tion  chain.  The  output  method  is  in¬ 
voked  at  each  simulation  cycle,  once 
per  simulated  nanosecond. 

Putting  It  All  Together 

Ultimately,  LogicLab  simulates  a  cir¬ 
cuit.  Somewhere  along  the  line,  it  must 
simulate  logic  devices.  Listing  Six  (page 
138)  is  the  simulation  method  found 
in  the  class  N74LS00.  A  hardware  74LS00 
device  is  commonly  known  as  a  “Quad 
2-Input  NAND  gate.”  This  name  indi¬ 
cates  that  a  single  IC  in  this  device 
contains  four  logic  gates.  The  output 
of  each  gate  is  determined  by  logically 
ANDing  two  inputs  and  then  negating 


Figure  4:  Divide-by-three  counter 


that  operation  —  hence  the  name  “NOT- 
AND,”  or  “NAND.” 

The  primary  characteristic  of  this  type 
of  gate,  which  is  exploited  by  the  simula¬ 
tion,  is  that  its  output  is  low  only  when 
both  inputs  are  high. 

In  LogicLab,  one  of  the  variables  in 
each  logic  device  is  an  array  of  Logic- 
Nodes.  In  Listing  Six,  the  statement  (pins 
at:  1)  isHigh  fetches  the  LogicNode 
from  the  first  element  of  the  device’s 
pins  array.  The  message  isHigh  is  then 
sent  to  that  LogicNode.  In  response  to 
the  isHigh  message,  the  LogicNode  re¬ 
turns  either  a  true  or  false  value,  de¬ 
pending  upon  whether  the  node’s  in¬ 
ternal  state  is  high  or  low. 

Most  simple  logic  gates  can  be  simu¬ 
lated  in  a  similar  manner.  More  com¬ 
plex  functions,  such  as  flip-flops  and 
counters,  can  also  be  simulated  in  the 
same  general  way  as  long  as  you  rec¬ 
ognize  that  latched  devices  must  re¬ 
member  their  previous  state  between 
simulation  cycles. 

As  a  test  of  LogicLab’s  ability  to  simu¬ 
late  an  actual  circuit,  I  breadboarded 
the  simple  divide-by-three  counter 
shown  in  Figure  4.  The  timing  diagram 
that  is  expected  from  this  circuit  is 
shown  below  the  schematic.  Compare 
this  timing  diagram  to  the  timing  dia¬ 
gram  in  Figure  2,  which  was  produced 


by  LogicLab’s  simulation  of  the  circuit. 
The  primary  difference  between  the 
two  timing  diagrams  is  the  length  of 
the  propagation  delays  between  inputs 
and  outputs. 

Objects  Pay  Big  Dividends 

This  project  demonstrated  to  me,  be¬ 
yond  any  doubt,  the  value  of  using  an 
object-oriented  programming  system  to 
construct  a  simulation.  The  ability  to 
construct  objects  by  using  their  physi¬ 
cal  counterparts  as  models  meant  that 
I  was  able  to  work  within  a  familiar 
framework  —  I  already  knew  the  rela¬ 
tionships  between  logic  devices,  sig¬ 
nals,  logic  probes,  and  analyzers.  Small¬ 
talk  let  me  express  those  relationships 
essentially  intact.  Other  languages 
would  have  required  me  to  translate 
those  relationships  into  a  more  rigid 
and  less  expressive  form.  Smalltalk’s 
integrated,  fully  interactive  development 
environment  also  assisted  me  at  every 
step  and  let  me  produce  the  prototype 
with  relative  ease. 

The  only  drawback  to  Smalltalk  is  its 
performance.  Not  only  is  Smalltalk  an 
interpreted  language,  but  the  overhead 
associated  with  message  sends  inflicts 
a  significant  penalty  upon  run-time  per¬ 
formance.  The  end  result  is  that  Logic¬ 
Lab  requires  approximately  one  sec¬ 
ond  of  real  time  for  every  ten  nano¬ 
seconds  of  simulated  time.  Blazing 
speed  is  not  this  simulator’s  claim  to 
fame!  But  the  slow  run-time  perfor¬ 
mance  is  easily  overlooked,  once  you’ve 
experienced  firsthand  the  ease  with 
which  Smalltalk  lets  you  transform  ideas 
into  functional  extensions  of  the  envi¬ 
ronment  itself. 

Availability 

All  source  code  is  available  on  a  single 
disk  and  online.  To  order  the  disk, 
send  $14.95  (Calif,  residents  add  sales 
tax)  to  Dr.  Dobb’s Journal,  501  Galves¬ 
ton  Dr.,  Redwood  City,  CA  94063,  or 
call  800-356-2002  (from  inside  Calif.) 
or  800-533-4372  (from  outside  Calif.). 
Please  specify  the  issue  number  and 
format  (MS-DOS,  Macintosh,  Kaypro). 
Source  code  is  also  available  online 
through  the  DDJ  Forum  on  Compu¬ 
Serve  (type  GO  DDJ).  The  DDJ  Listing 
Service  (603-882-1599)  supports  300/ 
1200/2400  baud,  8-data  bits,  no  parity, 
1-stop  bit.  Press  SPACEBAR  when  the 
system  answers,  type:  listings  (lower¬ 
case)  at  the  log-in  prompt. 

DDJ 

(Listings  begin  on  page  130.) 
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Are  the 

Emperor's  New  Clothes 

Object  Oriented  ? 

Some  down-to-earth  questions  about  programming’s  latest 

high-flying  fad 


Scott  Guthery 


A  large  number  of  sweeping 
claims,  particularly  with  respect 
to  programmer  productivity 
and  code  reuse,  are  being  made 
for  object-oriented  program¬ 
ming  (OOP),  many  of  them  by  firms 
that  are  in  the  business  of  making  and 
selling  object-oriented  programming 
tools.  Before  we  bet  a  real  program¬ 
ming  project  on  this  freshly  sewn  tech¬ 
nology,  we’d  like  to  ask  some  ques¬ 
tions  about  object-oriented  program¬ 
ming  just  to  make  sure  the  emperor’s 
new  clothes  are  really  as  fine  as  these 
tailors  claim. 

Where's  the  Evidence? 

In  scientific  and  engineering  disciplines  — 
besides  computer  science  and  program¬ 
ming  —  we  accumulate  experience, 
gather  evidence,  and  conduct  experi¬ 
ments,  which  we  then  generalize  to 
make  claims.  If  one  doubts  the  claims 
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and  statistics  from  Michigan  State  Uni¬ 
versity  and  he  has  been  programming 
since  1957.  He  can  be  reached  through 
Internet:  @guthery  asc.slb.com. 


one  is  invited  to  reanalyze  the  data  and 
replicate  the  experiments.  For  some 
strange  reason,  programmers  have  a 
history  of  accepting  claims  blindly  with¬ 
out  asking  for  proof.  Hope  springs  eter¬ 
nal,  I  guess,  and  dire  need  grasps  any 
straw.  To  my  knowledge  there  has  been 
absolutely  no  evidence  gathered  or 
experiments  performed  to  validate  the 
claims  made  for  object-oriented  pro¬ 
gramming,  particularly  for  object-ori¬ 
ented  programming  in  the  large. 

The  biggest  OOP  projects  undertaken 
to  date  seem  to  be  the  OOP  develop¬ 
ment  systems,  and  the  news  from  this 
front  is  not  all  good  [Harrison,  19891. 
But  OOP  isn’t  supposed  to  be  an  end 
in  itself.  Esperanto  was  wonderful  for 
writing  books  about  Esperanto  but  not 
much  else.  If  you  want  to  write  an  OOP 
system,  then  OOP  is  probably  just  the 
thing.  But  if  you  want  to  write,  say,  an 
accounting  system  or  a  reservation  sys¬ 
tem  using  OOP  you’re  going  where 
no  man  or  woman  has  gone  before.  In 
fact,  you’ll  be  performing  on  yourself 
the  very  experiments  that  the  OOP  ped¬ 
dlers  should  have  performed  to  sub¬ 
stantiate  their  claims.  Would  you  ac¬ 
cept  this  situation  if  OOP  were,  for 
example,  a  new  surgical  procedure? 

What  is  an  Object? 

The  atomic  element  of  object-oriented 


programming  is,  not  surprisingly,  the 
object.  But  what  is  an  object?  The  51 
papers  in  the  IEEE  “Tutorial  on  Object- 
Oriented  Computing”  by  Gerald  Peter¬ 
son  [Peterson,  1987]  contain  many  defi¬ 
nitions  and  descriptions  of  an  object. 
These  definitions  come  in  two  basic 
flavors.  One  flavor  talks  about  model¬ 
ing  reality  and  the  other  talks  about 
encapsulated  collections  of  program¬ 
ming  tricks. 

Stripped  of  its  fancy  jargon,  an  ob¬ 
ject  is  a  lexically-scoped  subroutine  with 
multiple  entry  points  and  persistent  state. 
Object-oriented  programming  has  been 
around  since  subroutines  were  invented 
in  the  1940s.  Objects  were  fully  sup¬ 
ported  in  the  early  programming  lan¬ 
guages  AED-0,  Algol,  and  Fortran  II. 
OOP  was,  however,  regarded  as  bad 
programming  style  by  Fortran  aficiona¬ 
dos.  As  Admiral  Grace  Hopper  has  so 
often  observed,  we  don’t  actually  do 
anything  new  in  computing  we  just 
rename  the  old  stuff.  Admiral  Hopper 
(at  the  time  Lt.  Hopper)  was  doing 
object-oriented  programming  on  the  Har¬ 
vard  Mark  I  in  1944  and  probably  didn’t 
even  know  it. 

Unfortunately,  we  have  completely 
ignored  Rentsch’s  1982  plea  [Rentsch, 
1982]:  “Let  us  hope  that  we  have  learned 
our  lesson  from  structured  program¬ 
ming  and  find  out  what  the  term  means 
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before  we  start  using  it.”  C++  was  first 
described  in  April,  1980  [Stroustrup, 
1980],  Over  nine  years  later  an  incompat¬ 
ible  Version  2.0  has  just  been  released. 
The  definition  of  C++  still  isn’t  com¬ 
plete.  Can  anything  that’s  this  hard  to 
define  be  good  for  writing  understand¬ 
able  and  maintainable  programs?  And 
if  you  think  it’s  hard  to  pin  down  the 
definition  of  an  object,  just  try  drawing 
a  bead  on  the  definition  of  the  inheri¬ 
tance  links  that  connect  objects. 

What's  the  Cost  of  OOP  Code  Reuse? 

One  of  the  primary  claims  of  object- 
oriented  programming  is  that  it  facili¬ 
tates  the  reuse  of  code.  Does  it?  And  if 
so,  at  what  cost? 

The  unit  of  reuse  in  object-oriented 
programming  is  the  hierarchy.  It  is  the 
hierarchy  and  not  the  object  that  is 
the  indivisible  whole.  Unlike  a  subrou¬ 
tine  library  where  you  can  just  take 
what  you  need  and  no  more,  in  object- 
oriented  programming  you  get  the 
whole  gorilla  even  if  you  just  wanted 
the  banana. 

The  problem  is  that  hierarchies  are 
nonmodular.  You  can’t  just  clip  the 
objects  you  want  to  reuse  out  of  the 
hierarchy  because  you  don’t  know  (in 
fact,  aren’t  supposed  to  know)  how  the 
objects  are  entangled  in  the  hierarchy. 
So,  the  cost  of  OOP-style  code  reuse 
seems  to  be  that  you  must  (re)use  a  lot 
more  code  than  you  want  or  need. 
Your  system  will  be  bigger,  run  slower, 
and  cost  more  to  maintain  than  with 
subroutine-style  reuse.  Though  .there 
may  be  situations  in  which  the  conven¬ 
ience  of  the  programmer  so  completely 
outweighs  the  interests  of  the  users 
and  the  interests  of  the  maintainers, 
I’ve  never  seen  one. 

How  to  Combine  Object  Hierarchies? 

If  object  hierarchies  need  to  be  small  to 
control  the  cost  of  their  reuse  then  you 
must  be  able  to  get  many  of  them  to 
work  together  when  you  build  your 
program.  You  may,  for  instance,  want 
to  use  a  polynomial  approximation  hi¬ 
erarchy,  a  linked  list  hierarchy,  a  com¬ 
munication  hierarchy,  an  indexed  rec¬ 
ord  hierarchy,  a  pop-up  menu  hierar¬ 
chy,  and  a  ray-tracing  hierarchy  all  at 
once. 

But  how  do  you  combine  object  hi¬ 
erarchies?  Can  objects  in  a  C++  mathe¬ 
matics  hierarchy  send  arguments  to  ob¬ 
jects  in  an  Objective-C  ray-tracing  hier¬ 
archy?  Sadly,  no.  What’s  worse  is  that 
you  can’t  even  send  arguments  from 
one  C++  hierarchy  to  another.  There 
are  neither  in  theory  nor  in  practice 
any  OOP  hierarchy  combiners. 

It  is  left  as  an  exercise  for  the  OOP 
programmer  to  “impedance  match” 
not  only  between  OOP  technologies 
but  between  OOP  hierarchies  within 
a  technology.  This  means  doing  ex¬ 
actly  what  you  were  told  you  wouldn’t 


have  to  do;  open  up  the  objects  and 
program  with  respect  to  representa¬ 
tion  of  the  state  inside.  The  object- 
oriented  programmer  must  map  from 
one  internal  representation  to  another. 
There  is,  after  all,  no  reason  to  suspect 
that  one  hierarchy’s  internal  represen¬ 
tation  of  a  compound  object  such  as 
a  matrix  or  a  picture  is  anything  like 
another’s.  This  clearly  defeats  one  of 
the  main  advertised  benefits  of  object- 
oriented  programming:  Namely,  hid¬ 
den  internal  representation.  What  you 
may  have  saved  by  not  having  to  write 
code  for  objects  in  the  same  hierar¬ 
chy,  you  now  must  spend  as  you  write 
code  to  map  between  objects  in  dif¬ 
ferent  hierarchies. 

One  of  the  few  things  that  we  have 
learned  (again  and  again)  over  the 
last  40  years  of  programming  is  that 
the  hard  part  isn’t  getting  code  frag¬ 
ments  to  work.  The  hard  part  is  get¬ 
ting  them  to  work  together.  The  name 
of  the  game,  particularly  when  it  comes 
to  code  reuse,  is  integration  at  scale. 
Object-oriented  programming  makes 
building  code  fragments  easier,  but  it 
makes  integration  much  more  diffi¬ 
cult.  Making  the  easy  parts  easier  but 
the  hard  parts  harder  is  not  progress 
by  my  lights. 

How  to  Tune  on  Object-Oriented 
Program? 

Has  any  program  you've  ever  written 
been  too  fast  or  even  fast  enough?  What 
do  you  do  if  your  object-oriented  pro¬ 
gram  isn’t  fast  enough?  How  do  you 
performance  tune  an  object-oriented 
program?  Indeed,  how  do  you  even 
answer  the  question,  "Where  is  the  pro¬ 
gram  spending  its  time?” 

It’s  just  possible  you’ll  find  yourself 
spending  lots  of  time  in  one  or  two  of 
your  own  methods  and  can  work  on 
making  those  methods  faster  using  clas¬ 
sic  techniques.  But  it’s  much  more  likely 
that  you’ll  find  you’re  spending  more 
time  than  you  care  to  running  around 
the  hierarchy. 

There  is  only  one  thing  you  can  do: 
Rearchitect  and  reorganize  the  hierar¬ 
chy  itself  to  make  it  more  efficient  and 
to  take  into  account  the  way  you  want 
to  use  it.  The  semantics  of  the  hierar¬ 
chy  thus  become  a  twisted  combina¬ 
tion  of  the  descriptive  reality  that  the 
objects  came  from  and  the  profile  of 
the  use  your  procedural  code  makes  of 
them.  This  is  not  an  attractive  prospect. 

The  problem  here,  of  course,  is  that 
while  the  semantics  of  classic  program¬ 
ming  languages  match  the  semantics 
of  the  underlying  hardware,  the  se¬ 
mantics  of  object-oriented  languages 
do  not.  When  using  classic  languages 
like  C  or  Fortran,  if  you  couldn’t  bind 
the  problem  to  the  hardware  tightly 
enough  to  get  the  performance  you 
needed,  you  could  make  this  binding 
tighter  yet  by  resorting  to  assembly  lan¬ 


guage  or  even  microcode.  You  can’t  do 
this  with  an  object-oriented  program 
because  you  can’t  get  at  the  virtual 
machine  that  implements  the  semantics 
of  these  languages.  They’re  all  hidden 
away  from  you  in  the  vendor’s  com¬ 
piler  and  runtime  library. 

Once  again,  the  programmer  is  be¬ 
ing  invited  to  pass  the  cost  of  expedi¬ 
ence  onto  the  user  of  the  system.  The 
additional  cost  of  supporting  a  runtime 
OOP  virtual  machine  can  vary  from  as 
little  as  50  percent  [Thomas,  19891  to 
as  much  as  500  percent  of  the  cost  of 
a  non-OOP  version  of  the  system.  This 
wholesale  sacrificing  of  runtime  effi¬ 
ciency  to  programmer’s  convenience, 
this  emphasis  on  the  ease  with  which 
code  is  generated  to  the  exclusion  of 
the  quality,  usability,  and  maintainabil¬ 
ity  of  that  code,  is  not  found  in  any 
production  programming  environment 
with  which  I  am  familiar. 

Finally,  before  we  leave  the  topic  of 
hardware,  let’s  not  forget  the  Intel  432. 
The  432  was  OOP  in  silicon  and  it 
failed  because  it  was  just  too  slow.  If 
we  couldn’t  make  OOP  efficient  when 
we  implemented  it  in  hardware  why 
do  we  think  we  can  make  it  efficient 
when  we  emulate  it  in  software? 

How  to  Manage  the  OOP  Development 
Team? 

Real  programs  are  built  by  large  pro¬ 
gramming  teams,  not  by  individuals  or 
small,  closely  knit  cliques.  Because  we 
certainly  don’t  want  to  imagine  that 
every  programmer  on  a  project  builds 
his  or  her  own  private  object  hierarchy, 
we  are  faced  with  the  prospect  of  many 
programmers  working  on  the  same  tree. 
Given  something  as  flexible  as  an  ob¬ 
ject  to  work  with,  it  is  almost  certain 
that  each  programmer  working  on  the 
tree  will  want  to  implement  a  different 
vision  of  the  reality  that  the  tree  is 
attempting  to  capture. 

One  possibility  is  to  appoint  an  ob¬ 
ject  “czar,”  the  direct  analogy  of  a  data¬ 
base  administrator.  Databases  need  to 
be  stable,  so  appointing  an  administra¬ 
tor  to  watch  over  the  database  schema 
and  carefully  coordinate  changes  to  it 
makes  good  software  engineering  sense. 
Object  hierarchies,  on  the  other  hand, 
are  deliberately  not  stable;  the  hierar¬ 
chy  is  the  program  after  all  and  it’s  the 
program  that  we’re  developing.  Imag¬ 
ine  having  to  ask  the  permission  of  the 
subroutine  czar  every  time  you  wanted 
to  write  a  subroutine. 

What  really  happens?  What  I’ve  seen 
in  three  large  (7000+  objects)  OOP  pro¬ 
jects  is  that  because  everyone  is  trying 
to  get  his  or  her  job  done  with  a  mini¬ 
mal  number  of  dependencies  on  ev¬ 
eryone  else,  subtrees  and  subrealities 
spring  up  all  over  the  place  and  new 
objects  and  new  methods  sprout  like 
weeds.  There  was  an  object  in  one  of 
these  systems  which  when  printed  went 
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on  for  80  pages.  One  also  finds  lots  of 
little  private  languages  for  communi¬ 
cating  between  these  subrealities. 

Of  course,  good  communication  be¬ 
tween  the  team  members  can  attenuate 
the  growth  of  some  of  this  gratuitous 
complexity.  But,  in  projects  on  tight 
schedules  with  programmers  removed 
from  one  another  in  time,  space,  and 
organization,  predicating  success  on 
good  communication  adds  more  risk 
to  an  already  risky  undertaking. 

Another  distressing  property  of  these 
multi-programmer  hierarchies  is  that 
they’re  difficult  to  debug.  If  there  is  one 
overarching  flaw  in  OOP,  it’s  debug¬ 
ging.  As  was  noted  recently  in  the  OOP 
newsgroup  on  USENET,  “It  has  been 
discovered  that  C++  provides  a  remark¬ 
able  facility  for  concealing  the  trivial 
details  of  a  program  —  such  as  where 
the  bugs  are.” 

While  we’re  passing  through  this  anal¬ 
ogy  with  database  management  sys¬ 
tems,  recall  that  one  of  the  raison  d’ette 
for  DBMSs  was  the  separation  of  data 
and  program.  Now,  along  comes  OOP 
and  we’re  told  that  mixing  data  and 
program  is  the  right  thing  to  do  after 
all.  Were  we  wrong  then  or  are  we 
wrong  now? 

Do  Object-Oriented  Programs  Coexist? 

We  have  gotten  used  to  mixing  lan¬ 
guages  in  our  programs.  This  is  indus¬ 
trial-strength  code  reuse  in  action;  if 
you  can’t  access  it  at  will,  you  can’t 
reuse  it.  You  don’t  have  to  rewrite  a 
Fortran  subroutine  into  C  to  use  it  in  a 
C  program,  you  just  call  it.  Common 
or  at  least  coercible  calling  conventions 
and  a  uniform  linking  model  have  made 
this  possible.  One  of  the  many  reasons 
that  Lisp  has  failed  as  a  programming 
language  is  that  Lisp  is  a  language  loner. 

How  about  object-oriented  lan¬ 
guages?  Can  you  mix  Objective-C,  Eif¬ 
fel,  CLOS,  Actor,  Owl,  and  C++  objects 
in  a  tree?  Not  on  your  tintype.  Object 
hierarchies  are  isolated  bunker  realities 
just  like  the  language  technologies  that 
implement  them. 

We  have  learned  that  there  is  no 
all-singing,  all-dancing  anything  in  com¬ 
puting.  No  one  language,  no  one  com¬ 
munication  protocol,  no  one  operating 
system,  no  one  graphics  package — no 
one  anything  is  always  right  all  the 
time  everywhere.  We  have  learned  again 
and  again  that  closed  systems  are  los¬ 
ers.  Successful  systems  have  one  thing 
in  common  —  they  can  coexist  peace¬ 
fully  and  gracefully  with  other  systems. 
Object-oriented  programming  does  not 
currently  have  this  property,  either  in 
concept  or  in  practice.  If  by  “reuse” 
OOP  advocates  really  mean  “reuse 
when  the  whole  world  is  just  like  me” 


then  this  is  not  reuse  in  any  practical 
or  useful  sense. 

What  are  the  Consequences  of 
Persistent  State? 

Persistent  state  means  that  data  obtained 
from  an  object  cannot  be  used  inde¬ 
pendently  of  that  object.  It  means  that 
the  very  act  of  obtaining  a  value  invali¬ 
dates  all  other  previously  obtained  val¬ 
ues.  Programmatically,  this  means  that 
every  time  you  want  to  use  a  value  you 
have  to  retrieve  it  from  the  hierarchy. 
It  is  a  programming  error  to  make  a 
local  copy  of  a  value.  Hierarchy  chas¬ 
ing  and  the  inheritance  machinery  are 
not  only  in  the  inner  loop  of  every 
orthodox  object-oriented  program,  they 
are  part  and  parcel  of  every  use  of 
every  value  in  the  program. 

But,  persistent  state  isn’t  only  a  per¬ 
formance  issue.  It  is  much  more  impor¬ 
tantly  a  data  consistency  issue.  The  only 
correct  way  to  get  two  or  more  consis¬ 
tent  values  from  an  object  hierarchy  is 
to  get  them  together  in  one  package 
in  one  response  to  one  query.  This  is 
the  only  way  you  can  be  assured  that 
they  are  consistent  each  with  the  other. 
Not  only  have  I  not  seen  any  discus¬ 
sion  of  this  property  of  OOP,  I  have 
seen  example  object-oriented  programs 
that  don’t  understand  the  consequences 
of  persistent  state  and  simply  assume 
consistency  between  values  obtained 
serially.  Without  explicit  assurances  from 
the  designers  of  the  hierarchy  in  use, 
this  is  an  error. 

There  was  a  very  good  reason  why 
persistent  state  was  regarded  as  bad 
Fortran  programming  style  —  it’s  a  se¬ 
mantic  mine  field.  Why  do  we  have  to 
completely  rediscover  the  principles  of 
good  programming  with  each  new  pro¬ 
gramming  language  and  paradigm  we 
invent?  In  all  but  very  restricted  and 
tightly  controlled  situations  experience 
has  shown  that  persistent  state  should 
be  avoided.  For  those  who  haven’t  taken 
a  stroll  in  this  mine  field,  object-ori¬ 
ented  programming  offers  the  oppor¬ 
tunity  to  avoid  reusing  other’s  experi¬ 
ence  and  learn  for  themselves.  As  with 
modularity  and  the  separation  of  pro¬ 
grams  and  data,  OOP  seems  content 
to  simply  ignore  what  we  have  learned 
in  40  years  of  programming. 

Can  You  Get  the  Development  System 
Out  of  the  Production  System? 

A  common  failing  of  many  program¬ 
ming  aids  such  as  OOP  is  that  you  can’t 
get  rid  of  them  when  you’re  done  with 
them.  They’re  like  training  wheels  on 
a  bicycle  except  you  can’t  take  them 
off  when  you’ve  learned  to  ride.  Pro¬ 
gramming  languages  such  as  Lisp  and 
methodologies  such  as  OOP  are  par¬ 


ticularly  painful  because  they  are  based 
on  a  virtual  machine  that  sits  between 
you  and  the  real  machine.  The  virtual 
machine  is  a  nice  warm-fuzzy  to  have 
during  development  but  we  simply 
can’t  afford  to  have  it  in  our  production 
systems. 

Structured  programming  was  such  a 
success  because  you  got  all  the  bene¬ 
fits  of  enhanced  software  productivity 
without  any  runtime  penalty.  We  don’t 
know  yet  what  the  minimal  runtime 
cost  of  OOP  is  but  our  inability  to  meas¬ 
ure  it  and  hence  engineer  it  should 
certainly  give  us  pause.  I’m  uncomfort¬ 
able  working  with  a  programming  para¬ 
digm  whose  runtime  cost  I  can’t  even 
estimate,  let  alone  eliminate. 

Conclusion 

Object-oriented  programming  runs  coun¬ 
ter  to  much  prevailing  programming 
practice  and  experience:  In  allocating 
and  controlling  software  costs,  in  modu¬ 
larity,  in  persistent  state,  in  reuse,  in 
interoperability,  and  in  the  separation 
of  data  and  program.  Running  counter 
to  prevailing  wisdom  does  not,  of 
course,  automatically  make  an  innova¬ 
tion  suspect  but  neither  does  it  auto¬ 
matically  recommend  it.  To  date,  in 
my  opinion,  advocates  of  object-ori¬ 
ented  programming  have  not  provid¬ 
ed  us  with  either  the  qualitative  argu¬ 
ments  or  the  quantitative  evidence  we 
need  to  discard  the  lessons  painfully 
learned  during  the  first  40  years  of 
programming. 
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_ EXAMINING  ROOM _ 

PDQ:  Less  Baggage, 
Faster  Code 

Doing  away  with  bloated  code 


Bruce  W.  Tonkin 


To  a  user,  the  biggest  difference 
between  a  compiled  program 
written  in  a  high-level  language 
and  a  compiled  program  writ¬ 
ten  in  assembly  language  is  the 
size  of  the  executable  (EXE)  file.  The 
majority  of  compilers,  regardless  of  lan¬ 
guage,  produce  large  EXE  files  even 
when  the  size  of  the  original  program 
is  trivial.  Most  serious  programmers 
would  like  to  have  an  alternative  to  this 
problem  of  bloated  code. 

QuickBasic  programmers,  take  note: 
Crescent  Software  has  found  a  way  to 
put  those  fat  EXE  files  on  a  severe  diet, 
shrinking  some  of  them  to  less  than 
IK  bytes.  As  a  bonus,  Crescent’s  PDQ 
library  allows  Basic  TSR  programs,  and 
permits  Basic  programs  to  return  an 
error  level  to  MS-DOS. 

The  large  size  of  most  EXE  files  par¬ 
tially  result  from  the  way  in  which  a 
language’s  libraries  are  arranged.  Ac¬ 
cording  to  Crescent  Software,  the  Mi¬ 
crosoft  QuickBasic  libraries  are  typical: 
If  a  program  contains  a  single  CLS  com¬ 
mand  (which  clears  the  screen),  the 
linker  also  includes  routines  for  COLOR, 
CSRLIN,  POSCO),  LOCATE ,  and  SCREEN 
(x,y).  Most  of  these  routines  also  in¬ 
clude  code  that  can  manage  screens  in 
graphics  mode,  whether  or  not  that 
code  is  needed.  The  addition  of  other 
simple  commands  and  functions  adds 
even  more  overhead.  This  library  “clump¬ 
ing”  factor  is  called  “granularity.” 

I  used  LIB. EXE  to  investigate  Cres- 
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cent's  claims.  A  simple  BEEP  command 
in  QuickBasic  4  costs  923  bytes  of  over¬ 
head,  and  a  single  ASC(  )  function  adds 
554  bytes  to  the  size  of  an  EXE  file! 
That’s  granularity  with  a  vengeance. 

Another  part  of  a  standard  EXE  file 
is  taken  up  by  routines  that  start  a 
program  and  determine  the  type  of 
video  adapter  attached,  the  keyboard, 
the  current  screen  and  graphics  mode, 
and  so  on.  Still  more  overhead  is  added 
in  order  to  handle  the  process  of  pro¬ 
gram  termination.  This  overhead  is  eas¬ 
ily  seen  when  a  null  program  is  com¬ 
piled:  In  QuickBasic  4.5,  a  program  that 
contains  only  an  END  statement  com¬ 
piles  to  an  EXE  of  9842  bytes  in  size! 

Crescent  claims  that  the  QuickBasic 
compiler  actually  produces  very  effi¬ 
cient  code.  If  this  is  true,  it  should  be 
possible  to  produce  very  small  execut¬ 
ables  by  making  the  library  more  effi¬ 
cient  and  by  reducing  the  size  of  de¬ 
fault  start-up  and  termination  code.  This 
method  seems  to  be  exactly  what  Cres¬ 
cent  has  done. 

Crescent’s  PDQ  is  a  substitute  library 
for  those  who  use  the  Microsoft  Quick- 
Basic  compiler,  Version  4.0,  or  higher. 
The  PDQ  library  is  intended  to  replace 
the  BCOM4x.LIB  file  with  a  subset  li¬ 
brary  that  has  smaller  granularity  and 
less  sophistication. 

“Less  sophistication”  means  that  no 
floating-point  routines  are  available. 
There  are  no  routines  to  draw  circles. 
Error  handling  is  greatly  simplified;  only 
eight  error  codes  are  supported.  Disk 
files  must  be  either  sequential  or  bi¬ 
nary.  All  arrays  must  be  static,  how¬ 
ever,  an  allocMEM  function  is  provided 
to  simulate  dynamic  arrays.  PDQ  pro¬ 
vides  no  random-number  generator,  no 


ON  anything,  no  DATA  statement  or 
READ/RESTORE  commands,  TAB, 
PRINT  USING,  or  WRITE. 

Is  this  too  much  to  give  up?  I  don’t 
think  so,  and  I’ll  bet  you  won’t,  either. 
I  wouldn’t  use  the  PDQ  library  to  write 
a  billing  system,  but  that’s  not  PDQ’s 
intended  use.  Before  the  introduction 
of  PDQ,  I  thought  that  only  C  or  assem¬ 
bly  would  be  appropriate  for  the  inevi¬ 
table  menus,  filters,  translators,  and  mis¬ 
cellany  that  are  part  of  most  systems. 
Now,  I  intend  to  use  PDQ  to  develop 
most  of  them. 

In  fact,  Crescent  has  done  what  many 
programmers  have  been  requesting.  For 
years,  compiler  vendors  have  been  in¬ 
creasing  the  size  of  the  default  code 
that  is  automatically  linked  to  each  pro¬ 
gram.  To  handle  the  proliferation  of 
hardware  options,  vendors  supply  many 
library  routines  in  the  most  general  form 
possible  —  and  that  only  makes  mat¬ 
ters  worse. 

It’s  hard  to  argue  with  the  apparently 
sensible  decision  to  supply  general  rou¬ 
tines.  If  I  write  a  program,  I  want  to  be 
sure  that  it  will  run  whether  the  user 
has  VGA,  MDA,  or  anything  in-between. 
On  the  other  hand,  many  programs  are 
strictly  character-mode  and  need  noth¬ 
ing  more  than  the  most  elementary  TTY 
functions.  Some  file  utilities  may  re¬ 
quire  only  the  simplest  I/O.  In  those 
cases,  why  should  the  developer  have 
to  accept  an  extra  25K  (or  more)  of 
unnecessary  run-time  code? 

The  availability  of  different  (individ¬ 
ual  selectable)  versions  of  library  rou¬ 
tines  would  provide  a  real  advantage 
for  developers.  (I’ve  long  argued  that 
developers  would  be  willing  to  pay  for 
such  libraries.)  Even  better,  I’d  like  the 
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(continued  from  page  88)  timized  code  possible,  and  that  it  linked 

option  to  use  some  sort  of  meta-com-  only  the  routines  that  were  absolutely 

mand  to  specify  which  libraries  will  necessary.  I  would  be  willing  to  pay  a 

be  used  for  which  parts  of  a  program,  good  deal  of  money  for  such  a  Basic 

Given  the  current  levels  of  complica-  compiler  and  linker.  (For  whatever  lan- 

tion  and  sophistication  in  compilers  guage,  I’m  not  the  only  developer  with 

and  libraries,  this  may  be  a  lot  to  ask.  those  opinions.)  I  would  also  be  will- 

At  the  very  least,  the  libraries  should  ing  to  debug  with  something  faster  but 

have  finer  granularity.  It’s  probably  true  less  efficient. 

that  the  process  of  linking  libraries  that  From  that  viewpoint,  Crescent’s  PDQ 
have  a  very  fine  granularity  takes  more  may  signal  the  start  of  something  big. 
time,  and  that  these  libraries  may  even  If  PDQ  becomes  a  success,  it  may  spur 
require  the  use  of  multiple  link  passes.  the  major  compiler  vendors  to  offer 
I'm  willing  to  make  that  sacrifice,  and  something  equivalent  to  PDQ  or  bet- 
I  think  that  most  developers  would  be  ter.  Most  developers  are  not  reconciled 
willing  to  do  so  too  —  at  least  for  final  to  working  with  large  executables  that 
distribution  versions  of  software.  need  a  lot  of  memory.  Speed  and  effi- 

Another  potential  problem  exists  with  ciency  will  always  have  appeal, 
respect  to  reduced  granularity.  Most  To  see  how  well  Crescent  has  suc- 
modules  are  aligned  on  paragraph  ceeded  with  PDQ,  let’s  consider  some 
boundaries,  meaning  that  each  module  examples  of  simple  programs  written 
wastes  an  average  of  half  a  paragraph —  in  QuickBasic  and  modified  for  the 

8  bytes.  The  more  modules,  the  more  PDQ  library.  Example  1  lists  the  (hoary) 
wasted  memory.  For  speed  reasons,  standard  SIEVE  program,  and  Example 
modules  should  at  least  be  aligned  on  2  shows  the  equivalent  program  modi- 
word  boundaries,  this  technique  causes  fied  for  PDQ. 

an  average  waste  of  one  byte  per  mod-  I  also  compiled  a  modified  version 
ule.  This  waste  factor  doesn’t  sound  of  the  program  (under  PDQ  and  QB 

like  much  of  a  problem,  but  it  can  4.5)  with  all  PRINT  and  TIMER  state- 
become  one  if  a  program  contains  sev-  ments  removed.  Table  1  shows  the  file 
eral  thousand  very  small  modules.  The  sizes  after  this  program  is  compiled, 
use  of  a  more  intelligent  linker  or  an  In  each  case,  the  EXE  file  created  by 
integrated  compiler/linker  might  cut  at  PDQ  is  about  a  tenth  of  the  size  of  the 
least  some  of  this  waste.  EXE  file  created  by  the  standard  Quick- 

I’ve  told  several  compiler  vendors  Basic  library.  Few  changes  were  neces- 
that  I  would  be  willing  to  accept  com-  sary,  and  the  program  ran  just  as 
pile  times  of  an  hour  or  longer  on  a  386  quickly  —  it  ran  in  about  3-24  seconds 
machine  —  provided  that  the  compiler  on  my  computer, 
produced  the  tightest,  most  highly  op-  Notice  the  effects  of  library  granular- 


: 

— PDQ  — 

Std.  No  Print 

Std. 

-QB  4.5  — 

No  Print 

SIEVE.BAS 

590 

352 

452 

352 

SIEVE.OBJ 

1585 

951 

1226 

951 

SIEVE.EXE 

2620 

1282 

27544 

12522 

Table  1:  File  sizes  after  PDQ  compilation 


Times  per  Million  Long  Integer  Operations 

8088 

80286 

80386 

QB4.5 

Raw  loop: 

2.76 

2.75 

2.24 

13.63 

Assignments: 

1.86 

1.86 

1.37 

1.75 

Additions: 

16.20 

16.20 

13.73 

14.34 

Subtractions: 

16.20 

16.20 

13.73 

14.40 

Multiplications: 

28.28 

27.40 

22.95 

25.33 

Divisions: 

32.46 

32.46 

25.04 

32.20 

Comparisons: 

12.02 

12.08 

11.25 

10.54 

Times  per  Million  Operations 

8088 

80286 

80386 

QB4.5 

Fixed  string  assignments: 

35.81 

36.52 

36.63 

51.43 

Fixed  string  MID$  operations: 

36.03 

36.24 

35.59 

23.67 

Fixed  string  “concatenations”: 

36.03 

36.24 

35.59 

24.26 

Miscellaneous  Times  and  Size 

8088 

80286 

80386 

QB4.5 

Print  1 ,000  70-byte  strings  to  screen: 

27.02 

27.02 

27.02 

9.93 

Executable  size  (bytes): 

7,346 

7,344 

7,126 

46,139 

Table  2:  Benchmark  results 


ity.  Removing  the  PRINT,  TIMER ,  and 
double-precision  subtraction  routines 
sliced  the  size  of  the  QB  4.5  EXE  file 
by  15K  bytes.  A  simple  TTY  print  rou¬ 
tine,  plus  the  bytes  contained  in  the 
actual  strings,  might  use  a  total  of  150 
bytes.  TIMER  ought  to  not  use  more 
than  a  dozen  or  so  bytes.  Double¬ 
precision  subtraction  routines  and  the 
numeric-to-ASCII  conversions  would 
surely  require  less  than  2K  bytes.  The 
rest  of  the  15K  overhead  in  the  QB  4.5 
EXE  file  comprises  all  of  the  unneces¬ 
sary  linked  code. 

A  Small  Utility  Program 

Consider  a  small  filter  utility.  Most  pro¬ 
grammers  would  write  such  a  utility  in 
C  or  in  assembly  language  in  order  to 
generate  the  smallest  EXE  possible.  The 
filter  utility  simply  inspects  the  text  in 
the  file  named  on  the  command  line 
and  converts  all  lowercase  letters  to 
uppercase.  This  utility  looks  like  the 
program  in  Example  3-  The  filter  utility 
is  straightforward  and  the  task  is  trivial, 
but  this  type  of  program  is  the  core  of 
most  file-filter  utilities.  The  file  sizes 
produced  with  PDQ  were: 

Std.  No  Print 

UCASE.BAS  592  459 

UCASE.OBJ  1723  1553 

UCASE.EXE  2578  2348 

Note:  I  added  some  remarks  for  publi¬ 

cation,  so  the  source  code  size  will  not 
match  the  numbers  shown  above. 

UCASE.BAS  ran  with  impressive 
speed,  converting  a  104K-text  file  to 
uppercase  letters  in  about  three  sec¬ 
onds  on  my  Tandy  4000  (16-MHz  80386, 
no  math  coprocessor,  Plus  Develop¬ 
ment  Hard  Card  40,  with  64K  cache 
enabled).  Further,  on  this  small  pro¬ 
gram,  PDQ  was  one-third  the  size  of 
the  equivalent  program  written  in 
QuickC  and  Turbo  C. 

PDQ  also  contains  several  alternate 
libraries.  These  libraries  provide  special 
versions  of  various  modules,  optimized 
for  the  80286  and  80386  processors.  The 
PDQ  documentation  mentions  that  the 
80386  library  is  especially  suitable  for 
use  with  long-integer  calculations,  most 
notably  long-integer  divisions. 

To  test  PDQ’s  speed  during  various 
operations,  I  used  a  modification  of  the 
benchmark  programs  presented  in  my 
earlier  QuickBasic  review  (DDJ,  No¬ 
vember  1988).  The  results  are  shown 
in  Table  2. 

Generally  speaking,  the  PDQ  routines 
are  equivalent  to  the  routines  in  the  stan¬ 
dard  QB  4.5  library.  The  PDQ  80386 
routines  are  appreciably  faster  at  long- 
integer  operations,  as  advertised. 

Regardless  of  the  library  used,  the 
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(continued  from  page  90) 
long-integer  assignment  operations  are 
much  faster  with  PDQ.  I  know  no  rea¬ 
son  for  this  difference  and  few  pro¬ 
grams  use  enough  assignment  opera¬ 
tions  to  make  this  difference  in  speed 
noticeable  to  the  programmer. 


Example  1:  Standard  Sieve 
program 


directly  to  screen  memory.  This  rou¬ 
tine’s  output  was  not  used  because  it 
cannot  be  redirected.  (The  ability  to 
The  slower  print  speeds  occur  be¬ 
cause  PDQ’s  standard  PRINT  com  m  a  n  ds 
go  through  DOS  services.  PDQ  also 
contains  a  PDQPRINT routine  that  prints 


Example  2:  PDQ  version  of  the 
Sieve  program 


direct  output  is  of  great  use  in  utility 
programs.)  Also  the  routine  does  not 
automatically  scroll. 

PDQPRINT  is  useful  when  a  pro¬ 
grammer  needs  to  force  screen  print¬ 
ing  (even  when  the  standard  output 
has  been  redirected),  or  when  greater 
speed  is  necessary.  In  addition,  PDQ¬ 
PRINT  supports  color  attributes;  the 
PRINT  routine  in  PDQ  doesn’t. 

I  also  compared  the  speeds  of  the 
integer  operations,  and  found  little  dif¬ 
ference  between  PDQ  and  QB  4.5.  Re¬ 
alistically,  integer  operations  are  so  fast 
in  nearly  any  compiler  that  much  greater 
performance  increases  result  from  the 
use  of  optimization  techniques  rather 
than  from  the  use  of  tricks  for  integer 
arithmetic.  Because  PDQ  uses  the  code 
generation  of  QB  4,  any  optimization 
(or  lack  of  it)  in  QB’s  code  generation 
is  reflected  in  PDQ.  The  performance 
changes  for  PDQ  result  only  from 
changes  in  library  routines. 

TSR  Power 

The  PDQ  library  does  more  than  just 
remove  functions  and  commands  —  it 
also  adds  some  new  ones.  The  most 
notable  added  commands  and  func¬ 
tions  make  TSR  programs  possible. 
Some  of  these  new  commands  and  func¬ 
tions  are: 


rem  $include:  ' pdqdecl .bas' 

DIM  flags (8190) 

DEFINT  A-Z 

CLS 

DIM  flags (81901 

PRINT  "25  iterations" 

CIS 

start &=pdqtimer& 

PRINT  "25  iterations" 

FOR  j  =  1  TO  25 

x#  *  TIMER 

count  =  0 

FOR  j  =  1  TO  25 

FOR  i  =  0  TO  8190 

count  ■  0 

flags (i)  *  1 

FOR  i  *  0  TO  8190 

NEXT  i 

flags (1)  =  1 

FOR  i  =  0  TO  8190 

NEXT  i 

IF  flags  (i)  THEN 

FOR  i  *  0  TO  8190 

prime  =  i  +  i  +  3 

IF  flags  (i)  THEN 

k  =  i  +  prime 

prime  =  i  +  i  +  3 

WHILE  k  <=  8190 

k  =  i  +  prime 

flags (k)  *  0 

WHILE  k  <-  8190 

k  =  k  +  prime 

flags (k)  *  0 

WEND 

k  =  k  +  prime 

count  =  count  +  1 

WEND 

END  IF 

count  *  count  +  1 

NEXT  i 

END  IF 

NEXT  j 

NEXT  i 

done&=pdqtimer& 

NEXT  j 

tots* (10* (done& -starts) ) \ 1 82 

XX#  *  TIMER 

'convert  timer  ticks  to  seconds. 

PRINT  USING  "####  primes  in  ##.### 

frac&=(10000&* (10* (done&~start&) 

seconds";count;xx#-x# 

mod  182) ) \182  'and  decimal. 

END 

..  ’  «>4  .  .  -V'  ■ 

PRINT  count; "primes  in  ";rtrim$ 

(str$ (tot&) ) ;" . "; frac&; "seconds . w 

END 

TestHotKey 

IntEntryl 

PopUpHere 

PointlntHere 

GotoOldlnt 

CallOldlnt 


StuffBuf 

ResetKeyboard 

PopDown 

IntEntry2 

EndTSR 


Rather  than  explaining  each  of  these 
commands  in  detail,  I’ll  present  a  sam¬ 
ple  TSR  program  that  uses  them. 

I  altered  one  of  Crescent’s  many  dem¬ 
onstration  programs  to  output  keyboard 


macros.  The  sample  program  intercepts 
calls  to  interrupt  9  (the  standard  key¬ 
board  interrupt).  If  the  key  combina¬ 
tion  pressed  is  ALT-A,  ALT-S,  or  ALT-D, 
the  TSR  program  clears  the  keyboard 
buffer  and  inserts  the  defined  sequence 
of  keystrokes  into  the  same  buffer.  Non- 
trapped  keys  are  passed  to  the  stan¬ 
dard  Int  9  handler.  You  may  not  stuff 
more  than  15  characters  into  the  key¬ 
board  buffer  (as  mentioned  in  the  PDQ 
documentation). 


'by  default,  all  variables  are  integers 
'initialize  a$  to  128  characters 
'buffer  for  file  is  8K  bytes 
'look  at  the  command  line 
'no  file  named;  give  help. 


defint  a-z 
call  initstr (a$, 128) 
call  initstr(b$, 8192) 
a$=command$ 
if  rtrim$ (a$) =""  then 
print "Syntax: " 
print"UCAS£  filename" 

print"The  named  file  will  be  converted  in  place  to  upper-case." 

end 

end  if 

open  rtrim$(a$)  for  binary  as  #1  'no  random  files  in  PDQ 


size&=lof (1)  'file  size 

if  size&“0  then  close  l:kill  rtrim$ (a$) rend  'no  such  file 

where &=1  'start  with  the  first  byte 

while  where&<=size&  'as  long  as  there  are  bytes  to  read 
remains&=size&-where&+l  'how  much  is  left? 
if  remains&<8192  then  call  setlength (b$, remainsS)  '<  8192  bytes 
get  l,where&,b$  'grab  the  next  chunk  to  convert 

b$=ucase$ (b$)  'upper-case  it 

put  l,where&,b$  'write  it  back  out 

where&=where&+len (b$)  'update  the  file  position 
wend 
end 


Example  3:  Sample  filter  utility 


The  sample  programs  furnished  with 
PDQ  do  work.  If  you  have  any  doubts 
about  the  correct  way  to  do  something 
with  PDQ,  look  at  those  examples  care¬ 
fully.  I  accidentally  omitted  the  final 
call  ReturnFromlnt for  ALT-D,  and  was 
sure  I’d  found  a  bug.  When  my  pro¬ 
gram  was  changed  to  a  TSR  program, 
all  attempts  to  use  macros  failed  after 
the  first  time  that  ALT-D  was  pressed. 
I’m  not  exactly  sure  why  this  happened, 
but  the  error  was  certainly  mine  and 
not  PDQ’s. 

Even  Basic’s  executables  would  make 
such  TSRs  rather  wasteful.  With  PDQ, 
TSRs  are  small  enough  to  be  practical. 
The  sample  program  that  I  just  pre¬ 
sented  results  in  an  EXE  file  of  only 
2404  bytes  in  size. 

The  Manual 

The  PDQ  documentation  supplied  with 
the  first  release  of  the  library  was  in 
preliminary  form,  and  will  be  changed 
soon.  Ethan  Winer  of  Crescent  Soft¬ 
ware  told  me  that  only  100  manuals 
were  printed  for  the  first  release  of 
PDQ,  so  criticisms  of  the  documenta¬ 
tion  may  be  moot. 

It  is  important  to  note  that  if  your 
program  uses  large  static  arrays,  you 
should  use  the  /ex  option  on  the  link 
command  line.  (This  option  is  not  men- 
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tioned  in  the  first  version  of  the  man¬ 
ual.)  The  /ex  option  packs  space  used 
by  static  arrays  and  results  in  much 
smaller  EXE  files.  Without  the  /ex  op¬ 
tion,  the  SIEVE  program  compiled  to 
approximately  18K  under  PDQ.  I  also 
used  the  /ex  option  when  I  compiled 
with  QB  4.5. 

This  first  version  of  the  manual  was 
disorganized  in  places,  but  was  fairly 
easy  to  use.  The  information  about  the 
new  commands  and  the  changes  from 
QB  4  were  well  organized,  but  the 
discussion  of  TSR  programs  was  incom¬ 
plete.  In  some  places,  the  manual  didn’t 
match  the  syntax  of  the  first  release. 
Fortunately,  the  distribution  disk  con¬ 
tains  a  generous  number  of  helpful 
example  programs,  all  of  which  work. 
If  you  purchase  PDQ,  I  recommend 
that  you  read  the  manual  and  then  pay 
very  close  attention  to  the  examples 
on  the  disk. 

From  previous  experience,  I  knew 
that  Crescent  Software’s  manuals  are 
chatty  and  easy  to  read.  The  manual 
for  PDQ  is  typical.  Ethan  Winer  clearly 
knows  a  lot  about  the  internals  of  Quick- 
Basic,  and  he’s  not  shy  about  sharing 
his  knowledge.  The  manual  contains  a 
number  of  performance  hints,  tips  for 
reducing  the  size  of  typical  PDQ  and 
QuickBasic  programs,  and  even  ways 


to  call  QuickBasic  library  routines  di¬ 
rectly.  One  such  example  shows  how 
to  force  QuickBasic  to  do  the  equiva¬ 
lent  of  MAT  READ. 

On  balance,  I  liked  the  manual  very 
much  despite  its  early  flaws;  later  ver¬ 
sions  of  the  manual  should  be  better. 

Overall  Utility 

PDQ  is  aimed  at  QuickBasic  program¬ 
mers,  but  it  has  clear  applicability  in 
other  areas.  In  the  past,  I  resorted  to 
the  use  of  assembly  language  or  C  to 
write  small  utilities.  I  resented  the  gen¬ 
eral  unreadability  of  C  and  the  more 
complicated  compilation  process  that 
it  requires.  Also,  because  of  the  low- 
level  nature  of  assembly  and  C,  I  found 
the  debugging  process  to  be  far  more 
tedious  than  the  process  of  debugging 
Basic,  even  with  the  new  versions  of 
C  and  assembly  from  Borland  and  Mi¬ 
crosoft.  As  long  as  I  benefited  from 
efficiency  and  speed,  I  was  willing  to 
put  up  with  those  disadvantages. 

Granted,  there  will  still  be  times  when 
C  or  assembly  are  the  most  suitable 
tools  for  the  job.  PDQ  simply  makes 
those  times  less  frequent,  and  makes 
my  work  easier. 

Programmers  who  are  unfamiliar  with 
either  C  or  assembly  can  now  attempt 
more  projects.  With  the  advent  of  PDQ, 


Basic  can  only  gain  stature  as  a  readable 
and  efficient  language  that  is  suitable  for 
both  small  and  large  projects.  As  a  long¬ 
time  Basic  enthusiast,  I  can’t  pretend 
to  be  unbiased  about  the  prospect. 

PDQ  is  a  watershed  product.  I  think 
it  is  the  first  in  a  series  of  efficient 
compilers  and  alternative  libraries.  In 
the  next  few  years,  we’ll  almost  cer¬ 
tainly  see  similar  attempts  for  C,  Pascal, 
and  other  popular  languages.  Subse¬ 
quent  products  will  surely  include  ever 
more  efficient  compilers  and  linkers, 
benefiting  us  all. 

Whether  or  not  you  find  PDQ  ap¬ 
pealing,  I  feel  sure  that  the  approach 
taken  by  Crescent  Software  is  the  ap¬ 
proach  that  the  whole  industry  will  fol¬ 
low  in  the  future.  Other  developments 
are  doubtful  —  this  one  is  not.  Bloated 
code  may  finally  be  doomed. 

Product  Information 

P.D.Q.  Crescent  Software,  Inc. 

11  Grandview  Ave., 

Stamford,  CT  06905 

Includes  full  source  code 

For  IBM  PC,  XT,  AT,  or  compatible 

$99 


DDJ 

Vote  for  your  favorite  feature/article. 
Circle  Reader  Service  No.  8. 
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Programming  and 

FPCA  ’89 

A  conference  report 


Editor’s  Note:  Over  the  past  few  years, 
a  new  method  of  developing  and  writ¬ 
ing  computer  programs  called  “func¬ 
tional  programming  ”  has  evolved  with¬ 
out  getting  much  attention  from  the 
general  public.  Nevertheless,  this  novel 
paradigm  may  influence  programming 
five  to  ten  years  from  now.  Every  sec¬ 
ond  year,  the  advances  in  this  area  are 
discussed  at  the  Conference  on  Func¬ 
tional  Programming  and  Computer  Ar¬ 
chitecture  (FPCA).  FPCA  '89  was  held 
in  London,  England  and  DDJ  corre¬ 
spondent  Ronald  Fischer  was  there;  here 
is  his  report. 

o  start  with,  forget  everything 
you  have  ever  learned  about 
computer  programming.  Dur¬ 
ing  the  last  decade,  a  new  way 
of  writing  programs  has  slowly 
developed:  The  “Functional  Program¬ 
ming  Paradigm,”  which  lacks  some  of 
the  most  salient  features  of  traditional 
programming  languages.  Most  notably 
among  those  missing  features  are  loop¬ 
ing  constructs  and  the  destructive  as¬ 
signment  to  memory  variables.  In  some 
respects,  this  new  programming  style 
appears  to  be  more  like  writing  mathe¬ 
matical  equations  than  developing  al¬ 
gorithms.  Its  proponents  in  fact  hope 
that  it  leads  to  more  bug-free  software, 
because  programs  may  be  proved  cor- 


Ronald  is  a  software  developer for  Soft- 
ware-Entwicklung  &  Consulting  and 
can  be  reached  at  Straubinger  Strasse 
20,  D-8000  Miinchen  21,  W.  Germany. 


Ronald  Fischer 

rect  by  mathematical  means,  instead 
of  by  debugging.  As  an  example,  con¬ 
sider  a  function  SUM,  which  returns  the 
sum  of  a  list  of  numbers: 

DEC  SUM:  LIST(NUM)— *  NUM; 

—  SUM(NIL)  <=  0; 

—  SUM(H::T)  <=  H  +  SUM(T); 

This  example  is  coded  in  a  “real”  func¬ 
tional  language  called  “Hope+.”  I  have 
chosen  this  language  because  of  its 
straightforward  syntax.  Hope+  programs 
are  easy  to  understand  even  if  you  are 
not  yet  comfortable  with  functional  pro¬ 
gramming  (FP  for  short). 

The  first  line  Declares  the  function 
SUM  as  a  mapping  from  the  set  “list  of 
numbers”  onto  the  set  “numbers.”  The 
next  two  lines  describe  what  SUM  actu¬ 
ally  does:  If  applied  to  an  empty  list, 
SUM  returns  zero.  If  SUM  is  instead 
applied  to  a  list  consisting  of  a  head  H 
and  a  tail  T,  it  sums  up  the  tail  and  adds 
it  to  the  head  element.  For  Prolog  pro¬ 
grammers,  this  way  of  thinking  may 
be  familiar.  Actually,  there  is  a  strong 
relationship  between  “pure"  Prolog  (that 
is,  no  “cut,”  no  side  effects,  no  extra 
logic  features)  and  FIope+,  as  you  may 
easily  model  one  with  the  other. 

Functional  programs  are  appealing 
because  they  are  free  of  side  effects. 
They  are  called  “referential  transpar¬ 
ent,”  which  means  that  two  successive 
invocations  of  a  function  with  the  same 
arguments  always  yield  the  same  re¬ 
sults.  In  traditional  languages  such  as 


C,  this  may  or  may  not  be  the  case. 
Here  is  a  C  function  that  is  not  referen¬ 
tial  transparent: 

int  foofint  n); 

(  static  int  c=0; 

return  n+getchar(  )+(c++); 

1 

You  can  argue  that  some  programs 
are  impossible  to  write  without  relying 
on  side  effects.  Interactive  input/out¬ 
put  comes  to  mind,  or  generation  of 
random  numbers.  As  we  will  see  shortly, 
this  is  not  true:  Every  conventional  pro¬ 
gram  can  be  written  in  functional  style. 
But  first,  it  is  necessary  to  understand 
a  few  little  FP  basics. 

In  the  Beginning 

The  roots  of  FP  can  be  traced  back  to 
the  famous  mathematician  Alonzo 
Church,  who  developed  in  1941  a  no¬ 
tation  to  reason  about  mathematical 
functions  without  giving  them  explicit 
names,  that  is,  anonymous  functions. 
This  notation  was  called  the  “lambda 
calculus,”  and  a  function  that  returns 
the  square  of  its  argument  looks  similar 
to  this  in  Church’s  notation:  X  x.x*x 
The  argument  x  is  listed  to  the  left 
of  the  period.  In  order  to  calculate  the 
square  of  a  particular  number,  say  5, 
you  write  (  X  x.x*x)  5. 

It  can  be  shown  (but  to  do  so  would 
require  a  separate  article  the  length  of 
this  one)  that  every  function  and  thus 
every  computer  program  could  be  writ¬ 
ten  as  a  series  of  —  possibly  nested  — 
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lambda  expressions.  This  is  not  obvi¬ 
ous  at  all;  just  think  of  how  you  would 
write  a  recursive  function  such  as  SUM 
as  a  lambda  expression.  Note  that  you 
must  not  use  names  (for  example,  SUM) 
to  accomplish  the  recursive  call,  be¬ 
cause  functions  in  the  lambda  calculus 
are  unnamed.  Besides,  N.G.  de  Bruijn 
proved  in  1972  that  it  is  even  possible 
to  dispense  with  the  names  of  the  vari¬ 
ables,  too! 

The  first  application  of  Church’s  the¬ 
ory  was  incorporated  into  the  program¬ 
ming  language  Lisp,  where  the  previ¬ 
ously  defined  function  to  square  its 
argument  could  be  written  as  (X X (* X 
Xj).  Lisp  could  be  very  close  to  func¬ 
tional  programming,  but  for  efficiency 
reasons,  Lisp  designer  McCarthy  soon 
had  to  abandon  this  concept  in  favor 
of  a  more  traditional  approach.  For  ex¬ 
ample:  (SETQ  V  5)  replaces  the  previ¬ 
ous  value  of  V  with  the  new  value  5. 
Destructive  assignments,  however,  are 
forbidden  in  any  FP  language. 

It  was  not  before  the  1970s  that  re¬ 
searchers  really  began  to  investigate 
the  possibility  of  a  pure  functional  lan¬ 
guage.  In  1978,  Fortran  inventor  John 
Backus  published  his  now  historic  pa¬ 
per,  “Can  Programming  Be  Liberated 
From  the  Von-Neumann  Style,”  where 
he  described  a  new  functional  language 
called  “FP.”  Soon  after,  research  activ¬ 
ity  took  off. 

Cheaper  memory  and  faster  CPUs 
made  functional  programming  usable. 


Hope+  was  developed  and  used  inter¬ 
nally  at  universities  for  teaching  pur¬ 
poses  and  for  application  programming. 
The  first  full-featured  and  commercially 
available  compiler  for  a  functional  lan¬ 
guage  was  announced  in  1985  at  the 
International  Conference  on  Functional 
Programming  and  Computer  Architec¬ 
ture  (FPCA  ’85)  at  Nancy,  France,  by 
researcher  David  Turner.  The  language 
implemented  was  called  “MIRANDA” 
and  introduced  a  formalism  called  “cur¬ 
rying”  (named  after  the  theoretician  Has¬ 
kell  B.  Curry):  A  function  of  n  argu¬ 
ments  may  be  treated  as  a  concatena¬ 
tion  of  n  single-argument  functions. 
Thus,  if  PLUS  expects  two  arguments 
and  returns  their  sum,  the  expression 
PLUS  1  denotes  a  new  function  of  one 
argument,  which  simply  adds  1  to  it. 

Miranda  and  Hope+  are  not  only 
pure  functional  languages  for  use  in 
research;  they  are  also  intended  to  be 
used  for  application  programming.  As 
mentioned  earlier,  there  seems  to  be  a 
conflict  between  referential  transpar¬ 
ency  and  some  real-world  problems 
such  as  input/output.  Of  course,  input 
from  the  terminal  could  be  regarded 
as  a  list  of  characters  that  can  be  passed 
at  once  to  a  function  for  processing. 
Because  output  to  the  screen  may  be 
regarded  as  a  similar  list,  one  may  be 
tempted  to  define  a  program  doing  in¬ 
teractive  I/O  in  the  following  way:  DEC 
DIALOGUE:  LIST? CHAR)  -*  LIST(CHAR); 

But  this  requires  the  program  to  an¬ 


ticipate  the  whole  input  at  once  and  in 
advance!  In  an  interactive  environment, 
however,  most  input  will  not  be  avail¬ 
able  until  at  least  part  of  the  output  has 
been  written  to  the  screen. 

One  solution  to  this  problem  is 
termed  “lazy  evaluation.”  During  func¬ 
tion  evaluation,  the  program  consumes 
only  as  much  from  its  (input)  parame¬ 
ters  as  is  necessary  for  the  communica¬ 
tion  with  the  terminal.  Therefore,  al¬ 
though  DIALOGUE  conceptually  ac¬ 
cesses  all  of  its  input  at  the  beginning 
and  delivers  all  of  its  output  at  the  end 
of  the  computation,  the  code  gener¬ 
ated  by  the  compiler  manages  the  in¬ 
terleaving  of  input  and  output.  The 
programmer,  of  course,  need  not 
worry. 

Look  for  instance  at  the  program 
SILLY  in  Figure  1.  It  expects  a  list  of 
character  digits  and  comments  on  each 
character  received.  If  the  character  re¬ 
ceived  is  indeed  numeric  (a  digit),  it 
says  “That’s  fine.”  If  it  is  not  numeric, 
it  complains.  SILLY  may  be  connected 
to  a  terminal  like  this: 

TOFILE(term_in,silly(FROMFILE 

(term_out)); 

term_m  and  term_out  are  not  part  of 
the  language  definition,  but  identifiers 


An  Interview  with  Simon  Peyton-Jones 


DDJ:  Simon,  you  promise  that  your 
new  language  called  “Haskell”  will 
be  a  standard  and  will  be  freely  avail¬ 
able.  In  what  way  do  you  mean  it’s 
free  and  everybody  will  have  it?  Will 
it  be  like  SNOBOL4,  so  everybody  can 
have  the  source  code  for  it? 

P-J:  Sure,  the  main  aspect  for  it  is 
that  anybody  can  implement  it  and 
distribute  their  implementations. 

DDJ:  Such  its  early  Unix? 

P-J:  That’s  right.  Anybody  can  use 
Haskell  and  distribute  it. 

DDJ:  What  do  you  think  when  it  will 
be  available? 

PJ:  Well,  to  the  end  of  next  year  [i.e., 
1990],  we  will  have  a  first-time  beta 
version.  Until  the  end  of  the  following 
year,  we  expect  to  have  a  full  work¬ 
ing  version. 

DDJ:  What  do  you  think  will  be  the 
reaction  from  the  industry?  Will  Has¬ 
kell  become  an  established  standard 
in  10  or  20  years? 


P-J:  Oh,  we  already  have  several  in¬ 
dustrial  promises  involving  functional 
projects,  so  the  industry  is  showing 
some  interest.  One  of  them  is  British 
Telecom.  Another  one  has  been  ICL. 
They  were  recently  involved  in  a  laige 
European  project  to  do  with  declara¬ 
tive  [i.e.,  functional]  programming. 

DDJ:  Do  they  actually  use  functional 
programming  for  applications  work? 
P-J:  Mainly  it’s  restricted  at  the  mo¬ 
ment  to  industrial  research  labs,  be¬ 
cause  available  implementations  just 
haven’t  been  fast  enough.  Nowadays 
we  are  just  beginning  to  get  to  a  state, 
where  we’ve  got  implementations  of 
functional  languages  where  you’re 
only  losing  a  small  factor  overwriting 
in  Fortran  or  C,  and  the  productivity 
benefits  you  pick  up  from  writing  in 
functional  languages  then  become  suf¬ 
ficiently  severe. 

DDJ:  Do  you  think  that  education 
will  be  an  issue? 

PJ:  Well,  I  think  education  is  an  im¬ 


portant  thing.  That’s  why  Pascal  be¬ 
came  so  important,  because  it  was 
taught  in  a  lot  of  universities,  so  a 
whole  generation  of  students  went 
out  knowing  Pascal.  We  have  already 
started  teaching  our  students  func¬ 
tional  programming  in  their  first  year; 
we  also  teach  imperative  languages 
later  on  as  well.  So,  functional  pro¬ 
gramming  may  become  more  wide¬ 
spread  now.  —  R.F. 

For  Additional  Information 

MIRANDA  (Unix  4.2  BSD,  Ultrix): 
Research  Software  Ltd. 

23,  Augustines  Road 
Canterbury,  Kent  CT1 1XP,  England 

Q’NIAL  (MS-DOS,  OS/2,  Unix,  Unity, 
VMS,  and  others): 

N.I.A.L  Systems  Ltd. 

155  Queen  Street,  9th  floor 
Ottawa,  Ontario,  Canada  KIP  5C9 

PC  SCHEME  (MS-DOS) 

Texas  Instruments  Inc. 

P.O.Box  2909,  M/S  2151 
Austin,  Texas  78769-2909 


98 

858 


Dr.  Dobb’s Journal,  December  1989 


such  as  these  should  be  provided  by 
the  respective  Hope+  installation.  Due 
to  lazy  evaluation,  the  user  gets  a  re¬ 
sponse  after  each  typed  character. 

Infinite  data  structures  like  the  ter¬ 
minal  input  mentioned  are  called 
“streams.”  Streams  are  not  only  useful 
for  input/output.  The  following  Hope+ 
function  returns  an  infinite  list  of  suc¬ 
cessive  integers,  starting  with  N:  DEC 
IUST:  NUM  —*UST(NUM);  —  FROM(N) 
<=  N  ::  FROM(N+ 1 );  This  would  be 


DEC  Silly:  LIST(CHAR)->LIST(LIST(CHAR)); 

— silly(NIL)  <=  [Thank  you  for  using  <silly>"]; 

— silly(onechar::remaining)  <= 

(IF  member(onechar, "01 23456789")  THEN  "That’s  fine!\n" 
ELSE  "Please  type  only  digits!\n") ::  silly(remaining); 

TYPEVAR  anyjype; 

DEC  member:  anyjype  #  LIST  (anyjype)  -*  TRUVAL; 
— member(_,NIL)  <=  FALSE; 

— member(a,a  ::  t)  <=  TRUE; 

— member(a,_  ::  t)  <=  member(a.t); 


Figure  1:  This  program  expects  a  list 
of  character  digits  and  comments  on 
each  character  received 


||  MIRANDA  example  program 

||  defining  a  tree  whose  nodes  can  be  any  type 

||  the  type  is  represented  by  the  asterisk  symbol  tree  *  ::=niltree 

|  node  *  (tree  *)  (tree  *) 

||  Now  implementing  a  sort  algorithm 

||  To  sort  a  tree,  first  flatten  it  to  get  a  list  of  nodes 

||  Next  build  a  sorted  tree  from  the  list  sort  =  flatten  .  buildsorted 

I!  This  defines  how  to  flatten  a  tree 

flatten  niltree  =  [  ]  ||  Flattening  an  empty  tree  gives  the  empty  list 
I!  To  flatten  any  other  tree,  flatten  the  left  subtree  first, 

||  append  the  root,  and  append  the  flattened  right  subtree, 
flatten  (node  a  left  right)  =  flatten  left  ++  [a]  ++  flatten  right 

||  This  defines  how  to  build  a  sorted  tree  from  an  unsorted  list 
||  Note:  “<=  and  V  must  be  defined  on  tree  nodes!  buildsorted 
=  foldr  insert  niltree  ||  foldr  is  a  predefined  transformer! 

where 

insert  a  niltree  =  node  a  niltree  niltree 
insert  a  (node  b  left  right) 

=  node  b  (insert  a  left)  right,  a<=b 
=  node  b  left  (insert  a  right),  a>b 


Figure  2:  A  polymorphic  sort  function 
that  sorts  anything  as  long  as  it  is  rep¬ 
resented  as  a  tree  and  has  an  ordering 
relation  defined  on  it 


#  Defining  the  FACTORIAL  function  in  NIAL 

#  i.e.,  factorial  4  results  in  16 

factorial  IS  FORK 
[  1  >=  ,  1  first , 

times  [  pass  ,  factorial  (1  CONVERSE  minus)  ] 
1 

#  Defining  the  AVERAGE  of  a  list  of  values 

#  i.e.,  average  3  9  5  3  results  in  4 
average  IS  /  [sum .tally] 

Figure  3-'  Sample  NIAL  code 
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impossible  to  accomplish  without  lazy 
evaluation,  because  a  call  to  //J.S'Avould 
lead  to  a  non-terminating  loop.  In 
Hope+,  however,  it  is  perfectly  reason¬ 
able  to  work  with  those  functions  and 
structures. 

Using  FP  in  Real  Projects 

So,  what  if  you  decide  to  use  functional 
programming  in  real  projects?  There 
are  a  lot  of  compilers  for  imperative 
languages  such  as  Fortran,  C,  Pascal, 
and  even  Smalltalk  and  Prolog,  but  if 
you  go  to  a  software  store  and  ask  for 
a  nifty  little  FP  system  for  your  work¬ 
station,  you  will  be  disappointed. 

Indeed,  the  present  situation  is  remi¬ 
niscent  of  the  time  the  first  Fortran 
compilers  became  available  in  the  mid- 
1950s:  Insiders  knew  that  something 
revolutionary  was  going  on,  but  how 
were  they  to  participate?  The  situation 
with  functional  programming  appears 
similar,  but  as  it  happens  it  could  be 
worse. 

Presently,  the  most  advanced  prod¬ 
ucts  run  under  Unix.  This  comes  as  no 
surprise  because  this  operating  system 
is  prominent  among  universities.  Hope+, 
for  instance,  runs  under  Unix.  This  com¬ 
piler  is  not  freely  available,  however, 
so  you  have  to  contact  a  university 
computer  science  department  to  get  a 
copy.  For  instance,  Imperial  College 
of  London  runs  a  copy  of  Hope+  in  its 
functional  programming  laboratory. 

At  present,  only  one  language  pro¬ 
viding  full  laziness  is  commercially  avail¬ 
able:  Miranda,  the  programming  lan¬ 
guage  invented  by  David  Turner. 
Turner,  who  at  the  time  worked  at  the 
University  of  Kent  in  England,  founded 
his  own  company,  Research  Software 
Ltd.,  in  order  to  market  his  compiler, 
which  is  currently  available  on  Sun, 
Apollo,  VAX  (running  Ultrix),  and  the 
Hewlett-Packard  9000  series. 

One  of  Miranda’s  attractive  features 
is  its  provision  for  strong  typing  with¬ 
out  requiring  the  programmer  to  write 
any  type  declarations  for  variables.  The 
compiler  simply  deduces  the  type  of  a 
function  from  its  applications,  and  re¬ 
ports  any  inconsistencies  it  finds. 

Data  abstraction  is  realized  by  “con¬ 
structor  functions,”  which  can  be  com¬ 
pared  to  user-defined  types  in  tradi¬ 
tional  languages.  To  define  a  type  tree 
representing  a  binary  tree  of  numbers, 
you  simply  write:  tree  ::  =  niltree  I  node 
num  tree  tree. 

In  this  equation,  num  is  a  prede¬ 
fined,  primitive  type,  while  the  remain¬ 
ing  words  are  user  defined  and  intro¬ 
duced  to  the  system  with  this  equation. 
A  function  sumtree,  which  sums  up  all 
numbers  stored  in  a  tree,  could  be  writ¬ 
ten  like  this: 


sumtree  niltree  =  0 
sumtree  (node  number  left  right)  = 
number  +  sumtree  left  +  sumtree 
right 

New  trees  are  built  by  the  application 
of  the  constructors.  The  expression: 
node  5  (node  2  niltree  niltree)  niltree 
returns  a  tree  whose  root  contains  the 
number  5,  whose  left  branch  contains 
2,  and  whose  right  branch  is  empty. 

As  in  Hope+,  functions  in  Miranda 
can  be  polymorphic.  This  means  that 
you  need  not  worry  about  a  concrete 
type  as  long  as  some  structural  invari¬ 
ant  is  observed.  Figure  2  shows  a  poly¬ 
morphic  sort  function  that  sorts  any¬ 
thing  as  long  as  it  is  represented  as  a 
tree  and  has  an  ordering  relation  de¬ 
fined  on  it. 

Miranda  is  unique  in  that  it  is  already 
used  for  many  industrial  applications. 
Among  the  steadily  increasing  commu¬ 
nity  of  Miranda  users  are  Toshiba, 
Signetics,  Shell  Netherlands,  BP  (UK), 
Olivetti,  Logica  Cambridge,  and  ICL. 
The  British  company  Logica  Cambridge 
uses  Miranda  currently  for  the  design 
of  Viper  2,  a  special-purpose  micro¬ 
processor  for  real-time  control. 

For  MS-DOS  and  OS/2,  there  are 
fewer  possibilities  for  doing  FP  today. 
This  is  understandable,  because  these 
operating  systems  are  used  extensively 
in  the  scientific  community.  Also,  due 
to  memory  limitations,  porting  a  com¬ 
piler  such  as  Miranda  to  MS-DOS  is  a 
non-trivial,  if  not  impossible,  task.  The 
market  for  OS/2,  on  the  other  hand,  is 
not  considered  important  enough  yet 
to  justify  the  cost  of  a  conversion. 

If  you  are  willing  to  sacrifice  lazy 
evaluation,  there  are  a  some  languages 
available:  Q’NIAL,  for  example,  is  an 
excellent  implementation  of  the  NIAL 
(nested  interactive  array  language)  lan¬ 
guage,  which  not  only  incorporates  an 
equivalent  of  Backus’s  FP  language  as 
a  subset  (see  Figure  3  for  examples), 
but  also  contains  a  lot  of  useful,  im¬ 
perative  constructs.  Because  Q’NIAL  is 
not  only  offered  for  DOS,  but  also  for 
OS/2,  Unix,  VMS,  and  several  other 
systems,  it  may  be  the  language  of 
choice  for  doing  serious  application 
development. 

Some  Lisp  dialects  also  enforce,  or 
at  least  enable,  programming  in  a  func¬ 
tional  style.  PC-Scheme,  an  implemen¬ 
tation  of  the  Lisp-derivate  Scheme  by 
hardware  manufacturer  Texas  Instru¬ 
ments,  is  an  example.  The  compiler  is 
well  made,  but  the  user  interface  lacks 
speed  and  sophistication.  There  is  also 
a  functional  Lisp  derivate  called  “Le- 
Lisp,”  implemented  at  a  French  univer¬ 
sity  for  Unix  and  DOS.  A  public  domain 
version  of  Backus’s  FP  was  implemented 
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in  C  by  Arch  D.  Robinson,  Urbana, 
Illinois.  It  runs  on  Unix  and  MS-DOS, 
but  may  be  used  only  for  educational 
purposes  because  it  is  so  slow. 

FPCA  '89,  the  Haskell  Language, 

And  More 

The  papers  presented  at  FPCA  ’89  cov¬ 
ered  a  wide  range  of  subjects,  from 
purely  theoretical  subjects  to  industrial 
applications.  As  with  the  introduction 
of  Miranda  in  1985,  this  year’s  confer¬ 
ence  revealed  a  new  and  widely  dis¬ 
cussed  programming  language  called 
“Haskell,”  named  after  Haskell  Curry 
(creator  of  the  “currying  functions”  of 
the  Miranda  language).  So  what’s  the 
advantage  of  Haskell  over  Miranda? 

While  Miranda  certainly  is  suitable 
for  every  kind  of  program  development, 
it  does  not  particularly  support  large 
projects  with  tens  of  programmers  writ¬ 
ing  hundreds  of  modules  concurrently. 
Haskell,  on  the  other  hand,  supports 
modular  programming  by  requiring  the 
definition  of  clean  interfaces  between 
modules  and  of  abstract  data  types.  In 
some  respects,  Miranda  is  to  Haskell 
as  Pascal  is  to  Modula-2:  The  spirit  is 
the  same,  but  the  latter  is  more  ad¬ 
vanced. 

Second,  and  even  more  important: 
Haskell  is  free!  This  means  that  for  a 
nominal  fee  covering  shipping  and  han¬ 
dling,  anyone  can  get  the  original  soft¬ 
ware  including  the  source  code  and 
port  it  to  any  operating  system  for  re¬ 
sale.  Of  course,  there  will  be  a  version 
available  ready  to  use  that  has  to  be 
paid  for. 

In  this  manner,  the  Haskell  research 
group,  centered  around  Philip  Wadler 
and  Simon  Peyton-Jones  of  Glasgow 
University,  hopes  to  spread  the  spirit 
of  functional  programming  around  the 
world.  Unlikely?  Remember  how  Unix 
became  popular.  Maybe  it  will  work 
again.  Figure  4  shows  a  small  Haskell 
program  that  types  a  file  FOO  to  the 
console.  Haskell  is  presently  neither 
standardized  nor  finished,  so  the  actual 
syntax  might  vary  slightly  when  the 
first  compiler  is  delivered. 

Another  interesting  feature  of  Haskell 
is  its  relationship  to  object-oriented  pro¬ 
gramming  (OOP).  Haskell  has  objects, 
classes,  multiple  inheritance,  and  all  other 
OOP  features  except  one,  of  course: 
Haskell  objects  don’t  have  internal 


main  resps  = 

[  ReadFile  "FOO"  Text, 
case  resps  of 

(Return  Val:_J  -* 

AppendChan  "stdout"  Text  Val  ] 


Figure  4:  A  Haskell  program  that  types 
a  file  FOO  to  the  console 
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“states,”  because  this  would  contradict 
the  referential  transparency  of  FP. 

Other  papers  covered  the  union  of 
FP  and  OOP,  and  also  of  FP  and  logic 
programming,  the  paradigm  used  in 
Prolog.  The  latter  has  been  proved  pos¬ 
sible  by  Erik  Ruf,  an  ambitious  young 
researcher  from  Stanford  University. 
While  demonstrating  his  ability  to  speak 
close  to  the  speed  of  light,  he  pre¬ 
sented  an  extension  to  the  program¬ 
ming  language  Scheme.  Scheme  is  a 
deviation  of  Lisp  that  doesn’t  offer  lazy 
evaluation,  but  enforces  programming 
in  FP  style  for  subprograms  that  don’t 
rely  on  interactive  input/output  such 
as  compilers.  Ruf’s  extension,  Log- 


Scheme,  simulates  all  constructs  of 
Prolog,  including  unification  and  extra 
logical  features  such  as  “The  Cut.” 

Maybe  the  most  interesting  question 
from  the  conference  is  not,  “Should  I 
use  FP  or  OOP  or  logic  programming 
in  the  future?”  but  “Why  not  use  them 
all  together?” 

A  great  deal  of  the  presented  papers 
focused  on  the  difficulties  experienced 
during  the  implementation  of  FP  com¬ 
pilers.  Among  the  topics  were  the  ag¬ 
gregate  assignment  problem,  strictness 
analysis,  and  abstract  interpretation. 

Adrienne  Bloss  from  the  Virginia  Poly¬ 
technic  Institute  for  example,  worked 
on  the  aggregate  assignment  problem. 
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Aggregates  (that  is,  arrays  or  records) 
are  necessary  for  storing  huge  amounts 
of  data  in  an  uniform  way.  Because 
destructive  assignment  is  forbidden  in 
the  functional  programming  paradigm, 
how  do  I,  then,  “update”  an  array?  In 
theory,  the  solution  is  easy:  You  just 
have  to  define  an  “update  function.” 
The  following  example  looks  like 
Hope+  again,  but  because  this  language 
does  not  provide  arrays  at  all  (lists  are 
used  instead),  I  simply  invented  them 
for  the  sake  of  clarity: 

Thus,  let  ARRAY(T)  be  an  (open 
ended)  array  of  type  T.  The  update 
function  must  be  declared  like  this: 
TYPEVAR  T;  DEC  UPD:  ARRAY(T)  * 
NUM  #T~>  ARRAY(T); 

UPD(A,N,  V)  therefore  returns  a  copy 
of  the  array  A,  except  the  Mh  element 
is  replaced  by  V.  Obviously  this  in¬ 
volves  a  lot  of  copying  and  memory 
management  at  mn  time,  especially 
when  the  arrays  are  large.  In  fact,  this 
is  one  of  the  main  obstacles  when  writ¬ 
ing  efficient  FP  compilers.  Adrienne 
Bloss  investigates  the  possibility  of  do¬ 
ing  an  in-place-update  instead  of  copy¬ 
ing,  for  example,  a  destructive  assign¬ 
ment  of  Uto  the  Ath  element  of  A.  This 
is  not  always  safe.  In  the  context  LET 
A=some  array  IN  TOFILE(term_out,  UPD 
(A,  4, 155)),  the  previous  value  of  A  need 
not  be  kept  in  memory,  while  a  func¬ 
tion  call  like  F(UPD(A,  N1,V1),UPD- 
(A,  N2,  V2),  G(A)),  which  involves  some 
auxiliary  functions  Fand  G,  makes  copy¬ 
ing  necessary.  Of  course,  this  decision 
is  made  by  the  compiler.  The  program¬ 
mer  still  thinks  in  terms  of  functions 
free  from  side  effects. 

Another  problem  area  in  FP  is  strict¬ 
ness  analysis.  As  mentioned  earlier,  in¬ 
put/output  and  infinite  data  structures 
are  handled  by  lazy  (delayed)  evalu¬ 
ation.  This  works  fine  in  theory,  but 
produces  much  overhead  when  applied 
to  every  argument  of  every  function  in 
a  functional  program. 

To  optimize  the  code  produced,  the 
compiler  should  know  when  it  can 
safely  use  a  traditional,  non-lazy  pa¬ 
rameter  passing  mechanism.  Such  func¬ 
tion  parameters  are  called  “strict.”  Of 
course,  the  programmer  could  provide 
the  necessary  information.  But  this 
would  introduce  a  new  class  of  errors: 
Arguments  erroneously  declared  “strict” 
would  cause  the  program  to  loop  for¬ 
ever.  On  the  other  hand,  programmers 
themselves  are  “lazy”  and  tend  to  de¬ 
clare  more  arguments  lazy  than  neces¬ 
sary,  just  to  avoid  such  errors.  This 
would  lead  to  correct,  but  inefficient 
programs. 

Enter  strictness  analysis.  Here,  the 
compiler  tries  to  find  out  which  func¬ 
tion  arguments  can  safely  be  assumed 


to  be  strict  by  examining  the  source 
code.  This  is  not  an  easy  task,  because 
parameters  may  be  passed  through  to 
other  functions,  which  in  turn  must  be 
analyzed.  Most  problems  regarding  strict¬ 
ness  analysis  are  solved  now,  although 
not  always  in  an  optimal  way:  This 
kind  of  optimization  is  still  very  time 
consuming. 

A  tutorial  on  the  state-of-the-art  of 
abstract  interpretation  was  given  by  John 
Hughes,  also  a  co-author  of  the  Has¬ 
kell  programming  language.  He  defines 
abstract  interpretation  as  “a  compile¬ 
time  analysis  technique  to  predict  in¬ 
formation  about  a  program’s  behavior 
from  partial  information  about  its  in¬ 
puts.”  The  idea  behind  this  is  simple: 
The  more  the  compiler  knows  about 
the  program,  the  more  efficient  code 
may  be  produced.  A  typical  example 
is  the  SIGN  function:  SIGN(X)  is  de¬ 
fined  to  be  -1  for  negative  X  and  +1  for 
positive  X.  SIGN(O)  equals  zero. 

Suppose  a  program  contains  the  fol¬ 
lowing  function  definition  (the  “sharp” 
symbol,  #,  separates  the  function  pa¬ 
rameters): 

DEC  F:NUM  *  NUM— ♦  NUM; 

—  F(I  J)<=I*SIGN(I*J); 

Now  imagine  that  the  compiler  is  able 
to  prove  that  on  every  concrete  invoca¬ 
tion  of  function  F,  both  arguments  sup¬ 
plied  always  have  the  same  sign.  The 
compiler  then  can  conclude  that 
SIGN(I’J)  always  produces  +1  and  F 
therefore  reduces  to: 

DEC  F:NUM  *  NUM -*  NUM; 

—  F(IJ)<=I; 

As  a  next  step,  the  function  F  is  obvi¬ 
ously  not  necessary  at  all,  because  it 
does  not  perform  any  computation.  This 
means  that  no  code  for  F  is  generated, 
and  that  every  application  of,  say,  F(A,B) 
is  simply  replaced  by  its  first  argument, 
A.  The  conference  also  attracted  some 
researchers  from  other  areas  who  are 
normally  not  associated  with  functional 
programming  in  the  scientific  commu¬ 
nity.  Among  the  audience,  there  was 
for  instance  Professor  Tim  Teitelbaum 
of  Cornell  University.  Teitelbaum  be¬ 
came  quite  famous  due  to  his  work  on 
the  Cornell  Program  Synthesizer,  an 
integrated  program  development  sys¬ 
tem  that  analyzes  and  compiles  the  pro¬ 
gram  while  it  is  being  entered.  What 
motivated  Professor  Teitelbaum  to  make 
the  trip  to  Europe  and  show  interest  in 
an  entirely  different  subject? 

“The  work  with  the  synthesizer  gen¬ 
erator  is  motivated  by  an  interest  in 
incremental  computation,”  says  Tim 
Teitelbaum,  adding,  “In  the  past,  we 


have  used  attribute  grammars  for  this 
purpose.  But  attribute  grammars  are 
not  the  only  game  in  town.  A  lot  of 
people  consider  functional  programs 
a  more  natural  way  for  expressing  in¬ 
cremental  compilation.”  For  the  cur¬ 
rent  version  of  his  program  synthe¬ 
sizer,  Teitelbaum  and  his  students  al¬ 
ready  use  a  special  technique  derived 
from  FP  called  “memorization,”  where 
function  results  are  automatically  stored 
in  a  table  after  the  first  evaluation,  and 
retrieved  quickly  when  the  function 
happens  to  be  called  again  with  the 
same  argument. 

The  Future  of  Functional  Programming 

Clearly,  implementation  problems  are 
no  longer  stumbling  blocks.  Lazy  evalu¬ 
ation  is  a  commonly-used  technique, 
at  least  at  universities,  and  FP  systems 
perform  well  enough  to  be  used  for 
practical  purposes,  fast  workstations  and 
a  few  megabytes  of  memory  provided. 
This  contrasts  with  the  conference  held 
at  Nancy  four  years  ago,  where  only 
two  examples  of  very  special  industrial 
applications  were  mentioned. 

Despite  its  name,  this  year’s  FPCA 
covered  many  topics  on  functional  pro¬ 
gramming,  but  practically  none  on  com¬ 
puter  architecture.  This  is  surprising, 
because  parallelism  in  hardware  espe¬ 
cially  would  gain  a  lot  from  functional 
programming:  Due  to  referential  trans¬ 
parency,  all  arguments  to  a  function 
may  be  safely  evaluated  in  parallel  with¬ 
out  worrying  about  possible  conflicts. 
Despite  this,  the  resolution  of  many 
implementation  problems  has  obviously 
shifted  towards  a  software  instead  of 
hardware  solution. 

The  implications  of  this  fact  are  not 
yet  apparent.  Perhaps  most  researchers 
concentrate  on  sequential  machines  be¬ 
cause  those  are  available  today  and  in 
widespread  use.  The  opinions  are  not 
undivided,  however.  Tim  Teitelbaum, 
for  instance,  assumes  that,  “The  future 
will  be  dominated  by  parallel  architec¬ 
ture.  The  issue  of  how  to  program  such 
machines  is  still  very  open.  If  it  turns 
out  that  the  FP  people  really  have  the 
answer,  then  we  will  necessarily  switch 
over  to  functional  programming  in  or¬ 
der  to  get  the  benefits  of  the  parallel¬ 
ism.” 

The  next  conference,  FPCA  ’91,  will 
be  held  in  the  United  States.  At  that 
time,  the  first  version  of  Haskell  should 
be  up  and  running.  Maybe  the  revolu¬ 
tion  has  already  begun. 
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listing  One  (Listing  continued,  text  begins  on  page  1 7.) 

PROCEDURE  GraphNode. EraseAll; 

TYPE 

BEGIN 

GraphNode  = 

IF  SELF. Next  <>  NIL  THEN 

OBJECT (TObject) 

SELF. Next. EraseAll;  {  Erase  next  GraphNode  ) 

Next:  GraphNode; 

SELF. Erase;  |  Erase  this  GraphNode  ) 

HotRegion:  RgnHandle; 

END; 

PROCEDURE  Initialize; 

PROCEDURE  GraphNode . SetRegion; 

{  Drawing  Methods  } 

BEGIN 

PROCEDURE  Draw; 

IF  SELF. HotRegion  <>  NIL  THEN  (  Drop  old  Region  ) 

PROCEDURE  DrawAll; 

DisposeRgn (SELF. HotRegion) ; 

PROCEDURE  Erase; 

SELF. HotRegion  :=  NewRgn;  (  Allocate  a  new  one  ) 

PROCEDURE  EraseAll; 

END; 

(  Location  Methods  } 

PROCEDURE  SetRegion; 

FUNCTION  GraphNode. PtlnNode (Where:  Point):  Boolean; 

FUNCTION  PtlnNode (Where:  Point):  Boolean; 

BEGIN 

FUNCTION  FindNode (Where:  Point):  GraphNode; 

IF  PtlnRgn (Wh6re,  SELF. HotRegion)  THEN 

FUNCTION  Connected (Which:  GraphNode):  Boolean; 

PtlnNode  :=  True 

FUNCTION  FindConnected (Which:  GraphNode):  GraphNode; 

ELSE 

{  Freeing  Methods  ) 

PtlnNode  :=  False; 

PROCEDURE  Free;  OVERRIDE; 

PROCEDURE  FreeAll; 

END; 

END; 

FUNCTION  GraphNode. FindNode (Where:  Point):  GraphNode; 

BEGIN 

GraphList  = 

IF  SELF. PtlnNode (Where)  THEN  (  It's  here  ) 

OBJECT (TObject) 

FindNode  :=  SELF 

FirstNode:  GraphNode; 

ELSE  IF  SELF. Next  =  NIL  THEN  (  There  are  none  ) 

PROCEDURE  Initialize; 

FindNode  :=  NIL 

(  Drawing  Methods  ) 

ELSE  |  Try  the  Next  ) 

PROCEDURE  Erase; 

FindNode  :=  SELF. Next .FindNode (Where) ; 

PROCEDURE  Draw; 

END; 

{  GraphList  Manipulation  Methods  ) 

PROCEDURE  AddNode (Which:  GraphNode); 

FUNCTION  GraphNode. Connected (Which:  GraphNode):  Boolean; 

PROCEDURE  Remo veNode (Which:  GraphNode); 

BEGIN 

(  Location  Methods  T 

Connected  :=  False; 

FUNCTION  FindNode (Where:  Point):  GraphNode; 

FUNCTION  FindConnected (Which:  GraphNode):  GraphNode; 

END; 

{  Freeing  Methods  ) 

FUNCTION  GraphNode. FindConnected (Which:  GraphNode):  GraphNode; 

PROCEDURE  Free;  OVERRIDE; 

BEGIN 

END; 

IF  SELF. Connected (Which)  THEN  (  Is  this  connected  } 

FindConnected  :=  SELF 

Vertex  = 

ELSE  IF  SELF. Next  =  NIL  THEN  (  There  are  none  ) 

OBJECT (GraphNode) 

FindConnected  :=  NIL 

Center:  Point;  (  Location  of  Vertex  ) 

ELSE  (  Try  the  Next  ) 

PROCEDURE  Initialize;  OVERRIDE; 

FindConnected  :=  SELF. Next .FindConnected (Which) ; 

(  Drawing  Methods  ) 

END; 

PROCEDURE  Draw;  OVERRIDE; 

PROCEDURE  Erase;  OVERRIDE; 

PROCEDURE  GraphNode. Free; 

(  Location  Methods  ) 

BEGIN 

PROCEDURE  SetRegion;  OVERRIDE; 

IF  SELF . HotRegion  <>  NIL  THEN  (  Free  Region  Space  ) 

PROCEDURE  SetCenter (thePoint:  Point); 

DisposeRgn (SELF . HotRegion) ; 

END; 

SELF. Erase;  (  Erase  then  Free  ) 

INHERITED  Free; 

Edge  = 

END; 

OBJECT (GraphNode ) 

FromVertex:  Vertex;  (  End  Points  of  Edge  } 

PROCEDURE  GraphNode. FreeAll; 

ToVertex:  Vertex; 

BEGIN 

PROCEDURE  Initialize;  OVERRIDE; 

IF  SELF. Next  <>  NIL  THEN  (  Free  the  next  GraphNode  ) 

(  Drawing  Methods  ) 

SELF. Next. FreeAll; 

PROCEDURE  Draw;  OVERRIDE; 

SELF. Free;  (  Then  Free  this  GraphNode  ) 

PROCEDURE  Erase;  OVERRIDE; 

END; 

{  Location  Methods  ) 

PROCEDURE  SetRegion;  OVERRIDE; 

(  -  GraphList  Methods  -  ) 

FUNCTION  Connected (Which:  GraphNode):  Boolean; 

PROCEDURE  GraphList . Initialize; 

OVERRIDE; 

BEGIN 

PROCEDURE  Edge. SetFrom (Which:  Vertex); 

SELF. FirstNode  :=  NIL; 

PROCEDURE  Edge. SetTo (Which:  Vertex); 

END; 

END; 

PROCEDURE  GraphList. Erase; 

Graph  = 

BEGIN 

OBJECT (TObject) 

IF  SELF. FirstNode  <>  NIL  THEN 

VertexList:  GraphList; 

SELF. FirstNode. EraseAll;  (  Erase  the  GraphList  ) 

EdgeList:  GraphList; 

PROCEDURE  Initialize; 

END; 

{  Drawing  Methods  } 

PROCEDURE  GraphList . Draw; 

PROCEDURE  Draw; 

BEGIN 

PROCEDURE  Erase; 

IF  SELF. FirstNode  <>  NIL  THEN 

[  Manipulation  Routines  ) 

SELF. FirstNode. DrawAll;  (  Draw  the  GraphList  } 

PROCEDURE  AddVert ex (Where:  Point); 

PROCEDURE  AddEdge (FromWhich,  ToWhich:  Vertex); 

END; 

PROCEDURE  RemoveVertex (Where:  Point); 

PROCEDURE  GraphList .AddNode (Which:  GraphNode); 

PROCEDURE  RemoveEdge (Where:  Point); 

BEGIN 

PROCEDURE  SetVert exCenter 

Which. Next  :=  SELF . FirstNode;  (  Link  Which  in  GraphList  ) 

(Which:  Vertex;  Where:  Point); 

SELF. FirstNode  :=  Which; 

(  Macintosh  Support  Routines  ) 

END; 

PROCEDURE  MoveVertex (Start:  Point); 

PROCEDURE  LinkVertices (Start:  Point); 

PROCEDURE  GraphList . RemoveNode (Which :  GraphNode); 

{  Freeing  Method  ) 

PROCEDURE  Free;  OVERRIDE; 

VAR 

END; 

Check:  GraphNode; 

BEGIN 

(  -  GraphNode  Methods  -  ) 

(  If  it  is  the  head  GraphNode,  relink  the  Head  ) 

PROCEDURE  GraphNode . Initialize; 

IF  SELF. FirstNode  =  Which  THEN 

BEGIN 

SELF. FirstNode  :=  Which. Next 

SELF. Next  :=  NIL; 

ELSE  BEGIN 

SELF. HotRegion  :=  NIL; 

(  Otherwise  look  for  Which  GraphNode  ) 

END; 

Check  :=  SELF. FirstNode; 

PROCEDURE  GraphNode. Draw; 

BEGIN 

(  If  Which  is  found,  remove  it  from  GraphList 

) 

END; 

IF  Check. Next  =  Which  THEN 

PROCEDURE  GraphNode. DrawAll; 

BEGIN 

IF  SELF. Next  <>  NIL  THEN 

END; 

SELF. Next .DrawAll;  (  Draw  next  GraphNode  } 

SELF. Draw;  {  Draw  this  GraphNode  } 

END; 

END; 

PROCEDURE  GraphNode. Erase; 

FUNCTION  GraphList . FindNode (Where :  Point):  GraphNode; 

BEGIN  (  Find  the  Node  at  this  location  ) 

IF  SELF. FirstNode  <>  NIL  THEN 
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FindNode  :=  SELF. FirstNode. FindNode (Where) 
FindNode  :=  NIL; 


END; 


FUNCTION  GraphList.FindConnected(Which:  GraphNode) :  GraphNode; 

BEGIN  (  Find  the  Node  connected  to  this  one  ) 

IF  SELF.FirstNode  <>  NIL  THEN 

FindConnected  :=  SELF. FirstNode.FindConnected (Which) 

ELSE 

FindConnected  :=  NIL; 

END; 

PROCEDURE  GraphList . Free; 

BEGIN 

IF  SELF.FirstNode  <>  NIL  THEN 

SELF.FirstNode.FreeAll;  (  Free  the  Nodes  ) 

INHERITED  Free;  (  Free  GraphList  } 

END; 


(  -  Vertex  Methods  - 

PROCEDURE  Vertex. Initialize; 

BEGIN 

INHERITED  Initialize; 
SELF. Center. h  :=  0; 
SELF. Center. v  :=  0; 

END; 

PROCEDURE  Vertex. Draw; 

VAR 


} 


theRect:  Rect; 

SELF. Erase;  (  Erase  Vertex  Area  ) 

{  Set  up  Rectangle  } 
theRect. top  :=  SELF. Center. v  -  10; 
theRect. left  :=  SELF. Center. h  -  10; 
theRect .bottom  :=  SELF. Center .v  +  10; 
theRect .right  :=  SELF. Center. h  +  10; 

{  Draw  Vertex  ) 

FrameOval (theRect) ; 


PROCEDURE  Vertex. Erase; 
VAR 


theRect:  Rect; 

(  Set  up  Rectangle  ) 
theRect. top  :=  SELF. Center .v  -  10; 
theRect. left  :=  SELF. Center. h  -  10; 
theRect .bottom  :=  SELF. Center. v  +  10; 
theRect . right  :=  SELF. Center .h  +  10; 

(  Erase  Vertex  ) 

EraseOval (theRect) ; 


PROCEDURE  Vertex. SetRegion; 
BEGIN 


END; 


INHERITED  SetRegion;  (  Do  default  processing  ) 
OpenRgn;  1  Create  new  region  area  ) 

SELF. Draw; 

CloseRgn(SELF.HotRegion) ; 


PROCEDURE  Vertex. SetCenter (thePoint :  Point); 

BEGIN 

SELF. Erase;  (  Erase  Vertex  at  old  Center  ) 

SELF. Center  :=  thePoint;  {  Set  the  Center  ) 

SELF. Draw;  {  Draw  Vertex  at  new  Center  ) 

SELF. SetRegion;  (  Reset  HotRegion  | 

END; 

(  - Edge  Methods  -  ) 

PROCEDURE  Edge. Initialize; 

BEGIN 

INHERITED  Initialize; 

FromVertex  :=  NIL; 

ToVertex  :=  NIL; 

END; 

PROCEDURE  Edge. Draw; 

VAR 

Where:  Point; 

BEGIN 

IF  (SELF. FromVertex  <>  NIL)  AND  (SELF. ToVertex  <>  NIL)  THEN  BEGIN 
(  Start  in  center  of  FromVertex  } 

Where  :=  SELF.FromVertex.Center; 

MoveTo (Where . h,  Where. v); 

(  Draw  line  to  center  of  ToVertex  } 

Where  :=  SELF.ToVertex.Center; 

LineTo (Where .h,  Where. v)  ; 


END; 


END; 


PROCEDURE  Edge. Erase; 
VAR 


pnState:  PenState; 

GetPenState (pnState) ;  (  Save  current  settings  ) 
PenPat (white) ;  f  Set  color  &  Draw  to  erase  ) 

SELF. Draw; 

SetPenState (pnState) ;  (  Reset  settings  ) 

SELF. FromVertex. Draw;  (  Redraw  affected  Vertices  ) 
SELF . ToVertex . Draw; 


END; 


PROCEDURE  Edge. SetRegion; 

BEGIN 

INHERITED  SetRegion;  (  Do  default  processing  ) 
OpenRgn;  {  Create  new  region  area  } 


MoveTo (SELF. FromVertex. Center. h  ■ 


SELF. FromVertex. 
Center.v  +  4)  ; 

LineTo(SELF. ToVertex. Center. h  +  4,  SELF.ToVertex.Center .v  + 
4); 

LineTo (SELF. ToVertex. Center. h  -  4,  SELF.ToVertex.Center .v  - 
4)  ; 

LineTo (SELF. FromVertex. Center. h  -  4, 
SELF.FromVertex.Center .v  -  4); 

LineTo (SELF.FromVertex.Center .h  +  4, 
SELF.FromVertex.Center .v  +  4); 

CloseRgn (SELF . HotRegion) ; 

END; 

FUNCTION  Edge. Connected (Which:  GraphNode):  Boolean; 

BEGIN 

IF  (SELF. FromVertex  =  Which)  OR  (SELF. ToVertex  =  Which)  THEN 
Connected  :=  True 

ELSE 

Connected  :=  False; 

END; 

PROCEDURE  Edge. SetFrom (Which:  Vertex); 

BEGIN 

IF  (SELF. FromVertex  <>  NIL)  AND  (SELF. ToVertex  <>  NIL)  THEN 

BEGIN 

(  Erase  old  edge  and  redraw  unlinked  Vertex  } 

SELF. Erase; 

SELF . FromVertex . Draw ; 

END; 

SELF. FromVertex  :=  Which; 

IF  (SELF. FromVertex  <>  NIL)  AND  (SELF. ToVertex  <>  NIL)  THEN 

BEGIN 

(  Draw  new  edge  and  redraw  linked  Vertices  ) 

SELF. Draw; 

SELF. FromVertex. Draw; 

SELF. ToVertex. Draw; 

SELF. SetRegion;  (  Reset  HotRegion  ) 


PROCEDURE  Edge. SetTo (Which:  Vertex); 

BEGIN 

IF  (SELF. FromVertex  <>  NIL)  AND  (SELF. ToVertex  <>  NIL)  THEN 

BEGIN 

(  Erase  old  edge  and  redraw  unlinked  Vertex  ) 

SELF. Erase; 

SELF . ToVertex . Draw; 

END; 

SELF. ToVertex  :=  Which; 

IF  (SELF. FromVertex  <>  NIL)  AND  (SELF. ToVertex  <>  NIL)  THEN 

BEGIN 

(  Draw  new  edge  and  redraw  linked  Vertices  ) 

SELF. Draw; 

SELF . FromVertex . Draw; 

SELF. ToVertex. Draw; 

SELF. SetRegion;  (  Reset  HotRegion  ) 

END; 

END; 


(  -  Graph  Methods  -  ) 

PROCEDURE  Graph. Initialize; 

BEGIN 

New (SELF. VertexList) ; 

SELF. VertexList . Initialize; 

New (SELF. EdgeList) ; 
SELF.EdgeList . Initialize; 

END; 

PROCEDURE  Graph. Draw; 

BEGIN 

IF  SELF.EdgeList  <>  NIL  THEN 
SELF . EdgeList . Draw; 

IF  SELF. VertexList  <>  NIL  THEN 
SELF. VertexList .Draw; 

END; 

PROCEDURE  Graph. Erase; 

BEGIN 

SELF . EdgeList . Erase; 

SELF. VertexList .Erase; 

END; 

PROCEDURE  Graph. AddVertex (Where:  Point); 

VAR 

NewVertex:  Vertex; 


(  Create  and  initialize  a  new  Vertex  at  Where  ) 
New (NewVertex) ; 

NewVertex. Initialize; 

NewVertex. SetCenter (Where) ; 

{  Add  new  vertex  to  list,  typecasting  is  required 
SELF. VertexList . AddNode (GraphNode (NewVertex) )  ; 


END; 


PROCEDURE  Graph. RemoveVertex (Where:  Point); 

VAR 

WhichEdge:  GraphNode; 

WhichVertex:  GraphNode; 

BEGIN 

(  Find  the  appropriate  Node  ) 

WhichVertex  :=  SELF. VertexList .FindNode (Where)  ; 

(  If  it  exists. . .  } 

IF  WhichVertex  <>  NIL  THEN  BEGIN 
REPEAT 

(  Find  Edges  Connected  to  the  Vertex  ) 
WhichEdge  := 

SELF . EdgeList . FindConnected (WhichVertex) ; 
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Listing  One  ( Listing  continued,  text  begins  on  page  17) 

(  If  an  Edge  exists,  remove  it  } 

IF  WhichEdge  <>  NIL  THEN 

SELF.EdgeList .RemoveNode (WhichEdge) ; 
UNTIL  (WhichEdge  =  NIL) ; 

(  Finally,  remove  the  Vertex  } 

SELF . VertexList . RemoveNode ( WhichVertex ) ; 

END; 

END; 

PROCEDURE  Graph . AddEdge (FromWhich,  ToWhich:  Vertex); 

VAR 

NewEdge :  Edge  ; 

BEGIN 

{  Create  and  initialize  a  new  Vertex  at  Where  ) 

New (NewEdge) ; 

NewEdge . Initialize; 

NewEdge. SetFrom (FromWhich) ; 

NewEdge . SetTo (ToWhich) ; 

{  Add  new  vertex  to  list,  typecasting  is  required  } 
SELF.EdgeList .AddNode (GraphNode (NewEdge) ) ; 

END; 

PROCEDURE  Graph . RemoveEdge (Where :  Point ) ; 

VAR 

WhichEdge:  GraphNode; 

BEGIN 

(  Find  the  appropriate  Node  } 

WhichEdge  :=  SELF.EdgeList .FindNode (Where) ; 

{  If  it  exists,  remove  it  ) 

IF  WhichEdge  <>  NIL  THEN 

SELF.EdgeList. RemoveNode (WhichEdge) ; 

END; 


Center  :  Point  ; 
Radius  :  Integer  ; 

(  Methods  ) 
Procedure  Draw  ; 
Procedure  Erase  ; 


(  The  Center  of  the  Circle  ) 
(  The  Radius  of  the  Circle  } 

(  Draw  the  Circle  ) 

{  Erase  the  Circle  ) 


end  ; 

Procedure  Circle. Draw  ; 

Var 

theRect  :  Rect  ;  {  Rectangular  area  of  the  Circle  } 

Begin 

(  Set  up  the  Rectangle  ) 
theRect. top  :=  SELF. Center .v  -  SELF. Radius  ; 
theRect. left  :=  SELF. Center .h  -  SELF. Radius  ; 
theRect .bottom  :=  SELF. Center .v  +  SELF. Radius  ; 
theRect . right  :=  SELF.Cener.h  +  SELF. Radius  ; 

FrameOval  (theRect)  ;  (  Draw  it  } 


End  ; 

Procedure  Circle. Erase  ; 

Var 

theRect  :  Rect  ;  (  Rectangular  area  of  the  Circle  } 

Begin 

(  Set  up  the  Rectangle  } 
theRect. top  :=  SELF. Center. v  -  SELF. Radius  ; 
theRect. left  :=  SELF. Center .h  -  SELF. Radius  ; 
theRect. bottom  :=  SELF. Center .v  +  SELF. Radius  ; 
theRect . right  :=  SELF.Cener.h  +  SELF. Radius  ; 


EraseOval  (theRect) 

End  ; 


(  Era. 


se  it  ) 


End  Listing  Two 


PROCEDURE  Graph. SetVertexCenter (Which:  Vertex;  Where:  Point); 

VAR 

anEdge:  Edge; 

BEGIN 

(  Move  through  the  EdgeList  finding  Connected  Instances) 
anEdge  :=  Edge (SELF. EdgeList .FindConnected (GraphNode (Which) )) ; 
WHILE  (anEdge  <>  NIL)  DO  BEGIN 

anEdge. Erase;  (  Erase  them  and  move  on  ) 

IF  anEdge. Next  <>  NIL  THEN 
anEdge  : = 

Edge (anEdge .Next .FindConnected (GraphNode (Which) ) ) 

ELSE 

anEdge  :=  NIL; 

END; 

Which. SetCenter (Where) ;  (  Set  the  Vertex  instance's  center  ) 

{  Move  through  the  EdgeList  finding  Connected  Instances) 
anEdge  :=  Edge (SELF.EdgeList . FindConnected (GraphNode (Which) ) ) ; 
WHILE  (anEdge  <>  NIL)  DO  BEGIN 

anEdge. Draw;  {  Draw  them  and  their  vertices;  move  on  ) 
anEdge . FromVertex . Draw; 
anEdge . ToVertex . Draw; 

IF  anEdge. Next  <>  NIL  THEN 
anEdge  := 

Edge (anEdge. Next .FindConnected (GraphNode (Which) ) ) 

ELSE 

anEdge  :=  NIL; 

END; 

END; 

PROCEDURE  Graph. MoveVertex (Start :  Point); 

VAR 

Displacement:  Point; 

NewCenter:  Point; 

WhichVertex:  Vertex; 

BEGIN 

WhichVertex  :=  Vertex (SELF. VertexList . FindNode (Start )) ; 

(  If  the  vertex  is  moved,  find  the  new  center  and 

place  the  Vertex  and  redraw  affected  Edges  ) 

IF  WhichVertex  <>  NIL  THEN 

IF  DragRegion (WhichVertex. HotRegion,  Start,  Displacement . h, 
Displacement. v)  THEN  BEGIN 
NewCenter  :=  WhichVertex. Center; 

AddPt (Displacement,  NewCenter) ; 

SELF. SetVertexCenter (WhichVertex,  NewCenter) ; 

END; 

END; 


PROCEDURE  Graph . LinkVertices (Start :  Point); 
VAR 


THEN 


FirstVertex:  Vertex; 

LastVertex:  Vertex; 

Stop:  Point; 

BEGIN 

(  Find  the  FromVertex  ) 

FirstVertex  :=  Vertex (SELF. VertexList .FindNode (Start) ) ; 

IF  FirstVertex  <>  NIL  THEN  BEGIN 

DragGrayLine (Start,  Stop);  {  Drag  a  line  around  ) 

1  Find  the  ToVertex  ) 

LastVertex  :=  Vertex (SELF. VertexList . FindNode (Stop) )  ; 
IF  (LastVertex  <>  NIL)  AND  (FirstVertex  <>  LastVertex) 


END; 

END; 


SELF. AddEdge (FirstVertex,  LastVertex) ; 


PROCEDURE  Graph. Free; 

BEGIN 

SELF . EdgeList .Free; 
SELF .VertexList .Free; 
INHERITED  Free; 

END; 


End  Listing  One 


Listing  Two 

Type 

Circle  =  Object  (TObject)  {  The  Circle  class  declaration  ) 

f  Instance  Variables  ( 


Listing  Three 


Program  DrawtheCircle  ; 

<  Circle's  type  declaration  > 
Var 

aCircle  :  Circle  ; 

<  Circle's  method  definitions  > 
Begin 

new(aCircle)  ; 

aCircle. Center .h  :=  50  ; 
aCircle. Center .v  :=  50  ; 
aCirlce. Radius  :=  50  ; 

aCircle. Draw  ; 
aCircle. Free  ; 

End. 


{  Get  a  new  instance  ) 

(  Set  up  instance  variables  } 

I  Draw  it  and  free  it  ) 


End  Listing  Three 


Listing  Four 


Type 

Circle  =  Object  (TObject)  (  The  Circle  class  declaration  ) 

(  Instance  Variables 


Center  :  Point  ; 

Radius  :  Integer  ; 

{  Methods  } 
Procedure  Draw  ; 

Procedure  Erase  ; 
Procedure  Free  ;  Override 

end  ; 

Procedure  Circle. Draw  ; 
as  before 

Procedure  Circle. Erase  ; 
as  before 

Procedure  Cirlce.Free  ; 

Begin 

SELF. Erase  ; 

Inherited  Free  ; 

End  ; 


(  The  Center  of  the  Circle  ( 

(  The  Radius  of  the  Circle  ) 

(  Draw  the  Circle  ) 

(  Erase  the  Circle  } 

;  (  The  Free  method  needs  changes  I 


End  Listing  Four 


Listing  Five 

Type 

DrawObject  =  Object  (TObject)  (  The  DrawObject  class  declaration  ) 

(  Instance  Variables  ) 

Location  :  Point  ;  (  The  location  of  the  Object  ) 

(  Methods  ) 

Procedure  Draw  ;  {  Draw  the  Object  ) 

Procedure  Erase  ;  {  Erase  the  Object  ) 

Procedure  Offset  (dh,  dv  :  Integer)  ;  [  Offset  Object  by  dh,  dv  ) 
Procedure  Free  ;  Override  ;  (  The  Free  method  needs  changes  ) 

end  ; 

Circle  =  Object  (DrawObject)  f  The  Circle  class  declaration  ) 

(  Instance  Variables  ) 

Radius  :  Integer  ;  {  The  Radius  of  the  Circle  ) 

{  Methods  ) 

Procedure  Draw  ;  Override  ;  {  Draw  the  Circle  ) 

Procedure  Erase  ;  Override  ;  {  Erase  the  Circle  ) 

end  ; 

Rectangle  =  Object  (DrawObject)  (  The  Rectangle  class  declaration  } 

(  Instance  Variables  ) 

(continued  on  page  111) 
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Listing  Five  (Listing  continued,  text  begins  on  page  1 7.) 

horSize  :  Integer  ;  {  The  Horizontal  Size  of  the  Rectangle  } 
verSize  :  Integer  ;  {  The  Verical  Size  of  the  Rectangle  ) 

(  Methods  ) 

Procedure  Draw  ;  Override  ;  (  Draw  the  Rectangle  } 

Procedure  Erase  ;  Override  ;  {  Erase  the  Rectangle  ) 

end  ; 

{  -  The  DrawObject  Methods  -  } 

Procedure  DrawObject  .Draw  ; 

Begin 
End  ; 

Procedure  DrawObject  .Erase  ; 

Begin 
End  ; 

Procedure  DrawObject  .Offset  (dh,  dv  :  Integer)  ;  {  Offset  Object  by  dh,  dv  } 
Begin 

SELF. Erase  ;  {  Erase  Object  at  its  present  location  ) 

{  Change  the  location  of  the  Object  ) 

SELF. Location. h  :=  SELF. Locat ion. h  +  dh  ; 

SELF. Location. v  :=  SELF. Locat ion. v  +  dv  ; 

SELF. Draw  ;  {  Draw  Object  at  its  new  location  } 

End  ; 

Procedure  DrawObject .Free  ; 

Begin 

SELF. Erase  ; 

Inherited  Free  ; 

End  ; 

{  - The  Circle  Methods -  } 

Procedure  Circle. Draw  ; 
as  before 

Procedure  Circle. Erase  ; 
as  before 

(  -  The  Rectangle  Methods  -  ) 

Procedure  Rectangle  .Draw  ; 

Var 

theRect  :  Rect  ;  {  Rectangular  area  of  the  Circle  ) 

Begin 

{  Set  up  the  Rectangle  ) 
theRect. top  :=  SELF. Location. v  ; 
theRect. left  :=  SELF. Locat ion. h  ; 
theRect .bottom  :=  SELF. Locat ion. v  +  SELF. verSize  ; 
theRect . right  :=  SELF. Location. h  +  SELF. horSize  ; 

FrameRect  (theRect)  ;  {  Draw  it  ) 

End  ; 

Procedure  Circle. Erase  ; 

Var 

theRect  :  Rect  ;  (  Rectangular  area  of  the  Circle  ) 

Begin 

{  Set  up  the  Rectangle  } 
theRect. top  :=  SELF. Locat ion. v  ; 
theRect. left  SELF. Location. h  ; 

theRect .bottom  :=  SELF. Location. v  +  SELF. verSize  ; 
theRect . right  :=  SELF. Location. h  +  SELF. horSize  ; 

EraseRect  (theRect)  ;  (  Draw  it  ) 

End  ; 


End  listings 


ACTOR 


Listing  One  (Text  begins  on  page  28.) 

/*  header  file  for  RegularExpression  class  */ 

♦define  ANYCHAR  1  /*  "A  */ 

♦define  A_CHAR  3  /*  AC  */ 

♦define  BEGIN_STR  2  /*  AB  */ 

♦define  END_STR  5  /*  AE  */ 

♦define  INCLUDE_SET  19  /*  AS  */ 

♦define  OMIT  SET  14  /*  AN  */ 


End  listing  One 


Listing  Two 

*  REGULARE.CLS:  RegularExpression  class  file  * 

/*  Class  used  to  hold  regular  expressions  for  string 
matching.  */!! 

inherit (Object,  IRegularExpression,  #( 

pattern  /*  a  pattern  to  match  */ 

caseMatch  /*  nil,  case  doesn't  matter  */ 

arrow  /*  used  to  scan  strings  */ 

cursor  /*  used  to  scan  patterns  */),  2,  nil)!! 

now (RegularExpressionClass) ! ! 

/*  Create  a  new  RegularExpression  from  String  s.  */ 
Def  new (self,  s  :  re) 

(  re  :=  init (new(self :Behavior) ) ; 
re. pattern  :=  makePattern (re,  s) ; 

Are; 


now (RegularExpression) ! ! 

/*  Change  every  occurrence  of  string  s  matching  the  pattern  to  string  t. 

Does  not  allow  recursion:  searching  occurs  after  the  new  string  has  been 
substituted.  The  target  string  t  is  not  a  pattern,  just  another  string, 
inserted  into  the  source  string  at  the  point  of  the  match.  Returns  the 
changed  source  string  s  */ 

Def  change (self,  s,  t  1  from,  last,  source) 

|  source  := 
if  caseMatch 
then  asUpperCase (s) ; 
else  s 
endif ; 
from  :=  0; 
loop 

while  from  <  size  (source) 
begin  last  :=  aMatch(self,  source,  from) ; 
if  last 

then  s  :=  replace (s,  t,  0,  size(t),  from,  last); 

from  :=  from  +  size(t); 
else  from  :=  from  +  1; 
endif; 
endLoop; 

As; 

I!  ! 

/*  Set  case  matching.  Converts  pattern  tc  upper-case,  too.  You  should 
save  the  old  pattern  if  you  plan  on  toggling  case  matching  a  lot.*/ 

Def  setCaseMatch (self ,  c) 

(  caseMatch  :=  c; 
if  caseMatch 

then  pattern  :=  asUpperCase (pattern) ; 
endif; 

Aself ; 

}!  ! 

/*  Match  the  String  s  against  the  pattern.  Calls  aMatchO  for  each 

possible  substring  in  the  String.  If  caseMatch  flag  is  set,  then  fold  case 
to  upper  before  doing  the  search.  */ 

Def  match(self,  s) 

(  if  caseMatch 
then  s  :=  asUpperCase  (s) ; 
endif; 
do (size (s) , 

(using  (i) 

if  aMatchfself,  s,  i) 
then  Ai; 
endi f ; 

)); 

Afalse; 

)!! 

/*  Compare  string  s  against  pattern  starting  at  position  from.  Makes 
successive  calls  to  oneMatch.  Returns  index  of  matching  character,  or 
nil.  Remember  that  oneMatch ()  advances  the  arrow  in  the  source  string.  */ 
Def  aMatch(self,  s,  from  !  found) 

(  arrow  :=  from; 
cursor  :=  0; 
found  :=  true; 
loop 

while  found  cand  (cursor  <  size (pattern) ) 
begin 

if  oneMatch (self ,  s) 

then  cursor  :=  cursor  +  patternSize (self ,  cursor); 
else  Afalse; 
endif; 
endLoop; 

Aarrow; 
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/*  Match  a  single  character  passed  as  an  argument  to  the  set  pointed  to  by 
the  pattern  cursor.  Returns  nil  if  not  in  the  set,  otherwise  non-nil.  */ 
Def  locate (self,  c  I  setSize,  fromCurs,  toCurs,  found) 

(  setSize  :=  aslnt (pattern [cursor+1] ) ; 
fromCurs  :=  cursor  +  2; 
toCurs  :=  fromCurs  +  setSize; 
found  :=  false; 
do (over (fromCurs,  toCurs), 

(using(i) 

if  pattern[i]  =  c 
then  found  :=  true; 
end if ; 

}); 

'found; 

1 !  1 

/*  Match  a  single  character  in  the  target  string  against  a  single 

character  in  the  pattern.  Returns  nil  or  non-nil.  Also  advances  arrow 
scanning  target  string  */ 

Def  oneMatch (self ,  s  !  next,  c) 

(  next  :=  -1; 

if  arrow  <  size(s) 
then  c  :=  aslnt (pattern [cursor] ) ; 
select 

case  c  =  ANY_CHAR 
is  next  :=  1; 
endCase; 

case  c  =  BEGIN_STR 
is 

if  arrow  :=  0 
then  next  :=  0; 
endif; 
endCase; 
case  c  =  A_CHAR 
is 

if  s[arrow]  =  pattern [cursor+1 ] 
then  next  :  =  1; 
endif; 
endCase; 

case  c  =  INCLUDE_SET 
is 

if  locate(self,  s(arrow)) 
then  next  :=  1; 
endif; 
endCase 

case  c  =  OMIT_SET 
is 

if  not (locate (self ,  s[arrow])) 
then  next  :=  1; 
endif; 
endCase 
endSelect  ; 

else  /*  at  end  of  string,  check  for  $  */ 
if  aslnt (patternfcursor] )  =  END_STR 
then  next  :=  0; 
endif; 
endif; 

if  next  >=  0 

then  arrow  :=  arrow  +  next; 
endif; 

' (next  >=  0) ; 

}!  ! 

/*  Get  the  pattern  String  from  a  Regular  Expression.  */ 

Def  pattern (self ) 

1  'pattern; 

)!  ! 

/*  Set  the  pattern  String  in  a  RegularExpression .  */ 

Def  setPattern (self ,  s) 

{  pattern  :=  s; 

'self ; 

)M 

/*  Initialize  a  RegularExpression.  */ 

Def  init(self) 

I  'self; 

I  !  ! 

/*  Return  the  size  of  the  Pattern  from  position  p.  */ 

Def  patternSize (self ,  p  !  c) 

(  c  :=  aslnt (pattern [p] ) ; 
select 

case  c  =  A_CHAR 
is  '2; 
endCase; 

case  c  =  ANY_CHAR  cor  c  =  BEGIN_STR  cor  c  =  END_STR 

is  '1; 

endCase; 

case  c  =  14  cor  c  =  19 
is  'aslnt (pattern[p+l]+2) ; 
endCase; 
default  '1; 
endSelect; 

) !  ! 

/*  Return  a  set  of  characters  for  inclusion  in  a  Pattern.  The  first  and 

last  characters  should  be  [  and  ] .  Returns  INCLUDE_SET  for  set  or  OMIT_SET 
for  exluded  set,  followed  by  a  count  of  the  characters  in  the  set  (just  a 
single  character),  followed  by  the  characters  themselves.  */ 

Def  f illSet (self ,  s  I  work,  i,  count,  from,  to) 

{  i  :  =  1; 

count  :=  0; 
if  s(i]  = 

then  work  :=  asString (asChar (OMIT_SET) ) ; 
i  :=  i  +  1; 

else  work  :=  asString (asChar (INCLUDE_SET) ) ; 
endif; 

work  :=  work+asString (asChar (1) ) ;  /*  holds  count  later  */ 
loop 


while  i  <  size(s)  and  s[i)  <>  ']' 
begin 
select 

case  s[i]  =  'V 

is  work  :=  work  +  asString  (s [i+1] ) ; 
i  :=  i  +  2; 
count  :=  count  +  1; 
endCase; 
case  s[i]  =  '-' 
is  from  :=  aslnt  (s [i-1] ) +1; 
to  ;=  aslnt (s[i+l) ) +1; 
do (over (from,  to), 

| using (c)  work :=work+asString (asChar (c) ) ; 

}); 

i  :=  i  +  2; 
endCase; 

default  work  :=  work  +  asString (s [i] ) ; 
i  :=  i  +  1; 
count  :=  count  +  1; 
endSelect; 
endLoop ; 

work[l]  :=  asChar (count) ; 

'work; 

M! 

/*  Convert  a  normal  String  into  a  pattern  String.  Note  that  it  does  not\lt\ 
set  the  Regular-Expression's  instance  variable.  */ 

Def  makePattern(self ,  s  I  work,  c,  i,  j) 

[  work  := 
i  :=  0; 
loop 

while  i  <  size(s) 
begin  c  :=  s [i] ; 
select 

case  c  =  '?' 

is  work  :=  work+asString (asChar (ANY_CHAR) ) ; 

i  :  =  i  +  1  ; 
endCase; 
case  c  =  '  %' 

is  work  :=  work+asString (asChar (BEGIN_STR) ) ; 

i  :=  i  +  1; 
endCase; 
case  c  =  '$' 

is  work  :=  work+asString (asChar (END_STR) ) ; 

i  :=  i  +  1; 
endCase; 
case  c  =  ' [ ' 

is  j  :=  indexOf(s,  ']',  i+1); 

work  :=  work  +  fillSet (self ,  subString(s,  i,  j  + 1 ) ) ; 
i  :=  j  +  1; 
endCase; 

default  work  :=  work+asString (asChar (A_CHAR) ) +asString (c) ; 
i  :=  i  +  1; 
endSelect; 
endLoop; 

'work; 

»!! 

End  Listing  Two 


Listing  Three 

/*  ************************************************* 

*  FILTER. CLS:  Filter  class  file  * 

a.**.....*******.**,,..,*.,*,*,,,******,,***..*,.  */ 

/*  This  is  a  class  that  makes  possible  filter  programs, 
like  Listers,  Greps,  etc.  in  and  out  are  objects  that 
respond  to  Stream  or  File  protocols.  initBlock,  processBlock, 
and  closeBlock  are  executed  when  the  filter  is  started, 
running,  and  done,  respectively.  */!! 

inherit (Ob ject,  #Filter,  #(inObj 

outOb j 

initBlock 

processBlock 

closeBlock 

),  2,  nil)!! 

now(FilterClass) ! ! 

/*  Create  a  new  Filter.  */ 

Def  new(self,  input,  output,  bl,  b2,  b3  I  f) 

1  f  :=  init (new (self :Behavior) ,  input,  output,  bl,  b2,  b3); 

'f  ; 

I  !  ! 

now (Filter) ! ! 

/*  Once  a  filter  has  been  set  up,  run  it.  Call  initBlock  to 
initialize  anything  other  than  opening  inObj  and  outObj. 

Read  a  line  from  inObj  and  call  processBlock.  When  done, 
close  both  objects.  Note  that  outObj  is  optional.  Also 
not  the  outObj  is  the  receiver  of  the  blocks.  This  is  because 
it's  the  object  that's  programmer-defined.  */ 

Def  run (self  I  str) 

(  eval (initBlock,  outObj,  inObj); 
open (inObj,  0) ; 
checkError  ( i.nOb j ) ; 
if  outObj 

then  create (outObj) ; 

checkError (outOb j) ; 
endif; 
loop 

while  str  :=  readLine (inObj) 

begin  eval (processBlock,  outObj,  str)  ; 

endLoop; 

eval (closeBlock,  outObj,  inObj); 
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close (inObj) ; 
if  outObj 

then  close (outObj) ; 
end if ; 

}  !  ! 

/*  Initialize  a  new  Filter.  Fill-in  all  its  instance 
variables.  */ 

Def  init (self ,  input,  output,  bl,  b2,  b3) 

(  inObj  :=  input; 
outObj  :=  output; 
initBlock  :=  bl; 
processBlock  :  =  b2; 
closeBlock  :=  b3; 

Aself ; 

1  !  ! 

End  Listing  Three 


Listing  Five 

*  REVISER. CLS:  Reviser  class  file  * 

/*  A  Reviser  is  like  a  Grep,  but  it  takes  an  additional 
instance  variable:  the  new  text  to  be  revised  when  the 
pattern  is  found.  Another  filename  is  also  required, 
to  hold  the  revised  text.  Finally,  there  is  a  handle 
for  the  new  file.  */!! 

inherit (Grep,  #Reviser,  t (newText 

newFileName 

newFile),  2,  nil)!! 

now (ReviserClass) ! ! 


Listing  Four 

*  GREP. CLS:  Grep  class  file  * 


/*  This  is  a  class  that  holds  a  single  method  that  will  analyze 
a  file  for  regular  expressions.  This  method  is  an  example  of  a 
generic  Filter,  too.  */!! 

inherit (Object,  #Grep,  #(fileName 
pattern 

matches) ,  2,  nil)  ! ! 
now(GrepClass) ! ! 

/*  Create  and  run  Grep  for  a  file  and  a  pattern.  */ 

Def  run (self,  file,  expr  !  g) 

(  g  :=  init (new (self :Behavior) ,  file,  expr) ; 

Ag; 

)!! 

now (Grep) ! ! 

/*  The  Filter  will  try  to  close  us.  Make  sure  something 
safe  happens.  */ 

Def  close (self) 

(  Aself ; 

1 !  ! 


/*  We  need  a  checkError  message  because  the  Filter  will  try  to 
call  one.  For  a  Grep  this  doesn't  do  anything.  */ 

Def  checkError (self ) 

(  Aself; 

1  !  ! 


/*  A  dummy  method,  needed  because  the  Filter  will  try  to 

create  ()  a  Grep  object  with  a  mode  value.  Ours  doesn't  do 
anything.  If  it  were  a  real  file,  it  would  be  created.  */ 
Def  create (self) 
f  Aself; 
t  !  ! 


/*  When  done,  print  the  number  of  matches  that  were  found.  */ 

Def  finish(self,  inFile) 

(  printLine (asStringRadix (matches,  10)+"  lines  matched  pattern."); 

Aself ; 

I  !  ! 

/*  Process  a  single  line.  Compare  it  against  the  pattern. 

If  it  matches,  print  it.  */ 

Def  process (self ,  s) 

(  if  match (pattern,  s) 
then  printLine (s) ; 

matches  :=  matches  +  1; 
endif ; 

Aself ; 

1  !  ! 

/*  Start  grep.  Assign  the  filename  to  the  TextFile  */ 

Def  start (self,  inFile) 

(  setName (inFile,  fileName) ; 
printLine  ("") ; 

printLine ("Searching  file:  ”+fileName); 

Aself ; 


/*  Create  and  run  a  Reviser.  */ 

Def  run (self,  file,  outFile,  expr,  text  !  r) 
f  r  :=  init (new (self : Behavior) ,  file,  outFile,  expr,  text); 
Ar; 

IN 


now (Reviser) ! ! 

/*  Initialize  what's  different  about  the  Reviser  from 
the  Grep.  */ 

Def  init (self,  file,  outFile,  expr,  text) 

(  newText  :=  text; 
newFileName  :=  outFile; 

Ainit (self :Grep,  file,  expr); 

}M 

/*  Process  a  single  line.  Compare  it  against  the  pattern, 
change  it.  For  simplicity,  this  does  not  handle  multiple 
the  same  line.  */ 

Def  process (self ,  s) 

{  if  match (pattern,  s) 

then  write (newFile,  change (pattern,  s,  newText)  +  CR_LF) ; 

matches  :=  matches  +  1; 
endif; 

Aself ; 

IN 


/*  Set  the  name  for  the  input  file,  then  do  whatever  else 
a  Grep  does.  *  / 

Def  start (self,  inFile) 

(  newFile  :=  new (TextFile) ; 
setName (newFile,  newFileName); 
setDelimiter (newFile,  CR_LF) ; 

Astart (self :Grep,  inFile); 

}M 


/*  Do  a  checkError  on  the  newFile  after  creation.  */ 
Def  checkError (self ) 

(  AcheckError (newFile) ; 

)M 

/*  Create  the  new  file.  */ 

Def  create (self) 

{  create (newFile) ; 

Aself ; 

}!! 

/*  Close  the  new  file  */ 

Def  close (self) 

{  close (newFile) ; 

Aself ; 


/*  Open  the  input  text  file  and  search  it  for  the  expression. 

If  found,  print  it.  */ 

Def  init  (self,  file,  expr  !  f,  start,  process,  finish, 
input,  output) 

(  input  :=  new (TextFile) ; 
setDelimiter (input,  CR_LF) ; 
output  :=  self; 

pattern  :=  new (RegularExpression,  expr) ; 
fileName  :=  file; 
matches  :=  0; 
start  := 

(using (me,  inFile)  start (me,  inFile); 

}; 

process  := 

(using (me,  theLine)  process (me,  theLine); 

1; 

finish  := 

(using (me,  inFile)  finish (me,  inFile); 

J; 

f  :=  new (Filter,  input,  output,  start,  process,  finish); 
run  (f ) ; 

Aself ; 

'  '  End  Listing  Four 


If  it  matches, 
substitutions  in 


End  Listings 
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Listing  On e(Text  begins  on  page  40.) 


/*  TOKENS.  */ 


<error> 

cidentif ier>  =>  KW  SEARCH 


=>  OP_SEARCH 
=>  OP  SEARCH 


<operator> 

<punctuator> 

<number> 

<string> 

<eof> 

<type> 


auto  break  case  cdeci  char  class  const  continue  default  delete  do 
double  else  enum  extern  far  float  for  friend  goto  huge  if  inline  int 
interrupt  long  near  new  operator  overload  pascal  private  protected 
public  register  return  short  signed  sizeof  static  struct  switch  this 
typedef  union  unsigned  virtual  void  volatile  while 

OPERATORS.  */ 

: :  && 

<<«*==>  >= 

+  -  *  /  % 

?  ++  —  '->' 

!  ~  a  '  &  »  « 

=  <<=  !  =  %=  &=  *=  +=  —  /»:■=  >>=  '*« 


/*  PUNCTUATORS.  */ 


/*  NONTERMINALS. 


Input  ->  File_and_tell  <eof> 
File  and  tell  ->  File  => 


=>  AllDoneNow  1  /*  normal  completion  */ 


File  ->  Item  I  File  Item 


Item  ->  Declaration 

/*  or  Definition,  not  in  yet.  */ 


To  recognize  a  declaration,  the  storage  class  and  type  appear 
once.  They  are  remembered.  Each  declaration  is  seperated  by 
commas,  and  share  the  same  type.  The  FinishedDeclarator  calls 
an  action  for  each  one  found. 


Declaration 

->  StorageClass  Type_w/const  Declarators  ; 

Declarators 

->  FinishedDeclarator 
->  FinishedDeclarator  ,  Declarators 

FinishedDeclarator  ->  Declarator  Initializer?  =>  Declaration  1 


->  <identifier>  =>  StoreTag  1 
->  <type>  =>  StoreTag  2 

Class 

->  struct 
->  class 

OverloadableOp  ->*!/!»!+/*  and  all  the  others  */ 

Elipses?  ->  !  ' . . . ' 

/*  Declarations  */ 

Declarator 
->  Decl2 

->  ReachAttribute  *  Const/Volatile?  Declarator  =>  TypeModifier  3 
->  ReachAttribute  &  Const/Volatile?  Declarator  =>  TypeModifier  4 


Decl2 

->  Decl2  (  Arg-Declaration-List  )  =>  TypeModifier  1 

->  Dec 12  [  ConstExp?  ]  =>  TypeModifier  2 

->  Decl3 

Decl3 

->  Dname  =>  Dname  1 

->  (  Declarator  ) 

Const/Volatile?  /*  const  or  volotile,  neither,  or  both  */ 

->  =>  ConstVol  0 

->  const  =>  ConstVol  1 

->  volatile  =>  ConstVol  2 

->  const  volatile  =>  ConstVol  3 

->  volatile  const  =>  ConstVol  3 


ReachAttribute 

->  =>  ReachType  0 

->  near  =>  ReachType  4 

->  far  ->  ReachType  8 

Dname 

->  SimpleDname 
->  <type>  : :  SimpleDname 

SimpleDname 

->  <identifier> 

->  <type> 

->  ~  <type> 

->  Operator-FunctionName 
Operator-FunctionName 

->  operator  OverloadableOp  /*  overload  operator  */ 

->  operator  <type>  /*  conversion  operator  */ 

/*  this  should  really  allow  any  abstract  type  definition,  not  just 
a  simple  type  name.  I'll  change  it  later  */ 

->  operator  <identifier>  /*  ERROR  production  */ 


/*  Argument  list  for  function  declarations  */ 
Arg-Declaration-List 

->  Start-Nested-Type  A-Decl-List?  Elipses?  End-Nested-Type 


Start-Nested-Type 

End-Nested-Type 


->  =>  NestedType  1 
->  =>  NestedType  0 


->  =  Expression 

->  ■  {  Expression-List  } 

Expression-List 
->  Expression 

->  Expression  Expression-List 


->  static 
->  extern 
->  typedef 
->  auto 


=>  StoreStorage  0 
=>  StoreStorage  1 
=>  StoreStorage  2 
=>  StoreStorage  3 
=>  StoreStorage  4 


->  register  =>  StoreStorage  5 

Type_w/const  /*  const  may  appear  before  or  after  the  type  name  */ 

->  Const/Volatile?  Type  Const/Volatile?  =>  StoreBaseConstVol 


char  => 

signed  char  => 

unsigned  char  => 

int  => 

short  => 

short  int  => 

signed  int  => 

signed  short  => 

signed  short  int 
unsigned  => 

unsigned  int  => 

unsigned  short 
unsigned  short  int 
long  => 

signed  long  => 

unsigned  long  => 

float  => 

double  => 

long  double  => 

void  => 

enum  Tag  => 

Class  Tag  => 

union  Tag  => 


StoreType  1 
StoreType  2 
StoreType  3 
StoreType  4 
StoreType  4 
StoreType  4 
StoreType  4 
StoreType  4 

=>  StoreType  4 
StoreType  5 
StoreType  5 
=>  StoreType  5 

=>  StoreType  5 
StoreType  6 
StoreType  6 
StoreType  7 
StoreType  8 
StoreType  9 
StoreType  10 
StoreType  11 
StoreType  12 
StoreType  13 
StoreType  14 


A-Decl-List 

->  A-Decl-List  ,  Argument-Declaration 
->  Argument-Declaration 

Argument -Declaration 

->  StorageClass  Type_w/const  Declarator  =>  Declaration  2 
/*  Expressions  */ 


ConstExp  ->  Expression  /*  semantics  will  check  */ 
Expression 

/*  stub  out  for  now  */ 

->  <identifier> 

->  <number> 

->  <string> 


End  Listing  One 


Listing  Two 


File:  NODE.HPP 


//  the  node  class  is  central  to  date  representati 
//  Everything  it  knows  is  in  a  node. 


enum  node_flavor  {  //state  the  derived  type  from  a  node 
nf_base,  nf_type,  nf_def 


class  node  ( 
protected: 


(continued  on  page  118) 
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Listing  Two  (Listing  continued,  text  begins  on  page  40. ) 

node ( ) ; 

virtual  ~node(); 
public: 

node_flavor  flavor; 
virtual  void  print (); 

}; 

enum  primary_t  (  type_vo.d,  type_char,  type_int,  type_long,  type_float, 
type_double,  type_ldouble,  type_enum,  type_class,  type_union, 
type_pointer,  type_reference,  type_array,  typefunction  } ; 

class  def_node_list;  //forward  ref 

class  type_node  :  public  node  { 
public: 

type_node*  to_what; 
typenode  {); 

~type_node {) ; 
void  print () ; 
unsigned  flags; 
primary_t  primary; 

node*  secondary {)  {  return  to_what;  } 
atom  tag; 

def_node_list*  aggr; 

void  stuff_primary  (int  x,  atom  tagname); 

bool  isConstO  {  return  flags&l;  ) 

bool  isVolO  {  return  flags&2;  ) 

bool  isNearO  (  return  flags&4;  ) 

bool  isFar()  1  return  flags&8;  } 

bool  isUnsignedO  {  return  flagsSl6;  } 

1; 

class  def_node  :  public  node  { 
public: 

atom  name; 
int  storage_class; 
type_node*  type; 
void  print ( ) ; 

def_node  (atom  n,  int  store,  type_node*  t); 

);  " 

/*  /\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\  */ 

/*  lists  of  nodes  *7 

/*  /\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\  */ 

class  node_list  ( 
node**  list; 
int  capacity; 
int  count; 
public: 

node_list () ; 

~node_list()  (  delete  list;  ) 

node**  access  (int  x) ; 

int  size()  {  return  count;  } 

void  add (node*  n)  (  ‘access (count++)  =  n;  ) 

) ; 

♦define  create_list (TYPE)  class  TYPE##_node_list  :  public  node_list  {  \ 
public: \ 

TYPE##_node*&  operator!]  (int  x)  {  return  * (TYPE##_node  **) access  (x) ;  }  ) 

create_list  (type); 
create_list  (def); 

End  Listing  Two 


Listing  Three 

/************.********.*******.*.*.******************* 

File:  ACTIONS. CPP  Copyright  1989  by  John  M.  Dlugosz 
the  Actions  called  from  the  parser  ^ 

♦include  "usual. hpp" 

♦include  <stream.hpp> 

♦include  "atom. hpp" 

♦include  "node. hpp" 

♦include  "define. hpp" 

//  ♦define  SHORT  return  0 

/*  short  out  actions  for  testing  parser  only, 
if  something  suddenly  goes  wrong,  I  can  stub 
out  all  the  actions  to  make  sure  I'm  not  walking 
on  data  somewhere.  */ 

♦define  SHORT 

//  the  normal  case. 

/*  /\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\  */ 

static  char  last_token [81] ; 

void  get_last_token () 

( 

/*  copy  last  token  from  scanner  into  a  nul-terminated  string  */ 

int  len=  80;  //maximum  sig.  length 

extern  char  *T_beg,  *T_end;  //from  the  scanner 

char*  source=  T_beg; 

char*  dest=  last_token; 

//cout  «  (unsigned) T_beg  «  "  "  «  Tend; 

//for  (int  x=  0;  x  <  5;  x++)  cout .put (T_beg [x] ) ; 

while  (len —  &&  source  <  T_end)  *dest++  =  *source++; 

*dest=  '\0'; 

} 

/*  /\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\  */ 


/*  in  a  declaration,  a  storage  class  is  the  first  thing  I  get.  This  starts 
it  off.  Then  a  ConstVol,  a  StoreType,  and  a  second  ConstVol.  The  const 
or  volatile  keyword  may  appear  before  or  after  the  type,  with  equal 
effect.  The  two  bits  are  ORed  together  for  the  final  result. 

After  this,  I  get  one  or  more  calls  to  Declaration. 

*/ 

/*  /\/\A/\/\/\/\/\/\/\/\/\A/\/\/\/\/\/\/\  */ 

//  the  type  I'm  building 
struct  working_type  { 

type_node*  this_type;  //the  tail 

type_node*  root_type;  //the  head 

int  base_type; 

atom  tag_name;  //  if  base_type  has  a  name 

atom  name;  //The  name  of  the  thing  being  declared 

int  storage_class; 

int  const_vol; 

workingtype*  next; 

}  MainType; 

working_type*  Tx=  SMainType; 

/*  this  is  accessed  through  a  pointer  because  a  declarator  can  be  encounted 
while  parsing  another  declarator.  This  lets  me  stack  them.  */ 

/*  AAAAAAAAAAAAAAAAAAAA  */ 

static  int  const_vol_stack[50] ; 
static  int  const_vol_stacktop=  0; 

/*  AAAAAAAAAAAAAAAAAAAA  */ 

int  Declaration  (int  x,...) 

( 

/*  values  for  x:  1-  global  or  local  def. 

2-  parameters 

3-  struct/union  list 

*/ 

SHORT; 

/*  This  finishes  it  off.  A  complete  declaration  has  been  found.  */ 
Tx->this_type->stuf f_primary  (Tx->base_type,  Tx->tag_name) ; 

Tx->this_type->f lags  1=  Tx->const_vol; 

//  build  the  'thing'  from  the  type_node  and  the  name. 
store_thing  (Tx->root_type,  Tx->name,  Tx->storage_class,  x); 

//  Tx->root_type->print () ; 

//  cout .put (' \n' ) ; 
return  0; 

) 

/*  AAAAAAAAAAAAAAAAAAAA  */ 

int  StoreBaseConstVol  (int  x, . . . ) 

( 

SHORT; 

//  the  first  two  calls  to  ConstVol  apply  here. 

Tx->const_vol  =  const_vol_stack [ — const_vol_stacktop] ; 

Tx->const_vol  !=  const_vol_stack[--const_vol_stacktop] ; 
return  0; 

1 

/*  /\/\/\/\/\/\/\/\/\/\/\/\/\/\AAA/\AA  */ 

int  StoreType  (int  x, ...) 

( 

SHORT; 

Tx->base_type=  x; 
return  0; 

} 

/*  /\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\AA/\  */ 

int  StoreTag  (int  x, ...) 

{ 

SHORT; 

/*  called  when  a  struct,  union,  or  enum  is  parsed.  The  tag  is  the  last 
token  read.  After  this  call,  the  StoreType  call  is  made  with  'union' 
or  whatever.  */ 
get_last_token ()  ; 

Tx->tag_name=  atoms [last_token] ; 
return  0; 

} 

/*  /\/\/\/\/\/\/\/\/\/\/\A/\A/\AAAAA  */ 

int  StoreStorage  (int  x,...) 

{ 

SHORT; 

/*  this  is  the  first  thing  called  */ 

Tx->storage_class=  x; 
return  0; 

} 

/*  /\/\/\/\/\/\/\/\A/\/\/\A/\AAAAAA  */ 

int  Dname  (int  x,...) 

( 

SHORT; 

/*  if  x==l,  the  last  token  is  the  name  of  a  thing  being  declared.  If 
x==0,  there  is  no  name  and  this  is  an  abstact  declarator.  Either 
way,  build  a  type  node  and  store  the  name.  This  overwrites  the  type 
node,  as  it  will  be  the  first  thing  called.  */ 

if  (x)  ( 

get_last_token ( ) ; 

Tx->name=  atoms [ last_token] ; 
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listing  ThreefListing  continued,  text  begins  on  page  40) 

] 

Tx->this  type=  new  type  node; 

atom  storage  atoms (16); 

Tx->root  type=  Tx->this_type; 

/*  AAAAAAAAAAAAAAAAAAAA  */ 

return  0; 

} 

atom  storage: :atom_storage  (int  size) 

/*  AAAAAAAAAAAAAAAAAAAA  */ 

1 

count=  0; 

int  TypeModifier  (int  x,...) 

capacity=  size; 

list=  (char**)  malloc  (size  *  sizeof (char*) ) ; 

SHORT; 

) 

/*  1  t()  2  t[]  3  *t  4  &t  */ 

/*  AAAAAAAAAAAAAAAAAAAA  */ 

switch  (x)  { 

atom  storage: : 'atom  storage () 

Tx->this  type->primary=  type  function; 

//  attach  parameter  list 

Tx->this_type->aggr=  completed_def_list ; 
break; 

free  (list) ; 

/*  AAAAAAAAAAAAAAAAAAAA  */ 

case  2: 

Tx->this_type->primary=  type_array; 

extern  "C”  int  strcmp(char*, char*) ; 

//  »  attach  size 
break; 

extern  "C"  char*  strdup (char*) ; 

case  3: 

atom  atom  storage :: operator [ )  (char*  s) 

Tx->this  type->primary=  type  pointer; 

Tx->this_type->f lags  (  =  const_vol_stack [ — const_vol_stacktop] ; 

for  (int  loop=  0;  loop  <  count;  loop++)  { 

if  (!strcmp(s,  list [loop]))  return  loop;  //found  it 

Tx->this_type->primary=  type  reference; 

) 

Tx->this_type->flags  !  =  const  vol  stack ( — const_vol_stacktop] ; 
break;  ~ 

capacity  +=  capacity/2; 

list=  (char**) realloc (list, capacity*sizeof (char*) ) ; 

Tx->this_type->to  what=  new  type  node; 

Tx->this_type*  Tx->this_type->to_what; 

1 

list [count ]=  strdup (s); 
return  count++; 

return  0; 

} 

) 

End  Listing  Four 

/*  AAAAAAAAAAAAAAAAAAAA  */ 

int  ConstVol  (int  x,...) 

SHORT; 

Listing  Five 

/*  1-const  2-volatile  3-both  */ 

const_vol_stack (const_vol_stacktop++] =  x; 
return  0; 

> 

FILE:  ATOM. HPP 

/*  /\/\/\/\/\/\/\/\/\/\/\/\A/\/\/\/\/\/\/\  */ 

typedef  int  atom; 

int  ReachType  (int  x,...) 

class  atom  storage  ( 

{ 

char**  list; 

SHORT; 

int  count; 

/*  0-default  1-near  2-far  */ 

int  capacity; 

return  0; 

public: 

} 

atom_storage (int  size) ; 

'atom  storage (); 

/*  /\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\  */ 

char*  operator []  (atom  x)  (  return  list  [ x ] ;  ) 
atom  operator!]  (char*); 

int  NestedType  (int  x,  ...) 

I; 

SHORT; 

working_type*  p; 

if  (x)  (  //start  nesting 

extern  atom  storage  atoms; 

p=  new  working  type; 
p->next=  Tx; 

Tx=  p; 

End  Listing  Five 

) 

else  {  //restore  old  type 

p=  Tx; 

Tx=  Tx->next; 
delete  p; 

Listing  Six 

parameter  list  (x) ;  //pass  on  to  DEFINE  module 

return  0; 

File:  DEFINE. CPP  Copyright  1989  by  John  M.  Dlugosz 

} 

deal  with  definitions  once  they  are  parsed 

/*  AAAAAAAAAAAAAAAAAAAA  */ 

***********«***********»*****************************/ 

/*  AAAAAAAAAAAAAAAAAAAA  */ 

/*  AAAAAAAAAAAAAAAAAAAA  */ 

linclude  "usual. hpp" 
linclude  <stream.hpp> 

int  AllDoneNow  (int  x,  ...) 

{ 

linclude  "atom. hpp" 
linclude  "node. hpp" 

SHORT; 

linclude  "define. hpp" 

cout  «  "parser  complete.  \n"; 

for  (int  loop=  0;  loop  <  global  stuff .size  () ;  loop++)  ( 

bool  local  level=  FALSE; 

global_stuf f [loop. ->print () ; 
cout. put  ('\n'); 

1 

def_node_list  global  stuff; 
struct  p  list  struct  ( 

return  0; 

def  node  list*  1; 

} 

p_list_struct*  next; 

End  Listing  Three 

static  p_list_struct  *p_list; 
def_node_list*  completed  def  list; 

Listing  Four 

/*  AAAAAAAAAAAAAAAAAAAA  */ 

void  store  thing  (type  node*  t,  atom  name,  int  storage  class,  int  param) 

/**+************,******.********************.**,.**.,, 

( 

File:  ATOM.CPP  Copyright  1989  by  John  M.  Dlugosz 

/*  'param'  is  passed  through  from  the  grammar.  If  1,  this  is  a  declaration 

store  strings 

for  a  local  or  global  object.  If  2,  this  is  part  of  a  parameter  list  */ 

********.***.**********.********.*****.*****,***.****/ 

def_node*  n=  new  def  node  (name,  storage  class,  t); 

((include  "usual. hpp" 

//  file  it  away  somewhere 

linclude  "atom. hpp" 

switch  (param)  ( 

case  1: 

extern  "C"  void*  malloc  (unsigned  size) ; 

extern  "C"  void  free  (void*) ; 

extern  "C"  void*  realloc  (void*,  unsigned); 

(continued  on  page  122) 
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Listing  Six  (Listing  continued,  text  begins  on  page  40.) 


if  (name  ==  -1)  1 

//  »  I  need  to  get  a  standard  error  reporter 
cout  «  "abstract  declarator  ignored\n"; 

} 

global_stuff .add  (n) ; 
break; 
case  2: 

//  »  check  it  over 
p_list->l->add (n)  ; 
break; 


/*  /\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\  */ 

void  parameter_list  (int  x) 

{ 

p_list_struct*  p; 
if  (x)  ( 

p=  new  p_list_struct; 
p->next=  p_list; 
p->l=  new  def_node_list; 
p_listm  p; 

) 

else  ( 

p=  p_list; 

p_list=  p_list->next; 
completed_def_list-  p->l; 
delete  p; 

) 


End  Listings 
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Listing  One  (Text  begins  on  page  48.) 

class  CIRCLE  export 

center,  radius,  intersectl,  intersect2, 
on,  inside,  outside, 
translate,  scale,  rotate  . . . 
feature 

center:  POINT; 
radius:  REAL; 

intersectl (other :  CIRCLE):  POINT  is 
--  One  of  the  intersections 
—  of  current  circle  with  other 
require 

not  other. Void; 
center .distance (other . center) 
<=radius  +  other. radius 
do 

...  Computation  of  intersection  ... 

ensure 

on (Result) ; 
other. on (Result) 
end;  --  intersectl 

intersect2 (other :CIRCLE) :  POINT  is 


on (p: POINT)  is 

--  IS  p  on  circle? 
require 

not  p.Void 

do  .  . . 
end;  --  on 

inside (p:POINT)  is 

--  Is  p  inside  circle? 
require 

not  p.Void 

do  . .  . 

end;  --  inside 

outside  (p : POINT)  is 

—  Is  p  outside  circle? 
require 

not  p.Void 

do  .  . . 

end;  --  outside 

Create  lc:POINT;  r : REAL)  is 

— Create  circle  with  center  c 
--and  radius  r 
require 

not  c.Void; 
r>=0 
do 

center:=c;  radius  :=r 
end;  —  Create 

...  Other  features  (translate,  scale,  ...)  ... 

invariant 

. . .  See  below  . . . 
end  --  class  CIRCLE 


End  Listing  One 


intersectl (other :  CIRCLE):  POINT 

—  One  of  the  intersections 
--  of  current  circle  with  other 

require 

not  other.Void; 
center .distance (other .center) 
<=radius  +  other. radius 

ensure 

on (Result) 
other .on (Result) 

intersect (other :CIRCLE) :  POINT 


on (p: POINT) 

—  Is  p  on  circle? 
require 

not  p.Void 

inside (p:POINT) 

—  Is  p  inside  circle? 
require 

not  p.Void 

ensure 

Result3 (center .distance (p) cradius) 


outside (p:POINT) 


...Specification  of  other  features 
(translate,  scale,  ...)  ... 


. . .  See  below  . . . 
end  --  class  interface  CIRCLE 


End  Listing  Three 


Listing  Four 


require 

P 

do 

if  not  p  then 

. . .  Deal  with  erroneous  case  . . . 

else 

...  Proceed  with  normal  execution 


end 

end;  --  p 


End  Listing  Four 


Listing  Six 


write(x:  T)  is 

--  Write  x; 

--  make  at  most 

local 

attempts : INTEGER 
external 

...  As  before  . 

do 

attempts :=attempts+l; 
attempt_to_write (x) ; 

rescue 

if  attempts  <  5  then 
retry 
end 

end  —  write 


Listing  Five 


Listing  Two 

require 

other_not_void:not  other.Void; 
circles_intersect : 

center . distance  (other . center ) 
<=radius  +  other. radius 


End  Listing  Two 


Listing  Three 

class  interface  CIRCLE 
exported  features 

center,  radius,  intersectl,  intersect?, 
on,  inside,  outside, 
translate,  scale,  rotate  . . . 
feature  specification 
center:  POINT; 
radius:  REAL; 


class  C  [T]  export 

write,  write_successful,  . . . 
feature 

write_successful:  BOOLEAN; 

—  An  attribute 

write  (x:  T)  is 
--  Write  x,  if  possible; 

—  make  at  most  five  attempts. 
--  Record  result  in  write_ 
successful 

local 

attempts:  INTEGER 
external 

attempt_to_wnte  (x:T) 
language  "  . . .  " 
do 

if  attempts  <5  then 

attempt_  to_write  (x) ; 
write_successful :=true 

else 

write_successf ul :=false 

end 

rescue 

at tempts: “attempt s+1; 

retry 

end  —  write 
end  —  class  C 


End  Listing  Five 


five  attempts. 


End  Listings 
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Listing  One  (Text  begins  on  page  64.) 

{Top  Window  Object) 

TWindow  =  OBJECT 


Client 

Rect; 

Coord 

Rect; 

TCoord 

Rect; 

Handle 

word; 

Shadow 

boolean; 

Col 

tWindowColors; 

Captured 

boolean; 

Class 

WindowClasses; 

Bitmap 

pointer; 

TimeOutState:  byte; 
ForceTimeOut :  boolean; 

CursMode 

CursorModes; 

CursX 

word; 

CursY 

word; 

procedure  TWindow. OpenWindow  (Class:  WindowClasses;  x,y,w,h:  word; 

Col:  tWindowColors;  Shadow:  boolean); 
procedure  TWindow. DrawWindow  (Clip:  IRect); 
procedure  TWindow. CloseWindow; 
procedure  TWindow. MoveWindow  (x,y:  word); 
procedure  TWindow. ChangeWindow  (x,y,w,h:  word); 
procedure  TWindow. MountWindow; 
procedure  TWindow . UnMountWindow; 
procedure  TWindow. GetClientArea  (var  Client:  Rect) ; 
procedure  TWindow. WrtChars  (var  C;  Len,x,y:  word); 
procedure  TWindow. WrtCharsAttr  (var  C;  Attr,Len,x,y:  word); 
procedure  TWindow. WrtExtendedCharsAttr  (var  C;  Attrl,Attr2, Len, Width, x,y: 
word) ; 

procedure  TWindow. WrtNAttr  (Attr, Len, x,y:  word); 
procedure  TWindow. WrtCells  (var  C;  Len,x,y:  word); 
procedure  TWindow. Wrt Frame  (F:  FramePartsSet;  Attr,x,y,w,h:  word); 
procedure  TWindow. WrtSeparator  (RightCorner :  boolean;  Attr,y:  word); 
procedure  TWindow. ScrollUp  (Lines,  Attr,x,y, w, h:  word); 
procedure  TWindow. ScrollDown  (Lines,  Attr, x, y, w, h:  word); 
procedure  TWindow. ScrollLeft  (Rows,  Attr,x,y,w,h:  word); 
procedure  TWindow. ScrollRight  (Rows,  Attr, x, y, w, h:  word); 
procedure  TWindow. CaptureMouse; 
procedu re  TWindow . UnCapt ureMouse ; 

procedure  TWindow. PressLMouse  (DbleClicked:  boolean;  x,y:  integer); 
procedure  TWindow. ReleaseLMouse  (x,y:  integer); 

procedure  TWindow. PressRMouse  (DbleClicked:  boolean;  x,y:  integer); 

procedure  TWindow. ReleaseRMouse  (x,y:  integer); 

procedure  TWindow. MoveMouse  (x,y:  integer); 

procedure  TWindow. PosCursor  (x,y:  word); 

procedure  TWindow. SetCursorMode  (Mode:  CursorModes); 

procedure  TWindow. GetChar  (Key:  word); 

procedure  TWindow. TimeOut; 

procedure  TWindow. Ref reshStatusLine; 

end; 


End  listing  One 


Listing  Two 


TDialogBox  = 


object  (TWindow) 
First  : 

Current 
Command  : 

ID  : 

HelpNO  : 

UndoID 

ValidID  : 
Appli  : 

MouseAction  : 
TitleColor  : 


pDialogBoxItem; 

pDialogBoxItem; 

function  (Dialog:  TDialogBox; 

word; 

word; 

word; 

word; 

TDialogBoxAppli; 

MouseActions; 

boolean; 


ID: word) : 


boolean; 


{ $ENDIF ) 


HeapPtr 


pointer; 


procedure 
w,  h 

Command 

HelpNO 

UndoID 

ValidID 


TDialogBox . OpenDialogBox 
:  word; 

:  pointer; 

:  word; 

:  word; 

:  word) ; 


(CheckPrevW 


:  boolean; 


procedure 

procedure 

procedure 

procedure 

procedure 

ride; 

procedure 

ride; 

procedure 

procedure 

procedure 

procedure 

procedure 

procedure 


TDialogBox. Call  (var  ID:  word); 

TDialogbox. GetChar  (Key:  word);  override; 
TDialogBox. CloseWindow;  override; 

TDialogBox. DrawWindow  (Clip:  IRect);  override; 
TDialogBox. PressLMouse  (DbleClicked:  boolean;  x,y: 

TDialogBox. PressRMouse  (DbleClicked:  boolean;  x,y: 

TDialogBox. ReleaseLMouse  (x,y:  integer);  override; 
TDialogBox. MoveMouse  (x,y:  integer);  override; 
TDialogBox.SelectDialogBoxItem  (ID:  word); 
TDialogBox. TimeOut;  override; 
TDialogBox.DelDialogBoxItem  (ID:  word); 
TDialogBox.AddComment  ( 

CommID  :  word; 

Alt ID  :  word; 

x,y,w  :  word; 

Text  :  String; 

justif  :  Justifications); 


integer) ;  over¬ 
integer)  ;  over- 


:  TDialogBox .AddFrame  ( 

FraraelD 

:  word; 

AltID 

:  word; 

x,y,w,h 

:  word; 

Text 

:  String) ; 

i  TDialogBox.AddSysButton  ( 

TabID 

:  word; 

SysID 

:  SysButtons; 

justif 

:  Justifications) 

TDialogBox.AddDlgText  ( 

TabID 

:  word; 

DlglD 

:  word; 

Size 

:  word; 

x,  y,  w 

:  word; 

Text 

:  String) ; 

TDialogBox.AddPushButton  ( 

TabID 

:  word; 

PushID 

:  word; 

x/y 

:  word; 

State 

:  boolean) ; 

TDialogBox.AddRadioButton  ( 

TabID 

:  word; 

GroupID 

:  word; 

RadioID 

:  word; 

LinkID 

:  word; 

:  word; 

State 

:  boolean; 

Trace 

:  pointer) ; 

TDialogBox.AddListBox  ( 

TabID 

:  word; 

ListID 

:  word; 

Columns 

:  word; 

x,  y,  w,  h 

:  word; 

LinkID 

:  word; 

Trace  :  pointer) ; 

procedure  TDialogBox.DrawComment  ( 

p  :  pDialogBoxItem) ; 

procedure  TDialogBox.DrawFrame  ( 

F  :  FramePartsSet; 

p  :  pDialogBoxItem) ; 

procedure  TDialogBox.DrawSysButton  ( 
Hilite  :  boolean; 

p  :  pDialogBoxItem) ; 

procedure  TDialogBox.DrawDlgText  ( 

p  :  pDialogBoxItem) ; 

procedure  TDialogBox.DrawPushButton  ( 

p  :  pDialogBoxItem) ; 

procedure  TDialogBox.DrawRadioButton  ( 

p  :  pDialogBoxItem) ; 

procedure  TDialogBox.DrawListBox  ( 

p  :  pDialogBoxItem) ; 

procedure  TDialogBox.SetComment  ( 

CommID  :  word; 

Text  :  String); 

procedure  TDialogBox.GetComment  ( 

CommID  :  word; 

var  Text  :  String); 

procedure  TDialogBox.GetDlgText  ( 

DlglD  :  word; 

var  Text  :  string); 

procedure  TDialogBox.SetDlgText  ( 

DlglD  :  word; 

Text  :  String); 

procedure  TDialogBox.SetLockState  ( 

DlglD  :  word; 

Lock  :  Boolean); 

procedure  TDialogBox .GetPushButton  ( 
PushID  :  word; 

var  State  :  boolean); 

procedure  TDialogBox. SetPushButton  ( 
PushID  :  word; 

State  :  boolean) ; 


procedure 

TDialogBox.GetRadioButton  ( 

GroupID 

:  word; 

var 

ID 

:  word) ; 

procedure 

TDialogBox.SetRadioButton  ( 

GroupID 

:  word; 

ID 

:  word) ; 

procedure 

TDialogBox, 

.GetTextListBox  ( 

ListID 

:  word; 

var 

Text 

:  string); 

procedure 

TDialogBox.GetOf fsetListBox 

ListID 

:  word; 

var 

Offset 

:  word) ; 

procedure 

TDialogBox. SetTextListBox  ( 

ListID 

:  word; 

offset 

:  word; 

Text 

:  string) ; 

procedure 

TDialogBox . 

SetOffsetListBox 

ListID 

:  longint; 

offset 

:  word) ; 

procedure 

TDialogBox.ClearListBox  ( 

ListID 

:  dword) ; 

function  TDialogBox .AddListBoxItem  ( 


ListID 

Text 


dword; 
string) :  boolean; 


End  Listing  Two 
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Listing  Three 

EditWindow 

object  (TDocument) 

Mode  :  OpenFileModes; 

ewNext 

EditWindow; 

dtType  :  DocTypes; 

ewPrev 

EditWindow; 

FileName  :  PathStr; 

ewWDW 

word; 

DefaultExt  :  ExtStr) ; 

ewDOC 

word; 

label  Error; 

ewType 

DocTypes; 

var 

ewUndo 

record 

H 

FileHandle; 

X 

byte; 

Size 

dword; 

Y 

word; 

wdw 

word; 

Len 

word; 

doc 

word; 

Buf 

MemHandle 

Time 

Longlnt; 

end; 

Ht 

MemHandle; 

Pt 

pFileText; 

ewFirstMark  , 

Dummy 

QPErrors; 

ewCursMark 

:  record 

Locked 

boolean; 

XY:  word; 

begin  (OpenFile) 

dX:  word 

(Check  if  it's  possible  to  open  a  new  document) 

end; 

Edit  :=  NIL; 

H  :=  0;  Ht  :=  NullMemHandle; 

if  CheckFileNameNotAlreadyLoaded  (FileName,  DefaultExt)  <>  0  then  begin 

procedure  EditWmdow.OpenFile 

Status  :  = 

ErrFileAlready Loaded; 

var  Status 

QPErrors; 

Col 

tWindowColors; 

DOC 

word; 

WDW 

word; 

==_ 

Locked 

boolean; 

Using  the  OpenFile  procedure 

dtType 

DocTypes; 

== } 

IsNew 

boolean; 

Time 

Longlnt; 

New  (Edit); 

(Memory  Allocated  for  the  object  Edit) 

Coord 

IRect; 

Edit .OpenFile  (Status, 

Title 

PathStr; 

wcEditWindows, 

|  TextHandle:  MemHandle; 

TextSize 

word) ; 

wdw, 

Locked, 

procedure  EditWindow. DuplicateWindow; 

procedure  EditWindow. SaveFile 

var  Status:  QPErrors;  FileName:  PathStr; 

DefaultExt:  Ex- 

tStr) ; 

NULL, 

procedure  EditWindow. CloseWindow;  override; 

procedure  EditWindow . CloseDocument ; 

function  EditWindow. NbLines :  word;  override; 

function  EditWindow.NbColumns : 

word;  override; 

function  EditWindow. GetLine  (Column, Line, Len:  word;  var  Buffer):  word;  over- 

ride; 

if  Ht  <> 

function  EditWindow. GetLmeLength  (Line:  word)  :  word;  override; 

procedure  EditWindow. GetPhysLine  (Column, Line, Len:  word;  var  Cells);  override; 

procedure  EditWindow. GetChar  (Key:  word);  override; 

function  EditWindow. CopyBlock2ClipBoard:  boolean;  override; 

procedure  EditWindow. MountWindow;  override; 

procedure  EditWindow. UnMountWindow;  override; 

procedure  EditWindow. ModifyLine  (Line:  word;  PosX,PosY:  word); 

procedure  EditWindow. ModifyEOF 

(Line:  word;  PosX,PosY:  word); 

end; 

End  Listings 

An  instance  of  an  object  of  type  EditWindow;  here,  the  object  Edit  is  passed 

to  the  procedure  InternalReplaceChar . 

procedure  InternalReplaceChar 

Edit  :  EditWindow;  (  <==  object  declared) 

AtX.AtY  :  word; 

Ch 

:  Char); 

var 

Pt 

:  pFileText; 

PI 

:  pFileLines; 

Pi 

:  pFileLinesInfo; 

begin  (InternalReplaceChar) 

with  Documents [Edit .ewDOC I 

do  begin 

SaveLineForUndo  (Edit,  AtX.AtY); 

FarLockMem2  (d.Lines,Pl 

dText, Pt) ; 

if  CheckAndExpandlf InTab  ( 

EditorError, 

Edit .ewDOC, 

Pt,  PI, 

AtX,  AtX,  AtY)  then  begin 

PtA[PlA[AtY]+AtX]  :=  Ch; 

OneSourceModified  :=  true; 

dUsed  :=  true; 

dTime  :=  GetDateTime; 

FarUnLockMem2 

dLines, dText) ; 

if  dMarkModif  then  begin 

$IFDEF  DEBUG) 

Assertion  (dlnfo  <>  NullMemHandle,  LINE  ,  SourceName) ; 

($ENDIF) 

FarLockMeml  (dlnfo,  Pi); 

PiA[AtY]  :=  0; 

FarUnLockMeml  (dlnfo) 

end 

end 

else 

ExtendedErrorBox  (false,  EditorError,  true,  dFileName) 

end 

end;  (InternalReplaceChar) 

*) 

( - 

The  Openfile  method? 

- - - - - } 

( - 

(  OpenFile) 

- ) 

procedure  OpenFile  ( 

var  Status 

:  QPErrors; 

var  Edit 

:  EditWindow; 
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LOGIC  SIMULATOR 


Listing  One  (  Text  begins  on  page  72.) 

self  close. ! 
componentNamed:  aName 

Object  subclass:  #LogicLab 

"Answer  the  component  (device,  signal,  or  switch) 

instanceVariableNames : 

whose  name  is  aName.  If  no  component  can  be  found 

'devices  signals  switches  clashes  changed  topPane  analyzer  breadboard 

listSelectcr  currentComponent 

!  realName  1 

classVariableNames :  " 

realName  :=  aName. 

poolDictionaries : 

clashes  isNil 

'FunctionKeys  CharacterConstants  '  ! 

ifFalse:  [ 

(clashes  includesKey:  aName) 

! LogicLab  class  methods  ! 

ifTrue:  [realName  :=  clashes  at:  aName]]. 

description 

devices  do:  [: aDevice! 

"Answer  a  String  describing  the 

(aDevice  name  =  realName) 

application  and  version." 

ifTrue:  [AaDevice] ] . 

A'LogicLab  (Version  1.0  —  06/26/88)'.! 

signals  do:  [: aSignal! 

new 

(aSignal  name  =  realName) 

"Answer  an  initialized  LogicLab  application." 

ifTrue:  [AaSignal]]. 

1  logicLab  1 

switches  do:  [: aSwitch! 

logicLab  :  =  super  new. 

(aSwitch  name  =  realName) 

logicLab  initialize. 

ifTrue:  [AaSwitch]]. 

"logicLab.!  ! 

Anil. ! 

componentTypeMenu:  selectorArray 

ILogicLab  methods  ! 

"Answer  a  user-selected  action  for  a 

addComponent :  aComponent 

component  type." 

"Add  aComponent  to  the  circuit  description. 

A ( (Menu 

If  there  is  an  error,  answer  nil;  otherwise 

labels:  ' Device\Signal\Switch'  withers 

answer  aComponent . " 

lines :  # ( ) 

!  name  ! 

selectors:  selectorArray)  popUpAt:  MenuPosition).! 

name  :=  aComponent  name. 

connect 

name  size  ==  0 

"Make  a  user-specified  connection." 

ifTrue:  [ 

!  from  to  ! 

from  :=  self  getNode. 

User  is  installing  —  get  a  name. 

from  isNil 

" 

ifTrue:  [Anil] . 

name  :=  self  getNewName. 

to  :=  self  getNode. 

name  isNil 

to  isNil 

ifTrue:  ( ''nil ) . 

ifTrue:  [Anil]. 

aComponent  name:  name] 

from  connect:  to. 

ifFalse:  [ 

changed  :=  true. 
currentComponent  :=  from  model. 

A  name  has  been  supplied  —  this  implies 

listSelector  :=  #listComponentConnections . 

that  the  component  is  being  installed  from 

breadboard  update.! 

a  file.  Need  to  check  for  a  clash  with 

description 

an  existing  name. 

"Answer  a  string  with  a  description  of  the  receiver." 

A(self  class  description).! 

(  (self  componentNamed:  name)  isNil) 

deviceNames 

ifFalse:  [ 

"Answer  a  collection  of  all  of  the 

" 

names  of  installed  devices." 

Had  a  name  clash  —  get  a  synonym 

1  list  1 

from  the  user  and  stash  both  of  them 

list  :=  OrderedCollection  new:  (devices  size) . 

away  in  the  clashes  table.  Then 

devices  do:  [: aDevice!  list  add:  aDevice  name]. 

rename  the  component . 

Alist . ! 

" 

devices 

name  :=  self  getNewName. 

"Answer  the  list  of  installed  devices." 

name  isNil 

Adevices . ! 

ifTrue:  [Anil]. 

disconnect 

clashes 

"Remove  a  user-specified  connection." 

at :  aComponent  name 

!  node  ! 

put :  name . 

node  :=  self  getNode. 

aComponent  name:  name]]. 

node  isNil 

changed  :=  true. 

ifTrue:  [Anil]  . 

aComponent  isDevice 

node  disconnect. 

ifTrue:  [devices  add:  aComponent] 

changed  :=  true. 

ifFalse:  [ 

currentComponent  :=  node  model. 

aComponent  isSignal 

listSelector  :=  IlistComponentConnections . 

ifTrue:  [signals  add:  aComponent] 

breadboard  update.! 

ifFalse:  [ 

erase 

switches  add:  aComponent. 

"After  user-verification,  erase 

analyzer  isNil 

the  circuit  description." 

ifFalse:  [analyzer  addSwitch:  aComponent]]]. 

Cursor  offset:  MenuPosition. 

AaComponent . ! 

(self  verify:  'Erase  circuit  description?') 

allNames 

ifFalse:  [Anil] . 

"Answer  an  array  of  all  of  the 

self  eraseCircuit . 

names  of  installed  components." 

listSelector  :=  #listDevices . 

A ( (self  deviceNames) ,  (self  signalNames) ,  (self  switchNames) ) . ! 

changed  :=  true. 

analyzer:  aModel 

breadboard  update.! 

"Set  the  LogicAnalyzer  Application  model 

eraseCircuit 

to  aModel." 

"Erase  the  circuit  description." 

analyzer  :=  aModel.! 

devices  do:  [: aDevice! 

breadboardList 

self  removeComponent :  aDevice]. 

"Answer  an  array  of  strings  according  to  the 

signals  do:  [:aSignal! 

current  list  selector." 

self  removeComponent:  aSignal] . 

listSelector  isNil 

switches  do:  [:aSwitch! 

ifTrue:  [listSelector  :=  #listDevices] . 

self  removeComponent:  aSwitch]. 

A(self  perform:  listSelector).! 

self  initialize . ! 

breadboardMenu 

getExistingComponent 

"Private  —  answer  the  menu  that  processes 

"Answer  a  user-specified  component." 

breadboard  functions." 

!  name  component  reply  list  ! 

MenuPosition  :=  Cursor  position. 

name  :=  self  getName. 

A (Menu 

name  isNil 

labels:  (' Load\Save\Erase\ListV , 

' Install\Connect\Remove\Disconnect\' , 

component  :=  self  componentNamed:  name. 

'  SimulateV , 

component  isNil 

'Quit')  withers 

ifFalse:  ["component] . 

lines:  #(4  8  9) 

Cursor  offset:  MenuPosition. 

selectors:  #(load  save  erase  list 

(Menu  message: 

install  connect  remove  disconnect 

(name,  '  not  installed  —  select  from  list?' ) )  isNil 

run 

ifTrue:  [ Anil] . 

quit) )  .  ! 

Cursor  offset:  MenuPosition. 

changed 

reply  :=  self  componentTypeMenu: 

"Answer  true  if  the  circuit  has  changed." 

# (deviceNames  signalNames  switchNames). 

Achanged. ! 

Cursor  offset:  MenuPosition. 

changed:  aBoolean 

reply  isNil 

"Set  the  circuit-changed  flag  to  aBoolean." 

ifTrue:  [Anil] . 

changed  :=  aBoolean.! 

list  :=  self  perform:  reply. 

close 

(list  size  ==  0) 

"Close  the  LogicLab  breadboarding  window." 

ifTrue:  [ 

topPane  dispatcher  deactivateWindow  closeWindow. ! 

Menu  message:  'None  installed' . 

Cursor  offset:  MenuPosition. 

"Close  the  breadboard  application  window." 

Anil]  . 

name  :=  VariableMenu  selectFrom:  list. 
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name  isNil 

ifTrue:  ["nil], 
name  :  =  list  at:  name. 

A (self  componentNamed :  name) . ! 
getExistingName 

"Answer  a  user-specified  name  of 
an  existing  component . " 

I  component  ! 

component  :=  self  getExistingComponent . 
component  isNil 
ifTrue:  [Anil). 

A (component  name) . ! 

getFile 

"Answer  a  FileStream  for  a 
user-specified  filename." 

!  name  I 

name  :=  self  getFilename. 
name  isNil 

ifTrue:  (Anilj . 

A (File  pathName:  name) . ! 
getFilename 

"Answer  a  user-specified  filename." 

!  name  I 

Cursor  offset:  MenuPosition. 
name  : = 

Prompter 

prompt :  'Enter  f i lename ' 
default:  ". 

Cursor  offset:  MenuPosition. 

Aname. ! 
getName 

"Answer  a  user-specified  name." 

I  name  ! 

Cursor  offset:  MenuPosition. 
name  := 

Prompter 

prompt:  'Enter  component  name' 
default :  ' ' . 

Cursor  offset:  MenuPosition. 

Aname . ! 
getNewName 

"Answer  a  user-specified  name  for 
a  new  component . " 

I  name  : 

Cursor  offset:  MenuPosition. 
name  : = 

Prompter 

prompt:  'Enter  name  for  new  component' 
default:  ' ' . 

Cursor  offset:  MenuPosition. 
name  isNil 

ifTrue:  (Anil) . 

((self  componentNamed:  name)  isNil] 
whileFalse:  ( 
name  := 

Prompter 

prompt.:  'Name  exists  —  enter  NEW  name' 
default:  name. 

Cursor  offset.:  MenuPosition. 
name  isNil 

ifTrue:  [ Anil ] ] . 

Aname. ! 
getNode 

"Answer  a  user-specified  LogicNode." 

I  component  1 

component  :=  self  getExistingComponent. 
component  isNil 
ifTrue:  [Anil] . 

A (component  getNode) . ! 
initialize 

"Private  —  initialize  a  new 
LogicLab  application." 
devices  :=  OrderedCollection  new. 
signals  :=  OrderedCollection  new. 
switches  :=  OrderedCollection  new. 
changed  :=  true.! 
install 

"Install  a  user-specified  component." 

!  component  I 

component  :=  LogicComponent  install, 
component  isNil 
ifTrue:  [Anil] . 
self  addComponent :  component. 
listSelector  :=  self  listSelectorFor:  component, 
breadboard  update. 

"component . ! 

installClassFrom:  aStream 

"Install  a  LogicComponent  subclass 
whose  name  is  the  next  word  on  aStream." 

I  className  I 

className  :=  aStream  nextWord. 

(Smalltalk  includesKey:  className  asSvmbol) 
if False:  ( 

self  error:  ('Class:  ',  className,  '  not  installed')].! 
installComponentFrom:  aStream 

"Install  a  LogicComponent  instance 

whose  name  is  the  next  word  on  aStream." 

'  className  class  component  I 
className  :=  aStream  nextWord. 
class  :=  LogicComponent  classNamed:  className. 
class  isNil 
ifTrue:  [ 

self  error:  ('Unknown  class:  ',  className). 

Anil]  . 

component  :=  class  new  installFrom:  aStream. 
component  isNil 

ifTrue:  ["nil]. 
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"(self  addComponent:  component).! 
installConnectionFrom:  aStream 

"Install  a  connection  from  aStream." 

!  fromName  from  toName  to  fromNode  toNode  I 
fromName  :=  aStream  nextWord. 
from  :=  self  componentNamed:  fromName. 
from  isNil 
ifTrue:  ( 

self  error:  ('Unknown  component:  ',  fromName). 

Anil] . 

fromNode  :=  from  getNodeFrom:  aStream. 
fromNode  isNil 
ifTrue:  [ 

self  error:  ('Unknown  node  on:  ',  fromName). 

Anil] . 

toName  :=  aStream  nextWord. 

to  :=  self  componentNamed:  toName. 
to  isNil 
ifTrue:  ( 

self  error:  ('Unknown  component:  ',  toName). 

Anil] . 

toNode  :=  to  getNodeFrom:  aStream. 
toNode  isNil 
ifTrue:  [ 

self  error:  ('Unknown  node  on:  ',  toName). 

Anil]  . 

"(fromNode  connect:  toNode).! 
installFrom:  aStream 

"Load  a  circuit  from  the  description 
on  aStream." 

I  keyWord  ! 

clashes  :=  Dictionary  new. 

[(aStream  atEnd) 

or:  [(keyWord  :=  aStream  nextWord)  isNil]] 
whileFalse:  [ 
keyword  =  ' LOAD' 
ifTrue:  [ 

self  installClassFrom:  aStream] 
ifFalse:  [ 

keyword  =  'INSTALL' 
ifTrue:  [ 

self  installComponentFrom:  aStream] 
ifFalse:  [ 

keyword  =  'CONNECT' 
ifTrue:  [ 

self  installConnectionFrom:  aStream] 
ifFalse:  ( 
self  error: 

('Unknown  command:  ', 
keyWord) ] ] ] ] . 

clashes  release, 
clashes  :=  nil. ! 

list 

"Process  a  user-specified  list  request." 

I  selection  I 
selection  := 

(Menu 

labels:  ('Components\Connections\' , 

'Circuit  Description')  withers 
lines:  #() 

selectors:  # (listComponents 
listConnections 
listCircuit) ) 
popUpAt:  MenuPosition. 
selection  isNil 

ifTrue:  [ "nil ]  . 
listSelector  :=  selection, 
breadboard  update.! 
listCircuit 

"Answer  a  collection  of  strings  with 
the  circuit  description." 

I  name  stream  list  I 
CursorManager  execute  change, 
name  :=  ' logiclab.tmp' . 

stream  :=  File  pathName:  name, 
list  :=  OrderedCollection  new. 
stream 

nextPutAll:  '****  Circuit  Description  ****'; 
cr; 

cr . 

self  storeOn:  stream, 
stream  flush, 
stream  position:  0. 

[stream  atEnd] 

whileFalse:  [list  add:  stream  nextLine] . 
stream  close. 

File  remove:  name. 

CursorManager  normal  change. 

"list . ! 

listComponentConnections 

"Answer  a  collection  of  strings  listing 
the  connection  chain  (s)  for  the 
' currentComponent' . " 
currentComponent  isNil 
ifTrue:  ["#()] 
ifFalse:  [ 

"(#(’****  Connection  List  ****'  ' 

currentComponent  connect ionList) ] . ! 

listComponents 

"Answer  a  collection  of  strings  containing 
a  list  of  installed  components." 

!  selection  : 
selection  := 
self  component TypeMenu: 
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Listing  One  (Listing  continued,  text  begins  on  page  72.) 

# (listDevices  listSignals  listSwitches) . 
selection  isNil 
if True:  [A#()J. 

A (self  perform:  selection) . ! 
listConnections 

"Answer  a  collection  of  strings  listing 
the  connection  chain (s)  for  a 
user-specified  component." 

!  component  ! 

component  :=  self  getExistingComponent . 
component  isNil 
if True:  [A#()]. 

currentComponent  :=  component. 

Aself  listComponentConnections . ! 
listContaining:  aComponent 

"Answer  the  list  (devices,  signals,  or  switches) 
that  includes  aComponent." 

(devices  includes:  aComponent) 
if True:  [Adevices] . 

(signals  includes:  aComponent) 
ifTrue:  [Asignals]. 

Aswitches. ! 
listDevices 

"Answer  a  collection  of  strings  containing 
a  list  of  all  the  installed  devices." 

!  size  list  ! 
size  :=  devices  size, 
size  ■■  0 

ifTrue:  [A#('No  devices  installed')), 
size  :=  size  +  1. 

list  :=  OrderedCol lection  new:  size, 
list  add:  'DEVICES'. 

devices  do:  [: aDevice:  list  add:  ('  ',  (aDevice  identify))]. 

Alist . ! 

listSelectorFor:  aComponent 

"Answer  the  list  selector  method  used 
to  produce  the  list  for  aComponent' s  type." 
aComponent  isDevice 

ifTrue:  [A#listDevices] . 
aComponent  isSignal 

ifTrue:  [A#listSignals] . 

Af listSwitches . ! 
listSignals 

"Answer  a  collection  of  strings  containing 
a  list  of  all  the  installed  input  signals." 

!  size  list  ! 

size  :=  signals  size. 

size  ==  0 

ifTrue:  [A#('No  signals  installed')], 
size  :=  size  +  1. 

list  :=  OrderedCollection  new:  size, 
list  add:  'SIGNALS'. 

signals  do:  [:aSignal!  list  add:  ('  ',  (aSignal  identify))). 

Alist. ! 
listSwitches 

"Answer  a  collection  of  strings  containing 
a  list  of  all  the  installed  swithces." 

!  size  list  ! 
size  :=  switches  size, 
size  ==  0 

ifTrue:  (A# (' No  switches  installed')], 
size  :=  size  +  1. 

list  :=  OrderedCollection  new:  size, 
list  add:  'SWITHCES'. 

switches  do:  [:aSwitch!  list  add:  ('  ',  (aSwitch  identify))]. 

Alist . ! 

load 

"Load  a  circuit  description  from 
a  user-specified  file." 

!  file  !' 

file  :=  self  getFile. 
file  isNil 

ifTrue:  [Anil] . 
self  installFrom:  file. 

listSelector  :=  #listDevices . 

breadboard  update.! 

noDelay 

"Setup  all  components  to  ignore 
propagation  delays." 
signals  do:  (: signal!  signal  noDelay]. 
switches  do:  (: switch!  switch  noDelay]. 
devices  do:  (:device!  device  noDelay].! 

noMenu 

"Private  —  answer  an  empty  menu." 

A (EmptyMenu  new) . ! 

open 

"Open  the  Breadboard  and  Analyzer  windows." 

!  size  position  ! 

size  :=  (Display  boundingBox  extent  *  3)  //  4. 

position  :=  Display  boundingBox  center  -  (size  //  2). 
topPane  := 

TopPane  new 

label:  ((self  class  description), 

’  —  Breadboard'); 
model:  self; 
menu:  #noMenu; 
yourself. 

topPane  addSubpane: 

(breadboard  :=  ListPane  new 
name:  #breadboardList; 
model:  self; 
menu:  fbreadboardMenu; 
change:  fdoNothing:; 
framingRatio:  (000  extent:  1  0  1)). 
topPane  reframe:  (position  extent:  size). 
topPane  dispatcher  openWindow  scheduleWindow. ! 

quit 

"Quit  this  LogicLab." 


(self  verify:  'Quit  this  LogicLab?') 

ifFalse:  [Anil] . 
self  eraseCircuit . 

signals  :=  switches  :=  devices  :=  nil. 
analyzer  isNil 
ifFalse:  [ 

analyzer  closeWindow. 
analyzer  :=  nil] . 

breadboard  dispatcher  deactivateWindow  closeWindow. 

Scheduler  systemDispatcher  redraw. 

Scheduler  resume . ! 
remove 

"Remove  a  user-specified  component." 

!  component  ! 

component  :=  self  getExistingComponent. 
component  isNil 

ifTrue:  ( Anil ]  . 
changed  :=  true. 

listSelector  :=  self  listSelectorFor:  component, 
self  removeComponent :  component, 
breadboard  update.! 
removeComponent :  aComponent 

"Remove  aComponent  from  the  circuit." 
analyzer  isNil 

ifFalse:  [analyzer  removeComponent:  aComponent]. 

(self  listContaining:  aComponent)  remove:  aComponent. 
aComponent  remove . ! 
reset 

"Reset  all  components." 
signals  do:  [: signal!  signal  reset], 
switches  do:  [: switch!  switch  reset], 
devices  do:  [: device!  device  reset].! 
restoreDelay 

"Setup  all  components  to  use 
propagation  delays." 

signals  do:  [:signal!  signal  restoreDelay]. 
switches  do:  [: switch!  switch  restoreDelay]. 
devices  do:  [: device!  device  restoreDelay].! 
resume 

"Resume  the  breadboarding  application 
after  running  the  simulation." 

Cursor  offset:  breadboard  frame  center. 
topPane  dispatcher  scheduleWindow.! 

run 

"Invoke  the  LogicAnalyzer  to  run  the  simulation." 
analyzer  isNil 
ifTrue:  [ 

analyzer  :=  LogicAnalyzer  new. 

analyzer  openOn:  self] 
ifFalse:  (analyzer  activate] . ! 

save 

"Store  the  circuit  description  in 
a  user-specified  file." 

!  file  ! 

file  :=  self  getFile. 
file  isNil 

ifTrue:  ( Anil]  . 

CursorManager  execute  change, 
self  storeOn:  file, 
file 
flush; 
close. 

CursorManager  normal  change.! 
selectName 

"Answer  a  user-selected  name  from  a  list 
of  the  names  of  installed  components." 

!  names  index  ! 
names  :=  self  allNames. 

(names  size  ==  0) 
ifTrue:  [Anil] . 

index  :=  VariableMenu  selectFrom:  names, 
index  isNil 

ifTrue:  [Anil] . 

A (names  at :  index) . ! 
signalNames 

"Answer  a  collection  of  all  of  the 
names  of  installed  signals." 

!  list  ! 

list  :=  OrderedCollection  new:  (signals  size), 
signals  do:  [:aSignal!  list  add:  aSignal  name]. 

Alist . ! 
signals 

"Answer  the  list  of  installed  signals." 

"signals . ! 
simulate 

"Simulate  one  pseudo-time  interval." 
signals  do:  [: signal!  signal  simulate]. 

switches  do:  [: switch!  switch  simulate], 
devices  do:  [: device!  device  simulate].! 
storeClassesOn:  aStream 

"Write  a  record  of  each  component  class 
used  by  the  circuit  on  aStream." 

!  classes  ! 
classes  :=  Set  new. 

devices  do:  [: aDevice!  classes  add:  aDevice  class], 

signals  do:  [:aSignal!  classes  add:  aSignal  class], 

switches  do:  [: aSwitch:  classes  add:  aSwitch  class), 

classes  do:  [:aClass! 
aStream 

nextPutAll:  ('LOAD  ',  (aClass  name)); 
cr]  . ! 

storeComponentsFrom:  aCollection  on:  aStream 

"Write  a  record  of  each  logic  component  from 
aCollection  installed  in  the  circuit  on  aStream." 
aCollection  do:  [: aComponent ! 
aStream  nextPutAll:  'INSTALL  '. 
aComponent  storeOn:  aStream. 
aStream  cr] . ! 

storeConnectionsOn:  aStream 

"Write  a  record  of  each  connection 

(continued  on  page  136) 
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Listing  One  ( Listing  continued,  text  begins  on  page  72.) 


in  the  circuit  on  aStream." 

devices  do:  [: aDevice!  aDevice  storeConnectionsOn:  aStream]. 
signals  do:  [:aSignal!  aSignal  storeConnectionsOn:  aStream]. 
switches  do:  [:aSwitch!  aSwitch  storeConnectionsOn:  aStream]. 
devices  do:  [:aDevice!  aDevice  unMark] . 
signals  do:  [:aSignal!  aSignal  unMark]. 
switches  do:  [: aSwitch!  aSwitch  unMark].! 
storeDevicesOn:  aStream 

"Write  a  record  of  each  logic  device 
installed  in  the  circuit  on  aStream." 
self  storeComponentsFrom:  devices  on:  aStream.! 
storeOn:  aStream 

"Write  a  description  of  the  circuit  on 
aStream  in  a  form  that  can  be  recovered 
by  the  'installOn:'  method." 

self 

storeClassesOn:  aStream; 
storeDevicesOn:  aStream; 
storeSignalsOn:  aStream; 
storeSwitchesOn:  aStream; 
storeConnectionsOn:  aStream. ! 
storeSignalsOn:  aStream 

"Write  a  record  of  each  logic  signal 
installed  in  the  circuit  on  aStream." 
self  storeComponentsFrom:  signals  on:  aStream.! 
storeSwitchesOn:  aStream 

"Write  a  record  of  each  logic  switch 
installed  in  the  circuit  on  aStream. " 
self  storeComponentsFrom:  switches  on:  aStream. ! 
switches 

"Answer  the  list  of  installed  switches." 

Aswitches. ! 
switchNames 

"Answer  a  collection  of  all  of  the 
names  of  installed  swithces." 

!  list  ! 

list  :-  OrderedCol lection  new:  {switches  size), 
switches  do:  [raSwitch!  list  add:  aSwitch  name]. 

Alist . ! 

verify:  aPrompt 

"Ask  the  user  to  verify  some  condition." 

Cursor  offset:  MenuPosition. 

A ( (Menu  message:  aPrompt)  notNil) . !  ! 


End  Listing  One 


Listing  Two 

LogicSwitch  subclass:  #ToggleSwitch 
instanceVariableNames:  " 
classVariableNames :  " 
poolDictionaries :  ''  ! 

!ToggleSwitch  class  methods  ! 

type 

"Answer  a  string  with  the  receiver's  type." 

A'Toggle  Switch'.!  ! 

JToggleSwitch  methods  ! 
identify 

"Answer  a  string  identifying  the  receiver." 

A((self  name), 

'  {' ,  (self  type) ,  ')').! 
push:  aButton 

"Simulate  pushing  a  toggle  switch  by 
inverting  its  state." 
node  invert, 
node  isHigh 

ifTrue:  [aButton  lampOn] 

ifFalse:  [aButton  lampOff:]. 

(model  isNil  or:  [changeSelector  isNil ] ) 

ifFalse:  [model  perform:  changeSelector].! 

reset 

"Reset  the  receiver." 
button  isNil 
ifFalse:  [ 

node  isHigh 

ifTrue:  [button  lampOn] 

ifFalse:  [button  lampOff ] ] . ! 

simulate 

"Simulate  a  toggle  switch." 

node  output . !  !  End  Listing  Two 


Listing  Three 

LogicSwitch  subclass:  #PulserSwitch 
instanceVariableNames : 

'rest  time  timer  ' 
classVariableNames:  '' 
poolDictionaries:  "  ! 

!PulserSwitch  class  methods  ! 

type 

"Answer  a  string  with  the  receiver's  type." 
A' Pulser' . !  ! 

!PulserSwitch  methods  ! 


identify 

timer  ==  0 

"Answer  a  string  identifying  the  receiver." 

ifTrue:  [ 

A  ( (self  name) , 

node  state:  rest. 

'  (' ,  (self  type) ,  '  —  ' , 

button  isNil 

(LogicNode 

ifFalse:  ( 

statePrintString:  (LogicNode  not:  rest)),  ':  ', 

node  isHigh 

(Timelnterval  timePrintString:  time),  ')').! 

ifTrue:  [button  lampOn] 

initialize 

ifFalse:  [button  lampOff]]] 

"Initialize  a  new  PulserSwitch. " 

ifFalse:  (timer  :=  timer  -  1]. 

super  initialize. 

node  output . ! 

rest  :=  false. 

storeOn:  aStream 

time  :=  timer  :=  0. ! 

"Store  a  record  of  the  receiver  on  aStream." 

install 

super  storeOn:  aStream. 
aStream 

"Answer  the  receiver  with  user-specified 

nextPutAll:  {'  ', 

rest  state  and  pulse  time." 

(LogicNode  statePrintString:  rest),  '  ', 

rest  :=  LogicNode  getState.  "User  will  select  pulse  state" 

rest  isNil 

(time  printstring)).!  ! 

ifTrue:  [Asuper  release]. 

rest  :=  LogicNode  not:  rest. 

time  :=  Timelnterval  getTimeFor:  'pulse' . 
time  isNil 

End  Listing  Three 

ifTrue:  [Asuper  release). 

Aself . ! 

installFrom:  aStream 

Listing  Four 

"Answer  a  new  PulserSwitch  initialized  with 
parameters  read  from  aStream." 

LogicDevice  subclass:  #N74LS00 

super  installFrom:  aStream. 

instanceVariableNames:  " 

rest  :=  LogicNode  stateNamed:  aStream  nextWord. 

classVariableNames:  " 

node  state:  rest. 

time  :=  aStream  nextWord  aslnteger. 

poolDictionaries:  "  ! 

Aself . ! 

1N74LS00  class  methods  ! 

push:  aButton 

description 

"Simulate  pushing  a  Pulser  Switch." 

"Answer  a  string  with  a  description 

timer  ==  0 

of  the  receiver's  function." 

ifTrue:  [node  state:  (LogicNode  not:  rest)]. 

A'Quad  2-input  NAND  gate'.! 

timer  :=  time. 

type 

node  isHigh 

"Answer  a  string  with  the  receiver's  type." 

ifTrue:  [aButton  lampOn] 

A ' 74LS00' . !  ! 

ifFalse:  [aButton  lampOff]. 

IN74LS00  methods  ! 

(model  isNil  or:  [changeSelector  isNil]) 

initialize 

ifFalse:  [model  perform:  changeSelector].! 

"Private  —  initialize  the  propagation  delays 

reset 

for  a  new  74LS00  LogicDevice." 

"Reset  the  receiver's  state  to  its  resting 

super 

state  and  its  timer  to  zero." 

initialize; 

node  state:  rest. 

initializeDelays: 

timer  :=  0. 

#(  5  5  10  5  5  10  0 

button  isNil 

10  5  5  10  5  5  0  ) .  ! 

ifFalse:  [ 

simulate 

node  isHigh 

"Simulate  a  74LS00  device." 

ifTrue:  [button  lampOn] 

((pins  at:  1)  isHigh  and:  [(pins  at:  2)  isHigh]) 

ifFalse:  (button  lampOff]].! 

ifTrue:  ((pins  at:  3)  output:  false] 

simulate 

ifFalse:  [(pins  at:  3)  output:  true]. 

"Simulate  a  Pulser  Switch." 

({pins  at:  4)  isHigh  and:  [(pins  at:  5)  isHigh]) 
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Listing  Four  (Listing  continued,  text  begins  on  page  72.) 


Listing  Six 


ifTrue:  [(pins  at:  6)  output:  false] 
ifFalse:  ((pins  at:  6)  output:  true]. 

((pins  at:  10)  isHigh  and:  [(pins  at:  9)  isHigh]) 
ifTrue:  [(pins  at:  8)  output:  false] 
ifFalse:  [(pins  at:  8)  output:  true]. 

((pins  at:  13)  isHigh  and:  [(pins  at:  12)  isHigh]) 
ifTrue:  [(pins  at:  11)  output:  false] 
ifFalse:  [(pins  at:  11)  output:  true].!  ! 


"Simulate  a  74LS00  device." 


End  listing  Four 


Listing  Five 

output:  aState 

"Generate  aState  as  an  output  from  the  node." 

old  :=  int. 
int  :=  aState. 
int  =  ext 
ifTrue:  ( 

"State  is  stable" 
timer  :=  0. 

Aself  output ToConnect ions] . 

"State  has  changed" 
timer  ==  0 
ifTrue:  [ 

"No  delay  in  progress  —  initiate  prop  delay" 
delay  ==  0 
ifTrue:  [ 

"No  delay  —  just  change  state" 
ext  :=■  int] 
ifFalse:  [ 

"Arm  delay  timer" 
timer  :=  delay] . 

Aself  output ToConnect ions] . 

"Propagation  delay  in  progress" 
timer  :=  timer  -  1. 
timer  ==  0 
ifTrue:  [ 

"Timer  has  expired  —  update  state" 
ext  :=  int] . 

self  outputToConnect ions . 


( (pins  at :  1) 
ifTrue:  [ 
ifFalse:  [ 
( (pins  at:  4) 
ifTrue:  [ 
ifFalse:  [ 
({pins  at:  10) 
ifTrue:  [ 
ifFalse:  [ 
((pins  at:  13) 
ifTrue:  [ 
ifFalse:  ( 


isHigh  and:  [ 
(pins  at:  3) 
(pins  at:  3) 
isHigh  and:  [ 
(pins  at:  6) 
(pins  at:  6) 
isHigh  and: 
(pins  at:  8) 
(pins  at:  8) 
isHigh  and: 
(pins  at:  11) 
(pins  at:  11) 


(pins  at:  2)  isHigh] ) 
output:  false) 
output:  true] . 

(pins  at:  5)  isHigh]) 
output:  false] 
output:  true]. 

[(pins  at:  9)  isHigh]) 
output:  false] 
output:  true]. 

[(pins  at:  12)  isHigh]) 
output:  false) 
output:  true]. 


End  Listings 


End  Listing  Five 
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OOPSLA  ’89: 
Fourth  Down 
And  Goal  to  Go 


As  I  walked  through  New  Orleans’s 
colorful  French  Quarter  one  hot 
night  in  early  October,  a  man 
caught  my  sleeve  and  offered  to 
bet  me  five  dollars  that  he  could  guess 
where  I  got  my  shoes.  I  declined  his 
tempting  offer,  assuming  that  the  an¬ 
swer  was,  in  a  shoe  store.  I  was  in  town 
for  the  Fourth  Annual  Conference  on 
object-oriented  systems,  languages,  and 
applications  (OOPSLA  ’89),  and  the  next 
morning  as  I  sat  listening  to  a  panel 
discussion,  it  stntck  me  that  this  was 
an  object-oriented  gag,  deliberately  con¬ 
fusing  class  with  instance.  Maybe  OOPS 
is  taking  over  the  world. 

Talking  About  a  Revolution 

It  was  easy  to  believe  that  there  was 
an  object-oriented  revolution  underway 
that  day  at  the  show.  There  was  a  lot 
of  enthusiasm,  and  there  were  a  lot  of 
people.  Although  claims  of  2000  atten¬ 
dees  at  last  year’s  OOPSLA  may  have 
been  exaggerated,  this  year  there  prob¬ 
ably  were  about  that  many.  The  pre¬ 
registration  and  on-site  registration  at¬ 
tendee  lists  give  1626  names,  by  my 
count.  In  any  case,  the  figures  don’t 
reflect  the  mad  rush  when  the  exhibit 
doors  opened  Tuesday  morning.  Al¬ 
though  they  gave  different  reasons,  ev¬ 
eryone  I  asked  said  that  this  OOPSLA 
was  the  best  they’d  been  to. 

Some  attendees  had  a  greater  pres¬ 
ence  than  most.  Apple  announced  its 
C++  and  talked  around  the  edges  of 


Michael  Swaine 


Apple  Script,  its  planned  user  program¬ 
ming  language.  Borland  announced 
Turbo  Pascal  5.5  with  object-oriented 
support.  But  there  was  more  interest 
in  what  might  be  coming  in  the  next 
few  months  from  Borland  and  from 
Microsoft,  which  was  not  present  as 
an  exhibitor,  although  a  number  of 
Microsoft  employees  were  there.  The 
biggest  presence  at  OOPSLA  ’89, 


though,  was  definitely  C++,  already  the 
most  widely-used  object-oriented  lan¬ 
guage  and  spreading  like  —  well,  you 
can  supply  your  own  simile.  Some  peo¬ 
ple  think  C++  is  a  disease  that  we  will 
all  soon  be  required  to  contract. 

All  the  expected  exhibitors  were 
there:  Digitalk,  The  Whitewater  Group, 
and  Interactive  Software  Engineering 
in  the  booth  right  in  front  of  the  en¬ 
trance.  But  there  were  few  announce¬ 
ments  of  importance;  this  was  an  ACM 
conference,  not  Comdex,  and  the  real 
action  was  in  the  presentations. 

The  tutorials  began  the  conference, 
and  to  a  certain  extent,  they  reflect  the 
topics  of  greatest  programmer  interest 
or  areas  of  greatest  difficulty  in  OOP 
today,  because  they  cover  the  topics 
that  teachers  of  OOP  are  finding  a  de¬ 
mand  for.  Most  of  the  tutorials  were 
not  specially  created  for  the  show  but 
are  classes  that  people  in  the  field  have 
been  putting  on  over  the  past  year. 

Jon  Pugh  of  Carleton  University  set 
up  the  tutorials,  which  included  intro¬ 
ductions  to  OOP  concepts,  MacApp, 
and  C++,  plus  object-oriented  issues 
in  databases  and  concurrency.  There 
were  also  tutorials  evaluating  OOP  en¬ 
vironments,  including  NextStep,  C++, 
Smalltalk,  MacApp,  and  a  portable  C++ 
class  library  for  Unix  called  “ET++,” 
along  with  more  advanced  tutorials  on 
object-oriented  analysis  and  design,  pro¬ 
totyping,  and  managing  object-oriented 
software  projects.  ET++  is  likely  to  get 
a  lot  of  attention,  because  there’s  not 
much  out  there  in  the  way  of  libraries 
for  C++. 

After  two  days  of  tutorials,  the  con¬ 
ference  proper  began.  The  emphasis 
in  the  conference  program  shifted  this 
year  away  from  some  peripheral  issues 
such  as  general  software  engineering, 
user  interface  design,  and  databases, 
and  toward  more  depth  of  coverage  in 
theory,  language  design  and  implemen¬ 
tation,  and  concurrency.  Conference 
Chair  Kent  Beck  explained  that  the  pe¬ 
ripheral  areas  were  welcomed  in  the 


past  because  they  would  not  have  got 
a  proper  hearing  in  any  other  venue 
until  recently.  Now,  though,  object- 
oriented  work  is  invading  the  general 
computer  magazines  and  journals  and 
other  conferences,  and  OOPSLA  could 
get  more  focused. 

The  overall  impression  I  got  from 
the  attendees,  the  exhibits,  the  tutori¬ 
als,  and  the  conference  program,  was 
of  a  fringe  thread  in  the  process  of 
being  pulled  up  into  the  general  fabric 
of  software  research  and  development. 

Except,  of  course,  for  the  fact  that 
there  still  does  not  seem  to  be  a  univer¬ 
sally  accepted  definition  of  object-ori¬ 
ented  programming. 

Views  from  the  Navel  Observatory 

If  you  can  believe  Johnny  Carson,  some 
20  percent  of  the  people  in  this  country 
examine  their  belly  buttons  daily.  A 
disproportionate  number  of  these  na¬ 
vel  observers  were  at  the  Hyatt  Re¬ 
gency  in  New  Orleans  the  first  week 
in  October,  asking  themselves  and  each 
other  what  object-oriented  program¬ 
ming  is.  To  be  fair,  I  should  add  that 
just  as  many  people  were  answering 
the  question  as  asking  it;  I  just  wish  I 
could  say  that  they  were  giving  the 
same  answer. 

The  answer  involves  some  subset  of 
these  features,  apparently:  These  data/ 
code  hybrids  called  objects,  object 
classes  of  which  particular  objects  are 
instances,  an  inheritance  mechanism 
defined  on  these  classes,  and  the  abil¬ 
ity  to  define  new  object  classes.  At  least 
one  language  has  been  called  object- 
oriented  despite  the  lack  of  each  of 
these  features,  although  each  has  been 
put  forth  as  necessary  by  one  authority 
or  another,  and  all  at  OOPSLA  ’89. 

The  keynote  speech  by  Peter  Wegner 
of  Brown  University  was  a  proper  ques¬ 
tion  raiser  and  territory  mapper.  Wegner 
wrote  the  first  book  on  Ada  and  got 
interested  in  object-oriented  program¬ 
ming  early  on  because  of  his  percep¬ 
tion  of  Ada’s  deficiencies  as  a  language 
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for  software  engineering.  In  Wegner’s 
view,  the  goals  of  object-oriented  pro¬ 
gramming  are:  Creating  a  technology 
of  off-the-shelf  software  components, 
developing  distributed  national  and  in¬ 
ternational  software  libraries,  and  grow¬ 
ing  to  a  capital-intensive  software  tech¬ 
nology  in  which  one  can  buy  rather 
than  build.  He  also  sees,  as  a  present 
goal,  the  extending  of  OOP  to  encom¬ 
pass  what  he  calls  OOP  in  the  large: 
Object-oriented  systems  supporting  con¬ 
currency  and  persistent  objects  for  mul¬ 
tiple  computers  and  multiple  users,  and 
distributed  data  and  cooperative  com¬ 
puting. 

Not  all  the  presentations  followed 
Wegner’s  map. 

One  session  described  SELF,  a  dy¬ 
namically-typed  object-oriented  lan¬ 
guage.  The  authors,  Craig  Chambers, 
David  Ungar,  and  Elgin  Lee,  all  of  Stan¬ 
ford,  presented  an  object-oriented  ap¬ 
proach  that  substitutes  prototypes  for 
classes.  Although  SELF  has  objects  and 
inheritance,  by  Wegner’s  criteria  it  is 
not  object-oriented,  because  it  has  no 
classes.  Objects  are  cloned  from  other 
(prototype)  objects,  from  which  they 
inherit  behavior  directly.  In  another  ses¬ 
sion,  Ungar  predicted  that  prototype- 
based  languages  will  ultimately  replace 
class-based  ones. 

Of  more  immediate  interest  than  the 
implementation  peculiarities  of  the  SELF 
language,  though,  is  the  fact  that  SELF 
runs  twice  as  fast  as  the  fastest  Small¬ 
talk  implementation,  even  though  SELF 
is  inherently  less  efficient  than  Small¬ 
talk.  The  authors  have  optimized  SELF 
with  techniques  applicable  (but  not  yet 
applied)  to  any  other  object-oriented 
language,  and  have  not  had  to  hard¬ 
wire  any  user-level  operations  into  the 
compiler,  as  some  researchers  have 
done  with  Smalltalk  implementations. 
They  bluntly  say  “researchers  seeking 
to  improve  performance  should  improve 
their  compilers  instead  of  compromising 
their  languages.” 

That  could  be  the  answer  to  one  of 
the  other  nagging  issues  in  object- 
oriented  programming:  Can  an  OOP 
system  provide  the  strong  typing  needed 
for  software  engineering  and  at  the 
same  time  remain  a  good  system  for 
rapid  prototyping?  Those  of  a  software 
engineering  bent  and  those  who  like 
OOPS  for  rapid  prototyping  both  like 
inheritance,  but  seem  to  use  it  for  dif¬ 
ferent  purposes.  The  differences  revolve 
around  type  checking  and  the  relation¬ 
ship  between  types  and  classes.  Panel¬ 
ists  in  one  session  argued  that  types 
and  classes  are  really  orthogonal  and 
should  not  be  confused;  and  that  pro¬ 
gramming  environments  could  be,  but 
are  not,  constructed  to  support  both 


production  and  exploratory  program¬ 
ming.  But  one  dissenter,  David  Stem- 
pel  of  the  University  of  Massachusetts, 
said  that  the  only  way  that  one  envi¬ 
ronment  can  support  both  styles  of  pro¬ 
gramming  is  by  really  being  two  envi¬ 
ronments,  with  a  switch  to  turn  off 
prototyping  features  when  in  produc¬ 
tion  mode. 

Several  talks  dealt  with  the  teaching 
of  OOP  concepts.  The  simplest  tech¬ 
nique  presented  was  in  some  ways  the 
most  intriguing.  Kent  Beck  of  Apple 
and  Ward  Cunningham  of  Wyatt  Soft¬ 
ware  Services  presented  an  index-card- 
based  approach  they  have  been  using 
to  teach  OOP.  The  approach  involves 
representing  objects  with  3x5  index 
cards,  and  placing  the  cards  in  appro¬ 
priate  physical  relationship  to  one  an¬ 
other.  A  card  contains  three  kinds  of 
information  about  the  object:  Its  class 
name,  its  responsibilities  (problems  it 
is  to  solve),  and  its  collaborators  (what 
other  classes  it  messages  or  is  mes¬ 
saged  by),  presumably  written  in  pen¬ 
cil  for  easy  modification.  This  simple 
technique  apparently  underscores  the 
objectness  of  the  objects,  and  the 
authors  report  students  picking  the  cards 
up  and  waving  them  around  to  dem¬ 
onstrate  their  interaction. 

Getting  Software  Engineering  on  the  Track 

There’s  not  even  agreement  that  soft¬ 
ware  engineering  is  the  goal  of  OOP, 
although  many  people  not  only  be¬ 
lieve  it  to  be  the  goal  but  even  speak 
as  though  there  were  such  agreement. 

The  early  afternoon  of  the  first  day 
of  the  program  was  given  over  to  soft¬ 
ware  engineering  papers  and  a  panel 
on  the  more-or-less  SE-oriented  topic 
of  the  role  of  transactions  in  object- 
oriented  systems.  A  couple  of  other 
panel  discussions  directly  addressed  soft¬ 
ware  engineering  concerns  as  well,  in¬ 
cluding  a  discussion  moderated  by  Brad 
Cox  on  the  software  industrial  revolu¬ 
tion.  Cox  was  of  the  opinion  that  the 
revolution  will  need  more  than  inter¬ 
changeable  parts  —  it’ll  also  need 
gauges  or  templates  to  ensure  that  the 
parts  fit.  He  stressed  the  importance  of 
developing  the  gauges  apart  from  the 
parts  they  test  —  possibly  even  employ¬ 
ing  a  different  technology  to  develop 
them. 

There  was  one  field  report  from  pio¬ 
neers  trying  to  build  a  full  software 
development  environment  using  object- 
oriented  technology.  William  Harrison, 
John  Shilling,  and  Peter  Sweeney  de¬ 
scribed  their  system,  which  runs  on  a 
PS/2  under  OS/2,  an  RT/PC  under  AIX, 
and  even  an  AT  under  MS-DOS  in  640K 
RAM.  (Two  of  them  work  for  IBM.)  The 
system  has  a  persistent  object  store  — 


the  object-oriented  version  of  a  file  sys¬ 
tem.  With  some  200,000  objects  in  their 
store,  the  authors  have  some  experience 
with  the  use  of  objects,  and  it  is  sugges¬ 
tive  that  they  found  that  organizing 
objects  by  type  hierarchy  did  not  work 
well,  because  their  actual  use  of  ob¬ 
jects  did  not  reflect  a  type  hierarchy. 
They  found  some  serious  hurdles,  too, 
and  concluded  that  the  object-oriented 
paradigm  needs  some  extensions  if  it 
is  to  be  used  for  things  such  as  version 
control,  and  that  the  paradigm  currently 
does  not  provide  the  necessary  sup¬ 
port  for  modifying  and  extending  the 
paradigm  itself. 

Lt.  Col.  John  Morrison  of  the  Na¬ 
tional  Test  Bed  spoke  briefly  of  one  of 
the  more  ambitious  software  projects 
to  date:  The  Strategic  Defense  Initia¬ 
tive.  Whether  one  thinks  SDI  is  a  bril¬ 
liant  and  achievable  project  or  a  fast 
one  put  over  on  a  gullible  chief  execu¬ 
tive,  SDI  research  should  be  a  remark¬ 
able  testbed  for  software  engineering 
and  reusable  components.  One  of  the 
elements  is  intended  to  be  a  large  na¬ 
tional  library  of  reusable  software  com¬ 
ponents. 

Real  Applications 

Others  discussed  how  they  were  using 
object-oriented  technology  for  real  ap- 
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plications  in  commercial  software  de¬ 
velopment,  CAE/CAD,  and  scientific  com¬ 
puting. 

Aldus  personnel  discussed  how  they 
are  using  object-oriented  techniques 
to  manage  software  development  in 
expanding  teams  of  developers  in  the 
face  of  competitive  pressure  to  deliver. 
The  Aldus  VAMP  system  has  helped 
them  isolate  the  developer  from  differ¬ 
ences  in  Macintosh  and  Windows  event¬ 
dispatching,  for  example. 

There  were  several  presentations  on 
business  applications.  Two  that  seemed 
significant  were  an  implementation  of 
security  in  an  object-oriented  system 
at  MCC,  and  a  language  developed  at 
GE  Corporate  R&D  and  Calma.  The 
MCC  system  implemented  security  lev¬ 
els  from  Unclassified  through  Confi¬ 
dential  and  Secret  to  Top  Secret,  more 
than  the  average  business  requires,  one 
would  think,  but  it  was  classified  as  a 
business  presentation.  The  system  from 
Calma  and  GE,  called  DSM,  is  designed 
for  commercial  CAE/CAD  applications. 
DSM  supports  most  of  the  features  ex¬ 
pected  in  an  object-oriented  language 
and  is  reported  to  be  nearly  as  efficient 
as  writing  straight  C  code.  The  only 
explanation  offered  for  this  remarkable 
performance  was  that  DSM  trades  mem¬ 
ory  for  speed. 

Papers  on  scientific  computing  came 
from  three  distinct  object-oriented  back¬ 
grounds:  CLOS  (the  Common  Lisp  Ob¬ 
ject  System),  Smalltalk,  and  C++.  Be¬ 
sides  talks  on  systems  for  function  mini¬ 
mization,  automatic  differentiation,  and 
linear  algebra,  there  was  an  interesting 
discussion  of  scientific  prototyping.  I 
guess  what  I  found  most  interesting 
about  it  was  the  realization  that  the 
ability  to  construct  3-D  computer  mod¬ 
els  of  objects  and  processes  and  to 
manipulate  the  models  has  become  an 
essential  tool  of  scientific  research.  San¬ 
dra  Walther  and  Richard  Peskin  pre¬ 
sented  a  Smalltalk-based  scientific  pro¬ 
totyping  environment  that  uses  C  primi¬ 
tives  for  efficiency. 

Is  OOP  seeing  real  use  in  embedded 
systems  development?  Design?  Im¬ 
plementation?  And  does  it  have  a  fu¬ 
ture  there?  The  one  case  study  of  em¬ 
bedded  system  development  presented 
at  the  conference  suggests  what  one 
might  expect:  OOP  was  a  good  tool  for 
managing  the  development  process  and 
coming  up  with  the  basic  design  in  a 
short  time,  but  the  actual  implementa¬ 
tion  required  substantial  recoding  in  C 
and  assembler. 

The  State  Space  of  the  Art 

Any  description  of  the  state-of-the-art 
in  any  developing  field  always  sounds 
wrong  to  some  part  of  the  audience. 


What  looks  close  to  SOA  to  one  person 
may  be  SF  to  another.  To  traditional 
DP  professionals  it  may  be  a  non-issue: 
Bill  Joy  said  he  did  not  consider  tradi¬ 
tional  DP  professionals  a  market  for 
OOP  because  they  would  not  under¬ 
stand  it.  Later,  being  fair,  he  added  that 
he’d  say  the  same  about  most  C  pro¬ 
grammers. 

Bill  Joy  said  that,  not  me.  My  only 
point  is  that  the  state-of-the-art  has  thick¬ 
ness;  it’s  not  so  much  a  time  slice  as  a 
time  loaf.  At  OOPSLA  ’89  there  were 
SOA  talks  on  theory,  and  SOA  talks  at 
the  implementation  level. 

A  couple  of  the  implementation  is¬ 
sues  on  the  edge  are  efficient  garbage 
collection  and  how  to  implement  per¬ 
sistent  objects  and  virtual  memory  for 
objects.  One  of  the  concepts  being  use¬ 
fully  employed  in  garbage  collection 
is  the  notion  of  a  generation:  Several 
systems  separate  objects  by  age,  focus¬ 
ing  garbage  collection  on  the  youngest 
generation,  where  turnover  is  likely  to 
be  most  rapid. 

One  of  the  more  interesting  theoreti¬ 
cal  papers  showed  that  inheritance, 
rather  than  being  merely  a  feature  of 
object-oriented  programming,  is  a  gen¬ 
eral  method  that  can  be  applied  to  any 
form  of  recursive  definition. 

Some  presentations  were  state-of-the- 
art  in  any  sense,  focusing  on  concepts 
on  the  edge,  such  concurrency,  agents, 
and  reflection. 

Object-oriented  programming  decom¬ 
poses  problems  in  ways  nicely  suited 
to  communicating  processes  in  a  paral¬ 
lel  architecture.  The  conference  dem¬ 
onstrated  that  there  are  real  implemen¬ 
tations  of  OOP  systems  that  imple¬ 
ment  fine-grained  parallelism,  although 
they  probably  won’t  run  on  your  ma¬ 
chine  yet. 

Several  talks  dealt  with  agents  that 
may  turn  out  to  be  important  for  mak¬ 
ing  sharable,  reusable  software  com¬ 
ponents  work  in  practice  in  widely  dis¬ 
tributed  systems.  Agents  are  indepen¬ 
dently  executing  entities  sensitive  to 
particular  stimuli.  Such  entities  could 
be  trained  to  search  libraries  for  the 
software  components  needed.  In 
“Swaine’s  Flames”  I  speculate  about 
the  economic  consequences  of  such  a 
system,  but  the  need  for  some  method 
of  automating  the  search  for  software 
components  seems  clear.  If  one  of  the 
goals  of  object-oriented  programming 
is  reusability,  and  if  objects  are  going 
to  multiply  as  fast  as  some  of  the  pres¬ 
entations  at  the  conference  suggest,  auto¬ 
mating  the  process  of  connecting  the 
component  with  the  person  who  needs 
it  will  be  essential. 

Reflection  is  the  ability  of  a  system 
to  represent  and  reason  about  itself.  It 


turns  out  to  be  relatively  easy  to  imple¬ 
ment  some  form  of  reflection  in  Small¬ 
talk  and  some  other  OOP  languages. 
The  benefits  discussed  at  the  confer¬ 
ence  include  modifying  the  behavior 
of  the  system,  monitoring  entities  of 
the  system,  and  self  reoiganization  (learn¬ 
ing).  Formerly  viewed  as  an  academic 
topic,  reflection  is  beginning  to  be  con¬ 
sidered  for  practical  implementations. 
One  presentation  discussed  a  way  of 
implementing  many  of  the  benefits  of 
full  reflection  with  no  cost  in  efficiency. 

Maybe  reflective  programs  could  de¬ 
bug  themselves.  That  would  be  handy. 

During  one  of  the  panel  discussions, 
Bjame  Stroustrup,  humble  developer 
of  an  arrogant  language,  told  the  audi¬ 
ence  that  anyone  claiming  that  object- 
oriented  programming  will  bring  about 
bug-free  software  was  probably  spend¬ 
ing  his  evenings  in  the  French  Quarter 
guessing  where  people  got  their  shoes. 
I  didn’t  notice  if  Lt.  Col.  Morrison 
laughed. 
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C  PROGRAMMING 


Text  Searching,  C++ 
and  OOPS,  and 
ANSI  Strings 


This  month  we  are  going  to  start 
a  new  “C  Programming”  column 
project.  We  are  going  to  examine 
some  of  the  problems  associated 
with  the  maintenance  of  large  text  data 
bases.  You  might  be  familiar  with  the 
problem.  You  have  a  lot  of  reference 
material  and  you  do  not  always  know 
how  to  find  what  you  are  looking  for. 
Sometimes  the  reference  material  is 
stored  in  text  files.  If  you  keep  a  lot  of 
word  processing  files  at  work,  or  if  you 
download  a  lot  of  software  with  .DOC 
or  READ. ME  files,  your  material  is  stored 
somewhere  in  ASCII  text  and  would 
be  ready  to  be  read  if  only  you  could 
find  it.  Our  new  project  will  address 
the  problems  associated  with  locating 
the  text  files  that  have  the  information 
we  need. 

Someday  everyone  will  have  Optical 
Character  Recognition  scanners,  and 
we  will  store  all  our  books  and  maga¬ 
zines  on  disk.  Maybe  the  magazines 
will  begin  to  sell  their  editorial  content 
on  diskettes  or  CD-ROM  as  well.  When 
that  happens,  then  all  our  reference 
works  will  be  ready  for  treatment  by  a 
document  processor  similar  to  the  one 
we  will  build  here  in  this  column. 

There  are  a  number  of  software  pack¬ 
ages  that  do  what  we  will  build  here. 
Most  CD-ROM  distributions  of  large  text 
data  bases  include  such  a  system.  We 
will  build  our  own.  That  way  each  of 
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us  can  customize  it  to  our  specific  re¬ 
quirements.  This  software  will  be  ge¬ 
neric  standard  C.  If  you  want  to  inte¬ 
grate  it  into  a  particular  user  platform, 
it  should  port  with  little  difficulty.  Our 
project  will  build  a  system  that  we  will 
call  TEXTSRCH. 

There  are  a  number  of  disciplines 
that  we  must  address  in  the  develop¬ 
ment  of  such  a  project.  First,  we  must 


ask,  given  a  large  text  data  base  and 
someone  to  search  it,  how  does  the 
search  proceed?  What  are  the  search 
criteria  and  how  will  we  express  them 
to  the  software?  These  are  the  first  re¬ 
quirements  to  consider,  because  they 
will  determine  what  techniques  we  use 
to  store  and  find  things.  Next,  once 
we  identify  files  of  text  that  match  our 
search  criteria,  how  must  the  system 
present  them  to  us? 

The  TEXTSRCH  Data  Base 

A  document  retrieval  system  such  as 
TEXTSRCH  works  best  in  an  environ¬ 
ment  where  the  data  files  are  static. 
There  is  a  lot  of  text  and  it  does  not 
change  much.  Users  control  changes 
with  addendum  or  replacement  docu¬ 
ments  at  scheduled  intervals.  Typical 
applications  are  engineering  specifica¬ 
tions,  maintenance  manuals,  and  refer¬ 
ence  libraries. 

To  build  the  data  base,  you  collect 
the  documents  in  a  controlled  location, 
perhaps  its  own  subdirectory,  and  then 
you  build  an  index.  The  index  sup¬ 
ports  searches.  Some  systems  require 
you  to  manually  examine  every  docu¬ 
ment  and  mark  all  the  phrases  that  will 
appear  in  the  index.  Others  build  the 
index  by  automatically  scanning  the 
text  and  extracting  words.  We  will  use 
this  second  approach. 

You  want  to  use  this  kind  of  system 
on  a  static  data  base  because  the  index¬ 
ing  operation  can  take  a  long  time. 

Retrievals 

With  the  data  base  in  place  and  the 
index  built,  you  are  ready  to  perform 
retrievals.  Let’s  first  discuss  how  such 
searches  will  proceed.  Someone  will 
want  to  find  all  references  to  a  word 
or  phrase  in  the  data  base.  Perhaps  you 
will  want  every  reference  to  the  phrase, 
“object-oriented  programming.”  You 
must  tell  the  system  what  you  want, 
and  it  must  tell  you  where  you  can  find 


those  references.  But  suppose  you  are 
interested  only  in  references  to  OOP 
that  are  specifically  about  Smalltalk. 
Then  you  might  want  your  search  to 
deliver  only  those  files  where  both  key 
phrases  appear.  Another  search  might 
want  to  specifically  exclude  references 
to  C++,  and  so  you  must  be  able  to  tell 
the  system  about  that  requirement  as 
well. 

Queries 

You  can  see  where  we  are  heading.  It 
is  apparent  at  the  outset  that  we  need 
some  form  of  structured  query  language 
with  Boolean  operators.  We  need  to 
be  able  to  parse  an  expression  such  as 
this  one: 

“object  oriented”  and  “Smalltalk”  but 

not “C++” 

Our  expressions  will  have  operators 
with  precedence,  so  we  will  need  to 
use  parentheses  to  override  the  default 
precedence  assigned  by  the  parser,  mak¬ 
ing  an  expression  such  as  this  one  pos¬ 
sible: 

“object  oriented”  and  (“design”  or 

“programming”) 

The  TEXTSRCH  Expression  Analyzer 

All  of  what  just  preceded  leads  us  to 
our  first  installment.  The  first  set  of 
functions  that  we  will  develop  will  parse 
such  query  expressions  and  prepare 
them  for  a  retrieval  pass  at  the  data 
base.  Listing  One,  page  164,  is  textsrch.h. 
This  listing  is  one  that  will  grow  over 
the  months.  As  we  add  features,  we 
will  add  macros,  prototypes,  and  such 
to  textsrch.h.  This  month  it  contains 
what  we  need  for  expression  analysis. 

Listing  Two,  page  164,  is  express. c, 
the  code  that  parses  our  expressions.  It 
begins  with  a  modified  BNF  that  de¬ 
scribes  the  query  language.  As  you  can 
see,  it  isn’t  very  complex.  A  program 
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that  wants  to  parse  an  expression  calls 
the  lexical_scan  function  in  this  mod¬ 
ule.  The  function  returns  a  NULL  if  it 
finds  an  error.  If  the  expression  is  cor¬ 
rect,  the  function  returns  a  pointer  to 
the  parsed  expression,  which  is  repre¬ 
sented  in  the  form  of  tokens  suitable  for 
processing  by  an  expression  interpreter. 

The  lexical_scan  function  calls  the 
expression  function  to  check  the  ex¬ 
pression  for  syntax  and  to  convert  it 
into  tokens.  The  syntax  check  uses  a 
recursive  descent  parser.  That  is,  if  the 
expression  function  finds  a  left  paren¬ 
theses  in  the  stream,  it  calls  itself  to 
validate  the  expression  that  is  in  paren¬ 
theses,  and  then,  when  it  returns,  it 
expects  to  find  a  right  parenthesis.  If  it 
finds  the  unary  NOT  operator,  it  calls 
itself  to  check  the  expression  that  fol¬ 
lows  the  operator.  If  it  finds  a  word  or 
phrase  —  a  phrase  in  our  context  con¬ 
sists  of  a  group  of  words  surrounded 
by  double  quotes  —  it  looks  at  the  next 
element  in  the  expression.  If  that  ele¬ 
ment  is  the  binary'  AND  or  OR  opera¬ 
tor,  the  expression  function  calls  itself 
to  check  the  expression  to  the  right  of 
the  operator. 

While  validating  the  expression,  the 
program  converts  it  into  tokens.  Each 
language  element  is  a  one-character 
token,  and  the  tokens  are  written  into 
an  array  in  the  order  in  which  they 
occur.  When  the  token  is  a  word  or 
phrase,  which  is  assigned  the  OPER¬ 
AND  token,  an  associated  string  con¬ 
tains  the  value  of  the  word  or  phrase. 

After  the  expression  is  found  to  be 
correct  and  the  tokens  are  built,  the 
lexical_scan  function  calls  the  postfix 
function.  Its  purpose  is  to  convert  the 
token  stream  from  infix  notation  to 
postfix  notation.  An  expression  in  infix 
notation  uses  defined  operator  prece¬ 
dence  with  parentheses  to  override  the 
defaults.  This  is  the  notation  we  use 
when  we  compose  the  query.  It  is  also 
the  notation  used  by  the  C  language. 
The  postfix  notation  (also  called  Re¬ 
verse  Polish  Notation)  eliminates  the 
parentheses  and  represents  precedence 
by  the  proximity  of  tokens  to  one  an¬ 
other.  Users  of  SNOBOL,  Forth,  and  TI 
scientific  calculators  will  recognize  the 
notation. 

An  infix  expression  places  a  binary 
operator  between  the  operands  as 
shown  here: 

this  and  that 
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The  postfix  version  of  this  expression 
pushes  the  operands  on  a  stack  fol¬ 
lowed  by  the  operator  as  shown  here: 

<and> 

that 

this 

(In  these  examples,  I’ve  used  the  angle 
brackets  to  set  operators  apart  from  the 
operands  on  the  stack.) 

A  parenthesized  infix  expression 
such  as  this: 

(this  and  that)  or  what 

is  represented  on  the  postfix  stack  this 
way: 

<or> 

what 

<and> 

that 

this 

Evaluation  of  a  postfix  expression  is 
a  stack  operation.  The  top  element  is 
popped.  If  the  element  is  an  operand, 
we  use  the  operand  to  derive  the  value 
of  the  expression.  If  the  element  is  a 
unary  operator,  the  next  element  is 
popped  and  evaluated,  the  unary  op¬ 
erator  is  applied  to  it,  and  the  result  is 
pushed.  If  the  element  is  a  binary  op¬ 
erator,  the  next  two  operators  are 
popped,  the  binary  operator  is  applied 
to  them,  and  the  result  is  pushed.  Then 
the  procedure  repeats  until  the  ele¬ 
ment  popped  is  a  single  result.  Each 
pop  is  a  recursive  repeat  of  the  entire 
procedure.  In  our  case  the  pushed  re- 

Object-oriented  design 
involves  building  base 
classes  and  derived 
classes  in  a  class 
hierarchy 


suits  are  true  or  false  values  within  the 
data  base  document  depending  on  the 
search  results.  Each  time  we  pop  a 
word  or  phrase,  we  see  if  it  is  in  the 
data  base  and,  if  so,  in  which  files.  The 
result  of  that  search  is  pushed.  We’ll 
get  further  into  the  details  of  expres¬ 
sion  evaluation  next  month. 


Conversion  from  infix  notation  to 
postfix  notation  is  a  simple  matter.  The 
procedure  is  described  in  detail  in  Fun¬ 
damentals  of  Data  Structures ,  Horo¬ 
witz  and  Sahni,  1976,  Computer  Sci¬ 
ence  Press,  on  pages  91  -  97.  We  im¬ 
plement  this  procedure  in  the  func¬ 
tions  postfix,  isp,  icp,  and  poststack. 

Listing  Three,  page  167,  is  testexpr.c, 
a  program  to  test  our  expression  ana¬ 
lyzer  and  display  the  results.  It  is  a 
throwaway  program  not  to  be  used  in 
the  project  beyond  its  purpose  as  a  test 
and  demonstration  tool.  You  type  your 
expression  into  the  gets  function.  Use 
words  and  phrases  with  interspersed 
operators.  The  valid  operators  are  AND, 
OR,  and  NOT.  The  purpose  of  the  query 
is  to  express  a  pattern  of  words  and 
phrases  that  do  or  do  not  appear  in  the 
text  data  base.  The  TEXTSRCH  pro¬ 
gram  will  find  files  that  match  the  query 
expression.  Typical  expressions  are 
these: 

(fortran  or  cobol)  and  not  pascal 

fortran  or  (cobol  and  not  pascal) 

The  testexpr  program  will  report  a  syn¬ 
tax  error  by  displaying  a  pointer  sym¬ 
bol  below  the  expression  element 
where  it  found  the  error.  If  the  expres¬ 
sion  is  correct,  the  program  will  display 
the  postfix  stack  in  this  format: 

Enter  the  search  expression: 

fortran  or  (cobol  and  not  pascal) 

Token 


<or> 

<and> 

<not> 

pascal 

cobol 

fortran 


Enter  the  search  expression: 

Press  the  Enter  key  with  no  expression 
to  terminate  the  program.  Next  month 
we’ll  discuss  how  we  will  index  the 
data  base  and  how  that  index  will  de¬ 
liver  our  query  results. 

Book  Report:  Object-Oriented  Program 
Design  With  Examples  in  C++ 

Are  you  looking  for  a  stocking  stuffer 
for  yourself  this  season?  There  is  a  new 
book  called  Object-Oriented  Program 
Design  With  Examples  in  C++,  by  Mark 
Mullins.  The  book  is  more  about  object- 
oriented  programming  and  design  than 
about  C++,  but  it  uses  C++  for  exam¬ 
ples  and  is  an  indispensable  addition 
to  your  library  if  you  are  trying  to  figure 
out  OOP  and  C++. 
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Mullin  takes  a  unique  approach  to 
these  subjects.  Instead  of  presenting 
just  another  enhancement  to  the  AT&T 
C++  reference  documents  and  Strous- 
trup’s  book,  he  teaches  the  basics  of 
object-oriented  design  and  uses  C++ 
to  demonstrate  the  lessons.  Follow  this 
book  from  beginning  to  end,  and  you 
will  have  a  manageable  grasp  on  object- 
oriented  design  and  programming  by 
the  time  you’re  done. 

Mullin’s  book  also  teaches  valuable 
lessons  about  the  general  approach  a 
programmer  uses  in  the  design  of  soft¬ 
ware  systems,  object  oriented  or  not, 
and  he  does  it  with  a  writing  style  that 
informs  and  often  entertains  the  reader. 
Every  now  and  then  he  slips  in  a  dry 
joke  that  goes  by  almost  unnoticed. 

To  show  you  how  to  design  an  object- 
oriented  system,  Mullin  undertakes  the 
development  of  an  integrated  informa¬ 
tion  management  system  for  a  fictional 
company.  This  is  the  first  extensive 
treatment  of  OOP  I’ve  seen  that  uses 
real,  believable  examples  of  things  that 
a  programmer  might  encounter  in  the 
real  world.  Most  writers  build  contrived 
analogies  that  attempt  to  relate  abstract 
examples  of  toasters,  fruit,  or  other  silly 
non-automata  to  the  mysterious  things 
that  the  object-oriented  paradigm  calls 
objects.  Mullin  uses  inventory,  sales 
and  personnel  database  records  to  dem¬ 
onstrate  the  development  of  a  class 
hierarchy  to  support  his  hypothetical 

design.  These  are  things  we  can  all 
associate  with. 

Perhaps  you’ve  never  worked  .on  an 
inventory  system,  but  you  can  readily 
see  what  one  might  need  to  do.  If  there 
is  a  warehouse  full  of  stuff  and  you 
need  to  locate  specific  items,  fill  orders 
for  items,  and  replace  what  you  sell, 
then  you  need  an  inventory  system. 
I’ve  worked  on  several.  The  smallest 
was  for  a  video  tape  store;  the  largest 
was  for  spare  parts  for  the  Space  Shut¬ 
tle.  Their  respective  functional  require¬ 
ments  were  similar.  The  inventory  man¬ 
agement  folks  call  it  “material  require¬ 
ments  planning.”  George  Carlin  calls  it 
“keeping  track  of  your  stuff."  Mullin 
takes  this  mundane  application,  one 


that  everyone  will  recognize,  and  de¬ 
signs  an  object-oriented  software  sys¬ 
tem  to  support  it. 

Mullin  traces  the  design  in  the  man¬ 
ner  in  which  it  might  actually  occur. 
The  false  starts,  the  refinement  of  re¬ 
quirements,  the  incremental  develop¬ 
ment  of  an  object-oriented  data  model, 
he  presents  them  all  in  the  sequence 
in  which  you  would  encounter  them 
during  a  real-design  project.  As  he  pro¬ 
ceeds,  Mullin  tells  you  how  you  should 
be  thinking  about  the  objects  and  their 
place  in  the  class  hierarchy. 

Mullin’s  design  sometimes  tends  to 
build  his  data  base  by  using  views  that 
seem  —  at  least  to  me  —  to  be  unnatu¬ 
ral.  Object-oriented  design  involves  build¬ 
ing  base  classes  and  derived  classes  in 
a  class  hierarchy.  Because  every  entity 
in  his  data  base  has  a  name  and  ad¬ 
dress,  Mullin  starts  out  with  a  new  class 
named  “Entity”  that  contains  name  and 
address  members.  Then  he  derives  ev¬ 
erything  else  from  that  class.  This  is 
not  the  natural  view  of  things.  We  are 
not  necessarily  always  subordinate  to 
our  common  denominators.  Because 

If  K&R  can  give  us 
“ initializer ;  ”  I  guess 
X3J11  similarly  pre¬ 
sumed  that  they  could 
extend  English  while 
they  extended  C 


we  all  have  addresses  does  not  mean 
that  we  are  subordinate  to  those  ad¬ 
dresses.  I  think  we  are  seeing  the  ten¬ 
dency  of  the  object-oriented  paradigm 
to  bend  our  perspective  in  inappropri¬ 
ate  directions.  The  solution  to  a  prob¬ 
lem  should  resemble  the  problem,  and 
names  and  addresses  are  components 
of  their  owners,  not  the  other  way 
around.  I  would  have  created  the  En¬ 
tity  class  with  its  name  and  address 
members  and  then  included  an  instance 
of  that  class  in  each  of  the  classes  that 
require  it.  The  functional  result  would 
be  the  same  but  we  would  not  be  forced 
to  perceive  our  data  base  from  an  il¬ 
logical  perspective  just  to  adhere  to 
hierarchical  dogma.  But  then,  I  do  not 
know  enough  about  object-oriented  de¬ 
sign  to  write  a  book.  Not  yet,  at  least. 
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My  only  other  criticism  of  this  book 
is  that  Mullin  and  his  editors  do  not 
seem  to  know  that  the  word  “data”  is 
a  plural  noun.  But  then,  many  of  my 
colleagues  here  at  DDJ  don’t  know  that 
either,  and  I  forget  sometimes,  too.  That 
criticism  aside,  this  is  a  very  good  book. 
OOP  and  C++  have  been  begging  for 
literary  treatments  this  good,  and  I’m 
happy  to  see  it  finally  happening. 

The  ANSI  Corner:  Preprocessing  and 
Strings 

The  ANSI  standard  C  specification  has 
introduced  something  the  committee 
calls  “stringizing,”  not  a  real  word,  an 
abomination  actually,  but  a  new  con¬ 
cept  in  preprocessing,  nonetheless.  (If 
K&R  can  give  us  “initializer,”  also  not 
a  word,  I  guess  X3J11  similarly  pre- 


885 


C  PROGRAMMING 


(continued  from  page  148) 

sumed  that  they  could  extend  English 

while  they  extended  C.) 

The  trouble  with  the  ANSI  document 
is  that  it  often  fails  to  provide  any  basis 
for  a  particular  extension  to  classic  C. 
In  too  many  cases  the  committee  leaves 
it  to  us  to  figure  out  why  they  included 
a  particular  feature.  They  will  describe 
the  feature  and  perhaps  provide  exam¬ 
ples  of  how  a  conforming  compiler 
must  behave,  but  they  do  not  adequately 
provide  the  motive  behind  it  all.  The 
rationale  document  that  accompanies 
the  specification  is  supposed  to  fill  these 
information  gaps  but  too  often  it  does 
not  or  tries  and  fails.  Such  is  the  case 
with  the  preprocessor’s  #  operator  on 
#define  macro  parameter  substitutions, 
the  so-called  “stringizing”  feature.  They 
tried  to  explain  it,  but  I  do  not  under¬ 
stand  the  explanation.  If  you  do  not 
already  know  how  you  might  use  the 
#  feature,  you  might  not  be  able  to 
guess  its  purpose  from  the  description 
in  the  specification  even  when  you 
know  what  it  does.  What  we  can  do  is 
look  at  what  it  does  and  see  if  this 
solution  solves  some  problem  we  might 
have.  The  #  operator  turns  a  parameter 
into  a  string.  That’s  all  it  does.  Here  is 
an  example: 

#define  str(x)  #  x 

printf(stKHELLO)); 

This  macro  expands  the  hello  parame¬ 
ter  into  a  string  so  that  the  print/  call 
looks  like  this  after  the  substitution: 

printf(“HELLO”); 

The  preprocessor  performs  any  other 
translations  on  the  parameters  before 
it  builds  the  string  as  shown  here: 

#define  HELLO  goodbye 

#define  str(x)  *  x 

printf(str(HELLO)); 

This  sequence  converts  to  this: 

printf(“goodbye”); 

Why  would  you  want  to  do  any  of  that? 
If  you  know  you  want  HELLO  to  be 
“HELLO”  or  goodbye  to  be  “goodbye,” 
why  not  just  code  it  that  way  in  the  first 
place?  Let’s  try  to  dream  up  a  circum¬ 
stance  where  this  feature  might  have 
some  use.  One  possibility  that  comes 
to  mind  is  in  the  realm  of  debugging. 
You  can  use  the  #  operator  to  create  a 
TRACE  macro  that  traces  selected  ex¬ 
pressions  in  your  program  on  the  con¬ 
sole.  You  can  turn  the  TRACE  on  and 
off  with  a  global  compile-time  variable. 
Here  is  the  macro: 


#ifdef  DEBUGGING 

^define  TRACE(x)(printf(“\n”#  x),(x)) 
#else 

^define  TRACE(x)  (x) 

#endif 

Suppose  your  program  has  an  expres¬ 
sion  that  you  want  to  trace  on  the  con¬ 
sole.  If  this  is  the  expression: 

b  =  strlen  (“12345”); 

To  trace  this  expression,  you  can  re¬ 
code  it  with  the  TRACE  macro  like  this: 

b  =  TRACECstrlen  (“12345”)); 

Now  whenever  the  expression  is  exe¬ 
cuted  with  the  DEBUGGING  global  vari¬ 
able  defined,  the  expression’s  code  is 
displayed  on  the  console,  as  well  as 
being  evaluated  because  the  statement 
is  preprocessed  to  this  sequence: 

b  =  (printf(“\  n”  “strlen  (\  “12345  \”)”), 
(strlen(“  12345”))); 

Notice  that  the  two  components  of 
the  macro  expansion,  the  print f  and 
the  strlen  calls  are  comma  separated. 
This  guarantees  that  the  strlen,  which 
is  the  rightmost  expression,  returns  the 
value  required  when  the  expression  is 
evaluated.  Notice  also  that  the  two  are 
surrounded  by  parentheses.  If  they  were 
not,  we  would  get  the  wrong  value  in 
the  “b”  integer  because  the  assignment 
operator  has  a  higher  precedence  than 
the  comma  operator. 

Next  month  the  ANSI  Corner  will 
explore  the  ##  token  pasting  operator. 
We  will,  that  is,  if  I  can  figure  out  a 
useful  application  for  token  pasting. 

Availability 

All  source  code  is  available  on  a  single 
disk  and  online.  To  order  the  disk, 
send  $14.95  (Calif,  residents  add  sales 
tax)  to  Dr.  Dobb’s Journal ,  501  Galves¬ 
ton  Dr.,  Redwood  City,  CA  94063,  or 
call  800  -356  -2002  (from  inside  Calif.) 
or  800  -533-  4372  (from  outside  Calif.). 
Please  specify  the  issue  number  and 
format  (MS-DOS,  Macintosh,  Kaypro). 
Source  code  is  also  available  online 
through  the  DDJ  Forum  on  Compu¬ 
Serve  (type  GO  DDJ).  The  DDJ  Listing 
Service  (603-882-1599)  supports  300/ 
1200/2400  baud,  8-data  bits,  no  parity, 
1-stop  bit.  Press  SPACEBAR  when  the 
system  answers,  type:  listings  (lower¬ 
case)  at  the  log-in  prompt. 

DDJ 

(Listings  begin  on  page  164.) 

Vote  for  your  favorite  feature/article. 

Circle  Reader  Service  No.  10. 
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OOPs,  I  Stepped  in 
Something  GUI . . . 


The  scene:  At  an  animal  research 
laboratory,  a  beaming  researcher 
directs  reporters’  attention  to  a 
window  in  a  room-sized  box  on 
the  floor  before  them.  Inside  the  box, 
a  bored-looking  gorilla  sits  on  the  floor 
and  picks  fleas  from  his  tummy. 

“We’ve  created  this  experiment  to 
measure  the  cleverness  of  gorillas,”  says 
the  researcher.  “We’ve  carefully  de¬ 
signed  this  cage  so  that  there  are  only 
three  ways  to  get  out.  We’re  monitor¬ 
ing  the  cage  continuously  to  see  how 
quickly  Grunion  hits  upon  a  way  to  get 
out,  and  which  one  he  chooses.” 

Inside  the  cage,  Grunion  just  sits 
there,  scratching. 

“He  seems  to  be  in  no  hurry  to  get 
started,”  observes  one  of  the  reporters. 

“Gorillas  can  be  stubborn,”  rejoins 
the  researcher.  “He’ll  get  down  to  busi¬ 
ness  shortly.” 

But  as  minutes  pass,  Grunion  shows 
absolutely  no  interest  in  finding  his  way 
out  of  the  box.  The  reporters  begin  to 
yawn.  The  researcher  grows  restive. 

“Hmmm.  He  may  not  be  feeling  well 
today.  I’d  better  go  in  and  take  a  look 
at  him.”  The  researcher  unlocks  the 
door  in  the  side  of  the  box  and  goes  in. 

Grunion  immediately  perks  up,  grabs 
the  researcher,  and  throws  him  at  the 
wall  so  hard  that  the  entire  side  of  the 
box  collapses  outward.  Grunion  then 
lopes  out  of  the  box  and  gives  the 
reporters  the  High  Five. 

Moral:  There  is  always  another  way 
out  of  the  box.  Plus:  Even  if  you  built 
the  box,  you  may  not  know  the  best 
way  out.  And  finally:  Never  be  too  sure 
you  ’re  smarter  than  the  gorilla. 


Jeff  Duntemann,  KI6RA 


Forklift  Toolkit 

Way  back  in  1985,  when  I  was  a  foot 
soldier  at  PC  Tech  Journal,  each  of  us 
on  the  editorial  staff  was  given  an  early 
copy  of  Microsoft  Windows.  I  loved  it. 
It  was  wonderful,  the  realization  of 


Xerox’s  inaccessible  PARC  research  for 
the  common  man.  Naturally,  I  immedi¬ 
ately  wanted  to  write  applications  that 
used  it.  So  I  called  Microsoft  and  asked 
for  whatever  it  took  to  generate  a  Win¬ 
dows  app,  affectionately  known  as  a 
“winapp.” 

A  couple  of  days  later,  the  Federal 
Express  man  rolled  this  thing  in  on  a 
forklift  and  I  was  on  my  own. 

Sheesh! 

The  Microsoft  Windows  Software  De¬ 
velopers’  Toolkit  (SDK)  is  a  massive 
collection  of  facts  and  diverse  utilities 
poured  into  a  box  with  little  thought  to 
organization  or  documentation  clarity. 
It  is  the  second  most  daunting  devel¬ 
opers’  tool  I  have  ever  confronted;  the 
first  (as  I’ll  return  to  a  little  later)  is  the 
SDK  for  OS/2  Presentation  Manager. 

The  Windows  SDK  makes  it  pretty 
plain  that  you  can  write  a  winapp  in 
one  of  two  languages:  Microsoft  C  or 
MASM.  Being  neither  a  masochist  nor 
suicidal,  I  called  Microsoft  and  com¬ 
plained.  There  were  but  two  (brutally 
difficult)  ways  out  of  the  box,  and  I 
cared  for  neither.  How  about  some  bind¬ 
ings  for  Pascal  or  Modula-2?  And  cripes, 
how  about  coming  up  with  some  rea¬ 
sonable  documentation? 

Their  answer  was  and  is  most  infor¬ 
mative:  The  Windows  SDK  is  intended 
for  use  by  experienced  professional 
developers.  In  other  words,  if  you  have 
the  head  muscle  to  design  a  major  ap¬ 
plication  that  can  compete  on  the  open 
market,  you’ve  got  the  head  muscle  it 
takes  to  untangle  the  unholy  mess  wait¬ 
ing  inside  the  SDK  box.  Programmers 
in  kiddie  languages  need  not  apply. 
Ah,  well.  It  was  a  fond  dream  .  ,  .  and 
like  Grunion,  I  sat  back  in  my  cage  and 
waited  for  someone  to  provide  another 
way  out  of  the  box. 

The  Nature  of  the  Box 

I  was  a  while  waiting.  In  the  meantime, 
Microsoft  was  moaning  about  how  no¬ 
body  was  jumping  on  the  Windows’ 
bandwagon.  Nobody  was  using  it  — 
perhaps  not  remarkably  because  there 


were  no  applications  of  consequence 
for  it.  This  may  have  seemed  incom¬ 
prehensible  to  Microsoft,  but  it  was 
pretty  plain  to  me:  Most  professional 
developers  were  looking  at  the  cost/ 
benefit  equations  presented  by  the  Win¬ 
dows  SDK  and  deciding  that  the  costs 
outweighed  the  benefits  by  about  fifty 
to  one. 

So  I  waited.  While  I  was  waiting,  I 
thought  a  lot  about  how  Windows  de¬ 
velopment  could  be  done  more  easily. 
Consider  the  nature  of  the  box:  There 
are  about  520  different  API  calls  for 
Microsoft  Windows  2.0.  This  is  cool; 
Windows  is  a  capable  and  complex 
gadget  that  does  a  lot  of  interesting  and 
difficult  things.  Furthermore,  Windows 
is  an  event-driven  system.  At  unpre¬ 
dictable  times,  the  Windows  machin¬ 
ery  alerts  your  winapp  that  significant 
things  have  occurred:  Mouse  clicks,  win¬ 
dow  overlaps,  things  like  that.  The  win¬ 
dows  comprising  your  application  must 
then  react  to  those  events  somehow. 

The  main  problem  with  the  Win¬ 
dows  SDK  is  that  it  makes  little  or  no 
effort  to  organize  its  API  calls  and  other 
information  in  hierarchical  fashion.  It 
hides  nothing,  in  keeping  with  the  C 
philosophy  of  giving  the  programmer 
control  over  everything.  However,  the 
C  folks  never  seem  to  catch  on  to  the 
fact  that  invisible  does  not  mean  inac¬ 
cessible.  The  essence  of  structured  pro¬ 
gramming,  according  to  old  Nick  Wirth, 
is  the  artful  hiding  of  details:  Hide  the 
stuff  you  don’t  need  so  that  it  doesn’t 
overwhelm  your  perception  and  un¬ 
derstanding  of  the  stuff  you  do  need! 

Most  of  the  stuff  in  the  SDK  can  be 
kept  hidden  and  out  of  the  way  about 
90  percent  of  the  time.  (Instead,  it  hangs 
in  your  face  like  cobwebs  and  makes 
the  whole  process  look  murky  and  in¬ 
comprehensible.)  My  suggestion  has 
always  been  that  a  carefully-crafted  bind¬ 
ings  library  could  provide  a  header  file 
full  of  useful  defaults  that  don’t  need 
to  be  tweaked  until  necessity  arises. 
Very  high-level  procedures  in  the  li¬ 
brary  would  allow  creation  of  windows 
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and  dialog  boxes  with  one  call  rather 
than  twenty.  A  winapp  should  need  to 
be  no  larger  than  this: 

PROGRAM  Yo; 

USES  WinLib; 

BEGIN 

InitWinApp; 

OpenWindow(WindowHandle, 
10, 10, 40, 5, ’Window  Title’); 

WriteToW  indow(WindowHandle , 
’Yo,  World!’); 

WaitUntilWindowClose(Window- 

Handle); 

END. 

As  part  of  the  functioning  of  InitWin¬ 
App,  the  init  code  would  fill  all  the 
necessary  descriptor  records  with  us¬ 
able  default  values.  The  programmer 
could  override  those  default  values  any 
time  that  the  default  values  just  wouldn’t 
serve.  Alas,  there  is  no  Pascal  library 
like  this,  so  don’t  call  me  up  at  three 
ayem  asking  me  where  to  buy  it. 

The  Way  Out 

Microsoft  wasn’t  listening  back  then, 
and  as  best  I  know  they’re  not  listening 
today.  While  waiting  for  someone  to 
implement  my  obvious  way  out  of  the 
box,  a  small  company  near  Chicago 
came  from  nowhere  and  provided  yet 
another  way  out,  a  way  that  was  years 
ahead  of  its  time  and  flew  right  past 
nearly  everybody  in  the  industry  in  1986: 
objects.  The  company  is  The  Whitewa¬ 
ter  Group,  and  the  product  is  Actor.  If 
you  have  a  hankering  to  do  Windows, 
let  me  be  pretty  blunt  about  it:  Actor  is 
the  only  way  to  develop  applications 
for  Microsoft  Windows  that  is  worth 
the  trouble  it  takes.  Period. 

Actor  is  a  wholly  synthetic  language 
developed  by  Whitewater  cofounder 
Charles  Duff,  who  earlier  implemented 
the  idiosyncratic  Macintosh  language 
called  Neon.  Actor  is  not  an  extension 
of  any  earlier  language,  though  it  con¬ 
tains  elements  of  many.  If  you’re  famil¬ 
iar  with  either  C  or  Pascal  it  won’t  seem 
totally  alien,  and  if  you’ve  learned  Small¬ 
talk  as  well,  it’ll  seem  downright  tradi¬ 
tional  by  comparison. 

Actor  manages  the  complexity  of  the 
Windows  API  by  modeling  the  elements 
of  the  Windows  GUI  (graphics  user 
interface)  in  object  form.  The  Window 
class  models  windows.  The  ScrollBar 
class  models  the  scroll  bar  control  that 
may  optionally  be  added  to  a  window. 
Creating  an  instance  of  a  Window  class 
hides  the  complexity  of  window  crea¬ 
tion  behind  a  single  easy-to-grasp  meta¬ 
phor:  The  Window  c lass  acts  as  a  “win¬ 
dow  factory”  and  whacks  out  a  win¬ 
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dow  object  for  you  to  use.  Very  visual, 
very  intuitive.  All  the  ugly  little  details 
of  setting  up  a  window  are  hidden 
behind  that  object  metaphor. 

Actually,  the  Window  class  is  never 
really  instantiated,  because  a  vanilla- 
flavored  window  isn’t  good  for  much. 
Window  is  a  formal  class  in  Actor,  which 
is  the  equivalent  of  the  abstract  class 
or  abstract  object  type  in  Quick  and 
Turbo  Pascal.  Child  classes  of  the  Win¬ 
dow  class  add  additional  code  to  spe¬ 
cialize  the  generic  window:  TextWin- 
dow  can  display  (though  not  edit)  or¬ 
dinary  text.  EditWindow  is  a  child  class 
of  TextWindow  that  can  edit  as  well  as 
display  text,  and  so  on. 

Every  important  service  Windows  of¬ 
fers  is  modeled  somewhere  in  the  Ac¬ 
tor  class  hierarchy.  The  hierarchy  man¬ 
ages  the  Windows  API  complexity  in 
two  dimensions:  First,  Actor  distributes 
the  specification  of  Windows  function¬ 
ality  up  and  down  the  class  hierarchy 
by  degree  of  specificity.  The  most  gen¬ 
eral  concepts  (windows,  controls,  and 
so  on)  float  to  the  top  and  the  most 
specific  concepts  (file  window,  button, 
polygon,  and  so  on)  move  to  the  bot¬ 
tom.  Second,  Actor  hides  the  implemen¬ 
tation  of  Windows  functionality  (that 
is,  the  gritty  details  of  calling  the  API 
and  handling  events)  behind  the  grasp- 
able  masks  of  the  individual  classes. 

This  dual-mode  management  of  com¬ 
plexity  (idea  complexity  and  implemen¬ 
tation  complexity,  both  at  once)  is  per¬ 
haps  the  greatest  gift  object-oriented 
techniques  offer  the  programmer.  Ac¬ 
tor  uses  it  to  the  fullest,  both  to  manage 
the  complexity  of  the  Windows  API 
and  also  Actor’s  own  very  rich  class 
library. 

The  Importance  of  a  Class  Library 

The  notion  of  a  rich  class  library  is 
extremely  important,  and  I  haven’t  re¬ 
ally  taken  it  up  so  far  in  my  discussion 
of  OOP  concepts.  If  you’ve  seen  White¬ 
water’s  excellent  ad  describing  how  to 
write  a  text  editor  in  two  code  state¬ 
ments,  you'll  begin  to  get  a  feeling  for 
the  complexity-hiding  leverage  Actor 
affords.  It  really  is  that  easy  to  create  a 
text  editor  in  Actor: 

MyEditor  :=  New(EditWindow, 
ThePort,  “editmenu  ’  ’ , 

“Editor”, nil); 

Show(MyEditor,  1); 

In  the  first  statement  the  object  MyEdi- 
tor is  instantiated  from  the  EditWindow 
class,  by  sending  the  New  message 
to  the  class.  In  the  second  statement, 
the  new  window  object  MyEditor  is 
made  visible  by  sending  it  the  Show 
message.  (I’ll  get  back  to  this  notion 
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of  message  passing  again  shortly.) 

This  is  not  just  a  matter  of  making 
Windows  API  calls.  Actor  actually  comes 
with  a  fully  functional  text  editor  object 
in  its  class  library.  This  is  the  rough 
equivalent  of  something  such  as  the 
Turbo  Pascal  Editor  Toolbox  with  all 
the  loose  ends  tied  up  and  tucked  in. 
Nothing  ties  up  loose  ends  such  as 
encapsulation.  The  cleanness  of  inter¬ 
facing  to  an  object  that  may  represent 
tens  of  thousands  of  lines  of  code  is 
one  reason  Actor  can  offer  things  like 
a  text  editor  class,  and  is  a  major  reason 
earlier  languages  had  a  tough  time  with 
toolbox  products. 

Actor  offers  lots  of  additional  library 
classes,  some  with  considerable  power 
and  many  with  no  analog  in  the  purely 
structured  world.  Under  the  formal  class 
Collections  (which  is  Actor’s  name  for 
what  we  would  simply  call  data  struc¬ 
tures)  are  a  number  of  interesting  crit¬ 
ters.  One  is  Bag ,  which  metaphorically 
is  just  what  its  name  implies:  A  con¬ 
tainer  in  which  you  can  toss  any  objects 
you  like.  The  class  keeps  track  of  what’s 
in  the  bag,  and  how  many  are  there. 

Bag  bears  some  relation  to  Pascal’s 
set  type.  Sets  in  Pascal  only  deal  in 
values,  not  variables,  however;  and  a 
value  is  either  in  a  set  or  not  in  the 
set  —  Bag  can  tell  you  how  many  ob¬ 


jects  of  a  given  class  are  present. 

The  TextCollection  class  resembles 
the  melding  of  a  Pascal  text  file  held 
completely  in  memory  with  a  simple 
line-oriented  editor  such  as  EDLIN. 
TextCollection  data  is  some  number  of 
string  values,  and  the  class  has  a  suite 
of  methods  for  inserting,  deleting,  and 
replacing  lines.  Actor  uses  TextCollec¬ 
tion  as  the  mechanism  for  communi¬ 
cating  with  the  Windows  clipboard  re¬ 
source.  Text  from  a  TextCollection  may 
be  written  to  or  read  from  the  clip¬ 
board  through  methods  defined  for  the 
purpose.  You  might  think  of  TextCollec¬ 
tion  objects  as  sheets  torn  off  the  Win¬ 
dows  clipboard  —  a  handy  metaphor 
for  what  is  a  very  handy  thing  to  have 
in  a  library. 

Another  important  collection  class 
is  the  Stream  class,  which  resembles 
an  array  of  objects,  where  the  objects 
can  be  of  any  class  at  all.  Streams  can 
be  handy  for  things  like  lexical  analysis 
when  held  entirely  in  memory,  but  are 
probably  most  useful  for  writing  ob¬ 
jects  to  disk  files.  Turbo  Pascal  5.5  has 
a  similar  Stream  type,  as  does  C++. 

It’s  possible  (if  not  easy)  to  provide 
libraries  of  routines  defining  text  edi¬ 
tors,  windows,  and  buttons  for  ordi¬ 
nary  structured  languages.  It  takes  the 
power  of  late  binding  and  polymor¬ 


phism,  however,  to  implement  things 
such  as  bags  and  streams  in  which  the 
elements  of  the  data  structure  can  be 
any  type  at  all. 

This  is  one  of  the  numerous  reasons 
that  rich  runtime  libraries  really  come 
into  their  own  in  an  object  setting.  Not 
only  does  encapsulation  make  libraries 
clean  and  easy  to  understand  and  use, 
but  polymorphism  allows  a  richness 
of  data  expression  that  older  purely 
structured  languages  simply  cannot 
match.  Just  try  to  code  up  a  bag  in 
preobject  C  or  Pascal.  Generic  pointers 
might  give  you  a  fighting  chance,  but 
the  resulting  Hackenstein’s  monster 
would  be  an  ugly  thing  indeed. 

Polymorphism  via  Messages 

By  now,  a  good  many  people  have 
sampled  OOP  concepts  in  the  forms 
of  Quick  Pascal  and  Turbo  Pascal.  Peo¬ 
ple  evaluating  Actor  will  more  and  more 
be  doing  so  not  from  a  platform  of  total 
ignorance  but  simply  from  different 
OOP  implementations.  Actor  has  all 
the  object-oriented  features  that  C++ 
and  Object  Pascal  have,  but  as  with 
Smalltalk  (as  I  described  a  few  col¬ 
umns  ago)  the  jargon  can  be  confusingly 
different. 

Polymorphism  is  a  case  in  point. 

In  C++  and  Turbo  Pascal  5  5,  poly- 
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morphism  is  an  option  rather  than  a 
way  of  life.  Your  methods  can  be  vir¬ 
tual  (meaning  that  they  support  poly¬ 
morphism)  if  you  choose,  but  they  de¬ 
fault  to  being  early-bound  (static),  just 
as  ordinary  procedure  calls  are.  (Quick 
Pascal,  on  the  other  hand,  makes  all 
methods  virtual,  period.) 

In  Actor  and  Smalltalk,  everything  is 
an  object  and  all  method  calls  are  late 
bound.  Both  languages  use  the  same 
jargon  in  describing  polymorphic 
method  calls:  Instead  of  calling  a  method 
directly  (which  would  imply  early  bind¬ 
ing)  you  call  an  object’s  method  by 
sending  that  object  a  message  indicat¬ 
ing  which  method  you  wish  to  call. 
The  object  then  uses  the  message  to 
select  which  method  code  is  actually 
invoked. 

If  you  learned  polymorphism  in  a 
Pascal  or  C++  context,  this  probably 
sounds  pretty  weird.  The  mechanism 
is  called  message  passing,  and  it  de¬ 
serves  a  little  elaboration. 

Think  of  it  this  (rather  literal)  way: 
Imagine  that  you,  as  a  farmer,  find  a 
note  in  your  mailbox  one  morning  from 
the  county  agent.  The  note  simply  says: 

KILLER  FROST  TONIGHT.  HARVEST 
YOUR  CROPS  NOW! 

Up  and  down  the  county  roads,  other 
farmers  find  the  same  message  in  the 
mailbox.  What  does  each  one  do? 

It  depends  on  the  nature  of  the  crops 
each  farmer  grows. 

If  you’re  a  cucumber  farmer,  you 
crank  up  your  cucumber-picking  ma¬ 
chine  and  head  off  down  the  rows  in 
your  fields.  If  you  own  a  cherry  or¬ 
chard,  you  haul  out  the  tall  ladders, 
call  out  the  kids  and  your  hired  hands, 
and  start  in  on  the  trees.  The  act  of 
picking  cucumbers  is  nothing  like  the 
act  of  picking  cherries,  but  both  ac¬ 
tions  amount  to  a  reasonable  response 
to  the  directive  HARVEST  YOUR  CROPS. 

The  “many  shapes”  of  crop  harvest¬ 
ing  are  a  form  of  polymorphism.  The 
county  agent  simply  tells  the  farmers 
in  his  district  what  to  do  —  not  how  to 
do  it.  The  farmers  each  know  how  to 
harvest  their  own  crops.  And  they  do 
it,  each  in  an  appropriate  way. 

Back  in  Actor,  consider  a  collection 
(a  bag,  say)  of  various  objects.  (Keep 
in  mind  that  everything  in  Actor  is  an 
object,  right  down  to  characters,  strings, 
and  numeric  digits.)  You  want  to  print 
out  the  value  of  every  object  in  the 
bag.  The  way  to  do  this  is  to  send  the 
Print  message  to  every  object  in  the 
bag.  Each  object  then  reacts  to  the  Print 
message  by  selecting  the  correct  Print 
method  to  invoke.  A  string  object  will 
print  using  one  method,  but  a  numeric 


value  object  will  need  to  use  a  different 
method  —  one  that  first  converts  the 
numeric  value  to  a  string  and  then  dis¬ 
plays  the  string  to  the  screen. 

If  you  think  about  it,  this  is  really  no 
different  than  the  situation  in  Object 
Pascal.  Remember,  that  when  virtual 
methods  are  inherited  down  an  object 
hierarchy,  the  name  of  the  virtual 
method  is  always  the  same,  even  when 
the  implementation  of  the  method  is 
different.  In  a  sense,  when  you  make 
a  virtual  method  call  you  pass  the  name 
of  the  method  to  the  object  in  question, 
which  then  looks  the  name  up  in  a 
table  to  determine  which  implementa¬ 
tion  of  that  named  method  to  invoke. 
The  name  of  the  virtual  method  is  thus 
a  message:  PRINT  YOURSELF.  The  re¬ 
ceiver  of  the  message  must  decide  what 
code  will  in  fact  do  the  job  and  satisfy 
the  directive. 

So  beneath  it  all,  message-passing 
and  virtual  method  calls  are  function¬ 
ally  the  same  thing.  Don’t  let  the  jargon 
get  you  down! 

Familiar  Bones 

Although,  Actor  uses  some  of  the  same 
jargon  as  Smalltalk,  it’s  an  easier  lan¬ 
guage  to  learn  because  the  bones  of 
language  are  implemented  in  more  fa¬ 
miliar  form.  Passing  a  message  to  an 
object  looks  a  heckuva  lot  like  a  Pascal 
procedure  call: 

MyStack  :=  New(OrderedCollection,64); 
Add(MyStack,17); 

Add(MyStack,42); 

Here,  we  create  an  instance  of  the  Or- 
deredCollection  class  (think  of  it  as  an 
array  with  a  built-in  stack  pointer)  and 
call  it  MyStack.  Notice  that  the  assign¬ 
ment  operator  and  syntax  is  identical  to 
Pascal’s.  Two  Add  messages  amount  to 
pushing  two  values  onto  MyStack.  You 
could  implement  a  stack  type  in  Pascal 
and  create  an  Add  procedure  that  would 
have  the  same  sort  of  interface. 

In  a  fashion  similar  (if  not  identical) 
to  C,  an  Actor  method  is  defined  by 
creating  a  header  and  then  enclosing 
some  number  of  statements  between 
curly  brackets: 

Def  MyMethod(self,Foo,Bar) 


DoSomething; 

DoSomethingElse; 

AndSoOn; 

) 

Actor’s  control  structures,  while  using 
slightly  different  syntax,  incorporate 
most  of  the  familiar  Pascal  keywords 
and  are  easy  to  recognize  and  under¬ 


stand.  Conditional  statements  are  pretty 
plain: 

if  (i  <  10) 

then  DoSomething; 

else  DoSomethingElse; 

endif; 

The  looping  construct  can  be  set  up  in 
a  number  of  different  ways,  but  it  reads 
well  in  any  configuration.  This  one  is 
set  up  as  a  while/do  loop: 

loop 

while  x  <  42 

X  :=  X  +  1; 

print(x); 

endloop; 

Actor’s  designers  have  taken  consider¬ 
able  pains  to  keep  “weirdness”  out  of 
the  language;  the  only  weirdness  is  the 
inescapable  weirdness  of  object-ori¬ 
ented  thinking,  which  like  kudzu  is 
destined  over  time  to  replace  whatever 
else  is  out  there. 

Actor  on  the  Scales 

Given  the  enormity  of  the  things  it  does 
(such  as  taming  the  Windows  API)  I 
found  Actor  almost  ridiculously  easy  to 
learn.  The  trick,  again,  is  not  in  the 
language  but  in  the  paradigm.  Once 
you  learn  to  think  object-ively,  you 
shouldn’t  have  any  more  trouble  than 
I  had. 

The  documentation  is  solid,  if  not 
exhaustive.  The  single  fat  (700  page) 
volume  hasn’t  failed  to  provide  me  what 
I’ve  needed  to  know  so  far,  which  is 
my  early  measure  of  language  docu¬ 
mentation.  I  haven’t  yet  tried  to  do 
anything  really  tricky,  such  as  using  the 
early-binding  option  or  create  a  stand¬ 
alone  application,  but  I  hope  to  report 
on  both  in  future  columns,  and  we’ll 
see  how  well  the  doc  stands  up  in  a 
pinch. 

On  the  low  end,  the  manual  is  a 
so-so  introduction  to  OOP  thinking.  I’ll 
forgive  them  that,  and  in  fact  I  prefer 
that  they’d  give  the  language  its  due  in 
the  manual  and  let  us  joinalists  anoint 
the  great  unwashed  in  object-oriented 
First  Principles.  If  you’ve  already  made 
the  conceptual  breakthrough  to  objects, 
on  the  other  hand,  you’ll  have  no  prob¬ 
lem  at  all  picking  up  Actor  itself. 

There  is  also  the  book  by  Marty  Franz, 
Object-Oriented  Programming  with  Ac¬ 
tor,  that  takes  a  slower,  more  gentle 
path  to  OOP.  Marty  has  a  clean,  plain 
style  and  goes  into  the  mindset  of  Ac¬ 
tor  programming  in  a  way  that  the  man¬ 
ual  itself  doesn’t  have  room  for.  If  you’re 
going  to  go  the  $500  to  acquire  Actor, 
it’s  well  worth  shelling  out  another  $25 
for  the  book. 
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(continued  from  page  156) 

Which  brings  us  to  the  question  of 
Actor’s  success  in  the  marketplace.  Pretty 
obviously,  Actor  has  hitched  its  wagon 
to  Windows,  and  won’t  do  any  better 
than  Windows  does.  Windows,  how¬ 
ever,  is  alluvasudden  on  a  roll,  fueled 
largely  by  the  availability  of  $2000-386 
machines  that  make  Windows  not  only 
fast  enough  but  almost  sprightly.  The 
Windows  installed  base  has  probably 
achieved  a  sort  of  critical  mass,  with 
even  Borland  announcing  that  they  will 
pursue  Windows  development  in  their 
languages. 

The  way  I  see  it,  Actor  has  only  one 
serious  impediment  to  its  success:  Its 
$500  price  tag.  Compared  to  the  Win¬ 
dows  SDK  it’s  cheap  enough,  but  an 
impulse  buy  it  is  not.  If  a  Tiny  Actor 
(Child  Actor?)  were  available  for  the 
canonical  $99,  there’d  be  no  stopping 
it.  Microsoft  has  done  well  with  its  Big 
C/Little  C  approach.  Whitewater  should 
pay  heed.  Actor  is  the  way  to  break  out 
of  the  Windows  software  development 
box,  but  for  Grunion  the  Gorilla  to 
knock  out  a  wall  with  it,  Actor  first  has 
to  get  in  the  door  somehow. 

OS/2,  Mon  Dieu! 

And  then  there  is  Presentation  Man¬ 
ager.  PM  is  to  OS/2  as  Windows  is  to 
DOS:  The  anointed  user  interface  and 
graphics  toolkit.  Like  Windows,  it  has 
an  SDK,  which  is  larger,  richer,  and 
perhaps  even  a  little  better  organized. 
Unfortunately,  because  PM  does  lots 
more  than  Windows,  the  end  result  is 
the  same:  You  could  spend  years  get¬ 
ting  good  enough  at  the  SDK  to  write 
a  competitive  product  with  it.  (Not  to 
mention  the  endless  irritation  of  hav¬ 
ing  to  write  in  C.) 

Ever  since  PM  was  announced,  I’ve 
been  thinking,  “Somebody  should  do 
an  Actor  for  it.”  The  whole  nature  of 
PM,  like  that  of  Windows,  cries  out  for 
an  object-oriented  development  lan¬ 
guage.  Both  of  the  current  books  I’ve 
obtained  on  Presentation  Manager  pro¬ 
gramming  describe  PM  internals  in  ob¬ 
ject-oriented  terms,  even  though  the 
example  code  is  in  plain  old-fashioned 
C.  If  you  intend  to  work  in  PM  I’d 
suggest  you  get  them  both:  Alan  South- 
erton’s  Programmer’s  Guide  to  Presen¬ 
tation  Manager  is  nicely  done,  if  a  little 
thin  on  figures  and  example  code  for 
my  tastes.  Even  so,  it  runs  to  750  pages  — 
there  is  a  lot  to  cover. 

The  book  to  have,  though,  is  the  one 
bundled  in  the  Microsoft  PM  SDK:  Pro¬ 
gramming  the  OS/2  Presentation  Man¬ 
ager  by  Charles  Petzold.  (Details  on 
both  books  are  given  at  the  end  of  the 
column  —  but  remember  not  to  buy 
Petzold’s  book  if  you’re  also  going  to 

158 


buy  the  SDK!)  Lord  knows  what  Micro¬ 
soft  would  have  done  without  a  writer 
like  Charles  Petzold  to  make  sense  of 
it  all.  In  850  pages  he  makes  PM  devel¬ 
opment  about  as  rational  as  it’s  ever 
going  to  be.  Lots  of  code,  lots  of  fig¬ 
ures,  and  beautifully  written.  To  get  a 
handle  on  PM  internals,  start  here. 

Presenting  Smalltalk 

I’ve  encouraged  Whitewater  to  do  an 
Actor  for  it,  and  they  well  might  —  or 
let  us  hope.  In  the  meantime,  however, 
Digitalk  has  gone  and  done  the  re¬ 
markable,  which  is  to  produce  a  Small¬ 
talk  for  PM  —  one  that  adheres  totally 
to  the  PM  user  interface  spec. 

This  is  remarkable  because  Small¬ 
talk,  the  language,  was  defined  with  its 
own  user  interface,  and  up  until  now 
Digitalk  has  been  relatively  faithful  to 
that  interface,  perhaps  for  fear  of  being 
accused  of  “tinkering  with  the  stan¬ 
dard.”  Their  latest  move  is  the  right 
one.  Smalltalk  has  its  own  user  inter¬ 
face  spec  because  when  it  was  de¬ 
signed  (mid-seventies)  Batch  was  King, 
and  user  interfaces  didn’t  exist.  For  the 
same  reason  that  UCSD  Pascal  was  de¬ 
signed  with  its  own  operating  system, 
Smalltalk-80  had  its  own  user  interface. 
But  operating  systems  have  become 
standardized  with  user  interfaces  right 
behind. 

I’ve  had  very  little  time  to  experi¬ 
ment  with  Smalltalk/V  PM,  mostly  be¬ 
cause  getting  OS/2  to  run  on  a  Frank- 
enclone  is  ticklish  business.  (The  prod¬ 
uct  itself,  even  in  its  unfinished  state, 
is  pretty  robust.)  At  this  writing  the 
product  is  still  in  beta  test  form.  I’ll 
have  a  lot  more  to  say  about  it  when  I 
receive  the  shrinkwrapped  product. 

For  now,  here  are  some  of  the  im¬ 
portant  points: 

•  Where  Smalltalk’s  original  spec  and 
PM  conflict,  PM  wins.  For  example, 
Smalltalk’s  original  Bitblt  class  and  its 
children  have  been  replaced  by  the 
new  GraphicsTool  class  and  its  chil¬ 
dren,  which  correspond  more  closely 
to  PM’s  vector-oriented  graphics. 

•  PM’s  coordinate  system  places  the 
default  origin  (0,0)  in  the  lower-left 
corner  of  a  window’s  client  area.  Small¬ 
talk  uses  the  upper-left  corner  for  the 
origin,  and  some  rewriting  of  existing 
Smalltalk  code  to  “flop”  the  grid  is  al¬ 
most  assured. 

•  The  Digitalk  interactive  environment 
now  generates  stand-alone  .EXE  files 
that  execute  without  the  presence  of 
any  runtime  system.  This  means  sim¬ 
pler  logistics  for  distributing  applica¬ 
tions  written  in  Smalltalk/V  PM.  Un¬ 
doubtedly,  there  is  some  internal  inter¬ 
pretation  going  on  (Smalltalk  is  at  heart 


an  interpreter)  but  the  sealed-off  appli¬ 
cation  is  as  independent  as  a  C  module 
and  all  the  apps  I’ve  seen  have  run 
unapologetically  fast. 

Yes,  it’s  a  dialect,  but  so  was  Turbo 
Pascal  —  which  has  weathered  the  rain 
of  brickbats  from  sourpuss  academi¬ 
cians.  Digitalk  has  done  the  right  thing, 
both  from  a  Smalltalk  perspective  and 
a  Presentation  Manager  perspective.  C 
is  not  an  appropriate  language  for  use 
in  developing  for  a  GUI.  (C++  is,  of 
course,  but  that’s  another  person’s  col¬ 
umn.)  Smalltalk,  as  it  was,  seemed 
chained  to  the  late  seventies,  trapped 
in  a  set  of  assumptions  that  simply 
don’t  apply  to  our  modern  machines 
and  operating  environments.  In  a  fu¬ 
ture  column  I’ll  use  Smalltalk/V  PM  to 
show  you  just  how  utterly  simple  it  can 
be  to  develop  for  Presentation  Man¬ 
ager.  Thanks,  Digitalk,  for  a  bold  step. 

And  welcome  to  the  real  world,  Small¬ 
talk. 

DDJ 

Vote  for  your  favorite  feature/article. 

Circle  Reader  Service  No.  11. 
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Actor  V  1.2 

The  Whitewater  Group 
906  University  Place 
Evanston,  IL  60201 
312-491-2370 
$495.00 

Object-Oriented  Programming 
with  Actor 
by  Marty  Franz 

Scott,  Foresman  &  Company,  1989 

ISBN  0-673-38641-  4 

$24.95 

Programmer’s  Guide  to 
Presentation  Manager 
by  Alan  Southerton 
Addison-Wesley,  1989 
ISBN  0  -201-19440-6 
$26.95 

Programming  the  OS/2 
Presentation  Manager 
by  Charles  Petzold 
Microsoft  Press,  1989 
ISBN  1-55615-170-5 
$29.95 

(Bundled  with  Microsoft’s  OS/2 
PM  Software  Developer’s  Toolkit) 

Smalltalk/V  PM 
Digitalk  Inc. 

9841  Airport  Blvd. 

Los  Angeles,  CA  90045 

213-645-1082 

$499.95 
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Listing  One  (Text  begins  on  page  144.) 

int  tok; 

tok  =  gettoken (expr) ; 

/* - textsrch.h - */ 

switch  (tok)  ( 

case  OPEN: 

♦define  MXTOKS  25  /*  maximum  number  of  tokens  */ 

if  (expression (expr)  ==  ERROR) 
return  ERROR; 

♦define  OK  0 

if  ((tok  =  gettoken (expr) )  !=  CLOSE) 

♦define  ERROR  !0K 

return  ERROR; 
break; 

struct  postfix  ( 

case  NOT: 

char  pfix;  /*  tokens  in  postfix  notation  */ 

if  (expression (expr)  ==  ERROR) 

char  ‘pfixop;  /*  operand  strings  */ 

return  ERROR; 

case  OPERAND: 

extern  struct  postfix  pftokens[]; 

break; 

extern  int  xp  offset; 

default : 

return  ERROR; 

/*  -  expression  token  values  -  * / 

} 

♦define  TERM  0 

tok  =  gettoken (expr) ; 

♦define  OPERAND  '0' 

switch  (tok)  ( 

♦define  AND 

case  TERM: 

♦define  OR  ' 

return  OK; 

♦define  OPEN  ' (' 

case  AND: 

♦define  CLOSE  ')' 

case  OR: 

♦define  NOT  '  ! ' 

return  expression (expr) ; 

♦define  QUOTE 

case  CLOSE: 

— token  ptr; 

/*  - textsrch  prototypes - */ 

— xpoffset; 

struct  postfix  ‘lexical  scan (char  *expr) ; 

return  OK; 

default: 

break; 

) 

End  Listing  One 

} 

/* -  extract  the  next  token  from  the  expression - */ 

static  int  gettoken (char  *expr) 

Listing  Two 

( 

char  tok; 

/*  - express. c - */ 

operands [token_ptr]  =  0; 

if  ((tok  =  getword (expr) ) =«  OPERAND)  ( 

operands [token  ptr]  =  malloc (strlen (word)  +1); 

♦include  <string.h> 

strcpy (operands [token_ptr] ,  word) ; 

♦include  <ctyDe.h> 

) 

tokens [token_ptr++]  =  tok; 
return  tok; 

♦include  "textsrch.h" 

*  Parse  a  search  expression  into  a  valid  postfix  token  stream. 

/*  _  -  extract  a  word,  operator,  parenthesis, 

*  The  input  expression  has  this  form: 

*  <expr>  <ident> 

or  terminator  from  the  expression - */ 

*  <ident>  <op>  <expr> 

static  int  getword (char  *expr) 

*  NOT  <expr> 

int  w  =  0; 

*  (<expr>) 

*  <op>  :=  AND 

*  OR 

/* - bypass  white  space - */ 

*  <ident>  :=  <character> 

while  (iswhite (expr [xp  offset] ) ) 

xp  offset++; 

*  "<phrase>" 

switch  (expr [xp_off set] )  ( 

*  <phrase>  :=  <ident> 

case  OPEN: 

*  <ident>  <space>  <phrase> 

*/ 

case  CLOSE: 

return  expr [xp_of f set++]  ; 
case  TERM: 

♦define  iswhite(c)  (c  <  33  SS  c  >  0) 

return  TERM; 

♦define  isparen(c)  (c  ==  OPEN  : :  c  ==  CLOSE) 

case  QUOTE: 

♦define  isop(c)  (c  ==  AND  : :  c  ==  OR) 

while  (expr[++xp  offset]  !=  QUOTE)  ( 

♦define  ischaracter (c)  (!isparen(c)  &&  \ 

if  (w  ==  50) 

return  ERROR; 

c  ! =  TERM  &&  \ 

word(w++]  =  tolower (expr [xp  offset]); 

!iswhite(c)  &&  \ 

) 

c  ! =  QUOTE) 

xp_of fset++; 
word[w]  =  '\0'; 

/*  -  prototypes  -  -  */ 

return  OPERAND; 

static  int  getword(char  *expr) ; 

default: 

static  int  gettoken (char  *expr) ; 

while  (ischaracter (expr [xp  offset]))  { 

static  int  expression  (char  *expr) ; 

if  (w  ==  50) 

static  void  postfix (void) ; 

return  ERROR; 

static  int  isp(int  tok) ; 

word[w++]  =  tolower (expr [xp  offset]); 

static  int  icp(int  tok); 

xp  offset++; 

static  void  poststack (void) ; 

I 

word[w]  =  ' \0' ; 

int  xp  offset  =  0;  /*  offset  into  the  expression  */ 

if  (strcmp (word,  "and")  ==  0) 

static  char  word[50);  /*  word  from  the  expression  */ 

return  AND; 

else  if  (strcmp (word,  "or")  ==  0) 

static  char  tokens [MXTOXS+1] ;  /*  tokens  in  infix  notation  */ 

return  OR; 

static  char  ‘operands [MXTOKS] ;  /*  operand  strings  */ 

else  if  (strcmp (word,  "not")  ==  0) 

static  int  token  ptr  =  0; 

return  NOT; 

return  OPERAND; 

static  char  stack (MXTOKS] ;  /*  stack  for  tokens  »/ 

> 

static  char  ‘stopr [MXTOKS] ;  /*  operand  strings  */ 

I 

static  int  top  =  0; 

/*  -  convert  the  expression  from  infix  to  postfix  notation  -  */ 

struct  postfix  pftokens [MXTOKS] ; 

static  void  postfix (void) 

static  int  pf  =  0; 

( 

char  tok  =  ' *' ; 

/*  -  analyze  the  expression  for  valid  syntax  - */ 

struct  postfix  ‘lexical  scan (char  *expr) 

top  =  token  ptr  =  pf  =  0; 

f 

stack [top]  =  ' *' ; 

token  ptr  =  xp  offset  =  0; 

while  (tok  ! =  TERM)  ( 

if  (expression (expr)  ==  ERROR) 

switch  (tok  =  tokens[token  ptr])  ( 

return  NULL; 

case  OPERAND: 

else  if  (gettoken (expr)  !=  TERM) 

pftokens [pf] .pfix  =  tok; 

return  NULL; 

pftokens [pf] .pfixop  =  operands [token  ptr]; 

postfix () ; 

pf++; 

return  pftokens; 

break; 

1 

case  NOT: 
case  OPEN: 

/*  - analyze  an  element  of  the  expression -  */ 

case  AND: 

static  int  expression (char  *expr) 

case  OR: 

{ 

(continued  on  page  167) 
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while  (isp (stack [top] )  >=  icp(tok)) 
poststack () ; 
stack [++top]  =  tok; 
break; 
case  CLOSE: 

while  (stack [top]  !=  OPEN) 
poststack () ; 

— top; 
break; 
case  TERM: 

while  (top) 

poststack () ; 

pftokens [pf++] .pf ix  =  tok; 
break; 

} 

token  ptr++; 

) 

) 

static  int  isp(int  tok) 

{ 

return  ( (tok  ==  OPEN)  ?  0  : 

(tok  «  '*')  ?  -1  : 

(tok  ==  NOT)  ?  2  : 


static  int  icp(int  tok) 

{ 

return  ( (tok  ==  OPEN)  ? 

(tok  —  NOT)  ? 


} 


4  : 

2  : 
l  ); 


Listing  Three 


- testexpr.c - */ 

A  program  to  test  the  TEXTSRCH  expression  analyzer 


♦include  <stdio.h> 
♦include  <process.h> 
♦include  <string.h> 
♦include  "textsrch.h" 


static  void  disp_token (struct  postfix  *pf); 

void  main (void) 

( 

char  expr[80]; 
do  { 

/* - read  the  expression  from  the  console - */ 

printf ("\nEnter  the  search  expression : \n") ; 
gets (expr) ; 
if  (*expr)  { 

/*  —  scan  for  errors  and  convert  to  postfix  —  */ 
if  (lexical_scan(expr)  ==  NULL)  [ 
while (xp_offset — ) 
putchar ('  '); 
putchar (' A' ) ; 
printf ("\nSyntax  Error"); 
exit  (1) ; 

} 


/*  —  remove  a  token  from  the  stack,  put  it  into  postfix  —  */ 
static  void  poststack (void) 

{ 

pftokens [pf] .pfix  *  stack [top]; 
pftokens [pfj .pfixop  =  stopr(top); 

— top; 
pf++; 

) 


/* - display  the  postfix  tokens - */ 

printf ("\nToken") ; 

printf  ( "\n - ")  ; 

disp_token (pftokens) ; 
printf  ("\n - ")  ; 

) 

}  while  (*expr); 

] 


static  void  disp_token (struct  postfix  *pf) 

[ 


if  (pfopfix  !-  TERM)  ( 
disp_token (pf +1 ) ; 

printf ("\n  %s",  pf->pfix  -=  AND  ? 

pf->pfix  ==  OR  ? 

pf->pf ix  ==  NOT  ? 

pf->pfixop) ; 


"<and>" 

"<or>" 

"<not>" 


End  Listing  Two 


End  Listings 


Dr.  Dobb’s  Journal,  December  1989 


167 

893 
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Apple  Computer  announced  the 
Macintosh  Programmer’s  Work¬ 
shop  (MPW)  C++  at  OOPSLA  ’89.  MPW 
C++  fully  supports  the  AT&T  2.0  speci¬ 
fication  including  multiple  inheritance, 
operator  overloading,  and  protected 
members.  Support  of  the  Macintosh  Tool¬ 
box  and  the  operating  system  as  well 
as  Object  Pascal-based  methods  found 
in  MacApp  are  also  provided.  MPW 
C++  includes  the  MPW  C++  translator, 
C++  interfaces,  and  libraries  for  com¬ 
plex  math  and  stream  processing,  an 
unmangler  for  CFront  messages,  and  a 
collection  of  example  programs.  In  ad¬ 
dition,  Apple’s  Symbolic  Application 
Debugging  Environment  (SADE)  can 
be  used  to  debug  programs  at  the  C++ 
source  level.  A  beta  version  of  MPW 
C++  (v  3.1B1  at  the  time  of  this  writing) 
is  available  through  the  Apple  Program¬ 
mers  and  Developers  Association 
(APDA)  for  $175.  MPW  C++  also  re¬ 
quires  MPW  C,  Version  3  0,  or  higher 
and  the  Macintosh  System  Software  6.0.2 
or  later.  Reader  service  no.  20. 

Apple  Computer 
20525  Mariani  Avenue 
Cupertino,  CA  95014 
Apple  Programmers  and  Developers 
Association  (APDA) 

800-282-2732 

408-562-3910 

ObjectVision  Inc.  of  Berkeley  Calif, 
has  just  released  its  visual  object-ori¬ 
ented  programming  environment  of  the 
same  name.  ObjectVision  allows  the 
programmer  to  both  organize  object 
hierarchies  and  design  objects  visually 
on  the  screen.  Once  an  object  is  cre¬ 
ated,  the  programmer  can  implement 
its  methods  through  a  pop-up  editor 
by  using  an  English-like  syntax.  Once 
the  design  is  completed,  ObjectVision 
generates  either  C++  or  Turbo  Pascal 
5.5  source  code.  A  “hide”  function  encap¬ 
sulates  the  details  of  a  newly  designed 
object,  keeping  the  screen  free  of  clut¬ 
ter.  In  addition,  a  built-in  browser  al¬ 
lows  the  designer  to  easily  traverse  the 
object  hierarchy.  ObjectVision  also  pro¬ 
vides  a  pixel  editor  for  the  creation  of 
icons,  the  ability  to  import  dBase  data 
into  specialized  database  objects,  built- 
in  drawing  functions,  and  a  rather  slick 
UI  that  includes  mouse  support.  Sup¬ 
port  for  multiple  inheritance  is  not  in¬ 


cluded  in  the  current  version,  although 
such  support  is  being  considered  for 
future  versions.  System  requirements 
for  ObjectVision  are  minimal  —  IBM  PC 
or  compatible  with  at  least  256K,  either 
a  VGA  or  EGA  and  a  mouse.  Ob¬ 
jectVision  sells  for  $399.  A  demo  disk 
is  also  available  at  $30.  Reader  service 
no.  21. 

ObjectVision,  Inc. 

2124  Kittredge  Street,  Ste.  118 
Berkeley,  CA  94704 
415-540-4889 

To  follow-up  on  last  month’s  “Of  Inter¬ 
est,”  Digitalk  was  demonstrating  the 
recently  announced  Smalltalk/V  PM  at 
OOPSLA  ’89-  Smalltalk  /  V  PM  is  an 
object-oriented  development  environ¬ 
ment  for  Presentation  Manager  under 
OS/2  and  allows  developers  to  take 
advantage  of  PM’s  capabilities  while 
hiding  its  complexities.  The  product  is 
positioned  as  a  prototyping  tool  for 
Ul-intensive  applications,  even  though 
it  is  the  first  fully  compiled  Smalltalk 
under  OS/2. 

Developers  can  pass  data  to  and  from 
PM  tools,  as  well  as  applications, 
through  Dynamic  Link  Libraries  (DLLs) 
and  Dynamic  Data  Exchange  (DDE). 
Digitalk  also  provides  tools  to  organize 
and  browse  source  code  including  PM 
code.  A  source-level  debugger  provides 
most  of  the  features  you’d  expect  in¬ 
cluding  breakpoints,  single-stepping, 
and  an  object  inspector.  The  object 
inspector  additionally  allows  the  pro¬ 
grammer  to  change  instance  variables 
during  the  debugging  session. 

Smalltalk  /  V  PM  comes  complete 
with  150+  classes  and  is  source  code 
compatible  with  Smalltalk/V  286  and 
Smalltalk  /  V  Mac.  The  package  requires 
OS/2  Presentation  Manager  1.1  or  later 
and  is  priced  at  $499-95.  Reader  service 
no.  22. 

Digitalk,  Inc. 

9841  Airport  Blvd. 

Los  Angeles,  CA  90045 

213-645-1082 

800-922-8255 

Stepstone’s  new  release  of  their  Ob- 
jective-C  compiler  marks  the  fourth  gen¬ 
eration  of  the  product,  which  runs  un¬ 
der  DOS.  Stepstone  also  offers  versions 
under  other  platforms  including  OS/2, 
Sun  3,  4,  and  Sun  386i  under  SunOS, 
and  the  Apollo  workstation. 

Objective-C  more  closely  follows  the 
message  sending  paradigm  found  in 
pure  object-oriented  languages  such  as 
Smalltalk  than  does  C++.  The  strength 
of  Objective-C  lies  in  its  strong  type 
checking.  The  compiler  extends  ANSI 
C  features  such  as  function  prototyp¬ 
ing  with  method  prototyping  and  type 


mismatch  detection  for  objects.  Debug¬ 
ging  tools  include  a  message  trace  fa¬ 
cility  that  allows  the  programmer  to 
view  the  message’s  receiver,  the  name 
of  the  message,  arguments  to  the  mes¬ 
sage,  and  the  sender  of  the  message. 
Another  tool,  back  tracing,  allows  the 
programmer  to  back  trace  through  the 
current  stack  after  an  exception  has 
occurred.  Also  available  from  Stepstone 
is  an  object-oriented  user  interface 
toolkit,  ICpak201,  for  workstations  run¬ 
ning  under  X-Windows.  The  toolkit  pro¬ 
vides  58  classes  with  over  1100  meth¬ 
ods  to  support  pop-ups,  scroll  bars, 
dialog  boxes,  and  the  like.  Other  classes 
support  the  UI  by  managing  the  envi¬ 
ronment,  providing  controllers,  fixtures, 
and  other  abstract  classes.  A  set  of  con¬ 
tainer  classes  is  also  included.  Reader 
service  no.  23. 

Stepstone  Corporation 
75  Glen  Road 
Sandy  Hook,  CT  06482 
203-426-1875 

A  new  book  from  MIS  Press,  Object- 
Oriented  Environment  in  C++,  by  David 
Hu,  presents  concepts  and  code  to  cre¬ 
ate  graphical  environments  such  as 
those  found  in  Smalltalk  or  MacApp 
using  C++.  Hu  covers  Zortech,  Guide¬ 
lines,  and  Advantage  C++  (from  Life¬ 
boat)  as  well  as  Stepstone’s  Objective- 
C  and  Smalltalk/V  from  Digitalk.  The 
strengths  and  weaknesses  of  the  vari¬ 
ous  languages  are  compared  so  that 
the  reader  can  make  informed  deci¬ 
sions  as  to  which  tool  is  best  suited  to 
a  given  project. 

Hu  also  shows  how  to  create  win¬ 
dows,  bit-mapped  icons  and  menus, 
and  how  to  support  the  mouse  using 
Zortech’s  C++.  In  addition,  he  presents 
schemes  for  knowledge  representation, 
and  shows  how  to  create  an  expert 
system  including  methods  for  defining 
forward-and  backward-chaining  infer¬ 
ence  engines.  In  a  final  chapter,  the 
author  presents  object-oriented  data¬ 
base  concepts  and  provides  insights 
into  the  Gemstone  Database  system 
from  Servio  Logic.  The  book  is  priced 
at  29. 9 5,  or  with  a  source  code  disk  at 
$59. 95.  Reader  service  no.  24. 
Management  Information  Source,  Inc. 
P.O.  Box  5277 
Portland,  OR  97208 
503-282-5215 

Quintus  Computer  Systems  and 
Logic  Programming  Associates  have 
teamed  up  to  announce  MacObject,  a 
graphical  package  to  generate  object 
hierarchies  in  Prolog++.  Prolog++  is 
an  extended  version  of  Quintus’s 
MacProIog  that  supports  meta-objects, 
(continued  on  page  1 73) 
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super-  and  sub-objects  (both  static  and 
dynamic).  Prolog++  also  supports 
daemons,  inheritance,  message  pass¬ 
ing,  broadcasting,  methods,  and  func¬ 
tions.  In  conjunction  with  MacObject 
is  the  announcement  of  version  3-0  of 
the  MacProlog  compiler.  MacProlog  pro¬ 
vides  a  complete  development  envi¬ 
ronment  that  includes  incremental  com¬ 
pilation,  multiple  scrolling  windows, 
hierarchical  menus,  and  pop-ups,  com¬ 
piled  graphics  windows  and  pictures, 
a  program  optimization,  access  to  Quick¬ 
Draw,  and  interfaces  to  C  and  Pascal 
code.  MacProlog  3.0  sells  for  $595.  Mac- 
Object,  which  includes  the  Prolog++ 
compiler,  is  priced  at  $495.  Reader  ser¬ 
vice  no.  25. 

Logic  Programming  Associates  Ltd. 
Studio  4,  RVPB,  Trinity  Road 
London,  SW18  3SX 
441-871-2016 

Quintus  Computer  Systems 
1310  Villa  Street 
Mountain  View,  CA  94041 
415-965-7700 

Franz  Inc.  recently  announced  Alle¬ 
gro  CLiP;  a  Common  Lisp  designed  for 
parallel  environments.  Allegro  CLiP, 
which  is  modeled  after  SPUR  Lisp,  pro¬ 
vides  a  set  of  low-level,  parallel-pro¬ 
gramming  primitives,  while  providing 
high-level  constructs  from  MultiLisp  and 
QLisp.  Access  to  the  Sequent  Parallel 
Programming  Library  is  also  provided 
through  a  set  of  interface  functions. 

Allegro  CLiP  provides  a  complete  inte¬ 
grated  development  environment  that 
features  debugging  facilities,  an  instru¬ 
mentation  style  interface,  and  the  mul¬ 
tiple  entry-levels  mentioned  above. 
Reader  service  no.  26. 

Franz,  Inc. 

1995  University  Avenue 
Berkeley,  CA  94704 
415-548-8253 

Addison-Wesiey  has  published  The 
Renderman  Companion ,  A  Program¬ 
mer’s  Guide  to  Realistic  Computer  Graph¬ 
ics  by  Steve  Upstill  of  Pixar  (Steve  wrote 
the  article  “Photorealism  in  Computer 
Graphics,”  Z/D/November  1988,  on  the 
Renderman  Shading  Language).  The 
book  is  a  tutorial  based  on  Pixar’s  Ren¬ 
derman  Interface  for  3-D  scene  descrip¬ 
tion,  which  can  produce  computer  graph¬ 
ics  that  are  indistinguishable  from  ac¬ 
tual  photographs.  Steve  said  he  wrote 
The  Renderman  Companion  “to  demon¬ 
strate  that  any  programmer  with  some 
3-D  computer  graphics  experience  can 
produce  stunning  pictures  with  the  use 
of  our  Renderman  Interface.” 

Some  of  the  topics  covered  in  the 
book  are  quadric  surfaces,  polygons, 


parametric  surfaces,  hierarchical  mod¬ 
eling,  the  digital  camera,  lighting  and 
shading,  surface  mapping,  and  the  Ren¬ 
derman  Shading  Language.  The  paper¬ 
back  sells  for  $26.95,  ISBN  0-201-50868- 
0.  Reader  service  no.  27. 
Addison-Wesiey  Publishing  Company 
Reading,  MA  01867 
617-944-3700 

Blaise  Computing  Inc.  has  announced 
C  TOOLS  PLUS/6.0,  the  latest  version 
of  Blaise’s  library  products  for  Micro¬ 
soft  C.  This  library  of  compiled  C  func¬ 
tions  supposedly  gives  programmers 
advanced  routines  for  developing  high- 
powered  C  applications,  and  includes 
virtual,  stackable  menus  and  windows 
with  full  mouse  support  and  optional 
“drop  shadows."  It  also  has  multiple 
virtual  pop-up  help  screens;  a  mini¬ 
ature  multiline  editor  for  gathering  user 
responses;  a  single  function  call  that 
can  move,  resize,  and  promote  a  win¬ 
dow  or  menu  on  top  of  all  others;  the 
ability  to  update  covered  windows  auto¬ 
matically  when  they  are  written  to;  sup¬ 
port  for  EGA,  VGA.  and  MCGA  text 
modes  including  30-,  43-,  and  50-line 
modes;  and  support  for  the  enhanced 
(101/102  key)  keyboard. 

The  library  comes  with  adaptable 
source  code  for  study  or  emulation. 
Blaise  claims  that  their  attention  to  de¬ 
tail,  like  the  use  of  function  prototyp¬ 
ing  and  the  const  modifier,  the  pre¬ 
built  libraries  for  the  four  standard  mem¬ 
ory  models,  the  organized  header  files, 
and  an  indexed  manual  makes  C  TOOLS 
PLUS/6.0  appropriate  for  both  experi¬ 
enced  software  developers  and  new¬ 
comers  to  C. 

The  library  also  supports  mouse  de¬ 
tection,  cursor  control,  and  button 
presses  and  releases,  with  mouse  sup¬ 
port  integrated  into  the  windows  and 
menus.  Functions  written  in  C  can  be 
installed  to  be  called  whenever  certain 
classes  of  mouse  events  occur;  even 
DOS  functions  can  be  accessed  in  re¬ 
sponse  to  mouse  events. 

Fully  documented  source  code  is  in¬ 
cluded  with  the  product,  and  the  man¬ 
ual  gives  a  general  overview  for  every 
function  category  and  descriptions  of 
each  function.  C  TOOLS  PLUS/6.0  can 
be  used  for  product  development  with¬ 
out  obligation  to  Blaise  Computing.  It 
requires  the  Microsoft  C  5  0  or  later  or 
QuickC,  DOS  2.0  or  later,  and  an  IBM 
or  compatible.  The  mouse  functions 
require  a  Microsoft-compatible  mouse 
and  its  driver  software.  The  product 
sells  for  $149.  Reader  service  no.  29. 
Blaise  Computing 
2560  Ninth  Street,  Suite  316 
Berkeley,  CA  94710 
415-540-5441 


Zortech  Inc.  recently  announced  ver¬ 
sion  2.0  of  its  C++  compiler  for  MS- 
DOS.  C++  V2.0  Developer’s  Edition  is 
fully  compatible  with  the  AT&T  2.0  speci¬ 
fication,  which  includes  support  for  mul¬ 
tiple  inheritance.  Other  features  include 
type  safe  linkage  and  built-in  support 
for  EMS.  Version  2.0  also  has  been 
enhanced  for  portability  to  other  C  en¬ 
vironments  including  Microsoft  C. 

In  addition,  the  Developer’s  Edition 
includes  a  C++  source  level  debugger, 
the  source  code  to  its  run-time  library, 
and  Version  2.0  of  Zortech’s  C++  tools. 
Each  of  these  components  may  be  pur¬ 
chased  separately  as  well.  The  overall 
system  features  compatibility  with  Mi¬ 
crosoft  Windows,  a  set  of  graphics 
classes,  and  a  TSR  library  that  can  make 
many  applications  resident  through  a 
simple  function  call. 

According  to  Scott  Ladd,  official  beta 
tester,  “its  virtually  100  percent  com¬ 
patible  with  AT&T  2.0,  also  supports 
Windows  programming  in  OS/2  as  well 
as  MS-DOS  —  an  impressive  product.” 

Zortech  has  also  announced  the  re¬ 
lease  of  its  OS/2  compiler  upgrade, 
priced  at  $149-  The  Zortech  C++  Devel¬ 
oper’s  Edition  sells  for  $450,  or  the 
compiler  can  be  purchased  separately 
for  $199.  Other  components  of  the  De¬ 
veloper’s  Edition  may  also  be  purchased 
separately,  including  the  new  debug¬ 
ger,  the  run-time  library  source  code, 
and  Version  2.0  of  C++  Tools  at  $149 
each.  Updates  to  existing  users  start  at 
$40.  Reader  service  no.  30. 

Zortech,  Inc. 

1 165  Massachusetts  Avenue 
Arlington,  MA  02174 
617-646-6703 
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S  W  A  I  N  E'  $  FLAMES 


It  Takes  More  Than  A  Winning  Smile 

Paradigm:  That  collection  of  model  problems,  techniques,  and  specialized  knowledge  that 
makes  a  specialist  generally  worthless. 

I  am  a  writer  of  prose,  and  when  I  venture  outside  the  paradigm,  I  do  so  at  peril.  Your  peril, 
usually,  but  I  did  warn  you.  I’d  like  to  talk  about  marketing:  The  marketing  of  software  innovation 
and  the  subversion  of  marketing  by  software  innovation. 

First,  Get  a  Million  Dollars 

How  does  a  capable  programmer  with  a  good  product  idea  become  a  successful  entrepreneur  with 
a  hot  product?  The  standard  truism,  that  you’ve  got  to  have  money  to  make  money,  is  no  help  and 
is  disproved  by  the  PC  software  industry  as  a  whole.  It  had  nothing  but  ideas  a  decade  ago,  and 
now  it’s  a  billion-dollar  industry.  Obviously,  there’s  a  cold  start  technique.  What  is  it?  I’ve  sniffed 
at  the  roots  of  the  major  personal  computer  software  companies  without  unearthing  any  rare  truffles 
of  wisdom.  Maybe  you've  got  to  know  about  business  to  learn  about  business.  But  here  are  two 
homely  “morels”  I  did  dig  up: 

There  appear  to  be  two  normal  sources  of  development  funding  for  those  without  private 
fortunes  or  rich  friends:  Your  current  clients  (or  employer)  and  your  future  customers.  You  can  sell 
part  of  your  enterprise,  once  you  have  one,  to  investors  or  venture  capitalists,  but  in  the  initial 
phase,  you  don’t  have  anything  to  sell  but  what’s  in  your  head.  Venture  capitalists  don’t  want  that, 
and  any  private  investors  willing  to  take  a  chance  on  you  are  probably  rich  friends,  clients,  or 
employers. 

In  the  client-funded  paradigm,  you  develop  the  components  or  early  prototypes  of  your  product 
on  contract  to  companies  with  big  budgets,  taking  care  to  retain  all  important  rights  to  your  work. 
(In  the  risky  employer-funded  variation,  you  do  product  development  on  the  job  and  hope  you  can 
take  it  away  with  you  without  losing  the  product  or  your  self  respect  or  a  lawsuit.  It’s  been  known 
to  work.)  Client-funded  development  is  probably  the  only  way  to  make  money  in  the  stackware 
market  today.  And  it’s  the  paradigm  followed  by  Microsoft,  which  got  its  start  in  Bill  Gates’s  tireless 
refining  of  Microsoft  Basic  under  contract  to  MITS,  Tandy,  and  others. 

The  most  gutsy  way  to  get  funding  is  from  future  customers.  This  is  how  the  personal  computer 
hardware  industry  was  launched:  Gullible  electronic  hobbyists  sent  checks  to  post  office  boxes, 
and  when  there  were  enough  checks,  the  products  got  built.  Legally,  this  technique  gives  you  only 
a  three-month  window,  but  a  three-month  interest-free  loan  is  nothing  to  sneeze  at.  Many  software 
companies  followed  this  mail  order  paradigm,  some  with  more  scrupulous  honesty  than  suggested 
by  this  scenario,  some  with  less.  The  most  successful  company  to  start  out  by  mail  orders  is  Borland 
International,  which  made  the  transition  to  shelf  space  competitor  with  remarkable  adroitness. 

Agents  are  Subversive 

One  of  the  promises  of  object-oriented  programming  is  that  you  will  be  able  to  build  software  from 
reusable  components:  Brad  Cox  calls  this  “the  software  IC  model.”  But  when  it  comes  to  finding 
the  components,  the  software  IC  model  doesn’t  fit.  Supplier  catalogs  are  too  narrow  a  channel. 
They  work  for  real  ICs,  because  manufacturing  costs  already  narrow  the  channel  drastically,  but 
will  be  a  problem  for  software  components,  for  which  there  are  likely  to  be  as  many  suppliers  as 
customers.  Some  OOP  supporters  see  agents  as  the  answer. 

An  agent  is  a  program  that  searches  for  information  based  on  criteria  you  supply.  An  agent  might 
scan  electronic  news  services  to  put  together  a  custom  newspaper  for  you  —  reflecting  your 
interests.  Or  it  might  find  reusable  software  components.  The  search  space  could  be  a  single 
software  library  or  all  the  sources  for  which  you  have  e-mail  addresses.  Where  the  product  sought 
is  information,  agents  could  be  essential  in  getting  the  product  into  the  hands  of  the  person  who 
needs  it.  And  they  could  subvert  the  economy  wherever  they  are  effectively  used. 

Usually,  it  is  the  vendor  who  takes  responsibility  for  making  the  connection  with  the  customer. 

I  can  think  of  only  two  reasons  why  it  would  be  appropriate  for  the  vendor  to  take  responsibility 
for  making  the  connection:  1.  It  is  easier  for  the  vendor  than  for  the  customer;  or  2.  The  vendor  has 
more  to  gain  from  the  transaction.  For  the  vast  majority  of  goods,  1.  can’t  be  true:  There  are  just  a 
lot  more  customers  than  vendors.  I  think  that  2.  is  usually  the  deciding  factor:  Most  sales  are  driven 
by  the  vendor’s  needs  rather  than  the  customer’s. 

Imagine  a  market  managed  by  customers  and  driven  by  their  needs.  Imagine  a  market  in  which 
there  were  no  marketing  costs  to  the  vendor  because  there  was  no  marketing.  If  you  wanted  a  tool 
to  help  you  do  your  job,  you  would  sketch  a  description  of  its  desired  properties  and  dispatch 
your  agent  to  search  for  one.  If  you  built  a  truly  better  mousetrap,  the  world  really  would  beat  a 
path  to  your  door. 

Could  we  actually  replace  marketing  by  technology  in  this  way?  A  lot  of  people  seem  ready  to 
try  it  in  the  area  of  reusable  software  components.  If  it  works  there,  the  model  might  spread  to  other 
markets.  Of  course,  one  can  think  of  many  products  and  services  for  which  it  obviously  wouldn’t 
work.  And  we  know  that  all  those  products  and  services  serve  real  needs.  Right? 

Michael  Swaine 
editor-at-large 
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GUEST  EDITORI A  L 


The  Mac  and  the  Mega-Micro  Syndrome 


It  is  a  real  pleasure  and  a  distinct  honor  to  have  been  invited  to  write  this  introduction. 
You  see,  if  it  weren’t  for  Dr.  Dobb’s,  there  probably  would  have  been  no  Macintosh. 

In  fact,  there  might  not  be  an  Apple  Computer  Inc.  today.  A  bit  of  history  will  explain 
why  this  is  so. 

In  1976,  Jim  Warren,  founder  and  then  editor  of  Dr.  Dobb’s ,  sent  a  budding,  free-lance 
journalist  and  programmer  to  interview  two  guys  who  had  been  making  a  bit  of  noise  at 
the  legendary  Home-Brew  Computer  Club.  He  gave  me  a  phone  number  and  an  address. 
The  journalist  was  me,  and  the  two  guys  were  both  named  Steve,  though  one  was  always 
referred  to  as  “Woz.”  They  were  working  on  the  Apple  I,  and  I  thought  it  had  some  of  the 
slickest  hardware  ideas  I  had  seen  in  the  two-year-old  personal  computer  industry.  I  still 
have  my  Apple  I,  and  it  still  works. 

I  did  the  interview  and  offered  to  write  the  manuals  for  the  early  Apples.  Soon  my 
newly-formed  company,  Bannister  &  Crun,  and  I  ended  up  writing  a  lot  of  the  early  Apple 
manuals,  and  eventually  my  whole  crew  was  hired  by  Apple  Computer  (in  1978)  as  their 
Publications  Department.  I  was  employee  No.  31  and  I  loved  the  Apple  II,  especially  its 
pre-decoded  bus.  I  own  Apple  II  serial  No.  2  (on  which  I  tested  the  manuals  and  early 
software),  and  it  still  works,  too. 

By  1979  the  company  was  gung  ho  on  two  projects  spearheaded  by  Steve  Jobs,  the 
Apple  III  and  Lisa  computers.  I  was  worried  that  the  Apple  was  not  forward-looking 
enough  and  that  Lisa  was  too  big  and  expensive  for  Apple’s  customer  base.  So  I  created 
a  project  to  make  a  small,  relatively  inexpensive,  small-footprint  machine  inspired  by  the 
screen  architecture  and  some  of  the  interface  elements  I  had  come  to  love  at  Xerox  PARC 
(at  which  I  was  a  regular  visitor  in  the  early  ’70s).  I  named  the  project  after  my  favorite 
apple,  the  McIntosh,  and  changed  the  spelling  to  avoid  (so  I  hoped)  conflict  with  the  hi-fi 
manufacturer  of  that  name. 

Thus  Dr.  Dobb 's  certainly  deserves  the  credit  for  making  a  connection  that  led  to  the 
creation  of  the  Macintosh.  And  if  Apple  didn’t  have  the  Mac,  would  it  be  in  business  today? 
Nobody  can  say  for  sure. 

Enough  History 

As  the  following  articles  prove,  the  Macintosh  has  become  a  complex,  intimidating 
monster,  requiring  the  same  kind  of  convoluted  understanding  as  did'the  mainframes  of 
a  decade  or  two  ago.  We  have  reached  the  age  of  the  megamicro.  Since  “mega”  stands  for 
106  and  “micro”  stands  for  10<_6)  this  term  equals  1 .  In  other  words,  we  have  canceled  one 
of  the  advantages  that  originally  sparked  the  growth  of  microcomputers:  Simplicity.  We 
are  back  to  where  we  started.  The  other  major  advantage,  namely  low  price,  has  also 
eroded,  but  not  to  nearly  the  same  extent,  although  the  magazines  once  devoted  to 
“personal”  computers  no  longer  blush  at  prices  easily  exceeding  $10,000  for  a  single-user 
system. 

On  the  other  hand,  we  are  exploring  new  ways  to  use  computers,  The  Xerox/Apple 
interface,  and  the  growing  understanding  of  object-oriented  programming  (OOP)  all  lead 
to  at  least  an  external  simplicity  from  the  user’s  point  of  view.  We  must  learn  to  match  it 
with  internal  simplicity  as  well.  Some  claim  that  our  brave,  new  graphic  world  is  inherently 
complex.  This  is  not  true,  but  if  we  believe  it  to  be  true  we  will  not  be  able  to  do  better. 

In  the  meanwhile,  articles  like  those  in  this  issue  will  act  like  a  guidebook  to  an 
adventure  game,  and  lead  you  ever  deeper  into  the  innards  of  Macintosh  software.  Don 
the  robes  of  a  software  wizard  and  you  will  find  treasure  here. 

/ 

Jef  Raskin 
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PROGRAMMING 
wi  th  COLOR 

QUICKDRAW 

I  Adding  color  and  using 
multiple  monitors 


□  he  large  base  of  software  avail¬ 
able  for  the  Macintosh  makes 
it  imperative  that  any  changes 
to  the  Mac,  no  matter  how 
wonderful,  not  cause  existing  programs 
to  stop  working.  Consequently,  any  im¬ 
provement  to  the  Macintosh,  small  or 
large,  must  be  carefully  designed  to  fit 
within  the  existing  architecture.  This  is 
hard  enough  with  simple  changes,  such 
as  adding  a  single  new  toolbox  call. 
With  more  extensive  changes  like  add¬ 
ing  color,  maintaining  compatibility  can 
be  a  monumental  task. 

The  goal  of  compatibility  is  allowing 
older  software  to  continue  to  function, 
while  the  goal  of  new  features  is  better 
software  in  the  future.  Well-written  ap¬ 
plications  can  benefit  from  both  com¬ 
patibility  and  new  features.  However, 
it  is  not  always  easy  to  create  well- 
written  applications.  This  is  particu¬ 
larly  true  when  approaching  the  prob¬ 
lem  of  color.  With  this  in  mind,  this 
article  explains  how  you  can  write  pro¬ 
grams  that  are  ‘color  smart.” 

Maintaining  Compatibility 

One  of  the  methods  used  to  maintain 
compatibility  is  mimicry:  New  software 
emulates  its  older  counterpart.  Older 
applications  continue  to  work,  because 


Chris  is  a  member  of  the  System  Soft¬ 
ware  group  at  Apple  Computer  and 
can  be  reached  at  20525 Mariani  Ave., 
MS  27-AJ,  Cupertino,  CA  95014. 


Chris  Derossi 

the  data  structures  and  calls  that  they 
use  are  still  supported.  Often  this  sup¬ 
port  is  a  facade,  though,  and  the  calls 
get  translated  into  the  new  way  of  do¬ 
ing  things. 

In  Color  QuickDraw,  the  CopyBits 
call  continues  to  take  the  address  of  a 
port’s  portBits  field  as  a  parameter,  even 
when  that  field  contains  a  PixMap- 
Handle,  and  not  a  BitMap. 

Sometimes  the  support  for  old  calls 
and  data  structures  is  easy  and  natural. 
Other  times,  however,  this  support  re¬ 
quires  hacks  to  an  otherwise  clean  de¬ 
sign.  And  most  times,  the  hacks  would 
not  be  necessary  if  applications  did  not 
make  assumptions  about  the  environ¬ 
ment  in  which  they  were  running. 

Some  assumptions  are  obvious,  and 
can  easily  be  avoided.  Other  assump¬ 
tions,  though,  are  more  subtle.  When 
the  Mac  Plus  was  new,  it  was  clear  by 
then  that  assuming  the  location  of  the 
screen  RAM  was  bad.  The  assumption 
that  each  pixel  on  the  screen  was  rep¬ 
resented  by  a  single  bit  was  less  obvi¬ 
ous.  But  because  multiple  monitors  for 
a  single  personal  computer  were  not 
yet  common,  it  was  natural  to  assume 
the  presence  of  a  single,  rectangular, 
contiguous  display. 

Because  it  is  difficult  to  completely 
predict  future  changes,  some  assump¬ 
tions  will  always  be  made.  Making  new 
software  compatible  generally  means 
supporting  these  unavoidable  assump¬ 
tions. 


Unfortunately,  there  is  an  adverse 
side  effect  to  supporting  such  assump¬ 
tions  with  new  software:  Developers 
continue  to  write  new  programs  that 
make  the  same  assumptions.  Writing 
such  programs  is  tacitly  encouraged, 
because  software  that  assumes  that  it 
is  running  on  the  lowest  common  de¬ 
nominator  of  the  machines  will  always 
run  on  all  of  the  machines.  This  prac¬ 
tice  is  acceptable,  up  to  a  point. 

Programming  for  the  lowest  com¬ 
mon  denominator  becomes  undesir¬ 
able  when  new  software  takes  advan¬ 
tage  of  some  of  the  new  features  and 
yet  still  relies  on  support  for  old 
assumptions.  By  their  nature,  assump¬ 
tions  valid  for  older  environments 
are  usually  limiting  in  the  new  environ¬ 
ment.  Using  such  assumptions  pro¬ 
duces  software  that  is  unnecessarily 
limited. 

One  of  the  more  common  examples 
of  this  problem  is  color  software,  like 
paint  programs,  that  will  not  run  unless 
a  color  monitor  is  the  main  display 
device.  Imagine  the  frustration  such  a 
program  causes  the  Macintosh  owner 
who  has  two  monitors  —  a  large  black- 
and-white  one  as  the  main  screen,  and 
a  color  display  on  the  side. 

The  main  screen  on  a  Macintosh  is 
the  screen  that  is  used  to  emulate  the 
old,  single,  rectangular  display.  Associ¬ 
ated  concepts  are  also  supported  by 
this  main  screen,  such  as  the  Quick¬ 
Draw  global  variable  screenBits,  which 
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is  supposed  to  contain  the  BitMap  that 
defines  the  display.  Except  for  certain 
hacks  put  in  by  Apple,  programs  that 
use  screenBits  find  themselves  restricted 
to  a  single  screen  when  several  might 
be  available. 

Again,  this  limitation  isn’t  so  bad  for 
older  software,  or  software  that  needs 
to  run  the  same  way  on  all  models  of 
the  Macintosh.  But  programs  written  to 
know  about  Color  QuickDraw  could  go 
one  step  further  and  know  about  multi¬ 
ple  display  devices.  And  programs  that 
require  Color  QuickDraw  to  run  have 
no  excuse  for  not  taking  advantage  of 
all  of  Color  QuickDraw’s  features. 

As  a  rule,  programs  that  utilize  the 
newest  routines  and  data  structures  have 
greater  functionality  and  flexibility. 
These  programs  also  have  a  longer  life 
expectancy,  as  older  features  will  not 
be  supported  forever.  They  also  pre¬ 
vent  headaches  for  users  who  don’t 
understand  why  the  menu  bar  has  to 
be  on  a  particular  screen  for  some  pro¬ 
grams  to  work. 

Handling  Multiple  Monitors 

As  you  can  probably  see  by  now,  an 
important  feature  of  a  color-smart  pro¬ 
gram  is  the  ability  to  handle  multiple 
monitors.  The  functionality  required  by 
your  program  may  be  available  on  a 
screen  other  than  the  main  one.  In¬ 
stead  of  checking  just  the  main  screen 
for  a  particular  configuration,  such  as 
pixel  depth,  a  program  should  check 
all  available  screens,  or  better  yet,  let 
the  user  decide  which  screen  to  use. 

If  your  window  is  displayed  on  a 
screen  that  can’t  support  the  program’s 
features,  it  is  better  to  disable  the  use 
of  those  features  than  to  uncondition¬ 
ally  exit  the  program.  The  user  might 
change  the  situation  at  least  two  ways: 
By  dragging  the  window  to  a  different 
monitor,  or  by  changing  the  screen 
attributes  with  the  Control  Panel.  The 
program  should  explain  to  the  user 
why  features  are  disabled,  and  should 
suggest  possible  solutions. 

In  addition  to  your  program’s  envi¬ 
ronmental  needs,  the  use  of  multiple 
monitors  affects  the  question  of  screen 
real  estate.  Historically,  the  size  of  the 
screen  would  dictate  the  limits  for  drag¬ 
ging  and  sizing  windows.  The  com¬ 
mon  practice  was  to  set  these  limits  to 
an  approximation  of  the  screenBits 
.bounds  rectangle. 

Because  the  screenBits  variable  repre¬ 
sents  only  the  main  screen,  the  user  of 
a  program  developed  before  the  ad¬ 
vent  of  the  Macintosh  II  would  have 
been  unable  to  drag  windows  to  other 
monitors.  Fortunately,  Apple  put  in  a 
hack  that  allows  windows  to  be  dragged 
onto  other  displays. 


Changing  the  size  of  a  window  is 
another  matter.  In  most  cases,  a  9-inch 
monitor  was  not  large  enough  to  dis¬ 
play  an  entire  document,  so  limiting 
the  size  of  a  window  to  the  size  of  the 
screen  was  not  a  problem.  With  the 
proliferation  of  large  monitors,  though, 
windows  could  easily  become  larger 
than  their  documents.  This  resulted  in 
garbled  displays  and  sometimes  in 
crashes.  In  other  cases,  programs  bene¬ 
fited  from  having  as  large  a  window 
as  they  could  get. 

The  Palette  Manager 
has  been  extended  to 
support  the  kinds  of 
things  that  developers 
want  to  do 


And  so  the  relationship  between  win¬ 
dow  contents  and  window  size  must 
be  considered  much  more  carefully  than 
that  between  window  contents  and  win¬ 
dow  position.  The  limit  you  set  for  the 
size  of  a  window  should  be  based  solely 
on  the  nature  of  the  document  in  the 
window.  Windows  set  up  this  way  will 
be  able  to  span  multiple  monitors  when 
appropriate.  For  the  user  who  purchases 
a  second  or  larger  screen,  the  benefit 
will  be  automatic. 

High-Level  Calls  and  Data  Structures 

Apple  has  defined  high-level  calls  and 
documented  data  structures  for  deter¬ 
mining  the  characteristics  of  display 
devices.  You  should  take  advantage 
of  these  resources. 

The  linked  list  of  display  devices 
(called  “GDevices”)  can  be  accessed 
and  traversed  with  the  GetDeviceList 
and  GetNextDevice  calls.  You  can  use 
the  call  GetMainDevice  to  find  the  par¬ 
ticular  element  of  this  list  that  repre¬ 
sents  the  main  screen.  Because  each 
GDevice  references  a  PixMap,  you  can 
determine  the  current  color  settings  of 
each  monitor.  Each  GDevice  also  con¬ 
tains  a  rectangle  that  represents  that 
monitor’s  global  position. 

With  this  information,  your  program 
can  locate  the  monitor  which  best  sup¬ 
ports  your  program’s  requirements.  You 
may,  for  example,  wish  to  open  new 
windows  on  the  most  appropriate  moni¬ 
tor.  (An  example  of  this  technique  is 
built  into  the  program  presented  later 
in  this  article.) 


Handling  Special  Cases 

In  addition  to  increased  functionality, 
programs  that  know  about  their  envi¬ 
ronment  can  provide  greater  efficiency 
and  better-looking  output. 

Images  designed  to  look  great  on 
an  8-bit  color  display  don’t  always  come 
out  as  nicely  when  mapped  by  Quick¬ 
Draw  to  a  color  device  of  lower  resolu¬ 
tion,  or  to  a  black-and-white  device. 
And  color  mapping  incurs  an  overhead 
that  can  be  detrimental  to  high-per¬ 
formance  programs.  Frequently,  how¬ 
ever,  you  can  make  the  same  images 
look  just  as  good  at  lower  color  resolu¬ 
tions,  either  by  using  a  different  set  of 
colors,  or  by  using  patterns. 

In  general,  software  will  work  fine 
using  a  pure  color  model,  and  letting 
QuickDraw  do  the  best  rendering  pos¬ 
sible  on  each  device,  but  there  is  an 
alternative  if  you  wish  to  go  that  extra 
mile  for  appearance  and  performance. 
In  addition  to  imaging  for  the  generic 
case,  you  can  deal  with  special  cases. 
Performance  and  output  will  generally 
be  enhanced  for  each  special  case,  al¬ 
though  the  amount  of  improvement  will 
vary,  depending  on  the  application. 

The  best  way  to  apply  this  technique 
is  to  use  a  generic  case  that  extends  to 
the  limits  defined  by  Color  QuickDraw. 
In  other  words,  use  as  many  colors  as 
are  appropriate  for  the  application,  and 
specify  each  color  by  using  the  full  48 
bits  available  in  the  RGBColorAala  struc¬ 
ture.  Then  handle  the  common  special 
cases  of  lower  functionality,  such  as 
8-bit  color,  4-bit  color,  and  black-and- 
white. 

It  is  important  to  deal  with  the  high- 
end  generic  situation.  After  your  pro¬ 
gram  has  been  written,  more  sophisti¬ 
cated  hardware  and  software  are  bound 
to  come  along.  Even  though  it  seemed 
superfluous  to  draw  with  more  than 
256  colors  when  the  Mac  II  first  came 
out,  the  programs  that  did  now  render 
full-color  images  using  Apple’s  32-bit 
QuickDraw. 

In  order  to  deal  with  special  cases, 
your  program  must  know  about  the 
devices  to  which  it  will  be  drawing. 
The  program  can  traverse  the  list  of 
GDevices  and  compare  their  locations 
to  the  global  coordinates  of  your  win¬ 
dow.  Once  the  GDevice  that  contains 
your  window  is  found,  the  GDevice’s 
PixMap  will  let  the  program  decide 
which,  if  any,  special  case  to  use. 

A  given  window  may  intersect  more 
than  one  display,  and  each  display  might 
be  set  to  a  different  configuration.  When 
traversing  the  device  list,  the  program 
should  treat  each  device  window  inter¬ 
section  as  a  separate  case. 

Even  if  a  program  is  running  on  a 
Macintosh  that  has  a  single  monitor, 
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(continued  from  page  10) 
the  user  can  change  the  color  environ¬ 
ment  at  any  time  with  the  Control  Panel. 
Such  changes  may  or  may  not  he  of 
concern  to  your  program.  If  you  use 
the  technique  just  described  for  all  of 
your  drawing,  then  everything  will  work 
automatically,  because  this  technique 
requires  that  you  can  actually  draw 
something  meaningful  on  each  device, 
no  matter  what  its  color  settings.  An 
update  event  will  be  generated  when 
the  color  environment  changes,  which 
will  prompt  the  program  to  execute  its 
GDevice  intersection  and  drawing  loop. 

As  a  rule,  programs  that 
utilize  the  newest 
routines  and  data 
structures  have  greater 
functionality  and 
flexibility 


If  your  program  requires  a  certain 
minimum  color  environment,  you 
should  check  to  see  if  the  color  envi¬ 
ronment  has  changed  whenever  your 
program  gets  an  update  event.  This 
test  is  easy,  because  the  ctSeed  field  in 
the  color  table  of  the  G  Device's  PixMap 
will  change  if  that  GDevice's  color  en¬ 
vironment  changes.  If  the  ctSeed  has 
changed,  you  can  then  check  other 
values,  like  the  pixel  depth,  to  see  if 
you  should  disable  some  features  or 
just  generate  a  new  set  of  colors  to  use. 

Using  the  Palette  Manager 

Your  color  programs  should  always  use 
the  Palette  Manager.  The  days  when 
the  Palette  Manager  created  more  prob¬ 
lems  than  it  solved  ended  with  the 
release  of  System  6.0.2.  Now,  as  part 
of  32-bit  QuickDraw,  the  Palette  Man¬ 
ager  has  even  more  functionality  and 
features  that  you  will  definitely  want 
to  use.  In  response  to  voluminous  feed¬ 
back,  the  Palette  Manager  has  been 
extended  to  support  the  kinds  of  things 
that  developers  want  to  do. 

For  example,  a  single  palette  can 
now  contain  a  different  list  of  colors 
for  each  kind  of  device.  This  is  exactly 
what  is  needed  to  support  the  tech¬ 
nique  described  earlier  for  drawing  the 
right  thing  to  each  GDevice. 


ICKDRAW 


Any  old  work-arounds  that  used  to 
be  required  should  be  discarded.  The 
support  provided  by  the  system  via  the 
Palette  Manager  should  be  used  in¬ 
stead.  Apple  will  continue  to  maintain 
the  Palette  Manager,  but  the  same  can¬ 
not  be  said  about  non-Apple  work¬ 
arounds. 

The  ShowColors  Program 

The  program  ShowColors  demonstrates 
some  of  the  concepts  described  in  this 
article.  Listing  One  (page  57)  gives  the 
MPW  Pascal  version  of  this  program, 
Listing  Two  (page  58)  gives  the  MPW 
C  version,  and  Listing  Three  (page  60) 
lists  the  Rez  input  for  the  application. 

ShowColors  is  a  color-smart  applica¬ 
tion  that  displays  something  meaning¬ 
ful  on  any  CLIJT  (color  lookup  table) 
or  Fixed  device.  It  doesn't  crash  when 
it  encounters  other  types  of  devices. 
The  display  shown  for  each  device  is 
a  representation  of  that  device’s  color 
table.  To  create  the  display,  the  pro¬ 
gram  uses  the  Palette  Manager's pmEx- 
plicite ntry  type. 

In  order  to  show  the  right  thing  on 
each  screen,  the  program  uses  the  de¬ 
vice  window  intersection  loop.  If  the 
area  of  intersection  is  large  enough, 
then  the  color  table  is  drawn;  other¬ 
wise,  that  portion  of  the  window  is  left 
white.  For  displays  that  are  not  CLUT 
or  Fixed-type  devices,  the  window  is 
painted  with  a  50  percent  gray.  When 
the  program  starts,  it  uses  a  simple  algo¬ 
rithm  to  find  what  it  considers  to  be  the 
best  device.  The  window  is  centered 
on  that  screen.  Because  this  program 
has  no  fixed  document  size,  the  win¬ 
dow  can  be  made  as  large  as  desired. 

Conclusion 

1  hope  that  this  article  has  encouraged 
you  to  write  programs  that  take  full 
advantage  of  the  Color  QuickDraw  fea¬ 
tures.  Your  programs  will  live  a  longer 
life,  and  your  users  will  appreciate  the 
added  functionality  and  flexibility. 

Availability 

All  source  code  for  articles  in  this  issue 
is  available  on  a  single  disk.  To  order, 
send  $14.95  (Calif,  residents  add  sales 
tax)  to  Dr.  Dobb 's  Journal,  501  Galves¬ 
ton  Dr.,  Redwood  City,  CA  94063,  or 
call  800-356-2002  (from  inside  Calif.) 
or  800-533-4372  (from  outside  Calif.). 
Please  specify  the  Macintosh  special 
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AVOIDING 

INIT  COLLISIONS 
at  BOOT  TIME 


I  Loading  device  drivers  with  an  INIT 
isn’t  the  only  way,  but  it’s  the  best 

John  Rosford 


□  his  article  describes  a  Macin¬ 
tosh  INIT  that  loads  a  com¬ 
plex  set  of  device  drivers  for 
a  group  of  IEEE-488  interface 
and  data  acquisition  cards.  Even  though 
drivers  vary  widely  in  purpose,  the  code 
that  loads  them  at  boot  time  is  much 
the  same,  so  this  basic  INIT  will  be  able 
to  load  most  driver  configurations.  One 
of  the  main  goals  of  this  INIT  code  is 
to  prevent  collisions  with  drivers  previ¬ 
ously  loaded  by  other  INITs,  so  this 
program  will  be  useful  to  Mac  pro¬ 
grammers  who  have  drivers  in  use,  as 
well  as  those  writing  new  ones. 

The  source  code  for  the  INIT  pro¬ 
gram  consists  of  initOpenDRVR.c  (List¬ 
ing  One,  page  62)  and  initOpenDRVR.h 
(Listing  Two,  page  68).  Source  code  for 
other  resources  can  be  found  in 
DDJInit.r  (Listing  Three,  page  70).  The 
tools  I  used  include  MPW  3  0  (to  com¬ 
pile  and  copy  the  resources  to  the  INIT) 
and  Think  C  3.0. 

Loading  Device  Drivers 

There  are  several  methods  for  making 
a  device  driver  available  to  an  applica¬ 
tion,  the  most  common  being  to  install 
the  driver  into  the  system  file.  Several 
standard  drivers  are  used  by  the  Macin¬ 
tosh  and  are  found  in  the  System  file. 


John  Rosford  is  an  engineer  at  Na¬ 
tional  Instruments  and  can  be  con¬ 
tacted  at  12109  Technology  Blvd.,  Aus¬ 
tin,  TX  78727-6204. 


These  drivers  are  installed  when  you 
upgrade  or  initially  install  the  system 
software  by  running  the  Installer. 

Another  method  is  to  write  an  INIT 
to  load  the  drivers  at  boot  time,  as 
suggested  by  the  “Macintosh  Technical 
Note  #14."  All  INITs  in  the  System  folder 
are  run  at  boot  time  by  the  system 
startup  code.  A  third  option,  rarely  used, 
is  to  make  the  application  load  its  own 
copy  of  the  drivers.  This  last  option 
presents  a  difficult  problem  of  hard¬ 
ware  resource  access  control  when  more 
than  one  application/driver  is  used  un¬ 
der  MultiFinder. 

Device  Drivers,  Expansion  Cards, 
and  the  INIT 

In  this  section,  I’ll  describe  a  set  of 
drivers  and  their  association  to  subdriv¬ 
ers  and  the  expansion  cards  that  they 
drive.  In  doing  so.  I’ll  provide  an  over¬ 
view  of  the  tasks  performed  by  the 
INIT  program. 

Before  an  application  can  use  either 
the  NB-GPIB  or  NB-DMA-8G  expan¬ 
sion  boards,  the  drivers  must  be  initial¬ 
ized.  These  drivers  share  data  because 
the  NB-GPIB  and  other  data  acquisi¬ 
tion  boards  request  DMA  services  from 
the  DMA  driver. 

The  master  driver,  LabDriver,  is 
opened  first  (see  Figure  1  and  Listing 
Three).  It  opens  each  board  driver  for 
the  boards  found  in  the  computer,  and 
points  them  to  the  master  global  stor¬ 
age  area,  which  they  fill  in  with  infor¬ 


mation  about  the  board.  The  board 
driver  .NB-GPI  does  nothing  more  than 
fill  in  information  about  the  NB-GPIB 
board;  the  driver  is  never  called  by 
an  application  and  it  does  not  mani¬ 
pulate  the  hardware.  The  .NB-DMA 
driver  not  only  fills  in  information  about 
the  NB-DMA-8G  board,  it  also  provides 
DMA  services  for  the  NBFIardwareCode 
driver  and  other  data  acquisition  drivers. 

Next,  the  INIT  opens  as  many  GPIB 
bus  drivers  as  needed  —  in  this  case, 
if  auto-configuration  is  set.  The  bus 
driver  will  be  .gpibO  for  the  GPIB  hard¬ 
ware  in  the  lower  slot  and  gpibl  will 
be  for  the  GPIB  in  the  higher  slot. 

Each  bus  driver  opens  the  shared 
code  and  the  hardware-variant  code. 
The  bus  driver  opens  hardware  variant 
code  that  matches  the  hardware  type 
for  the  slot  associated  with  the  bus 
driver.  These  open  calls  link  the  bus 
driver’s  read,  write,  and  control  calls 
to  the  hardware  drivers. 

One  of  the  drivers  is  a  hardware 
variant  for  the  serial  ports.  This  driver 
can’t  be  automatically  configured  at  boot 
time,  because  there  is  no  way  to  find 
out  what  kind  of  device  is  attached 
without  disturbing  the  serial  port.  If 
you  write  commands  out  the  port  to 
see  if  it  is  a  serial  device  that  the  INIT 
has  a  driver  for,  you  will  get  undefined 
results  if  the  port  is  connected  to  some 
other  device. 

Because  the  INIT  sysz  resource  has 
requested  allocation  of  a  certain  amount 
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of  additional  system  heap  memory,  the 
drivers  in  the  INIT  should  allocate  dur¬ 
ing  the  execution  of  the  INIT  all  the 
memory  that  they  will  need.  Memory 
not  allocated  by  the  drivers  can  be 
taken  by  subsequent  INITs,  and  thus 
will  not  be  available  when  an  applica¬ 
tion  executes  a  call  to  one  of  the  driv¬ 
ers.  There  is  no  recommended  way  to 
expand  the  system  heap  at  run  time, 
so  you  are  stuck  with  an  inoperative 
driver  until  something,  like  a  desk  ac¬ 
cessory  or  driver,  releases  enough  sys¬ 
tem  memory,  usually  by  being  closed. 

The  NB-DMA-8G  is  a  multifunction 
board.  It  has  two  distinct  hardware  sec¬ 
tions,  the  GPIB  section  and  the  DMA 
section.  Making  a  driver  for  each  sec¬ 
tion  is  the  best  approach.  The  NBHard- 
wareCode  driver  handles  the  GPIB  sec¬ 
tion,  and  the  NB-DMA  driver  handles 
the  DMA  section.  This  approach  mini¬ 
mizes  the  duplication  of  code  for  this 
set  of  drivers.  Any  driver  for  the  GPIB 
or  data  acquisition  can  use  DMA  serv¬ 
ices  by  calling  the  DMA  driver  instead 
of  manipulating  the  DMA  section  of 
the  NB-DMA-8G  directly. 

The  NBHardwareCode  is  a  multi¬ 
board  driver.  If  the  bus  is  associated 
with  the  NB-DMA-8G,  the  drivers,  as 
just  described,  are  used.  The  NBHard¬ 
wareCode  handles  both  the  NB-GPIB 
board  and  the  GPIB  section  of  the  NB- 
DMA-8G  board;  the  hardware  is  virtu¬ 
ally  identical. 

The  INIT  code  performs  a  number 
of  simple  steps  to  load  a  set  of  drivers. 
Those  steps  are: 

1 .  Initialize  the  Macintosh  Toolbox  Man¬ 
agers.  Because  most  of  the  Toolbox 
Managers  should  not  be  initialized  un¬ 
til  needed,  you  only  need  to  initialize 
and  open  the  graph  port  (for  plotting 
the  icon)  to  show  that  the  INIT  is  run¬ 


Figure  1:  Device  drivers  and  associated 


ning.  This  initialization  makes  the  cur¬ 
rent  grafPort  the  size  of  the  screen. 

2.  Show  the  icon  in  the  bottom  lower- 
left  comer  of  the  screen.  The  icon  will 
remain  on  the  screen  until  after  all  INITs 
have  run  or  InitWindows  is  called. 

3.  Check  for  a  user  abort.  If  Com¬ 
mand  Period  is  pressed,  then  give  the 
option  of  aborting  the  device  driver 
installation.  This  should  be  standard 
practice  for  INITs.  (If  you  hold  down 
the  Command  Period  keys  to  prevent 
the  INIT  from  loading  drivers  and  the 
Command  key  is  still  pressed  when  Multi- 
Finder  starts  to  execute,  you  will  also 
prevent  MultiFinder  from  launching.) 

4.  Call  SysEnvirons  and  check  that 
the  INIT  is  running  on  the  right  ma¬ 
chine.  Some  INITs  should  abort  if  run¬ 
ning  on  the  wrong  type  of  machine, 
or  if  the  machine  is  missing  needed 
resources. 

5.  Get  the  driver  information  tables 
from  resources  in  the  INIT  file.  There 
are  two  tables  of  information:  A  driver 
table  and  an  owned  resource  table. 
Information  in  these  tables  includes  the 
driver  resource  ID,  which  will  change 
if  any  resource  ID  collision  occurs;  the 
load  status;  the  driver  type,  which  de¬ 
termines  under  what  circumstances  the 
driver  is  to  be  loaded;  and  the  driver 
name.  The  load  status  is  determined 
by  the  INIT  from  the  driver  type  and 
the  type  of  boards  found  in  the  com¬ 
puter.  These  tables  allow  the  INIT  to 
calculate  the  number  of  drivers  and 
give  information  about  each  driver. 

6.  Get  the  configuration  data  from  the 
INIT  file.  This  data  allows  the  user  to 
customize  the  operating  characteristics 
of  the  device  drivers  or  the  INIT. 

7.  Mark  a  driver  for  loading  if  the  slot 
is  for  serial  hardware;  or  if  the  slot  is 
for  NuBus  and  one  of  our  boards  is  in 
the  slot;  or  if  the  driver  is  called  by  a 


expansion  cards 


driver  that  is  marked  for  loading. 

8.  Alert  the  user  if  the  device  drivers 
are  already  loaded.  The  user  may  have 
two  different  revisions  of  the  drivers 
in  the  system.  To  detect  a  duplicate  set 
of  drivers,  point  the  Resource  Manager 
away  from  the  INIT  so  it  won’t  see 
these  device  drivers.  Then  try  to  open 
the  drivers  that  have  been  marked  for 
loading.  Only  these  drivers  would  be 
previously  loaded.  Having  two  sets  of 
drivers  in  memory  would  be  a  waste 
of  memory  and  driver  IDs  (a  limited 
resource). 

9.  Check  that  there  is  enough  mem¬ 
ory.  Now  that  the  drivers  have  been 
marked  for  loading,  the  INIT  must  de¬ 
termine  whether  they  will  fit  in  mem¬ 
ory.  Read  each  resource  into  memory. 
If  a  memory  error  occurs,  abort  the 
INIT  process. 

10.  Make  sure  that  each  driver  ID  is 
unique  within  the  system.  There  are 
two  places  to  check:  The  driver  unit 
table,  which  has  a  device  control  entry 
(DCE)  for  each  open  driver,  and  the 
System  file.  We  are  interested  in  those 
drivers  loaded  by  INITs  that  have  run 
previous  to  our  INIT,  and  drivers  in  the 
System  file,  which  may  be  opened  later. 
Because  all  INITs  test  for  collisions  with 
drivers  loaded  by  previous  INITs,  there 
is  no  chance  of  a  driver  collision  with 
subsequently  loaded  drivers.  Drivers 
loaded  by  applications  must  take  the 
same  precautions  as  do  those  loaded 
by  INITs.  If  a  driver  were  loaded  with 
an  ID  that  collides  with  that  of  an  open 
driver,  the  new  driver  would  replace 
the  open  driver.  If  its  ID  were  to  collide 
with  that  of  an  unopened  driver  in  the 
System  file,  then  the  system  driver  would 
replace  our  driver  when  the  system 
driver  was  opened. 

Initially,  there  are  only  64  IDs  avail¬ 
able,  but  Inside  Macintosh  says  that 
the  table  will  automatically  expand  to 
128.  Because  some  of  the  IDs  are  re¬ 
served  for  the  system,  it  is  not  clear 
whether  the  table  expands  when  all 
user  IDs  are  used,  or  when  all  64  IDs 
are  used.  If  it  is  the  former  case,  then 
which  IDs  are  user  IDs?  Do  they  in¬ 
clude  the  desk  accessory  IDs?  If  a  driver’s 
ID  is  changed,  then  the  ID  of  each  of 
its  owned  resources  must  also  be 
changed. 

11.  Open  the  drivers.  In  this  exam¬ 
ple,  only  the  master  driver  and  the  bus 
drivers  are  opened.  These  drivers  are 
loaded  only  if  needed  as  determined 
by  markLoad.  All  other  drivers  are 
subdrivers  that  are  opened  by  the  mas¬ 
ter  driver,  bus  drivers,  or  another 
subdriver.  Opening  a  driver  creates  a 
DCE  in  the  driver  unit  table. 

12.  Detach  the  drivers.  When  an  ap¬ 
plication  quits,  all  of  its  resources  are 
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(continued  from  page  16) 
removed  from  memory.  So  that  the 
driver  resources  will  not  be  removed, 
they  are  detached  from  the  INITs  list 
of  resources.  Detaching  the  driver  re¬ 
sources  affects  only  the  memory  copy 
of  the  resources  —  it  does  not  remove 
the  drivers  from  the  INIT  file.  Because 
the  driver  resources  are  detached,  the 
memory  copy  of  the  driver  resources 
won’t  be  removed  when  the  INIT  file 
closes.  As  long  as  the  drivers  remain 
open,  their  DCEs  will  remain  in  the 
unit  table,  allowing  your  application 
to  open  and  use  the  drivers  without  also 
opening  the  INIT  file.  Configuration  data 
can  be  passed  to  the  drivers  in  the 
open  call. 

Important  Resources 

Resources  in  the  file  DDJInit.r  (Listing 
Three)  are  parts  of  the  INIT  file  that 
may  be  conveniently  described  with 
the  MPW  resource  language  and  com¬ 
piled  with  the  MPW  Rez  resource  com¬ 
piler.  Resources,  such  as  577?#,  are  stan¬ 
dard  to  the  Macintosh  OS.  As  such, 
there  are  ROM  calls  that  can  make  use 
of  these  resources  directly.  Other  re¬ 
sources,  such  as  dTbl,  were  designed 
specifically  for  the  INIT.  Typically,  re¬ 
sources  for  a  specific  application  have 
a  corresponding  C  structure  or  Pascal 
record  to  identify  each  part  of  the  data 
stored  in  the  resource.  The  structure 
for  the  dTbl  makes  it  clear  that  the  data 
is  a  list  of  driver  information:  The  driver 
ID,  load  status,  type,  and  name.  Figure 
2  shows  which  parts  of  the  operating 
system  and  the  INIT  need  which  re¬ 
sources.  The  Finder  resources  BNDL, 
FRET,  DDJI,  and  1CN#  are  discussed  in 
detail  in  Inside  Macintosh ,  Volume  III 
and  vers  in  “Tech  Note  #189.” 

The  important  resources  include  three 
that  are  user  defined:  dTbl ,  oTbl,  and 
busD.  The  type  dTbl  is  a  table  of  infor¬ 
mation  about  the  drivers.  There  are 


Figure  2:  INIT  resources 
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four  elements  in  each  entry  of  the  ta¬ 
ble:  The  driver  ID,  the  driver  load  status, 
the  load  attribute,  and  the  driver  or 
board  name.  The  type  oTbl  is  a  table 
of  information  about  resources  owned 
by  one  of  the  drivers  in  the  driver- 
table.  There  are  three  elements  in  each 
entry  of  the  table:  The  type  of  owned 
resource,  the  sub-ID  of  the  owned  re¬ 
source,  and  the  ID  of  the  resource’s 
owner.  In  these  two  tables,  you  enter 
information  for  each  driver  that  the  INIT 
must  load.  The  type  busD  is  a  table  of 
user  configuration  data.  The  contents 
of  this  resource  depends  on  the  con¬ 
figuration  data  needed  by  the  drivers. 
I  have  included  some  example  con¬ 
figuration  data  used  by  the  bus  drivers. 

The  error  messages  are  in  a  standard 
resource  of  strings,  type  577?#.  This  al¬ 
lows  the  INIT  to  be  localized  for  other 
countries,  and  it  allows  me  to  use  the 

The  INIT  code  performs 
a  number  of  simple  steps 
to  load  a  set  of  drivers 


standard  system  call  GetlndString  to 
read  a  string  from  the  resource. 

Compiling  the  Source  Code  and 
Resource  Files 

With  all  the  source  code  files  and  re¬ 
source  files  completed  we  can  compile 
them  to  create  the  various  pieces  of  the 
INIT.  First,  we  create  the  INIT  resource, 
which  is  the  INIT’s  executable  code  am 
by  the  system’s  INIT  runner,  INIT  31,  at 
boot  and  restart  times.  Next,  we  append 
the  resources  created  by  MPW  Rez. 

Rezis  used  because  it  identifies  many 
system  resource  formats.  You  can  de¬ 


fine  your  own  resource  types,  and  you 
can  decompile  resources  with  Derez 
that  you  create  or  modify  in  ResEdit. 

The  Think  C  project  should  contain 
all  source  files  and  libraries  needed. 
(Read  Think  C’s  warnings  about  using 
library  calls  that  need  global  storage. 
If  you  are  using  library  calls  that  need 
globals,  then  recompile  the  library  as 
described  in  the  Think  C  manual.)  From 
the  Project  menu,  choose  the  menu 
item  Set  Project  Type  .  .  .  Click  the  Code 
Resource  radio  button  onto  the  File 
Type  to  ????,  and  the  Creator  to  ????.  (See 
Figure  3  )  The  file  type  and  creator  will 
be  changed  to  their  correct  values  after 
the  INIT  has  been  completely  built, 
because,  by  itself,  this  is  not  a  working 
INIT  file,  so  we  don’t  want  the  system 
to  identify  it  as  such.  We  don’t  want  a 
custom  header;  we  will  use  Think  C’s 
standard  header  for  code  resources. 
Enter  a  name  such  as  DDJ  Init  (this  is 
optional  because  INITs  are  not  referred 
to  by  name).  Set  the  resource  type  to 
INIT,  ID  to  0,  and  resource  attributes 
to  Locked.  Now  choose  options  from 
the  Edit  menu  and  select  any  options 
you  want.  I  suggest  MacsBug  Symbols 
for  Code  Generation  and  Check  Pointer 
Types,  and  Require  Prototypes  for  Com¬ 
piler  flags. 

Now  create  the  INIT  resource  by 
choosing  Build  Code  Resource  .  .  .  from 
the  Project  menu.  Enter  the  file  name 
of  the  INIT,  such  as  * INIT.rsrc  (I  put 
an  asterisk  as  the  first  character  of  the 
name  of  any  part  of  the  INIT  file  for 
easy  identification).  Move  to  the  Build 
INIT  folder  and  save.  This  save  com¬ 
mand  overwrites  any  existing  file  of 
that  name. 

Code  resources,  such  as  the  INIT 
resource,  can’t  be  segmented  with  Think 
C  3  0,  but  with  MPW  C  3  0  you  can 
make  segments  larger  than  32K  bytes. 
Unlike  code  resources,  Think  C  will  let 
you  create  segmented  drivers.  If  you 
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(continued  from  page  18) 
create  a  multisegment  driver,  then  there 
will  be  one  DRVR  resource  and,  for 
each  segment,  a  DCOD  resource.  Each 
of  these  resources  will  have  global  data 
in  an  owned  DATA  resource.  If  any 
owned  DATA  resource  has  zero  size, 
you  can  delete  it.  You  must  enter  the 
information  on  all  of  these  resources 
in  the  driver  table  used  by  the  INIT. 
Add  them  to  the  source  code  file  com¬ 
piled  by  MPW  Rez. 

The  MPW  Rez  command  compiles 
resources  specified  with  the  Rez  lan¬ 
guage,  which  is  similar  to  the  C  lan¬ 
guage.  The  resource  file,  DDJInit.r ;  speci¬ 
fies  various  Finder  and  INIT  resources, 
not  including  the  INIT  and  DRVR  re¬ 
sources.  Four  commands  are  used  to 
build  the  final  INIT  file.  The  first  two 
commands  set  shell  variables  to  the 
name  of  the  build  directory,  where  all 
the  compiled  driver  and  INIT  files  are, 
and  to  the  name  of  the  INIT  file  to  be 
created.  The  Rez  command  specifies 
the  output  file  name,  the  search  direc¬ 
tory  for  Include  statements,  and  the 
source  file.  On  this  line,  you  can  de¬ 
fine  an  identifier  to  control  conditional 
compilation.  This  is  useful  if  you  want 
different  resources  for  different  comput¬ 
ers.  The  last  command  sets  the  bundle 
bit,  the  file  type,  and  file  creator.  These 
are  the  commands  used  to  compile 
this  file;  set  the  file  attributes,  type, 
and  creator;  and  copy  the  resources 
to  the  INIT: 

Set  BuildDir  -Build  INIT:' 

Set  InitName  ’DDJ  INIT' 


Figure  3’  The  Project  menu 


Rez  -o  "IBuildDirl(InitName)" 

-s  "IBuildDirl"  DDJInit.r 
Setfile  "IBuildDirlllnitNamel" 

-a  B  -t  INIT  -c  DDJI 

Near  the  top  of  the  file  are  three  In- 
elude  statements  that  read  the  INIT  and 
DRVR  resources  into  the  INIT  file.  In 
this  example,  I  put  all  my  device  driv¬ 
ers  in  one  file,  *DDJ  Driver ,  with  Res- 
Edit.  The  Include  statements  find  the 
driver  file  with  the  help  of  the  search 
directory  specified  by  the  —s  option  to 
the  Rez  command.  The  drivers  used  in 
this  example  must  be  locked  in  the 
system  heap.  The  first  Include  state¬ 
ment  copies  into  the  INIT  file  any  driver 
whose  ID  is  in  the  range  0  -  64,  chang¬ 
ing  the  resource  attributes  of  each  driver 
from  Purgeable  to  System  Heap  and 
Locked,  leaving  the  ID  and  name  as 
they  were.  There  is  no  easy  way  to  set 
these  attributes  with  Think  C.  The  next 
statement  copies  all  of  the  global  data 
resources  to  the  INIT  file.  Think  C  sets 
the  resource  attributes  to  Locked.  The 
last  Include  statement  copies  the  INIT 
resource  to  the  INIT  file.  The  attributes 
remain  the  same  because  you  set  the 
resource  attributes  of  the  INIT  resource 
to  Locked  in  the  Think  C  project.  Here 
are  the  Include  statements: 

include  "*DDJ  Driver"  'DRVR'  (0:64) 
as  DRVR’  ($$ID,  $$Name, 
SysHeap,  Locked); 
include  "*DDJ  Driver"  'DATA' 

(-  15424:-  15200);  as 'DATA' 
($$ID,  SysHeap,  Purgeable); 
include  '"TNIT.rsre"; 


Testing  the  INIT  Program 

As  with  any  application,  you  should 
test  the  INIT  code  to  make  sure  it  per¬ 
forms  correctly.  If  an  INIT  bombs,  then 
the  user  must  abort  the  INIT  before  it 
executes,  or  boot  on  another  volume. 
Most  INITs  don’t  have  a  way  for  the 
user  to  make  the  INIT  abort  execution. 

Testing  the  INIT  takes  some  plan¬ 
ning  because  the  actions  performed 
by  the  INIT  depend  on  the  user  con¬ 
figuration  data  and  the  hardware  con¬ 
figuration  of  the  computer  when  the 
INIT  is  executed  by  the  system.  The 
configuration  is  determined  by  the  ex¬ 
pansion  boards  installed,  the  drivers 
required  by  the  user  configuration  data, 
the  presence  of  drivers  loaded  by  any 
previously  run  INIT  file,  and  the  pres¬ 
ence  of  drivers  in  the  System  file. 

This  INIT  makes  ID  changes  perma¬ 
nent,  so  when  you  are  building  the 
INIT,  build  it  in  any  folder  other  than 
the  System  Folder.  The  reason  is  that  if 
an  ID  collision  occurs,  both  the  driver 
and  the  INIT’s  driver  and  owner  tables 
get  updated  with  the  new  driver  ID. 
By  keeping  a  master  version  of  the 
current  INIT  and  copying  it  to  the  Sys¬ 
tem  Folder,  you  can  be  sure  that  the 
driver  IDs  agree  with  the  IDs  in  the 
INIT  resources.  Otherwise,  if  you  re¬ 
compile  a  driver  whose  ID  previously 
collided  and  add  it  to  the  INIT  in  the 
System  Folder,  the  resource  tables  will 
have  a  different  ID  than  the  driver. 

The  first  test  is  to  open  all  the  drivers 
that  the  INIT  can  load.  If  your  applica¬ 
tion  fails  to  open  a  driver,  compile 
your  drivers  with  MacsBug  symbols. 
After  restarting  the  computer,  break  to 
the  debugger  and  perform  a  symbol 
dump  of  the  system  heap.  If  your  driver’s 
symbols  don’t  appear,  then  any  one  of 
the  following  may  be  true: 

•  The  INIT  never  marked  the  driver  for 
loading. 

•  The  INIT  never  detached  the  driver 
resource. 

•  The  driver’s  System  Heap  attribute 
was  not  set.  Accordingly,  the  driver 
was  loaded  into  the  application  heap, 
which  was  subsequently  initialized. 

•  The  driver’s  Purgeable  attribute  was 
set,  and  the  driver  was  purged  before 
you  looked  for  the  symbols. 

•  The  driver  was  successfully  closed 
before  you  looked  for  the  symbols. 

If  your  driver’s  symbols  do  appear, 
then  it  may  be  that  the  driver  was  never 
opened,  either  by  the  INIT  or  by  an¬ 
other  driver,  before  the  driver  resource 
was  detached  by  the  INIT. 

To  test  for  duplicate  drivers,  simply 
copy  the  INIT  file  to  the  System  folder, 
select  and  duplicate  it,  and  restart  the 
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computer.  You  will  see  the  first  INIT 
complete  normally,  but  the  second 
driver  will  put  up  an  alert  to  flag  the 
duplicate  driver  condition.  You  should 
perform  this  test  for  each  separate  driver 
configuration. 

The  INIT  should  never  report  an  “out 
of  system  heap  memory  error”  because 
the  size  resource  in  the  INIT  file  re¬ 
quests  enough  additional  memory  from 
the  system  to  satisfy  the  highest  mem¬ 
ory  requirement  of  the  set  of  drivers. 
However,  an  error  will  occur  if  the 
system  does  not  have  enough  memory 
to  satisfy  the  request,  or  if  you  set  the 
value  of  the  size  resource  too  low. 

To  test  a  memory  error  if  your  driv¬ 
ers  use  more  than  about  16K  bytes  of 
memory,  then  set  the  size  resource  to 
zero,  make  sure  enough  drivers  will 
be  loaded,  and  restart  the  computer. 
Because  the  system  normally  has  no 
more  than  16K  bytes  of  free  space  in 
the  system  heap,  the  INIT  should  re¬ 
port  the  error  to  cause  a  memory  error 
under  normal  condition. 

If  your  drivers  are  too  small,  then 
you  may  decide  that  testing  for  an  out-of- 
memory  condition  is  not  required.  You 
can  still  perform  the  test  by  making 
your  drivers  larger  than  16K  bytes.  To 
do  this,  open  a  text  file  that  is  larger 
than  16K  bytes,  such  as  the  initOpen- 
Driver.c  source  file;  select  all  of  it;  and 
copy  (to  the  Clipboard).  With  ResEdit, 
select  one  of  the  drivers  that  will  be 
marked  for  loading,  and  choose  Open 
General  from  the  File  menu.  Scroll  to 
the  bottom,  put  the  cursor  after  the  last 
byte  on  the  right  (ASCII)  side  of  the 
window,  and  paste  (from  the  Clipboard). 
Close  the  window  and  choose  Get  Info. 
You  will  see  that  your  driver  now  oc¬ 
cupies  more  than  16K  bytes.  Now  quit 
ResEdit,  saving  the  changes,  and  restart 
the  computer.  This  time  you  should  get 
the  “out  of  system  heap  memory”  error. 

If  testing  the  INIT  requires  that  the 
INIT  be  modified,  restore  it  to  its  origi¬ 
nal  condition  before  starting  a  new 
phase  of  testing.  Just  copy  the  original 
INIT  to  the  system  folder.  Make  changes 
only  to  this  copy  of  the  INIT  when 
using  a  resource  editor. 

A  major  portion  of  the  INIT  code 
deals  with  driver  resource  ID  collisions. 
Testing  this  feature  will  tell  whether 
the  ID  of  our  conflicting  driver  was 
successfully  changed  to  an  unused  ID, 
and  whether  the  other  driver  was  not 
altered  or  opened. 

The  INIT  has  some  conditionally  com¬ 
piled  code  that  you  can  enable  by  de¬ 
fining  the  identifier  DEBUG2.  This  code 
will  put  up  an  alert  when  a  driver  con¬ 
flict  occurs  and  will  show  the  new  ID 
number. 

To  cause  a  collision  with  a  driver  in 


the  System  file,  copy  any  driver  from 
the  INIT  that  will  be  loaded,  and  paste 
it  in  the  System  file;  and  use  ResEdit  to 
change  the  name  of  this  copy  of  the 
driver  to  an  unused  name.  Now  this 
driver  will  conflict  with  the  driver  in 
the  INIT,  so  restart  the  computer,  step 
through  the  alerts,  and  make  a  note  of 
the  new  ID  that  the  driver  will  be  given. 
With  ResEdit,  check  that  the  driver  you 
put  in  the  System  file  has  not  been 
altered.  Check  its  name,  size,  and  at¬ 
tributes.  (MPW’s  ResEqual  compares  all 
the  resources  between  two  files,  so  it 
would  not  be  useful  in  this  case).  Now 

Testing  the  INIT  takes 
some  planning,  because 
the  actions  performed 
by  the  INIT  depend  on 
the  user  configuration 
data  and  the  hardware 
configuration  of  the 
computer  when  the  INIT 
is  executed  by  the  system 

check  the  driver  in  the  INIT  file:  Its  ID 
should  be  the  new  ID,  and  the  owner 
ID  of  all  its  owned  resources,  listed  in 
the  owned  table,  should  also  be  the 
new  ID. 

To  cause  a  collision  with  a  driver 
loaded  by  a  previous  INIT,  compile  the 
INIT  code  with  the  identifier  DEBUG3, 
which  will  disable  checking  for  dupli¬ 
cate  drivers.  Copy  the  resulting  INIT 
file  to  the  System  Folder  and  then  du¬ 
plicate  it  in  the  System  Folder  so  that 
two  copies  of  the  INIT  will  execute. 
Rename  the  copy  so  that  it  runs  before 
the  other  (the  system  runs  INITs  in 
alphabetical  order).  Change  the  name 
of  each  driver  so  that  your  driver  test 
program  will  have  to  open  the  set  of 
drivers  that  were  given  new  IDs. 

Restart  the  computer  and  make  a 
note  of  all  the  new  IDs.  Check  that  the 
INIT  that  executes  second  changes  the 
IDs  of  all  its  drivers  that  are  marked  for 
loading,  because  these  drivers  will  ex¬ 
ist  in  the  driver  unit  table  from  the  INIT 
that  runs  first.  You  can  use  ResEdit  to 
check  that  the  driver  and  owned  re¬ 
sources  IDs  have  been  changed  cor¬ 
rectly.  The  new  IDs  must  not  conflict 


with  any  of  the  drivers  in  the  System 
file.  Now  run  a  test  program  to  exercise 
your  drivers.  Check  the  drivers  in  the 
INIT  that  runs  first.  There  should  be 
no  changes  in  the  resource  IDs  unless 
there  was  a  conflict  with  some  other 
drivers.  The  resource  attributes  should 
also  be  at  their  default  values. 

If  loading  a  driver  depends  only  on 
the  user  configuration  data,  such  as  a 
driver  for  hardware  attached  to  the  se¬ 
rial  port,  make  sure  all  the  needed  driv¬ 
ers  get  loaded  when  no  other  hard¬ 
ware  variants  are  in  the  computer.  This 
test  would  verify  that  a  driver  could  be 
marked  for  loading  by  the  user  con¬ 
figuration  data  only. 

Conclusion 

Loading  device  drivers  with  an  INIT 
should  be  the  preferred  method  over 
installing  them  into  the  System  file.  With 
this  method,  one  file  can  accomplish 
three  things  for  you.  It  can  make  instal¬ 
lation  and  upgrading  easier;  it  can  con¬ 
tain  a  Control  Panel  device  that  can 
perform  user  configuration;  and  it  can 
expand  the  system  heap  to  make  room 
for  the  drivers. 
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MEMORY 

MANAGEMENT 

with  MacApp 

I  Take  control  of  your 
application  s  heap 

Curt  Bianchi 


any  Macintosh  programmers 
equate  MacApp  with  object- 
oriented  programming  and 
vice  versa.  Although  it’s  cer¬ 
tainly  true  that  much  of  MacApp  is 
object-oriented,  it  offers  many  services 
implemented  with  procedural  program¬ 
ming  as  well.  Among  those  services  are 
tools  that  help  with  the  difficult  prob¬ 
lem  of  managing  an  application's  mem¬ 
ory  space.  These  tools  range  from  use¬ 
ful  debugging  aids  to  techniques  for 
detecting  and  recovering  from  memory 
allocation  failures,  culminating  in  a  com¬ 
prehensive  strategy  for  implementing 
robust  Macintosh  applications  in  a  dy¬ 
namic  memory  environment.  Because 
these  tools  are  implemented  as  con¬ 
ventional  Pascal  units  and  supplied  with 
source  code,  they  can  be  used  by  any 
Macintosh  program  built  with  MPW, 
including  those  written  in  C. 

The  purpose  of  this  article  is  to  de¬ 
scribe  some  of  these  tools  so  that 
MacApp  and  non-MacApp  programmers 
alike  can  make  use  of  them  and  per¬ 
haps  even  entice  some  non-MacAp- 
pers  into  giving  MacApp  a  try.  By  the 
way,  I  assume  you  have  a  pretty  good 
idea  of  how  the  Macintosh  Memory 
Manager  works.  If  you  don’t,  How  to 
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Write  Macintosh  Softwareby  Scott  Knas- 
ter  has  an  excellent  description,  and  it’s 
funny,  too!  And  there’s  always  Inside 
Macintosh,  though  it  lacks  Scott’s  hu¬ 
mor  (unless  you  count  the  Munger). 
Also,  this  article  is  based  on  MacApp 
2.0B9.  Some  details  may  not  apply  to 
previous  versions  of  MacApp,  includ¬ 
ing  MacApp  2.0B5. 

The  Problem 

One  of  the  most  difficult  aspects  of 
writing  a  Macintosh  application  is  the 
pervasive  use  of  dynamic  memory  allo¬ 
cation.  The  Macintosh  user  interface 
and  the  design  of  the  Toolbox  both 
encourage  heavy  use  of  dynamic  mem¬ 
ory  allocation.  For  example,  good  Macin¬ 
tosh  programs  allow  the  user  to  open 
multiple  documents  and  windows,  lim¬ 
ited  only  by  available  memory.  Because 
there  is  no  way  to  know  in  advance 
how  many  windows  or  documents  can 
be  opened  on  a  given  machine,  dy¬ 
namic  allocation  of  window  and  docu¬ 
ment  data  structures  provides  the  natu¬ 
ral  solution.  Given  that  available  mem¬ 
ory  is  indeed  limited,  a  major  task  in 
completing  an  application  is  ensuring 
that  it  properly  handles  the  time  when 
memory  fills  up  and  dynamic  memory 
requests  are  no  longer  satisfied. 

To  complicate  matters  further,  an  ap¬ 
plication  doesn’t  have  complete  con¬ 
trol  of  its  own  heap!  (See  the  accompa¬ 
nying  box.)  The  Macintosh  system  dy¬ 
namically  allocates  handles,  such  as 


code  and  system  resources,  in  the  ap¬ 
plication’s  heap.  And  the  system  isn’t 
very  polite  about  such  matters:  It  doesn’t 
inform  the  application  when  using  its 
heap,  nor  does  it  recover  gracefully  if 
one  of  its  requests  fails.  Furthermore, 
any  number  of  foreign  objects  can  take 
up  residence  in  your  heap,  the  most 
common  being  the  desk  accessory, 
which  uses  your  heap  when  MultiFin- 
der  isn’t  available.  In  other  words,  your 
explicit  memory  requests  compete  with 
the  demands  (they  can  hardly  be  called 
requests  because  they  can’t  fail)  from 
the  Macintosh  system  for  the  very  same 
memory  space  —  namely  —  the  appli¬ 
cation’s  heap. 

MacApp's  Strategy 

Clearly,  an  overall  strategy  is  needed 
for  implementing  a  program  in  such 
an  environment.  The  goals  of  the  strat¬ 
egy  should  be  twofold.  First,  it  should 
implement  a  scheme  that  always  main¬ 
tains  enough  free  space  in  the  applica¬ 
tion  heap  to  satisfy  the  system’s  needs. 
And  second,  the  heap  should  always 
have  enough  space  to  carry  out  essen¬ 
tial  operations  such  as  quitting,  saving 
documents,  or  deleting  data  from  docu¬ 
ments.  Though  more  subtle,  the  latter 
goal  is  just  as  important  as  the  former. 
And  it’s  easier  said  than  done.  Quitting 
an  application,  for  example,  typically 
requires  loading  code  segments  that 
are  used  only  when  terminating  the 
program.  If  the  program  has  allowed 
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the  user  to  use  up  too  much  memory 
for  data,  then  those  termination  seg¬ 
ments  won’t  be  loadable!  (Don’t  laugh, 
I’ve  seen  this  happen.) 

MacApp’s  strategy  is  mostly  imple¬ 
mented  in  a  Pascal  unit  called  “UMem- 
ory,”  which  controls  which  memory 
requests  succeed.  The  idea  is  to  ensure 
that  essential  requests  always  succeed, 
whereas  non-essential  requests  may  fail. 
Examples  of  requests  that  must  suc¬ 
ceed  are  allocations  for  code  segments 
(strictly  speaking,  MacApp’s  strategy  is 
smart  enough  that  only  certain  seg¬ 
ments  must  be  loadable),  defprocs,  and 
packages.  An  example  of  a  request  that 
may  fail  is  the  allocation  of  data  struc¬ 
tures  to  open  a  second  (or  third,  and 
so  on)  document. 

The  way  MacApp  does  this  is  by 
reserving  enough  space  in  the  heap  so 
that  essential  memory  requests  can  be 
satisfied  at  any  point  in  the  program. 
Because  the  Macintosh  Memory  Man¬ 
ager  doesn’t  know  an  essential  request 
from  a  nonessential  one,  it’s  necessary 
to  intervene  in  the  process  and  give  the 
Memory  Manager  some  help. 

Fortunately,  the  designers  of  the  Mem¬ 
ory  Manager  provided  a  mechanism 
that  lets  you  do  just  that.  It’s  called  the 
grow  zone  function.  The  way  it  works 
is  that  whenever  the  Memory  Manager 
finds  that  there  isn’t  enough  space  in 
the  heap  to  satisfy  a  memory  request, 
it  calls  the  grow  zone  function  in  the 
hopes  of  freeing  additional  space  in 
the  heap.  The  grow  zone  function  is 
called  repeatedly  until  either  there  is 


enough  space  in  the  heap  to  satisfy  the 
request  or  the  grow  zone  function  is 
unable  to  free  any  more  space,  in  which 
case  the  allocation  request  fails.  By  in¬ 
stalling  a  grow  zone  function,  a  pro¬ 
gram  can  determine  which  requests  suc¬ 
ceed  and  which  ones  fail. 

Permanent  vs.  Temporary  Requests 

MacApp’s  grow  zone  function  distin¬ 
guishes  between  essential  and  nones¬ 
sential  memory  requests.  In  MacApp 
terminology,  these  are  classified  as  tem¬ 
porary' (essential)  and  permanent  { non- 
essential).  A  useful  way  of  thinking 
about  this  is  that  temporary  requests 
are  program-driven  whereas  permanent 
requests  are  user-driven.  Memory  allo¬ 
cated  with  a  temporary  request  is  freed 
when  the  program  has  finished  with  it; 
memory  allocated  with  a  permanent 
request  is  freed  when  the  user  has  fin¬ 
ished  with  it.  Table  1  provides  examples 
of  each. 

Given  this  distinction  between  tem¬ 
porary  and  permanent  memory  re¬ 
quests,  how  does  MacApp  take  advan¬ 
tage  of  it?  If  you  look  at  Table  1,  you’ll 
notice  that  the  very  nature  of  tempo¬ 
rary  requests  is  that  they  must  succeed. 
For  one  thing,  most  temporary  requests 
come  from  the  system,  which  assumes 
success!  Also,  because  these  requests 
are  program-driven,  their  success  is  usu¬ 
ally  essential  to  keep  the  application 
running.  In  other  words,  failure  of  a 
temporary  request  is  usually  fatal.  On 
the  other  hand,  the  failure  of  a  perma¬ 
nent  request  simply  indicates  a  lack  of 


memory  to  carry  out  a  user  operation 
such  as  opening  another  document. 
Assuming  the  application  started  with 
enough  memory  to  perform  a  reason¬ 
able  set  of  operations,  failure  of  perma¬ 
nent  requests  isn’t  catastrophic.  It  sim¬ 
ply  indicates  that  the  user  needs  to 
reduce  memory  usage,  say  by  closing 
a  document  or  deleting  some  data. 

MacApp  ensures  the  success  of  tem¬ 
porary  requests  by  reserving  enough 
space  in  the  heap  so  that  any  tempo¬ 
rary  request  succeeds  (ultimately  at  the 
expense  of  permanent  requests).  The 
space  is  reserved  simply  by  allocating 
a  handle  large  enough  to  reserve  it. 
This  handle  is  known  as  the  temporary 
reserve.  Its  size  is  determined  by  taking 
the  total  amount  of  space  reserved  for 
temporary  requests  and  subtracting  from 
it  the  sizes  of  the  currently  allocated 
temporary  handles.  Because  its  pur¬ 
pose  is  to  reserve  space,  the  size  of  the 
temporary  reserve  varies  over  time  as 
the  amount  of  temporary  handles  in 
memory  increases  or  decreases. 

Now,  when  a  memory  request  is 
made  and  there  is  no  room  in  the  heap, 
the  Memory  Manager  calls  MacApp’s 
grow  zone  function.  It  behaves  differ¬ 
ently  depending  on  whether  the  re¬ 
quest  is  temporary  or  permanent.  The 
algorithm  is  shown  in  Table  2.  The 
basic  idea  is  never  to  let  a  permanent 
request  use  space  reserved  for  tempo¬ 
rary  requests,  thereby  always  having 
enough  space  to  satisfy  a  temporary 
request.  (The  emerging  reserve  referred 
to  in  the  algorithm  will  be  described 
later  in  this  article.) 

The  algorithm  raises  some  interest¬ 
ing  questions.  First,  how  is  it  that 
MacApp’s  grow  zone  function  knows 
whether  it’s  been  called  in  response  to 
a  temporary  request  or  a  permanent 
one?  And  second,  how  does  the  grow 
zone  function  know  if  a  handle  is  tem¬ 
porary  and  whether  such  a  handle  is 
currently  in  use  or  not? 

The  Permanent  Flag 

The  answer  to  the  first  question  is  that 
MacApp’s  UMemory  unit  maintains  an 
internal  flag  indicating  whether  it’s  in 
temporary  or  permanent  mode.  It  is 
used  by  MacApp’s  grow  zone  function 
to  decide  what  to  do.  The  normal  state 
of  the  flag  is  temporary,  causing  system 
requests  (which  tend  to  come  at  unpre¬ 
dictable  times)  to  be  temporary. 

For  making  permanent  requests, 
MacApp  defines  four  memory  alloca¬ 
tion  routines,  each  consisting  of  these 
steps: 

1 .  Set  the  flag  to  permanent 

2.  Carry  out  the  request 

3.  Restore  the  state  of  the  flag 


Temporary  Requests 

Temporary  requests  usually  come  from  the  system,  when  it  attempts  to  use  the 

application’s  heap.  Examples  of  such  uses  are: 

•  Code  segments,  whose  handles  are  allocated  by  the  Macintosh  operating  system 
when  a  segment  has  to  be  loaded  into  memory. 

•  Defprocs  for  the  Window  Manager,  Control  Manager,  Menu  Manager,  and  List 
Manager.  They  take  the  form  of  WDEF,  CDEF,  MDEF,  and  LDEF  resources, 
respectively. 

•  Packages,  which  take  the  form  of  PACK  resources. 

•  Fonts,  which  take  the  form  of  FONT  and  FOND  resources.  Handles  for  Toolbox  data 
structures  associated  with  windows,  controls,  etc. 

•  Handles  allocated  by  the  Toolbox  and  operating  system  for  temporary  data  such  as 
printing  data  structures,  regions  for  QuickDraw,  the  file  list  for  Standard  File  dialogs, 
etc. 

•  Handles  allocated  by  the  application  for  short-term  use,  such  as  handles  that  are 
created  and  disposed  of  within  the  same  routine. 

Permanent  Requests 

Most  explicit  requests  by  the  application  are  permanent,  and  are  used  for  data 

structures  requested  by  the  user,  such  as  document  data  structures.  These 

include: 

•  Allocation  of  objects. 

•  Most  handles  allocated  by  the  application. 


Table  1:  Examples  of  temporary  requests  and  permanent  requests 
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These  routines  are  shown  in  Table  3- 
The  inclusion  of  SetPermHandleSize 
and  SetPermPtrSize  may  seem  odd  at 
first,  but  increasing  the  size  of  a  handle 
or  pointer  results  in  a  memory  request 
no  different  from  creating  the  handle 
or  pointer  in  the  first  place.  An  addi¬ 
tional  routine  called  PermAllocation  is 
available  for  setting  the  flag  to  affect 
any  number  of  subsequent  requests. 
Thus,  the  two  code  fragments  in  Listing 
One,  page  28,  accomplish  the  same 
thing  —  they  allocate  two  handles  as 
permanent  requests. 

Most  allocations  by  the  application 
itself  are  permanent.  For  this  reason, 
creating  objects  with  NEW  uses  New- 
PermHandleto  allocate  the  object’s  han¬ 
dle.  Likewise,  most  handles  you  create 
will  be  for  long-lived  data  such  as  docu¬ 
ment  or  window  data  structures,  so 
they  should  be  allocated  with  New- 
PermHandle.  Handles  used  for  short¬ 
term  use,  such  as  those  allocated  and 
disposed  of  in  the  same  routine,  can 
be  allocated  with  NewHandle. 

Temporary  Handles 

The  second  question  that  needs  an¬ 
swering  is  how  MacApp’s  grow  zone 
function  finds  temporary  handles  that 
are  not  in  use.  Actually,  it’s  simple. 
MacApp  maintains  four  lists  of  han¬ 
dles.  The  handles  in  these  lists  are  con¬ 
sidered  temporary,  and  may  be  purged 
by  MacApp’s  grow  zone  function  if  they 
aren’t  in  use.  The  four  lists  are: 

1.  gCodeSegs,  which  contains  handles 
to  all  the  code  segments 

2.  gSysMemList,  which  contains  han¬ 
dles  to  all  the  non-ROM  system  and 
application  LDEF,  CDEF,  MDEF, 
WDEF,  and  PACK  resources 

3-  gApplMemList  and  gApp2MemList, 
which  contain  handles,  usually  to 
resources,  that  the  application  wishes 
to  be  subject  to  purging  by  MacApp’s 
grow  zone  function 

Note  that  handles  to  code  segments 
and  other  resources  exist  whether  or 
not  the  segment  or  resource  is  loaded 
into  memory.  (If  it’s  not  in  memory,  the 
handle’s  master  pointer  is  NIL.) 

The  definition  of  “not  in  use”  is  sim¬ 
ply  that  the  handle  is  not  locked.  For 
example,  when  code  in  a  segment  is 
executed,  the  segment’s  handle  is 
locked.  When  a  segment  is  unloaded, 
it  is  simply  unlocked  and  eligible  for 
purging.  Likewise,  when  a  defproc  is 
actually  used,  it  is  locked.  When  it’s 
not  locked,  it’s  also  eligible  for  purg¬ 
ing.  Normally  all  these  unlocked  han¬ 
dles  would  be  purged  by  the  Memory 
Manager  long  before  it  got  to  the  grow 
zone  function.  But  because  MacApp 
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wants  to  control  when  these  handles 
are  purged,  it  marks  each  of  them  as 
nonpurgable  to  prevent  the  Memory 
Manager  from  interfering.  Thus,  Mac¬ 
App’s  grow  zone  function  is  able  to 
choose  when  to  purge  them. 

By  the  way,  these  lists  are  prioritized 
in  terms  of  which  handles  get  purged 
first.  The  order  is  gCodeSegs,  gAppl¬ 
MemList,  gSysMemList ,  and  gApp2Mem- 
List.  That  is,  MacApp’s  grow  zone  func¬ 
tion  will  purge  unused  code  segments 
before  purging  unused  system  re¬ 
sources.  Similarly,  those  handles  in 
gApplMemList  are  purged  before  those 
in  gApp2MemList. 

Determining  How  Much  Space  to 
Reserve  for  Temporary  Handles 

Essential  to  making  this  scheme  work 
is  ensuring  that  the  right  amount  of 
space  is  reserved  for  temporary  requests. 
If  too  little  space  is  reserved,  then  the 
application  could  wind  up  being  un¬ 
able  to  satisfy  a  temporary  request, 
which  usually  results  in  a  system  error. 
(Despite  its  frequency  of  appearance, 
the  system  error  alert  is  not  considered 
part  of  the  Macintosh  look  and  feel.) 
On  the  other  hand,  reserving  too  much 
space  is  wasteful,  causing  the  applica¬ 
tion  to  require  more  memory  than  it 
really  needs. 

To  determine  how  much  space  to 
reserve,  MacApp  uses  the  following 
formula: 

1.  Add  up  the  sizes  of  the  code  seg¬ 
ments  whose  names  are  listed  in  all 


seg !  resources,  segf  resources  will  be 
explained  shortly  —  their  purpose  is 
to  list  the  segments  that  must  be  in 
memory  at  the  time  the  application  uses 
the  greatest  amount  of  code. 

2.  Add  to  this  total  an  arbitrary  amount 
from  all  mem!  resources.  This  lets  you 
reserve  space  for  noncode  use,  such 
as  system  resources;  mem!  resources 
are  also  explained  later. 

The  result  of  this  formula  should  be 
the  maximum  amount  of  space  that  the 
application  will  need  to  satisfy  any  tem¬ 
porary  request.  Note  that  I  said  should 
be.  That’s  because  both  steps  require 
that  you  provide  information  to 
MacApp  —  namely,  a  list  of  code  seg¬ 
ments  in  step  1  and  an  additional  pad¬ 
ding  amount  in  step  2.  Thus,  this  scheme 
is  only  as  good  as  the  information  you 
give  it. 

Accounting  for  Code  Segments,  or  How 
to  Use  seg!  Resources 

Because  allocating  memory  for  a  code 
segment  is  considered  a  temporary  re¬ 
quest,  it  is  necessary  to  know  how 
much  space  to  reserve  for  code.  A  sim¬ 
ple-minded  approach  would  be  to  add 
up  the  sizes  of  all  the  code  segments 
in  the  application,  but  that  would  be 
wasteful  because  it’s  doubtful  a  large 
program  would  ever  need  all  of  its 
segments  in  memory  at  one  time.  A 
better  way  is  to  add  up  the  sizes  of  the 
code  segments  that  must  be  in  memory 
when  the  application  uses  the  greatest 
amount  of  code.  If  enough  space  is 


For  a  permanent  request: 

1 .  If  the  temporary  reserve  is  too  big,  reduce  its  size  to  that  actually  needed. 

2.  Otherwise,  if  there  is  a  temporary  handle  that's  not  in  use,  purge  it  so  long  as  the 
space  held  by  the  temporary  reserve  and  the  other  temporary  handles  doesn't  fall 
below  the  minimum  that  must  be  reserved. 

3.  Otherwise,  if  the  emergency  reserve  is  intact,  purge  it  as  a  last-ditch  attempt 
to  free  space. 

For  a  temporary  request: 

1 .  If  the  temporary  reserve  exists,  purge  it.  (It  will  be  reallocated  later.) 

2.  Otherwise,  if  there  is  a  temporary  handle  that’s  not  in  use,  purge  it.  A  temporary 
handle  is  considered  to  be  in  use  only  if  it's  locked. 

3.  Otherwise,  if  the  emergency  resen/e  is  intact,  purge  it  as  a  last-ditch  attempt  to 
free  space. 

Table  2:  MacApp's  grow  zone  function  algorithm 


Permanent  Request 

Routines 

Inside  Mac 
Counterparts 

FUNCTION 

NewPermPtr (logicalSize:  Size):  Ptr; 

NewPtr 

FUNCTION 

NewPermHandle (logicalSize :  Size) :  Handle; 

NewHandle 

PROCEDURE 

SetPermHandleSize  (h:  Handle;  newSize :  Size) ; 

SetHandleSize 

PROCEDURE 

SetPermPtrSize (p:  Ptr;  newSize:  Size); 

SetPtrSize 

Table  3:  Permanent  requestors 
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reserved  for  that  case,  then  clearly  there 
will  be  enough  space  for  code  in  all 
cases.  To  do  this,  you  must  determine 
which  segments  are  required  and  the 
sizes  of  those  segments  —  which  is  ex¬ 
actly  what  seg!  resources  are  for. 

A  seg !  resource  is  simply  a  list  of 
strings,  each  of  which  is  the  name  of  a 
segment.  The  segments  listed  in  seg! 
resources  are  those  segments  that  must 
be  in  memory  at  the  point  of  greatest 
code  usage.  When  the  application  is 
started,  MacApp  will  add  up  the  sizes 
of  all  the  code  segments  listed  in  the 
seg!  resources,  arriving  at  the  amount 
of  memory  that  it  reserves  for  code. 
The  nice  part  is  that  you  don’t  have  to 
know  the  actual  size  of  each  segment, 
just  the  names  of  the  segments  involved. 

MacApp  defines  one  seg!  resource 
of  its  own,  shown  in  Listing  Two,  page 
28.  It  lists  MacApp’s  resident  segments  — 
that  is,  the  MacApp-defined  segments 
that  are  always  in  memory  — and  con¬ 
ditionally  lists  MacApp’s  debugging  seg¬ 
ments.  Normally  you  add  one  seg!  re¬ 
source  of  your  own  identifying  which 
segments,  in  addition  to  those  in 
MacApp’s  lists,  are  in  memory  at  the 
point  of  greatest  usage. 

Obviously  the  key  to  making  this 
work  is  knowing  which  segments  to 
list  in  your  seg!  resources.  MacApp's 
debugger  makes  this  easy  to  do.  First, 
you  can  request  that  the  debugger  in¬ 
terrupt  the  program  any  time  the  previ¬ 
ous  point  of  greatest  code  usage  is 
exceeded.  And  second,  when  the  point 
of  greatest  usage  is  identified,  you  can 
ask  the  debugger  to  list  those  code 


segments  in  use  at  the  time.  Voila  — 
you’ve  got  your  sqg/list. 

Here’s  the  step-by-step  procedure: 

1.  Build  a  debugging  version  of  your 
application. 

One  of  the 
most  difficult 
aspects  of  writing  a 
Macintosh  application 
is  the  pervasive  use  of 
dynamic  memory 
allocation 


2.  Start  the  application  by  double-click¬ 
ing  its  icon  (or  better,  by  double-click¬ 
ing  one  of  its  documents).  Immediately 
afterward,  hold  down  the  Shift,  Op¬ 
tion,  and  Command  keys;  this  is  how 
you  break  into  the  MacApp  debugger. 
What  you  want  to  do  is  break  into  the 
debugger  as  soon  as  possible.  When 
the  program  break  occurs,  the  MacApp 
debugger  window  will  appear,  con¬ 
taining  the  cryptic  message 

stopped  at  Begin  1NITUMENUSETUP 

Seg#:  10 


Command  [BCDEFGHILMOP7TQRS 

pTWX?]: 

The  first  line  indicates  where  the  pro¬ 
gram  was  interrupted,  in  this  case  at 
the  start  of  the  routine  InitUMenuSetup , 
which  is  in  segment  number  10.  The 
second  line  is  the  debugger’s  command 
prompt.  Commands  in  the  MacApp  de¬ 
bugger  are  issued  by  typing  a  single 
character.  At  any  debugger  prompt,  the 
characters  accepted  appear  within  brack¬ 
ets;  typing  a  question  mark  displays  a 
description  of  each  command. 

3.  Type  x,  then  r.  This  causes  MacApp 
to  report  via  the  debugger  window  each 
time  the  amount  of  memory  used  by 
code  and  system  resources  surpasses 
the  previous  maximum. 

4.  Type  x,  then  b.  This  causes  MacApp 
to  also  interrupt  the  program  each  time 
the  previous  maximum  is  surpassed. 

5.  Type  g  to  resume  execution  of  the 
program.  It  will  be  interrupted  immedi¬ 
ately  with  the  debugger  window  show¬ 
ing  a  message  similar  to  that  in  Exam¬ 
ple  1. 

This  indicates  that  a  new  all-time 
high  has  been  achieved  in  the  amount 
of  memory  required  for  code  and  sys¬ 
tem  resources.  Each  time  a  new  high 
is  achieved,  the  program  will  be  inter¬ 
rupted  and  this  message  displayed. 
Now,  as  soon  as  you  type  g  to  resume 
the  application,  this  will  probably  hap¬ 
pen  again.  In  fact,  this  may  happen 
several  times  until  the  application  gets 
to  the  point  where  it’s  waiting  for  a 
user  event. 

6.  Completely  exercise  the  program, 


How  the  Macintosh  System  Uses  an  Application’s  Heap 


The  Macintosh  system  uses  the  appli¬ 
cation’s  heap  for  many  purposes. 

It  doesn’t  notify  the  application  when 
this  happens,  and  if  there  isn’t 
enough  space  in  the  heap  for  the 
system’s  needs,  the  application  will 
bomb.  Here  are  the  most  common 
system  uses  of  the  application 
heap: 

1.  The  very  code  an  application  is  made 
of  gets  loaded  by  the  system  into  the 
application’s  heap  on  a  segment-by¬ 
segment  basis  whenever  a  routine  is 
called  in  a  segment  not  currently  in  the 
heap. 

2.  When  the  application  is  not  run  un¬ 
der  MultiFinder,  the  system  loads  vari¬ 
ous  system  resources  into  the  applica¬ 
tion’s  heap  when  the  application  uses 
them.  These  include; 


•  Defprocs  (short  for  definition  pro¬ 
cedures),  which  implement  the  ba¬ 
sic  low-level  behavior  of  windows, 
controls,  and  menus.  They  take 
the  form  of  WDEF,  CDEF ,  and 
MDEF  resources,  respectively.  There 
are  also  LDEF  resources  for  the  List 
Manager. 

•  Packages,  which  are  collections  of 
code  akin  to  libraries  and  get  loaded 
into  the  application’s  heap  when¬ 
ever  the  application  requires  their 
services.  In  most  cases  the  interface 
to  the  routines  in  a  package  pro¬ 
vides  no  clue  that  those  routines  are 
in  fact  in  a  package.  For  example,  a 
simply  utility  such  as  NumToString 
for  converting  integers  to  strings  is 
contained  in  the  Decimal-to-Binary 
package. 

•  Fonts  used  by  your  application  that 


are  not  in  ROM.  Fonts  appear  as  FONT 
and  FOND  resources,  and  they  can 
take  up  quite  a  bit  of  space. 

3.  The  system  uses  the  application’s 
heap  for  short  periods  to  maintain 
various  data  structures.  These  uses 
include  temporary  regions  for  Quick¬ 
Draw  operations,  the  creation  of  file 
lists  for  Standard  File  dialogs,  saving 
the  screen  bits  behind  a  pull-down 
menu,  and  the  allocation  of  data  struc¬ 
tures  for  printing. 

4.  If  the  application  is  not  run  under 
MultiFinder,  then  desk  accessories  use 
the  application’s  heap  for  their  mem¬ 
ory  requirements.  Even  worse,  ill- 
behaved  desk  accessories  can  leave 
handles  in  your  heap  and  there’s  noth¬ 
ing  you  can  do  about  it! 

—  C.B. 
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trying  all  its  commands  and  options. 
What  you’re  trying  to  do  is  find  the  one 
point  in  the  application  that  requires 
the  greatest  amount  of  code  and  sys¬ 
tem  resources.  For  many  applications 
this  occurs  at  program  start-up  (when 
the  user  double-clicked  a  document) 
when  printing,  or  when  quitting  and 
saving  a  document.  Of  course,  this  will 
vary  greatly  depending  on  the  nature 
of  the  application,  and  you  should  thor¬ 
oughly  exercise  your  program  to  make 
sure  you’ve  found  the  right  place. 

7.  Now  that  you  know  where  the  high 
point  is,  run  the  program  again  using 
the  procedure  just  described  and  cause 
the  known  high  point  to  be  reached. 
When  the  program  is  interrupted  at  this 
point,  type  the  following  commands 
into  the  debugger:  h,  then  s.  This  pro¬ 
duces  a  list  of  the  code  segments  in  use 
at  the  time  and  looks  similar  to  Exam¬ 
ple  2.  (You  can  move  and  resize  the 
debugger  window  in  order  to  see  the 
complete  list.)  This  list  shows  the  set 
of  segments  that  should  be  included 
in  the  seg!  resources.  A  dot  in  front  of 
a  segment  name  indicates  the  segment 
is  resident  and  is  always  in  memory. 
An  L  in  front  of  the  name  indicates  the 
segment  is  locked  in  memory  because 
it’s  currently  in  use.  Note  that  other 
segments  may  be  in  memory  too,  but 
because  they’re  not  in  use  (and  could 
be  purged  from  memory  if  necessary) 
they’re  not  shown.  (A  list  of  all  seg¬ 
ments,  in  memory  or  not,  can  be  shown 
by  typing  h  and  Option-s.) 

You  can  either  write  these  down  or 
dump  the  list  to  a  text  file  using  the 
debugger’s  output  redirection  feature. 
This  is  done  by  typing  o,  then  a  file 
name  such  as  Segment  Listing.  Type  y 
to  the  prompt  after  entering  the  file 
name  to  cause  debugger  output  to  be 
displayed  in  the  window  while  it  is 
written  to  the  text  file.  Then  type  h  and 
s  to  list  the  segments  again.  This  time 
the  list  is  copied  to  the  text  file.  Type  o 
to  close  the  output  redirection  file,  and 
quit  the  application  (by  typing  q  in  the 
debugger). 

With  the  list  of  segments  in  hand,  it’s 
a  simple  matter  to  add  your  own  seg! 
resource  to  the  application.  Make  sure 
you  assign  it  a  resource  ID  of  256  or 
greater  as  anything  less  than  256  is 
reserved  by  MacApp.  Also,  list  only 
those  segments  that  do  not  appear  in 
MacApp’s  seg!  lists.  Repeating  a  seg¬ 
ment  causes  MacApp  to  reserve  space 
for  it  each  time  it  occurs  in  a  seg! list. 

Accounting  for  Noncode  Usage  (or  How 
to  Use  mem!  Resources) 

As  mentioned  earlier,  mem!  resources 
can  be  used  to  increase  the  size  of  the 
temporary  reserve.  Actually,  each  mem! 


resource  consists  of  three  numbers,  effect.  In  such  a  low-memory  situation, 
MacApp  2.0b9’s  mem!  resources  are  your  application  should  prevent  the 
shown  in  Listing  Three,  page  28.  Like  user  from  performing  any  operations 
seg!  resources,  there  can  be  as  many  that  add  to  the  application’s  memory 
mem!  resources  as  needed.  requirements.  MacApp’s  mem! resources 

The  first  value  of  each  mem! resource  reserve  4K  for  emergency  use.  You  can 
is  added  to  the  size  of  the  temporary  add  more  if  necessary, 
reserve.  This  lets  you  account  for  non-  The  third  values  of  the  mem!  re¬ 
code  temporary  requests,  such  as  sys-  sources  are  summed  to  determine  the 

tern  resources  or  system-allocated  tern-  amount  of  space  for  the  application’s 
porary  data  structures  used  for  things  stack,  in  addition  to  the  8K  automati- 
such  as  printing  or  perhaps  complex  cally  reserved  by  the  Memory  Manager, 
region  manipulation.  MacApp  includes  If  you  need  a  bigger  stack,  say  because 
three  mem!  resources  of  its  own.  The  you’re  passing  large  data  structures  as 
result  is  that  4K  is  always  allocated  for  parameters  or  defining  them  as  local 
the  temporary  reserve,  an  additional  variables  in  procedures,  you  can  do 
40K  is  added  if  the  application  prints,  so  by  supplying  the  additional  amount 
and  another  2K  is  added  if  MacApp’s  in  a  mem!  resource.  You  can  also  de¬ 
debugger  is  included.  Your  mem!  re-  crease  the  stack  space  by  using  a  nega- 
source  can  reserve  additional  space  if  tive  number.  Normally,  it  isn’t  neces- 
necessary  to  account  for  things  like  sary  to  change  the  size  of  the  stack, 
fonts,  or  it  may  not  need  to  add  any¬ 
thing  to  this  total.  (It  may  take  some  gApplMemList  and  gApp2MemList 
work  to  determine  empirically  how  The  lists  gApplMemList  and  gApp2- 
much  your  application  needs.  Of  course,  MemList  were  described  previously  as 
the  more  you  reserve,  the  safer  you  are.)  containing  handles  considered  to  be 
MacApp  sums  the  second  values  of  temporary  and  subject  to  MacApp’s  con- 
each  mem!  resource  to  determine  the  trol.  The  difference  between  the  two 
size  of  a  handle  that  reserves  memory  is  that  handles  in  gApplMemList  are 
for  emergency  use.  The  emergency  re-  purged  before  those  in  gApp2MemList. 
serve  was  alluded  to  in  the  algorithm  Typically  the  handles  put  in  these  lists 
for  MacApp’s  grow  zone  function.  As  are  for  resources.  For  example,  you 
its  name  implies,  this  handle  is  purged  may  want  to  add  the  handles  to  font 
by  the  grow  zone  function  as  a  last  resources  to  gApp2MemList  so  that  the 
resort,  when  all  other  avenues  have  fonts  stay  in  memory  for  as  long  as 
been  exhausted.  By  definition,  once  possible. 

this  reserve  is  emptied,  the  application  Normally  these  lists  aren’t  used.  If 
is  in  a  low-memory  situation,  and  you  want  to  use  one  of  them,  you  must 
MacApp  will  display  an  alert  to  that  first  create  the  list  and  then  assign  han- 

=  =  New  maximum  resources  usage:  211884  =  = 
stopped  at  Break  CHECKRSRCUSAGE  Seg*:  1 
Command  [  BCDEFG HILMNOPtcQRS p  WX'l: 


Example  1:  Breaking  into  the  MacApp  debugger 


Command  [  JBCDEFGHILMOPrtQRS  P  ,TWX?]:  H 

Heap/Stack  Cmd  [+BDIMRSP?]:  S 

Total  *  segments  =  32 

•  =  resident,  L  =  loaded 

$0008A22C  Seg#:  1» 

Main 

24584  bytes 

S0008A184  Seg#:  4« 

GDebug 

10288  bytes 

$0008A18C  Seg#:  6* 

GNonRes 

10004  bytes 

S0008A190  Segt:  !• 

GFields 

16012  bytes 

$0008.41 9C  Seg#:  10  L 

GInit 

6984  bytes 

50008A1A0  Seg#:  11  • 

GInspector 

15600  bytes 

S0008A1A4  Segt:  12  L 

GOpen 

16640  bytes 

50008A1AC  Segt:  14  L 

GSelCommand 

9060  bytes 

$0008A1BC  Seg#:  18  • 

BBRes 

228  bytes 

SOOO8A1C0  Seg#:  19  • 

GWriteLn 

16224  bytes 

50008A1C4  Seg#:  20  • 

GDebugger 

28932  bytes 

S0008A1C8  Seg#:  21  • 

GPerformanceTools 

5988  bytes 

S0008A1CC  Segt:  22  • 

GMain 

11436  bytes 

$0008A1D8  Seg#:  25  • 

GRes 

31700  bytes 

$0008a1DC  Seg#:  26  • 

ARes 

6016  bytes 

$OOOBA1EO  Seg#:  27  • 

%  MethTables 

10940  bytes 

Total  loaded  code  =  220764 

Current  temp  space:  locked  =  220764,  unlocked  =  0,  total  =  220764 

Command  [  JBCDEFGHILMOPttQRSPTWX?]:  O 

Example  2:  An  example  of  the  segment  list  displayed  by  MacApp ’s  debugger 
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MEMORY  MANAGEMENT 


dies  to  it  with  MacApp’s  AddHandle 
routine: 

gApplMemList  := 

HHandle  List(NewHandle(0)); 
AddHandle(aResource, 

gApplMemList); 


Handling  Low-Memory  Conditions 

A  MacApp  program  is  considered  to 
be  in  a  low-memory  condition  when 
its  emergency  reserve  handle  cannot 
be  allocated.  In  this  condition  there 
will  still  be  some  free  memory  in  the 
heap,  giving  the  application  a  little  breath¬ 


ing  room.  In  fact,  the  larger  the  emer¬ 
gency  reserve,  the  more  memory  is  in 
a  low-memory  condition.  Even  in  a 
low-memory  condition,  the  application 
can  continue  to  request  memory  and 
the  Memory  Manager  will  oblige  until 
every  last  byte  of  the  heap  is  allocated. 
After  that,  further  requests  will  cause 
the  program  to  bomb. 

Consequently,  whenever  the  program 
is  in  a  low-memory  condition,  it  is  im¬ 
portant  that  it  not  perform  any  opera¬ 
tions  that  increase  its  memory  usage. 
To  that  end,  MacApp  automatically  dis- 


Commands  that 
reduce  the  memory 
burden  should  be 
enabled 


plays  an  alert  informing  the  user  of  the 
condition  and  disables  the  New  and 
Open  commands.  You  should  take  simi¬ 
lar  precautions  of  your  own.  To  find 
out  if  the  application  is  low  on  mem¬ 
ory,  call  MacApp’s  MemSpacelsLow func¬ 
tion.  If  it  returns  true,  then  you  should 
disable  any  operations  that  increase 
the  memory  burden  of  the  program. 
Obviously,  any  commands  that  add  data 
to  a  document,  such  as  Paste,  should 
be  disabled. 

On  the  other  hand,  commands  that 
reduce  the  memory  burden  should  be 
enabled,  particularly  the  Clear  com¬ 
mand.  The  Cut  command  may  not  be 
effective  in  a  low-memory  condition 
because  it  sometimes  increases  the  use 
of  memory.  This  is  because  in  addition 
to  copying  data  from  a  document  or 
view  to  the  Clipboard,  MacApp  makes 
a  copy  of  the  existing  Clipboard  to 
make  the  Cut  undoable. 

Provided  enough  space  has  been  re¬ 
served  for  temporary  requests,  a  low- 
memory  condition  will  only  affect  per¬ 
manent  requests  (because  MacApp  re¬ 
leases  its  temporary  reserve  for  tempo¬ 
rary  requests  but  not  for  permanent 
ones).  Thus,  MacApp’s  strategy  is  geared 
toward  the  ultimate  failure  of  perma¬ 
nent  requests  as  the  user  fills  up  mem¬ 
ory,  so  it’s  important  to  test  the  result 
of  every  permanent  request  to  verify  its 
success.  Two  MacApp  routines  are  use¬ 
ful  for  this  purpose:  FailNIL  and  Fail- 
MemError. 

FailNIL  has  a  single  parameter,  which 


Listing  One 


Fragment  1:  aHandle  :=  NewPermHandle (100) ; 

anotherHandle  :=  NewPermHandle (200) ; 


Fragment  2  : 


wasPermanent: 


wasPermanent  :=  PermAllocation (TRUE) ;  (Subsequent  requests  are  permanent  ) 
aHandle  :=  NewHandle(lOO) ;  (Both  NewHandle  calls  are  considered) 

anotherHandle  :=  NewHandle (200) ;  (permanent  because  perm,  flag  is  set) 

wasPermanent  :=  PermAllocation (wasPermanent) ;  {  Restore  state  of  the  flag  ) 


End  Listing  One 


Listing  Two 

resource  'seg!'  (kBaseMacApp, 
#if  qNames 

"BaseMacApp", 

#endif 

purgeable)  ( 

(  "Main"; 

"GMain"; 

"ARes"; 

"GRes"; 

"BBRes"; 

"%_MethTables"; 

#if  qlnspector  &&  IqDebug 
"GDebug"; 
"GInspector"; 
"GWriteLn"; 

"GFields" 

#endif 

#if  qPerform 

"GPerf ormanceTools" ; 

#endif 


); 


}; 


End  Listing  Two 


Listing  Three 

resource  'mem!'  (kBaseMacApp 
#if  qNames 

"BaseMacApp", 

#endif 

purgeable)  ( 

4096, 

4096, 

8192 


//  Add  to  temporary  reserve 
//  Add  to  permanent  reserve 
//  Add  to  stack  space  (actually  this  first 
//  one  sets  the  base  stack  requirement  to 
//  be  the  same  as  for  a  Macintosh  Plus) . 


resource  'mem!'  (kPrinting, 
#if  qNames 

"kPrinting", 

lendif 

purgeable)  ( 

43  *  1024, 


//  Add  to  temporary  reserve 
//  Add  to  permanent  reserve 
//  Add  to  stack  space 


resource  'mem!'  (kForDebugging, 
#if  qNames 

"F  orDebuggi ng " , 

#endif 

purgeable)  ( 

2048, 

0, 

0 


//  Add  to  temporary  reserve 
//  Add  to  permanent  reserve 
//  stack  space 


End  Listings 
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is  a  handle,  object,  or  pointer.  If  the 
parameter  is  NIL ,  then  FailNIL  signals 
failure.  FailNIL  can  be  used  to  test  the 
result  of  NEW,  NewHandle,  NewPerm- 
Handle,  NewPtr,  and  NewPermPtr ,  be¬ 
cause  each  of  these  returns  NIL  if  there 
isn’t  enough  space  to  complete  the  al¬ 
location. 

FailMemError can  be  used  to  test  the 
result  of  any  Memory  Manager  routine. 
It  signals  failure  if  the  value  of  the 
Memory  Manager’s  MemError  function 
returns  a  nonzero  value.  MemError  re¬ 
turns  the  result  of  the  last  Memory  Man¬ 
ager  routine  that  was  called.  This  is 
useful  for  testing  the  result  of  SetHan- 
dleSize,  SetPermHandleSize,  SetPtrSize , 
and  SetPermPtrSize. 

Conclusion 

Some  people,  when  they  see  the  amount 
of  work  that’s  gone  into  MacApp’s  mem¬ 
ory  management  scheme,  wonder 
whether  it’s  really  necessary.  The  fact 


is  that  if  you  want  to  build  a  truly 
robust  Macintosh  application,  then  a 
strategy  of  some  sort  is  necessary  to 
address  the  problems  described  in 
this  article.  By  using  MacApp,  or  its 
memory  management  scheme,  your 
application  has  a  proven  strategy  in 
place  that’s  relatively  easy  to  take  ad¬ 
vantage  of. 
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VISUAL 

OBJECT-ORIENTED 

PROGRAMING 


Standard  C  with  home  brewed 
OOP  features 


raphical,  direct-manipulation 
interfaces  are  quickly  becom¬ 
ing  the  standard  for  today's 
software.  Object-oriented  pro¬ 
gramming  (OOP)  techniques  can  be 
naturally  applied  to  such  interfaces,  be¬ 
cause  the  on-screen  objects  that  users 
see  and  manipulate  can  be  directly  and 
conveniently  implemented  as  abstract 
objects  in  an  OOP  language. 

LabView  is  a  program  with  just  such 
an  interface.  It  is  a  visual  programming 
and  execution  environment  for  data 
acquisition  and  laboratory  automation. 
Functions  are  wired  together  in  Lab- 
View’s  diagrammatic,  dataflow  language 
to  produce  executable  programs.  Gra¬ 
phical  display  objects  provide  both  in¬ 
teractive  and  programmatic  input  and 
output  for  the  functions.  (See  Dr  Dobb 's 
Software  Engineering  Sourcebook,  Win¬ 
ter  1988,  28-35  for  a  more  detailed 
description  of  LabView.)  While  LabView 
itself  is  not  an  OOP  environment,  our 
implementation  of  Version  2  of  LabView 
is  very  much  object-oriented. 

One  thing  noteworthy  about  the 
LabView  object-oriented  implementation 
is  that  the  language  is  standard  C-fla- 
vored  but  incorporates  our  own  home 
brewed  OOP  mechanisms.  This  article 


Rob  is  a  software  engineer  at  National 
Instruments  and  a  member  of  the 
LabView  2. 0  development  team.  He  can 
be  reached  at  12109  Technology  Blvd., 
Austin,  TX  78727. 


Rob  Dye 

describes  these  mechanisms  —  how  they 
were  implemented,  how  messages  are 
dispatched,  how  inheritance  is  achieved, 
and  how  objects  are  represented. 

Why  Not  a  Real  OOP  Language? 

Why  don't  we  just  use  a  real  OOP 
language  to  reap  OOP  benefits?  Funda¬ 
mentally  because  when  development 
began  on  LabView  2.0  in  mid-1987,  no 
high-performance  OOP  language  was 
available  on  the  Mac.  Several  OOP  en¬ 
vironments  have  since  become  avail¬ 
able,  yet  we  still  feel  our  OOP  im¬ 
plementation  has  advantages  over  these 
others.  By  building  our  own  OOP  fea¬ 
tures  into  standard  C,  we  have  the  free¬ 
dom  to  buy  into  as  much  object-orien¬ 
tedness  as  we  need  and  can  afford. 
We  can  leave  out  those  features  that 
we  feel  negatively  affect  performance, 
and  yet  build  in  and  fine-tune  those 
that  we  feel  are  worth  the  price  of 
implementing. 

Our  implementation  of  LabView  2.0 
embodies  two  OOP  concepts:  1.  The 
close  binding  of  objects  with  the  meth¬ 
ods  that  operate  on  them,  and  2.  the 
code-sharing  framework  accorded  by 
inheritance.  These  concepts  are  mani¬ 
fested  in  several  features:  A  concise 
way  of  sending  messages  to  objects 
and  an  inconspicuous  dispatcher  for 
those  messages;  a  mechanism  enabling 
a  class  to  automatically  inherit  meth¬ 
ods  from  its  superclass;  and  a  class 
hierarchy  that  can  be  traversed  at  run 


time  by  a  second  dispatcher  to  allow  a 
class  to  forward  messages  to  its  super¬ 
class.  In  implementing  these  features, 
we  generally  optimized  for  speed  rather 
than  space. 

Together,  these  features  give  us  al¬ 
most  all  the  benefits  that  any  real  OOP 
language  offers.  A  few  features  are  miss¬ 
ing,  though.  We  have  no  true  data  en¬ 
capsulation  because  it  must  be  pro¬ 
vided  by  the  language,  and  C’s  file 
scoping  and  #include  files  are  minimal 
encapsulation  features.  Garbage  col¬ 
lection  is  sometimes  listed  as  a  feature 
of  OOP  languages.  It  is  not  a  feature 
of  our  architecture  - —  our  objects  are 
responsible  for  cleaning  up  after  them¬ 
selves.  This  is  in  keeping  with  the  C 
philosophy  that  the  programmer  re¬ 
tains  all  the  power,  not  to  mention  all 
the  responsibility. 

A  class  browser  like  the  one  in  Small¬ 
talk,  although  certainly  not  a  require¬ 
ment  for  an  OOP  language,  would  be 
a  nice  tool  for  managing  our  large  col¬ 
lection  of  classes.  To  perform  this  task, 
we  use  a  group  of  tools  that  treat  the 
OOP  system  as  a  matrix,  with  classes 
labeling  rows  and  messages  labeling 
columns.  (See  the  accompanying  box, 
“Managing  Class  Attributes,”  for  a  dis¬ 
cussion  of  these  method  table  tools.) 

The  Programmer's  View 

These  OOP  mechanisms  give  us  a  more 
powerful  language  to  work  with,  but 
its  successful  use  hinges  on  program- 
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mer  discipline.  Therefore,  before  get¬ 
ting  into  the  details  of  the  implementa¬ 
tion,  we’ll  describe  how  these  features 
appear  to  the  programmer.  For  the  most 
part,  they  look  like  the  familiar  features 
of  the  C  language. 

The  template  that  defines  an  object’s 
instance  variables  is  created  through 
the  use  of  nested  macros,  where  the 
nesting  mirrors  the  class  ancestry  of  the 
object.  See  Listing  One  (page  35)  for 
an  example  adapted  from  LabView’s 


source  code.  The  example  shows  the 
definition  of  object  fields  for  a  class 
hierarchy  four  layers  deep;  the  classes 
shown  are  involved  in  the  display  of 
input  and  output  values  to  functions. 
Figure  1  depicts  the  logical  relation¬ 
ships  between  these  classes,  and  Fig¬ 
ure  2  shows  how  some  instances  are 
graphically  represented  in  LabView. 

At  the  root  of  the  hierarchy  is  the 
data  display  object  (DDO).  Front  panel 
DDOs  inherit  all  of  their  fields  by  nest¬ 


ing  the  DDO_ClassFields  macro  within 
the  FPDDO_ClassFields  macro,  and  then 
supplying  a  few  new  fields  of  their 
own.  These  two  classes  are  examples 
of  abstract  classes  because  no  object 
instances  of  these  classes  are  ever  actu¬ 
ally  created;  their  purpose  is  to  provide 
a  base  class  from  which  many  sub¬ 
classes  may  inherit  certain  methods. 

Numeric  display  objects  inherit  all 
the  fields  of  the  FPDDO  class  and  sup¬ 
ply  those  fields  specific  to  numbers, 
such  as  the  numeric  representation,  a 
digital  display  object,  and  its  range  of 
valid  numbers. 

Finally,  we  see  the  actual  structure 
definition  of  several  objects  with  three 
typedefs.  The  standard  numeric  display 
object  is  defined  simply  in  terms  of  the 
NumericDDO_ClassFields.  The  Knob  dis¬ 
play  object  inherits  all  those  fields,  plus 
some  information  relating  to  its  graphi¬ 
cal  depiction  and  the  scale  around  its 
perimeter.  The  StringDDO  inherits  from 
the  FPDDO  and  adds  fields  necessary 
for  displaying  text. 

Once  a  template  for  a  class  has  been 
defined,  the  programmer  must  be  able 
to  refer  to  an  object  of  that  class.  In 
LabView,  the  objects  allocated  for  a 
single  document  (called  a  “virtual  in¬ 
strument”)  are  contained  within  a  data 
structure  called  an  ObjHeap.  A  particu¬ 
lar  object  is  therefore  referred  to  unam¬ 
biguously  by  a  pair  of  values:  A  handle 
(a  doubly  indirect  pointer)  to  an 
ObjFleap  and  an  ObjID.  The  ObjHeap 
is  a  relocatable,  dynamically  sized  block 
of  memory  in  which  objects  are  allo¬ 
cated.  An  object’s  ObjID  is  its  offset 
from  the  beginning  of  its  ObjHeap.  (Han¬ 
dles  and  memory  management  are  dis¬ 
cussed  later  in  this  article.) 

Because  a  pair  of  values  is  used  to 
refer  to  an  object,  accessing  an  object’s 
field  requires  dereferencing  the  heap’s 
handle,  then  adding  the  offset  to  yield 
a  pointer  to  the  object’s  structure. 
Macros  are  used  to  perform  these  two 
steps  in  a  consistent  way  for  each  class. 
The  definition  of  Knobldr  in  Listing  One 
is  an  example  of  such  a  macro.  Exam¬ 
ple  1  shows  an  example  of  its  use. 

Another  implication  of  this  two-value 
identifier  is  that  all  messages  must  take 
at  least  two  arguments:  An  ObjHeap 
handle  and  an  ObjID.  It  does  not  nec¬ 
essarily  mean  that  all  stored  references 
(such  as  one  object  holding  a  link  to 
another)  need  to  have  both  values,  be¬ 
cause  the  ObjHeap  is  usually  known 
by  the  context.  In  LabView,  the  vast 
majority  of  inter-object  links  are  within 
the  same  ObjHeap. 

One  of  the  features  most  visible  to 
the  programmer  is  the  syntax  for  send¬ 
ing  messages.  The  message  is  not  an 
explicit  argument  to  a  function  called, 


Data  Display  Object 


Front  Panel  DDcP>  CgSer  classjj^ 


CJStringDDCPjP  CNumericDDCT) 


Cj<nobDDcPb 


Figure  1:  The  class  hierarchy  corresponding  to  the  definitions  in  Listing  One. 
Arrows  indicate  superclass  relationship 


a  KnobDDO 


This  is  a 
StringDDO. 


a  StdNumericDDO 


0.0000 

-1.000 


\ 

1.0000 


0.0000 


Figure  2:  The  graphical  representation  in  LabView  of  three  of  the  classes 
shown  in  Figure  1 


Figure  3:  Memory  organization  and  the  structure  of  an  object 
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say,  MsgDispatcb,  rather,  the  message 
is  the  actual  name  of  the  function  that 
is  called.  The  message  is  therefore  em¬ 
phasized,  not  the  dispatching  mecha¬ 
nism.  For  example,  to  send  a  message 
asking  an  object  to  copy  itself,  you 
would  write  code  like  this: 

theCopy  =  oCopy(h,  o,  .  .  .); 

The  name  of  the  function  or  method 
that  actually  gets  invoked  need  not  be 
known  by  the  programmer,  and  fre¬ 
quently  it  isn't  known.  The  ultimate 
destination  is  determined  by  the  class 
of  the  object  described  by  the  first  two 
arguments  to  the  message.  The  O  (for 
object)  at  the  beginning  of  the  message 
name  is  a  convention  used  to  signal 
those  reading  the  code  that  this  is  no 
ordinary  function  call.  (It  also  gives  mi¬ 
nor  amusement  to  those  who  read  the 
message  names  as  holy  incantations.) 

A  similar  syntax  is  used  for  forward¬ 
ing  a  message  to  an  object’s  superclass: 

theCopy  =  supCopy(myClass,h,  o, .  . .); 

The  extra  argument  myClass  is  used 
so  that  the  message-dispatching  mecha¬ 
nism  can  correctly  crawl  up  the  class 
hierarchy  tree  to  the  parent  class.  This 
mechanism  is  more  complex  than  that 


used  for  normal  messaging,  and  space 
considerations  do  not  permit  its  de¬ 
scription  in  this  article. 

Writing  a  method  is  no  different  from 
writing  any  other  function  in  C.  The 
method  names,  however,  adhere  to  a 
convention  so  that  the  names  can  be 
automatically  generated  by  the  method 
table  tools.  The  name  is  generated  by 
the  concatenation  of  the  name  of  the 
class  to  which  they  belong;  the  charac¬ 
ter  O,  the  name  of  the  message  to  which 
this  method  responds;  and  the  word 
Method.  Example  2  shows  such  a 
method. 

Memory  Management  of  Objects 

As  mentioned  earlier,  object  instances 
(Figure  3)  physically  reside  in  a  data 
structure  called  an  ObjHeap  (. shown  in 
the  middle  of  the  figure).  ObjHeaps 
themselves  reside  in  a  data  structure, 
defined  by  the  Macintosh  Memory  Man¬ 
ager,  called  a  “zone”  (shown  at  the 
right  side  of  the  figure).  ObjHeaps  are 
relocatable  blocks  of  memory  that  must 
be  accessed  through  a  nonrelocatable 
master  pointer.  Only  one  master  pointer 
exists  for  each  relocatable  block  in  a 
zone,  and  it  belongs  to  the  Memory 
Manager.  When  the  block  must  be  re¬ 
located,  the  Memory  Manager  updates 
the  master  pointer  to  point  to  the  block's 


new  location.  All  other  references  to 
the  block  are  handles  —  pointers  to 
the  master  pointer  —  thus,  we  have  dou¬ 
ble  indirection.  This  arrangement  al¬ 
lows  the  Memory  Manager  to  compact 
the  zone  by  moving  all  the  relocatable 
blocks  to  one  end  of  the  zone  when  it 
becomes  fragmented  from  numerous 
allocations  and  deallocations. 

ObjHeaps,  therefore,  live  in  the  do¬ 
main  of  the  Macintosh  Memory  Man¬ 
ager.  Objects  within  LabView  live  in 
the  domain  of  the  ObjHeap  Manager. 
LabView's  ObjHeap  Manager  takes  care 
of  object  allocation  and  deallocation 
within  ObjHeaps.  At  first  glance,  this 
extra  layer  of  memory  management  soft¬ 
ware  may  seem  to  be  a  source  of  ex¬ 
traordinary  overhead,  but  it  actually  re¬ 
sults  in  a  significant  increase  in  per¬ 
formance. 

One  of  the  lessons  we  learned  (the 
hard  way)  from  developing  LabView 
1.0  was  that  the  performance  of  the 
Mac  Memory  Manager  begins  to  de¬ 
grade  severely  when  the  number  of 
blocks  allocated  in  a  zone  gets  to  be 
more  than  a  couple  of  thousand.  This 
is  because  allocation  of  a  new  block 
may  require  searching  extensively 
through  a  fragmented  zone  before  find¬ 
ing  a  free  block  large  enough  to  satisfy 
the  memory  request.  If  such  a  block 
can’t  be  found,  the  zone  must  be  com¬ 
pacted  and  the  search  restarted. 

All  of  the  OOP  languages  that  have 
become  available  recently  on  the  Mac 
(the  Object  Pascal  environments,  Think 
C  4.0,  and  the  soon-to-be  released  MPW 
C++)  make  the  same  mistake  we  made 
in  LabView  1.0;  each  object  is  allocated 
in  its  own  pointer  or  handle  block. 
Some  ambitious  programs  written  in 
LabView  may  require  as  many  as  50 
linked  documents  totaling  tens  (per¬ 
haps  hundreds)  of  thousands  of  ob¬ 
jects.  Our  heavy  reliance  on  the  Mac 
Memory  Manager  degraded  all  aspects 
of  performance  that  relied  on  memory 
allocation,  even  drawing.  Other  OOP 
languages  that  rely  on  the  Memory  Man¬ 
ager  can  be  expected  to  run  into  the 
same  problems. 

Adding  an  extra  layer  of  memory 
management  improves  the  performance 
of  both  layers.  Each  layer  has  to  deal 
with  fewer  numbers  of  blocks.  And 
because  the  lowest  layer  of  object  man¬ 
agement  is  our  own,  we  are  free  to 
tweak  the  ObjHeap  Manager  to  en¬ 
hance  performance.  As  mentioned  ear¬ 
lier,  we  avoided  the  framework  im¬ 
posed  by  an  OOP  language  in  order 
to  keep  this  kind  of  freedom. 

Another  advantage  of  ObjHeaps  has 
to  do  with  saving  all  the  objects  of  a 
document  to  disk.  As  explained  earlier, 
a  virtual  instrument  is  in  large  part  made 


Managing  Class  Attributes 


During  the  development  of  a  large 
object-oriented  system,  class  hierar¬ 
chies  and  message  protocols  are  fre¬ 
quently  changed.  OOP  languages  gen¬ 
erally  have  mechanisms  that  ease  these 
modifications  —  Smalltalk's  Browser 
is  perhaps  the  best  example  of  such 
a  mechanism.  With  LabView,  we  had 
to  invent  our  own  mechanisms  exter¬ 
nal  to  the  language,  all  of  which  de¬ 
pend  on  a  spreadsheet  that  contains 
a  matrix  of  objects  and  messages. 

This  spreadsheet,  which  we  call  the 
method  database,  is  essentially  a  primi¬ 
tive  browser.  Each  row  defines  a  class, 
each  column  an  attribute  of  the  class. 
The  various  attributes  are  the  class’s 
name,  its  superclass’s  name,  the  name 
of  the  typedef  that  defines  its  objects’ 
fields,  and  so  on.  In  addition  to  these 
attributes  there  is  a  column  for  every 
message  in  the  system.  The  entry  at 
the  intersection  of  a  class  and  a  mes¬ 
sage  tells  whether  the  class  defines  its 
own  method  for  that  message,  inher¬ 
its  a  method  from  its  superclass,  re¬ 
sponds  with  an  ErrorMethod,  or  uses 
a  function  with  a  special  name. 

A  program  that  we  wrote  reads  the 
text  version  of  this  spreadsheet  file 


and  generates  from  it  six  source  code 
files  (as  well  as  a  number  of  includes) 
that  are  compiled  into  LabView.  These 
files  include  all  the  class  initialization 
functions  for  all  the  built-in  classes 
in  LabView,  as  well  as  a  function  that 
calls  them  in  the  correct  order  to  as¬ 
sure  that  no  class  is  initialized  before 
its  superclass.  It  also  generates  the 
message  glue  functions  and  the  in¬ 
dexes  into  the  defProc  method  pointer 
tables  for  each  message  selector. 

Modifications  to  the  method  data¬ 
base,  such  as  introducing  a  new  mes¬ 
sage  or  a  new  object,  or  changing  an 
object’s  response  to  a  message  from 
inheriting  a  method  to  overriding  with 
its  own  method,  are  sufficiently  infre¬ 
quent  that  the  following  three-step 
process  is  not  too  much  of  a  hassle. 
1.  Modify  the  spreadsheet  and  save 
as  text.  2.  Run  the  source  code  gen¬ 
erator.  3-  Remake  all  the  necessary 
files.  One  can  easily  imagine  a  pro¬ 
gram,  however,  that  not  only  would 
allow  browsing  in  an  easier  way,  but 
also  would  generate  the  required 
source  code.  So  much  code  to  write, 
so  little  time. 

—  R.D. 
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up  of  two  ObjHeaps.  Each  ObjHeap 
can  be  written  out  to  disk  as  a  single 
block.  Because  inter-object  references 
are  simply  offsets  within  an  ObjHeap 
and  not  memory  addresses,  the  refer¬ 
ences  need  not  be  encoded  or  trans¬ 
formed  in  any  way  to  survive  the  move 
to  disk  and  then  back  into  memory. 
This  goes  a  long  way  towards  achiev¬ 
ing  truly  persistent  objects,  that  is,  ob¬ 
jects  that  maintain  their  identity  and 
interrelationships  from  one  invocation 
of  the  program  to  another. 

One  disadvantage  of  maintaining  ob¬ 
jects  within  an  ObjHeap  is  the  expense 
of  calculating  a  pointer  to  an  object 
from  its  ObjHeap  handle  and  offset. 
This  disadvantage  is  somewhat  exacer¬ 
bated  by  the  fact  that  ObjHeaps  are 
relocatable,  which  means  that  a  pointer 
to  an  object  inside  an  ObjHeap,  once 
calculated,  can  go  stale  across  function 
calls,  which  can  cause  memory  reloca¬ 
tions.  Programmers  must  be  careful  to 
refresh  such  pointers  at  the  appropri¬ 
ate  times.  We  consider  this  a  minor 
penalty,  given  the  massive  global  sav¬ 
ings  in  memory  management.  Judicious 
use  of  register  variables  can  further  re¬ 
duce  the  penalty. 

Representation  of  Objects 

An  object  has  a  logical  extent  that  cor¬ 
responds  exactly  to  the  struct  that  de¬ 
fines  the  object’s  fields.  However,  an 
object's  physical  extent  is  larger  than  its 
logical  extent  by  three  32-bit  integers 
(plus,  perhaps,  a  few  bytes  of  internal 
fragmentation).  These  three  integers  are 
in  a  header  that  is  at  a  negative  offset 
from  the  logical  beginning  of  the  ob¬ 
ject.  They  contain  system  information 
that  is  normally  invisible  to  the  pro¬ 
grammer:  The  actual  physical  size  of 
the  object,  a  scratch  field,  and  a  pointer 


KnobDDORec  *k; 
k  =  KnobFtr (heap,  self ) ; 
k->knobFlags  1=  clockwiseFlag; 


Example  1:  Defining  the  macro 


KnobOCopyMethod(heap,  self,  I) 
OHHandl®  heap; 

ObjID  self? 

i" 

i" 


Example  2:  A  typical  method 


to  the  data  structure  representing  the 
class  of  which  the  object  is  an  instance. 

The  physical  size  of  the  object  is  the 
private  data  of  the  ObjHeap  Manager. 
The  scratch  field  is  used  both  by  the 
ObjHeap  Manager  (for  example,  during 
the  compaction  of  an  ObjHeap )  and 
by  objects  during  certain  message  pro¬ 
tocols  (for  example,  oCopy ,  oCompile ). 

The  pointer  to  the  class  data  struc¬ 
ture  is  the  most  important  field  for  our 
purposes  in  this  article.  It  is  the  link 
that  binds  the  object  to  its  methods. 

Functions  are  wired 
together  in  LabView’s 
diagrammatic,  dataflow 
language  to  produce 
executable  programs 


The  defProc 

All  the  defining  information  about  a 
class  is  held  in  a  data  structure  we  call 
a  defProc.  For  the  most  part,  it  is  a  table 
of  pointers  to  the  class? s  methods  that 
is  indexed  (not  searched)  by  message 
selectors.  defProcs  are  the  source  of  a 
space  trade-off  inherent  in  our  entire 
OOP  mechanism.  The  average  size  for 
a  defProc  is  about  600  bytes. 

At  the  beginning  of  the  defProc  is  the 
range,  which  is  the  maximum  selector 
value  allowed  for  this  class.  (See  Figure 
4.)  The  range  is  the  offset  in  the  defProc 
to  the  last  entry  in  the  table  of  method 
pointers  —  an  error-handling  method. 


Should  an  object  be  sent  a  message 
that  is  beyond  its  ken,  that  is,  a  mes¬ 
sage  selector  that  indexes  beyond  the 
end  of  its  method  table,  the  error¬ 
handling  method  is  invoked.  This 
method  performs  much  the  same  func¬ 
tion  as  does  the  doesNotUnderstand 
method  in  Smalltalk. 

Beyond  the  end  of  the  method  table 
in  the  defProc  is  a  fixed-length  structure 
containing  a  variety  of  information,  in¬ 
cluding  the  logical  size  of  an  instance 
of  this  class,  the  ASCII  name  of  the  class 
and  its  superclass,  and  a  pointer  to  the 
superclass’s  defProc.  The  pointer  to  the 
superclass’s  defProc  establishes  the  in¬ 
heritance  hierarchy  and  is  used  at  run 
time  to  route  superMessages. 

defProcs  for  LabView’s  built-in  classes 
are  created  and  initialized  at  LabView 
initialization  time,  not  by  the  compiler 
at  compile  time.  (The  reason  is  an  un¬ 
fortunate  limit  in  the  amount  of  static 
data  allowed  by  the  compiler.)  Classes 
may  also  be  defined  externally  to 
LabView;  their  defProcs  are  read  in  and 
initialized  the  first  time  an  object  of 
that  class  is  instantiated.  A  description 
of  how  external  classes  are  defined  is 
beyond  the  scope  of  this  article. 

One  of  the  steps  in  the  initialization 
of  a  defProc  establishes  the  inheritance 
of  all  methods  from  its  superclass’s 
defProc.  In  this  step,  all  the  method 
pointers  of  the  superclass  are  copied 
into  the  defProc  being  initialized.  Once 
the  pointers  are  copied,  the  class’s  ini¬ 
tialization  procedure  continues  by  pok¬ 
ing  the  addresses  of  its  own  methods 
into  the  appropriate  places  in  the  meth¬ 
od  table.  Because  inherited  methods 
are  copied  directly  into  the  subclass’s 
defProc ,  it  is  not  necessary  to  climb  up 
the  inheritance  tree  at  run  time  to  find 
the  class  that  defines  the  method. 


Figure  4:  Structure  of  a  defProc 
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You  might  think  that  generating  and 
maintaining  these  defProc  initialization 
procedures,  as  well  as  the  indexes  in 
the  table  for  each  method,  would  be 
quite  a  nightmare.  It  could  be,  if  you 
did  it  by  hand.  Our  method  table  tools 
automatically  regenerate  the  source 
code  for  these  initializers  whenever  a 
change  needs  to  be  made  in  a  class’s 
methods,  or  when  new  messages  are 
introduced. 

Message  Dispatching 

What  path  does  the  code  follow  in 
getting  from  the  point  of  sending  an 
object  a  message  to  the  actual  execu¬ 
tion  of  that  object’s  method?  The  path 
goes  through  two  functions:  One  could 
be  called  the  message  glue;  the  other  is 
the  message  dispatcher,  an  assembly  lan¬ 
guage  function  called  DefProcDispatch. 
Its  source  is  shown  in  Listing  Two. 

As  we  saw  earlier,  sending  a  mes¬ 
sage  actually  calls  a  function  with  the 
same  name  as  the  message  —  this  is 
the  message  glue  function.  These  func¬ 
tions  are  quite  small  (as  you  can  see  in 
Listing  Two),  and  their  source  is  auto¬ 
matically  generated  by  the  method  ta¬ 
ble  tools.  All  the  function  does  is  place 
its  message  selector  in  data  register  zero 
and  jump  to  DefProcDispatch. 

DefProcDispatch  knows  the  state  of 
the  stack  upon  entry.  When  the  mes¬ 
sage  was  originally  sent,  the  parame¬ 
ters  were  pushed  from  right  to  left  (as 
they  appear  in  the  source  code).  There¬ 
fore  the  most  recently  pushed  items 
on  the  stack  (besides  the  return  ad¬ 
dress)  are  the  objects  ObjID  and  han¬ 
dle  to  the  ObjHeap.  With  these  items, 
DefProcDispatch  generates  a  pointer 
to  the  object  being  sent  the  message 
and  retrieves  the  pointer  to  the  objects 
defProc  from  the  objects  header.  The 
message  selector  in  D03  is  compared 
to  the  range  at  the  beginning  of  the 
defProc  to  make  sure  that  the  defProc 
contains  an  entry  at  this  index  in  its 
method  table.  If  all  is  well,  the  method 
address  is  retrieved  from  the  table  and 
DefProcDispatch  jumps  to  it. 

One  of  the  nice  features  of  this  mecha¬ 
nism  is  that  all  message  traffic  goes 
through  DefProcDispatch.  Therefore,  it 
is  a  convenient  place  to  put  all  sorts  of 
debugging  hooks.  We  use  it  to  check 
the  validity  of  ObjHeap  and  ObjID  ar¬ 
guments,  and  to  count  messages  for 
performance  evaluation. 

Conclusion 

We  feel  the  benefits  of  object-oriented 
programming  are  substantial.  Extend¬ 
ing  and  modifying  existing  objects,  as 
well  as  experimenting  with  new  sub¬ 
classes,  is  quite  easy.  Building  in  our 
own  OOP  mechanisms  has  caused  a 


certain  amount  of  overhead  in  devel¬ 
opment  time.  We  had  to  spend  more 
time  on  mechanisms  rather  than  on  the 
code  that  actually  gets  the  job  done, 
but  we  feel  that  the  benefits  are  worth 
this  overhead. 

The  experience  of  both  building  and 
using  these  mechanisms  has  been  en¬ 
lightening.  We  have  all  come  to  a  greater 
appreciation  of  what  object-oriented 
programming  is  all  about  and  what  kind 
of  design  considerations  go  into  the 
making  of  an  OOP  language.  Certainly 
this  education  will  be  useful  to  us  as 
we  consider  the  development  of  future 
software. 
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I  Here’s  a  template  program  to 
get  you  started 

Bryan  Waters 


□  rogramming  on  the  Macintosh 
has  always  been  an  exercise 
in  research,  usually  requiring 
bits  of  information  from  a 
dozen  different  sources.  Device  drivers 
provide  a  good  example  of  this  pro¬ 
cess,  and  in  this  article  I'll  share  some 
of  the  information  I’ve  gathered  and 
discovered,  and  describe  the  structure 
of  a  Macintosh  device  driver.  I’ll  then 
present  a  driver  template  written  in 
Think  C  4.0. 

The  Device  Manager 

A  set  of  system  routines  called  the  “De¬ 
vice  Manager"  gives  access  to  device 
drivers  on  the  Macintosh.  The  calls  pro¬ 
vided  by  this  Manager  define  the  appli¬ 
cation’s  interface  to  the  drivers.  The 
Manager  includes  functions  for  open¬ 
ing  and  closing  drivers,  synchronous 
and  asynchronous  I/O,  control  and 
status  calls. 

Opening  and  closing  drivers  are  per¬ 
formed  by  two  routines,  OpenDriver 
and  CloseDriver,  while  the  I/O  routines 
are  implemented  through  the  FSRead 
and  FSWrite  calls.  The  Control  routine 
provides  an  interface  for  sending  con¬ 
trol  information  to  and  from  the  driver, 
and  the  Status  routine  returns  status  infor¬ 
mation  about  the  driver  and  its  current 
state.  (These  are  all  high-level  routines, 
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meaning  that  the  interfaces  have  been 
simplified  at  the  expense  of  functional¬ 
ity.  Each  of  these  routines  in  turn  calls 
a  low-level  parameter  block-based  rou¬ 
tine  to  perform  the  desired  function.) 

Inside  Device  Drivers 

Drivers  are  used  for  many  purposes: 
Accessing  block  devices  such  as  disk 
drives,  providing  a  common  interface 
to  many  different  printers,  and  even  for 
implementing  networks.  But  drivers  aren’t 
always  used  for  talking  to  a  hardware 
device.  They  can  also  be  used  for  Inter- 
Application  Communication,  and  par¬ 
ticularly  for  things  such  as  implementing 
desk  accessories  on  the  Macintosh. 

There  are  four  general  classes  of  driv¬ 
ers  on  the  Macintosh:  System  drivers, 
desk  accessories,  slot  drivers,  and  device¬ 
independent  (general  usage)  drivers. 
System  drivers  are  used  as  network 
drivers,  SCSI  drivers,  and  printer  driv¬ 
ers,  and  most  are  stored  in  the  Mac’s 
ROM.  Desk  accessories,  on  the  other 
hand,  are  a  special  case  of  driver  de¬ 
signed  to  be  used  as  “mini-applica¬ 
tions”  that  can  be  accessed  from  any 
application.  Though  somewhat  limited 
in  size,  desk  accessories  can  have  their 
own  menus  and  windows,  and  receive 
and  handle  events  in  a  manner  similar 
to  applications.  But  because  they  must 
coexist  with  applications,  desk  acces¬ 
sories  cannot  take  the  same  liberties 
with  the  system  as  do  some  applica¬ 
tions.  NuBus  slot  drivers  are  usually 
loaded  into  memory  from  devices  on 


the  NuBus.  And  general  usage  drivers, 
usually  not  associated  with  any  hard¬ 
ware,  can  be  used  to  implement  such 
things  as  Inter-Application  Communi¬ 
cation  or  a  network  E-mail  system. 

Device  drivers  are  accessed  through 
the  Unit  Table  stored  in  the  Macin¬ 
tosh’s  system  heap.  A  pointer  to  the 
Unit  Table  is  stored  in  the  low-memory 
global  UTableBase  ($1 1C),  and  the  size 
of  the  Unit  Table  is  stored  in  the  low- 
memory  global  UntryCNt  ($1D2).  The 
Unit  Table  contains  entries  from  which 
each  specific  driver  is  referenced.  When 
a  driver  is  installed  in  the  Unit  Table,  a 
device  control  entry  structure  is  allo¬ 
cated  in  the  system  heap,  and  its  han¬ 
dle  is  installed  in  the  appropriate  entry 
in  the  unit  table.  The  device  control 
entry,  commonly  referred  to  as  the  DCE, 
is  then  filled  out  with  the  driver’s  attrib¬ 
utes.  The  format  of  the  device  control 
entry  structure  is  shown  in  Example  1 . 
The  high-order  byte  of  the  field  dCtlFlags 
is  set  from  the  drvrFlags  field  in  the 
driver’s  header,  while  the  low-order  byte 
is  set  up  at  driver  installation  time.  The 
bits  are  defined  in  Figure  1 . 

The  driver  itself  is  usually  stored  as 
a  DRVR  resource,  although  it  can  be 
loaded  in  from  a  hardware  device.  The 
format  of  the  DRVR  resource  is  shown 
in  Figure  2.  Table  1  provides  further 
details  on  this  format. 

Each  driver  can  have  five  routines 
to  handle  calls  from  the  device  man¬ 
ager.  The  routines  are:  open,  prime, 
control,  status,  and  close.  The  open 
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and  close  routines  perform  initializa¬ 
tion  and  clean  up  functions  for  the 
driver.  Read  and  write  calls  are  han¬ 
dled  through  the  prime  routine.  The 
driver’s  status  routine  returns  the  status 
of  the  driver  to  the  device  manager, 
and  the  control  routine  is  for  control 
functions  pertaining  to  the  driver’s  task. 
When  one  of  the  driver’s  routines  is 
called,  a  pointer  to  the  parameter  block 
for  that  call  is  passed  in  implementing 
function  register  AO,  and  a  pointer  to 
the  device  control  entry  is  passed  in 
Al.  The  call-specific  information  is 


passed  in  a  parameter  block  as  shown 
in  Example  2. 

The  csCode  field  is  used  as  a  selector 
for  requesting  a  specific  function  or 
specific  information  from  a  control/ 
status  call.  When  defining  the  separate 
control  calls  for  a  driver,  the  program¬ 
mer  must  take  into  account  that  some 
csCodes  are  predefined,  such  as  the 
accRun  (csCode  65),  which  is  used  to 
give  the  driver  time  if  the  dNeedTime 
bit  is  set  in  the  driver’s  DCE. 

The  ioPosMode ,  and  the  ioPosOffset 
fields  are  used  for  block  device  drivers 


to  position  the  current  read/write.  The 
valid  modes  are  fsAtMark,  fsFromStart, 
fsFromMark.  The  current  position  is 
contained  in  the  driver’s  dCtlEntryHan- 
dle.  If  the  mode  is  fsAtMark ,  ioPos¬ 
Offset  should  be  ignored  and  the  opera¬ 
tion  started  at  the  current  position.  If  it 
is  fsFromStart ,  or  fsFromMark ,  then 
ioPosOffset  is  added  to  the  beginning 
of  the  device,  or  the  current  position 
respectively,  to  obtain  the  starting  posi¬ 
tion  for  the  operation.  The  constants 
used  to  determine  mode  are:  fsAtMark 
=  0 ,  fsFromStart  =  1 ,  fsFromMark  =  3- 
And  the  ioTrap  field  can  be  used  to 
determine  whether  operation  is  a  read 
or  write,  and  whether  it  is  synchronous 
or  asynchronous. 

I/O  Management 

I/O  requests  for  drivers  are,  for  the 
most  part,  managed  by  the  Device  Man¬ 
ager,  which  calls  the  driver  at  the  ap¬ 
propriate  time  to  handle  enqueuing 
asynchronous  requests.  A  call  to  the 
IODone  routine  informs  the  Device  Man¬ 
ager  that  the  request  was  completed. 
The  address  of  this  routine  is  stored  in 
the  low  memory  global  jlODone  at  ad¬ 
dress  S8FC.  If  the  request  was  asyn¬ 
chronous  and  our  driver  was  unable 
to  complete  the  call,  then  we  must  exit 
via  an  RTS.  If  the  call  was  completed 
we  must  JMP  to  the  IODone  routine,  at 
which  point  the  Device  Manager  de¬ 
queues  the  request  and  calls  the  re¬ 
quest’s  completion  routine.  The  Open 
and  Close  routines  will  always  be  called 
synchronously. 

Two  other  routines  that  a  driver  may 
use  are  Fetch  and  Stash,  which  are 
used  as  an  aid  for  asynchronous  I/O. 
The  Fetch  routine,  called  using  the  jFetch 
vector  at  address  $8F4,  simply  returns 
one  byte  at  a  time  from  the  request’s 
data  buffer  pointed  to  by  ioBuffer ;  while 
incrementing  ioActCount  by  one.  The 
Stash  routine  is  used  for  Read  requests, 
and  simply  stuffs  bytes  into  the  re¬ 
quest’s  buffer,  incrementing  ioActCount 
by  one.  Its  vector  is  jStash  at  address 
$8F8.  The  setup  for  these  calls  is  listed 
in  Table  2. 

Device  Drivers  in  Think  C 

Think  C  provides  a  mechanism  for  de¬ 
veloping  drivers  entirely  in  C  using  a 
stub  to  call  main( /with  the  parameter 
block,  the  DCE,  and  a  selector  to  spec¬ 
ify  the  type  of  call.  The  prototype  for 
the  main  routine  is: 

int  main  (cntrlParam  *ioBlock_ptr, 
DCtlPtr  dce_ptr,  int  call_type); 

The  call_type  parameter  is  used  to  spec¬ 
ify  which  type  of  Device  Manager  call 
was  actually  made  to  the  driver.  The 


typedef  struct  { 

Ptr  dCtlDriver  ; 

/*  Pointer  to  ROM  driver,  or  a  handle  to  RAM 

driver*/ 

short  dCtlFlags  ; 

/*  Driver  flags  */ 

QHdr  dCtlQHdr  ; 

/*  Driver  I/O  queue  header  */ 

long  dCtlPosition  ; 

/*  Current  position;  used  by  block  device 

• 

drivers*/ 

}  DCtlEntry,  *DCtlPtr, 

•'DCtlHandle  ; 

Example  1:  The  format  of  the  device-control  entry  structure 


bit5: 

set  if  the  driver  is  open 

bit6: 

set  if  the  driver  is  RAM  based 

bit7: 

set  if  the  driver  is  currently  executing 

Figure  1:  The  bits  of  the  dCtlFlags  field 


byte  0:drvrFlags 

( length  2  bytes  ) 

byte  2:drvrDelay 

( length  2  bytes  ) 

byte  4:drvrEMask 

( length  2  bytes  ) 

byte  6:drvrMenu 

( length  2  bytes  ) 

byte  8:drvr0pen 

( length  2  bytes  ) 

byte  10:drvrPrime 

j  length  2  bytes  ) 

byte  12:drvrCtl 

( length  2  bytes  ) 

byte  l4:drvrStatus 

( length  2  bytes  ) 

byte  16:drvrClose 

( length  2  bytes  ) 

byte  18:drvrName 

( length  1  byte  ) 

byte  19:drvrName  +  1 

( length  n  bytes  ) 

byte  19+n:driver  routines 

Figure  2:  The  format  of  the  DRVR  resource 


Resource 

Description 

drvrFlags 

The  high  order  byte  of  the  drvrFlags  field  contains  the  following  bit  fields: 
dReadEnable  (bit  8)  is  set  if  the  driver  can  respond  to  Read  calls. 
dWriteEnable  (bit  9)  is  set  if  the  dirver  can  respond  to  Write  calls. 
dCtlEnable  (bit  10)  is  set  if  the  driver  can  respond  to  Control  calls. 
dStatEnable  (bit  11)  is  set  if  the  driver  can  respond  to  Status  calls. 
dNeedGoodbye  (bit  12)  is  set  if  driver  needs  to  call  be  called  before  the 
application  heap  is  reinitialized. 

dNeedTime  (bit  1 3)  is  set  if  driver  needs  to  be  called  periodically. 
dNeedLock  (bit  14)  is  set  if  driver  should  be  locked  in  memory. 

drvrDelay 

This  field  is  used  if  the  dNeedTime  bit  of  the  drvrFlags  field  is  set.  It 
defines  how  often  the  dirver  will  be  called  to  perform  periodic  actions. 
This  is  done  by  a  control  call  with  csCode  65. 

drvrEMask 

This  field  is  the  event  mask  used  by  desk  accessories.  This  contains 
flags  for  the  desk  accessory  to  define  which  events  it  can  receive. 

drvrMenu 

This  field  is  also  used  by  desk  accessories.  If  a  desk  accessory  has  it’s 
own  menu,  then  the  menulD  of  the  menu  is  stored  here. 

drvrOpen 

drvrPrime 

drvrCtl 

drvrStatus 

drvrClose 

Each  of  these  fields  contain  an  offset  to  their  respective  routines. 

drvrName 

The  device  driver’s  name.  The  name  of  a  non-desk  accessory  device 
driver  always  starts  with  a  by  convention. 

Table  1:  Detailed  description  of  resource  format 
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body  of  the  driver  should  be  set  up  as 
a  switch  statement  based  on  call_type , 
which  is  shown  in  Example  3. 

The  ioBlock _ptr  parameter  contains 
a  pointer  to  the  current  request  pa¬ 
rameter  block,  and  the  second  parame¬ 
ter  is  a  pointer  to  the  driver’s  device 
control  entry.  Think  C  also  allows  you 
to  declare  globals,  and  when  the  driver 
is  loaded,  the  stub  will  allocate  the 
memory  required  and  store  a  handle 
to  it  in  the  dCtlStorage  field  of  the  de¬ 
vice  control  entry.  If  the  stub  routine 
could  not  allocate  the  memory  for  the 
globals,  then  dCtlStorage  will  be  0,  and 
the  driver’s  open  routine  should  return  a 
negative  error  value.  It  is  not  necessary 
to  call  the  IODone  routine,  as  the  driver 
stub  provided  with  Think  C  does  this 
automatically.  If  an  asynchronous  re¬ 
quest  could  not  be  completed,  all  that 
is  necessary  is  to  return  a  1  to  the  stub. 

Driver  Template 

The  driver  presented  in  this  article  was 
written  using  the  Object  C  extensions 
in  Think  C  4.0.  Listing  One  (page  72) 
shows  driver.h,  the  header  file,  while 
Listing  Two  (page  72)  lists  driver.c,  the 
source  file.  In  order  to  use  the  tem¬ 
plate,  simply  declare  a  subclass  of  the 
class  driver,  and  override  whatever  meth¬ 
ods  are  necessary  (see  Example  4).  For 
more  information  on  Object  C,  see  the 
Think  C  User’s  Guide  for  Version  4.0. 
Also,  a  New( )  routine  must  be  pro¬ 
vided  to  allocate  the  subclass  as  shown 
in  Example  5. 

The  Fetch/)  and  Stash( )  routines 
were  provided  for  use  with  asynchro¬ 
nous  calls,  but  should  not  be  used  for 
non-immediate  calls.  The  async  field 
of  the  driver  class  can  be  used  to  deter¬ 
mine  whether  a  call  was  asynchronous. 
After  the  driver  is  completed,  all  that 
needs  to  be  done  is  to  install  it  in  the 
unit  table.  Although  it  sounds  simple 
in  theory,  this  can  be  as  much  fun  as 
writing  the  driver  itself,  so  I  will  leave 
driver  installation  for  another  article. 

Availability 

All  source  code  for  articles  in  this  issue 
is  available  on  a  single  disk.  To  order, 
send  $14.95  (Calif,  residents  add  sales 
tax)  to  Dr.  Dobbs  Journal ,  501  Galves¬ 
ton  Dr.,  Redwood  City,  CA  94063,  or 
call  800-356-2002  (from  inside  Calif.) 
or  800-533-4372  (from  outside  Calif.). 
Please  specify  the  Macintosh  special 
issue. 


DDJ 

(Listings  begin  on  page  72.) 

Vote  for  your  favorite  feature/articte. 
Circle  Reader  Service  No.  5. 


Control/Status  calls 

/*  parameter  block 

for  Control/Status  calls  */ 

typedef  struct { 

QElemPtr 

qLink; 

/♦Link  to  next  parameter  block  in 
driver  queue*/ 

int 

qType; 

/•Queue  type*/ 

int 

ioTrap; 

/•Trap  to  make  call; 

PBControl  -  SA0Q4  */ 

Ptr 

ioCmdAddr; 

/♦Trap  address*/ 

ProcPtr 

ioCompletion; 

/♦Completion  routines  address*/ 

OsErr 

ioResult; 

/♦Result  of  call*/ 

StringPtr 

ioNamePtr; 

/•Driver  name*/ 

int 

ioVRefNum; 

/♦Volume  reference  number*/ 

int 

ioRefNum; 

/♦Driver  reference  number*/ 

int 

csCode; 

/♦Type  of  Control/Status  call*/ 

int 

csParamfll]  / 

/•Control/Status  information*/ 

}  cntrlParam; 

Prime  (Read/Write)  calls 

typedef  struct f 

QElemPtr 

dLink; 

/♦Link  to  next  parameter  block  in 
queue*/ 

int 

qType; 

/♦Queue  type  */ 

int 

ioTrap; 

/•Trap  used  to  make  call; 

PBRead  »  $A002*/ 

Ptr 

ioCmdAddr; 

/♦Trap  address  */ 

ProcPtr 

ioCompletion; 

/♦Completion  routines  address  */ 

OsErr 

ioResult? 

/♦Result  of  call  */ 

StringPtr 

ioNamePtr; 

/•Driver  name  */ 

int 

ioVRefNum; 

/♦Volume  reference  number  */ 

int 

ioRefNum; 

/♦Driver  reference  number  */ 

SignedByte 

ioVersNum; 

/•Not  used  */ 

SignedByte 

ioPermssn; 

/•Read/Write  permission  (for  block 
device  drivers)*/ 

Ptr 

ioMisc; 

/♦Not  used  */ 

Ptr 

ioBuffer; 

/♦Pointer  to  data  buffer  */ 

long 

ioReqCount; 

/•Requested  number  of  bytes  */ 

long 

ioAct Count; 

/♦Actual  number  of  bytes  */ 

int 

ioPosMode; 

/•Positioning  mode  (block  device 
drivers) */ 

long 

ioPosOf f set ; 

/•Positioning  offset  (block  device 
drivers)*/ 

}  ioParam; 

Example  2:  Call  specific  information 


Call 

Description 

IODone 

Asynchronous  I/O  completion  call. 

Entry:  store  pointer  to  device  control  entry  in  A1 . 

Fetch 

Fetches  a  byte  fpr  a  wrote  request  (asynchronous  only). 

Entry:  pointer  to  device  control  entry  in  A1 . 

Exit:  one  byte  stored  in  DO  (if  bit  1 5  is  set  then  it  is  the  last  character  in  the 

buffer). 

Stash 

States  a  byte  for  a  read  request  (asynchronous  only). 

Entry:  pointer  to  device  control  entry  in  A1  byte  to  be  stashed. 

Exit:  if  bit  1 5  of  DO  is  set  then  last  byte  has  been  stashed. 

Table  2:  Setup  for  I/O  calls 


int  main(  cntrlParam  *io_ptr,  DCtlPtr  dce_ptr,  int  call_type  ) 

switch 

call  type  )  ( 

case  0 

/*  open  */ 

case  1 

/*  prime  */ 

case  2 

/*  control  */ 

case  3 

/*  status  */ 

case  4 

/*  close  */ 

return 

} 

result  ; 

Example  3-'  The  body  of  the  driver  should  be  set  up  as  a  switch  statement 
based  on  call_type 


struct  my_driver: driver  { 
int  my_storage  ; 

driver  *New(  ) 

/*  overridden  routines  */ 
void  Open(  )  ; 
void  Close  (  )  ; 
void  Read(  )  ; 
void  Write  (  )  ; 

f 

return  new (  my  driver  )  ; 

1 

I  ; 

Example  5:  A  New(  )  routine  allocates 

Example  4:  Overriding  methods  the  subclass 
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PERSISTENT 

OBJECTS 

I  Dealing  with  storage 
in  Smalltalk 


n  recently  had  to  develop  sev¬ 
eral  expert  systems  that,  along 
with  a  host  of  other  consid¬ 
erations,  had  to  be  able  to 
use  files  created  by  existing  applica¬ 
tions.  The  expert  system  then  needed 
to  store  the  data  from  those  files  in 
other  files  that  could  be  shared  on  a 
network.  This  article  describes  a  tech¬ 
nique  that  I  used  for  building  those 
requirements  into  my  expert  systems. 
This  technique,  which  uses  persistent 
objects,  allows  programs  to  access  files 
from  other  applications  and  then  store 
shareable  persistent  objects  on  disk. 

Among  the  other  constraints  on  this 
project  were  the  type  of  PCs  at  my 
disposal  (a  network  of  XT  clones),  user- 
interface  considerations,  and  a  limited 
amount  of  time  available  to  create  the 
system.  Consequently,  I  decided  that 
the  best  development  environment  for 
the  job  was  Smalltalk  —  in  particular, 
Digitalk’s  Smalltalk  /  V. 

Why  is  an  XT-based  system  being 
discussed  in  a  magazine  that  focuses 
on  Macintosh  programming?  Because 
I  do  all  of  my  work  —  code  develop¬ 
ment,  documentation  creation,  the  writ¬ 
ing  of  user’s  guides,  the  works  —  on  a 
Macintosh,  using  Smalltalk  /  V  Mac.  I 
develop  applications  on  my  Mac  at 
home,  copy  them  to  a  Compaq  port¬ 
able,  and  then  port  them  to  PCs  at  the 


Charles  is  a  system  designer  who  can 
be  reached  on  CompuServe  71230, 121 7, 
BIX  crovira,  or  care  of  Adelphi,  3465 
Wyman  Crescent,  Gloucester,  Ontario, 
Canada  K1 V  OP3- 


Charles-A.  Rovira 

client  site  in  Smalltalk  /  V  or  Smalltalk  / 
V286.  This  process  is  convenient  for 
two  reasons:  The  PC  can  be  used  effec¬ 
tively  with  a  decent  user  interface,  and 
I  don't  have  to  recode  my  applications 
(apart  from  niggling  details). 

Streams  and  RecordStreams 

Smalltalk  is  the  language  that  defined 
all  of  the  relevant  concepts  of  object- 
oriented  programming  and  provided 
the  first  implementation  of  that  ap¬ 
proach.  Fundamentally,  Smalltalk  re¬ 
mains  a  single-user,  memory-based,  sin¬ 
gle  processor  system.  Furthermore,  Small¬ 
talk’s  file-handling  system  is  quite  lim¬ 
ited,  satisfying  all  of  its  needs  with 
Streams  of  bytes. 

Most  programmers  never  see  beyond 
this  limitation.  During  the  course  of 
their  programming  experiences,  they’ve 
developed  the  attitude  that  any  lan¬ 
guage  without  unit-record  support  can’t 
be  considered  a  real  computer  language. 
This  common  misconception  stems 
from  the  fact  that  languages  are  gener¬ 
ally  fixed,  and  thus  are  limited  by  their 
original  definition.  Because  file  1  /  O 
is  usually  the  territory  of  compiler  writ¬ 
ers,  we  programmers  are  stuck  with 
whatever  file-handling  capabilities  are 
already  provided  for  us  in  a  language. 
What  can  be  a  revelation  to  program¬ 
mers  about  Smalltalk  is  that  this  pro¬ 
gram  can  be  a  superb  file  manager  or 
database  manager,  if  the  appropriate 
objects  —  such  as  persistent  objects  — 
are  defined. 

In  general,  persistent  objects  can  be 
thought  of  as  files  that  consist  of  collec¬ 


tions  of  bytes,  one  after  another,  that 
are  normally  read  from  beginning  to 
end  as  Streams  of  data.  Streams  may 
be  positioned  at  any  point  in  the  stream, 
thereby  providing  random  access.  The 
file-management  system  built  into  Small¬ 
talk  handles  Streams  quite  well. 

In  the  simplest  kind  of  persistent  ob¬ 
ject,  files  are  just  repositories  for  fixed- 
format  data.  Each  file  contains  only  one 
type  of  record.  The  files  are  completely 
external  to  memory,  and  a  window, 
one  record  wide,  is  provided  for  view¬ 
ing  the  files,  as  illustrated  in  Figure  1. 

The  process  of  extending  Streams 
from  files  of  bytes  to  files  of  unit  re¬ 
cords  is  relatively  simple.  Listing  One 
(page  74)  provides  all  of  the  code 
needed  to  implement  a  mechanism  to 
access  a  file  of  any  record  type.  This 
code  is  safe  to  use,  as  long  as  you  don’t 
position,  read,  or  write  by  any  other 
methods  than  these  methods  imple¬ 
mented  in  class  RecordStream,  which 
have  not  been  disinherited.  It  is  still 
possible  to  position  the  file  at  points 
other  than  at  record  boundaries.  (If 
you  write  off  boundaries,  you  will  de¬ 
stroy  your  file.)  This  implementation 
also  has  no  end-of-file  handling  mecha¬ 
nism  in  its  file  reads,  and  currently 
passes  end-of-file  detection  to  the  alEnd 
message  that  the  file  inherits  from  class 
File.  The  code  is  primitive,  but  usable. 

Model  Behavior 

The  definition  of  RecordStream  incor¬ 
porates  a  frequently  used  Smalltalk  con¬ 
cept  —  the  notion  of  a  model.  In  a 
“model,”  objects  manipulate  other  ob- 
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jects.  By  providing  the  manipulative 
objects  with  the  means  to  interrogate 
any  manipulated  object  about  informa¬ 
tion  relevant  to  a  manipulative  object, 
it  is  possible  to  both  make  an  object 
perform  actions  and  to  cause  the  object 
to  act  upon  any  other  object. 

For  example,  say  we  need  to  read 
from  and  write  to  a  file  of  employee 
data  in  which  fields  are  delimited  by 
commas,  and  records  are  delimited  by 
carriage  returns.  We  can  define  a  model 
for  employee  records.  The  Employee 
class  should  define  all  of  the  behavior 
of  an  employee,  from  the  date  of  hire 
to  the  date  of  termination.  Listing  Two 
(page  74)  contains  a  sample  class  defi¬ 
nition  for  employees.  This  Employee 
model  enables  us  to  create  an  employee 
file,  albeit  a  very  simple  one.  Let’s  say 
that  the  employee  master  for  January 
1989  is  called  EmpMast.891.  Access  to 
the  file  could  be  performed  in  this  way: 

I  empfile  empRec  ! 

empfile  :=  File  pathName: 
’EmpMast.891’  model:  Employee 

We  can  read  the  fifth  employee  record 
by  sending  the  recordReadAt:  message 
to  the  file,  and  passing  the  record  num¬ 
ber  as  a  parameter:  empRec  .  =  empfile 
recordReadAt:  5 

We  read  the  next  employee  record 
with  the  code:  empRec  .  =  empfile  re- 
cordReadNext. 

We  can  write  the  fifth  employee  re¬ 
cord  by  sending  the  record  Write: at:  mes¬ 
sage  to  the  file,  and  passing  the  em¬ 
ployee  to  be  written  and  that  employee’s 
record  number  as  the  following  parame- 


Figure  2:  Persistent  objects 


ters:  empfile  recordWrite:  empRec  at:  5. 

We  read  the  next  employee  record 
by  sending  the  recordWriteNext:  mes¬ 
sage  to  the  file,  and  passing  the  em¬ 
ployee  to  be  written  as  a  parameter: 
empfile  recordwriteNext:  empRec. 

Now  that  we  have  provided  a  basic 
mechanism  for  dealing  with  flat  files, 
the  unit  record  mechanism  can  be  ex¬ 
tended  to  include  structured  files  such 
as  dBase  files,  B-tree  files,  and  other 
allocation  and  indexing  schemes.  The 
use  of  a  record  model  class  now  allows 
us  to  define  a  unit  record  file  as  a  file 
that  contains  something. 

Persistent  Collections 

A  more  interesting  type  of  persistent 
object  —  the  persistent  collection  —  al¬ 
lows  you  to  store  instances  of  objects, 
regardless  of  their  class  or  size.  This 
type  of  persistent  object  is  implemented 
by  extending  the  collection  classes  be¬ 
yond  the  bounds  of  memory.  When 
such  an  object  is  accessed,  the  collec¬ 
tion  is  loaded  into  memory,  and  the 
instances  that  make  up  the  collection 
remain  on  disk. 

With  persistent  collections,  files  can 
contain  variable-length  data,  and  they 
are  no  longer  limited  to  one  class  of 
object  per  file.  The  files  are  partially 
resident  in  memory,  and  a  window  on 
the  entire  file  is  provided.  Only  the  spe¬ 
cific  instances  within  the  collection  are 
disk-resident,  as  shown  in  Figure  2. 

The  position  of  the  class  within  the 
hierarchy  also  means  that  a  fast-run¬ 
ning  development  version  of  an  appli¬ 
cation  can  be  produced  quickly.  You 
can  easily  modify  both  test  and  pro¬ 


duction  versions  of  the  application  in 
order  to  use  external  storage.  To  do  so, 
just  change  the  initialization  and  termi¬ 
nation  methods  of  the  application. 

The  use  of  persistent  collections  lets 
you  create  and  maintain  objects  that 
can  be  orders  of  magnitude  larger  than 
the  memory  available  to  most  comput¬ 
ers  (640K  in  the  PC  world,  and  1  Mbyte 
in  the  Macintosh  world.)  Most  real- 
world  data  is  larger  than  a  computer’s 
available  RAM  memory,  and  these 
classes  enable  Smalltalk  to  aspire  to 
real-world  applications  on  PCs. 

Listings  Three  and  Four  (page  74 
and  76,  respectively)  contain  a  sample 
class  definition  for  Persistent  Array.  The 
file  is  accessed  in  an  initialization  rou¬ 
tine: 

!  empPerArr  empRec  ! 

empPerArr  :=  PersistentArray 

open:  ’EmpPA.89T  of:  10. 

After  initialization,  PersistentArrays  are 
totally  transparent  and  can  be  used  in 
the  same  way  as  any  other  array.  To 
access  the  fifth  instance,  send  the  array 
the  message:  empRec  :=  empPerArr  at: 
5.  To  add  or  update  the  fifth  instance, 
send  the  array  the  message:  empPerArr 
at:  5  put:  empRec.  This  definition  of 
PersistentArray  includes  only  three  meth¬ 
ods  for  managing  the  array:  at:,  at:if Ab¬ 
sent:,  and  at.put:. 

The  rest  of  the  definition  contains 
methods  for  managing  the  file-resident 
portion  of  PersistentArray.  These  meth¬ 
ods  handle  the  following  activities: 

•  initially  binding  to  a  persistent  object 

•  optionally  requesting  a  read-only 
mode 

•  optionally  requesting  that  the  integ¬ 
rity  of  the  read-only  file  be  preserved 
by  coercing  any  read-write  object 
bound  to  append  any  changes 

•  optionally  requesting  that  any  changes 
to  the  object  be  posted  to  specific, 
synchronized  read-only  instances 

•  closing  the  object 

•  optionally  compressing  read-write  in¬ 
stances 

•  closing  all  read-only  instances  of  the 
same  object 

Because  of  recovery  considerations,  in¬ 
stances  within  a  persistent  collection 
are  composed  of  associations.  Should 
you  ever  have  to  rebuild  a  persistent 
object  because  of  media  failure  or  an¬ 
other  fatal  error,  the  task  is  made  much 
easier  by  the  use  of  associations. 

Of  course,  extending  the  flexibility 
of  Smalltalk  outside  of  its  own  memory 
does  not  come  without  certain  risks 
and  costs.  The  synchronization  between 
the  memory-resident  copy  and  the  in- 
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stances  on  disk  may  be  corrupted  if 
one  process  updates  the  object  while 
another  process  is  accessing  the  object, 
or  if  a  failure  to  return  the  memory- 
resident  portion  of  a  persistent  collec¬ 
tion  to  disk  occurs  (because  of  a  sys¬ 
tem  crash,  a  software  error,  or  what¬ 
ever). 

Also,  a  collection  may  no  longer  fit 
in  the  space  reserved  for  it  at  the  front 
of  the  file.  The  file  may  contain  large 
gaps,  and  may  need  garbage  collec¬ 
tion,  a  simple  but  time-consuming  ac¬ 
tivity.  The  entire  process  and  the  per¬ 
sistent  object  structure  can  be  optimized 
in  order  to  minimize  the  need  for  gar¬ 
bage  collection. 

Conclusion 

Persistent  objects  and  persistent  collec¬ 
tions  allow  access  to  existing  data  and 
provide  the  flexibility  of  Smalltalk,  while 
enabling  you  to  store  objects  on  disk 
and  even  to  share  objects  between  ap¬ 
plications.  The  synchronization  of  views 
across  operating  system  task  bounda¬ 
ries  can  be  accomplished  with  some 
judicious  intertask  messaging.  The  en¬ 


tire  problem  can  also  be  circumvented 
through  the  use  of  a  server-client  mecha¬ 
nism,  which,  of  course,  presents  its 
own  subtleties. 
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I  Fast  disk  backups  save 
time  and  money 

Don  Gaspar 


t’s  8  a.m.,  and  you  need  ten 
copies  of  a  program  you’ve 
been  writing  to  hand  out  to 
beta  testers.  The  Finder  is  just 
too  slow  when  copying  and  formatting 
entire  disks:  A  Kcibayashi  Maru  scenario 
won’t  work  here.  Besides,  you  need  the 
disk  now,  not  next  year.  So  you  try  your 
disk  copier,  only  to  find  it  doesn’t  allow 
you  to  make  multiple  copies.  Oh  no! 

You  decide  that  you’ll  make  single 
copies  by  reading  the  disk  into  mem¬ 
ory,  writing  the  copy  to  another  disk, 
and  then  repeating  both  steps  again, 
and  again.  You  know  this  process  will 
be  extremely  time  consuming,  but  the 
only  alternative  is  using  the  Finder, 
which  will  require  more  disk  swaps 
and  mouse  clicks  than  you  can  count. 
You  launch  your  copier  and  find  that 
it  doesn’t  support  the  new  Macintosh 
1.44-Mbyte  disks.  Nuts! 

So  you  start  the  single-copy  process, 
knowing  full-well  it’s  going  to  require 
ten  steps  of  swapping  and  clicking  and 
almost  as  many  minutes  for  each  of  ten 
disks.  Holy  Bazookas!  What  are  you 
going  to  do? 

How  about  writing  your  own  disk 
copier,  over  which  you’ll  have  com¬ 
plete  control?  Too  hard?  No  way. 


Don  is  a  physicist  and  a  senior  soft¬ 
ware  engineer  for  DIALOG  Informa¬ 
tion  Services,  Inc.  in  Palo  Alto.  He  can 
be  reached  at  3460  Hillview  Ave.,  Palo 
Alto,  CA  94304. 


This  article  explains  how  to  write  a 
sector-copying  disk  utility  for  your  Macin¬ 
tosh.  A  sector  copier  is  a  program  that 
reads  entire  sectors  on  a  disk  into  a 
designated  area  in  RAM,  and  then  later 
writes  them  from  RAM  to  a  destination 
drive.  The  data  of  all  your  programs, 
files,  and  utilities  is  stored  on  your  me¬ 
dia  in  this  way.  The  sector  copier  will 
read  a  disk  into  memory,  sector  by 
sector  (which  is  512  bytes  at  a  time), 
and  then  write  this  data  to  the  destina¬ 
tion  disk.  Reading  a  sector  at  a  time  has 
the  advantage  of  speed  since  you’re 
reading/writing  sequences  of  512  bytes 
from  each  read/write  process.  The  C 
source  code  for  WizardCopy,  a  disk 
copier  I  wrote,  is  shown  in  Listing  One, 
page  80.  (The  Rez  file  that  implements 
the  WizardCopy  application  is  avail¬ 
able  on  CompuServe,  the  DDJ  on-line 
service,  and  on  disk.)  Programs  like 
WizardCopy  are  timesavers  when  it 
comes  to  multiple  copies;  I  just  made 
15  copies  of  a  beta  version  of  a  pro¬ 
gram  I’m  writing  to  send  to  beta  testers, 
and  the  whole  copy  process  took  only 
a  few  minutes!  I  would  have  aged  a 
year  if  I’d  had  to  make  the  copies  by 
other  means. 

The  programming  techniques  pre¬ 
sented  in  this  article  illustrate  Macin¬ 
tosh  fundamentals  for  using  the  Device 
Manager  and  the  Disk  Driver.  You’ll 
quickly  understand  these  important  fun¬ 
damentals  by  looking  through  the 
source  code  in  Listing  One.  No  more 


clicking  the  mouse  again  and  again 
just  to  format  a  disk.  No  more  dragging 
disks’  icons  to  other  icons  and  waiting. 
How  about  auto-formatting  with  mini¬ 
mal  input?  How  about  copying  the  disk 
in  17  to  45  seconds  (depending  on 
whether  the  disk  is  400K,  800K,  or  1.44- 
Mbyte)?  These  speed  advantages  are 
another  reason  to  make  a  sector  copier; 
the  more  copies  you  have  to  make,  the 
better  the  performance  gain  will  be. 

The  WizardCopy  Program 

WizardCopy  is  a  sector-copying  utility 
that  will  copy  400K,  800K,  and  1.44- 
Mbyte  disks  for  your  Macintosh.  It  re¬ 
quires  minimal  input,  is  extremely  fast, 
and  has  only  four  controls  (see  the 
main  window  in  Figure  1). 

The  check  boxes  let  you  tell  Wiz¬ 
ardCopy  to  warn  you  before  copying 
over  an  existing  disk,  and  whether  or 
not  to  format  every  disk  that  you  insert. 
These  items  are  simple  to  implement 
and  are  extremely  useful.  The  check 
boxes  are  represented  in  WizardCopy 
as  Boolean  flags  that  are  either  on  or 
off;  simple  semantic  logic  dictates  how 
the  program  behaves  after  checking  these 
flags.  This  alert  was  written  as  a  separate 
dialog  box  because  it  requires  a  response 
of  Yes  or  No,  and  the  other  dialog  box 
offers  only  an  acknowledgement. 

For  example,  if  you  click  ‘Format 
All,’  all  the  destination  disks  are  automati¬ 
cally  formatted.  If  ‘Warn  Before’  is  ac¬ 
tive  and  you  insert  a  destination  disk 
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that  already  has  data  on  it,  WizardCopy 
will  warn  you,  and  ask  if  you  wish  to 
proceed. 

The  ‘New  Master’  and  ‘Quit’  buttons 
are  the  other  controls,  and  are  also 
available  as  commands  in  the  File  Menu. 
The  'New  Master’  button  (or  command) 
tells  WizardCopy  that  you  would  like 
to  copy  a  new  disk.  WizardCopy  will, 
of  course,  free  as  much  space  as  possi¬ 
ble  in  the  heap,  and  prompt  you  to 
insert  the  disk.  When  you  want  to  copy 
another  disk,  select  this  option  again. 
The  Quit  button  (or  command)  does 
what  its  name  implies:  It  frees  all  mem¬ 
ory  that  was  used  by  WizardCopy  and 
disposes  of  all  windows,  menus,  and 
so  on.  It  then  returns  you  to  the  Finder. 
The  WizardCopy  window  also  contains 
four  status  items:  A  progress  meter  at 
the  bottom  of  the  window,  and  boxes 


labeled  Status,  Copies  Made,  and  In 
Memory.  The  progress  meter  (perhaps 
more  decorative  than  functional,  some 
might  argue)  tells  you  how  far  along 
you  are  when  reading  and  writing  sec¬ 
tors.  The  light  gray  rectangle  (see  Fig¬ 
ure  1)  fills  to  solid  black  when  the 
copying  is  done.  This  meter  is  simple; 
it  uses  a  fundamental  algebraic  relation 
between  the  number  of  sectors  on  the 
disk  and  the  size  of  the  rectangle. 

The  progress  meter  is  advanced  each 
time  through  a  read  loop  or  a  write 
loop  (which  read  and  write  ten  512- 
byte  sectors,  respectively).  The  right  side 
of  the  rectangle  is  equal  to  the  left  side 
plus  the  quantity  of  the  sector  just  read 
(or  written)  times  the  length  of  the  rec¬ 
tangle  divided  by  the  number  of  sectors. 

The  meter  is  implemented  with  Quick¬ 
Draw.  To  draw  the  meter,  WizardCopy 


gets  the  dialog  user  item  (ID  #11,  in 
this  case),  fills  it  with  a  light  gray  pat¬ 
tern,  and  then  frames  it.  Another  rec¬ 
tangle  is  created,  equal  to  the  first  one, 
but  its  right  side  is  calculated  by  the 
equation  just  described  —  it’s  filled  with 
black.  Every  time  a  sector  (or  ten  sec¬ 
tors,  in  this  case)  is  read,  the  counter  is 
incremented  and  the  rectangle  is  drawn  — 
an  accurate  copy  progress  meter. 

It  may  be  easier  for  some  of  you  to 
write  this  meter  as  a  control  definition 
procedure,  which  will  have  many  ad¬ 
vantages  over  the  technique  outlined 
here.  No  matter  which  technique  you 
use,  the  progress  meter  will  have  the 
same  look  and  will  perform  virtually 
the  same  way. 

The  ‘Status’  item  tells  the  user  what’s 
going  on.  It  displays  the  messages  “Writ¬ 
ing,  Reading,  Formatting,  Please  insert 


Modifying  WizardCopy  for  Hard  Disks 


While  making  multiple  copies  of  a 
floppy  diskette  using  the  approach 
Don  presents  here  is  certainly  a  handy 
utility,  it  does  require  that  your  Mac 
has  at  least  2  Mbytes  of  RAM  or  that 
you  modify  the  WizardCopy  program 
for  multiple-passes  (for  single  floppy 
drive  systems).  Besides  being  more 
complex,  such  a  modification  requires 
more  disk  swapping  (an  undesirable 
side  effect).  One  alternative  is  to 
change  the  WizardCopy  code  so  that 
you  use  a  hard  drive  instead  of  using 
valuable  RAM  to  store  the  data  from 
the  master  disk.  Modifying  the  exist¬ 
ing  programming  scheme  to  do  this 
involves  little  more  than  using  the 
Macintosh’s  File  Manager  in  place  of 
many  Memory  Manager  routines. 

Actual  code  modifications  are  sim¬ 
ple  and  straightforward.  Allocate  space 
on  the  hard  drive  volume  instead  of 
in  memory.  When  the  master  floppy 
is  read,  transfer  the  data  to  the  newly 
created  hard  drive  file  instead  of  to 
memory.  Finally,  when  the  duplicate 
diskettes  are  to  be  written,  read  the 
data  from  the  hard  drive  instead  of 
from  RAM. 

The  first  change  you  can  make  to 
WizardCopy  is  to  the  MakeRAM  rou¬ 
tine.  The  new  code  should  create  a 
work  file  on  the  hard  drive  with  the 
File  Manager  function  Create.  This 


Ken  is  a  design  engineer  for  Rodime 
Systems,  Boca  Raton,  Fla.,  makers  of 
hard  disk  drives  for  the  Mac.  He  can 
be  contacted  through  DDJ’x  office. 


Kenneth  Turner 

replaces  the  call  to  the  Memory  Man¬ 
ager  function  NeivPtr.  Remove  the  calls 
to  DisposPtr,  FreeMem,  and  Compact- 
Mem.  These  functions  managed  the 
allocation  of  memory  and  reduced 
heap  fragmentation.  Instead,  open  the 
file  with  FSOpen  and  use  the  function 
Allocate  to  ensure  there  is  enough 
free  space  on  the  hard  drive  volume. 
(Though  hard  drive  fragmentation  is 
also  an  important  issue,  it  is  not  cru¬ 
cial  in  this  application  and  will  be 
ignored.) 

In  the  existing  ReadFloppy  and 
WriteFloppy  routines,  a  FOR  loop  con¬ 
trols  the  transfer  of  the  master  data 
to  and  from  a  5K-byte  buffer.  A  hard 
drive  version  will  still  maintain  this 
smaller,  temporary  data  area.  Another 
FOR  loop,  however,  controls  the  trans¬ 
fer  of  data  between  the  large,  master 
buffer  and  this  intermediate  buffer. 
Replace  this  loop  with  a  single  call 
to  either  FSRead or  FSWrite,  depending 
on  the  situation.  These,  obviously, 
interface  with  the  master  data  file  in¬ 
stead  of  the  old  master  RAM  buffer. 

The  Memory  Manager  requires  care¬ 
ful  maintenance  of  pointers  and  han¬ 
dles.  Though  there  is  not  a  direct 
correspondence,  the  File  Manager  de¬ 
mands  its  own  bookkeeping.  The  disk 
copier  needs  to  keep  track  of  the 
access  path  number  for  the  work  file 
it  creates  and  the  volume  reference 
number  of  the  hard  drive  volume. 
These  enable  the  program  to  precisely 
specify  to  the  operating  system  the 
file  containing  the  master  floppy  data. 


The  volume  reference  number  can 
be  obtained  with  the  Get Vol  function. 
The  path  reference  number  is  returned 
when  the  file  is  opened. 

Also,  WizardCopy  must  always 
know  the  position  of  the  file  mark. 
This  is  the  logical  location  of  the  last 
read  or  write.  Whenever  a  new  mas¬ 
ter  diskette  is  to  be  read  or  a  new 
duplicate  diskette  is  to  be  written,  the 
mark  must  be  set  to  the  beginning  of 
the  file  with  SetFPos.  Finally,  when 
the  program  is  finished,  the  file  should 
be  closed  with  FSClose  and  deleted 
from  the  volume  with  FSDelete. 

To  put  the  finishing  touches  on  the 
hard  drive  version,  small  changes 
should  be  made  to  the  user  interface. 
Replace  strings  such  as  “In  Memory” 
with  “On  Disk"  and  change  warnings 
such  as  “You  need  memory”  to  “The 
hard  drive  is  full.” 

With  this  modification,  the  door  is 
now  open  to  other  attractive  features. 
For  instance,  the  program  could  keep 
track  of  several  master  diskettes  at 
once,  instead  of  having  to  reread  a 
floppy  that  was  duplicated  previously. 
A  library  of  virtual  master  diskettes 
could  be  maintained  on  the  hard  drive 
and  recalled  as  needed.  Or,  the  pro¬ 
gram  might  be  modified  to  work  in 
the  background  under  MultiFinder  with¬ 
out  requiring  the  heap  space  used 
by  other  concurrent  applications.  This 
simple  hard  drive  option  is  only  the 
first  step  toward  a  comprehensive  disk 
copier. 

—  K.T. 


46 


Dr.  Dobb's  Macintosh  Journal,  Fall  1989 


927 


WIZARDCOPY 


(continued  from  page  46) 
a  master  disk,”  and  so  on.  It  doesn’t 
serve  as  an  alert,  but  more  as  a  mes¬ 
sage  center  for  the  basic  tasks  our  pro¬ 
gram  executes.  The  strings  for  these 
operations  are  stored  as  a  STR#  re¬ 
source,  and  each  is  individually  indexed. 

The  ‘Copies  Made’  item  tells  the  user 
exactly  how  many  copies  of  a  disk  they 
have  made.  This  feature  is  useful  when 
you  need  several  copies  and  aren’t  count¬ 
ing  each  one.  A  global  integer,  nCopies, 
is  incremented  each  time  a  successful 
copy  is  made;  it’s  cleared  when  ‘New 
Master’  is  selected,  as  the  counter  must 
then  be  reset. 

The  ‘In  Memory’  item  displays  the 
name  of  the  disk  being  copied.  If  there 
is  no  disk  in  RAM,  WizardCopy  dis¬ 
plays  the  string  ‘Nothing’  in  this  box. 
This  item  is  extremely  helpful  when 
you  are  making  copies  of  multiple  disks 
and  you’re  not  sure  what  you’re  copy¬ 
ing:  Just  look  at  the  In  Memory  item, 
and  you’ll  see  the  disk  in  action. 

The  Wizard  icon  in  Figure  1  has  been 
added  to  the  program  for  aesthetic  pur¬ 
poses  only,  and  can  be  removed  from 
the  resource  fork  if  you  don’t  like  it.  I 
think  it  makes  the  program  look  great. 
(It  was  drawn  by  artist  extraordinaire 
Danny  Green.)  The  alert  boxes  are  as 
simple  as  possible. 

The  text  for  the  alerts  and  the  main 
window  is  stored  as  an  STR#  resource, 
and  accessed  via  the  procedure  Get- 


Figure  1:  WizardCopy  main  window 
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IndString.  Remember  that  we’re  in  the 
Macintosh  world,  and  all  the  strings 
we’re  working  with  are  Pascal  strings. 
To  use  this  alert  for  other  problems 
that  may  occur,  I  simply  get  the  appro¬ 
priate  string,  and  then  do  a  GetDItem 
followed  by  a  SetIText  to  change  the 
text  to  the  desired  result.  This  dual 
operation  is  in  a  routine  called  SetDText , 
which  is  short  for  Set  Dialog  Text.  Hav¬ 
ing  the  strings  in  this  format  also  sim¬ 
plifies  translating  WizardCopy  to  for¬ 
eign  languages  —  just  access  Wizard- 
Copy’s  resource  fork! 

Event  Loop 

The  main  window  is  actually  a  mode¬ 
less  dialog  box,  which  simplifies  our 
coding  slightly.  The  event  loop  is  struc¬ 
tured  as  normal,  and  a  function  called 
IsDialogEvent  has  been  added.  If  Get- 
Next  Event  returns  TRUE,  we  then  test 
IsDialogEvent.  IsDialogEvent  will  tell 
us  if  an  event  has  occurred  in  our  dia¬ 
log  box;  we  can  then  take  appropriate 
action.  If  IsDialogEvent  is  TRUE,  we 
then  call  DialogSelect. 

DialogSelecttak.es  the  appropriate  ac¬ 
tion  and  tells  us  which  item  has  been 
selected.  If  DialogSelect  is  TRUE,  we 
then  call  DoDialog.  The  events  for  the 
dialog  box  are  intercepted  before  go¬ 
ing  to  DoDialog ,  which  then  processes 
the  required  response  —  a  simple  fil¬ 
tering  operation.  Two  events  are  inter¬ 
cepted:  updateEvt  and  diskEvt. 


The  updateEvt  is  intercepted  only  be¬ 
cause  the  dialog  box  has  some  nice 
boxes  around  some  of  the  status  items. 
Intercepting  the  event  here,  we  call  our 
own  update  procedure,  which  both  up¬ 
dates  the  dialog  box  and  draws  our  text. 

For  the  copy  process,  the  disk  events 
are  also  intercepted.  The  two  possible 
levels  are  reading  or  writing  disks,  and 
are  identified  by  two  flags.  A  function 
called  DoDisk  executes  the  appropri¬ 
ate  action  based  on  the  level.  For  ex¬ 
ample,  if  DoDisk  is  in  masterLevel,  it 
will  know  it  is  to  copy  a  master  disk; 
after  copying  the  disk,  it  moves  into 
destLevel  (destination  level),  where  it 
writes  the  copied  disk  to  a  destination 
volume.  If  New  Master  was  not  se¬ 
lected,  WizardCopy  will  then  eject  all 
inserted  disks. 

The  event  loop  for  other  events,  like 
menus  or  desk  accessories,  is  then  pro¬ 
cessed  as  usual  (Listing  One). 

Formatting  Disks 

Formatting  disks  is  a  simple  operation. 
Make  a  control  call  with  csCode  equal 
to  6,  and  send  the  reference  number 
of  the  disk  driver  (-5).  We  also  tell  the 
driver  what  type  of  disk  to  format.  For 
a  single-sided  or  a  double-sided  disk, 
we  make  csParam  equal  to  either  1  or 
2;  for  the  1.44-Mbyte  disks,  I  had  no 
idea  what  to  do,  so  I  ran  The  Debugger 
(by  Jasik  Designs)  while  in  the  Finder, 
and  set  a  trap  intercept  at  Control  and 
Status.  The  calls  for  formatting  1.44- 
Mbyte  floppies  are  identical  to  those 
for  formatting  400K  disks.  The  Macin¬ 
tosh  apparently  realizes  we  have  an 
HD  floppy,  and  formats  accordingly. 

When  formatting  a  400K  or  800K  disk, 
I  always  format  it  as  800K;  I  have  found 
no  physical  difference  between  the  two 
types  of  disk  except  for  the  price.  Save 
some  money  and  buy  400K  disks,  and 
use  them  as  800K  disks  —  you  should 
have  no  problems.  You  can  also  save 
by  purchasing  bulk  SS  disks  and  for¬ 
matting  them  as  DS  disks.  The  reason 
manufacturers  differentiate  between  the 
two  is  that  it's  cheaper  to  produce  one 
kind  of  disk  and  label  the  disks  either 
SS  or  DS,  rather  than  producing  two 
different  kinds  of  disks  in  the  same 
factory.  Try  formatting  disks  this  way 
for  yourself,  and  see  if  you  ever  have 
an  abnormally  high  number  of  failures. 

The  formatting  routine  is  called  DoFor- 
mat,  and  it  works  in  conjunction  with 
a  routine  called  CheckDisk.  CheckDisk 
merely  checks  the  format  of  the  disk 
being  copied,  so  that  we  can  allocate 
RAM  and  do  other  tasks. 

Reading  and  Writing  Disks 

The  calls  for  reading  and  writing  disks 
are  similar  to  the  formatting  calls,  ex- 
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cept  that  we  use  some  low-level  read 
and  write  calls  in  the  File  Manager. 
Essentially,  we  set  up  an  ioParamBlock: 
We  specify  where  to  start  the  read/ 
write  process,  how  many  bytes  to  read/ 
write,  a  buffer  pointer  for  the  data,  and 
the  disk  driver  reference  number  (-5, 
again).  When  we  receive  a  disk  event, 
DoDisk  checks  the  appropriate  level 
( masterLevel  or  destLevel)  and  executes 
a  read  or  write  call. 

WizardCopy  executes  a  loop  and 
reads/writes  ten  512-byte  sectors  at  a 
time,  The  progress  meter  can  thus  be 
implemented  accurately.  We  could  have 
made  one  read/write  call  and  done  the 
entire  process  in  one  swing,  but  it 
wouldn’t  have  been  as  exciting  or  as 
user  friendly. 

If  you  would  like  to  modify  the  pro¬ 
gress  meter  for  greater  accuracy,  you 
can  have  WizardCopy  read  a  sector  at 
a  time  (this  will  cause  it  to  run  a  bit 
more  slowly).  The  routines  ReadFloppy 
and  WriteFloppy  accomplish  this  task; 
see  Listing  One. 

Possible  Enhancements 

WizardCopy  could  use  more  error  trap¬ 
ping.  Error  detection  is  provided  in 
every  instance  where  it  would  be  im¬ 
portant,  but  it  has  not  been  imple¬ 
mented  and  intercepted  in  each  case, 
because  of  some  laziness  on  my  part. 
You  can  easily  see  where  to  add  your 
own  dialog  boxes.  Or  you  can  simply 
add  strings  in  the  STR#  resource  and 
call  the  biker  dialog  box  with  strings 
added  in  it. 

You  could  make  WizardCopy  check 
to  see  if  the  latest  version  of  the  disk 
driver  is  available  on  the  machine  you're 
using.  It  would  also  be  nice  to  see  if 
you’re  in  System  6.0.3  or  a  later  ver¬ 
sion.  You  can  put  this  routine  in  the 
procedure  Checklhings. 

WizardCopy  reads  and  writes  an  en¬ 
tire  disk  in  RAM  in  one  pass;  and  will 
tell  users  of  smaller  machines  that  more 
RAM  is  needed.  You  can  easily  make 
WizardCopy  a  multiple-pass  copier  by 
putting  some  of  the  routines  in  a  loop, 
and  repeating  the  loop  n  times  until  n 
passes  are  accomplished.  The  next  ver¬ 
sion  of  WizardCopy  will  include  this 
feature. 
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OBJECT  C 

and  the  MACINTOSH 
CONTROL  PANEL 


I  Object-oriented  cdev 
development 

Bryan  Waters 


ith  the  addition  of  object-ori¬ 
ented  extensions  to  Think  C 
in  Version  4.0,  Think  Tech¬ 
nologies  adopted  the  notion 
of  “Object  C,"  which  combines  the 
functionality  of  Object  Pascal  with  the 
syntax  of  C++.  While  Object  C  sup¬ 
ports  the  declaration  of  classes,  sub¬ 
classes,  inheritance,  and  methods,  it 
does  not  support  function  and  opera¬ 
tor  overloading,  constructors  and  des¬ 
tructors,  data  hiding  through  the  use 
of  public  and  private  keywords,  or  in¬ 
line  functions.  In  this  article,  I'll  show 
how  Object  C  can  be  used  to  simplify 
the  development  of  Macintosh  re¬ 
sources,  and  I’ll  use  a  control  panel 
device  as  an  example. 

A  class  in  Object  C  is  declared  (as 
shown  in  Example  1)  where  class_name 
is  the  name  of  the  class,  and  storagejzlass 
can  be  either  direct  or  indirect.  This 
determines  whether  the  object  is  allo¬ 
cated  as  a  pointer  or  a  handle. 

To  declare  a  method,  simply  include 
the  routine’s  prototype  in  the  class  dec¬ 
laration.  Subclasses  are  defined  using 
the  syntax  shown  in  Example  2. 

Methods  are  defined  by  using  the 
class_name combined  with  the  method 
name,  separated  by  the  scope  opera¬ 
tor  ‘ :  :  ’ .  The  object  itself  is  passed  implic- 
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itiy  to  the  method,  and  can  be  refer¬ 
enced  either  explicitly  by  using  the 
keyword  this,  or  implicitly  by  referenc¬ 
ing  the  field  or  method  directly.  (All  of 
the  new  keywords  are  interpreted  in 
context,  and  do  conflict  with  variable 
naming;  for  example,  you  can  have  a 
non-object  variable  named  this,  al¬ 
though  I  wouldn't  recommend  it.) 

Objects  are  allocated  and  destroyed 
using  the  functions  new(  land  deletef  ). 
Memory  that  was  not  allocated  using 
these  functions  can  be  treated  like  an 
object,  by  using  the  functions  blessC ) 
and  blessD(  ),  respectively,  for  pointers 
and  handles.  The  final  function  is  a 
memberi  ),  which  is  used  to  determine 
whether  an  object  is  a  member  of  a 
specific  class. 

Control  Panel  Devices 

With  the  release  of  the  Macintosh  SE, 
the  Control  Panel  desk  accessory  be¬ 
came  extendible  through  the  use  of 
cdev,  a  control  panel  device.  This  al¬ 
lowed  programmers  to  add  their  own 
utilities  to  the  control  panel,  without 
using  a  precious  desk  accessory  slot 
(currently  a  maximum  of  15  desk  ac¬ 
cessories  is  allowed).  The  cdev  takes 
the  form  of  a  resource  file  that  is  placed 
in  the  Macintosh's  system  folder.  When 
the  Control  Panel  DA  is  opened,  it 
searches  the  system  folder  for  all  files 
of  type  cdev,  and  adds  them  to  its  list. 
A  cdev  must  have  a  list  of  mandatory 
resources  before  being  adopted  by  the 


control  panel.  This  list  includes  the  ‘cdev’ 
code  resource  (an  icon  used  to  repre¬ 
sent  itself  in  the  control  panel’s  list),  a 
dialog  item  list  and  ‘nrct’  resource  (which 
determine  the  cdev's  interface),  and  a 
'mach'  resource  (a  bitmask  used  to  de¬ 
termine  which  Mac  the  ‘cdev’  should 
appear  on;  for  example,  a  ‘cdev’  to 
change  menu  bar  colors,  would  not  be 
appropriate  for  a  Macintosh  without 
color  QuickDraw).  The  ‘cdev’  resource 
contains  the  code  to  implement  the  cdev 
and  is  called  from  the  control  panel  in 
the  format  shown  in  Example  3. 

The  control  panel  communicates  with 
the  ‘cdev’  by  passing  messages  pertain¬ 
ing  to  a  specific  event  or  requesting  a 
specific  action.  For  example,  when  the 
cdev  is  first  selected,  the  control  panel 
calls  the  ‘cdev’  code  resource  with  the 
InitDev  message.  The  messages  are  listed 
in  Table  1. 

OOP  and  the  Control  Panel 

Included  with  Think  C  4.0  is  an  object- 
oriented  cdev  development  shell  that  I 
will  use  to  develop  a  typical  cdev.  The 
cdev  development  shell  is  based  around 
a  cdev  class,  which  implements  the  ba¬ 
sics  of  a  control  panel  device.  To  use 
this  to  write  a  cdev,  you  must  override 
the  methods  needed  by  your  cdev.  The 
example  I  chose  (see  Listing  One,  page 
86)  uses  the  SysEnvironsf  )  routine  to 
obtain  the  current  system  information 
for  display  purposes;  basically  a  sys¬ 
tem  info  cdev. 
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To  implement  this,  you  need  to  de¬ 
fine  a  subclass  that  overrides  the  Init( ) 
method,  which  corresponds  to  the  init- 
Dev  message  passed  to  the  cdev.- 
resource  by  the  control  panel.  Also, 
you  need  to  provide  a  routine  named 
Runnable( ),  which  examines  the  envi¬ 
ronment  and  determines  whether  the 


cdev  should  be  shown  or  not.  This 
corresponds  to  the  macDev  message, 
which  cannot  be  implemented  as  a 
method  because  it  will  be  called  be¬ 
fore  the  object  is  allocated.  Finally,  the 
New  routine  must  be  provided  to  allo¬ 
cate  the  subclass  and  return  the  object 
reference. 


struct  class_name  :  storage_type  { 

variable  and/or  method  declarations  ; 


Example  1:  Declaring  an  Object  C  class 


struct  subclass_name:class_name  ( 

variable  and/or  method  declaration  ; 

/*  NOTE:  in  order  to  override  a  method  in  the  class, 
simply  redeclare  the  method  in  the  subclass  */ 

1  ! 


Example  2:  Declaring  an  Object  C  subclass 


pascal  long  cdev(  message,  Item,  numltems,  CPanellD,  ev, 
cdevValue  CPDialog  ) 

int  message,  Item,  numltems,  CPanellD  ; 

EventRecord  *ev  ; 
long  cdevValue  ; 

DialogPtr  CPDialog  ; 


Example  3:  Format  for  calling  a  cdev 


Message 

Meaning 

initDev 

initialization 

hitDev 

mouse  down  inside  of  a  cdev  dialog  item 

closeDev 

cleanup 

nulDev 

idle  time  message 

updateDev 

update  event  message 

activDev 

activate  event  message 

deActivDev 

de-activate  event  message 

keyEvtDev 

key  down  event  message 

macDev 

used  for  checking  machine  characteristics  (this  is  only  used  if  the 
'mach'  resource  does  not  define  the  environment  that  the  cdev 
should  be  used  in). 

undoDev 

the  user  selected  undo  from  the  menu. 

cutDev 

the  user  selected  cut  from  the  menu. 

copyDev 

the  user  selected  copy  from  the  menu. 

paste  Dev 

the  user  selected  paste  from  the  menu. 

clearDev 

the  user  selected  clear  from  the  menu. 

Table  1:  Messages  passed  between  the  control  panel  and  cdev 


Conclusion 

The  cdev  shell  included  with  Think  C 
4.0  makes  cdev  development  relatively 
easy.  Essentially  all  you  have  to  do  is 
write  the  application-specific  portions 
of  the  control  panel  device,  a  tech¬ 
nique  that  can  be  used  for  the  develop¬ 
ment  of  any  Macintosh  code  resources 
like  control  and  window  definition  pro¬ 
cedures,  and  even  device  drivers.  (For 
an  example  of  a  driver  shell  in  Object 

The  cdev  takes  the  form 
of  a  resource  file  that 
is  placed  in  the 
Macintosh’s  system 
folder 


C,  see  my  article  entitled  “Writing  Macin¬ 
tosh  Device  Drivers”  in  this  issue  on 
page  37.) 
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APDA  Update 

APDA  is  an  international  direct 
distribution  channel  open 
to  anyone  interested  in 
developing  Mac  products. 


panded  that  service  by  creating  three 
basic  programs  —  the  Apple  Program¬ 
mers  and  Developers  Association 
(APDA),  Apple  Associates,  and  Apple 
Partners  (formerly  Certified  Devel¬ 
opers)  — through  which  third-party  de¬ 
velopers  have  access  to  what  previ¬ 
ously  were  in-house  resources. 


Members  can  order  Apple  development 
tools,  like  the  Macintosh  Programmers 
Workshop  (MPW)  and  MacApp,  and 
documentation,  such  as  “Inside  Macin¬ 
tosh,"  and  “Macintosh  and 
Apple  II  Technical 
Notes.”  Members 


hile  enthusiasm  for  the  Macin¬ 
tosh  as  a  programming  plat¬ 
form  has  been  largely  respon¬ 
sible  for  the  more  than  3000 
currently  available  applications,  Ap¬ 
ple  realizes  that  programmers  and 
developers  need  support  if  they  are 
to  continue  producing  new  and  better 
software  for  Macintosh  (and  Apple  II) 
systems.  Although  the  company  has 
supported  developers  through  their 
Certified  Developer  program  since 
1983,  it’s  just  recently  that  Apple  ex- 
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can  also  order  third-party  development 
products  —  compilers,  development 
utilities,  and  books.  The  $20  annual 
membership  fee  includes  a  subscrip¬ 
tion  to  the  quarterly  APDAlog  product 
catalog. 

Furthermore,  says  Wendy  Tajima, 
APDA’s  marketing  manager,  APDA 
“offers  HyperCard  for  the  Macintosh 
and  Applesoft  Basic  or  Basic  compilers 
for  the  Apple  II”  for  end  users  inter¬ 
ested  in  programming.  Corporate  in- 
house  developers  can  get  MacWorksta- 
tion  and  MacAPPC,  the  tools  for  build¬ 
ing  network  and  mainframe  access  soft¬ 
ware.  And  professional  developers  of 
in-house  products  and  products  for  re¬ 
sale  have  access  to  MPW  for  the  Mac 
and  APW  for  the  Apple  II,  not  to  men¬ 
tion  development  tools  such  as  A/UX 
(Apple’s  Unix). 

APDA,  formerly  administered  by 
TechAlliance  (a  national  user  group 
based  in  Renton,  Wash.),  was  brought 
in-house  by  Apple  to  expand  services 
and  provide  additional  resources,  to 
get  closer  to  Apple’s  development 
customers,  and  to  better  coordinate  with 
other  developer-oriented  groups  within 
Apple.  This  transition,  accord  ng  o  Sue 
Espinosa  of  Apple’s  developer  chan¬ 
nels  group,  has  increased  company¬ 
wide  awareness  —  beyond  the  engi¬ 
neering  department  —  of  the  value  of 


ucts),  technical  notes,  sample  code,  hot¬ 
line  support  (non-technical),  an  Ap¬ 
pleLink  subscription  (the  proprietary 
worldwide  communication  network, 
which  includes  current  product  and 
program  information,  sample  code,  and 
technical  libraries  and  notes),  the  Ap- 
pleDirect  monthly  newsletter,  the  Ap¬ 
ple  Viewpoints  biweekly  newsletter,  an 
APDA  subscription,  and  the  Developer 
Library  discount  (optional). 

Two  publications,  Apple  Viewpoints 
(biweekly)  and  AppleDirect  (monthly), 
are  published  to  keep  developers  in¬ 
formed  of  the  latest  development-re¬ 
lated  information,  and  contain  techni¬ 
cal  and  marketing  information,  news, 
interviews,  insights  and  perspectives  on 
trends  in  the  computer  industry,  and 
information  on  future  Apple  directions. 

The  Partners  Program 

The  Apple  Partners  Program  replaces 
the  Certified  Developers  Program,  and 
targets  developers  who  intend  to  sell 
Apple-compatible  products  within  two 
years.  Participants  include  third-party 
developers,  VARs,  and  contract  pro¬ 
grammers,  among  others  (Table  2).  The 


programming  development  products. 

APDAlog  is  billed  as  an  information 
catalog  for  developers  and  program¬ 
mers.  The  first  half  of  the  magazine 
consists  of  short  articles  on  program¬ 
ming  languages  and  development  tools. 
What  follows  is  a  complete  catalog  of 
development  products,  the  majority  of 
which  are  for  the  Mac.  Through  the 
Apple  Partners  Program  and  the  Apple 
Associates  Program  (described  later), 
those  who  intend  to  develop  products 
for  resale  or  for  in-house  use  can  di¬ 
rectly  connect  with  the  people  at  Ap¬ 
ple,  for  a  fee,  of  course  (see  Table  1). 

The  Associates  Program 

Apple  created  the  Associates  Program 
in  order  to  lend  support  to  a  wider 
group  of  developers  than  was  formerly 
reached  by  the  Certified  Developer  pro¬ 
gram.  The  Associates  Program  targets 
educators,  researchers,  and  in-house 
developers,  all  of  whom  might  develop 
software  for  the  Mac  or  Apple  II  for 
their  own  use,  not  for  resale.  (See  Ta¬ 
ble  2  for  a  longer  list  of  participants.) 
Development  information  available  to 
associates  includes  system  software  and 
updates,  the  Technical  Guidebook  (con¬ 
taining  datasheets  about  Apple  prod¬ 
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benefits  of  this  program  include  all  of 
those  provided  to  associates  plus  tech¬ 
nical  support  via  electronic  mail,  the 
Marketing  Guidebook,  an  AppleLink  sub¬ 
scription  (plus  12  hours  of  connect  time, 
one  hour  per  month),  the  Marketing 
Assistance  Program  (including  the  Cus¬ 
tomer  Mailing  Program),  an  invitation 
to  the  annual  Developer’s  Conference, 
hardware  discounts  (30  -  50  percent  off 
retail),  and  leasing  and  credit  options 
for  equipment  purchase. 

One  benefit  of  being  a  partner  is  that 
Apple  provides  marketing  assistance, 
sharing  strategies  and  helps  develop¬ 
ers  analyze  potential  markets. 

Additional  Services 

Both  partners  and  associates  have  the 
option  of  purchasing  the  Macintosh  or 
Apple  II  Developer  Libraries,  which  con¬ 
sist  of  programming  manuals,  user  in¬ 
terface  guidelines,  technical  notes,  de¬ 
velopment  guidelines,  and  sample  code, 
for  an  extra  $150.  And  both  receive 
subscriptions  to  AppleLink  and  its  elec¬ 
tronic  mail  system  that  connects  devel¬ 
opers  not  only  with  Apple,  but  with 
other  developers,  VARs,  Apple  dealers, 
and  user  groups.  Apple  partners  can 
connect  with  the  Developer  Technical 
Support  through  this  service  and  reach 
engineers  who  are  there  to  help  solve 


Table  2:  Support  to  various  groups 
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problems,  answer  questions,  or  address 
concerns.  Participants  in  both  programs 
receive  advance  copies  of  new  ver¬ 
sions  of  Apple  system  software  in  or¬ 
der  to  conduct  compatibility  testing. 

Also  available  to  partners  and  asso¬ 
ciates  are  the  courses  on  Mac  program- 

Apple  has  created 
three  basic  programs 
through  which 
third-party  developers 
have  access  to  what 
previously  were 
in-house  resources 


ming  at  Apple’s  Developer  University, 
which  runs  from  two  to  five  days,  and 
costs  between  $900  and  $1420.  Though 
all  are  available  in  Cupertino,  Calif 


others  are  available  in  locations  through¬ 
out  the  U.S.  The  curriculum  includes 
Macintosh  Programming  Fundamentals, 
Advanced  Macintosh  Programming, 
MPW  (Macintosh  Programmers  Work¬ 
shop  development  system),  Technical 
Introduction  to  AppleTalk,  and  MacApp 
and  Object-Oriented  Programming. 

Beneath  the  umbrella  of  the  Devel¬ 
oper  Group  are  Developer  Services, 
including  programs,  technical  support, 
special  events,  the  university,  and  the 
press.  This  includes  “evangelism,”  which 
targets  developers  who  are  implement¬ 
ing  key  products  and  provides  them 
with  product-design  assistance  during 
all  phases  of  the  product  development 
cycle,  such  as  guidance  on  standards 
compliance,  competitive  analysis,  and 
international  marketing.  The  Developer 
Tools  Product  Marketing  is  another 
branch;  it  works  with  Apple  develop¬ 
ment  tools  engineers  and  with  third 
parties  to  make  development  systems 
and  tools  available.  And  developer  tech¬ 
nical  publications  produces  technical 
books  and  manuals  that  describe  Apple 
products  and  development  techniques. 

Apple  currently  has  about  10,000  reg¬ 
istered  developers  working  on  new  soft¬ 
ware  and  hardware.  With  an  installed 
base  of  over  two  million  Macintosh 
computers,  the  market  is  definitely  there. 


How  to  Join 

APDA 

Apple  Computer,  Inc. 

20525  Mariani  Ave.  MS  33G 
Cupertino,  CA  93014 
800-282-2732  (in  U.S.) 

800-637-0029  (in  Canada) 
408-562-3910  (elsewhere) 

(APDA  offers  a  free  introductory 
issue  of  APDAlog  to  those  interested 
in  joining.) 

Developer  Programs 
Apple  Computer,  Inc. 

20525  Mariani  Ave.  MS  51W 
Cupertino,  CA  95014 
408-974-4897 

Developer  University  Registrar 
Apple  Computer,  Inc. 

20525  Mariani  Ave.  MS  51M 
Cupertino,  CA  95014 
408-974-6215 


DDJ 

Vote  for  your  favorite  feature/article. 

Circle  Reader  Service  No.  9. 
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Partners 

Associates 

Program 

Program 

Macintosh  or  Apple  II  development  materials  with  the 
developer  library 

$750 

$500 

Macintosh  or  Apple  II  development  materials  without 
the  developer  library 

$600 

$350 

Annual  renewal  fee 

$600 

$350 

Table  1:  Apple's  Developer  Group  program  fees 


Partners  Program 

Associates  Program 

Third-party  developers 

Educators 

Value-added  resellers 

Researchers 

Systems  integrators 

MIS  professionals 

Original  equipment  manufacturers 

In-house  developers 

Software  publishers 

Computer  consultants 

Contract  programmers 

Industry  analysts 

Dealer-supported  VARs 

Computer  training  providers 

Computer  accessory  manufacturers 
Writers  of  Apple-related  books 

Distributors  of  Apple-related  products 

COLOR  QUICKDRAW 


Listing  One  (Text  begins  on  page  8.) 


PROGRAM  ShowColors; 

|  (  A  color-smart  application  by  Chris  Derossi  for  Dr.  Dobb's  Journal. 

This  nifty  little  utility  displays  the  color  table  currently  set  for  each 
display  device.  It  uses  a  single  window  which  can  be  moved  onto  any  monitor, 
and  grown  to  any  size.  The  window  is  also  allowed  to  lie  across  multiple 
monitors;  each  monitor-window  intersection  is  drawn  separately. 

If  a  particular  device  does  not  have  a  color  table  (it  is  not  a 
CLUT  or  Fixed  device),  then  that  portion  of  the  window  is 
filled  with  50%  gray.  If  there  is  not  enough  room  to  display  a 
device's  entire  color  table,  the  window  remains  white. 

The  window  is  initially  made  visible  on  what  the  program 
considers  to  be  the  best  device  for  displaying  color.  ) 

USES 

Memtypes,  OSIntf,  Toollntf,  QuickDraw,  Palettes; 

PROCEDURE  _DataInit;  (Declared  so  we  can  reference  it  later.) 

EXTERNAL; 

CONST 

applelD  -  128;  (Standard  Apple  menu) 

filelD  =  129;  (File  menu  for  Quit  command) 

edit ID  =  130;  (Edit  menu  for  DAs) 


(The  ID  of  our  single  window) 
(The  About  ShowColorsI  Dialog) 
(The  ID  of  the  error  alert) 


applelD 

- 

128 

filelD 

= 

129 

editID 

- 

130 

appleM 

1 

fileM 

— 

2 

editM 

= 

3 

menuCount 

=> 

3 

kWindowID 

= 

128 

kAboutMeDLOG 

= 

128 

kNoColorlD 

= 

129 

undoCommand 

= 

1 

cutCommand 

= 

3 

copyCommand 

= 

4 

pasteCommand 

= 

5 

clearCommand 

■ 

6 

aboutMeCommand 

= 

1 

quit Command 

= 

1 

mBarHeight 

$BAA, 

TYPE 

IntPtr 

VAR 

myMenus 

dragRect 

newSize 

doneFlag 

wRecord 

myWindow 


(About  ShowColorsI  item  in  the  Apple  menu) 
(Quit  command  in  the  File  menu) 


ARRAY  [1 . .menuCount)  OF  MenuHandle; 
Rect  ; 

Longlnt; 

BOOLEAN; 

WindowRecord; 

WindowPtr; 


f$S  Initialize) 

PROCEDURE  SetUpMenus; 

VAR 

i  :  Integer; 

BEGIN 

myMenus [appleM]  :=  GetMenu (applelD) ; 

AddResMenu (myMenus [appleM] ,  ' DRVR' ) ; 

myMenus [fileM]  :=  GetMenu (filelD) ; 

myMenus [editM]  :=  GetMenu {editID) ; 

FOR  i  ;=  1  TO  menuCount  DO 
InsertMenu (myMenus [i],  0); 

DrawMenuBar; 

END; 

1$S  Initialize) 

FUNCTION  FindBestDevice  :  GDHandle; 

{  This  function  finds  what  it  considers  to  be  the  best  device  from 
the  list  of  screens  connected  to  the  Macintosh.  For  this  program, 
best  is  considered  to  be  more  colors,  and  color  is  better  than 
monochrome.  The  precise  ordering  of  goodness  is:  1-bit  mono, 

2-bit  mono,  2-bit  color,  4-bit  mono,  8-bit  mono,  4-bit  color, 

8-bit  color.  Non-CLUT  or  Fixed  devices  are  not  good  at  all  for 
this  program,  even  if  they  support  more  colors. 

To  compare  the  devices,  each  device  is  assigned  a  rating.  The 
higher  the  rating,  the  better  the  device.  To  convert  a  device's 
characteristics  into  a  rating,  we  first  convert  the  characteristics 
into  a  number,  then  use  that  number  in  a  CASE  statement  to  assign 
the  rating.  The  mapping  from  characteristics  to  integer  is  as  follows: 
bits  0..6  :  pixel  size  =  color  depth  (enough  bits  to  handle 


127  bits/pixel) 


END; 

FindBestDevice  :=  bestDevice; 

END; 

($S  Main) 

FUNCTION  PositionWindow(worldRect,  windRect  :  Rect)  :  Rect; 

{  This  function  centers  the  windRect  over  the  worldRect  in  the  horizontal 
direction,  and  places  windRect  one  third  of  the  way  down  over  worldRect 
in  the  vertical  direction.  This  positioned  rectangle  is  then  returned.) 
BEGIN 

Of fsetRect (windRect,  -windRect .left,  -windRect . top) ; 

WITH  worldRect  DO 

Of fsetRect (windRect,  (right  +  left  -  windRect . right)  DIV  2, 

(bottom  -  top  -  windRect .bottom)  DIV  3  +  top); 

PositionWindow  :=  windRect; 

END; 

($S  Initialize) 

PROCEDURE  ShowColorsInit; 

(  Initialize  the  standard  Mac  stuff  and  the  application  stuff.  For  the 
application,  the  window  needs  to  be  created  and  placed  on  the  best 
available  monitor. 

Since  this  program  requires  Color  QuickDraw,  we  check  for  its  presence  with 
SysEnvirons  before  we  try  to  open  the  window.  If  Color  QuickDraw  is  not 
present,  we  set  doneFlag  to  TRUE  which  causes  the  application  to 
terminate  right  away.) 

VAR 

mySysStuff  :  SysEnvRec; 

bestDevice  :  GDHandle; 

aRect  :  Rect; 

mbhPtr  :  IntPtr; 

dummyltem  :  Integer; 

myPalette  :  PaletteHandle; 


bit  7:0=  monochrome,  1  =  color.  ) 

VAR 

aDevice  :  GDHandle; 
bestDevice  :  GDHandle; 
aRating  :  Integer; 
bestRating  :  Integer; 

BEGIN 

bestRating  :=  0; 
aDevice  :=  GetDeviceList; 

bestDevice  :=  aDevice;  (In  case  we  donUt  find  any  good  devices) 

WHILE  aDevice  <>  NIL  DO  BEGIN 

IF  (NOT  TestDeviceAttribute (aDevice,  screenActive) )  OR 
I (aDevice" ".gdType  <>  clutType)  AND  (aDeviceA A .gdType  of ixedType) )  THEN 
aRating  :=  0 
ELSE 

CASE  BAnd (aDevice" A .gdFlags,  1)  *  128  +  aDeviceAA.gdPMapAA .pixelSize  OF 

1  :  aRating  :=  1;  (1-bit  monochrome) 

129  :  aRating  :=  2;  (1-bit  color) 

2  :  aRating  :=  3;  (2 -bit  monochrome) 

130  :  aRating  :=  4;  (2-bit  color) 

4  :  aRating  :=  5;  (4 -bit  monochrome) 

8  :  aRating  :=  6;  (8-bit  monochrome) 

132  :  aRating  :=  7;  (4-bit  color) 

136  :  aRating  :=  8;  (8-bit  color) 

END; 

IF  aRating  >  bestRating  THEN  BEGIN 
bestRating  :=  aRating; 
bestDevice  :=  aDevice; 

END; 

aDevice  :=  GetNextDevice (aDevice) ; 


mySysStuff  :  SysEnvRec; 

bestDevice  :  GDHandle; 

aRect  :  Rect; 

mbhPtr  :  IntPtr; 

dummyltem  :  Integer; 

myPalette  :  PaletteHandle; 

BEGIN 

UnLoadSeg(@_DataInit) ;  (Get  rid  of  MPWUs  data  initialization  segment) 
MaxApplZone; 

InitGraf (SthePort) ; 

InitFonts; 

FlushEvents (everyEvent,  0); 

InitWindows; 

InitMenus; 

TEInit; 

InitDialogs (NIL)  ; 

InitCursor; 

IF  SysEnvirons (1,  mySysStuff)  =  0  THEN  (Nothing)  ; 

IF  mySysStuff .hasColorQD  THEN  BEGIN 
SetUpMenus; 

(  Get  our  window  and  create  a  palette  for  it.  Our  palette  needs  to  have 
256  explicit  entries.  We  don't  care  what  the  palette  color  entries 
are,  so  we  can  pass  NIL  as  the  color  table  handle  to  NewPalette.  ) 
myWindow  :=  GetNewCWindow (kWindowID,  OwRecord,  Pointer  (-1) ) ; 
myPalette  :=  NewPalette (256,  NIL,  pmExplicit,  0) ; 

NSetPalette  (myWindow,  myPalette,  pmAllUpdates) ; 

(  Find  the  best  screen  for  our  window.  The  window  is  markes  as 
invisible  in  the  resource  template  so  we  can  move  it  before  we 
show  it .  ) 

bestDevice  :=  FindBestDevice; 

aRect  :=  bestDevice"" .gdRect;  (Device's  global  rectangle) 

IF  bestDevice  =  GetMainDevice  THEN  BEGIN  (Take  menu  bar  into  account.) 
mbhPtr  :=  IntPtr (mBarHeight) ;  (Get  ptr  to  low  memory  global) 

aRect. top  :=  aRect. top  +  mbhPtr";  (Adjust  size  of  rectangle) 

END; 

aRect  :=  PositionWindow (aRect,  myWindow" . portRect) ; 

MoveWindow (myWindow,  aRect. left,  aRect. top,  TRUE); 

ShowWindow (myWindow) ; 

SetPort (myWindow) ; 

doneFlag  :=  FALSE;  (Will  be  set  to  true  when  user  chooses  Quit) 

END  ELSE  BEGIN 

dummyltem  :=  StopAlert (kNoColorlD,  NIL); 
doneFlag  :=  TRUE; 

END; 

END; 

($S  Main) 

PROCEDURE  ShowAboutMeDialog; 

VAR 

itemHit  :  Integer; 

theDialog  :  DialogPtr; 

savedPort  :  GrafPtr; 

aRect  :  Rect; 

mbhPtr  :  IntPtr; 

BEGIN 

GetPort (savedPort) ; 

theDialog  :=  GetNewDialog (kAboutMeDLOG,  NIL,  WindowPtr!  -  1)); 

SetPort (theDialog)  ; 

aRect  :=  screenBits .bounds;  (Main  Device's  global  rectangle) 

mbhPtr  :=  IntPtr (mBarHeight) ; 

aRect. top  :=  aRect. top  +  mbhPtr";  (Adjust  for  the  menu  bar) 
aRect  :=  PositionWindow (aRect,  theDialog" .portRect) ; 

MoveWindow (theDialog,  aRect. left,  aRect. top,  TRUE); 

ShowWindow (theDialog) ; 

REPEAT 

ModalDialog (NIL,  itemHit) 

UNTIL  (itemHit  =  ok); 

DisposDialog (theDialog) ; 

SetPort (savedPort) ; 

END; 

($S  Main) 

PROCEDURE  DrawWindowContents (aWindow  :  WindowPtr); 

I  This  is  the  procedure  that  loops  through  all  of  the  screens  and  draws 
whatever  is  appropriate  for  that  screen  in  the  part  of  the  window 
which  intersects  the  screen.  Each  screen-window  intersection  is 
treated  separately.  ) 

VAR 

grayRGB  :  RGBColor; 

aDevice  :  GDHandle; 

aRect  :  Rect; 

globalWindRect  :  Rect; 

mbhPtr  :  IntPtr; 

workRect  :Rect,-  (continued  on  page  58) 


Integer; 

DialogPtr; 

GrafPtr; 

Rect; 

IntPtr; 


grayRGB 

aDevice 

aRect 

globalWindRect 

mbhPtr 

workRect 
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listing  One  (Listing  continued,  text  begins  on  page  8.) 


vCount 

hCount 

vBlockSize 

hBlockSize 

h 

BEGIN 


:  Integer; 
:  Integer; 
:  Integer; 
:  Integer; 
:  Integer; 
:  Integer; 


{  Create  a  50%  gray  color  for  filling  in  non-clut/f ixed  devices  } 

WITH  grayRGB  DO  BEGIN 
red  :=  $8000; 
green  :=  $8000; 
blue  :=  $8000; 

END; 

(  Turn  the  window's  portRect  into  global  coordinates  for  intersecting 
the  screens.  } 

globalWindRect  :=  aWindowA .portRect; 

LocalToGlobal (globalWindRect .topLeft) ; 

LocalToGlobal (globalWindRect . botRight ) ; 

{  Loop  through  all  of  the  devices,  seeing  if  we  intersect  each  one  1 
aDevice  :=  GetDeviceList; 

WHILE  aDevice  <>  NIL  DO  BEGIN 
aRect  :=  aDeviceAA .gdRect; 

IF  aDevice  =  GetMainDevice  THEN  BEGIN  (Exclude  menu  bar  from  draw. area  I 
mbhPtr  :=  IntPtr (mBarHeight) ;  (Get  a  ptr  to  the  low  memory  global) 
aRect. top  :=  aRect. top  +  mbhPtrA;  (Adjust  size  of  working  rectangle) 
END; 


IF  SectRect (aRect,  globalWindRect,  workRect)  THEN  BEGIN 

GlobalToLocal (workRect .topLeft)  ; 

GlobalToLocal (workRect .botRight) ; 

(  Figure  how  many  blocks  to  draw  to  show  whole  color  table  ) 

IF  (aDeviceAA.gdType  ■  clutType)  OR  (aDeviceAA .gdType  =  fixedTypel  THEN  BEGIN 
CASE  aDeviceA '  .gdPMapAA .pixelSize  OF 

1  :  BEGIN 
vCount  1; 
hCount  : -  2 ; 

END; 

2  :  BEGIN 
vCount  :=  2; 
hCount  :=  2; 

END; 

4  :  BEGIN 
vCount 
hCount 

END; 

8  :  BEGIN 
vCount  :: 
hCount  :: 

END; 

OTHERWISE 
vCount  :■ 

END; 

(  Size  of  blocks  be  in  the  horizontal  and  vertical  directions?  ) 
vBlockSize  :=  (workRect .bottom  -  workRect. top)  DIV  vCount; 
hBlockSize  :=  (workRect . right  -  workRect . left)  DIV  hCount; 
f  Use  the  smaller  dimension  for  both  to  keep  the  blocks  square  ) 

IF  vBlockSize  <  hBlockSize  THEN 

hBlockSize  :=  vBlockSize 


:=  4; 


16; 

16; 


-1; 


(  Uh  oh.  A  pixel  size  that  we  canUt  handle.  ) 
(Force  the  vBlockSize  to  be  less  than  zero.) 


ELSE 

vBlockSize  :=  hBlockSize; 

(  If  there  is  enough  room  to  draw  the  color  table,  then  do  it.  ) 

IF  (vBlockSize  >  0)  AND  (hBlockSize  >  0)  THEN  BEGIN 
FOR  v  :=  0  TO  vCount -1  DO 
FOR  h  :=  0  TO  hCount-1  DO  BEGIN 
PMForeColor (v  *  hCount  +  h); 

SetRect (aRect,  workRect . left  +  h  *  hBlockSize,  workRect. top  +  v  *  vBlock  Size, 
workRect . left  +  (h+1)  *  hBlockSize,  workRect. top  +  (v+1)  *  vBlock  Size); 
PaintRect (aRect) ; 

END; 

END; 

END  ELSE  BEGIN  (  Not  a  CLUT  or  Fixed  device.  Draw  gray  on  screen  ) 
RGBForeColor (grayRGB) ; 

PaintRect (workRect) ; 

END; 

END; 

aDevice  :=  GetNextDevice (aDevice) ; 

END; 

END; 


($S  Main) 

PROCEDURE  Ma inloop; 

(  This  is  the  standard  event  polling 
be  done  and  handles  the  request  or 
VAR 

dragRect  :  Rect; 

newSize  :  Longlnt; 

theChar  :  CHAR; 

myEvent  :  EventRecord; 

whichWindow  :  WindowPtr; 

BEGIN 

SystemTask; 

IF  GetNextEvenr (everyEvent,  myEvent 
CASE  myEvent. what  OF 
mouseDown : 


procedure  that  finds  out  what 
dispatches  to  the  appropriate 


)  THEN 


needs  to 
routine.  ) 


CASE  FindWindow (myEvent . where,  whichWindow)  OF 
inSysWindow;  SystemClick (myEvent,  whichWindow); 
inMenuBar:  DoCommand (MenuSelect (myEvent .where) ) ; 
inDrag:  BEGIN 

{  If  the  boundsRect  parameter  passed  to  DragWindow  looks  like  it  was 
derived  from  screenBits .bounds,  DragWindow  will  substitute  a  region 
which  represents  active  screens.  This  is  what  we  want,  since 
we  can't  pass  a  region  to  DragWindow,  we  have  to  rely  on  this  hack. 
That's  why  we  make  dragRect  equal  to  screenBits. bounds.  ) 
dragRect  :=  screenBits .bounds ; 

DragWindow (whichWindow,  myEvent .where,  dragRect); 

(  Because  dragging  window  may  change  the  device-window 

intersections,  we  force  the  window  to  be  redrawn  completely. 
This  causes  a  redraw  even  when  the  window  is  moved  only  a 
little  bit  on  the  same  screen.  A  little  more  intelligence 
could  be  added  here  to  avoid  unneeded  updating.  That's  left 
for  the  reader.  ) 

InvalRect (myWindowA .portRect) ; 

END; 

inGrow:  BEGIN 

SetRect (dragRect,  32,  32,  32766,  32766); 

newSize  :=  GrowWindow (whichWindow,  myEvent .where,  dragRect); 

IF  Longlnt (newSize)  <>  0  THEN  BEGIN 
SizeWindow (whichWindow,  LoWord (newSize) ,  HiWord (newSize) ,  TRUE); 
InvalRect (myWindowA . portRect )  ; 

END; 

END; 

inContent:  BEGIN 

IF  whichWindow  <>  FrontWindow  THEN 
SelectWindow (whichWindow) ; 


END; 

END;  (of  mouseDown  case) 
keyDown,  autoKey: 

IF  myWindow  =  FrontWindow  THEN  BEGIN 

theChar  :=  CHR(BAnd (myEvent. message,  charCodeMask) ) ; 

IF  BAnd (myEvent .modifiers,  cmdKey)  <>  0  THEN 
DoCommand (MenuKey (theChar) ) ; 

END; 

activateEvt ; 

IF  WindowPtr (myEvent .message)  =  myWindow  THEN  BEGIN 
IF  BAnd (myEvent .modifiers,  activeFlag)  <>  0  THEN  BEGIN 
DisableltemfmyMenus [editM] ,  0) ; 

END  ELSE  BEGIN 

Enableltem (myMenus [editM] ,  0); 

END; 

DrawMenuBar; 

END; 

updateEvt : 

IF  WindowPtr (myEvent .message)  =  myWindow  THEN  BEGIN 
BeginUpdate (myWindow) ; 

EraseF.ect  (myWindowA  .portRect)  ; 

DrawWindowContents (myWindow) ; 

EndUpdate (myWindow) ; 

END; 

END;  (of  myEvent. what  cases) 

END; 


($S  Main) 

BEGIN  (ShowColors) 
ShowColorsInit; 

WHILE  NOT  doneFlag  DO 
Mainloop; 

END. 


($S  Main) 

PROCEDURE  DoCommand (mRe suit : 
VAR 


theltem 

theMenu 

name 

temp 

dummyBool 

BEGIN 


:  Integer; 
:  Integer; 
:  Str255; 

:  Integer; 
:  Boolean; 


Longlnt) ; 


theltem  :=  LoWord (mResult) ; 
theMenu  :=  HiWord (mResult) ; 

CASE  theMenu  OF 
applelD: 

IF  (theltem  -  aboutMeCommand)  THEN 
ShowAboutMeDialog 
ELSE  BEGIN 


Get Item (myMenus [appleM] ,  theltem, 
temp  :=  OpenDeskAcc (name) ; 

SetPort (myWindow) ; 

END; 
f ilelD: 

CASE  theltem  OF 


name) ; 


quitCommand  :  doneFlag  ;=  TRUE; 

END; 

editID: 

dummyBool  :=  SystemEdit (theltem  -  1); 

END; 

HiliteMenu (0) ; 

END; 


End  Listing  One 


Listing  Two 


*  ShowColors  -  A  sample  color-smart  application 

*  by  Chris  Derossi  for  Dr.  Dobb's  Journal.  MPW  C  Version. 

*  This  nifty  little  utility  displays  the  color  table  currently  set  for  each 

*  display  device.  Uses  a  single  window  which  can  be  moved  onto  any  monitor, 

*  and  grown  to  any  size.  The  window  is  also  allowed  to  lie  across  multiple 

*  monitors;  each  monitor-window  intersection  is  drawn  separately. 

*  If  a  particular  device  does  not  have  a  color  table  (not  a  CLUT  or  Fixed 

*  device),  then  that  part  of  the  window  is  filled  with  50%  gray.  If  there  is 

*  not  enough  room  to  display  a  deviceUs  entire  color  table,  window  remains 

*  white.  Window  is  initially  made  visible  on  what  the  program  considers  to 

*  be  the  best  device  for  displaying  color. 

*/ 

((include  <types.h> 
tinclude  <memory.h> 

((include  <events.h> 

((include  <osevents.h> 
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Listing  Two  (Listing  continued,  text  begins  on  page  8.) 

grayRGB. green  =  0x8000; 
grayRGB.blue  =  0x8000; 

//  Turn  window's  portRect  into  global  coordinates  for  intersecting  screens. 
globalWindRect  =  aWindow->portRect; 

LocalToGlobal ( (Point  *) &globalWindRect .top) ; 

LocalToGlobal ( (Point  *) &globalWindRect .bottom) ; 

//  Loop  through  all  of  the  devices,  seeing  if  we  intersect  each  one. 
aDevice  =  GetDeviceList () ; 
while  (aDevice)  { 
aRect  =  (“aDevice)  .gdRect; 

if  (aDevice  ==  GetMainDevice () )  //  Exclude  menu  bar  from  drawable  area 

aRect. top  +=  MBarHeight;  //  Adjust  size  of  working  rectangle 

if  (SectRect (4aRect,  figlobalWindRect,  &workRect) )  {  //  Window  intersects. 
GlobalToLocal ( (Point  *) SworkRect.top) ; 

GlobalToLocal ( (Point  *) sworkRect .bottom) ; 

//  Figure  out  how  many  blocks  to  draw  to  show  the  whole  color  table 
if  ( ( (**aDevice) .gdType  «■  clutType)  I!  ( (“aDevice) .gdType  ==  fixedType))  f 
switch  ( (“  (“aDevice)  .gdPMap)  .pixelSize)  ( 
case  1: 
vCount  =1; 
hCount  =  2; 
break; 
case  2 : 

vCount  =  hCount  -  2; 
break; 
case  4: 

vCount  -  hCount  =  4; 
break; 
case  8: 

vCount  =  hCount  =  16; 
break; 

default:  //  Uh  oh.  A  pixel  size  that  we  canUt  handle. 

vCount  =  -1;  //  Will  force  the  vBlockSize  to  be  less  than  zero. 

1 

//  How  big  will  the  blocks  be  in  horizontal  and  vertical  directions? 
vBlockSize  =  (workRect. bottom  -  workRect.top)  /  vCount; 
hBlockSize  =  (workRect. right  -  workRect . left)  /  hCount; 

//  Use  the  smaller  dimension  for  both  to  keep  the  blocks  square 
if  (vBlockSize  <  hBlockSize) 
hBlockSize  -  vBlockSize; 
else 

vBlockSize  -  hBlockSize; 

//  If  there  is  enough  room  to  draw  the  color  table,  then  do  it. 
if  ((vBlockSize  >  0)  &&  (hBlockSize  >0))  { 
for  (v  =  0;  v  <  vCount;  v++) 
for  (h  =  0;  h  <  hCount;  h++)  ( 

PmForeColor (v  *  hCount  +  h); 

SetRect (& aRect,  workRect. left  +  h  *  hBlockSize, 
workRect.top  +  v  *  vBlockSize, 
workRect. left  +  (h+1)  *  hBlockSize, 
workRect.top  +  (v+1)  *  vBlockSize); 

PaintRect (&aRect) ; 

} 

1 

1  else  (  //  Not  a  CLUT  or  Fixed  device.  Draw  gray  on  this  screen. 

RGBForeColor (SgrayRGB) ; 

PaintRect (SworkRect) ; 

) 

> 

aDevice  =  GetNextDevice (aDevice) ; 


void  DoCommand(mResult) 
long  mResult; 

{ 

short  theltem; 
short  theMenu; 
char  name [256]; 
theltem  =  LoWord (mResult) ; 
theMenu  =  HiWord (mResult ) ; 
switch  (theMenu)  ( 
case  applelD: 

if  (theltem  ==  aboutMeCommand) 

ShowAboutMeDialogO ; 
else  { 

Get Item (myMenus [appleM] ,  theltem,  name); 

OpenDeskAcc (name) ; 

SetPort (myWindow) ; 

} 

break; 

case  filelD: 
doneFlag  =  true; 
break; 

case  editID: 

SystemEdit (theltem  -  1) ; 
break; 

} 

HiliteMenu(O) ; 

} 

void  MainloopO 

/*  Standard  event  polling  procedure  that  finds  out  what  needs  to  be  done 
*  and  handles  the  request  or  dispatches  to  the  appropriate  routine. 

*/ 

{ 

Rect  dragRect ; 

long  newSize; 

char  theChar; 

EventRecord  myEvent; 

WindowPtr  whichWindow; 

SystemTask () ; 

if  (GetNextEvent (everyEvent,  &myEvent) ) 
switch  (myEvent. what)  { 
case  raouseDown: 


switch  (FindWindow (myEvent .where,  &whichWindow) )  { 
case  inSysWindow: 

SystemClick (SmyEvent,  whichWindow) ; 
break; 

case  inMenuBar: 

DoCommand (MenuSelect (myEvent .where) ) ; 
break; 

case  inDrag: 

//  If  boundsRect  parameter  passed  to  DragWindow  looks  like  it  was 
//  derived  from  screenBits .bounds,  DragWindow  substitutes  region 
//  which  represents  all  of  the  active  screens.  We  want  this,  since 
//  we  can't  pass  a  region  to  DragWindow,  we  have  to  rely  on  hack. 
//  That's  why  we  make  dragRect  equal  to  screenBits .bounds. 
dragRect  =  qd. screenBits .bounds; 

DragWindow (whichWindow,  myEvent .where,  sdragRect); 

//  Because  dragging  the  window  may  change  the  device-window 
//  intersections,  window  is  redrawn  completely.  This  causes 
//a  redraw  even  when  the  window  is  moved  on  the  same 
//  screen.  More  intelligence  could  be  added  here  to  avoid  unneeded 
//  updating.  That's  left  for  the  reader. 

InvalRect (&myWindow->portRect)  ; 
break; 

case  inGrow: 

SetRect (fidragRect,  32,  32,  32766,  32766); 

newSize  =  GrowWindow (whichWindow,  myEvent .where,  SdragRect) ; 

if  (newSize)  { 

SizeWindow (whichWindow,  LoWord (newSize) ,  HiWord (newSize) ,  true); 
InvalRect (6myWindow->portRect) ; 

) 

break; 

case  inContent: 

if  (whichWindow  !=  FrontWindow ( ) ) 

SelectWindow (whichWindow) ; 
break; 

)  //  end  of  mouseDown  case 
case  keyDown: 
case  autoKey: 

if  (myWindow  ==  FrontWindow () )  ( 

theChar  =  (myEvent .message  &  charCodeMask) ; 
if  (myEvent .modifiers  &  cmdKey) 

DoCommand (MenuKey (theChar) ) ; 

) 

break; 

case  activateEvt: 

if  (myEvent. message  ==  myWindow)  ( 
if  (myEvent .modifiers  &  activeFlag)  ( 

Disableltem (myMenus [editM] ,  0); 

)  else  ( 

Enableltem (myMenus [editM] ,  0); 

} 

DrawMenuBar () ; 

) 

break; 

case  updateEvt: 

if  (myEvent. message  ==  myWindow)  ( 

BeginUpdate (myWindow)  ; 

EraseRect (&myWindow->portRect) ; 

DrawWindowContents (myWindow) ; 

EndUpdate (myWindow) ; 

) 

break; 

)  //  end  of  myEvent. what  cases 

I 

void  main() 

( 

ShowColorsInit ( )  ; 
while  (! doneFlag) 

MainloopO  ; 

) 


End  Listing  Two 


Listing  Three 


/*  ShowColors.r  -  Rez  source  for  the  color-smart  program 
*  by  Chris  Derossi  for  Dr.  Dobb's  Journal 
*/ 

♦include  "Types. r" 

/*  These  define' s  are  used  in  the  MENU  resources  to  disable  specific 
menu  items.  */ 

♦define  Allltems  Obi 1 1 11 1 1 1 1 1 1 1 L 1 1 1 1 1 111 1 1 1 11 1 11 11  /*  31  flags  */ 

♦define  Menulteml  ObOOOOl 

♦define  Menultem2  ObOOOlO 

type  'ShCo'  as  'STR  '; 

resource  'ShCo'  (0)  { 

"ShowColors  Application.  Copyright  )  1989  Chris  Derossi" 

}; 

resource  'WIND'  (128,  "Colors  Window")  ( 

(40,  10,  200,  170), 
documentProc, 
invisible, 
noGoAway, 

0x0, 

"Colors  Window" 

}; 

resource  'DLOG'  (128,  purgeable)  ( 

(40,  40,  200,  340), 
altDBoxProc, 
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invisible, 

noGoAway, 

0x0, 

128, 

"About  ShowColorsI  Dialog" 


resource  'DITL'  (128,  purgeable)  i 

(  /*  array  DITLarray:  4  elements  */ 

/*  [1]  */ 

{0,  0,  160,  300), 

Userltem  1 
enabled 

}, 

/*  [2]  */ 

(17,  4,  37,  294), 

StaticText  ( 
disabled, 

"ShowColors  Color-Smart  Sample  Application" 

), 

/*  [3]  */ 

{113,  24,  132,  211), 

StaticText  { 
disabled, 

"by  Chris  Derossi  for  Dr.  DobbUs  Journal" 

), 

/*  (4)  */ 

(58,  129,  90,  161), 

Icon  ( 

disabled, 

128 


$"00  00  00  00  00  00  00  00  00  00  00  00  7F  FF  00  00 
$"80  00  80  00  80  00  80  00  FF  FF  80  00  AA  AA  80  00 
$"D5  55  80  00  AA  AA  80  00  D5  FF  80  00  AB  00  80  00 
$"D5  FF  80  00  AB  00  80  00  D5  00  BF  FE  AB  00  CO  6B 
$"D5  00  CO  55  AB  00  CO  6B  D5  00  CO  55  AB  00  CO  6B 
$"D5  00  CO  55  AB  00  CO  6B  D5  00  CO  55  AB  00  CO  6B 
$ "D5  FF  FF  D5  AA  AA  EA  AB  D5  55  D5  55  7F  FF  3F  FE 


resource  'ICN#'  (128)  { 

{  /*  array:  2  elements  */ 

/*  (1)  */ 

$"00  00  00  00  00  00  00  00  00 

$"00  00  00  00  00  00  00  00  00 

$"80  00  80  00  80  00  80  00  FF 

$*D5  55  80  00  AA  AA  80  00  D5 

$“D5  FF  80  00  AB  00  80  00  D5 

$"D5  00  CO  55  AB  00  CO  6B  D5 

$"D5  00  CO  55  AB  00  CO  6B  D5 

$"D5  FF  FF  D5  AA  AA  EA  AB  D5 

/*  [2]  */ 

$"00  00  00  00  00  00  00  00  00  I 

$"00  00  00  00  00  00  00  00  00 

$"FF  FF  80  00  FF  FF  80  00  FF  i 

$"FF  FF  80  00  FF  FF  80  00  FF  ! 

$"FF  FF  80  00  FF  FF  80  00  FF  ! 

$"FF  FF  FF  FF  FF  FF  FF  FF  FF  i 

$"FF  FF  FF  FF  FF  FF  FF  FF  FF  ! 

$"FF  FF  FF  FF  FF  FF  FF  FF  FF  ! 


00  00  00  00  00" 
00  7F  FF  00  00" 
00  AA  AA  80  00" 
00  AB  00  80  00" 
FE  AB  00  CO  6B" 
55  AB  00  CO  6B" 
55  AB  00  CO  6B" 
55  7F  FF  3F  FE", 

00  00  00  00  00" 
00  7F  FF  00  00" 
00  FF  FF  80  00" 
00  FF  FF  80  00" 
FE  FF  FF  FF  FF" 
FF  FF  FF  FF  FF" 
FF  FF  FF  FF  FF" 
FF  7F  FF  3F  FE" 


resource  'ALRT'  (129)  ( 

(36,  52,  114,  320), 

129, 

{  /*  array:  4  elements  */ 

/*  [1]  */ 

OK,  visible,  soundl, 

/*  (2)  */ 

OK,  visible,  soundl, 

/*  [3]  */ 

OK,  visible,  soundl, 

/*  [4]  V 

OK,  visible,  soundl 


resource  'BNDL'  (128)  ( 

' ShCo' , 

0, 

{ 

'ICN#',  (0,  128), 
'FREF',  (0,  128) 


resource  'FREF'  (128)  { 


resource  'DITL'  (129)  { 

(  /*  array  DITLarray:  2  elements  */ 

/*  [1]  V 

(50,  201,  70,  261), 

Button  ( 

enabled, 

"Okay" 

), 

/*  [2)  */ 

(8,  87,  44,  261), 

StaticText  { 
enabled, 

"ShowColors  requires  Color  QuickDraw  to  be  present. 


resource  'MENU'  (128,  "Apple",  preload)  { 

128,  textMenuProc, 

Allltems  6  ~MenuItem2,  /*  Disable  item  #2  */ 
enabled,  apple, 


"About  ShowColorsI", 

noicon,  nokey,  nomark,  plain; 


noicon,  nokey,  nomark,  plain 


resource  'MENU'  (129,  "File",  preload)  ( 
129,  textMenuProc, 

Allltems, 
enabled,  "File", 

{ 

"Quit", 

noicon,  "Q",  nomark,  plain 


resource  'MENU'  (130,  "Edit",  preload)  ( 

130,  textMenuProc, 

Allltems  &  ~ (Menultem2) ,  /*  Disable  item  #2  */ 

enabled,  "Edit", 

{ 

"Undo", 

noicon,  "Z",  nomark,  plain; 
noicon,  nokey,  nomark,  plain; 


"Cut", 

noicon, 

"Copy", 

"X", 

nomark, 

plain, 

noicon, 

"Paste", 

"C", 

nomark. 

plain, 

noicon, 

"Clear", 

"V", 

nomark. 

plain, 

resource  'SIZE'  (-1,  purgeable)  ( 
dontSaveScreen, 
ignoreSuspendResumeEvents, 
enableOptionSwitch, 
cannotBackground, 
notMultiFinderAware, 
backgroundAndForeground, 
dontGetFrontClicks, 
ignoreChildDiedEvents , 
not32BitCompatible, 
reserved, 
reserved, 
reserved, 
reserved, 
reserved, 
reserved, 
reserved, 

50  *  1024, 

50  *  1024 


End  listings 


noicon,  nokey,  nomark,  plain 


resource  'ICON'  (128)  ( 

$"00  00  00  00  00  00  00  00  00  00  00  00  00  00  00  00" 
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listing  One  (Text  begins  on  page  1 5.) 

/*  initOpenDRVR.c 

•endif 

#  John  Rosford,  National  Instruments. 

if  (  !err) 

♦  Copyright  1988,1989  National  Instruments  Corporation 

err  =  detachDriver (  pDrvrTbl,  pOwnedTbl) ; /‘detach  the  driver  resources*/ 

#  All  rights  reserved. 

ClosePort (SmyPort) ;  /*  close  my  grafPort  */ 

#  This  Macintosh  INIT  loads  device  drivers,  checking 

•ifdef  GLOBALS 

for  driver  ID  collisions.*/ 

RestoreA4 () ; 

•include  <MacTypes.h> 

•endif 

) 

•include  <Quickdraw.h> 

•include  <WindowMgr .h> 

char  * 

•include  <EventMgr.h> 

text (index,  strBuf)  /*  return  a  C  string  in  strBuf  */ 

•include  <DialogMgr .h> 

int  index; 

•include  <OSUtil.h> 

char  ‘strBuf; 

•include  <MemoryMgr .h> 

f 

•include  <Pascal.h> 

return  (  PtoCstr(  text  PStr (index,  strBuf))); 

•include  <DeviceMgr .h> 

) 

•include  <ResourceMgr .h> 

•include  <ControlMgr .h> 

char  * 

•include  <ToolboxUtil . h> 

text  PStr (index,  strBuf)  /*  return  a  Pascal  string  in  strBuf  */ 

•include  <OSUtil.h> 

int  index; 

•include  <Strings.h> 

char  ‘strBuf; 

•include  <SlotMgr.h> 

I 

•include  "initOpenDRVR.h" 

GetlndString (strBuf ,  SS_MSGS_ID,  index); /‘get  string  from  STR#  resource*/ 
return (strBuf) ; 

I 

•define  NBICONID  128 

•define  NUM  DRVRS  SizeResource (GetResource (  DRVR  TBL  TYPE, 

/**********************.*****,*****.*.*******.******.************************/ 

/*  Add  code  to  show  your  icon  */ 

DRVR  TBL  ID) ) /sizeof (struct  drvrStruct) 

showIconO 

•define  NUM  OWNED  SizeResource (GetResource (  OWNED  TBL  TYPE, 

0 

/*..***.*.*******.  ..*.*,*,.<**.*.**.*.*.******.*.***. ************************/ 

OWNED_TBL_ID) ) /sizeof (struct  ownedStruct) 

•ifdef  LSC 

getTables (  hDrvrTbl,  hOwnedTbl)  /*  Get  the  driver  tables.  */ 

/*  setup  address  register  A4  for  global  data  */ 

struct  drvrStruct  **hDrvrTbl;  /*  handle  to  the  driver  table.  */ 

•define  SetUpA4()  asm(  move.l  a4,-(sp)  \ 

struct  ownedStruct  **hOwnedTbl;  /*  handle  to  the  owned  resource  table.  */ 

move.l  a0,a4  1 

t 

•define  RestoreA4()  asm(  move.l  (sp)+,a4  ) 

Handle  hData; 

•endif 

int  err; 

char  strBuf [ 128] ; 

main () 

( 

•ifdef  DEBUG  TRACE 

struct  drvrStruct  ‘pDrvrTbl;  /*  ptr  to  drvrStruct  */ 

alertNote ( "getTables ( ) " ) ; 

struct  ownedStruct  ‘pOwnedTbl;  /*  ptr  to  ownedStruct  */ 

♦endif 

register  short  err;  /*  error  code  */ 

hData  =  GetResource!  DRVR  TBL  TYPE,  DRVR  TBL  ID);  /*  get  driver  table  */ 

int  used  id [NUM  IDS);  /*  true  if  device  driver  id  is  in  use  */ 

if {  err  =  ResError () ) { 

char  nilstr [1] ; 

alert (text (S  FAIL  GET  DRVR  TBL,  strBuf)); 

char  strBuf (256) ; 

return (  err); 

SysEnvRec  theWorld; 

); 

config  t  config; 

HLock(  hData);  /*  table  needs  to  be  locked  while  the  INIT  runs  */ 

GrafPort  myPort; 

‘hDrvrTbl  =  (struct  drvrStruct*)  ‘hData;  /*  send  pointer  back  to  caller  */ 

•ifdef  DEBUG4 

hData  =  GetResource (  OWNED  TBL  TYPE,  OWNED  TBL  ID); 

DebugStr ("\pBreak  at  MAIN+0"); 

7*  get  owned  resource  table  */ 

•endif 

if (  err  *  ResError () ) ( 

•ifdef  GLOBALS 

alert (text (S  FAIL  GET  OWNED  TBL,  strBuf)); 

SetUpA4 (); 

return  (  err); 

•endif 

); 

InitGrafl  sthePort);  /*  initialize  quickdraw  global  variables  */ 

HLock(  hData);  /*  table  needs  to  be  locked  while  the  INIT  runs  */ 

OpenPort (SmyPort) ;  /*  make  myPort  the  current  grafPort  */ 

•hOwnedTbl  =  (struct  ownedStruct*)  *hData;  /*  send  pointer  back  to  caller  */ 

/*  Other  toolbox  managers  are  initialized  when  needed  for  dialogs.  */ 

return  err; 

nilstr [0]=' \0' ;  /*  make  a  nil  string  */ 

•ifdef  DEBUG4 

/*  Copy  in  user  configuration  from  resources  */ 

alertNote ("Number  of  owned  resources:  %d",  (int)NUM  OWNED); 

configlnfo (config) 

•endif 

register  config  t  ‘config;  /*  pointer  to  the  configuration  data  */ 

err  =  noErr;  /*  start  with  no  error  •/ 

( 

showIcon();  /*  display  the  icon  */ 

register  short  err; 

if(  kill  keyO)  /*  True  if  User  abort  key  combination  •/ 

Handle  DefBoardsH;  /*  default  board  data  resource  */ 

/*  question:  abort  the  init?  */ 

register  BusResource  *BP;  /*  pointer  to  bus  data  */ 

if(  err  =  qAbort (  text  PStr(S  Q  USER  ABORT,  strBuf),  nilstr,  nilstr)) 

char  TheString[256] ;  /*  storage  for  message  string  */ 

alert  {  text (S  USER  ABORT,  strBuf));  /*  yes,  abort  */ 

if(  !err) 

•ifdef  DEBUG  TRACE 

SysEnvirons(  1,  stheWorld) ;  /*  what  environment  is  the  init  */ 

alertNote ( "configlnfo () ") ; 

/*  running  in?  */ 

•endif 

if (  !err)( 

slotlnfoTable (config) ;  /*  fill  in  brdName  and  brdID  for  each  NB  slot  */ 

if(  err  =  (theWorld. machineType<envMacII  && 

/*  Load  default  configuration  */ 

theWorld. machineType ! =envMachUnknown) )  /*envMacII*/ 

DefBoardsH  =  GetResource (BUS  DATA  TYPE, BUS  DATA  ID); 

alert (  text(S  NEED  MAC  II,  strBuf));  /•  my  drivers  need  a  Mac  II  */ 

/*  get  the  bus  data  resource  */ 

} 

if  (DefBoardsH  ==  NULL)  ( 

if(  !err) 

alert (text (S  FAIL  GET  DATA,  TheString) ) ; 

getTables!  spDrvrTbl,  spOwnedTbl);  /*  Get  the  driver  tables.  */ 

return  -1; 

if(  !err) 

I 

err  =  conf iglnfo (sconf ig) ; /*  Copy  in  user  configuration  from  resources  */ 

HLock  (DefBoardsH) ;  /*  lock  data  resource  until  we  read  */ 

if (  !err) 

/*  it  into  local  variables  */ 

err  =  markLoad(  pDrvrTbl, Sconf ig) ;  /*  mark  drivers  that  need  loading.  */ 

BP  =  (BusResource*)  ‘DefBoardsH; 

•ifndef  DEBUG3 

err  =  configBrdsI  BP, config);  /*  read  bus  configuration  data  */ 

if(  !err) 

if(  err) 

err  =  dupDriverlnstalled (  pDrvrTbl);/*  check  for  duplicate  drivers  */ 

return (err) ;  /*  failed  */ 

•endif 

HUnlock (DefBoardsH) ;  /*  unlock  data  resource  */ 

if(  !err) 

ReleaseResource (DefBoardsH) ;  /*  release  the  resource  */ 

err  =  checkSysHeapSize (  pDrvrTbl,  pOwnedTbl) ; /*is  there  enough  memory?*/ 

return  noErr; 

if(  !err) 

) 

err  =  findUsedIDs(  used  id);  /*  find  all  IDs  used  in  the  system  */ 

if(  !err) 

configBrds(  BP, config) 

err  =  checkIDs (  pDrvrTbl,  pOwnedTbl,  used  id); 

register  BusResource  *BP; 

/*  check  the  IDs  of  the  INIT's  drivers  */ 

register  config  t  ‘config; 

if(  ! err) { 

f 

if(  err  =  openMarkedDrivers (  pDrvrTbl, Sconf ig) ) 

register  short  bus, MaxBuses; 

/*  open  drivers  that  need  loading  */ 

•ifdef  DEBUG  TRACE 

•ifdef  DEBUG1 

alertNote ("conf igBrds ( ) ") ; 

♦endif 

MaxBuses  =  conf ig->MaxBuses  =  BP->Cnt;  /*  get  number  of  buses  we  */ 

/*  have  data  for  */ 

if (  BP->Rev  ! =  BOARDREV) { 

alertNote ("After  openMarkedDrivers,  Will  load  %s",  pDrvrTbl [i] .name) ; 

alert (text (S_FAIL_REVISION,  strBuf) ) ; 

return  e_brdrev;  (continued  on  page  64) 
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1NIT  COLLISIONS 


Listing  One  (Listing  continued,  text  begins  on  page  15  ) 

for  (bus=0;  bus<MaxBuses;  bus++)  {  /*  for  each  bus,  copy  the  data  */ 

default : 

config->brdRsrc.BusData[bus] .b  uflags  =  BP->BusData [bus] .b  uflags; 

/*  error  if  there  is  an  unknown  type  in  the  table  */ 

config->brdRsrc.BusData[busj .b  slot  =  BP->BusData [bus] .b  slot; 

alertNote (text (S  NOT  DRVR  TYPE,  strBuf),  drvrTbl [i] .type,  i) ; 

/*  if  the  bus  is  associated  with  a  serial  slot,  copy  the  extra  data  */ 

err  =  1; 

if(  isSerSlot (config->brdRsrc.BusData[bus] .b  slot))[ 

break; 

config->brdRsrc.BusData [bus] .b  baud  =  BP->BusData [bus] .b  baud; 

} 

I 

) 

} 

tifdef  DEBUG 1 

alertNote ("Show  drivers  marked  for  loading"); 

tifdef  DEBUG1 

for (  i=0;  i<NUM  DRVRS;  ++i) 

for  (bus=0;  bus<MaxBuses;  bus++)  ( 

if(  drvrTbl [i] . load)  /*  all  are  YES  or  NO  at  this  point  */ 

if (config->brdRsrc .BusData [bus] .b  slot) [ 

alertNote ("Marked  %s",  drvrTbl [i' .name) ; 

/*  alert:  4  int  args  max  */ 

alertNote ("configBrds :  bus  %d  with  slot  %d",  bus, 

tendif 

config->brdRsrc. BusData [bus] .b  slot); 

return  err; 

alertNote ("configBrds:  uflags  %x", 

) 

BP->BusData[bus] .b  uflags); 

1 

/*  Input:  driver  type.  Output:  its  drvrTbl  index.  */ 

1 

ndxDrvrType (  drvrTbl,  type) 

tendif 

struct  drvrStruct  ‘drvrTbl; 

return (noErr) ; 

1 

short  type; 

( 

register  unsigned  short  i; 

/*  Mark  the  drivers  and  owned  resources  that  will  need  to  be  loaded. 

*  Look  at  the  boards  to  determine  which  to  load. 

for  (  i=0;  i<NUM  DRVRS;  ++i) 

*  All  drivers  will  be  mark  either  YES  or  NO. 

if(  type  ==  drvrTbl [ i ] .type  ) 

*  Always  returns  noErr. 

return  i; 

*/ 

return  0; 

1 

markLoad(  drvrTbl, conf ig) 

struct  drvrStruct  * drvrTbl; 

/*  Input:  driver  id.  Output:  its  drvrTbl  index.  */ 

register  config  t  *config; 

drvrID2index(  drvrTbl,  id) 

f 

struct  drvrStruct  ‘drvrTbl; 

register  short  i,  k,  err,  bus;  /*  loop  counters,  error,  and  bus  number  */ 

register  short  id; 

char  strBuf[128];  /*  storage  for  message  strings  */ 

( 

register  short  i; 

#ifdef  DEBUG  TRACE 

char  strBuf [128]; 

alertNote ( "markLoad ( ) " ) ; 

tendif 

for (  i=0;  i<NUM  DRVRS;  ++i) 

err  =  noErr; 

if(  drvrTbl[i] .id  ==  id) 

for(  i=0;  i<NUM  DRVRS;  ++i) {  /*  Check  boards  before  anything  else.  */ 

return  i; 

short  brdID;  /*  board  ID  variable  */ 

alert (text (S  FAIL  NO  DRVR,  strBuf),  id); 

brdID  =  drvrTbl [i] .type;  /*  driver  type  can  be  a  board  ID  */ 

return  0; 

switch (  brdID) {  /*  which  board  ID?  */ 

} 

case  NB  GPIB: 

case  NB  DMA  8: 

/*  Slot  number  range  1-n  while  bus  numbers  range  0-m  */ 

drvrTbl [i] . load  =  getSlot(  brdID, conf ig) ; 

/*  return  slot  if  board  whose  id=brdID  is  found,  else  0  */ 

/*  mark  if  board  is  in  any  slot  */ 

getSlot (  brdID,  config) 

break; 

register  unsigned  short  brdID; 

case  T  SERIAL  HW: 

register  config  t  ‘config; 

/*  Load  if  any  bus  is  configured  as  a  serial  slot:  */ 

{ 

/*  GPIB-422CT,  GPIB -MAC  */ 

register  unsigned  short  i; 

for(  k=0;  k<conf ig->MaxBuses;  ++k) [ 

if (  isSerSlot (conf ig->brdRsrc . BusData [k] .b  slot))! 

for  (i-1;  i<=NSLOTS;  i++)  { 

drvrTbl [i] .load  =  true; 

if (  brdID  ==  config->slotInfo[i-l) .brdID  ) 

#ifdef  DEBUG1 

return  i; 

alertNote ("Load  serial  slot  %d,  bus  %d", config->brdRsrc. BusData [k]  .b  slot,k); 

) 

#endif 

#ifdef  DEBUG4 

break; 

alertNote(  "No  slot  for  brdID:  0x%x",  brdID); 

) 

tendif 

) 

return  0; 

break; 

) 

default : 

/*  Take  no  action  here  if  type  is  not  a  brdID.  */ 

/*  Types  will  be  checked  below.  */ 

/*  return  the  slot  of  the  (bus)th  GPIB  board  in  the  machine.  */ 

break; 

autoSlot (  bus, config) 

) 

int  bus; 

) 

register  config_t  ‘config; 

/*  Loading  the  master  driver  depends  only  on  the  boards  */ 

register  unsigned  short  i,  brdID; 

/*  but  not  the  serial  driver.  */ 

i  =  ndxDrvrType(  drvrTbl,  T  DRVR  MASTER) ; /‘get  index  of  the  master  driver*/ 

if(  0<=bus  &&  bus<NBUSES) { 

drvrTbl [i] .load  =  L  NO; 

for  (i-1;  i<=NSLOTS;  i++) ( 

for (  k=0;  k<NUM  DRVRS;  ++k) 

brdID  =  config->slotInfo [i-1 ] .brdID; 

/*  mark  the  master  driver  if  any  other  driver  except  */ 

if (brdID==NB  GPIB  ! !  brdID==NB  DMA  8) 

/*  the  serial  or  NB-GPIB  driver  is  marked  */ 

if (  !bus — )  /*  example:  bus  1  will  return  slot  of  first  match  */ 

if (  drvrTbl [ k ] . load  &&  drvrTbl [k] .type ! =T  SERIAL  HW  && 

return  i; 

drvrTbl [k] .load  !=  NB  GPIB) { 

> 

drvrTbl [i] .load  =  L  YES; 

) 

break; 

tifdef  DEBUG4 

} 

else 

bus  =  0; 

alertNote ("Bad  parameter:  autoSlot (%d) ",  bus); 

for (  i=0;  i<NUM  DRVRS;  ++i) ( 

tendif 

switch(  drvrTbl [i] .type) (  /*  scan  through  the  other  driver  types  */ 

return  0; 

case  T  SERIAL  HW:  /*  ignore  serial,  board,  and  master  types  */ 

) 

case  NB  GPIB: 

case  NB  DMA  8: 

/*  Get  NuBus  slot  info  for  each  slot  */ 

case  T  DRVR  MASTER: 

slotlnfoTable (config) 

break; 

register  config  t  ‘config; 

case  T  DRVR  GPIB:  /*  load  GPIB  type  if  any  GPIB  board  or  */ 

< 

/*  serial  driver  is  marked  */ 

register  int  i; 

drvrTbl [i] . load  =  ( (drvrTbl [ndxDrvrType (drvrTbl, NB  DMA  8)]. load 

I!  drvrTbl [ndxDrvrType (drvrTbl, NB  GPIB)]. load 

for  (i-1;  i<=NSLOTS;  i++)  ( 

drvrTbl [ndxDrvrType (drvrTbl, T  SERIAL  HW)].load)  ? 

config->slotInfo[i-l] .brdID  =  GetSlotlnfo (i. 

L  YES  :  L_NO) ; 

config->slotInfo [i-1] .brdName) ; 

) 

break; 

case  T  BUS  DRVR:  /*  Load  GPIB  bus  driver  if  user  or  auto  */ 

tifdef  DEMO 

/*  configured.  */ 

config->slotlnfo[0] .brdID  =  NB  DMA  8; 

drvrTbl [i] . load  =  config->brdRsrc. BusData [bus] .b  slot; 

tendif 

bus++; 

break; 

/*  serial  slots  are  a  different  hardware  variant  */ 

case  T  BOARD  HW:  /*  Load  if  any  NI-488  resource:  */ 

conf ig->slotInfo [SSLOTA  NDX] .brdID  =  GPIBMAC; 

/*  NB-GPIB,  NB-DMA  */ 

conf ig->slotInfo [SSLOTB  NDX] .brdID  =  GPIBMAC; 

/*  if  any  GPIB  board  is  present,  then  bus  0,  the  first  bus,  */ 

) 

/*  will  have  a  slot.  */ 

drvrTbl [i] . load  =  autoSlot (0,  conf ig) ; 

break; 

/* 
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Return  boardID  and  driver  name  of  board  in  slot  'slot' 
returns  one  of  the  board  IDs  listed  in  brdIDs.h 


/*  spIDs  */ 

#define  sRsrc_Name  2 
#define  BoardID  32 
♦define  Vendorlnfo  36 
♦define  VendorlD  1 

GetSlotInfo(slot,  dName) 
int  slot; 
char  ‘dName; 

{ 

SpBlock  sBlock; 

SpBlockPtr  sp; 

int  brdID; 

OSErr  err; 

Ptr  structZero; 

struct  SPRAMRecord  ( 
short  boardID; 
char  VendorUse [6] ; 

}SPRAMRec; 

dName [0]  =  '\0'; 

sp  »  fisBlock; 

♦ifdef  DEBUG 

printf (”\n»#*f»«  slot  ♦Id  ♦♦♦♦♦♦♦\nH,  slot); 

♦endif 

sp->spSlot  =  macSlotNum (slot) ;  /*  convert  slot  to  NuBus  slot  number  */ 

sp->spResult  =  (long) SSPRAMRec; 

err  -  SReadPRAMRec (sp) ; 

♦ifdef  DEBUG 

printf ("SReadPRAMRec  err:  Id,  boardID  =  0xlx\n",  err,  SPRAMRec. boardID) ; 
♦endif 

if (  err  ==  smSlotOOBErr)  /*  slot  does  not  exist,  number  is  out  of  bounds.*/ 
brdID  =  SLOT  OUT  OF  BOUNDS; 


char  strBuf[64); 


/*  storage  for  message  string  */ 


else  if {  err) 

brdID  =  NO_BOARD ; 

else 

brdID  -  SPRAMRec. boardID; 


/*  unknown  error,  no  board.  */ 


err  =  noErr; 

/*  if  no  drivers  are  marked  for  loading 
♦  then  the  flag  should  be  anything  besides  noErr. 

*/ 

openError  =  ! noErr; 
myRefNum  =  CurResFile () ; 

numDrivers  =  NUM_DRVRS;  /*  macro  would  return  0  if  used  after  */ 

/*  UseResFile (0)  */ 

UseResFile (0) ;  /*  Use  the  System  File  only  */ 

for(  i=0;  i<numDrivers  &&  openError  !=  noF.rr;  ++i)  ( 

if(  drvrTbl (ij . load) (  /*  see  if  this  driver  already  exists  */ 

openError  =  OpenDriver(  CtoPstrf  strcpyl  strBuf, 

drvrTbl [i] .name) ) ,  &refNum) ; 
I 

) 

UseResFile (myRefNum) ;  /*  go  back  to  the  INIT  resource  file  so  we  */ 

/*  can  display  an  alert  */ 

if(  openError  —  noErr) ( 

alert  (  text ( S_FAI L_REMOVE ,  drvrTbl [i] .name) ) ; 

err  =  1;  /*  In  this  case,  no  error  is  a  failure.  */ 

} 

♦ifdef  DEBUG4 
else 

alertNote ("No  duplicate  master  driver  found,  Id.",  openError); 

♦endif 

return  err; 


/*  see  if  there  is  enough  memory  to  load  the  drivers  */ 
checkSysHeapSize (  drvrTbl,  ownedTbl) 
struct  drvrStruct  ‘drvrTbl;  /*  array  of  drvrStruct  */ 
struct  ownedStruct  ‘ownedTbl;  /*  array  of  ownedStruct  */ 

( 

register  short  i;  /*  loop  counter  */ 

register  OSErr  err;  /*  OS  error  */ 

register  Handle  hdl;  /*  resource  handle  */ 

char  strBuf (128);  /*  storage  for  message  string  */ 


sp->spSlot  =  macSlotNum (slot) ;  /*  convert  slot  to  Mac  slot  number  */ 

sp->spID  =  1; 
sp->spExtDev  =  0; 
err  =  SRsrcInfo (sp) ; 

if{  err  ==  smNoMoresRsrcs)  /*  either  no  board  or  slot  does  not  exist  */ 
brdID  =*  NO_BOARD ; 

if  (  err  ■-  noErr) 

^  structZero  =  sp->spsPointer;  /*  can  be  changed  by  other  calls  */ 

if  (  err  ==  noErr)  ( 

/*  Get  board  name  */ 

sp->spsPointer  =  structZero;  /*  restore  spsPointer  from  SNextsRsrcO  »/ 
sp->spID  =  sRsrc_Name; 
if  ( (err=SGetcString (sp) )  ==  noErr)  { 
strcat (dName,  (Ptr) sp->spResult) ; 

(else 

brdID  =  NOT  OUR  BOARD; 

} 

if  (  err  ==  noErr)  { 

♦ifdef  DEBUG 

printf ("spSlot  Id,  spID  Id,  spExtDev  ld\n", 

sp->spSlot , sp->spID, sp->spExtDev) ; 

♦endif 

/*  Track  down  vendor  name  */ 

/*  spsPointer  from  SNextsRsrcO  */ 

sp->spID  =  Vendorlnfo; 

if  ( (err=SFindStruct (sp) )  ==  noErr)  ( 

/*  spsPointer  from  SFindStruct  ()  */ 
sp->spID  =  VendorlD;  /*  vendor  name  */ 
if  ( (err=SGetcString(sp) )  ==  noErr) ( 
long  ourName(6); 
ourName [0] =' Nati' ; 
ourName[l)='onal' ; 
ourName [2]='  Ins'; 
ourName [3] ='trum' ; 
ourName (4 ] =' ents' ; 
ourName [5) =0L; 

if  (err=strcmp( (Ptr) sp->spResult,  (Ptr) ourName) ) 
brdID  =  NOT_OUR_BOARD ; 

)else 

brdID  =  NOT_OUR_BOARD ; 

(else 

brdID  =  NOT_OUR_BOARD ; 


return  brdID; 


/*  initOpenDRVRp2 . c  -  DDJ  part  2  */ 

/*  Check  for  any  existing  NI  Drivers.  */ 
dupDriverlnstalled (drvrTbl) 

struct  drvrStruct  ‘drvrTbl;  /*  pointer  to  the  driver  table  */ 

short  myRefNum,  refNum;  /*  INIT's  and  driver's  reference  numbers  */ 

register  unsigned  short  i;  /»  loop  counter  */ 

register  short  openError,  numDrivers,  err;  /*  openDriver  error,  */ 

/*  number  of  drivers,  */ 
/*  other  error  */ 


♦ifdef  DEBUG_TRACE 

alertNote ("checkSysHeapSize () ")  ; 

♦endif 

/*  Find  out  how  much  memory  is  needed  to  load  the  drivers  */ 
err  =  noErr; 

/*  while  not  err,  size  DRVRs  that  need  to  be  loaded  */ 
for (  i=0;  i<NUM_DRVRS  &&  !err;  ++i)  { 
if (  ! drvrTbl ( i ] .load) 
continue; 

hdl  =  GetResource (DRVR_TYPE,  drvrTbl [i] .id) ;  /*  read  resource  */ 

/*  into  memory  */ 

err  =  ResError(); 
if  (  ! hdl  : I  err) ( 

alert (text (S_FAIL_GET_DRVR,  strBuf),  drvrTbl [i] .name) ; 
if (  !err) 

err  =  true; 

) 


/*  while  not  err,  size  owned  resources  that  nee'd  to  be  loaded.  */ 
for (  i=0;  i<NUM_OWNED  (,(,  !err;  ++i)  { 
register  short  id; 

if(  IdrvrTbl (drvrID2index (  drvrTbl,  ownedTbl [i ). owner) ]. load) 

/*  fixed  bug:  5/13/88  */ 

continue; 

id  =  0WNED_ID (ownedTbl [ i] .owner, ownedTbl [i] . id) ;  /*  calc  owned  id  */ 

hdl  =  GetResource (ownedTbl [i] .type,  id);  /*  read  resource  */ 

/*  into  memory  */ 

err  =  ResError  () ; 
if (  ! hdl  : :  err) ( 

alert (text (S_FAIL_GET_OWNED,  strBuf),  drvrTbl [drvrID2index 

(  drvrTbl,  ownedTbl (i) .owner) ] .name) ; 
alertNote (text (S_FAIL_ID_OSERR,  strBuf),  ownedTbl [i] . id,  err) ; 
if(  ! err) 

err  =  true; 

) 


if(  err  ==  -108)  /*  if  out  of  system  heap  */ 

alert (text (S_FAIL_HEAP,  strBuf) ) ; 
else  if (  err) 

alert (text (S_FAIL_RSRC_MGR,  strBuf),  err) ; 
return  err; 


findUsedIDs(  used_id) 

int  used_id();  /*  true  if  device  driver  id  is  in  use  */ 

( 

register  short  UNtryCnt,  i,  err; 

♦ifdef  DEBUG_TRACE 

alertNote ("findUsedIDs  0 ") ; 

♦endif 

UNtryCnt  =  UnitNtryCnt;  /*  get  number  of  entries  in  Unit  Table  */ 
♦ifdef  DEBUG2 

alertNote ("Number  of  Unit  Entries:  Id.",  UNtryCnt); 

♦endif 

for (  i = START_OF_U S E R_ I D S ;  icUNtryCnt;  ++i) 

used_id[i]  =  0;  /*  clear  used  id's  */ 

/*  check  both  the  Unit  Table  and  the  system  file  */ 

err  =  checkUnitTable (  used_id);  /*  Any  test  after  this  should  OR  */ 
/*  in  the  results.  */ 

if(  !err) 

err  =  checkSysRsrcs (  used_id) ; 
return  err; 


(continued  on  page  66) 
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INIT  COLLISIONS 


Listing  One  (Listing  continued,  text  begins  on  page  15.) 

for (  i=0;  i<NUM_DRVRS  &&  !err;  ++i) { 
register  short  newID; 

/*  check  if  a  driver  of  the  same  id  already  exists  in  the  driver  Unit  Table.*/ 

if (  ! drvrTbl [i] . load) 
continue; 

drvr  =  &drvrTbl(i]; 
if(  used  id [drvr->id] )  ( 

checkUnitTable (  used  id) 

int  used_id[];  7*  true  if  device  driver  id  is  in  use  */ 

register  DCtlHandle  *UTable; 

lifdef  DEBUG2 

register  short  UNtryCnt,  i; 

/*  find  a  resource  ID  that  doesn't  conflict  with  system  */ 

alertNote ( "checkUnitTable ( )  " ) ; 

#endif 

/*  or  init  driver  IDs.  */ 

newID  =  getUnusedID(  used_id, init_id) ; 

UTable  =  UTableBase;  /*  get  base  address  of  Unit  Table  */ 

UNtryCnt  =  UnitNtryCnt;  /*  get  number  of  entries  in  Unit  Table  */ 

/*  Mark  if  this  DCtl  handle  is  not  NULL  */ 

lifdef  DEBUG2 

alertNote ( "NewID  Id.",  newID); 

lendif 

if (  newID) ( 

hdl  =  Get  1 Resource (  DRVR_TYPE,  drvr->id) ; 
if  ((hdl  ==  NULL)  II  (err  =  ResErrorO))  ( 

for {  i=START  OF  USER  IDS;  i<UNtryCnt;  ++i) ( 

used  id [ i J  =  UTable (i]  !=  NULL; 

#ifdef  DEBUG2 

if(  used_id[i]) 

alertNote ("UnitTable  ID  %d  found.",  i); 

lendif 

used_id(newID]  =  TRUE; 

err  =  changeRsrcID (  hdl,  newID);  /*  change  the  */ 

return  noErr; 

» 

/*  resource's  ID  */ 

/*  check  if  a  resource  of  the  same  type  s  id  already  exists  in 
the  system  file.*/ 
checkSysRsrcs (  used  id) 

) 

if (  !err) 

err  =  newOwner(  ownedTbl,  drvr->id,  newID);/*  update  owner  */ 

/*  of  rsrcs  */ 

/*  owned  by  drvr*/ 

int  used  id [ ] ;  /*  true  if  device  driver  id  is  in  use  */ 

{ 

register  short  i,  count,  UNtryCnt;  /*  loop  count,  number  of  resources,  */ 

/*  size  of  Unit  Table  */ 

short  id,  err;  /*  resource  id,  error  */ 

if  (  ! err) [ 

drvr->id  =  newID;  /*  change  data  in  the  tabel  rsrc  */ 

err  =  changeTableResources (  DRVRTBL) ; 

ResType  type;  /*  res  type  */ 

char  name [32];  /*  res  name  */ 

} 

register  Handle  hdl;  /*  res  handle  */ 

char  strBuf(128);  /*  string  buffer  */ 

return  err; 

) 

lifdef  DEBUG_TRACE 

alertNote ("checkSysRsrcs  () ") ; 

/*  Return  an  unused  DRVR_TYPE  id  (0  if  none)  from  the  previously 
built  used  id  table.  */ 

getUnusedID(  used_id, init_id) 

/*  UseResFileO  has  no  effect  on  GetlndResource ( )  */ 

int  ‘used  id, ‘init  id;  /*  true  if  device  driver  id  is  in  use,  true  */ 

SetResLoad (FALSE) ; 

/*  if  init  id  is  in  use.  */ 

1 

iff  !err) ( 

count  =  CountResources (' DRVR' ) ; 
err  =  ResErrorO; 

) 

register  short  id,  UNtryCnt; 
char  strBuf [128] ; 

lifdef  DEBUG  TRACE 

alertNote  ("getUnusedIDO  ") ; 

for  (i  ”  1;  i  <=  count  &&  !err;  i++)  ( 

lendif 

hdl  =  GetlndResource ('DRVR' ,  i); 
err  =  ResErrorO; 

/*  Find  a  resource  ID  that  doesn't  conflict.  */ 

UNtryCnt  -  UnitNtryCnt;  /*  Number  of  unit  entries.  */ 

if (  hdl  &&  ! err) { 

for  (id=START  OF  USER  IDS; id<UNt ryCnt  &&  (used  id [ id)  I  1  init  id [id] ) ; id++) 

GetResInfo(  hdl,  Sid,  stype,  name); 
err  =  ResErrorO; 

/*  5/31/88  used_id [ id]  JR/LG  */ 

/*  Mark  (with  prev  result)  if  this  resource  is  from  the  */ 

if  (id  ==  UNtryCnt)  ( 

/*  system  file.  */ 

alert (text (S  FAIL  NO  FREE  ID,  strBuf)); 

if (  idcUNtryCnt  &&  id>=0  &&  ! err ) { 

id  =  0;  7*  failed  */ 

used_id[id]  1=  HomeResFile(  hdl)  ==  0; 
err  =  ResError  () ; 

) 

return  id; 

#ifdef  DEBUG2 

> 

if  (used  id [ id ] ) 

alertNote ( "Marked  Driver  ID  Id  used.",  id); 

#endif 

1 

/*  update  owner  ID  of  rsrcs  owned  by  drvr  */ 
newOwner(  ownedTbl,  drvrOldID,  drvrNewID) 

lifdef  DEBUG2 

struct  ownedStruct  ‘ownedTbl;  /*  array  of  ownedStruct  */ 

else 

short  drvrOldID,  drvrNewID; 

alertNote ("Driver  ID  Id  out  of  range.",  id); 

( 

lendif 

register  short  i,  err,  old  id; 

[else 

register  struct  ownedStruct  ‘owned; 

alert (text (S  FAIL  RSRC  MGR,  strBuf) ,  err); 

register  Handle  hdl; 

) 

char  strBuf [ 128] ; 

if{  ! err)  ( 

SetResLoad (TRUE)  ; 

lifdef  DEBUG  TRACE 

err  =  ResErrorO; 

alertNote ("newOwner () ")  ; 

1 

lendif 

return  err; 

> 

err  =  noErr; 

fort  i=0;  i<NUM  OWNED  &S  !err;  ++i) ( 

owned  =  SownedTbl [ i ] ; 

checkIDs(  drvrTbl,  ownedTbl,  used  id) 

if(  owned->owner  ==  drvrOldID) ( 

struct  drvrStruct  ‘drvrTbl;  /*  array  of  drvrStruct  */ 

old  id  =  OWNED  ID (drvrOldID, owned->id) ;  /*  calc  owned  id  */ 

struct  ownedStruct  ‘ownedTbl;  /*  array  of  ownedStruct  */ 

lifdef  DEBUG2 

int  ‘used  id; 

alertNote ("GetlResource (  id  =  Id).",  old  id); 

( 

lendif 

register  short  i,  err,  k; 

hdl  =  GetlResource (owned->type,  old  id); 

register  struct  drvrStruct  *drvr; 

if  (err  =  ResError ( ) )  ( 

Handle  hdl; 

alert (text (S  FAIL  ID  CHANGE,  strBuf),  old  id,  err); 

char  strBuf (128] ; 

return (err) ; 

int  init_id[NUM_IDS] ;  /*  true  if  init  device  driver  id  */ 

short  UNtryCnt; 

1 

err  =  changeRsrcID (  hdl,  OWNED  ID (drvrNewID, owned->id) ) ; 

/*  Change  the  resource's  owner's  ID  */ 

/*  Check  all  drivers.  If  marked  for  loading,  it  must  have  a  unique  and 

if  (  !err) I 

unused  ID  within  the  system. 

owned->owner  =  drvrNewID;  /*  Change  table  rsrc  of  the  owner.  */ 

*  Else,  it  must  have  a  unique  ID  within  the  INIT. 

*  check  if  a  DRVR  of  the  same  id  already  exists. 

*  Change  the  DRVR's  ID  and  its  owned  rsrc's  ID's. 

*  Change  table  resources. 

err  =  changeTableResources (  OWNERTBL) ; 

I 

) 

) 

*/ 

return  err; 

lifdef  DEBUG  TRACE 

alertNote ("Checking  driver  ID'S."); 

lendif 

/*  If  resource  is  owned,  then  pass  in  the  real  ID,  not  the  sub  ID.  */ 

err  =  noErr; 

changeRsrcID!  rsrcHdl,  drvrNewID) 

/*  table  of  driver  ids  used  by  INIT  */ 

Handle  rsrcHdl; 

UNtryCnt  =  UnitNtryCnt; 

for (  i=START  OF  USER  IDS;  iCUNtryCnt;  ++i) 

short  drvrNewID; 

( 

init  id [ i ]  =  0;  /*  clear  init  id's  */ 

short  attr; 

for (  i=0;  i<NUM  DRVRS;  ++i) 

register  OSErr  err; 

init_id [drvrTbl [i] .id]  =  true; 

ResType  type; 
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char  name [30]; 

) 

short  drvrOldID; 

} 

char  strBuf [128] ; 

for (  i=0, bus=0;  i<NUM  DRVRS  &&  !err;  ++i)  ( 

#ifdef  DEBUG  TRACE 

if (  drvrTbl [i] .type  ==  T_BUS_DRVR) ( 
if  (  drvrTbl [i] . load) 

alertNote ("changeRsrcID {) ") ; 

err  =  openBusDriver (drvrTbl [i] .name, bus, conf ig) ; 

fendif 

bus++; 

GetResInfo(  rsrcHdl,  SdrvrOldlD,  stype,  name);  /*  get  name  */ 

) 

if  (err  =  ResErrorO  )  ( 

) 

alert (text (S  FAIL  GET  INFO,  strBuf),  err); 

return  err; 

return (err) ; 

) 

(fifdef  DEBUG2 

/*  Detach  the  driver  if  the  drivers  load  flag  is  not  false  */ 

alertNote ("SetResInfo  NewID  %d",  drvrNewID) ; 

detachDriver (  drvrTbl,  ownedTbl) 

#endif 

struct  drvrStruct  ‘drvrTbl;  /*  array  of  drvrStruct  */ 

SetResInfo(  rsrcHdl,  drvrNewID,  name);  /*  set  new  ID  and  name  */ 

struct  ownedStruct  ‘ownedTbl;  /*  array  of  ownedStruct  */ 

if  (err  -  ResErrorO )  ( 

( 

alert (text (S  FAIL  SET  INFO,  strBuf),  err); 

register  short  i,  id; 

return (err) ; 

register  OSErr  err; 

1 

Handle  hndl; 

if (  !err)( 

char  strBuf [ 128] ; 

ChangedResource (  rsrcHdl);  /*  Mark  the  resource  as  changed.  */ 

err  =  ResErrorO; 

fifdef  DEBUG  TRACE 

) 

alertNote ("detachDriver () ") ; 

return (err) ; 

fendif 

) 

err  =  noErr; 

changeTableResources (  change)  /*  Change  the  driver  table  resources.  */ 

/*  Update  the  resource  file  because  ResError  will  return  resAttrErr  if  you 
*  call  DetachResource  to  detach  a  resource  whose  resChanged  attribute  has 

int  change;  /*  which  driver  table  has  changed.  */ 

*  been  set. 

Handle  hData; 

UpdateResFile (  CurResFile () ) ;  /*  Assumes  that  the  current  res  file  */ 

int  err; 

/*  is  the  init.  */ 

char  strBuf [128]; 

/*  Here  go  the  DRVRs  */ 

fifdef  DEBUG  TRACE 

for (  i=0;  i<NUM_DRVRS  &&  !err;  ++i)  ( 

alertNote ("changeTableResources  0 ") ; 

fendif 

fifdef  DEBUG1 

if {  change  &  DRVRTBL) ( 

alertNote ("Detach  Is  driver",  drvrTbl (i ]. name) ; 

hData  =  GetResource  (  DRVR_TBL_TYPE ,  DRVR_TBL_ID) ; 

if  {  err  =  ResErrorO  )  ( 

hndl  =  GetResource!  DRVR  TYPE,  drvrTbl [i] .id) ; 

alert (text (S  FAIL  GET  DRVR  TBL,  strBuf)); 

if  (  err  =  ResErrorO  ) 

return {  err); 

alert (text (S  FAIL  GET  DRVR,  strBuf),  drvrTbl [l] .name) ; 

); 

DetachResource (hndl) ; 

ChangedResource (  hData); 

if  (  err  =  ResError () ) 

if  (  err  =  ResErrorO  )  { 

alert (text (S  FAIL  DETACH  DRVR,  strBuf),  drvrTbl [i] .name) ; 

alert (text (S  FAIL  RSRC  MGR,  strBuf),  err); 

) 

return (  err); 

/*  Here  go  the  owned  resources;  Required  for  segmented  drivers.  */ 

>; 

for (  i=0;  i<NUM  OWNED  &fi  !err;  ++i) ( 

} 

short  drvrlndex; 

if (  change  &  OWNERTBL) { 

if (  ! drvrTbl [drvrID2index(  drvrTbl,  ownedTbl [i] .owner) ] .load) 
continue; 

hData  =  GetResource (  OWNED  TBL  TYPE,  OWNED  TBL  ID); 

drvrlndex  =  drvrID2index (  drvrTbl,  ownedTbl [l] .owner) ; 

if (  err  -  ResError () ) ( 

fifdef  DEBUG2 

alert (text (S  FAIL  GET  OWNED  TBL,  strBuf)); 

alertNote ("Detach  owned  type:  14s",  iownedTbl [i] .type) ; 

return  (  err); 

/*  adr  of  4  chars  */ 

>; 

alertNote ("id:  Id,  owner:  Id",  ownedTbl [ i] . id,  ownedTbl [ i ] .owner) ; 

ChangedResource!  hData); 

if (  err  =  ResError () ) ( 

id  =  OWNED  ID (ownedTbl [i] .owner, ownedTbl [i] .id) ;  /*  calc  owned  id  */ 

alert (text (S  FAIL  RSRC  MGR,  strBuf),  err); 

hndl  =  GetResource!  ownedTbl [i] .type,  id); 

return (  err); 

if  (  err  =  ResError () ) 

); 

alert  (text  (S  FAIL  GET  OWNED,  strBuf),  drvrTbl  [drvrID2mdex 

) 

(  drvrTbl,  ownedTbl [i] .owner) ) .name) ; 

return  err; 

DetachResource (hndl) ; 

) 

if  (  err  =  ResError () > 

/*  openMarkedDrivers .c 

alert (text (S  FAIL  DETACH  OWNED,  strBuf),  drvrTbl (drvrID2index 

(  drvrTbl,  ownedTbl [i] .owner) ] .name) ; 

".NB-DMA"  and  ".NB-GPI"  and  other  subdrivers  are  opened  as 

) 

needed  by  " .LabDRIVER" 

*/ 

return  err; 

) 

/******************»**************************•*************************/ 

openBusDriver (name, bus,  config) 
char  ‘name; 

/* 

short  bus;  /*  0  to  n-1  buses  */ 

*  Opens  certain  GPIB  drivers  if  they  are  marked  for  loading. 

register  config  t  ‘config; 

*  If  no  NI  boards  are  in  the  system,  then  don't  load  any  drivers. 

( 

*  Load  will  be  either  L  NO  or  NOT  L  NO. 

ioParam  iopb; 

*  Only  driver  table  types  T  DRVR  MASTER  and  T  BUS  DRVR  will  be  opened. 

I Board  b; 

*  Other  types  are  opened  by  higher  level  drivers. 

short  err; 

*/ 

char  strBuf [128] ; 

openMarkedDrivers (  drvrTbl, conf ig) 

fifdef  DEBUG  TRACE 

struct  drvrStruct  ‘drvrTbl;  /*  array  of  drvrStruct  */ 

alertNote ("openBusDriver () ") ; 

register  config  t  *config; 

fendif 

( 

b.b  uflags  =  config->brdRsrc.BusData [bus] .b  uflags; 

register  short  i; 

b.b  slot  =  config->brdRsrc.BusData [bus] .b  slot; 

register  short  bus;  /*  1  to  n  buses  */ 

fifdef  DEBUG1 

short  masterRefNum; 

alertNote ("bus  Id,  slot  Id,  uflags  Oxlx",  bus,  b.b  slot,  b.b  uflags); 

register  OSErr  err; 

/*  4  args  max  */ 

char  strBuf [128]; 

fendif 

fifdef  DEBUG  TRACE 

if(  isSerSlot (b.b  slot))! 

alertNote ( "openMarkedDrivers ( ) " ) ; 

b.b  slot  =  conf2initSerSlot (b .b  slot); 

fendif 

b.b  baud  =  config->brdRsrc.BusData [bus] .b  baud; 

err  =  noErr; 

fifdef  DEBUG1 

masterRefNum  =  0; 

alertNote ("Serial  slot  Id,  b  baud  Id",  b.b  slot,  b.b  baud);/*  4  args  max  */ 

for (  i=0;  i<NUM  DRVRS  &&  !err;  ++i)  { 

fendif 

fifdef  DEBUG1 

1 

if ( (  drvrTbl [i] . load  &&  (drvrTbl [i] .type  ==  T  DRVR  MASTER 

iopb. ioCompletion  =  NULL; 

!l  drvrTbl [i] .load  &&  drvrTbl [i] .type  ==  T  BUS  DRVR))) 

iopb. ioPermssn  =  fsCurPerm; 

alertNote(  "Will  open  %s",  drvrTbl [i] .name) ; 

iopb. ioNamePtr  =(StringPtr)  CtoPstr (name) ; 

fendif 

iopb.ioMisc  =(Ptr)  &b; 

if  (  drvrTbl  [i]  .  .Load  &&  drvrTbl  [i]  .type  ==  T  DRVR  MASTER)! 

err  =  PBOpen (&iopb, FALSE) ;  /*  name  is  now  Pascal  */ 

err  =  OpenDriver(  CtoPstr(  drvrTbl [i] .name) ,  SmasterRefNum) ; 

PtoCstr (  name);  /*  Must  be  a  C  string  in  the  table.  */ 

/*  name  is  now  Pascal  */ 

PtoCstr (  drvrTbl [i] .name) ;  /*  Must  be  a  C  string  in  the  table.  */ 

alert (text (S  FAIL  OPEN  NAME,  strBuf),  name); 

if  (  err) ( 

return (err) ; 

masterRefNum  =0; 

} 

alert (text (S  FAIL  OPEN  NAME,  strBuf),  drvrTbl [i] .name) ; 

) 

/*  US  keyboard  only  */ 

break;  /*  only  one  master  driver  */ 

kiiikeyo  (continued  on  page  68) 
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INIT  COLLISIONS 


Listing  One  (Listing  continued,  text  begins  on  page  15.) 

{ 

KeyMap  theKeys; 

GetKeys (  &theKeys) ; 

#ifdef  TEST 

printf ("Ox%lx  %lx  %lx  %lx\n",  theKeys .Key [3] ,  theKeys .Key [2] , 

theKeys. Key [1] ,  theKeys .Key [0] ) ; 

#endif 

return (  (theKeys. Key (1)  ==  Ox808000L)  &&  ! (theKeys. Key [3]  :: 

theKeys. Key [2]  II  theKeys. Key [0] ) ) ; 
/*  index  and  value  for  cmd-period.  */ 

char  *GetOSErrStr  () ; 

short  firstlnit  =  0; 

initMac () 

I 

if (  ! firstlnit) ( 

firstlnit  =  true; 

/*  InitWindows  would  erase  previous  INIT  icons  from  the  screen  if  */ 

/*  called  from  main().  */ 

InitFonts();  /*  These  inits  are  required  by  Dialog  Mgr..  */ 

InitWindows () ; 

InitMenus () ; 

TEInit ()  ; 

InitDialogst  NULL);  /*  resume  won't  work  for  INITs  */ 

DeskHook  =  (ProcPtr)O;  /*  alert  at  init  time  will  bomb  if  not  */ 

/*  initialized  */• 

FlushEvents(  everyEvent,  0); 

InitCursor () ; 


alert (str,  errl,  err2,  err3,  err4)  /*  expects  a  C  (null  terminated)  string  */ 
char  *str; 

short  errl,  err2,  err3,  err4; 

( 

char  buf (256) , strBuf [128] ; 
char  nilstr  [1] ; 
nilstr [0] =' \0' ; 

sprintf(buf,  str,  errl,  err2,  err3,  err4); 

note(  text_PStr (S_FAIL_INSTALL,  strBuf),  CtoPstr(  buf),  nilstr); 

1 

alertNote (str,  errl,  err2,  err3,  err4)  /*  expects  a  C  (null  terminated)  string 
char  *str; 

short  errl,  err2,  err3,  err4; 

{ 

char  buf (256) ; 
char  nilstr (1)  ; 
nilstr (0)=' \0' ; 

sprintf(buf,  str,  errl,  err2,  err3,  err4); 
note(  CtoPstr(  buf),  nilstr,  nilstr); 


note (  msgl,  msg2,  msg3) 
char  *msgl,  *msg2,  *msg3; 

( 

char  nilstr [1] ; 
nilstr (0)  =  '  \0'  ; 

initMac  0 ; 

ParamText(  msgl,  msg2,  msg3,  nilstr); 
Alert (  128,  NULL);  /*  no  beep  */ 


caution (  msgl,  msg2,  msg3) 
char  *msgl,  *msg2,  *msg3; 

I 

char  nilstr [1] ; 
nilstr (0)=' \0' ; 

initMac ( ) ; 

ParamText  (  msgl,  msg2,  msg3,  nilstr); 
Alert (  129,  NULL);  /*  one  beep 


qAbort (  msgl,  msg2,  msg3] 
char  *msgl,  *msg2,  *msg3; 

{ 

char  nilstr(l); 
nilstr (0)=' \0' ; 

initMac () ; 

ParamText (  msgl,  msg2,  msg3,  nilstr); 
return (  Alert (  130,  NULL)  ==  1); 


/*  true  if  abort  */ 


/*  No  global  space  is  used. 

*  fomats:  \n,  %s,  %c,  %d,  %o,  and  %x. 


sprintf  (buf,  f,  al) 
register  char  *f,  *buf; 
int  al; 

{ 

register  char  *s; 
register  int  *args; 
register  int  length; 
int  radix; 

args  =  Sal ; 
for  (;  *f ;  f++) 
switch  (*f)  ( 


*buf ++  =  '  \r' ; 

default: 

*buf++  =  *f; 
break; 

case  ' : 

length  =  0; 

while  (*++f  >=  'O'  s&  *f  <=  '9') 

length  =  length  *  10  +  *f  -  'O'; 

switch  (*f)  ( 

default : 

*buf++  =  *f; 
break; 
case  ' s'  : 

if (  (length) 

length  =  0x7fff; 


/*  no  maximum  length  */ 


#else 

#endif 


s  =  * (char  **)args; 
args+=sizeof (char* ) /sizeof (int) ; 

s  =  * (char  **)args++; 

while  (*s  ss  length — ) 

*buf++  =  *s++; 
break; 

case  ' d' : 

radix  =  10; 
goto  cvt; 


radix  =  8; 
goto  cvt; 


radix  =  16; 

buf  +=  itob  (buf, 

break; 


*buf++  =  *args++; 
break; 


*buf ++  =  ' \0'  ; 


*args++,  radix); 


/*  null  end  of  string  */ 


/*  integer  to  base  */ 
itob  (buf,  n,  base) 
char  *buf; 

register  unsigned  int  n; 
register  unsigned  int  base; 

[ 

register  unsigned  int  len,  extra=0; 

if  (base  ==  10  ss  (int)n  <  0)  { 

n  =  -n; 

*buf++  ■ 
extra++; 

} 

len  =  n  <  base  ?  0  :  itob  (buf,  n  /  base,  base) ; 

buf [len]  =  digits (n  %  base) ; 

return  len  +  extra  +  1; 


/*  returns  the  ASCII  of  the  binary  n  without  using  a  global  table  */ 
digits (  n) 
int  n; 

{ 

int  c; 
switch  (n) [ 


case 

0: 

c= '  0 ' 

break; 

case 

1: 

c='  1' 

break; 

case 

2: 

c='  2' 

break; 

case 

3: 

c='  3' 

break; 

case 

4: 

c='  4' 

break; 

case 

5: 

c= '  5' 

break; 

case 

6: 

c='  6' 

break; 

case 

7: 

c='  7' 

break; 

case 

8: 

c='8' 

break; 

case 

9: 

c=  ’  9' 

break; 

case 

10 

c='  a 

;  break; 

case 

11 

c='  b 

;  break; 

case 

12 

c='  c 

;  break; 

case 

13 

c=' d 

;  break; 

case 

14 

c='  e 

;  break; 

case 

15 

c='  f 

;  break; 

default 

c='?' 

;  break; 

End  Listing  One 


Listing  Two 


/*  initOpenDRVR.h 

#  John  Rosford,  National  Instruments. 

#  Copyright  1988,1989  National  Instruments  Corporation 

#  All  rights  reserved. 

*/ 

/*  select  compile  configuration  for  Macintosh  handler  inits.*/ 
fdefine  DEBUG_TRACE  /*  Alert  for  each  function.  */ 

♦define  DEBUG1  /*  Show  drivers  marked  for  loading.  */ 

♦define  DEBUG2  /*  Show  driver  ID  collisions.  */ 

♦define  DEBUG3  /*  Disable  duplicate  drivers  error.  */ 

fundef  DEMO  /*  Fill  slot  info  with  NB-DMA-8  in  slot 
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GLOBALS  /*  Using  global  variables.  */ 

LSC  /*  Lightspeed  C  */ 

NSLOTS  6  /*  number  of  NuBus  slots.  Don't  include  */ 

/*  serial  slots  here.  */ 

■  START_OF_USER_IDS  12  /*  Inside  Mac  IV-215.  Zero  is  used  */ 

/*  to  flag  a  failure.  */ 

:  SSLOTS  2  /*  serial  slots  */ 

;  SSLOTA_NDX  (O+NSLOTS)  /*  index  into  slotlnfo  table  -  */ 

/*  serial  slot  A,  modem  */ 

i  SSLOTB_NDX  (1+NSLOTS)  /*  index  into  slotlnfo  table  -  */ 

/*  serial  slot  B,  printer  */ 

!  OwnedMASK  OxCOOO  /*  bit  mask  for  the  ID  of  a  resource  */ 

/*  owned  by  a  driver  */ 

:  OWNED_ID (owner, sub_id)  (OwnedMASK  !  (owner  «  5)  I  (sub_id)) 
i  NUM_IDS  128  /*  max  number  of  driver  ids  */ 


♦define  E_NBRDS  -1 

♦define  EJ3RDREV  -2 

/*  Bus  Structure  */ 
struct  busConf  { 
ulntl6  b_uflags; 
ulntl6  b_siot; 
ulntl6  b_baud; 

); 


Errors  returned  by  getBrds  &  getDevs 


/*  user  flags  */ 

/*  Slot  for  this  GPIB  bus.  */ 
/*  Baud  for  slots  A  &  B  */ 


typedef  struct  ( 

ulntl6  Rev;  /*  hex  value,  for  example:  0x10  for  Rev  1.0  */ 

ulntl6  Cnt;  /*  number  of  buses  in  BusData  */ 

struct  busConf  BusData [NBUSES] ;  /*  configuration  data  for  each  bus  */ 

)  BusResource; 

/*  INIT  configuration  structures  and  constants  */ 

♦define  isSerSlot(s)  (s  >  NSLOTS)  /*  is  serial  slot  */ 

♦define  conf2initSerSlot (s)  (s-NSLOTS-1)  /*  is  serial  slot  */ 

/*  hardware  variant  types  other  than  NuBus  */ 

♦define  GPIBMAC  20000 


DRVR_TYPE  ' DRVR' 

- ' dTbl '  Resources - 

DRVR_TBL_TYPE  'dTbl' 

DRVR  TBL  ID  128  /*  driver  table  */ 


- ' oTbl'  Resources - 

OWNED_TBL_TYPE  ' oTbl ' 

OWNED  TBL  ID  128  /*  owned  table  */ 


- ' busD'  Resources- 

BUS_DATA_TYPE  'busD' 

BUS_DATA_ID  128 

BUS  DATA  NAM  "GPIB-BusData" 


/* - STRi  Resources - 

♦define  SS_MSGS_ID  128  /*  init  message  strings  */ 

/*  Load  flags  must  not  conflict  with  a  slot  number:  1-6  */ 
♦define  L_NO  0 

♦define  L_YES  -1 

♦define  NB_GPIB  0x109 

♦define  NB_DMA_8  OxlOA 

♦define  ourBoard(id)  (  id==NB_GPIB  II  id==NB_DMA_8) 

/*  Type  flags.  DRVR  flags  include  dependency  information. 
enum( 

T_DRVR_MASTER-1,  /*  Load/open  if  any  NI  board  */ 

T_BUS_DRVR,  /*  Load/open  GPIB  bus  driver  if  conf. 


T_DRVR_GPIB, 

T_BOARD_HW, 

T_SERIAL_HW, 

T_NB_GPIB, 

T  NB  DMA  8 


Load/open  if  any  NI  board  */ 

Load/open  GPIB  bus  driver  if  configured  or  */ 
any  NI-488  board  in  slot  */ 

Load  if  any  NI-488  board:  NB-GPIB,  NB-DMA,  etc.  */ 
Load  if  any  NI-488  resource:  NB-GPIB,  NB-DMA  */ 

Load  if  any  NI-488  resource:  GPIB-422CT,  GPIB-MAC  */ 
Load  if  hardware  is  installed  */ 

Load  if  hardware  is  installed  */ 


/*  slot  translation:  s=l  to  6  ->  s+8,  s=7  to  14  ->  s-6  */ 

♦define  macSlotNum (s)  (s<=6?s+8 : s-6) 

/*  identifies  table  resource  */ 

♦define  DRVRTBL  1 

♦define  OWNERTBL  2 

/*  NB-Series  Board  Types  */ 

♦define  NOT_OUR_BOARD  0 

♦define  NO_BOARD  -1 

♦define  SLOT_OUT_OF_BOUNDS  -2 

/*  typedefs  and  macros  created  to  aid  compatibility  between  compilers. 

typedef  char  int8; 

typedef  short  intl6; 

typedef  long  int32; 

typedef  unsigned  char  ulnt8; 

typedef  unsigned  short  ulntl6; 

typedef  unsigned  long  ulnt32; 

/*  structure  of  the  driver  and  owned  resource  resources.  */ 
struct  drvrStruct{  /*  id  changes  if  DRVR  ID  conflict  in  checkIDsO 

inti 6  id;  /*  All  of  these  are  DRVR_TYPE  */ 

inti 6  load;  /*  Set  according  to  boards  and  drivers  installec 


intl6  type; 
char  name [16]; 


struct  ownedStructf 
Res Type  type; 
inti 6  id; 


/*  id  changes  if  DRVR  ID  conflict  in  checkIDsO.  */ 
/*  All  of  these  are  DRVR_TYPE  */ 

/*  Set  according  to  boards  and  drivers  installed.  */ 
/*  Load  driver  if  true.  */ 

/*  name  is  either  a  board  name  or  a  driver  name.  */ 
/*  the  name  */ 


/*  owner  changes  if  DRVR  ID  conflict  in  checkIDsO.*/ 

/*  sub  id.  Never  changes.  Resource  id  is  */ 

/*  OWNED_ID (owner_id, sub_id)  */ 

/*  owner's  id  */ 


/*  Parameter  to  first  openDriver.  */ 
typedef  struct  IBOARD 
1 

ulntl6  b_uflags;  /*  user  flags  */ 

ulnt8  b_slot;  /*  NUBUS  slot  or  serial  port  number  */ 

ulntl6  b_baud;  /*  Baud  for  slots  A  &  B  */ 

}  I Board ; 

/*  GPIB  configuration  structures,  resource  names,  and  constants  */ 

♦define  NBUSES  2  /*  number  of  buses  in  bus  data  */ 

♦define  BOARDREV  0x12  /*  Rev  1.2  of  BoardResource  */ 


typedef  struct  { 

char  brdName [256) ;  /*  max  name  length  */ 

intl6  brdID; 

)  slot Inf oType; 

typedef  struct  { 

intl6  MaxBuses;  /*  number  of  buses  read  from  bus  data.  */ 

slotlnfoType  slotInfo[NSLOTS+SSLOTS) ;  /*  nubus+serial  slots  */ 

BusResource  brdRsrc; 

)config_t; 

/*  Prototypes  of  functions  defined  in  initOpenDRVR.c  */ 
main (void) ; 

dupDriverlnstalled (struct  drvrStruct  *drvrTbl); 
char  *strcpy(  char*,  char*); 
char  *strcat (char*,  char*); 
int  strcmp(  char*,  char*); 
char  *text_PStr (intl6,  char  *) ; 
char  *text(intl6,  char  *); 
showlcon (void)  ; 

getTables (  struct  drvrStruct  **,  struct  ownedStruct  **); 
conf iglnfo (conf ig_t  *); 
configBrds (  BusResource*, conf ig_t * ) ; 
markLoad(  struct  drvrStruct  *,  config_t  *); 
ndxDrvrType(  struct  drvrStruct  *,  i n 1 1 6 ) ; 
drvrID2index (  struct  drvrStruct  *,  intl6); 
getSlot{  unsigned  intl6,  config_t  *); 
autoSlot (  intl6, conf ig_t  *); 
slotlnfoTable (config_t  *); 
calcNslots(  void)  ; 

GetSlotlnfo (intl6,  char  *); 

checkSysHeapSize (  struct  drvrStruct  *,  struct  ownedStruct  *); 
findUsedIDs(  intl6*); 
checkUnitTable (  intl6*); 
checkSysRsrcs (  intl6*); 

checkIDs(  struct  drvrStruct  *,  struct  ownedStruct  *,  intl6  *); 
getUnusedID(  intl6  *,intl6  *); 
newOwner(  struct  ownedStruct  *,  intl6,  intl6); 
changeRsrcID (  Handle,  intl6); 
changeTableResources (  intl6); 

openMarkedDrivers (  struct  drvrStruct  *,config_t  *); 
detachDriver (  struct  drvrStruct  *,  struct  ownedStruct  *); 
openBusDriver (char  *, intl6, conf ig_t  *); 
kill_key (void) ; 
initMac (void)  ; 
alert (char  *,  . . .)  ; 
alertNote (char  *,  ...); 
note(  char  *,  char  *,  char  *); 
caution (  char  *,  char  *,  char  *); 
qAbort (  char  *,  char  *,  char  *); 
sprintf  (char  *,  char  *,  ...); 
itob  (char  *,  unsigned  intl6,  unsigned  int 16); 
digits  (  int 16); 

/*  indices  to  STR^  */ 
enum( 

ZERO, 

S_FAIL_INSTALL, 

S_FAIL_REMOVE, 

S_FA I L_GET_D RVR_TB  L , 

S_FA I L_GET_OWNED_TBL , 

S_FAIL_NO_DRVR, 

S_F  A I L_GET_DRVR , 

S_FAI L_GET_OWNED , 

S_F  A I L_ I D_OSERR , 

S_FAIL_HEAP, 

S_FA I L_RSRC_MGR , 

S_FAIL_NO_FREE_ID, 

S_F  A I L_ I D_CHANGE , 

S_FAIL_GET_ATTR, 
s_FAIL_GET_INFO, 

S_FAIL_SET_INFO, 

S_FA I L_S ET_ATT R , 

S_FAIL_OPEN_NAME , 

S_FAIL_OPEN_DRVRS, 

S_FA I L_DETACH_DRVR , 

S_FAIL_DETACH_OWNED , 

S_N0T_DRVR_T YP  E , 

S_NEED_MAC_SE, 

S_NEED_MAC_I I , 

S_U  S  E  R_ABORT , 

S_Q_USER_ABORT , 

S_F  A I L_GET_DATA , 

s  fah,  get  name,  End  Listing  Two 

S_F  A I L_NUM_BUS  E S , 

S_FAIL_REVISION, 

xs_last  string  (Listings  continue  on  page  70) 
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INIT  COLLISIONS 


listing  Three  (Listings  continued,  text  begins  on  page  15  J 

/*  File  DDJInit . r 

Copyright  ©  1989  National  Instruments. 

With  MPW,  to  compile  this  file  and  copy  the  resources  to  the  INIT: 

Set  BuildDir  ' :Build  INIT:' 

Set  InitName  ' DDJ  INIT' 

rez  -o  " (BuildDir ){ InitName) "  -s  "(BuildDir)"  DDJInit. r 
Setfile  " (BuildDir) (InitName) "  -a  B  -t  INIT  -c  DDJI 


/*  include  other  resources  */ 

♦define  INIT_RSRC 
♦ifdef  INIT_RSRC 

include  "*INIT.rsrc";  /*  INIT  resource;  flags  OK  */ 

#endif 

include  "*DDJ  Driver"  ' DRVR'  (0:64)  as 

'DRVR'  ($$ID,  $$Name,  SysHeap,  Locked);  /*  DRVR  resource  */ 
include  "*DDJ  Driver"  'DATA'  (-15424 : -15200)  as 

'DATA'  ($$ID,  "",  SysHeap,  Purgeable) ;  /*  owned  DATA  resource 

/*  include  other  text  files  */ 

♦include  "Types. r" 

♦include  "SysTypes.r" 


♦define  CREATOR 

/*  Board  IDs  */ 
♦define  NB_GPIB 
♦define  NB_DMA_8 

/*  Resource  IDs  */ 


/*  file  creator  */ 


0x109 

OxlOA 


♦define  DRVR_TBL_TYPE 
♦define  DRVR  TBL  ID 


'dTbl' 

128 


'dTbl'  Resources - */ 


♦define  OWNED_TBL_TYPE  'oTbl' 
♦define  OWNED  TBL  ID  128 


/*  driver  table  */ 

' oTbl'  Resources - */ 


/*  owned  table  */ 


♦define  SS  MSGS  ID 


- STR^  Resources - */ 

128  /*  init  message  strings  */ 


/* - ' busD'  Resources - */ 

♦define  BUS_DATA_TYPE  'busD' 

♦define  BUS_DATA_ID  128 

♦define  BUS_DATA_NAM  "GPIB-BusData" 

/*  Load  flags  must  not  conflict  with  a  slot  number:  1-6  */ 

♦define  L_NO_X  0 

♦define  L  YES  X  -1 


-dTbl  •  driver  table- 


type  D  RVR_TB  L_T  Y  P  E 
wide  array 


cstring(16 


BUS0  ID=30, 

/* 

GPIB  bus  drivers  */ 

CREATOR, 

BUS1  ID, 

0, 

SHARE  ID, 

/* 

Shared  code  */ 

(  /*  array  TypeArray:  2 

elements  */ 

SH  ID, 

/* 

GPIB  serial  port  hardware  */ 

/*  (1)  V 

BH  ID, 

/* 

GPIB  board  hardware  */ 

'icNr, 

LAB  ID, 

/* 

LabDriver  */ 

(  /*  array  IDArray: 

2 

elements  */ 

DMA  ID, 

/* 

NB- 

-DMA  subdriver  */ 

/*  [1]  */ 

GPI_ID 

/* 

NB- 

-GPIB  subdriver  */ 

0,  128, 

/* 

DRVR  IDs  */ 

), 

L  YES=L  YES  X, 

/*  [2]  V 

L  NO=L  NO  X; 

/' 

'  Load  status  */ 

'FREF', 

T  DRVR  MASTER=1 

, 

/' 

'  Load  if  any  NI  board  */ 

1  /*  array  IDArray: 

2 

elements  */ 

T_BUS_DRVR, 

/* 

'  Load  GPIB  bus  driver  if  configured  */ 

/*  [1]  */ 

/* 

'  and  any  NI-488  board  in  slot  */ 

0,  128, 

T_DRVR_GPIB, 

r 

'  Load  if  any  NI-488  resource:  */ 

) 

n 

'  NB-GPIB,  NB-DMA,  GPIB-422CT,  etc  */ 

) 

T  BOARD  HW, 

/* 

'  Loaded  by  LabDriver  */ 

); 

T_SERIAL_HW, 

/* 

1  Load  if  any  NI-488  resource:  */ 

/* 

'  GPIB-422CT,  GPIB -MAC  V 

type 

CREATOR  as  ' STR  '; 

T  NB  GPIB, 

/* 

1  Load  if  hardware  is  installed  */ 

T_NB_DMA_8 

/i 

1  Load  if  hardware  is  installed  */ 

resource  CREATOR  (0)  ( 

; 

/* 

'  DRVR  Type  flags  */ 

"DDJ  Mac  Init  Version  1.01 

[16); 

/* 

'  board  name  else  driver  name  */ 

); 

type  OWNED_TBL_TYPE  ( 
wide  array  ( 

literal  longint; 
integer; 

integer  BUS0_ID=30, 
BUS1_ID, 
SHARE_ID, 
SH_ID, 
BH_ID, 
LAB_ID, 
DMA_ID, 

GPI  ID 


-oTbl  •  owned  resource  table - */ 


/*  type  of  owned  resource  */ 

/*  id  of  owned  resource  */ 

/*  GPIB  bus  drivers  */ 

/*  Shared  code  */ 

/*  GPIB  serial  port  hardware  */ 
/*  GPIB  board  hardware  */ 

/*  LabDriver  */ 

/*  NB-DMA  subdriver  */ 

/*  NB-GPIB  subdriver  */ 

/*  DRVR  IDs  */ 


-DATA  •  Bus  Data¬ 


type  BUS_DATA_TYPE  { 
hex  integer; 
integer; 
wide  array  { 

unsigned  hex  integer; 


/*  Revision  */ 

/*  Number  of  Buses  */ 


/*  uflags  */ 


unsigned  integer; 
unsigned  integer; 


data  'sysz'  (0)  ( 
$"0001  0000" 


/*  slot  */ 
/*  baud  */ 


/*  expand  sys  heap  */ 


/*  DRVR  indices  must  match  table  resources.  See  initOpenDRVR.c 
resource  DRVR_TBL_TYPE  (DRVR_TBL  ID,  "drvrTbl",  preload)  ( 

( 

BUS0_ID,  L_NO,  T_BUS_DRVR, 

BUS1_ID,  L_NO,  T_BUS_DRVR, 

SHARE_ID,  L_NO,  T_DRVR_GPIB, 

SH_ID,  L_NO,  T_SERIAL_HW, 

BH_ID,  L_NO,  T_B0ARD_HW, 

LAB_ID,  L_NO,  T_DRVR_MASTER, 

DMA_ID,  L_NO,  NB_DMA_8, 

GPI_ID,  L  NO,  NB_GPIB, 


" .GPIB0", 

" . GPIB1" , 

" .GPIBSharedCode" 
" .GMHardwareCode" 
" .NBHardwareCode" 
" . LabDRIVER" , 
".NB-DMA", 

" . NB-GPI " 


resource  OWNED_TBL_TYPE  (OWNED_TBL_ID,  "ownedTbl",  preload)  ( 

( 

'DATA',  0,  BUS0_ID,  /*  ".GPIB0"  owned  data  resource  */ 

'DATA',  0,  BUS1_ID,  /*  " .GPIB1"  owned  data  resource  */ 

'DATA',  0,  SHARE_ID,  /*  ".GPIBSharedCode"  owned  data  resource 

'DATA',  0,  BH_ID,  /*  ".NBHardwareCode"  owned  data  resource 

'DATA',  0,  SH_ID,  /*  ".GMHardwareCode"  owned  data  resource 

'DATA',  0,  LAB_ID,  /*  ".LabDRIVER"  owned  data  resource  */ 
'DATA',  0,  DMA_ID,  /*  ".NB-DMA"  owned  data  resource  */ 

'DATA',  0,  GPI_ID  /*  ".NB-GPI"  owned  data  resource  */ 

I 


♦define  baud9600  10 

/*  No  two  buses  should  be  assigned  to  the  same  slot.  Slots  range 

*  from  1  to  NSLOTS+SSLOTS  with  zero  for  not  assignment.  Change 

*  slot  to  7  for  port  A. 


resource  BUS_DATA_TYPE  (BUS_DATA_ID,  BUS_DATA_NAM)  ( 
0x12,  /*  Revision  */ 

2,  /*  Number  of  Buses  */ 

(  /*  array:  2  elements  */ 

/*  (1)  V 

0xlC03, l,baud9600,  /*  uflags, slot  l,baud  */ 

/*  (2)  *1 

0xlC03, 7,baud9600  /*  serial  slot  A  */ 


resource  'FREF'  (128,  preload)  ( 
'INIT' , 

0, 


resource  'vers'  (1,  purgeable)  ( 

0x01,  0x00,  final,  0x00,  verUS, 

"1.0", 

"1.0,  ©  National  Instruments  1989" 

); 

resource  'vers'  (2,  purgeable)  ( 

0x01,  0x00,  final,  0x00,  verUS, 

"1.0", 

"DDJ  INIT  Release  1.0" 

); 

resource  ' STR^'  (SS_MSGS_ID,  "INIT  Messages")  { 

( 

"The  driver  installation  failed.", 

"Remove  old  or  duplicate  NI  drivers.", 
"Failed  to  get  the  driver  table  resource.", 
"Failed  to  get  the  owned  table  resource.", 
"No  driver  with  id  =  %d.", 

"Failed  to  get  the  driver  resource:  %s.", 
"Failed  to  get  an  owned  resource  of:  %s.", 
"ID  %d,  OSErr  =  %d", 


S_FAIL_INSTALL  */ 

S_F A I L_REMOVE  */ 
S_FAIL_GET_DRVR_TBL  */ 
S_FAIL_GET_OWNED_TBL  */ 
S_FAIL_NO_DRVR  */ 

S_FAI L_GET_DRVR  */ 

S_F A I L_GET_OWNED  */ 

S  FAIL  ID  OSERR  */ 
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"Out  of  memory  in  the  system  heap.", 
"Resource  Mgr  error:  %d", 

"Failed  to  find  a  free  driver  ID.", 

"Failed  to  get  resource  for  ID  change,  id= 

"Failed  to  get  resource  attributes,  err=ld, 
"Failed  to  get  resource  info,  err=%d.", 
"Failed  to  set  resource  info,  err=%d.", 
"Failed  to  set  resource  attributes,  err=%d. 
"Failed  to  open  %s.", 

"OpenDriver  error  %d.", 

"Failed  to  detach  Is  driver.", 

"Failed  to  detach  Is  owned  resource.", 

"Not  a  driver  type:  Id,  at  table  index  Id", 
"The  handler  requires  a  Macintosh  SE.", 

"The  handler  requires  a  Macintosh  II.", 
"User  aborted  driver  installation.", 

"Abort  the  driver  installation?", 

"Failed  to  get  the  default  bus/device  data 

"Failed  to  get  the  default  name  resources." 
"Too  many  buses  in  default  data  resources", 
"Wrong  revision  in  default  data  resources." 
"End  of  strings."  /*  */ 


/*  S_FAIL_HEAP  */ 

/*  S_F A I L_RS RC_MG R  */ 

/*  S_FAI L_NO_FREE_ I D  */ 
=!d,  err=%d.", 

/*  S_FAIL_ID_CHANGE  */ 

.",  /*  S_FAI L_GET_ATTR  */ 

/*  S_FAIL_GET_INFO  */ 

/*  S_FAI L_SET_INFO  */ 

",  /*  S_FA I L_S ET_ATTR  */ 

/*  S_FAI L_OPEN_NAME  */ 

/*  S_FAI L_OPEN_DRVRS  */ 

/*  S_FAI L_DETACH_DRVR  */ 
/*  S_FAIL_DETACH_OWNED  */ 
/*  S_NOT_DRVR_TYPE  */ 

/*  S_NEED_MAC_SE  */ 

/*  S_NEED_MAC_I I  */ 

/*  S_USER_ABORT  */ 

/*  S_Q_USER_ABORT  */ 
resources. ", 

/*  S_FAI L_GET_DATA  */ 

',  /*  S_FAIL_GET_NAME  */ 

/*  S_FAIL_NUM_BUSES  */ 

/*  S  FAIL  REVISION  */ 


f 60,  265,  78,  335), 
Button  ( 

enabled, 

"Continue" 

}, 

/*  (3)  */ 

(10,  10,  24,  440), 
StaticText  ( 
enabled, 

"  AQ" 

), 

/*  (4)  */ 

(25,  10,  39,  440), 
StaticText  { 
enabled, 

"Ar 

), 

/*  [5]  */ 

(40,  10,  54,  440), 
StaticText  ( 
enabled, 

"A2" 

) 


resource  'ALRT'  (128)  ( 

(50,  30,  150,  480), 

128, 

(  /*  array:  4  elements  */ 

/*  [1]  */ 

OK,  visible,  silent, 

/*  [2]  */ 

OK,  visible,  silent, 

/*  (3)  */ 

OK,  visible,  silent, 

/*  (4]  */ 

OK,  visible,  silent 


resource  'ALRT'  (129)  ( 

(50,  30,  150,  480), 

128, 

I  /*  array:  4  elements  */ 
/*  [1]  V 

OK,  visible,  soundl, 


resource  'ICN#'  (128)  ( 

(  /*  array:  2  elements  */ 

/*  (1)  */ 

$"FF  FF  FF  FE  80  00  00  03 

$"88  34  19  13  8D  DE  ED  B3 

$"85  2A  94  A3  85  2A  94  A3 

$"85  2A  94  A3  85  2A  94  A3 

$"85  2A  94  A3  85  2A  94  A3 

$"85  2A  94  A3  85  2A  94  A3 

$"88  34  18  A3  8F  E7  F0  A3 

$"80  00  03  C3  80  00  00  03 

/*  (2)  V 

$"FF  FF  FF  FE  FF  FF  FF  FF 

$"FF  FF  FF  FF  FF  FF  FF  FF 

$"FF  FF  FF  FF  FF  FF  FF  FF 

$"FF  FF  FF  FF  FF  FF  FF  FF 

$"FF  FF  FF  FF  FF  FF  FF  FF 

$"FF  FF  FF  FF  FF  FF  FF  FF 

$"FF  FF  FF  FF  FF  FF  FF  FF 

$"FF  FF  FF  FF  FF  FF  FF  FF 


80  00  00  03  8F  E7  FI  F3" 
85  6A  B4  A3  85  2A  94  A3" 
95  2A  94  A3  85  2A  94  A3" 
85  2A  94  A3  85  2A  94  A3" 
85  2A  94  A3  85  2A  94  A3" 
B5  6A  B4  A3  8D  DE  EC  A3" 
80  00  03  A3  80  00  02  63" 
FF  FF  FF  FF  7F  FF  FF  FF" 

FF  FF  FF  FF  FF  FF  FF  FF" 
FF  FF  FF  FF  FF  FF  FF  FF" 
FF  FF  FF  FF  FF  FF  FF  FF" 
FF  FF  FF  FF  FF  FF  FF  FF" 
FF  FF  FF  FF  FF  FF  FF  FF" 
FF  FF  FF  FF  FF  FF  FF  FF" 
FF  FF  FF  FF  FF  FF  FF  FF" 
FF  FF  FF  FF  7F  FF  FF  FF" 


End  Listings 


OK,  visible,  soundl, 
/*  [3]  */ 

OK,  visible,  soundl, 
/*  [4]  */ 

OK,  visible,  soundl 


resource  'ALRT'  (130)  { 

(50,  30,  150,  480), 

129, 

(  /*  array:  4  elements  */ 

/*  (11  */ 

OK,  visible,  soundl, 

/*  [2]  */ 

OK,  visible,  soundl, 

/*  [3]  V 

OK,  visible,  soundl, 

/*  (4)  */ 

OK,  visible,  soundl 


resource  'DITL'  (128)  { 

(  /*  array  DITLarray:  4  elements  */ 

/*  m  V 

(60,  190,  78,  260), 

Button  ( 

enabled, 

"OK" 

), 

/*  [2]  */ 

(10,  10,  24,  440), 

StaticText  { 
enabled, 

,,A0" 

), 

/*  (3)  */ 

(25,  10,  39,  440), 

StaticText  ( 
enabled, 


/*  [4]  */ 

(40,  10,  54,  440), 
StaticText  ( 
enabled, 

"  A2  " 

) 


resource  'DITL'  (129)  { 

(  /*  array  DITLarray:  5  elements  */ 

/*  [1]  */ 

(60,  115,  78,  185), 

Button  ( 

enabled, 

"Abort" 
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Listing  One  (Text  begins  on  page  3  7.) 


/*  driver  class  declaration  */ 
#ifndef  _driver_h_ 

♦define  _driver_h_ 

struct  driver  :  indirect  ( 


cntrlParam 
DCtlPtr  dc 
int  async  ; 
int  status 


rpb  . 


parameter  block  */ 

device  control  entry  field  */ 

this  is  1  if  the  call  is  asynchronous,  else  0 

return  status  */ 


/*  methods  */ 
void  Open (  )  ; 
void  Prime (  )  ; 
void  Read{  )  ; 
void  Write (  )  ; 
void  Control (  )  ; 
void  Status (  )  ; 
void  Close (  )  ; 
void  Idle(  )  ; 
void  Error (  int  ) 


}  ; 

/*  generic  allocation  routine  */ 
driver  *New(void  )  ; 

/*  some  useful  defines  */ 

♦ifndef  NULL 
♦define  NULL  OL 
♦endif 

/*  define  jump  vectors  */ 

♦define  jFetch  0x8f4 

♦define  jStash  0x8f8 

/*  This  is  not  needed  since  the  IODone  routine  is  automatically  called  by 

Think  C's  driver  stub 

♦define  j IODone  0x8fc 
*/ 

/•♦define  asyncTrpBit  0x0200*/ 

MacHeaders  */ 

♦define  ioNotCompleted  1 

♦endif 

Listing  Two 

♦include  <DeviceMgr .h> 

♦include  "driver. h" 

♦define  OPEN  0 
♦define  PRIME  1 
♦define  CONTROL  2 
♦define  STATUS  3 
♦define  CLOSE  4 

driver  *drvr  =  NULL  ; 

int  main(  cntrlParam  *paramBlock,  DCtlPtr  devCtlEnt,  int  rout  ) 

1 

int  result  =  0  ; 

if {  rout  !=  OPEN  &&  drvr  !=  NULL  )  { 
drvr->pb  =  paramBlock  ; 
drvr->dc  =  devCtlEnt  ; 

drvr->async  =  paramBlock->ioTrap&asyncTrpBit  ; 

/*  is  it  asynchronous  */ 

drvr->status  =  0  ; 

}else  if{  rout  !=  OPEN  )( 

returnbadUnitErr; /‘drivernotopen, butinstalled*/ 

} 


void  driver: :Open {  ) 

< 

status  =  0  ; 
return  ; 

} 

void  driver: : Prime (  ) 

{ 

if(  pb->ioTrap&0x00FF  ==  aRdCmd  )  (  /*  is  it  a  read  command  */ 

Read (  )  ; 

}else{ 

Write (  )  ; 

/*  no  so  it  must  be  a  write  command  */ 

} 

return  ; 

} 

void  driver: : Read (  ) 

{ 

/*  override  this  routine  to  implement  reads  from  the  device  */ 

/*  if  the  operation  is  asynchronous,  and  could  not  be  completed  right 
/*  away,  then  in  order  to  find  out  whether  a  call  is  asynchronous, 

simply 

} 

void  driver :: Write (  ) 

I 

/*  override  this  routine  to  implement  writes  to  the  device  */ 

/*  if  the  operation  is  asynchronous,  and  could  not  be  completed  right 
/*  away,  then  in  order  to  find  out  whether  a  call  is  asynchronous, 

simply 

> 

void  driver : :Control (  ) 

I 

switch (  pb->csCode  )  { 
case  accRun: 

Idle!  )  ; 
break  ; 
case  goodBye: 

Close (  )  ; 
break  ; 

) 

I 

void  driver :: Status (  ) 

( 

status  -  0  ; 
return  ; 

} 

void  driver: :Idle(  ) 

{ 

return  ; 

} 

void  driver : :Close (  ) 

{ 

/*  if  close  is  successful,  set  status  to  0,  else  set  status  to 

closeErr (-24)  */ 

/*  eg.  if(  cannot  close  for  some  reason  )  (  Error (  closeErr  ) 
status  =  0  ; 
return  ; 

) 

void  driver :: Error (  int  err  val  ) 

( 

/*  This  routine  sets  status  to  the  error  number  specified  by  err_val. 
Note:  this  must  be  a  negative  number,  preferably  a  valid  Macintosh  e 
status  =  errval  ; 

) 

/*  Routine:  Fetch 

Description:  This  routine  gets  the  next  character  from  the  ioBuffer 
and  increments  ioActCount  by  1 .  If  it  is  the  last  character  to  sen 

Result:  returns  the  next  character  to  send  to  the  device. 

Note:  this  routine  should  only  be  used  on  asynchronous  calls 


/*  already  defined  inThink  C 

End  Listing  One 


switch (  rout  )  { 
case  OPEN: 

if (  drvr  ==  NULL  )  { 

if (  devCtlEnt->dCtlStorage  ==  NULL  )  f 
result  =  -1  ; 

}else{ 

drvr  =  New (  )  ; 
if (  drvr  ==  NULL  )  ( 
result  =  -1  ; 

)else( 

drvr->pb  =  paramBlock  ; 
drvr->dc  =  devCtlEnt  ; 
drvr->Open (  )  ; 

I 

I 

) 

break  ; 
case  PRIME: 

drvr->Prime(  )  ; 
break  ; 
case  CONTROL: 

drvr->Control (  )  ; 
break  ; 
case  STATUS: 

drvr->Status (  )  ; 
break  ; 


case 


drvr->Close (  )  ; 
result  =  drvr->status  ; 
delete (  drvr  )  ; 
drvr  =  NULL  ; 
break  ; 


/*  if  the  driver  is  open,  then  return  result  from  the  driver  */ 
if(  drvr  !=  NULL  )  result  =  drvr->status  ; 
return  result  ; 

) 


*/ 

char  Fetch)  DCtlPtr  dc,  int  *last_char  ) 

{ 

int  data  ; 
asm{ 

move.l  dc,  A1 
move.l  jFetch,  A0 
jsr  (A0) 

move.b  DO,  data 

) 

*last_char  =  data  &  0x8000  ; 
return  data&OxOOFF  ; 

) 

/*  Routine:  Stash 

Description:  This  routine  takes  care  of  stashing  a  byte  of  data  read 
from  a  device  into  the  ioBuffer  and  incrementing  the  ioActCount. 

Result:  returns  true  after  stashing  the  last  byte  requested. 

Note:  this  routine  should  only  be  used  on  asynchronous  calls 

*/ 

int  Stash (  DCtlPtr  dc,  char  stash  data  ) 

{ 

int  data  ; 
asm( 

move.l  dc,  A1 
move.b  stash_data,  DO 
move.l  jStash,  A0 
jsr  (A0) 

move.b  DO,  data 

} 


return  data&0x8000  ; 


End  Listings 
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Listing  One  (Text  begins  on  page  41.) 

model:  aClass 

"Private  -  Set  the  model  for  the  objects  in  the  file. 

"  ************************************************************************* 

Used  only  by  the  pathName : mode 1 :  in  class  File  " 

This  system  has  been  developped  for  Digitalk's  Smalltalk/V.  It  was 

model  :=  aClass! 

developed  in  /V  Mac,  ported  to  ./V  and  tested  in  /V  and  /V  Mac. 

positionAt :  anlnteger 

Author:  Based  on  some  preliminary  code  by  Steve  Northover. 

"Position  the  receiver  before  the  object  at  anlnteger. 

Packer:  This  file,  documentation  and  additional  methods  by  Charles-A. 

Unit-Record  files  run  from  l..n  not  0..n 

Rovira. 

while  not  strictly  speaking  a  private  method  it  really 

Install:  fileln  this  file. 

seves  no  real  purpose  outside  of  the  recordReadAt:  and 

Globals:  none. 

recordWrite : at :  methods  in  this  (ReadStream)  class" 

startup:  none  required. 

self  position:  (anlnteger  -  1  *  model  recordSize) 

shutdown:  all  files  should  be  closed.  None  enforced. 

recordReadAt:  anlnteger 

Usage:  See  notes  below. 

"Answer  the  unit  accessible  by  the  receiver  at 

Class (es):  Object,  File,  RecordStream 

anlnteger  position  in  the  file.  Report  an  error  if 

Class:  Object 

the  receiver  stream  is  positioned  at  the  end.  " 

Method(s):  recordToString:  stringToRecord:  recordSize 

self  positionAt:  anlnteger. 

Class:  File 

'self  recordReadNext! 

Method (s) :  path: model: 

recordReadNext 

Class:  RecordStream 

"Answer  the  next  record  accessible  by  the  receiver 

Method(s):  model:  positionAt: 

and  advance  the  stream  position.  Report  an  error  if 

recordReadAt :  recordReadNext 

the  receiver  stream  is  positioned  at  the  end." 

recordWrite:at:  recordWriteNext 

!  bytes  1 

These  routines  implement  a  file  management  system  comparable  to 

self  atEnd  ifTrue:  [ 

the  COBOL  random/ sequential  file  system. 

'self  error:  'Read  beyond  end  of  file']. 

In  order  to  use  unit-record  files  if  is  necessary  to  create  a  class 

bytes  :=  String  new:  model  recordSize. 

which  will  respond  to  at  least  three  messages: 

CursorManager  write  showWhile:  ( 

The  first  two  are  class  methods: 

1  to:  model  recordSize  do:  (:i  ! 

recordSize,  which  answers  the  size  of  unit-record  on  the  file.. 

bytes  at:  i  put:  self  next]]. 

stringToRecord,  which  translates  a  string  loaded  from  disk  into  a 

'model  stringToRecord:  bytes! 

Smalltalk  internal  representation  of  an  object  instance 

recordWrite:  anObject  at:  anlnteger 

and  answers  an  new  instance  of  the  modeled  object 

"Position  the  receiver  before  the  object  at  anlnteger. 

the  third  is  an  instance  method: 

and  write  the  object  onto  the  file" 

recordToString,  which  translates  the  Smalltalk  internal  representation 

self  positionAt:  anlnteger 

of  an  object  instance  into  a  string  to  be  stored  on  disk 

self  recordwriteNext:  anObject! 

The  model  class  can  manipulate  the  records  in  whatever  manner  is 

recordwriteNext:  anObject 

appropriate  to  the  application  in  addition  to  these  methods.  The 

"Write  anObject  to  the  receiver  stream.  Report  an  error 

system  in  a  bit  fool-proofed  in  that  the  Object  class  defines 

if  its  too  big  and  pad  with  spaces  if  its  too  small" 

a  simple  version  of  these  three  methods.  For  IBM  card-image  files 

:  bytes  size  1 

it  is  only  necessary  to  define  a  class  for  manipulating  or  extracting 

bytes  :=  anObject  recordToString. 

information  from  or  putting  information  onto  the  card  images. 

bytes  size  >  model  recordSize 

Nota  Bene:  Files  run  from  1  to  n  record.  They  are  not  zero  based 

ifTrue:  ['error:  'record  too  big']. 

Examples : 

CursorManager  write  showWhile:  ( 

A  unit  record  file  can  be  accessed  as  follows: 

self  nextPutAll:  bytes. 

I  turf  "TemporaryUnitRecordFile" 
turfRec  "TemporaryUnitRecordFile-Record"  : 
turf  :=  File  pathName:  '<file>'  model:  AnExampleClass 

A  unit  record  file  can  be  read  as  follows: 

self  next:  (model  recordSize  -  bytes  size)  put:  $  .]!  ! 

End  Listing  One 

turfRec  :=  turf  recordReadAt:  anlnteger. 

Sequential  reading  is  performed  as  follows: 
turfRec  :=  turf  recordReadNext. 

Listing  Two 

A  unit  record  file  can  be  written  to  as  follows: 
turf  recordWrite:  turfRec  at:  anlnteger 

Sequential  writing  is  performed  as  follows: 
turf  recordwriteNext:  turfRec. 

A  sample  class  to  describe  the  behavior  of  any  instance  of  an 

Employee  object. 

.'Object  methods  ! 
recordToStnng 

"Private  -  Lowest  level  of  unit-record  file  management. 

We  assume  that  the  object  defining  the  content  of  the 
unit-record  file  will  store  its  string  image  That's 
what's  answered. 

This  should  be  implemented  in  a -unit-record  model  Subclass" 

Aself  storeString!  ! 

! Object  class  methods  ! 
stringToRecord:  aString 

"Private  -  Lowest  level  of  unit-record  file  management. 

We  assume  that  the  object  defining  the  content  of  the 
unit-record  file  is  filled  by  a  string  image.  In  order, 
to  provide  for  more  flexibility  we  evaluate  the  string. 

That's  what's  answered. 

This  should  be  implemented  in  a  unit-record  model  Subclass" 
''Compiler  evaluate:  aString!  ! 

! Object  class  methods  ! 
recordSize 

"Private  -  Lowest  level  of  unit-record  file  management. 

We  assume  that  the  record  length  will  be  80  bytes  as 
that  has  been  the  standard  size  to  assume  for  over  a 
century. 

This  should  be  implemented  in  a  unit-record  model  Subclass  class 

'80 !  ! 

! File  class  methods  ! 
pathName:  aString  model:  aClass 

"Answer  a  RecordStream.  This  is  the  entry  point 
of  the  unit-record  file  management  system.  Access  files 
by  specifying  the  name  of  the  file  to  use  and  the  class 
which  models  the  type  of  objects  the  file  should  contain" 

!  anArray  dir  file  aDirectory  aStream  ! 

"The  following  code  has  been  duplicated  from  the  Directory  class 
to  simplify  creation  of  the  RecordStream  class  " 
anArray  :=  self  splitPath:  aString. 

dir  :=  anArray  at:  1. 

file  :=  anArray  at:  2. 

aDirectory  :=  Disk, 

dir  =  "  if False:  [ 

dir  first  =  $:  ifTrue:  ( 

dir  :=  aDirectory  pathName, 

(dir  copyFrom:  2  to:  dir  size)]). 

"The  preceeding  code  was  been  duplicated  from  the  Directory  class 
to  simplify  creation  of  the  RecordStream  class  " 
aStream  :=  RecordStream  on:  (File  open:  file  in:  aDirectory). 
/'aStream 

model:  aClass!  ! 

FileStream  subclass:  #RecordStream 
instanceVariableNames : 

'model' 

classVariableNames :  " 
poolDictionaries :  "  ! 

(RecordStream  class  methods  !  ! 

! RecordStream  methods  ! 


Object  subclass:  #Employee 
instanceVariableNames : 

'lastName  firstName  socInsNum' 
classVariableNames:  " 
poolDictionaries:  "  ! 

!  Employee  class  methods  ! 


"we  will  assume  that  employees  each  have: 

20  characters  for  the  lastName 
1  character  for  the  comma 
20  characters  for  the  firstName 
1  character  for  the  comma 

9  characters  for  the  SocInsNum  (social  insurance  number) 
1  character  for  the  Carriage  return/Line  feed" 


StringToRecord:  aString 

"Answer  a  new  Employee  object" 
'Employee  new  initializeWith :  aString! 

!  Employee  methods  ! 

initializeWith:  aString. 

"Fill  the  receiver  from  the  string" 
I  aStream  I 

aStream  :=  aString  asStream. 


firstName 

lastName 

socInsNum 


=  aStream  upTo:  ','  ;skip:  1. 
=  aStream  upTo:  ','  ;skip:  1. 
=  aStream  upTo:  CrLf. 


recordtoString:  anEmployee 

"answer  a  string  for  writing  to  disk" 
'firstName,  ','  lastName,  socInsNum  ,  'V  withers! 


End  Listing  Two 


Listing  Three 


Extending  Collections  in  Smalltalk/V.  The  PersistentArray 

Install:  Class  Loader  must  be  installed  (See  DL/4  in  CIS  AIExpert  forum) 
fileln  this  file. 

Globals:  Class  variable:  Openlnstances . 
startup:  PersistentArray  initialize 

Install  in  SystemDictionary  start-up 
shutdown:  PersistentArray  shutdown. 

In  /V  Mac,  regenerate  ShutDownList 
Usage:  See  notes  below. 

Class (es):  PersistentArray 
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Class:  PersistentArray 

index  :=  index  -  1] ! 

Method (s) :  Class  - 

at:  anlnteger 

initialize 

"Answer  the  value  of  the  key/value  pair  at  anlnteger. 

open : of : 

If  not  found,  report  an  error." 

open : of : readonly : synchroni zed : 

self  at:  anlnteger  ifAbsent : [self  errorAbsentElement] ! 

shutdown: 

at:  anlnteger  ifAbsent:  aBlock 

Instance  - 

"Answer  the  value  of  the  key/value  pair  at  anlnteger 

- 

If  not  found,  evaluate  aBlock  (with  no  arguments)." 

associate:with: 

answer  ! 

associationsDo: 

A  (answer  :=  content  at:  anlnteger)  ==  nil 

at : 

ifTrue :  [aBlock  value] 

at : if Absent : 

ifFalse:  [(self  fileReadAt:  answer)  value] I 

at : put : 

at:  anlnteger  put:  anObject 

close 

"Answer  the  object. 

closeReadOnlys: 

If  setting  to  nil 

coerce 

remove  the  object." 

compress: 

'  old  : 

contents 

(anObject  ==  nil) 

contents: 

ifTrue:  ["self  removeAt:  anlnteger 

do: 

notFound:  [self  error:  'Persistent  Array  boundaries']]. 

file: 

(old  :=  content  at:  anlnteger)  ==  nil 

fileAppend: 

ifFalse:  [content  at:  anlnteger 

f ileHeader 

put:  (self  fileReplace:  (self  associate:  anlnteger 

fileReadAt : 

with:  anObject) 

f ileReadSizeAt : 

at :  old) ] 

fileRemoveAt : 

ifTrue: [content  at:  anlnteger 

fileReplace:at: 

put:  (self  fileAppend:  (self  associate:  anlnteger 

fileWrite:of :at : 

with:  anObject) ) ] . 

includes : 

"anObject I 

initHeader 

close 

loadBy : 

"closing  the  persistent  object 

loadFrom: as: and: 

if  its  readonly 

loadHeader 

close  it 

readonly 

if  its  readWrite 

removeAt : notFound : 

close  all  readOnlys  on  it 

reserve: 

see  if  it  needs  to  be  compressed 

synchronize : 

update  the  header 

synchronized 

pull  it  off  the  Openlnstances  OrderedCollection" 

unloadBy : 

1  aStream  newSize  ! 

These  routines  extend  collections  outside  the  boundaries  of  Smalltalk 

CursorManager  execute  showWhile:  [ 

memory. 

readonly 

In  order  to  use  PersistentArray  it  is  only  necessary  to  create  an 

ifTrue: 

instance  of  this  class  by  issuing  the  class  message  'open'.  It  can 

[file  close) 

then  be  used  like  any  other  Array  until  you  want  to  dispose  of  it. 

ifFalse: 

Then  it  must  be  closed. 

[self  closeReadOnlys:  self. 

Nota  Bene:  The  loader  class  must  allready  be  present. 

aStream  :=  WriteStream  on:  ". 

Examples: 

Loader  new  unload:  content  on:  aStream. 

A  unit  record  file  can  be  accessed  as  follows: 

newSize  :=  (2  +  content  size)  *  32. 

!  tpa  : 

(lostBytes  >  (file  size  /4)  or: 

tpa  :=  PersistentArray  open:  '<file>'  of:  10  . 

[headSize  <  newSize]) 

Access  to  and  from  the  array  is  the  same  as  for  any  other  array. 

ifTrue: 

tpa  at:  5. 

[self  compress:  newSize]. 

tpa  at:  5  put  anObject 

CursorManager  write  showWhile: 

Instances  can  be  removed  by  setting  them  to  nil  or  by  explicitely 

(self  fileHeader. 

requesting  a  deletion: 

file  flush; 

tpa  at:  5  put:  nil  -  or  - 

close] ] . 

tpa  removeAt:  5  notFound:  (]. 

Openlnstances  remove:  self]  I 

Saving  the  object  to  disk  is  accomplished  by: 

closeReadOnlys :  aPersistentOb ject 

1  tpa  : 

"close  read  only  objects  tied  to  this  read/write  aPersistentOb ject" 

tpa  close. 

Openlnstances  do:  [:each  1 

{(each  =  aPersistentObject)  and: 

[each  readonly  ]) 

Object  subclass:  iPersistentArray 

ifTrue:  [each  close]]! 

instanceVariableNames : 

coerce 

'content  file  lostBytes  headSize  readonly  synchronized  appendsCoerced  ' 

"the  read/write  instance  has  appendsCoerced" 

classVariableNames : 

appendsCoerced  :-  true! 

'Openlnstances  ' 

compress :  newKs 

poolDictionaries : 

' CharacterConstants  '  ! 

"copies  objects  referenced  by  the  old  dictionary  onto 

a  new  dictionary" 

1  window  newPersistent  newName  1 

IPersistentArray  class  methods  ! 

GrafPort  push. 

window  :=  Window  dialogBox:  (20  @  50  extent:  450  @  150). 

initialize 

'Compressing  a  Persistent  Object...' 

"Private  -  there  are  no  Openlnstances,  Make  it  so." 

displayAt:  2  @  2  *  SysFont  charSize 

Openlnstances  :=  OrderedCollection  new. I 

font:  Font  menuFont . 

open:  aFileName  of:  anlnteger 

'CAUTION:' 

"Open  the  persistent  object  in  read/Write  mode" 

displayAt:  205*  SysFont  charSize. 

!  temp  : 

'Please  do  not  interrupt  this  process  with  Control-Break' 

temp  :=  super  new. 

displayAt:  5  @  6  *  SysFont  charSize. 

temp  initialize:  anlnteger;  loadFrom:  aFileName  as:  false  and:  false. 

not  much  to  this,  is  there?" 

"temp! 

open:  aFileName  of:  anlnteger  readonly:  aBoolean  synchronized:  aBoolean2 
"Open  the  Persistent  Array 
in  whatever  mode 

newName  :=  file  pathName. 

newPersistent  :=  PersistentArray  open:  (newName,  '$$$') 

of:  (2  *  content  size) . 

and  whatever  synchronization" 

self  associationsDo:  [ : anOldAssociation  : 

I  temp  . 

newPersistent  at:  anOldAssociation  key 

temp  :=  super  new. 

temp  initialize:  anlnteger;  loadFrom:  aFileName  as:  aBoolean  and: 

put:  anOldAssociation  value]. 
newPersistent  file  close. 

aBoolean2. 

file  close. 

•'temp! 

File  remove:  newName. 

shutdown:  aBoolean 

File  rename:  (newName, '$$$' ) 

"Private  -  close  Openlnstances" 

to:  newName. 

Openlnstances  do:  (:each  1 

file  reopen. 

window  release. 

GrafPort  pop.! 

IPersistentArray  methods  I 

contents 

=  aPersistentArray 

Answer  the  contents  for  this  instance" 

"Quickie  to  compare  PAs" 

"content ! 

"  (file  pathName  =  aPersistentArray  file  pathName) I 

contents:  anArray 

associate:  aKey  with:  aPosition 

This  read  only  object  has  its  indexes  updated" 

"return  an  association  for  internal  use" 

content  :=  anArray! 

"Association  key:  aKey  value:  aPosition! 

do:  aBlock 

associationsDo:  aBlock 

"Answer  the  receiver.  For  each  value  in  the  receiver, 

"Answer  the  receiver.  For  each  element  in  the  receiver. 

evaluate  aBlock  with  that  value  as  the  argument." 

evaluate  aBlock  with  that  element  as  the  argument." 

content  do:  [:each 

!  index  element  1 

each  isNil  ifFalse:  [ 

index  :=  super  size. 

aBlock  value:  (self  fileReadAt:  each)  value]]! 

[index  >  0] 

file 

whileTrue:  [ 

"Answer  the  file  for  this  instance" 

(element  :=  super  at:  index)  ==  nil 

ifFalse:  [aBlock  value:  self  fileReadAt:  element  value]. 

"file ! 

(continued  on  page  76) 
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Listing  Three  (Listing  continued,  text  begins  on  page  41.) 

fileAppend:  anAssociation 
"Answer  a  position 
find  a  logical  end  of  file 
derive  the  size  of  the  unloaded  association 
write  the  resultiing  collection  and  size  at  the  end" 

I  aPositior.  aStream  aSize  ! 
readonly  ifTrue:  [ 

"self  error:  'You  cannot  update  this  object']. 

CursorManager  execute  showWhile:  [ 
aPosition  :=  file  size  max:  headSize. 
aStream  :=  WriteStream  on: 

Loader  new  unload:  anAssociation  on:  aStream. 
aSize  :=  aStream  collection  size]. 

Aself  fileWrite:  aStream  collection  of:  aSize  at:  aPosition! 
f ileHeader 

“write  the  header  information  to  disk" 

!  temp  ! 

CursorManager  write  showWhile:  [ 
temp  :=  Array  with:  headSize 
with:  lostBytes 
with:  content, 
file  position:  0. 

Loader  new  unload:  temp  on:  file]  ! 
fileReadAt:  aPosition 

"Answer  an  Association, 
read  the  size  of  and  the  association" 

!  size 

CursorManager  read  showWhile:  [ 
file  position:  aPosition. 

size  :=  (Loader  new  loadFrom:  file)  "aslnteger" . 

^Loader  new  loadFrom:  file] ! 
f ileReadSizeAt :  aPosition 
"Answer  the  size. 

read  the  size  of  the  association  which  follows" 

CursorManager  read  showWhile:  ( 
file  position:  aPosition. 

A (Loader  new  loadFrom:  file)  aslnteger]! 
f ileRemoveAt :  aPosition 
"Lose  the  bytes" 
self  readonly 

ifTrue:  (Aself  error:  'You  cannot  update  this  object']. 
lostBytes  :=  lostBytes  +  self  fileReadSizeAt :  aPosition.! 
fileReplace:  anAssociation  at:  aPosition 

"Answer  aPosition  or  the  logical  end  of  file 
derive  the  size  of  the  unloaded  association 
look  up  the  old  size  on  disk 
if  its  still  fits 
write  it  in  place 
else 

find  the  logical  end  of  file 
append  it" 

:  aStream  newSize  oldSize  aNewPosition  ! 

"(anAssociation  isKindOf:  Association)" 
readonly 

ifTrue:  [Aself  error:  'You  cannot  update  this  object']. 
aStream  :=  WriteStream  on:  ". 

Loader  new  unload:  anAssociation  on:  aStream. 

newSize  :=  aStream  size. 

oldSize  :=  self  fileReadSizeAt:  aPosition. 

(oldSize  <  newSize  or:  [appendsCoerced] ) 
ifTrue: 

[lostBytes  :=  lostBytes  +  oldSize. 
aNewPosition  :=  file  size  max:  self  header. 

Aself  fileWrite:  aStream  collection 
cf:  newSize 
at:  aNewPosition] 

ifFalse: 

[lostBytes  :=  lostBytes  +  (oldSize  -  newSize). 

Aself  fileWrite:  aStream  collection 
of:  oldSize 
at :  aPosition]  . ! 

fileWrite:  aCollection  of:  bytes  at:  aPosition 

"write  anAssociation  size  and  anAssociation" 

CursorManager  write  showWhile:  [ 
file  position:  aPosition. 

Loader  new  unload:  bytes  printstring 
on:  file. 

file  nextPutAll:  aCollection. 

"file  nextPutAll: 
file  flush] . 

AaPosition ! 
includes:  anObject 

"Answer  true  if  the  receiver  contains  the  key/value 
pair  whose  value  equals  anAssociation,  else  answer  false." 
self  do:  (  : element  I 

(self  fileReadAt:  element}  value  =  anObject 
ifTrue:  [A  true] ] . 

A  false! 
initHeader 

"initialize  the  persistent  object  header" 
headSize  :=  (2  +  content  size)  *  32. 

lostBytes  :=  0. 

self  reserve:  headSize.! 
initialize:  anlnteger 

"initialize  the  persistent  object  collection" 
content  :=  Array  new:  anlnteger! 
loadBy:  aLoader 

"Write  out  the  instance  variables  of  the  receiver 
using  the  loader  object  aLoader." 
self  error:  'Can''t  (un)load  a  Persistent  object  (its  pointless)'! 
loadFrom:  aFileName  as:  readOnlyStatus  and:  synchronizedStatus 
"initialize  or  load  the  Persistent  object 
as  readWrite  [check  for  reopening  of  readWrite]  or 
readonly  [as 

requiring  appendsCoerced  or 
requiring  synchronization]  " 

!  temp  I 

file  :=  (File  pathName:  aFileName) . 

(readonly  :=  readOnlyStatus) 


ifFalse:  [Openlnstances  do: 

[:each  !  (each  file  pathName  =  file  pathName  and: 

[each  readonly  =  false]) 
ifFalse:  [ 

Aself  error:  'Cant  open:  ', aFileName,  '  twice  for  update']]] 

ifTrue: 

[File  pnmitiveChangeModeOf :  aFileName  to:  1. 

"Change  to  read  only  mode.  #  from  'Inside  Macintosh'" 
appendsCoerced  :=  synchronizedStatus  not. 

(synchronized  :=  synchronizedStatus) 
ifFalse : 

[self  openlnstances  do:  [:each  I 

each  file  pathName  =  file  pathName  and: 

[each  readonly  not]] 
ifFTrue:  [each  coerce]]]. 

Openlnstances  add:  self. 

file  size  =  0 

ifTrue: 

[self  initHeader] 
ifFalse: 

[self  loadHeader] . 

Aself ! 
loadHeader 

"get  the  persistent  object  header  from  disk" 

!  temp  : 

CursorManager  read  showWhile:  [ 
file  position:  0. 

temp  :=  (Loader  new  loadFrom:  file) . 

headSize  :=  temp  at:  1. 

lostBytes  :=  temp  at:  2. 

content  :=  temp  at:  3]! 

readonly 

"Answer  the  readonly  for  this  instance" 

A readonly ! 

removeAt:  anlnteger  notFound:  aBlock 

"Answer  anlnteger.  Remove  the  key/value  pair  at  anlnteger 
If  such  a  pair  is  not  found,  evaluate  aBlock 
(with  no  arguments)." 

(content  at  .-anlnteger)  ==  nil 
ifTrue:  [A  aBlock  value), 
self  fileRemoveAt :  (content  at:  anlnteger) 
content  at:  anlnteger  put:  nil. 

Aanlnteger ! 
reserve:  newSize 

"Answer  newSize. 

Reserve  newSize  bytes  for  the  persistent  collection. 

Pad  out  the  file  as  required." 

!  fileSize  ! 
headSize  :=  newSize. 
fileSize  :=  file  size. 

1  to:  (newSize-fileSize)  do:  [ : junk  !  file  nextPut :  Space  "$!"]. 

AnewSize ! 

synchronize:  aPersistentOb ject 

"find  the  read  instance  (s)  and  synchronize  keys" 
self  openlnstances  do:  [:each  ! 
each  =  aPersistentOb ject  and: 

[each  readonly  and: 

(each  synchronized] ) 

ifTrue:  [each  contents:  aPersistentObject  contents]]! 
synchronized 

"answer  synchronized" 

Asynchronized! 
unloadBy:  aLoader 

"Write  out  the  instance  variables  of  the  receiver 
using  the  loader  object  aLoader." 

self  error:  'Can"t  (un)load  a  Persistent  object  (its  pointless)'!  ! 

End  Listing  Three 


Listing  Four 


Extending  Collections  in  Smalltalk/V.  The  Loader 

This  system  has  been  developed  from  Digitalk's  Smalltalk/V  loader. 
The  Loader,  as  defined  in  Smalltalk/V,  required  two  modifications 
to  operate  in  the  /V  Mac  environment. 

The  original  /V  Loader  class  is  on  the  AIExpert  forum  on  CompuServe 
in  Data  Library  4. 

Install:  fileln  this  file. 

Globals:  none, 
startup:  none 
shutdown:  none 

Usage:  Internal  to  Persistent  objects. 


Object  subclass:  #Loader 
instanceVariableNames : 

'stream  loaderlndex  objectNumber  loader  loaderQueue  classDict  ' 
classVariableNames :  " 
poolDictionaries: 

' CharacterConstants  '  ! 

[Loader  class  methods  !  ! 

.'Loader  methods  ! 

classIndexFor :  aClass 

"Unloading  -  Answer  the  string  for  the  class  of  the  next 
object  to  be  unloaded." 

!  index  ! 

index  :=  classDict  at:  aClass 
if Absent:  [ 

classDict  at:  aClass  put:  objectNumber. 

AaClass  name) . 

A,l', index  printstring! 
getClass 

"Loading  -  Answer  the  class  of  the  next  object  in  the  file" 
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\  classString  char  index  ! 

(char  :=  stream  next)  ==  $% 

ifTrue:  ["(loader  at:  (stream  upTo:  Lf)  aslnteger)  class). 
classString  :=  (String  with:  char)  ,  (stream  upTo:  Lf) . 

"Smalltalk  at:  classString  asSymbol! 
getSize 

"Loading  -  Answer  the  next  object  size" 

"(stream  upTo:  Lf)  aslnteger! 
load:  anObject 

"Loading  -  Load  the  next  object  from  the  file" 

!  index  ! 
index  : =  1 . 

anObject  class  isPointers 
ifTrue:  [ 

[index  <=  loader Index] 
whileTrue:  [ 

anObject  instVarAt:  index  put:  self  nextlnstVar. 
index  :=  index  +1). 

"self]  . 

anObject  class  isBytes 
ifTrue:  [ 

[index  <=  loaderlndex] 
whileTrue:  [ 

anObject  at:  index  put:  stream  next  asciiValue. 
index  :=  index  +1]. 
stream  next. 

"self] . 

anObject  class  isWords 
ifTrue:  [ 

[index  <=  loaderlndex] 
whileTrue:  [ 

anObject  at:  index  put: 

stream  next  asciiValue  *  256  +  stream  next  asciiValue. 
index  :=  index  +1]. 
stream  next. 

"self]  ! 

loaderlndex 

"Loading  -  Indicates  the  size  of  the  next  object  in  the  file. 

Unloading  -  Used  as  an  object  reference  pointer" 

"loaderlndex! 
loadFrom:  aStream 

"Loading  -  Load  objects  from  aStream  and  return  root" 

!  numOfObjects  index  anObject  ! 
stream  :=  aStream. 

numOfObjects  :=  (stream  upTo:  Lf)  trimBlanks  aslnteger. 
loader  :=  Array  new:  numOfObjects. 
index  :=  1. 

(index  <=  numOfObjects] 
whileTrue:  [ 

loader  at:  index  put:  String  new. 
index  :=  index  +1]. 
index  :=  1. 


(index  <=  numOfObjects] 
whileTrue:  ( 

anObject  :=  self  loadlnstance. 

(loader  at:  index)  become:  anObject . "become :  (loader  at:  index).  ? 

->  backwards  ?" 

(loader  at:  index)  loadBy:  self, 
index  :=  index  +  1]. 
loader  do:  [:each!  each  rehash]. 

"loader  at:  1! 
loadlnstance 

"Loading  -  Create  an  empty  instance  of  the  next  object 
in  the  file" 

!  class  ! 

class  :=  self  getClass. 
loaderlndex  :=  self  getSize. 
class  isVariable 

ifTrue:  ("class  basicNew:  loaderlndex  -  class  instSize] 
ifFalse:  ("class  basicNew] ! 
nextlnstVar 

"Loading  -  Answer  the  next  instance  variable  from  the  stream" 

1  char  ptr  answer  classString  size  ! 
char  :=  stream  next, 
char  ==  $% 
ifTrue:  [ 

ptr  :=  stream  upTo:  Lf. 
ptr  =  't'  ifTrue:  ("true), 
ptr  =  'f'  ifTrue:  ("false), 
ptr  =  'n'  ifTrue:  ("nil]. 

"loader  at:  ptr  aslnteger). 
char  ==  $- 

ifTrue:  ["(stream  upTo:  Lf)  aslnteger  negated], 
char  isDigit 

ifTrue:  ["((String  with:  char),  (stream  upTo:  Lf ) )  aslnteger]. 
char  ==  $$ 
ifTrue:  ( 

answer  :=  stream  next, 
stream  next. 

"answer] . 
char  ==  $# 

ifTrue:  ["(stream  upTo:  Lf)  asSymbol]. 
char  ==  $ ! ! 
ifFalse:  [ 

classString  :=  (String  with:  char), 

(stream  upTo:  Lfi . 
size  :=  classString  size. 

(size  >  6 

and:  [(classString  copyFrom:  size  -  5  to:  size)  =  '  class']) 
ifTrue:  [ 

classString  :=  classString 
copyFrom:  1  to:  size  -  6. 

"(Smalltalk  at:  classString  asSymbol)  class]. 

"Smalltalk  at:  classString  asSymbol]. 
stream  peek  ==  $ ! ! 

ifTrue:  [  (continued  on page  78) 
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Listing  Four  (Listing  continued,  text  begins  on  page  41.) 

answer  :«  (Compiler  evaluate:  stream  nextChunk) 
filelnFrom:  stream) 

ifFalse:  (answer  Compiler  evaluate:  stream  nextChunk). 

"'answer! 

stream 

"Answer  the  stream  of  the  receiver" 

Astream! 

unload:  anObject 

"Unloading  -  unload  anObject  to  the  stream" 

!  size  index  ! 

size  :=  anObject  class  instSize  +  anObject  basicSize. 
stream 

nextPutAll:  (self  classIndexFor :  anObject  class); 
nextPut:  Lf; 

nextPutAll:  size  printstring; 
nextPut:  Lf. 
index  1. 

anObject  class  isPointers 
ifTrue:  ( 

(index  <-  size) 
whileTrue:  [ 

stream  nextPutAll:  (self  unloadlndexFor : 

(anObject  instVarAt:  index)), 
index  :=  index  +  1. 
stream  nextPut:  Lf ) . 

Aself] . 

anObject  class  isBytes 
ifTrue:  ( 

(index  <■  size) 
whileTrue:  ( 

stream  nextPut:  (anObject  at:  index)  asCharacter. 
index  :-  index  +1). 

"stream  nextPut:  Lf ) . 
anObject  class  isWords 
ifTrue:  ( 

(index  <-  size] 
whileTrue:  ( 

stream  nextPut:  ((anObject  at:  index)  //  256)  asCharacter. 
stream  nextPut:  ((anObject  at:  index)  \\  256)  asCharacter. 
index  :-  index  +1). 

"stream  nextPut:  Lf ) ! 
unload:  anObject  on:  aStream 

"Unload  anObject  on  aStream" 

I  class  oldPos  ! 

oldPos  aStream  position. 

(anObject  isKindOf:  Behavior) 

ifTrue:  ("self  error:  'cannot  have  ',  anObject  name,  '  as  root'], 
class  :■  anObject  class. 

(class  —  UndefinedObject 
or:  (class  --  Symbol 

or:  (class  -»  Character 

or:  (class  isKindOf:  Boolean)])) 
ifTrue:  ("self  error:  'cannot  have  ',  class  name,  '  as  root'], 
stream  :-  aStream. 
loaderlndex  :«  1. 
objectNumber  :-  1. 
loader  :=  IdentityDictionary  new. 
classDict  IdentityDictionary  new. 
loaderQueue  :-  OrderedCollection  new. 
stream 

nextPutAll:  '  '; 

nextPut:  Lf. 

loader  at:  anObject  put:  1. 
loaderQueue  addLast:  anObject. 

[loaderQueue  isEmpty] 
whileFalse:  ( 

loaderQueue  removeFirst  unloadBy:  self. 
objectNumber  :=  objectNumber  +  1). 

astream 

position:  oldPos; 

nextPutAll:  ((loaderlndex  printstring  ,  '  ') 

copyFrom:  1  to:  5); 
flush! 

unloadlndexFor:  anObject 

"Unloading  —  Answer  the  external  string  representation  for 
anObject  used  in  the  unload  stream." 

!  templnt  ! 

(anObject  isKindOf:  Behavior) 
ifTrue:  ("anObject  name). 
anObject  «  nil 

ifTrue:  ["'%n']. 
anObject  ■■  true 

ifTrue:  ["'%t']. 
anObject  — *  false 
ifTrue:  ["'%f']. 

(anObject  isKindOf:  Integer) 

ifTrue:  ("anObject  printstring] . 
anObject  class  ==  Character 

ifTrue:  ("String  with:  $$  with:  anObject). 
anObject  class  Symbol 

ifTrue:  ("'#', anObject) . 
templnt  :■  loader  at:  anObject 
if Absent:  ( 

loaderlndex  :«  loaderlndex  +  1. 
loaderQueue  addLast:  anObject. 
loader  at:  anObject  put:  loaderlndex). 
templnt  printstring!  ! 

! Object  methods  ! 
loadBy:  aLoader 

"Load  the  instance  variables  of  the  receiver  using 
the  loader  object  aLoader." 
aLoader  load:  self! 
unloadBy:  aLoader 

"Write  out  the  instance  variables  of  the  receiver 
using  the  loader  object  aLoader." 
aLoader  unload:  self!  ! 

!SortedCollection  methods  ! 
unloadBy:  aLoader 

"Write  out  the  instance  variables  of  the  receiver 


using  the  loader  object  aLoader.  Convert  the 
receiver  to  an  OrderedCollection  since  blocks 
of  code  cannot  be  loaded  or  unloaded." 
self  asOrderedCollection  unloadBy:  aLoader!  ! 

IString  methods  ! 
loadBy:  aLoader 

"Load  the  instance  variables  of  the  receiver  using 
the  loader  object  aLoader." 

!  aStream  index  size  I 
size  :■  aLoader  loaderlndex. 
aStream  :«  aLoader  stream, 
index  :«  1. 

[index  <-  size] 
whileTrue:  [ 

self  at:  index  put:  aStream  next, 
index  index  +1). 
aStream  next! 
unloadBy:  aLoader 

"Write  out  the  instance  variables  of  the  receiver 
using  the  loader  object  aLoader." 
aLoader  stream 

nextPutAll:  (aLoader  classIndexFor:  self  class); 
nextBytePut:  10; 

nextPutAll:  self  basicSize  printstring; 
nextBytePut:  10; 
nextPutAll:  self; 
nextBytePut:  10!  ! 

! Object  methods! 
rehash 

"Rehash  the  receiver,  the  default  is  do  nothing."!  ! 
!Set  methods! 
rehash 

"Rehash  the  receiver." 

!  aSet  ! 

aSet  :=  self  species  new:  self  basicSize. 
self  do:  (  :element  I  aSet  add:  element). 

"self  become:  aSet!  ! 
iDictionary  methods! 
rehash 

"Rehash  the  receiver." 

•  aDictionary  ! 

aDictionary  :*=  self  class  new:  self  basicSize. 
self  associationsDo:  [  :anAssociation  ! 

aDictionary  add:  anAssociation] . 

"self  become:  aDictionary!  ! 

! IdentityDictionary  methods! 
rehash 

"Rehash  the  receiver." 

!  aDictionary  ! 

aDictionary  :■  self  species  new. 
self  associationsDo:  (  : anAssociation  ! 

aDictionary  add:  anAssociation] . 

"self  become:  aDictionary!  ! 


End  listings 
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Listing  One  (Text  begins  on  page  45.) 


*  WizardCopy  vl.0.0  by  Don  Gaspar 

*  A  disk  copier  for  the  Apple  Macintosh 

*/C  1989  by  Don  Gaspar.  All  rights  reserved.  Portions  C  1985  by  Don  Gaspar 
#include  <ControlMgr.h> 

♦include  <DeviceMgr.h> 

♦include  <DialogMgr .h> 

♦include  <DiskDvr.h> 

♦include  <EventMgr.h> 

♦include  <FileMgr.h> 

♦include  <FontMgr.h> 

♦include  <ListMgr.h> 

♦include  <MacTypes.h> 

♦include  <MemoryMgr.h> 

♦include  <MenuMgr.h> 

♦include  <OSUtil.h> 

♦include  <pascal.h> 

♦include  <Quickdraw.h> 

♦include  <ToolboxUtil .h> 

♦include  <WindowMgr .h> 

♦include  <math.h> 

♦define  beginMenu  880 

♦define  endMenu  882 

♦define  mainDialog  880 

♦define  ourStrings  880 

♦define  aboutDialog  881 

♦define  badDisk  882 

♦define  dataDialog  883 

♦define  useVol  8000 

♦define  nil  0L 

♦define  false  0 

♦define  true  1 

♦define  watchCursor  4 

♦define  newMaster  1 

♦define  aboutMe  1 

♦define  quit  2 

♦define  mQuit  3 

♦define  inMemory  3 

♦define  copiesMade  4 

♦define  status  5 

♦define  nothing  6 

♦define  none  7 

♦define  waiting  8 

♦define  pictltem  9 

♦define  warnBefore  10 

♦define  statMeter  11 

♦define  progress  12 

♦define  alwaysFormat  13 

♦define  SSDD  1 

♦define  DSDD  2 

♦define  MFM  3 

/*  globals  */ 

Handle  myMenus[3);  /*  array  of  our  menus  */ 

Boolean  done  =  false,  format  -  false,  warn  =  true, 

masterLevel  =  false, destLevel  =  false; 
DialogPtr  wizDialog; 

Ptr  data  =  nil;  /*  here's  the  disk  data  */ 

EventRecord  the  Event;  /*  main  event  record  */ 

Point  dummyPt; 

Str255  defaultName, volumeName; 

short  temp,diskKind,nCopies  =  0; 

long  sectors;  /*  #of  sectors  of  copying  disk  */ 

errno;  /*  because  I  don't  want  stdio  */ 


/*  sets  the  text  of  our  main  dialog  to  the  specified  string  */ 
void  SetDText (item,  text) 
short  item; 

Str255  ‘text; 

( 

short  type; 

Handle  h; 

Rect  r; 

GetDItem(wizDialog, item, stype, Sh, Sr) ; 

SetIText (h, text) ; 

)/*  SetDText  */ 

/*  changes  the  status  text  in  the  main  dialog  box  */ 
void  SetAllDText (iteml, item2, item3) 
short  iteml, item2, item3; 

( 

Str255  myStr;/*  a  pascal  string  */ 
if  (iteml  !=  useVol)  { 

GetlndString (SmyStr, ourStrings, iteml ) ; 

SetDText (nothing,  SmyStr)  ; 


SetDText (nothing, SvolumeName) ; 
NumToString ( (long) nCopies, SmyStr) ; 

SetDText (none, SmyStr) ; 

GetlndString {SmyStr, ourStrings, item3) ; 
SetDText (waiting, SmyStr) ; 

)/*  SetAllDText  */ 

/*  simple  routine  to  center  the  window;  will  make 
it  visible  if  showlt  is  true  */ 
void  CenterWindow (theWindow, showlt) 

WindowPtr  theWindow; 

Boolean  showlt; 

( 

Point  centerScreen, centerWind; 

Rect  toRect; 

centerScreen. h  =  screenBits. bounds. right/2; 
centerScreen. v  =  screenBits. bounds. bottom/2; 
centerWind. h  =  (theWindow->portRect . right  - 
theWindow->portRect . left) 12; 


centerWind. v  =  (theWindow->portRect .bottom  - 
theWindow->portRect . top) / 2; 

MoveWindow (theWindow, centerScreen. h  -  centerWind. h, 
centerScreen. v  -  centerWind. v, false) ; 
if  (showlt) 

ShowWindow (theWindow) ; 

}/*  CenterWindow  */ 

/*  use  this  for  updating  the  wizard  dialog  when  the 

conditions  are  that  an  update  event  is  not  posted  */ 
void  DrawWizDialog ( ) 

{ 

Graf Ptr  oldPort; 

SetAllDText (2, 3, 1)  ; 

GetPort (SoldPort) ; 

SetPort (wizDialog) ; 

InvalRect (S (wizDialog->portRect) ) ; 

SetPort (oldPort) ; 

)/*  DrawWizDialog  */ 

/*  ejects  the  disk  and  unmounts  the  volume  */ 

OSErr  MyEject (drive) 

short  drive; 

1 

OSErr  err; 
short  vRef; 

Str255  name; 
long  dummy; 

err  =  GetVInfo (drive, sname, &vRef, &dummy) ; 
err  =  UnmountVol (&name, vRef ) ; 
err  =  DiskEject (drive) ; 
return (err) ; 

)/*  myEject  */ 

/*  tells  you  that  you  inserted  a  bad  disk  */ 
void  BadDisk (index) 

short  index;  /*  this  is  the  string  index  ♦  */ 

I 

DialogPtr  badBox; 

short  item, type; 

Graf Ptr  oldPort; 

Handle  h; 

Rect  r; 

Str255  myStr; 

GetPort (SoldPort) ;  /*  get  the  current  port  */ 

badBox  =  GetNewDialog (badDisk, nil, ( (WindowPtr) -1) ) ; 
GetDItem (badBox, 3, Stype,  Sh,  Sr) ; 

GetlndString (SmyStr, ourStrings, index) ; 

SetIText (h, SmyStr) ; 

CenterWindow (badBox, true)  ; 

SysBeep(3) ; 

SetPort (badBox) ;  /*  set  current  port  */ 

do 

ModalDialog(nil, Sitem) ; 
while  (item  !=  2) ; 


DisposDialog (badBox) ;  /*  trash  it  since  we're  done  with  it  */ 

SetPort (oldPort) ;  /*  set  it  back  */ 

DrawWizDialog  () ; 

)/*  BadDisk  */ 

/*  allocate  sufficient  space  for  copy  */ 

OSErr  MakeRAMf format) 

short  format; 

< 

long  free,sizo; 

OSErr  err; 
if  (data  !=  nil) 

DisposPtr (data) ; 

sizo  =  (format  ==  MFM)  ?  1474560 : 819200; 

sectors  =  sizo/512;  /*  globally  keep  track  of  this  */ 

if ( (long)FreeMem()  <  sizo) 

free  =  (long) CompactMem ( (long) 1474560) ; /*  ask  for  large  block  */ 

data  =  NewPtr (sizo) ; 
err  =  MemError () ; 
if  (err  !=  noErr)  ( 

BadDisk  (20) ; 

(void)  E  jectAUDisks  ()  ; 
masterLevel  =  true; 
destLevel  =  false; 

DisposPtr (data) ; 

)/*  if  */ 
return (err) ; 

)/*  MakeRAM  */ 

/*  disk  has  data  on  it.  Proceed?  */ 

Boolean  DataAlertO 

< 

DialogPtr  box; 

short  item; 

GrafPtr  oldPort; 

GetPort (SoldPort) ;  /*  get  the  current  port  */ 

box  =  GetNewDialog (dataDialog, nil, ( (WindowPtr) -1) ) ; 

CenterWindow (box, true) ; 

SetPort (box) ;  /*  set  current  port  */ 

do 

ModalDialog (nil, sitem) ; 
while  (item!=l  ss  item  !=2); 

DisposDialog (box) ;  /*  trash  it  since  we're  done  with  it  */ 

SetPort (oldPort) ;  /*  set  it  back  */ 

return {(item  ==  1)  ?  true  :  false); 

)/*  DataAlert  */ 

/*  formats  the  disk  in  the  desired  format  */ 

OSErr  CheckDisk (drive, format) 
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Listing  One  (Listing  continued,  text  begins  on  page  45J 

short  drive, ‘format; 

{ 

OSErr  err; 

cntrlParam  db; 

DrvSts  sts; 

db. ioVRefNum  =  drive; 
db.  ioCompletiori  =  nil; 

db.csCode  =  10;  /*  we  want  to  inspe.ct  the  disk  and  the  drive*/ 

db.ioRefNum  =  -5;  /*  the  disk  driver  */ 

err  =  PBStatus (&db, false) ; 

‘format  =  (db.csParam(O)  ==  -1  &&  db.csParam(l)  ==  -1) 

?  MFM  :  nil; 

if  (‘format  !=  MFM)  {  /‘call  was  invalid,  get  disk  format  */ 
err  =  DriveStatus (drive, &sts) ; 

‘format  =  (sts.twoSideFmt  ==  -1)  ?  DSDD  :  SSDD; 

)/*  if  ...  */ 
return (err) ; 

)/*DoFormat  */ 

/*  formats  the  disk  in  the  desired  format  */ 

OSErr  DoFormat (drive, format) 
short  drive, format; 

( 

OSErr  err; 

cntrlParam  db; 

int  ‘dummy; 

db. ioVRefNum  =  drive; 
db. ioCompletion  =  nil; 

db.csCode  =  6;  /*  we  want  to  format  the  disk  */ 
db.ioRefNum  =  -5; 
dummy  =  &db.csParam; 

‘dummy  =  (format  ==  MFM)  ?  1: format;/*  gotta  format  it  right  */ 
err  =  PBControl (&db, false) ; 
return (err) ; 

) /‘DoFormat  */ 

/*  Get  the  default  disk  back  */ 
void  GetDefaultVol () 

( 

done  =  true; 

DisposDialog (wlzDialog)  ; 
if  (data  !=  nil) 

DisposPtr (data) ; 

}/*  GetDefaultVol  */ 


/*  toggle  between  off  and  on  depending  what  iut  is  */ 
void  Toggleltem (aWindPtr, item, new) 

WindowPtr  aWindPtr; 

short  item; 

Boolean  new; 


ControlHandle  h; 

Rect  aRect; 

short  type,val; 

GetDItem (aWindPtr, item, &type, &h, &aRect )  ; 

SetCtlValue ( (ControlHandle) h, (GetCtlValue ( 

(ControlHandle) h)  ?  false  :  true));  /*  on-off  or  off-on  */ 

if  (new) 

SetCtlValue ( (ControlHandle) h, true)  ; 


/*  disable  appropriate  menu  items  */ 
void  SetMenusf) 

{ 

short  index; 

DisableItem(myMenus [0] , 2 ) ; 
DisableItem(myMenus[l],2) ; 
for  (index=0; index<8; index++ ) 

DisableItem(myMenus [2] , index) ; 

}/*  SetMenus  */ 


/*  read  an  entire  floppy  into  RAM  */ 
OSErr  ReadFloppy (drive) 
short  drive; 


OSErr 

ioParam 

short 

Rect 

Handle 

short 

GrafPtr 

GetDItem(wizDia 
delta  =  r. right 
x  =  r; 


err; 

ioStuff; 
index, i, delta; 
r,  x; 
h; 

kind; 

oldPort; 

log, statMeter, ikind, ih, &r) ; 

-  r.left; 

/*  this  is  our  status  rect. 


x. right  =  r.left; 
GetPort (SoldPort) ; 
SetPort (wizDialog) ; 


*/ 


ioStuff .ioVRefNum  =  drive; 
ioStuff .ioReqCount  =  5120; 
ioStuf f . ioMisc  =  nil; 
ioStuf f . ioRefNum  =  -5; 
ioStuff .ioBuffer  =  NewPtr (5120) ; 
ioStuf f. ioPosOffset  =  0; 
ioStuff .ioPosMode  =  fsFromStart; 


/*  the  drive  #  */ 

/*  read  10  sectors  at  a  time  */ 

/*  the  disk  driver  */ 

/*  this  is  a  temp,  ptr*/ 

/*  start  at  beg.  of  disk  */ 


for  (index=0; index<sectors/10;index++)  (  /*  read  the  disk  */ 

err  =  PBRead (SioStuff, false) ;  /*  read  it  */ 

x. right  =  floor ( (double) delta* (double) index/ (double) 

(sectors/10) ) 


+r . left; 

FillRect (6x, Sblack) ; 
for (i=0; i<5120; i++) 

data [ioStuff. ioPosOf fset+i]  =  ioStuf f . ioBuffer 
ioStuff .ioPosOffset  +=  5120;  /*  advance  512  bytes  : 

}/*  for. . .  */ 

DisposPtr (ioStuff . ioBuffer) ; 

FillRect (&r,  sltGray) ; 


[i]  ; 
*/ 


FrameRect (&r) ; 
SetPort (oldPort)  ; 
return (err) ; 

)/*  ReadFloppy  */ 


/*  write  an  entire  floppy  from  RAM  to  a  dest.  disk  */ 

OSErr  WriteFloppy (drive) 
short  drive; 

{ 

OSErr  err; 

ioParam  ioStuff; 

short  index, i, delta; 

Rect  r,x; 

Handle  h; 

short  kind; 

GrafPtr  oldPort; 

GetDItem(wizDialog, statMeter, Skind, &h, Sr) ; 

delta  =  r. right  -  r.left;  /*  diff.  between  left  and  right  sides  */ 
x  =  r;  /*  this  is  our  status  rect.  */ 

x. right  =  r.left; 

GetPort (SoldPort) ; 

SetPort (wizDialog) ; 


ioStuf f. ioVRefNum  =  drive;  /* 

ioStuff . ioReqCount  =  5120;  /* 

ioStuff .ioMisc  =  nil; 

ioStuf f . ioRefNum  =  -5;  /* 

ioStuff .ioBuffer  =  NewPtr(5120); 

ioStuf f . ioPosOf fset  =  0; 

ioStuf f . ioPosMode  =  fsFromStart; 


the  drive  #  */ 

write  10  sectors  at  a  time  */ 

the  disk  driver  */ 

/*  this  is  a  temp,  ptr*/ 

/*  start  at  beg.  of  disk  */ 


for  (index=0; index<sectors/lO;index++)  {  /*  write  the  disk  */ 

for (i=0; i<5120; i++)  /*  accuarate  control  meter  */ 

ioStuff .ioBuffer[i]  =  data [ioStuf f . ioPosOf fset+i] ; 
err  =  PBWrite  (SioStuff, false) ;  /*  write  it  */ 

x.right=floor ( (double) delta* (double) index/ (double) 


FillRect (&*, Sblack) ; 

ioStuf f . ioPosOf fset  +=  5120;  /*  advance  512  bytes  */ 

)/*  for. . .  */ 

DisposPtr (ioStuf f . ioBuffer) ; 

FillRect (Sr, SltGray) ; 

FrameRect (Sr) ; 

SetPort (oldPort) ; 
return (err) ; 

)/*  ReadFloppy  */ 


/*  pop  out  all  disks  in  all  drives  */ 

OSErr  E jectAllDisks ( ) 

( 

OSErr  err; 

DrvSts  sts; 
short  diive; 

for (drive=l;drive<3;drive++)  ( 

err  =  DriveStatus (drive, ssts) ; 
if  (err  ==  noErr) 

if  (sts.disklnPlace  >  0)  /*  is  it  there?  */ 

(void)MyEject (drive) ;  /*  pop  it  out  */ 

}/*  for  */ 
return  (err) ; 

)/*  E jectAllDisks  */ 


/*  which  drive  was  the  disk  inserted  into?  */ 
short  WhichDriveO 
I 

DrvSts  sts; 

OSErr  err; 
short  drive, index; 
do  ( 

err  =  DriveStatus (index, &sts) ; 

if  (sts .diskInPlace>0)  /*  is  it  there?  */ 

drive  =  sts.dQDrive;  /*  this  drive  has  the  disk  */ 
)  while (drive<0) ; 
return  (drive) ; 

)/*  whichDrive  */ 

/*  returns  the  name  of  the  inserted  disk  */ 

OSErr  GetDiskName (drive, name) 
short  drive; 

Str255  ‘name; 

( 

OSErr  err; 

long  free; 

short  vRef; 

err  =  GetVInfo (drive, name, &vRef, sfree) ; 

return (err) ; 

)/*  GetDiskName  */ 

/*  we  have  to  handle  activate  events  too!  */ 
void  DoActivate (myEvent) 

EventRecord  myEvent; 

I 

WindowPtr  targetWP; 

targetWP  =  (WindowPtr) myEvent .message; 

if  (targetWP  !=  FrontWindow ( ) ) 

SelectWindow (targetWP) ; 

SetPort (targetWP) ; 

)/*  DoActivate  */ 

/*  set  the  text  to  tell  you  what's  up  */ 
void  SetTheText (item, strlnd) 
short  item, strlnd; 

( 

Rect  r; 

Handle  h; 
short  type; 

Str2S5  theStr; 

GetDItem (wizDialog, item, Stype, &h, &r) ; 

GetlndString (stheStr, ourStrings, strlnd) ; 
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SetIText (h, stheStr) ; 

)/*  else  if  */ 

}/*  SetTheText  */ 

return (err) ; 

)/*  DoDisk  */ 

/*  here's  the  simple  line  drawings  */ 

void  DrawPseudoBoxes (r, x) 

/*  handle  the  new  master  disk  inserted  */ 

Rect  r; 

void  DoNewMaster () 

short  x; 

{ 

{ 

(void)EjectAHDisks  () ; 

MoveTo(r. left-3, r.top+7) ; 

SetAllDText  (2, 3, 11) ; 

LineTo(r. left-3, r.bottom+20) ; 

masterLevel  =  true; 

LineTo (r. right, r.bottom+20) ; 

)/*  DoNewMaster  */ 

LineTo (r. right, r.top+7) ; 

LineTo(r.left+x,r.top+7) ; 

/*  simple  dialog  box  */ 

MoveTo(r. left-3, r.top+7) ; 

void  DoAbout ( ) 

LineTo (r. left, r.top+7) ; 

{ 

}/*  DrawPseudoBoxes  */ 

DialogPtr  aboutBox; 

/*  is  the  disk  write  protected?*/ 

short  item; 

GrafPtr  oldPort; 

Boolean  WriteProtected (drive) 

GetPort (SoldPort) ;  /*  get  the  current  port  */ 

short  drive; 

aboutBox  =  GetNewDialog (aboutDialog, nil, ( (WindowPtr) -1) ) ; 

{ 

CenterWindow (aboutBox,  true) ; 

DrvSts  sts; 

SetPort (aboutBox) ;  /*  set  current  port  to  ours  */ 

OSErr  err;  /*  for  err  handling  to  be  added  later  */ 

ModalDialog(nil, Sitem) ; 

err  -  DriveStatus (drive, &sts) ; 

DisposDialog (aboutBox) ;  /*  trash  it  since  we're  done  with  it  */ 

SetPort (oldPort) ;  /*  set  it  back  */ 

return (BitTst (&sts .writeProt, (long)7) ) ;  /*  is  it?  */ 

}/*  DoAbout*/ 

}/*  WriteProtected  */ 

/*  simple  QuickDraw  McGraw  stuff  to  make  main  dialog  look  good  */ 

/*  process  menu  items  that  were  selected  */ 
void  DoMenu(code) 

void  BoxDialogThings () 

long  code; 

short  type, item; 

short  menuNum, itemNum; 

Handle  h; 

Str255  name; 

Rect  r; 

short  temp; 

GetDItem(wizDialog, inMemory, Stype, Sh, &r) ; 

menuNum  =  HiWord (code) ; 
itemNum  =  LoWord (code) ; 

DrawPseudoBoxes ( r ,  72 ) ; 

if  (itemNum  >  0)  ( 

GetDItem(wizDialog,copiesMade,  stype,  &h,sr) ; 

switch  (menuNum)  ( 

DrawPseudoBoxes (r,  85) ; 

case  beginMenu: 

GetDItem(wizDialog,  status,  Stype, &h,  & r ) ; 

switch  (itemNum)  { 

DrawPseudoBoxes (r,  50) ; 

case  aboutMe  : 

GetDItem(wizDialog, statMeter, Stype, &h, Sr) ; 

DoAbout () ; 

FillRect (Sr, SltGray) ; 

break; 

FrameRect (Sr) ; 

default  : 

)/*  BoxDialogThings  */ 

Get  Item (myMenus [0) , itemNum, &name) ; 

/*  handle  disk  event  */ 

temp  =  OpenDeskAcc (Snarae) ; 

)/*  switch  itemNum  */ 

OSErr  DoDisk (message) 

break; 

long  message; 

case  beginMenu+1: 

( 

switch  (itemNum)  ( 

OSErr  err; 

case  newMaster  : 

Boolean  wp.flag  =  false; 

DoNewMaster () ; 

short  drive, kind; 

break; 

wp  =  WriteProtected (LoWord (message) ) ; 

case  mQuit  : 

drive  =  LoWord (message) ; 

GetDefaultVol () ; 

if  (masterLevel)  (  /*  are  we  reading  a  master  disk?  */ 

)/*  switch  itemNum  */ 

if  (HiWord (message)  !*•  noErr  SS  HiWord (message)  !-  volOnLinErr 

break; 

BadDisk (19) ; 

case  endMenu:; 

else  if  (wp)  ( 

)/*  switch  menuNum  */ 

nCopies  =  0; 

HiliteMenu (false) ; 

CheckDisk (drive, SdiskKind) ; 

}/*  if  */ 

masterLevel  -  false;  /*  don't  copy  unless  it's  wp!*/ 

)/*  DoMenu  */ 

destLevel  =  true; 

/*  update  main  window  */ 

(void)GetDiskName  (drive, SvolumeName) ; 

void  DoUpdate (myEvent) 

SetAllDText (useVol, 3, 16) ; 

EventRecord  myEvent; 

{ 

if  (MakeRAM(diskKind, data)  ==  noErr)  { 

ReadFloppy (drive) ; 

WindowPtr  tempFort, aWindPtr; 

SetAllDText (useVol, 3, 12) ; 

aWindPtr  =  (WindowPtr) myEvent .message;  /*  get  window  */ 

)/*  if  MakeRAM  . . .  */ 

if  (aWindPtr  ==  wizDialog)  ( 

else 

SetCursor (‘GetCursor (watchCursor) ) ;  /*  hold  on  a  sec  */ 

SetAllDText (2, 3, 11); 

GetPort (stempPort) ; 

) /*  else  if  ! . . .  */ 

SetPort (aWindPtr) ; 

else 

ForeColor (blueColor) ; 

BadDisk (6) ; 

TextFont  (geneva) ;  /*  easy  on  the  eyes  */ 

(void)MyEject (LoWord (message) ) ; 

ForeColor (blackColor) ; 

}/*  if  */ 

BeginUpdate (aWindPtr) ; 

else  if  (destLevel)  (  /*  are  we  making  copies???  */ 

EraseRect (SaWindPtr->portRect) ;  /*  clean  it  out  */ 

if  ( (HiWord (message) )  ==  noErr  &&  !wp  )  ( 

DrawDialog (wizDialog) ;  /*  and  redraw  */ 

if  (warn)  f 

BoxDialogThings () ; 

if  ( !DataAlert () ) 

EndUpdate (aWindPtr) ; 

flag  =  true; 

SetPort (tempPort) ; 

} 

TextFont (systemFont) ;  /*  back  to  correct  system  font*/ 

if  ( ! f lag) { 

InitCursor () ;  /*  back  to  the  arrow  */ 

CheckDisk (drive, skind) ; 

}/*  if  */ 

if  (kind  !=  diskKind  1 !  format)  ( 

)/*  DoUpdate  */ 

if  (kind  !=  MFM  1 1  format)  ( 

SetAllDText  (useVol,  3, 17) ,- 

/*  handle  things  for  our  main  dialog  */ 

(void) DoFormat (drive, diskKind) ; 

void  DoDialog(item) 

short  item; 

else 

switch  (item)  { 

BadDisk (4) ; 

case  newMaster  :  /*  a  master  disk  was  inserted,  do  it!  */ 

) 

DoNewMaster () ; 

)/*  else. . .  */ 

break; 

}/*  if...  */ 

case  quit  :  /*  we're  done  */ 

else  if  {(format  !!  (HiWord (message)  !=  noErr))  &&  !wp)  ( 

GetDefaultVol () ; 

SetAllDText (useVol, 3, 17) ; 

break; 

(void) DoFormat (drive, diskKind) ; 

case  alwaysFormat  :  /*  automatically  format  all  disks  */ 

)/*  if  format  */ 

Toggleltem (wizDialog, alwaysFormat, false) ; 

if  (!wp  &&  .’flag)  {/*  write  data  to  disk  */ 

format  =  (format==true)  ?  false  :  true;  /*  toggle  */ 
break; 

SetAllDText (useVol, 3,18); 

case  warnBefore  :  /*  warn  before  formatting  an  existing  disk*/ 

(void) WriteFloppy (drive) ; 

Toggleltem (wizDialog, warnBef ore,  false) ; 

nCopies++;  /*  let's  keep  track  here  */ 

) 

warn  =  (warn==true)  ?  false  :  true;/*  toggle  */ 

)/*  switch  */ 

else  if  (wp) 

)/*  DoDialog  */ 

BadDisk (7) ; 

(void) MyE ject (drive) ; 

/*  handle  the  key  events  */ 

SetAllDText (useVol, 3, 12) ; 

void  DoKeyEvent  (myEvent)  ( Continued  Ofl  page  84) 
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listing  One  (Listing  continued,  text  begins  on  page  45  ) 

EventRecord  myEvent ; 

DrawMenuBar () ; 

( 

ToggleItem(wizDialog, warnBefore,  true) ; 

char  theKey; 

SetMenus ( ) ; 

long  item; 

)/*  SetUpThings  */ 

if  (myEvent .modifiers  &  cmdKey)  { 

theKey  = 

void  main ( ) 

myEvent .message  &  charCodeMask;  /*  which  key  */ 

( 

if  (item  =  MenuKey (theKey) ) 

InitThings  () ; 

DoMenu (item) ;  /*  do  it  */ 

if  (CheckThings () )  ( 

) 

SetUpThings  ( ) ; 

)/*  DoKeyEvent  */ 

RememberDefault  () ; 

while  (!done)  ( 

/*  handle  the  mouse  down  event  */ 

if  (GetNextEvent (everyEvent, &theEvent) ) 

void  DoMouseDown (myEvent) 

if  ( IsDialogEvent (&theEvent ) )  ( 

EventRecord  myEvent; 

if  (theEvent . what  ==  updateEvt) 

1 

DoUpdate (theEvent) ; 

short  windowLoc; 

else  if  (theEvent . what  ==  diskEvt)  ( 

Point  mousePos; 

if  (masterLevel  ! 1  destLevel) 

WindowPtr  aWindPtr; 

DoDisk (theEvent .message) ; 

Rect  r; 

else 

mousePos  =  myEvent .where; 

(void) E jectAllDisks () ; 

windowLoc  =  FindWindow (mousePos, SaWindPtr) ; 

) /*  else  if  ...  */ 

switch  (windowLoc)  { 

else  if  (DialogSelect (&theEvent, &wizDialog, Stemp) ) 

case  inMenuBar  : 

DoDialog (temp) ; 

DoMenu ( (long) MenuSelect (mousePos) ) ; 

)/*  if  ‘/ 

break; 

else 

case  inSysWindow  :/»  for  those  pesky  DAs'  */ 

HandleEvent (StheEvent) ; 

SystemClick (SmyEvent, aWindPtr) ; 

)/*  while  */ 

break; 

)/*  if  CheckThings  */ 

case  inDrag  : 

else  ( 

)/*  else  */ 

SetRect (&r, screenBits . bounds . left+4 , screenBits .bounds . top+24 , 

if  (  data  !=  nil  ) 

screenBits. bounds. right-4, screenBits .bounds .bottom-4) ; 

DisposPtr (data) ; 

DraqWindow (aWindPtr, mousePos, &r) ; 

}/*  main  */ 

break; 

case  inContent  : 

if  (FrontWindowO  !=  aWindPtr) 

SelectWindow (aWindPtr) ; 

break; 

default  :; 

)/*  switch  */ 

)/‘  DoMouseDown  */ 

/*  Init.  mgrs.,  allocate  space,  etc.  */ 

void  InitThingsO 

InitGraf (sthePort) ; /*  init  appropriate  mgrs  */ 

InitFonts () ; 

InitWindows {) ; 

End  Listing 

InitMenus () ; 

TEInitO; 

InitDialogs  (nil) ; 

InitCursor  () ; 

MoreMasters  () ;  /*  get  master  pointers  */ 

MoreMasters  ()  ; 

MoreMasters  ( ) ; 

MaxApplZone  ( ) ; 

FlushEvents (everyEvent, 0) ;  /*  clear  event  queue  */ 

wizDialog  =  GetNewDialog (mainDialog, nil, ( (WindowPtr) -1 ) I ; 

CenterWindow(wizDialog) ; 

DrawWizDialog () ; 

}/*  InitThings  */ 

/*  Handle  any  event  that  occurred  */ 

void  HandleEvent (myEvent) 

EventRecord  ‘myEvent; 

i 

switch  (myEvent->what)  { 

case  mouseDown  : 

DoMouseDown ( ‘myEvent ) ; 

break; 

case  activateEvt  : 

DoActivate (‘myEvent) ; 

break; 

case  updateEvt  : 

break; 

case  keyDown  : 

case  autoKey  : 

DoKeyEvent (‘myEvent) ; 

break; 

case  diskEvt  : 

(void) DoDisk (myEvent ->message) ; 

)/*  switch  */ 

)/*  HandleEvent  */ 

/*  remember  the  default  volume  */ 

void  RememberDefault () 

short  vRef; 

(void)GetVol (idefaultName,  SvRef ) ; 

}/*  RememberDefault  ‘/ 

/*  check  system,  ram,  etc.  */ 

Boolean  CheckThings ( 1 

return (true) ; 

)/*  CheckThings  */ 

/*  Setup  menus,  window,  controls,  etc.  */ 

void  SetUpThings () 

short  index; 

for  (index=beginMenu; index<endMenu+l; index++)  /*  get  menus  */ 

myMenus [index-beginMenu]  =  GetMenu (index) ; 

AddResMenu (myMenus [0] , ' DRVR' ) ;  /»  add  desk  accessories  */ 

for  (index=beginMenu; index<endMenu+l; index++) 

InsertMenu (myMenus [index-beginMenu] ,0) ; 
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Listing  One  (Text  begins  on  page  51.) 

♦include  <DialogMgr .h>  /*  for  dialog  routines  */ 

/*  NOTE:  this  routine  must  be  called  to  set  up  the  cdev  class  */ 

♦include  <cdev.h>  /*  for  cdev  class  */ 

inherited: : Init ( ) ; 

/*  define  subclass  of  class  cdev  */ 

/*  get  system  environment  */ 

struct  sys  info: cdev  { 

SysEnvirons!  curSysEnvVers,  ssys  env  )  ; 

void  Init(  )  ;  /*  override  the  initDev  message  */ 

}; 

/*  set  machine  type  */ 

/*  dialog  item  numbers  */ 

GetDItem!  this->dp,  MACH  TYPE  +  this->lastltem,  Stype,  Shdl,  sbox  )  ; 

♦define  MACH  TYPE  1 

switch!  sys  env.machineType  )  ( 

♦define  SYS  VER  2 

default: 

♦define  PROC  TYPE  3 

case  envMachUnknown: 

♦define  HAS  FPU  4 

SetIText!  hdl,  "\punknown"  )  ; 

♦define  HAS  CQD  5 

break  ; 

♦define  KBD  TYPE  6 

case  envMacPlus: 

♦define  AT  VER  7 

SetIText!  hdl,  "\pMacintosh  Plus"  )  ; 

/*  current  system  environment  version  */ 

break  ; 
case  envSE: 

♦define  curSysEnvVers  1 

SetIText!  hdl,  "\pMacintosh  SE"  )  ; 

/*  computer  model  */ 

break  ; 

case  envMacII: 

♦define  envMachUnknown  0 

SetIText!  hdl,  "\pMacintosh  II"  )  ; 

♦define  env512KE  1 

break  ; 

♦define  envMacPlus  2 

case  envMacIIx: 

♦define  envSE  3 

SetIText!  hdl,  "\pMacintosh  IIx"  )  ; 

♦define  envMacII  4 

break  ; 

♦define  envMacIIx  5 

case  envMacSE30: 

♦define  envMacSE30  7 

SetIText!  hdl,  "\pMacintosh  SE/30"  )  ; 

/*  cpu  types  */ 

break  ; 

) 

♦define  envCPUUnknown  0 

♦define  env68000  1 

/*  set  system  version  */ 

♦define  env68010  2 

GetDItem!  this->dp,  SYS  VER  +  this->lastltem,  Stype,  shdl,  Sbox  )  ; 

♦define  env68020  3 

if(  sys  env.systemVersion  ==  0  )  ( 

♦define  env68030  4 

SetIText!  hdl,  "\punknown"  )  ; 

/*  keyboard  types  */ 

(else! 

count  =  0  ; 

♦define  envUnknownKbd  0 

currl  =  sbufferl [1]  ; 

♦define  envMacKbd  1 

tmp  =  (  sys  env.systemVersion  S  OxFFOO  )  »  8  ; 

♦define  envMacAndPad  2 

NumToString!  tmp,  buffer2  )  ; 

♦define  envMacPlusKbd  3 

curr2  =  Sbuffer2[l]  ; 

♦define  envAExtendKbd  4 

while!  buffer2[0] —  )  ( 

♦define  envStandADBKbd  5 

count ++  ; 

/*  Will  the  cdev  be  usable  in  this  environment?  */ 

*currl  =  *curr2  ; 
currl++  ;  curr2  ++  ; 

/*  This  routine  should  be  used  to  determine  whether  the  cdev 

) 

should  appear  in  the  control  panel  for  this  environment.  An 

count++  ; 

example  of  this  would  be  a  cdev  for  setting  the  parameters  for 

*currl  =  ' . '  ; 

the  virtual  memory  manager  for  System  7.0.  This  cdev 

currl++  ; 

would  only  be  necessary  for  68020  with  the  Paged  Memory 

tmp  =*  (  sys  env.systemVersion  S  OxOOFF  )  ? 

Management  Unit,  or  a  68030.  In  this  case,  the  Runnable 

NumToString!  tmp,  buffer2  )  ; 

routine  would  determine  the  type  of  machine  it  was  on,  and 

curr2  =  Sbuffer2[l]  ; 

return  either  TRUE  or  FALSE,  depending  on  whether  the  cdev 

while!  buf fer2 [0] —  )  { 

serves  a  valid  purpose  on  this  machine  */ 

Boolean  Runnable (  ) 

‘currl  =  ‘curr2  ; 

{ 

currl++  ;  curr2  ++  ; 

return  TRUE  ; 

1 

} 

bufferl[0]  =  count  ; 

/*  This  routine  creates  the  cdev.  In  our  cdev,  it  doesn't  really 

SetIText!  hdl,  bufferl  )  ; 

} 

serve  any  purpose,  since  we  don't  have  any  storage 

requirements,  but  we  still  need  the  structure  allocated  for 

/*  set  processor  type  */ 

purposes  of  calling  the  appropriate  methods  */ 

GetDItem!  this->dp,  PROC  TYPE  +  this->lastltem,  Stype,  Shdl,  Sbox  )  ; 

cdev  *New() 

switch!  sys  env. processor  )  { 

{ 

return  new(  sys  info  )  ; 

default : 

case  envCPUUnknown: 

} 

SetIText!  hdl,  "\punknown"  )  ; 

/*  This  routine  overrides  the  initDev  message,  which  is  called 

break  ; 

upon  selection  of  any  item  in  the  control  panel  list.  For  a 

more  complex  cdev,  this  routine  would  do  all  initialization 

required  for  the  cdev,  and  the  more  complex  interaction 

required  by  the  cdev  would  be  implemented  using  remainder  of 

SetIText!  hdl,  "\pMotorola  68010"  )  ; 

the  messages,  and  their  handlers.  The  remainder  of  the 

messages,  and  the  related  method,  are  listed  below: 

case  env68020: 

hitDev  -  for  mouse  downs.  Method:  ItemHit (  ) 

SetIText!  hdl,  "\pMotorola  68020"  )  ; 

closeDev  -  for  de-initialization.  Method:  Close (  ) 

nulDev  -  idle  routine,  for  whatever  needs  to  be  done  on  a 

SetIText!  hdl,  "\pMotorola  68030"  )  ; 

regular  basis,  but  is  not  really  event  related. 

break  ; 

Method:  Idle(  ) 

updateDev  -  for  update  events.  Method:  Update (  ) 

activDev  -  for  activate  events.  Method:  Activate (  ) 

deActivDev  -  for  de-activate  events.  Method:  Deactivate!  ) 

GetDItem!  this->dp,  HAS  FPU  +  this->lastltem,  Stype,  shdl,  sbox  }  ; 

keyEvtDev  -  for  key  downs.  Method:  Key!  ) 

undoDev  -  for  handling  undos.  Method:  Undo!  ) 

cutDev  -  for  handling  cuts.  Method:  Cut!  ) 

/*  set  has  colorQD  */ 

copyDev  -  for  handling  copys .  Method:  Copy!  ) 

GetDItem!  this->dp,  HAS  CQD  +  this->lastltem,  Stype,  Shdl,  Sbox  )  ; 

pasteDev  -  for  handling  pastes.  Method:  Paste!  ) 

SetIText!  hdl,  sys  env.hasColorQD  ?  "\pyes" : "\pno"  )  ; 

clearDev  -  for  handling  clears.  Method:  Clear!  ) 

To  implement  any  of  these  messages,  simply  override  the 

/*  set  keybord  type  */ 

GetDItem!  this->dp,  KBD  TYPE  +  this->lastltem,  Stype,  Shdl,  Sbox  )  ; 

method,  in  your  subclass. 

switch!  sys  env.keyBoardType  )  { 

*/ 

default: 

void  sys  info::Init(  ) 

SetIText!  hdl,  "\punknown"  )  ; 

int  type  ; 

break  ; 

case  envMacKbd: 

Handle  hdl  ; 

SetIText!  hdl,  "\pstandard"  )  ; 

Rect  box  ; 

break  ; 

SysEnvRec  sys_env  ; 

case  envMacAndPad: 

long  tmp  ; 

SetIText!  hdl,  "\pstandard  with  key  pad"  )  ; 

int  count  ; 

break  ; 

char  *currl  ; 

case  envMacPlusKbd: 

char  *curr2  ; 

SetIText!  hdl,  "\pMacintosh  Plus  Keyboard"  )  ; 

char  bufferl[10]  ; 

char  buffer2[10]  ; 

case  envAExtendKbd: 

/*  first  call  inherited  Init  routine  */ 

SetIText!  hdl,  "\pApple  extended"  )  ; 
break  ; 
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case  envStandADBKbd: 

SetIText(  hdl,  "\pstandard  ADB”  )  ; 
break  ; 

I 

/*  set  appletalk  version  */ 

GetDItem(  this->dp,  AT_VER  +  this->lastltem,  stype, 
if (  sys_env.atDrvrVersNum  ==  0  )  { 

SetIText(  hdl,  "\pnot  loaded"  )  ; 

lelse( 

tmp  =  (  sys_env.systemVersion  &  OxFFOO  )  » 
NumToString(  tmp,  bufferl  )  ; 

SetIText(  hdl,  bufferl  )  ; 


/*  finished  */ 
return  ; 


shdl,  Sbox  )  ; 


8  ; 


End  Listing 
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Yesterday,  Today,  and  Tomorrow 

It  has  been  an  honor  and  a  privilege  to  be  involved  in  the  production  of  this  issue  of  Dr.  Dobb’s 
Journal.  DDJ has  always  been  a  resource  for  C  programmers,  and  it  is  only  fitting  that  it  produces 
an  issue  devoted  to  the  future  of  C.  I  think  you’ll  find  that  the  variety  of  articles  in  this  issue  reflect 
the  myriad  uses  of  C  you’ll  find  today  and  tomorrow. 

C  was  bom  in  the  1970s,  matured  during  the  1980s,  and  is  headed  for  an  even  better  future  in 
the  1990s.  Going  from  an  obscure  systems  programming  language  at  AT&T,  C  has  grown  to  be  a 
premiere  language  for  the  development  of  sophisticated  applications  on  nearly  every  hardware 
platform.  C  is  not  a  static  language;  the  original  Kernighan  and  Ritchie  C  has  evolved  into  ANSI  C 
and  C++.  The  world  of  programming  changes  so  often  that  a  language  cannot  remain  unchanged 
and  still  be  viable  over  the  long  term. 

Where  to  go  from  here?  C++  is  an  obvious  answer;  while  several  other  object-oriented  variants 
of  C  exist  (that  is,  Objective  C,  C_talk),  none  of  them  have  garnered  the  following  C++  has.  C++ 
does  have  faults  and  detractors  —  but  what  language  doesn’t?  C++  offers  what  C  programmers 
have  always  liked:  Freedom  of  expression.  An  idea  central  to  both  C  and  C++  is  that  the  programmer 
knows  how  to  program,  and  the  compiler  should  not  stand  in  the  way.  As  with  any  other  form  of 
creativity,  programming  is  best  done  when  the  tools  being  used  have  few  limitations. 

The  eventual  success  of  C++  depends  on  many  things.  Probably  C++’s  biggest  fault  is  the  lack 
of  a  standard  object  class  library.  Smalltalk  and  other  “pure”  object-oriented  languages  provide  a 
cornucopia  of  classes  for  everything  from  linked  lists  to  windowing  and  graphics.  These  built-in 
classes  provide  more  than  program  building  blocks:  They  show  a  programmer  how  object-oriented 
programming  should  be  done.  Historically,  languages  without  standard  libraries  (such  as  Modula-2) 
have  suffered  in  the  marketplace.  If  AT&T  does  not  address  this  need,  then  those  of  us  who  use 
C++  must  work  together  to  build  publicly-available  standard  libraries. 

In  spite  of  C++,  C  will  continue  to  be  a  popular  programming  language.  Once  the  ANSI  standard 
is  finalized,  new  directions  for  C  include  the  development  of  standards  for  mathematical  extensions 
and  international  markets.  An  ANSI  subcommittee  is  working  on  the  former,  and  an  ISO  committee 
is  developing  the  latter.  As  the  requirements  of  programmers  change,  so  will  C. 

Another  change  we  can  expect  will  occur  in  the  programming  environment.  Just  as  the  days  of 
card  punches  and  batch  compiles  have  passed,  so  too  will  our  current  system  of  compile/edit/ 
debug  be  replaced.  Working  with  C++  has  shown  that  the  current  programming  environment  is  too 
limited  for  sophisticated  software  development.  New  tools  are  needed  to  help  us  understand, 
design,  document,  and  debug  our  programs. 

You  can  already  see  the  germination  of  some  of  these  capabilities,  with  the  introduction  of 
integrated  environments  and  sophisticated  debuggers.  However,  these  tools  are  often  slow, 
cumbersome,  and  lack  the  “power”  expert  programmers  want.  Also,  the  best  programmers  tend 
to  be  very  particular  about  the  way  their  tools  work,  particularly  when  it  comes  to  editors. 

One  concept  that  interests  me  is  that  of  development  environments  where  individual  development 
applications  are  linked  together  via  intelligent  interfaces.  We  talk  about  integrating  data  bases, 
communications,  and  word  processing  for  users,  by  using  operating  environments  that  allow 
interapplication  communication.  The  same  thing  can  be  done  with  a  program  development 
environment,  where  CASE  tools,  editors,  compilers,  and  debuggers  can  be  linked  together  to  form 
an  integrated  environment.  It  would  be  even  better  if  programmers  could  mix  and  choose 
components  of  the  system,  integrating  their  favorite  tools  to  make  a  customized  environment. 

No  matter  what  the  future  of  programming  holds,  you  can  rest  assured  that  C  and  its  derivatives 
will  continue  to  be  a  part  of  that  future.  And  DDJ  will  be  there,  every  step  of  the  way. 


Scott  Robert  Ladd 
project  editor 
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INTERVIEWS 


From  C  to  C++ 

Interviews  with  Dennis  Ritchie 
and  Bjarne  Stroustrup 

Al  Stevens 


Dennis  Ritchie  is  the  designer 
of  the  C  language  and  is  the 
“R”  in  K&R,  the  nickname  for 
The  C  Programming  Lan¬ 
guage,  co-authored  by  Brian 
Kemighan.  He  is  a  member  of  the  Com¬ 
puting  Science  Research  Center  at  AT&T 
Bell  Laboratories  in  Murray  Hill,  New 
Jersey. 

Dennis  did  his  undergraduate  and 
graduate  work  in  physics  and  applied 
mathematics  at  Harvard  University.  Since 
joining  Bell  Lab’s  Computer  Science 
Research  Center  in  1968,  he  has  worked 
on  the  design  of  computer  languages 
and  operating  systems.  Along  with  oth¬ 
ers  at  Bell  Labs,  Dennis  created  the 
Unix  operating  system,  and  designed 
and  implemented  the  C  language.  His 
current  research  is  concerned  with  the 
structure  of  operating  systems. 

DDJ:  As  the  designer  of  the  C  language, 
you  are  no  doubt  the  world's  very  first 
C  programmer  in  a  world  where  the 
number  of  C programmers  is  inestima¬ 
ble  and  growing  fast.  Yet,  certainly  C 
was  not  your  first  language.  When  did 
your  programming  career  begin  and 
with  what  systems? 

DR:  I  started  when  I  was  in  college  in 
1961. 1  was  a  physics  major.  There  was 
no  such  thing  as  a  Computer  Sciences 
curriculum  then.  The  Comp  Center  at 
Harvard  offered  an  informal  course  in 
programming  on  the  Univac  I,  and  I 
went  to  the  IBM  office  and  got  manu¬ 
als.  In  graduate  school  in  1963  I  was 
the  teaching  fellow  for  the  introduc¬ 
tory  programming  course.  For  a  while 
I  worked  at  Project  MAC  at  MIT.  My 


Al  is  a  contributing  editor  and  colum¬ 
nist  for  DDJ  and  the  author  of  a  num¬ 
ber  of  books  on  C.  He  can  be  reached 
at  DDJ,  501  Galveston  Drive,  Redwood 
City,  CA  94063 


graduate  work  was  theoretical  in  recur¬ 
sive  function  theory.  I  lost  interest  in 
that  aspect  of  things  when  I  finished 
there,  and  I’ve  been  spending  most  of 
my  time  programming  ever  since. 

DDJ:  Do  you  actively  program  now? 

DR:  It  depends  what  you  mean  by  pro¬ 
gramming.  There’s  a  fair  amount  of 
looking  at  stuff  and  deciding  how  it 
should  work.  These  days  there’s  more 
bureaucratic  stuff.  I’m  not  in  manage¬ 
ment,  but  I  write  memos,  look  at  pro¬ 
posals,  complain  to  the  X3J11  C  com¬ 
mittee,  and  things  like  that.  I’m  defi¬ 
nitely  still  involved  in  the  technical  as¬ 
pects  of  things. 

DDJ:  The  ANSI  X3J11  committee  has 
been  five-plus  years  in  arriving  at  a 
proposed  standard  for  the  C  language. 
How  long  did  it  take  you  from  the  time 
you  had  your  original  idea  for  a  C 
language  until  you  had  the  first  com¬ 
piler  running? 

DR:  The  C  language  grew  out  of  an 
earlier  language.  The  syntax  of  the  early 
C  language  was  essentially  that  of  B. 
Over  the  period  of  a  couple  of  years  it 
grew  into  something  like  its  current 
form.  The  most  significant  milestone 
in  the  growth  of  the  language  was  when 
the  Unix  system  was  rewritten  in  C. 

DDJ:  How  long  did  that  take? 

DR:  Mostly  it  was  done  in  the  summer. 
There  were  two  tries  at  it.  This  was  in 
1973.  The  summer  before,  Ken  Thomp¬ 
son  tried  to  do  it,  and  gave  up.  The 
single  thing  that  made  the  difference 
was  the  addition  of  structures  to  the 
language.  When  he  first  tried  there  were 
no  structures.  They  were  in  by  the  next 
summer,  and  this  provided  a  way  of 
(continued  on  page  10) 
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Bjarne  Stroustrup  is  the  creator 
of  C++,  the  object-oriented  ex¬ 
tension  to  the  C  language.  He 
is  a  researcher  at  the  AT&T 
Bell  Laboratories  Computing  Sci¬ 
ence  Research  Center  where,  in  1980, 
he  began  the  development  of  the  C++ 
extensions  that  add  data  abstraction, 
class  hierarchies,  and  function  and  op¬ 
erator  overloading  to  C.  The  C++  lan¬ 
guage  has  undergone  several  versions, 
and  the  latest  is  Version  2.0.  Dr.  Strous¬ 
trup  maintains  an  active  presence  in  all 
matters  concerning  the  development, 
advancement,  standardization,  and  use 
of  C++. 

DDJ:  Many  experts  are  predicting  that 
C++  will  be  the  next  dominant  soft¬ 
ware  development  platform,  that  it  will 
essentially  replace  C. 

BS:  They're  not  alone.  People  were 
saying  that  five  years  ago. 

DDJ:  When  you  conceived  the  idea  of 
C++  as  an  extension  to  the  C language, 
were  you  thinking  about  object-oriented 
programming  in  the  way  it’s  come  to 
be  known,  or  were  you  looking  to  build 
a  solution  to  a  specific  programming 
problem  that  would  be  supported  by  the 
features  that  you  built  into  C++? 

BS:  Both.  I  had  a  specific  problem.  All 
good  systems  come  when  there  is  a 
genuine  application  in  mind.  I  had  writ¬ 
ten  some  simulations  of  distributed  com¬ 
puter  systems  and  was  thinking  about 
doing  more  of  them.  At  the  same  time 
I  was  thinking  about  the  problem  of 
splitting  Unix  up  to  run  on  many  CPUs. 
In  both  cases  I  decided  that  the  prob¬ 
lem  was  building  greater  modularity 
to  get  fire  walls  in  place,  and  I  couldn’t 
do  that  with  C.  I  had  experience  with 
Simula,  writing  rather  complex  simula¬ 
tions,  so  I  knew  the  basic  techniques 


of  object-oriented  programming  and 
how  it  applied. 

To  solve  the  problem  I  added  classes 
to  C  that  were  very  much  like  Simula 
classes.  That,  of  course,  was  the  solu¬ 
tion  to  a  particular  problem,  but  it  in¬ 
cluded  a  fair  amount  of  general  knowl¬ 
edge  about  techniques,  thoughts  about 
complexity  and  management,  complex¬ 
ity  of  modularity  and  all  the  baggage 
that  you  get  from  Simula.  Simula  is  not 
ad  hoc,  especially  not  when  it  comes 
to  the  class  concept,  which  is  what  I 
was  interested  in. 

DDJ:  Are  you  familiar  with  any  of  the 
PC  ports  to  C++,  specifically  Zortech 
C++,  Guidelines  C++,  and  Intek  C++? 

BS:  Only  from  talking  to  people  and 
listening  to  discussions  about  them. 
They  all  sound  good.  The  CFRONT 
ports,  Intek  and  Guidelines,  have  the 
advantage  of  having  the  same  bugs 
and  features  that  you  have  on  the  big¬ 
ger  machines  all  the  way  up  to  the 
Cray,  whereas  Zortech  has  the  advan¬ 
tage  of  being  native  to  the  PC  world. 

I  walked  around  back  in  1985  ex¬ 
plaining  why  the  current  implementa¬ 
tion  of  C++  couldn’t  be  put  on  a  PC.  I 
designed  the  language  under  the  as¬ 
sumption  that  you  had  one  MIPS  and 
one  Meg  available.  Then  one  day  I  got 
fed  up  with  explaining  why  it  couldn’t 
be  done  and  did  it  instead.  It  was  a 
pilot  implementation,  and  it  wasn’t  ever 
used,  but  I  proved  that  it  was  possible, 
and  people  went  and  did  the  real  ports. 
All  the  implementations  are  reasonably 
good,  and  they  could  all  be  better. 
Given  time,  they  will  be. 

DDJ:  Do  the  PC  ports  accurately  im¬ 
plement  C++  the  way  you  have  it  de¬ 
signed? 

(continued  on  page  14) 


Bjarne  Stroustrup 


One  of  the  advantages 
of  C++  is  that  you 
can  take  some  of  the 
preliminary  steps  without 
a  paradigm  shift  from 
function  to  object-oriented 
programming 
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(continued  from  page  8) 
encapsulating  or  describing  the  data 
structures  within  the  operating  system. 
Without  that  it  was  too  much  of  a  mess. 

DDJ:  You  mentioned  complaining  to 
the  ANSI  X3J11  C  committee.  What  was 
the  extent  of  your  participation  in  the 
development  of  the  ANSI  C  standard ? 

DR:  My  participation  in  the  commit¬ 
tee  was  really  quite  minimal.  I  sent 
them  a  couple  of  letters.  One  was  to 
point  out  the  consequences  and  diffi¬ 
culties  of  the  path  they  were  taking 
with  the  new  style  function  definitions 
and  declarations.  It’s  clear  that  the  new 
style  —  function  prototypes,  as  they 
call  them  —  is  a  good  thing.  The  lan¬ 
guage  is  better  for  having  it,  and  it 
should  have  been  done  that  way  the 
first  time.  The  problem,  however,  is  in 
the  interval  before  prototypes  are  uni¬ 
versally  accepted,  while  you  still  have 
both  the  old  and  new  styles.  I  pointed 
out  that  with  that  approach  there  will 
be  confusion  and  the  possibility  of  er¬ 
rors.  For  example,  if  you  think  that 
there’s  a  prototype  in  scope,  you  might 
call  the  function  and  expect  that  the 
arguments  are  going  to  be  coerced  as 
they  would  be  in  regular  ANSI  C.  But 
it  might  not  happen. 

DDJ:  In  the  Rationale  document,  X3J11 
has  paved  the  way  to  eventually  do 
away  with  the  old  style  of  function 
declarations  and  definitions.  Will  that 
solve  the  problem? 

DR:  Yes,  but  in  this  interval  there  is  a 
sticky  situation.  There  are  complicated 
rules  for  what  happens  when  you  mix 
the  new  and  old  styles.  They  covered 
all  the  bases  when  they  made  the  rules, 
but  the  rules  are  messy,  and  most  peo¬ 
ple  couldn’t  reproduce  them  or  explain 
what  they  mean.  The  letter  I  wrote  was 
to  suggest  that  maybe  they  should  think 
about  not  doing  it  if  only  because  it’s 
too  late,  or  as  an  alternative  they  should 
consider  requiring  an  ANSI  compiler 
to  have  the  new  style  only. 

My  second  letter  was  related  to  this 
“no  alias"  business  that  came  up  about 
a  year  and  a  half  ago.  I  felt  more  strongly 
about  this  issue  because  I  felt  they  were 
about  to  make  a  bad  mistake,  and  I 
was  willing  to  spend  a  lot  of  time  get¬ 
ting  them  to  reverse  it. 

Around  December  1987,  when  they 
were  intending  to  produce  the  penulti¬ 
mate  draft,  the  one  that  had  all  the 
technical  things  in  it  (with  possibly  some 
language  polishing  needed,  but  noth¬ 
ing  important),  something  that  had  been 
simmering  a  long  time  came  to  the 
boil.  Some  people  wanted  to  put  in  a 
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mechanism  that  would  reduce  the  prob¬ 
lems  that  optimizers  have  with  aliasing. 

Here’s  the  problem.  Suppose  you 
have  a  single  function  that  has  two 
pointers  as  arguments,  and  the  func¬ 
tion  can  never  be  sure  that  the  pointers 
might  not  point  to  the  same  thing.  Or, 
suppose  one  of  the  pointers  points  to 
some  external  place.  The  function  can¬ 
not  tell  where  the  pointers  are  going 
to  clash.  According  to  the  language 
rules,  this  kind  of  thing  is  possible,  and 
optimizers  have  to  be  very  conserva¬ 
tive  about  it.  In  most  functions  it  might 
never  happen,  and  so  the  conservative 
compiler  will  generate  worse  code  than 
it  would  otherwise.  Languages  such  as 

There’s  still  plenty 
of  work  to  be  done 
finding  languages 
that  have  the 
touch  of  reality 
that  C  has 


Fortran  have  an  easier  job  of  this  be¬ 
cause  such  aliasing  is  simply  forbid¬ 
den.  There’s  no  enforcement,  of  course, 
but  the  compiler  can  take  an  optimistic 
point  of  view.  If  your  program  doesn’t 
work,  someone  can  pull  out  the  stan¬ 
dard  and  say  you  shouldn't  have  done 
that.  Aliasing  was  a  plausible  thing  for 
the  committee  to  think  about.  It  does, 
in  fact,  make  C  somewhat  harder  to 
optimize.  The  mistake  they  made  was 
in  trying  to  design  a  facility  to  allow  the 
programmer  to  say  that  a  particular  func¬ 
tion  has  no  aliasing  problem.  But  they 
actually  blew  it.  The  language  rules 
that  they  developed,  even  after  many 
sessions  of  hard  work,  really  just  weren’t 
correct.  Their  specification  for  how  you 
say  “no  alias”  was  broken  and  would 
have  been  much  more  dangerous  than 
not  having  it.  If  this  had  happened 
three  or  four  years  ago,  people  would 
have  seen  that  this  was  wrong,  fiddled 
with  it,  and  either  thrown  it  out  or  fixed 
it  one  way  or  the  other.  But  this  was 
supposed  to  be  the  next  to  the  last 
draft,  and  all  the  technical  requirements 
were  supposed  to  be  already  done, 
and  it  was  just  broken. 

That  December  I  drafted  a  long  and 
strongly  worded  letter  to  them  saying 
that  this  just  won’t  do,  and  pointed  out 


the  problems  that  I’d  found.  I  even 
went  to  the  meeting,  the  first  X3J11 
meeting  I’d  been  to,  and  argued  against 
it.  What  got  me  worried  and  annoyed 
was  that  this  had  happened  when  it 
did.  If  the  thing  had  gone  ahead  it 
would  have  been  a  real  bug  in  the 
specification.  On  the  other  hand,  fixing 
it  essentially  meant  a  technical  change, 
an  important,  non-editorial  change,  and 
they  would  need  another  long  public 
review  period.  The  point  of  view  that 
I  advanced  was  to  get  rid  of  it.  I  figured 
that  my  argument  had  to  be  simple  to 
understand.  If  I  had  said,  “This  ‘no 
alias’  is  broken,  here’s  another  thing 
that  you  should  do  instead,”  I  could 
see  us  getting  bogged  down  endlessly 
worrying  about  the  technical  details, 
so  I  figured  it  was  better  to  argue  that 
they  should  just  throw  it  out  altogether. 

That  was  the  only  really  detailed  in¬ 
volvement  I  had  with  X3J11.  The  out¬ 
come  was  that  there  is  no  specification 
for  “no  alias.”  They  voted  it  out.  Except 
for  some  slight  fiddles,  the  draft  that  is 
now  before  X3  is  technically  identical 
to  what  it  was  nearly  two  years  ago. 

Aside  from  those  two  issues,  I  left 
them  alone  for  two  reasons.  One  is 
that  to  take  part  in  a  standardization 
effort  is  an  enormous  amount  of  work. 
There  are  three  one-week  meetings  a 
year  all  over  the  world,  a  lot  of  detailed 
reading,  and  I  really  didn’t  have  the 
heart  to  do  that.  The  second  reason  is 
that  it  became  dear  early  in  the  pro¬ 
ceedings  that  the  committee  was  on 
the  right  track  themselves.  Their  char¬ 
ter  was  to  codify  and  to  standardize  the 
language  as  it  existed.  They  decided 
in  advance  to  do  that  and  that  is  what 
they  did.  They  did  add  some  new  things. 
The  function  prototypes  are  by  far  the 
most  obvious,  and  there  are  a  lot  more 
minor  things,  but  mainly  they  stuck  to 
their  charter. 

I  think  they  did  a  very  good  job, 
particularly  when  compared  to  the 
things  that  are  happening  in  the  For¬ 
tran  committee,  X3J3,  where  there  are 
wide  swings  back  and  forth  about  the 
strange  new  things  they’re  adding  in, 
taking  out,  and  putting  back  in.  They 
have  great  political  arguments  between 
customers  and  vendors,  Europeans  ver¬ 
sus  North  Americans,  and  it  really  seems 
to  be  a  free-for-all.  Even  though  some 
wrangling  went  on  in  the  C  committee, 
with  the  people  involved  seeming  fairly 
fierce  when  you  looked  at  it  from  out¬ 
side,  it’s  obvious  that  X3J11  was  a  com¬ 
paratively  tranquil  and  technically  wise 
group. 

The  upshot  is  that  I  think  they  did  a 
good  job.  Certainly,  though,  if  I’d  con¬ 
tinued  to  work  on  things,  some  of  the 
details  would  have  been  different. 
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DDJ:  Are  there  any  major  areas  where 
you  disagree  with  the  standard  as  it 
exists  now ? 

DR:  There  are  some  obvious  weak¬ 
nesses.  For  example,  they  have  never 
worked  out  what  const  really  means. 
One  of  its  intents  is  to  say  that  this  is 
some  data  that  can  be  put  into  some 
read-only  storage  because  it’s  never  go¬ 
ing  to  be  modified.  The  definition  that 
they  have  now  is  sufficient  for  that.  But 
they  also  had  other  ideas  about  what 
it  should  mean,  having  to  do  with  opti¬ 
mization,  for  example.  The  hope  was 
that  const  is  somehow  a  promise  that 
the  compiler  could  assume  that  the 
data  item  wouldn’t  change  underfoot. 

If  you  have  a  pointer  to  a  const ,  one 
might  hope  that  what  is  const  is  not 
going  to  suddenly  change  secretly.  But, 
unfortunately,  the  way  the  rules  read 
that’s  not  actually  true.  It  can  change, 
and  this  wasn’t  just  an  oversight.  In 
fact,  they  are  potentially  overloading 
the  meaning  of  const.  There  are  ideas 
involved  other  than  what  people  hoped 
to  get,  and  they  never  really  worked 
out  exactly  which  ones  they  wanted 
and  which  ones  they  didn’t  want.  It’s  a 
little  confusing. 

It’s  generally  recognized  that  the  stan¬ 
dardization  of  the  library  was  as  impor¬ 
tant  as  the  standardization  of  the  lan¬ 
guage.  Among  Unix  systems  there  are 
few  variations  on  what’s  available  in 
the  library.  Most  things  are  pretty  much 
the  same.  In  recent  years,  the  use  of  C 
has  spread  far  outside  of  Unix  systems, 
and  the  libraries  supplied  with  compil¬ 
ers  tend  to  vary  a  lot,  although  many 
of  them  were  based  on  what  was  avail¬ 
able  on  Unix.  So  the  standardization 
of  the  library  is  important.  On  the  other 
hand,  I’ve  heard  lots  of  complaints, 
both  from  users  and  implementors,  that 
what  they  standardized  and  some  of 
the  rules  and  interfaces  for  library  rou¬ 
tines  were  not  very  well  worked  out. 
There  may  be  more  there  than  is  neces¬ 
sary.  Things  got  too  complicated. 

DDJ:  What  was  the  rationale  behind 
the  decision  to  leave  out  the  read,  write, 
open,  close,  and  create  functions? 

DR:  Those  functions  are  viewed  as  be¬ 
ing  quite  specific  to  the  Unix  system. 
Other  operating  systems  might  have 
great  difficulty  in  supplying  things  that 
work  the  same  way  those  do.  The  idea 
of  the  original  pre-ANSI  standard  I/O 
library  was  to  make  it  possible  to  im¬ 
plement  those  I/O  routines  in  a  variety 
of  operating  systems.  It  took  us  a  cou¬ 
ple  of  tries  to  reach  that  particular  in¬ 
terface.  The  machines  we  had  here  were 
the  PDP-11  running  Unix,  a  Honeywell 


6000  running  GECOS,  and  some  IBM 
360s  running  various  IBM  systems.  We 
wanted  to  have  standard  I/O  routines 
that  could  be  used  in  all  the  operating 
systems,  even  those  that  didn’t  have 
anything  like  Unix’s  read  and  write. 
The  committee  felt  that  it  was  better  to 
let  the  IEEE  and  other  Unix  standardi¬ 
zation  groups  handle  that.  They  spe¬ 
cifically  avoided  putting  things  in  the 
C  library  that  were  Unix-specific  unless 
they  had  meaning  in  other  systems. 

They  did  another  thing  that  people 
don’t  quite  understand.  They  explicitly 
laid  out  the  name  space  that  a  standard 
compiler  is  allowed  to  usurp  or  claim. 
In  particular,  the  guarantee  is  that  there 
is  a  finite  list  of  names  that  the  compiler 
and  the  compiler  system  take  up.  These 
are  simple  names,  beginning  with  un¬ 
derscore,  and  are  listed  in  the  back  of 
the  standard,  something  like  keywords. 
You  are  allowed  to  use  any  name  that 
isn’t  on  this  list.  In  an  ANSI-conforming 
world,  you  are  allowed  to  define  your 
own  routine  called  read  or  write  and 
even  run  it  on  a  Unix  system.  It’s  guar¬ 
anteed  that  this  will  be  your  routine 
and  that  your  use  of  the  name  does  not 
conflict  with  any  I/O  that  the  library 
itself  does  on  your  behalf.  The  Unix 
library  authors  will  be  constrained  to 
have  an  internal  name  for  read  that 
you  can’t  see  so  that  if  you  bring  a  C 
implementation  from  a  big  IBM  ma¬ 
chine  or  from  an  MS-DOS  machine  and 
you  happen  to  use  the  name  read  for 
your  own  routine,  it  will  still  compile 
and  run  on  a  Unix  system  even  though 
there’s  a  system  call  named  read.  They 
have  circumscribed  the  so-called  name 
space  pollution  by  saying  that  the  sys¬ 
tem  takes  these  names  and  no  others. 

DDJ:  How  can  they  be  sure  that  an 
implementor  won’t  need  other  than 
those  specific  names  from  the  list? 

DR:  There  are  rules  for  how  the  inter¬ 
nal  people  can  generate  names,  namely 
these  underscore  conventions.  The  end 
user  is  not  allowed  to  use  underscore 
names  because  any  of  these  might  be 
used  internally.  There  is  a  problem, 
though.  They  made  a  list  of  things  and 
said  they’ll  do  this  and  no  more,  and 
that  helps.  But  there  is  still  a  problem 
for  the  writer  of  a  library  who  wants  to 
sell  or  distribute  it.  You’re  in  a  bind 
because  you  don’t  know  all  the  under¬ 
score  names  that  all  the  implementa¬ 
tions  are  going  to  use.  If  you  have  your 
own  internal  names,  you  can’t  be  sure 
that  they’re  not  going  to  conflict  some¬ 
where.  If  they  have  underscores,  they 
might  conflict  with  the  underlying  im¬ 
plementation.  If  they  don’t,  then  they 
might  conflict  with  things  that  your 


end  users  are  going  to  use.  The  C  com¬ 
mittee  did  not  solve  the  problem  that 
other  languages  have  tackled  explic¬ 
itly.  There  are  other  ways  of  control¬ 
ling  the  name  space  problem.  They 
made  a  convention  that  helps,  but  it 
certainly  didn’t  solve  the  real  problem. 
It  solved  it  enough  to  improve  the  situ¬ 
ation.  The  basic  problem  with  an  un¬ 
controlled  name  space  is  that  if  you 
write  a  program,  and  it  just  uses  some 
name  that  you  made  up,  it  may  be 
actually  difficult  to  find  out  that  this  is 
not  the  same  name  as  some  random 
routine  that’s  used  internally  by  your 
system  library.  Unfortunately,  we  here 
at  Bell  Labs  are  in  a  bad  position  to 
notice  this  and  do  something  about  it 
because  in  our  group  we’ve  simultane¬ 
ously  developed  the  compiler  and  the 
library  and  the  Unix  system,  and  so 
people  here  tend  to  know  the  names. 

So,  to  summarize  X3J 1 1 ,  the  two  larg¬ 
est  things  the  committee  did  were  func¬ 
tion  prototypes  and  the  standardiza¬ 
tion  of  the  library.  It  was  more  work 
than  anybody  expected,  but  I’m  per¬ 
fectly  happy  with  what  they  did.  The 
only  problem  was  it  took  twice  as  long 
as  they  thought. 

DDJ:  Do  you  see  a  potential  for  other 
standard  extensions  to  C,  beyond  those 
added  by  X3J1 1? 

DR:  One  of  the  major  excuses  they 
give  for  not  doing  something  is  that 
there’s  no  practice,  no  prior  art.  So 
obviously  people  will  try  to  create  prior 
art  for  the  things  they’d  like  to  have 
happen.  One  such  group  is  the  Nu¬ 
merical  C  Extensions  Group. 

There  are  people  who  have  strong 
views  about  what  should  happen.  The 
idea  is  to  get  together  with  this  group 
and  agree  that  these  are  the  things  we 
need  to  have,  so  let’s  make  some  rules 
so  that  when  people  try  things  out, 
we’ll  all  be  trying  it  the  same  way,  and 
we’ll  have  a  coherent  story  to  tell,  if 
there  are  going  to  be  these  extensions. 

Most  of  them  have  to  do  with  IEEE 
arithmetic  issues,  exceptions  and  such, 
for  example.  There’s  a  core  of  things 
that  are  more  general,  and  one  that 
interests  me  is  variable  arrays  with  ad¬ 
justable  sizes.  One  of  the  things  C  does 
successfully  is  deal  with  single-dimen¬ 
sion  arrays  that  can  be  variable  in  size, 
but  it  doesn’t  deal  with  multi-dimen¬ 
sioned  arrays  that  are  variable  at  all. 
This  is  an  important  lack  for  numeric 
types,  because  it  makes  it  hard  to  write 
library  routines  that  manipulate  arrays. 
Multiplying  two  arrays  is  a  bit  painful 
in  C  if  the  arrays  are  variable  in  size. 
You  can  do  it  but  you  have  to  program 
it  in  detail  and  the  interface  doesn’t 
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look  pleasant.  That’s  an  obvious  need, 
and  I  volunteered  to  look  at  how  it 
might  be  done. 

The  NCEG  will  probably  try  to  be¬ 
come  official.  They  will  affiliate  them¬ 
selves  either  with  X3J11  or  as  an 
IEEE  standardization  organization.  This 
would  give  them  more  clout.  Also,  many 
of  the  companies  involved  worry  about 
legal  issues.  Companies  who  are  mem¬ 
bers  of  informal  groups  deciding  stan¬ 
dards  worry  about  anti-trust,  whereas 
if  they  are  members  of  official,  blessed 
standards  organizations,  then  they  can 
contribute.  They  worry  about  being  ac¬ 
cused  of  going  off  into  a  corner  and 
doing  things  behind  other  people’s 
backs.  It’s  better  to  do  it  in  the  open. 
This  may  be  just  some  lawyer’s  night¬ 
mare.  NCEG  will  probably  become  a 
subcommittee  of  X3J11. 

DDJ:  One  non-ANSI  extension  to  C  is 
C++,  a  superset  language  that  surrounds 
C  with  disciplines  and  paradigms  that 
go  beyond  its  original  intent  as  a  pro¬ 
cedural  language.  Can  you  comment 
on  how  appropriate  that  is  and  how 
successful  it  has  been? 

DR:  Let  me  confess  at  the  start  that  I 
know  less  about  C++  than  I  probably 
should.  C  is  a  very'  low-level  language 
on  a  variety  of  fronts.  The  kinds  of 
operations  that  it  performs  are  quite 
basic.  The  control  over  names  and  visi¬ 
bility  is  basic.  The  defects  or  limitations 
of  C  in  this  area  are  most  evident  when 
you  get  into  a  large  project  where  you 
need  strong  standards,  rules,  and  mecha¬ 
nisms  outside  the  language.  Language 
developments  such  as  C++  are  trying 
to  supply  some  of  the  structure  within 
the  rules  of  the  language  for  controlled 
visibility  of  name  space  and  are  trying 
to  encourage  various  kinds  of  modu¬ 
larization.  This  is  good,  I  suppose. 

C  was  designed  in  an  environment 
where  modularity  was  encouraged  not 
so  much  by  the  language  but  by  the 
kinds  of  programs  we  wrote.  In  the 
Unix  system,  the  tradition  is  for  small 
utilities  that  work  together  as  tools, 
and  the  interfaces  between  them  were 
set  by  the  conventions  and  rules  of 
the  operating  system,  i.e.,  pipelines 
and  so  forth.  The  complexity  of  the 
pieces  was  kept  low  by  custom.  Com¬ 
mands  tend  to  be  simple.  In  the  world 
today,  there’s  a  certain  amount  of  ad¬ 
miration  for  that  point  of  view.  Cer¬ 
tainly  the  appreciation  for  that  style  is 
part  of  the  reason  for  the  growth  of 
Unix.  People  now  are  undertaking  the 
building  of  much  bigger  systems,  and 
things  that  we  handled  by  convention 
ten  or  fifteen  years  ago  must  be  han¬ 
dled  by  more  explicit  means.  C++  is 


one  such  attempt. 

Bjarne  decided  to  design  a  compat¬ 
ible  superset  of  C  and  to  translate  the 
C++  language  into  C  code.  That  ap¬ 
proach  is  not  without  its  problems.  First, 
having  decided  that  C++  is  going  to 
be  largely  compatible  with  C,  every 
time  he  departs  from  that  he’s  under 
pressure  either  because  of  some  acci¬ 
dent  or  because  ANSI  changed  some¬ 
thing.  Or  because  he  feels  that  there’s 
something  he  has  to  differ  in,  people 
are  going  to  complain  and  get  con¬ 
fused.  Second,  he  is  constrained  by  the 
choice  to  make  a  C++  to  C  translator 

C  is  a  very  low-level 
language.  The  kinds  of 
operations  it  performs 
are  quite  basic 


possible,  that  is,  he  is  constrained,  as 
C  was,  by  the  existing  tools  of  the 
various  systems.  The  whole  separate 
compilation  business  in  C++  is  made  a 
lot  harder  by  the  desire  to  make  it  work 
with  existing  tools.  If  he  could  have 
simply  designed  a  language  and  imple¬ 
mented  it,  then  a  lot  of  the  anguish 
would  have  been  avoided. 

DDJ:  Rumor  is  that  within  Bell  Labs , 
C++  is  now  called  C.  and  C  is  called 
"old  C.  "Any  truth  in  that? 

DR:  I’ve  asked  Bjarne  not  to  say  “old 
C,”  and,  as  far  as  I  know,  he  has  com¬ 
plied  with  that  request. 

DDJ:  Colleges  and  universities  have 
started  offering  courses  in  C.  Some  C 
tutors  have  observed  that  many  instruc¬ 
tors  either  don 't  understand  C  well 
enough  or  they  don ’t  understand  teach¬ 
ing  well  enough  to  insulate  the  novice 
student  from  the  kinds  of  things  you 
can  do  in  C,  things  that  the  student 
cannot  grasp.  In  light  of  that,  and  as 
compared  to  Pascal,  how  do  you  view 
C  as  a  potential  teaching  language? 

DR:  Obviously,  C  was  never  designed 
to  be  a  teaching  language.  It  was  de¬ 
signed  as  a  tool  to  express  the  kind  of 
programs  that  we  were  trying  to  write 
at  the  time.  And  it’s  fairly  low  level  in 
that  concepts,  like  pointers,  have  a  promi¬ 
nent  role.  I  would  not  argue  that  C  is  a 
particularly  good  language  for  teach¬ 
ing  programming.  As  Pascal  was  ex¬ 
plicitly  designed  for  that. 


Pascal’s  main  fault  is  that  you  cannot 
use  Pascal  originally  designed  to  ex¬ 
press  all  the  things  you  need  to,  cer¬ 
tainly  not  in  a  systems  environment, 
and  not  for  general  applications  either 
because  of  explicit  constraints  that  are 
built  into  the  language.  C  was,  from  the 
very  start,  designed  to  do  all  the  things 
that  we  found  necessary  in  order  to 
express  ourselves,  and  little  design 
thought  was  given  to  preventing  peo¬ 
ple  from  using  its  powerful  features. 

Nevertheless,  it’s  possible  to  teach  C 
in  a  way  that’s  reasonably  safe  if  you 
start  with  parts  of  the  language  that  are 
similar  to  other  procedural  languages. 
Then  you  can  teach  C’s  more  unusual 
aspects  —  pointers,  for  example  —  as 
cliches  or  set  ways  of  expressing  array 
manipulations  and  so  forth.  Later  you 
can  gradually  widen  out  into  the  more 
general  things  possible  with  pointer 
manipulations. 

I  have  not  had  the  experience  that 
the  tutors  have  had.  Part  of  the  diffi¬ 
culty  with  being  in  a  position  like  this 
is  that  you  have  very  little  opportunity 
to  see  what  the  novice  really  feels.  But 
perhaps  the  reason  there  are  not  better 
instructors  is  that  things  have  grown 
fast,  and  there  might  be  people  teach¬ 
ing  C  who  only  recently  took  the  intro¬ 
ductory  course  on  the  language  them¬ 
selves. 

DDJ:  Would  you  attempt  a  prediction 
for  the  future  of  the  C  language? 

DR:  I  think  the  period  of  C’s  largest 
growth  is  over,  although  it  will  be  in¬ 
creasingly  used  and  it  probably  will 
not  change  very  fast.  The  new  lan¬ 
guage  developments  based  on  C  will 
be  on  successors  such  as  C++  or  per¬ 
haps  some  things  we  haven’t  heard  of. 
In  terms  of  what  C  tried  to  do,  I  think 
it  succeeded  fairly  well.  The  goals  were 
reasonably  modest.  There’s  still  plenty 
of  work  to  be  done  finding  languages 
that  have  the  touch  of  reality  that  C 
has,  work  where  you  handle  real  prob¬ 
lems  in  real  environments  as  opposed 
to  dealing  with  elegant  creations  that 
can’t  be  used.  Sometimes  things  can’t 
be  used  just  because  the  compilers  don’t 
exist  on  the  machines  people  have. 
Sometimes  it’s  because  there  are  sim¬ 
ply  flaws  in  the  design,  not  from  the 
language  point  of  view,  but  from  the 
point  of  view  of  what  the  language 
ends  up  doing  in  the  real  world.  And 
in  that  respect,  C  seems  to  have  worn 
fairly  well. 

DDJ 


Bjarne  Stroustrup’s  interview  starts  on 
page  9. 
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BJARNE  STROUSTRUP 


(continued  from  page  9) 

BS:  We  do  have  a  problem  with  port¬ 
ability  from  one  machine  to  another. 
If  you  have  a  large  program  of  ten  to 
twenty  thousand  lines,  it’s  going  to  take 
you  a  day  to  move  from  one  indepen¬ 
dent  implementation  to  another.  We’re 
working  on  that.  Standardization  is  be¬ 
ginning.  We’re  all  sharing  language  man¬ 
ual  drafts,  and  so  it’s  trying  to  pull 
together.  But  a  large  program  port  will 
still  take  a  day  as  compared  to  the 
ANSI  standard  ideal  where  you  take 
something  from  a  PC  to  a  Cray  and 
everything  works.  Of  course,  you  never 
really  get  to  that  point  even  after  full 
standardization. 

DDJ:  There  are  lots  of  rumors  about 
Borland  and  Microsoft  coming  out  with 
C++  compilers.  Has  any  of  this  come 
to  your  attention? 

BS:  I’ve  talked  to  people  both  from 
Microsoft  and  from  Borland.  They’re 
both  building  a  C++  compiler,  and  it 
sounds  as  if  they’re  building  it  as  close 
to  the  2.0  specification  as  they  jolly 
well  know  how  to.  Naturally,  for  their 
machines  they’ll  need  something  like 
near  and  far,  which  is  not  standard 
language,  but  that’s  pretty  harmless. 

Both  asked  for  a  bit  of  advice  and 
Microsoft  asked  for  the  reference  manu¬ 
als.  I’ve  talked  to  the  Borland  guys.  I’m 
sad  to  say  they  didn’t  ask  for  a  manual, 
but  maybe  they  got  one  from  other 
sources.  The  PC  world  is  pretty  cut¬ 
throat.  Maybe  people  get  the  impres¬ 
sion  everybody  is  cut  throat.  That’s  not 
quite  the  case. 

DDJ:  One  of  the  advantages  of  lan¬ 
guages  such  as  C  and  C++  is  that  they 
can  be  implemented  on  a  wide  range 
of  machines  ranging  from  PCs  to  Crays. 
With  more  and  more  people  using  PCs 
in  their  work,  it’s  widely  believed  that 
acceptance  in  the  PC  world  is  what 
spelled  the  overwhelming  success  of  C 
as  the  language  of  choice. 

BS:  That’s  widely  believed  in  the  PC 
world.  In  the  minicomputer  world  it’s 
widely  believed  that  the  PDP-11  and 
the  VAX  spelled  the  success  of  C  and 
that  is  why  the  PC  world  picked  it  up. 
One  of  the  reasons  C  was  successful  is 
that  it  was  able  to  succeed  in  very 
diverse  environments.  There  are  enough 
languages  that  work  in  the  PC  world, 
enough  that  work  in  the  minicomputer 
world,  enough  that  work  on  the  large 
machines.  There  were  not  very  many 
languages  that  worked  on  all  of  them, 
and  C  was  one  of  them.  That’s  a  major 
factor.  People  like  to  have  their  pro¬ 
grams  run  everywhere  without  too  many 


changes,  and  that’s  a  feature  of  C.  And 
it’s  a  feature  of  C++. 

DDJ:  Do  you  see  the  PC  as  figuring  as 
prominently  in  the  acceptance  of  C++? 

BS:  Definitely.  There  are  probably  as 
many  C++  users  on  PCs  as  on  bigger 
systems.  Most  likely  the  number  of  PC 
users  will  be  growing  the  fastest  be¬ 
cause  the  machines  are  smaller.  People 
who  would  never  use  a  PC  for  their 
professional  work  —  there  are  still  a  lot 
of  those  —  nevertheless  like  to  play  with 

Programming 
is  an  art  like  riding 
a  bicycle.  It’s  learned 
by  doing 


things  on  a  PC  to  see  what  it  is,  and  that 
is  where  PCs  come  in.  Similarly,  if  you 
are  working  on  a  PC,  sooner  or  later 
you  run  into  a  bigger  machine,  and  it’s 
nice  to  be  able  to  carry  over  your  work. 
I’m  very  keen  on  portability. 

DDJ:  Do  you  have  opinions  as  to 
whether  preprocessing  translators,  such 
as  the  CFRONT  implementation  on 
Unix,  have  advantages  over  native  com¬ 
pilers  such  as  Zortech  C++? 

BS:  It  depends  on  what  you’re  trying 
to  do.  When  I  built  C++  I  felt  that  I 
couldn’t  afford  to  have  something  that 
was  hard  to  port,  meaning  it  mustn’t 
take  more  than  a  couple  of  days.  I 
thought  if  I  built  a  portable  code  gen¬ 
erator  myself,  it  would  be  less  than 
optimal  everywhere.  So,  I  thought  if  I 
generate  C,  I  could  hijack  everybody 
else’s  code  generators. 

For  the  last  40  years  we’ve  been  look¬ 
ing  for  a  universal  intermediate  lan¬ 
guage  for  compilation,  and  I  think  we’ve 
got  it  now,  and  it’s  called  C.  So,  what  I 
built  was  something  that  was  a  full 
compiler,  full  semantic  check,  full  syn¬ 
tax  check,  and  then  used  C  as  an  inter¬ 
mediate  representation.  In  essence  I 
built  a  traditional  two-pass  compiler. 
And  two-pass  compilers  have  great  ad¬ 
vantages  if  you’ve  got  lots  of  code  gen¬ 
erators  sitting  around  for  them,  and  I 
had.  They  have  the  advantage  that  they 
tend  to  find  errors  faster  than  one-pass 
compilers  because  they  don’t  start  gen¬ 
erating  code  until  they  have  decided 
that  the  program  looks  all  right.  But 


they  tend  to  be  slow  when  they  actu¬ 
ally  generate  code.  They  also  tend  to 
be  slightly  larger  and  slightly  slower 
throughout  the  whole  process  because 
they  have  to  go  through  the  standard 
intermediate  form  and  out  again. 

And  so,  the  advantages  for  the  trans¬ 
lator  technology  are  roughly  where  you 
have  lots  of  different  machines  and 
little  manpower  to  do  the  ports.  I  see 
the  one-pass  compilers,  the  so-called 
native  compilers,  useful  for  machines 
and  architectures  where  the  manpower 
available  for  support  and  development 
is  sufficient  to  make  it  worthwhile,  which 
is  when  you’ve  got  enough  users. 

The  two-pass  strategy  for  translators 
was  essential  in  the  early  days  and  will 
remain  essential  as  long  as  new  ma¬ 
chine  architectures  and  new  systems 
come  on  the  market  so  that  you  need 
to  get  a  compiler  up  and  running 
quickly.  As  the  C++  use  on  a  given 
system  matures,  you’ll  see  the  transla¬ 
tors  replaced  by  more  specifically  crafted 
compilers.  On  the  PC,  for  example, 
CFRONT  likes  memory  too  much;  it 
was  built  for  a  system  where  memory 
was  cheap  relative  to  CPU  time.  So 
once  you  know  you  are  working  for  a 
specific  architecture,  you  can  do  intel¬ 
ligent  optimizations  that  the  highly  port¬ 
able  strategy  that  I  was  using  simply 
mustn’t  attempt. 

DDJ:  Are  there  different  debugging  con¬ 
siderations  when  you  are  using  a  pre¬ 
processing  translator? 

BS:  One  of  the  things  that  people  have 
said  about  the  translators  is  that  you 
can’t  do  symbolic  debugging.  That’s 
just  plain  wrong  because  the  informa¬ 
tion  is  passed  through  to  the  second 
pass  and  you  can  do  debugging  of  C++ 
at  the  source  level.  Using  the  2.0  trans¬ 
lator  we’re  doing  that.  The  1.2  versions 
didn’t  have  quite  enough  finesse  to  do 
it,  and  people  didn’t  invest  enough  in 
modifying  debuggers  and  the  system- 
build  operations  to  give  good  symbolic 
debugging.  But  now  you  have  it. 

DDJ:  Can  you  estimate  the  worldwide 
C++  user  base  today? 

BS:  Fifty  thousand  plus,  and  growing 
fast,  and  that  is  a  very  conservative 
estimate. 

DDJ:  Have  you  formed  plans  to  re¬ 
write  any  or  all  of  Unix  with  C++? 

BS:  Unfortunately,  I  haven’t,  despite 
that  being  one  of  my  original  thoughts. 
I’ve  been  bitten  trying  to  write  software 
that  was  too  complex  for  the  tools  I 
had.  When  thinking  about  rewriting 
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Unix,  I  decided  that  C  wasn't  up  to  the 
job.  I  diverted  into  tool  building  and 
never  got  out  of  that  diversion.  I  know 
that  there  is  an  operating  system  writ¬ 
ten  in  C++  at  the  University  of  Illinois. 
It  has  a  completely  different  kernel,  but 
it  runs  Unix  and  you  can  make  it  look 
like  System  V,  USD,  or  a  mixture  of  the 
two  by  using  different  paths  through 
the  inheritance  trees  in  C++.  That’s  a 
totally  object-oriented  system  built  with 
C++.  I  know  that  AT&T  and  Sun  have 
been  talking  about  Unix  System  V,  Re¬ 
lease  5,  and  that  there  are  projects  work¬ 
ing  on  things  like  operating  systems 
rewrites,  but  whether  they  become  real 
or  not  depends  more  on  politics  and 
higher  corporate  management  than  any¬ 
thing  else.  Why  should  we  guess?  All 
we  can  do  is  wait  and  see. 

DDJ:  Is  what  you  do  now  primarily 
related  to  the  development  of  C++  or 
the  use  of  it? 

BS:  Both.  1  write  a  fair  bit  of  code,  still. 

I  do  a  lot  of  writing,  and  I  coordinate 
people,  saying  “Hey,  you  need  to  talk 
to  that  guy  over  there,”  then  getting 
out  of  the  loop  fast.  I  do  a  fair  bit  of 
thinking  about  what  else  needs  to  be 
done  with  C++  and  C++  tools,  libraries 
and  such. 

DDJ:  C  is  a  language  of  functions, 
and  a  large  part  of  the  ANSI  C  stan¬ 
dard  is  the  standardization  of  the func¬ 
tion  library.  C++  has  all  that  as  well 
and  adds  classes  to  the  language.  Is 
there  a  growing  library  of  C++  classes 
that  could  eventually  become  part  of  a 
standard? 

BS:  The  problem  is  there  are  several 
of  them.  We  use  some  inside  AT&T, 
and  several  of  the  other  purveyors  of 
C++  compilers  and  tools  have  their  own 
libraries.  The  question  is  to  what  extent 
we  can  pull  together  for  a  standard 
library.  I  think  that  we  can  eventually 
get  to  a  much  larger  standard  library 
and  much  better  than  what  is  available 
and  possible  in  C.  Similarly,  you  can 
build  tools  that  are  better  than  what  is 
possible  with  C  because  there  is  more 
information  in  the  programs. 

But  people,  when  they  say  standards, 
tend  to  think  about  intergalactic  stan¬ 
dards,  about  things  that  are  available 
in  any  implementation  anywhere,  and 
I  think  that  they  think  too  small.  There 
are  good  reasons  for  differences  be¬ 
tween  the  ideal  C++  environment  for  a 
Cray  and  the  ideal  C++  environment 
for  a  PC.  The  orientation  will  be  differ¬ 
ent  as  will  the  emphasis  on  what  is 
available.  So  we  will  see  many  stan¬ 
dards,  some  for  machine  architectures, 


some  over  ranges  of  machines,  some 
national  standards.  You  could  imagine 
the  French  having  a  whole  series  of 
libraries  and  tools  that  would  be  stan¬ 
dard  for  people  doing  French  word 
processing,  for  instance.  You  will  see 
national  standards,  international  stan¬ 
dards,  industry  standards,  departmen¬ 
tal  standards.  A  group  building  things 
like  telephone  operator  control  panels 
would  have  the  standard  libraries  for 
everybody  in  the  corporate  department 
doing  that  kind  of  work.  But  a  token 
standardization  of  everything,  you  won’t 
see.  The  world  is  simply  too  big  for 
that.  But  we  can  do  much  better  than 
we’re  doing  now. 

DDJ:  To  the  programmer,  there  is  an 
event-driven  or  object-oriented  appear¬ 
ance  to  the  graphical  user  interfaces 
(X  Windows,  the  Macintosh,  Presenta¬ 
tion  Manager,  MS-DOS  Windows,  and 
so  on).  These  seem  to  be  a  natural  fit 
for  the  class  hierarchies  of  C++.  How 
would  these  facilities  be  best  imple¬ 
mented,  and  do  you  know  of  any  re¬ 
cent  efforts  in  these  areas? 

BS:  Some  people  have  the  idea  that 
object-oriented  really  means  graphics 
because  there  is  such  a  nice  fit.  That 
has  not  been  my  traditional  emphasis. 
The  examples  people  have  seen  of  ob¬ 
ject-oriented  programming  and  object- 
oriented  languages  have,  by  and  large, 
been  fairly  slow.  Therefore,  their  use 
has  been  restricted  to  areas  where  there’s 
a  person  sitting  and  interacting.  People 
are  relatively  slow. 

My  first  aims  were  in  areas  where 
you  had  complex  programs  that  had 
a  very  high  demand  on  CPU  and  mem¬ 
ory,  so  that’s  where  I  aimed  first.  But 
people  have  been  building  very  nice 
toolsets  for  doing  user  interfaces  with 
C++.  There  is  one  from  Stanford  called 
“Interviews.”  Glockenspiel,  in  coopera¬ 
tion  with  Microsoft,  is  selling  Common 
Views,  which  is  a  C++  toolset  that  looks 
and  feels  exactly  the  same  whether 
you  are  under  Presentation  Manager, 
MS-DOS  Windows,  or  on  a  Mac.  There 
are  C++  libraries  for  Open  Look. 

The  problem  with  all  these  so-called 
standards  is  that  everybody  seems  to 
have  their  own  standards,  and  then 
you  start  wondering  how  you  can  get 
toolsets  that  give  platform  indepen¬ 
dence  across  all  of  these.  I  think  that’s 
one  place  where  C++  comes  in.  Most 
of  the  differences  between  the  major 
systems  in  the  areas  of  text  handling  — 
as  opposed  to  high-performance 
graphics  —  seem  to  be  quite  manage¬ 
able  as  a  common  set  of  classes  that 
could  be  standardized  at  the  language 
level.  It’s  certainly  something  that’s 


worth  exploring  because  the  world  is 
getting  more  fragmented. 

DDJ:  Are  you  familiar  with  Objective 
C,  a  C  language  extension  that  ap¬ 
pears  to  do  at  least  a  subset  of  what 
C++  does,  and  how  do  the  two  lan¬ 
guages  compare? 

BS:  Vaguely.  The  company  that  sells 
it  will  claim  that  it  does  a  superset  of 
what  C++  does,  and  that  whatever  C++ 
does  that  it  does  not,  is  not  as  impor¬ 
tant,  naturally,  I  disagree.  There  is  much 
higher  emphasis  in  C++  on  static  type 
checking  and  on  coherence  of  the  type 
system.  C++  is  a  rather  large  affair  with 
multiple  purveyors  and  multiple  librar¬ 
ies,  where  Objective  C  is  a  corporate 
language  from  a  corporation  that  wants 
to  make  its  fortune  out  of  it.  That  places 
a  different  emphasis  on  everything. 

DDJ:  Concurrent  C  and  Concurrent 
C++  are,  like  C++,  extensions  to  the 
language.  They  add  parallel  process¬ 
ing  operations  to  C  and  C++  for  the 
development  of  multitasking  programs 
that  are  portable  among  multitasking 
platforms.  Do  you  have  any  comments 
on  Concurrent  C++?  Is  there  a  need 
for  portable  parallel  processing,  and 
do  you  think  that  Concurrent  C++ fills 
that  need? 

BS:  I  don’t  like  the  idea  of  putting 
ADA  tasking  into  C  or  C++.  I  think  it 
solves  the  issues  dealing  with  concur¬ 
rency  at  the  wrong  level,  sort  of  a 
medium-level  thing.  It  doesn’t  give  the 
transaction  processing  view  and  trans¬ 
action  logging  that  you  need  in  data¬ 
bases.  It  doesn’t  give  the  machine- 
near  world  that  you  need  when  you 
write  an  operating  system  kernel  or  a 
real-time  application.  Personally,  I  don’t 
like  that  approach  at  all.  The  approach 
I’ve  taken  with  C++  is  to  provide  con¬ 
currency  in  the  form  of  libraries.  We 
have  the  Task  Library  that  provides  a 
much  lower-level  system  that  allows 
you  to  write  multi-threaded  programs. 
I've  used  it  for  simulations  where  I 
needed  a  couple  of  thousand  processes 
or  tasks  and  I  want  them  to  run  with 
fairly  minimal  overhead.  It  has  been 
used  for  robotics  and  such.  I  much 
prefer  the  library  route  over  the  route 
of  adding  syntax  to  the  language.  I 
think  it  serves  more  people  better. 

DDJ:  Let’s  discuss  the  future  of  C++ 
and  what  programmers  can  expect  in 
the  next  decade.  The  immediate  fu¬ 
ture  of  C++  is,  of  course,  2.0,  which 
adds  multiple  inheritance  to  the  lan¬ 
guage.  Can  you  summarize  the  other 
features  added  by  version  2.0? 
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BS:  It’s  a  reworking  of  the  language, 
polishing  off  the  little  rough  corners, 
the  unnecessary  restrictions,  and  the 
problem  areas  we  found.  Even  multi¬ 
ple  inheritance  can  be  seen  as  remov¬ 
ing  a  little  odd  restriction,  which  was 
that  you  couldn’t  have  more  than  one 
base  class.  We  can  argue  how  major 
an  extension  it  is.  Some  people  think 
it’s  major.  I  think  it’s  sort  of  medium. 
It  allows  you  to  do  things  that  you 
could  do  with  C++  but  noticeably 
cleaner  and  easier.  I  don’t  think  it  al¬ 
lows  you  to  do  anything  radically  new, 
and  most  of  the  other  features  I’ve 
added  to  2.0  are  of  that  ilk.  It’s  meant 
to  stabilize  the  language,  it’s  meant  to 
increase  the  quality  of  the  implemen¬ 
tations,  and  it’s  meant  to  remove  un¬ 
necessary  restrictions  without  destroy¬ 
ing  run-time  or  space  efficiencies. 

So,  in  version  2.0  you  have  the  multi¬ 
ple  inheritance,  you  have  a  more  sensi¬ 
tive  and  better  overloading  resolution 
mechanism,  you  have  type-safe  link¬ 
age  to  make  sure  you  can  link  larger 
programs  together  more  effectively,  and 
you  have  abstract  classes.  The  list  is 
fairly  long  but  not  radical.  We  have  a 
lot  of  users,  and  we  have  to  make  sure 
there  is  a  certain  stability  in  the  growth. 

DDJ:  Are  you  planning  specific  fea¬ 
tures  for  C++  beyond  2.0? 

BS:  We’ve  been  talking  about  excep¬ 
tion  handling  and  parameterized  types 
for  a  long  time.  It’s  universally  agreed 
that  we  need  them.  We  have  a  reason¬ 
ably  good  design  for  parameterized 
types  that  I  presented  at  the  last  USENEX 
C++  conference,  and  that  needs  to  be 
refined  a  little  bit.  Exception  handling 
is  one  stage  behind  that,  but  we  need 
it  badly.  When  you  go  to  C++,  you  get 
more  ambitious.  You  want  to  have  larger 
libraries,  you  want  to  use  more  of  other 
people’s  code,  and  so  you  need  more 
support.  That’s  what  we’re  trying  to 
provide  as  quickly  as  we  can  without 
just  throwing  in  everything  at  random. 
The  language  has  to  be  kept  coherent. 

DDJ:  The  Integrated  Development  En¬ 
vironment  with  its  integrated  editor, 
compiler,  and  debugger  has  become 
the  chosen  software  development  suite 
in  small  systems.  Turbo  C,  QuickC, 
Turbo  Pascal,  etc.,  are  examples.  Stand¬ 
alone  symbolic  debuggers  that  deal  spe¬ 
cifically  with  objects  like  C++  classes 
are  beginning  to  appear  as  well.  Are 
such  environments  appropriate  for  C++, 
and  do  you  know  of  any  current  devel¬ 
opments? 

BS:  Oh  yes.  They’ll  come.  Some  peo¬ 
ple  will  use  them,  and  I  believe  you  can 


buy  one  from  ParcPlace  now.  I’ll  as¬ 
sume  that  since  Microsoft  is  working 
on  C++,  they’ll  be  working  on  a  suit¬ 
able  environment.  Borland  is  playing 
the  same  game  they’ll  be  doing  it,  too. 
I  know  of  several  other  people  who  are 
thinking  along  those  lines. 

The  thing  that  one  has  to  seek  is 
code  portability  across  the  different  plat¬ 
forms.  Certainly  you  can  provide  better 
tools  for  a  specific  platform,  a  better 
compiler,  better  compile  times,  a  bet¬ 
ter  program  development  environment. 

The  examples  people 
have  seen  of  object- 
oriented  languages 
have,  by  and  large, 
been  fairly  slow 


Unless,  however,  you  are  able  to  take 
your  programs  out  of  their  environ¬ 
ment  and  export  them  to  something 
else,  you  have  painted  yourself  into  a 
corner. 

DDJ:  To  date  there  is  no  standard  for 
C++.  Hewlett-Packard  formally  requested 
the  ANSI  X3J11  committee  to  undertake 
that  standardization  as  a  compatible 
superset  of  ANSI  C,  but  the  committee 
was  ambivalent  about  it,  failing  to  vote 
to  begin  the  task.  One  reason  for  the 
request  was  to  avoid  the  time-consum¬ 
ing  overhead  of  setting  up  a  new  com¬ 
mittee.  Opponents  to  the  idea  pointed 
out  that  you  are  still  in  the  process  of  the 
C++  definition  and,  as  such,  are  not 
ready  for  standardization.  Do  you  see 
the  committee’s  action  as  an  impedi¬ 
ment  to  the  acceptance  of  C++?  Is  C++ 
ready  for  standardization? 

BS:  Life  isn’t  easy.  Clearly  we  would 
like  a  fully  standardized  language,  and 
equally  clearly  we  don’t  know  how  to 
do  that.  There  are  still  some  features  that 
we  need  to  design.  There  were  discus¬ 
sions  that  included  me,  other  people  at 
AT&T,  and  people  from  Hewlett-Packard 
and  Microsoft.  Where  do  we  go  from 
here,  we  asked?  How  can  we  get  the 
most  stable  environment  the  fastest  with¬ 
out  freezing  the  language  at  a  level  where 
everybody  has  to  extend  it  themselves? 
If  we  standardized  C++  simply  as  it  was, 
everybody  would  build  their  own  excep¬ 
tion  handling  and  parameterized  types. 

I  don’t  think  that  the  ANSI  C  commit¬ 
tee  would  be  at  all  a  suitable  forum  for 


standardizing  C++.  First  of  all,  they  are 
not  C++  users.  They  may  be  C  experts, 
but  they  are  not  C++  experts.  We  might 
as  well  say  that  since  the  Pascal  com¬ 
mittee  did  a  good  job  on  Pascal,  let 
them  do  C++.  We  need  a  new  commit¬ 
tee  composed  of  people  with  C++  ex¬ 
perience.  We  clearly  need  a  standard 
as  soon  as  possible,  but  we  simply 
have  to  figure  out  what  “as  soon  as 
possible”  means. 

We  need  a  C++  that’s  as  compatible 
with  ANSI  C  as  possible,  but  it  can’t  be 
one  hundred  percent  compatible  with¬ 
out  destroying  every  C++  program  ever 
written.  When  ANSI  turned  down  the 
proposal,  Hewlett-Packard  went  to 
SPARC,  the  policy  committee  for  ANSI, 
with  a  new  request  to  start  a  new  ANSI 
C++  committee  with  the  charter  for  stan¬ 
dardizing  C++,  a  committee  composed 
of  people  who  know  the  problems  of 
exception  handling  and  parameterized 
types,  and  who  know  that  one  hun¬ 
dred  percent  compatibility  with  ANSI 
C  is  not  desirable  —  as  close  as  possi¬ 
ble  but  no  closer.  That  was  accepted 
by  SPARC,  and  they  have  sent  a  recom¬ 
mendation  to  X3  to  start  an  ANSI  C++ 
committee.  Presumably  the  first  meet¬ 
ing  of  that  will  be  next  spring. 

DDJ:  'As  close  as  possible  to  C  but  no 
closer. "  That  was  the  title  of  a  paper  by 
you  and  Andrew  Koenig  wherein  you 
identified  the  differences  between  ANSI 
C  and  C++.  The  tone  of  the  paper  was 
that  those  differences  are  proper  and 
necessary  given  the  different  purposes 
of  the  two  languages.  The  paper  also 
stresses  the  inconsequential  nature  of 
most  of  the  differences.  Do  you  see  those 
differences  as  proof  that  C  and  C++ 
can  not  be  combined?  Should  they  be 
combined? 

BS:  I  don’t  think  the  two  languages 
should  be  reconciled  further  than  they 
are.  The  differences  are  quite  manage¬ 
able  by  conditional  expressions.  If  you 
are  writing  C++,  you  use  the  new  key¬ 
words  and  it  isn’t  ANSI.  If  you  are  writ¬ 
ing  ANSI  C  you  could  have  an  option 
in  your  compiler  that  suppresses  the 
C++  subset,  and  it  will  not  affect  the 
way  you  write  code.  It’s  much  more 
an  issue  for  language  lawyers  than  it  is 
for  programmers.  The  whole  thing  can 
be  exhaustively  discussed  on  two  pages 
and  the  differences  can  be  listed  in 
about  ten  lines. 

DDJ:  Will  you  rewrite  your  book,  the 
C++  Programming  Language,  to  reflect 
the  new  features  of  version  2.0? 

BS:  I  will  as  soon  as  I  get  time.  But  it’s 
more  important  to  get  the  language 
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stabilized,  and  so  I’m  working  on  a 
new  language  definition,  a  new  man¬ 
ual.  I  am  working  on  a  book,  as  well, 
with  Margaret  Ellis  that  explains  what 
C++  is,  not,  as  the  first  book  does,  how 
you  go  about  using  it.  The  book  states 
what  the  language  is,  what  the  im¬ 
plementation  techniques  are  that  make 
sensible  implementations  of  certain 
parts,  and  why  certain  decisions  were 
made. 

This  is  a  “what”  book,  not  a  “how¬ 
to”  book.  In  theory,  it’s  a  book  for 
experts.  If  you  have  a  question  about 
what  the  language  is,  the  answer  should 
be  there.  Lots  of  people  prefer  to  learn 
languages  from  such  explanations.  You 
never  know  who  would  want  some¬ 
thing  like  that.  I  learned  ALGOL  60  out 
of  the  ALGOL  60  Revised  Report.  I’m 
not  the  only  one  who  is  sort  of  semi- 
masochistic  in  the  way  I  read  things. 

DDJ:  When  will  this  new  book  be  avail¬ 
able? 

BS:  It’s  supposed  to  happen  in  De¬ 
cember  or  January.  The  question  is 
whether  I  can  make  it.  The  manual 
work  itself  is  taking  longer  than  it 
should.  It’s  about  twice  the  size  of  the 
original  manual,  not  because  version 
2.0  is  twice  the  language  as  version 
1.0,  but  because  I  need  to  go  into  much 
greater  depth. 

If  you  can  assume  your  reader’s  cul¬ 
ture,  you  can  take  shortcuts  in  expla¬ 
nations,  and  there  are  certain  words 
that  you  can  forget  to  define  without 
getting  into  trouble.  C++,  however,  is 
breaking  out  of  the  C  ghetto.  People 
who  were  brought  up  with  Pascal  and 
wouldn’t  touch  C  with  a  barge  pole  are 
getting  on  board  with  C++.  They  come 
in  and  they  try  to  read  some  of  the 
standard  C++  literature.  When  you  get 
their  comments,  you  learn  what  as¬ 
sumptions  you  made  without  explain¬ 
ing  them.  Such  things  must  not  be  done 
in  the  manuals  we  are  working  on.  It’s 
getting  harder  to  write  a  manual  be¬ 
cause  the  audience  is  becoming  more 
diverse. 

DDJ:  One  of  the  problems  we’ve  ob¬ 
served  when function-oriented  program¬ 
mers  attempt  the  transition  to  object- 
oriented  systems  is  that  there  doesn 't 
seem  to  be  anv  way  to  describe  the  new 
paradigm  to  them  in  a  way  that  they 
can  learn  it  without  actually  using  it. 

BS:  We’ll  eventually  do  better.  The  first 
books  on  C++  just  said  what  the  lan¬ 
guage  was,  put  a  thin  veneer  on  top  of 
it,  or  described  it  primarily  as  a  better 
C.  Lipmann’s  book  and  Dewhurst  and 
Stark’s  book  go  beyond  that  and  dem¬ 


onstrate  how  things  are  done.  We  have 
a  major  education  problem  on  our 
hands.  I’ve  been  saying  that  for  years. 
You  can  write  Fortran  in  any  language, 
and  if  you  only  use  C++  as  a  better  C, 
you’ll  see  improvements  in  your  pro¬ 
grams  and  productivity,  but  you  won’t 
get  anywhere  near  what  you  can  do 
or  what  we  have  seen  demonstrated 
with  greater  degrees  of  data  abstrac¬ 
tion  and  object-oriented  programming. 

Some  people  have  the 
idea  that  object-oriented 
really  means  graphics 
because  there  is  such  a 
nice  fit 


DDJ:  The  function-oriented  program¬ 
mer  does  not  understand  intuitively 
what  the  advantage  of  that  is. 

BS:  It’s  hard  to  explain  how  to  bicycle. 
I  can  talk  myself  hoarse  and  still  you 
go  up  to  a  bicycle,  and  you  fall  off  the 
first  time.  A  certain  amount  of  practice 
must  be  done.  Programming  is  an  art 
like  riding  a  bicycle.  It’s  learned  by 
doing  it.  But  you  can  certainly  help  the 
process.  You  don’t  just  say  to  some¬ 
body,  “Here’s  a  bicycle.  Ride.”  Simi¬ 
larly  we  need  better  education  on  how 
to  use  a  language  like  C++  for  object- 
oriented  programming.  You  can  write 
better  articles,  use  videotapes,  put  train¬ 
ing  wheels  on  the  new  programming 
environments,  help  programmers  get 
started.  It  can  be  managed.  It  will  be 
managed.  The  gains  in  doing  so  have 
been  demonstrated  often  enough. 

DDJ:  Programmers  have  been  told  that 
they  must  unlearn  what  they  have 
learned  in  order  to  use  object-oriented 
programming,  and  they  reject  that. 

BS:  That’s  not  what  I  am  telling  them. 
C++  is  a  better  C,  and  it  supports  data 
abstraction,  and  it  supports  object-ori¬ 
ented  programming,  and,  yes,  you  can 
forget  all  you  have  learned  and  jump 
into  the  deep  end.  But  lots  of  people 
do  it  differently.  They  start  out  using  it 
like  a  better  C,  they  experiment  on  the 
side  with  the  techniques  they  don’t  quite 
understand.  Follow  the  literature  so  that 
you  know  the  syntax,  the  basic  seman¬ 
tics,  and  your  tools  before  you  take 


that  big  leap.  Then  try  to  focus  on 
classes  for  a  new  project. 

One  of  the  advantages  of  C++  is  that 
you  can  take  some  of  the  preliminary 
steps  without  a  paradigm  shift  from 
function  to  object-oriented  program¬ 
ming.  You  can  learn  the  tools,  the  lan¬ 
guage,  the  basics,  how  to  use  debug¬ 
gers,  whatever  it  takes.  And  then  one 
day  when  you  find  the  right  project, 
you  can  try  the  next  step.  We’ve  seen 
that  done  quite  a  few  times. 

There  are  people  who  enthusiasti¬ 
cally  read  all  the  literature,  go  to  C++ 
conferences,  and  then  go  straight  in, 
design  huge  class  hierarchies,  and  pro¬ 
gram  them.  I’m  always  amazed  when 
it  works,  but  it  does  quite  often.  There 
are  people  who  can  write  perfectly  stan¬ 
dard  designed  C  programs,  go  away 
and  wait  two  months  and  come  back 
and  write  their  first  program  in  C++, 
truly  object-oriented  with  tens  of  thou¬ 
sands  of  lines,  and,  lo  and  behold,  it 
works.  By  all  laws,  it  oughtn’t.  But  it’s 
happened. 

Of  course,  I’m  sure  there  are  also 
people  out  there  who  have  gotten  burnt 
trying  to  do  that. 

DDJ:  Would  you  offer  your  comments 
about  the future  of  programming.  What 
kinds  of  things  do  we  need  to  under¬ 
stand  in  order  to  deal  with  software 
development  in  the  near  future. 

BS:  I  think  we’ll  see  much  more  em¬ 
phasis  on  the  design  of  classes  and  the 
formal  interfaces  between  parts,  and 
an  increase  in  the  reuse  of  existing 
programs  and  libraries  of  classes.  We 
will  need  tools  that  help  us  do  this  and 
draw  structure  or  draw  inference  on 
what  the  structure  is.  Things  like  per¬ 
formance  analysis  and  coverage  test¬ 
ing  will  all  be  available.  It’s  worth  re¬ 
membering  that  it’s  not  a  solitary  ac¬ 
tivity  —  not  just  one  guy  sitting  there 
with  one  machine;  many  of  the  key 
activities  are  social. 

We’ll  also  need  to  develop  ways  of 
talking  about  programs  that  are  ahead 
of  what  we  are  doing  today.  It’s  no 
good  if  we  can  compose  programs  and 
components  out  of  classes  if  we  can’t 
talk  about  that  activity  in  a  sensible 
way.  We  don’t  have  the  vocabulary.  It 
would  be  nice  if  we  knew  what  object- 
oriented  design  was.  By  and  large,  we 
don’t  know  it  yet.  But  that  will  emerge 
in  five  years  and  will  be  virtually  ac¬ 
cepted  almost  universally  after  that. 

DDJ 
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C++  String  Classes 

An  exercise  in  class  design 


Scott  Robert  Ladd 


Object-oriented  programming 
is  the  art  of  breaking  down 
a  program  into  its  fundamen¬ 
tal  data  types  and  their  asso¬ 
ciated  operations.  A  class  de¬ 
fines  a  specific  data  type  and  encapsu¬ 
lates  both  the  data  definition  and  the 
operations  for  objects  of  that  type.  The 
fundamental  problem  facing  the  begin¬ 
ning  C++  programmer  is  learning  how 
to  create  classes.  Almost  a  language 
unto  itself,  class  definition  in  C++  re¬ 
quires  an  understanding  of  the  fundamen¬ 
tal  philosophies  behind  object-oriented 
programming.  Once  you’ve  grasped  the 
process  of  class  definition,  you  are  well 
on  the  road  to  becoming  an  object- 
oriented  programmer. 

Object-oriented  programming  is  not 
a  task  to  be  undertaken  lightly;  it  re¬ 
quires  forethought  and  planning.  There¬ 
fore,  the  first  action  to  be  undertaken 
when  designing  a  class  is  to  determine 
exactly  what  its  purpose  is  and  how  it 


Scott  is  a  computer  programming  ad¬ 
dict  with  15  years  of  experience  in  a 
wide  variety  of  languages.  You  can 
contact  him  via  MCI  Mail  (369-4376), 
or  at  705  W.  Virginia,  Gunnison  CO 
81230.  Scott  also  maintains  a  BBS  sjs- 
tem  dedicated  to  computer  program¬ 
ming  and  scientific  subjects ;  its  phone 
number  is  303-641-5125  (300/1200/ 
2400  bps,  8  bits,  no  parity,  1  stop  bit). 
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will  be  used.  In  these  days  of  extensive 
programming  environments  and  high- 
pressure  schedules,  it  might  seem  un¬ 
realistic  to  expect  programmers  to  spend 
time  designing  their  programs  before 
writing  them.  In  the  case  of  developing 
classes,  however,  planning  is  of  the 
utmost  importance.  The  programmer 
must  have  a  clear  idea  of  the  goal  of  a 
class  before  writing  the  first  line  of  code. 

A  class  in  C++  is  a  definition  of  a 
new  data  type.  For  all  intents  and  pur¬ 
poses,  this  new  data  type  is  an  analog 
to  those  which  C++  predefines.  Similar 
to  the  int,  float,  and  char  types,  the 
types  defined  by  classes  have  their  own 
built-in  rules,  operations,  and  attrib¬ 
utes.  This  is  known  as  “encapsulation," 
where  form  and  function  are  linked. 
Encapsulation  defines  and  controls  ex¬ 
actly  what  a  type  can  and  cannot  do. 

Furthermore,  a  class  also  offers  the 
capability  to  do  “data  abstraction.”  When 
we  use  a  predefined  type,  such  as  a 
float ,  we  are  not  concerned  with  ex¬ 
actly  how  floating-point  numbers  are 
stored  and  manipulated.  The  actual  im¬ 
plementation  of  the  float  type  will  vary 
from  architecture  to  architecture.  If  we 
had  to  rewrite  our  floating-point  code 
every  time  we  ported  it  between  com¬ 
puters,  there  would  be  very  little  porting 
of  code  going  on.  Instead,  floating¬ 
point  values  are  abstracted.  We  know 
that  we  can  do  assignments  and  mathe¬ 
matical  operations  on  them,  and  we 
write  our  programs  using  the  high- 
level  definition  of  these  activities.  We 
don’t  need  to  understand  the  complexi¬ 
ties  of  binary  multiplication  to  multiply 
floats-,  we  assume  the  compiler  under¬ 
stands  this  already,  and  will  do  it  for 
us  automatically.  Classes  give  us  the 
capability  to  “hide"  the  actual  implemen¬ 
tation  of  our  own  data  types  so  that  the 
users  of  those  classes  can  make  as¬ 
sumptions  about  how  they  work.  Data 
abstraction  frees  the  programmer  from 
becoming  involved  in  the  details. 

A  String  Class 

The  first  project  many  budding  C++ 
programmers  undertake  is  the  devel¬ 
opment  of  a  character  string  class.  One 
of  C’s  primary  faults  is  that  it  lacks  the 
sophisticated  string  handling  available 
in  languages  such  as  Pascal  and  Basic. 
Strings  are  quite  useful:  Nearly  every 
program  manipulates  text  data  of  one 
type  or  another.  A  string  class  was  one 
of  my  first  projects,  and  during  the  two 
years  of  its  existence  the  class  has  un¬ 
dergone  substantial  changes.  As  my 
understanding  of  C++  has  grown,  so 
has  my  ability  to  build  a  better  class.  I 
am  quite  happy  with  the  current  incar¬ 
nation,  which  works  well  in  applica¬ 
tions  ranging  from  data  bases  to  text 


editors.  The  entire  class  is  shown  in 
Listings  One,  string. hpp,  (page  68)  and 
Two,  string.cpp  (page  68).  Listing  Three, 
strtst.cpp,  (page  69)  shows  a  program 
to  exercise  the  String  class. 

My  goal  was  to  create  a  dynamically 
allocated  string  class  that  would  pro¬ 
vide  all  the  functionality  of  standard, 
NULL-terminated  C  character  arrays 
(which  I  call  “C-strings”).  However,  I 
wanted  to  avoid  the  pitfalls  of  C-strings; 
for  example,  errors  often  occur  when 

Class  definition  in  C++ 
requires  an 
understanding  of  the 
fundamental 
philosophies  behind 
object-oriented 
programming 


working  with  C-strings  because  they 
fail  to  do  any  sort  of  range  or  validity 
checking.  In  addition,  the  start  library 
functions  defined  in  string. h  are  miss¬ 
ing  important  features.  In  order  for 
strings  to  be  useful  in  a  wide  variety  of 
applications,  they  needed  manipula¬ 
tion  routines  not  normally  found  in  C 
function  libraries,  such  as  those  for  in¬ 
serting  and  deleting  data. 

The  private  Section 

Listing  One  shows  the  file  string. hpp, 
which  contains  the  definition  of  the 
String  class.  A  String  is  defined  as  hav¬ 
ing  three  private  instance  variables:  Siz, 
Len,  and  Txt.  Siz  contains  the  currently 
allocated  length  of  the  Txt  pointer;  Len 
holds  the  actual  number  of  characters 
stored  in  String.  The  char  pointer  Txt 
points  to  the  location  on  the  heap  of 
the  buffer  containing  the  Strings  text 
data.  Every  instance  of  String  will  have 
its  own,  unique  variables  with  these 
names. 

Alloclncr  is  not  an  instance  variable; 
rather,  it  is  a  private  “static  class  mem¬ 
ber."  Any  class  data  item  defined  as 
static  has  only  one  occurrence,  shared 
by  the  entire  class.  In  this  case,  there 
is  only  one  copy  of  Alloclncr,  which  is 
common  to  all  String  objects.  The  pur¬ 
pose  of  private  static  class  members  is 
to  eliminate  global  variables;  they  should 
be  used  whenever  there  is  a  data  item 
that  is  accessed  only  from  within  a 


class  scope.  There’s  no  need  for  any¬ 
thing  external  to  the  String  class  to 
“see”  Alloclncr,  so  it  is  safely  locked 
away  from  outside  manipulation. 

The  public  Section 

In  general,  class  methods  are  made 
public  to  facilitate  their  use  by  user- 
defined  objects.  In  the  case  the  String 
class,  however,  the  method  Shrink  is 
used  only  internally  by  the  class.  Shrink 
adjusts  the  buffer  space  allocation  for 
a  string  in  order  to  eliminate  wasted 
space.  It  is  not  meant  to  be  called  from 
outside  the  class  scope,  and  thus  it  is 
declared  in  the  private  section  of  the 
String  class  definition. 

The  public  section  of  the  String  class 
begins  by  defining  two  enumerated 
types:  StrCompVal  and  StrCompMode. 
StrCompVal  is  the  return  value  of  the 
Compare  method;  StrCompMode  is  used 
to  indicate  whether  or  not  String  com¬ 
parisons  are  case-sensitive.  I  use  enu¬ 
merations  for  these  types  so  that  I  can 
control  the  validity  of  values  being 
passed  to  and  returned  from  methods. 
The  types  must  be  public  so  that  the 
enumeration  constants  are  available  to 
the  user  of  the  class. 

The  remainder  of  the  public  section 
defines  all  of  the  other  methods  associ¬ 
ated  with  the  String  class.  The  first  four 
of  these  are  constructors,  which  are 
specialized  methods  used  to  initialize 
(that  is,  construct)  new  String  objects. 
Objects  tend  to  be  complex,  and  con¬ 
structors  allow  the  programmer  com¬ 
plete  control  over  how  the  instance 
variables  of  an  object  are  loaded  with 
values  when  an  object  is  instantiated 
(comes  into  scope). 

The  constructor  String/ )  is  used  to 
create  an  empty,  uninitialized  string. 
String/String  &  Str)  is  known  as  the 
“copy  constructor;”  it  copies  one  String 
object  into  another.  String(char  *  Cstr) 
allows  a  newly  created  String  to  be  in¬ 
itialized  with  the  value  of  a  C-string.  The 
last  constructor,  String(char FillCh,  un¬ 
signed  int  Couni),  creates  a  new  string, 
which  contains  Count  FillCh  characters. 

Copy  constructors  require  a  bit  of 
explanation.  The  C++  compiler  will  gen¬ 
erate  a  copy  constructor  for  you  if  you 
don’t  design  one  yourself.  The  gener¬ 
ated  copy  constructor  simply  assigns 
the  instance  variables  of  one  object  to 
another.  This  default  copy  constructor 
won’t  work  for  most  classes,  including 
String.  Each  String  contains  a  pointer 
to  a  buffer.  When  we  create  a  copy  of 
a  String,  we  want  it  to  have  its  own, 
unique  buffer.  The  default  copy  con¬ 
structor  will  merely  assign  the  address 
of  the  existing  buffer  to  the  new  Strings 
Txt  instance  variable,  giving  us  two 
objects  that  are  using  the  same  mem- 
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ory  space.  Therefore,  we  need  to  de¬ 
fine  a  copy  constructor  that  duplicates 
the  buffer  from  the  original  String  for 
the  new  String. 

The  next  method,  ~String( ),  is  a  des¬ 
tructor.  Destructors  are  called  when¬ 
ever  an  object  is  deleted  or  goes  out 
of  scope.  As  with  constructors,  most 
complex  classes  will  require  an  explic¬ 
itly  defined  destructor.  A  default  con¬ 
structor  is  created,  but  it  merely  frees 
the  space  being  used  by  the  instance 
variables  of  an  object.  This  will  not 
work  for  Strings ;  the  Txt  pointer  lo¬ 
cates  spaces  allocated  on  the  stack, 
and  this  space  must  be  deallocated  to 
avoid  wasting  memory.  The  ~String(  ) 
destructor  handles  this  for  us. 

Remember  that  constructors  and  des¬ 
tructors  are  called  automatically  by  the 
compiler.  Every  time  an  object  is  cre¬ 
ated,  a  constructor  is  called  for  it;  every 
time  an  object  is  destroyed,  a  destruc¬ 
tor  is  called.  As  we  shall  see  shortly, 
constructors  tend  to  get  called  far  more 
often  than  is  immediately  apparent,  and 
the  programmer  must  be  aware  of  these 
hidden  method  function  calls. 

The  Length/ )  and  SizeC )  methods 
simply  return  the  current  length  and 
allocation  size,  respectively,  of  a  string. 
Length  corresponds  to  the  string. h  func¬ 
tion  strlen( ).  Size  was  originally  cre¬ 
ated  to  help  in  testing  the  class;  be¬ 
cause  it  is  so  simple,  1  just  left  it  in  for 
future  use.  Another  simple  method  is 
Empty( ),  which  clears  a  string  to  the 
blank  —  or  empty  —  value,  with  a 
length  of  0  and  an  allocation  of  8  bytes. 

The  remaining  methods  manipulate 
the  value  of  String.  Copy(  )and  Dupe(  ) 
provide  similar  functions;  Copy(  )  cop¬ 
ies  the  contents  of  String  into  a  pre¬ 
defined  C-string,  and  Dupe( )  returns 
a  pointer  to  a  C-string  (filled  with  the 
value  of  its  Txt  buffer)  it  created  on  the 
heap.  Copy( )  is  useful  when  an  exist¬ 
ing  C-string  needs  to  be  filled  with  the 
value  of  String.  Dupe( )  can  be  used 
as  the  equivalent  of  the  standard  func¬ 
tion  strdupC  ). 

Next  we  come  to  a  series  of  operator 
definitions.  The  first  is  the  operator  = 
method,  which  handles  assignments  be¬ 
tween  Strings.  Note  that  this  is  not  du¬ 
plicating  the  function  of  the  copy  con¬ 
structor  discussed  earlier.  The  copy  con¬ 
structor  is  used  when  a  new  String  is 
created;  the  assignment  operator  is  used 
when  the  value  of  an  existing  String  is 
assigned  to  another  extant  String. 

You  may  wonder  why  I  didn’t  create 
an  assignment  operator  to  copy  a  C- 
string  to  an  existing  String.  The  truth 
is  that  there  is  no  need  for  such  a 
method.  Earlier,  we  defined  a  construc¬ 
tor  ( StringCchar  *  CstrJ)  that  created  a 
String  from  a  C-string.  Whenever  a  C- 


string  is  used  in  a  method  invocation 
that  expects  a  String  as  a  parameter, 
the  C-string  is  automatically  converted 
via  the  constructor  to  a  temporary  String. 
Once  the  temporary  String  has  been 
used,  it  is  destructed. 

This  principle  carries  over  to  the  meth¬ 
ods  for  the  two  additive  operators,  + 
and  +  =.  Rather  than  define  methods 
for  every  possible  combination  of  add¬ 
ing  String  and  a  C-string,  these  meth¬ 
ods  operated  entirely  on  Stringy.  If  a 
C-string  is  passed  as  one  of  the  argu¬ 
ments  to  these  methods,  it  is  automati¬ 
cally  converted  to  String  by  the 
StringCchar  *  Cstr)  constructor. 

The  fundamental 
problem  facing  the 
beginning  C++ 
programmer  is  learning 
how  to  create  classes 


The  advantage  of  using  conversion 
constructors  such  as  StringCchar  *  Cstr) 
is  simplicity.  Only  one  method  needs 
to  be  defined  for  each  operation,  and 
the  constructor  can  take  care  of  the 
rest.  To  add  compatibility  with  another 
data  type  (say,  an  alternative  string 
class),  you  merely  need  to  create  a 
single  conversion  constructor.  The  draw¬ 
back  is  overhead:  custom-written  meth¬ 
ods  for  each  combination  of  values 
will  not  incur  the  overhead  of  hidden 
constructor  and  destructor  calls. 

The  next  method  declared  is  Com- 
pareC ).  It  compares  two  strings  and 
returns  an  enumeration  of  type  Str- 
CompVal ,  which  indicates  the  relation¬ 
ship  between  the  two  values.  This  works 
much  like  the  standard  function  strcmp , 
with  the  exception  that  the  Case  pa¬ 
rameter  determines  whether  the  com¬ 
parison  is  case-sensitive.  It’s  possible 
to  define  a  series  of  operator  methods 
for  the  <,  >,  and  =  =  operations  as  well; 
I’ve  found  that  CompareC  )  works  well 
enough  for  my  purposes. 

The  method  FindC )  duplicates  the 
purpose  of  the  standard  function  strstrC  ), 
by  locating  a  given  String  within  an¬ 
other  String.  It  returns  an  index  indi¬ 
cating  where  the  substring  begins.  Simi¬ 
lar  to  Compare ,  the  Case  parameter  de¬ 
faults  to  SF_IGNORE  to  indicate  a  case- 
insensitive  comparison.  The  search  can 
be  made  case  sensitive  by  specifying 


the  Case  parameter  as  SF_SENSITIVE. 

The  DeleteC ^method  removes  a  speci¬ 
fied  number  of  characters  from  a  string. 
The  parameter  Pos  provides  the  index 
of  the  first  character  to  be  deleted,  and 
the  Count  parameter  indicates  how 
many  characters  should  be  deleted. 

Characters  and  strings  can  be  inserted 
into  String  at  any  position  with  the 
Insert/) methods.  The  first  method  listed 
inserts  a  single  character,  and  the  sec¬ 
ond  inserts  an  entire  String.  Once  again, 
the  conversion  constructor  allows  us 
to  use  a  C-string  in  place  of  the  String 
parameter. 

Occasionally,  it  is  necessary  to  ex¬ 
tract  a  section  of  a  string.  The  SubStr 
method  accomplishes  this  by  copying 
Count  characters  beginning  at  Pos  into 
another  String. 

Last  but  not  least,  the  indexing  op¬ 
erator  is  defined.  This  allows  us  to  ex¬ 
tract  single  characters  at  specific  posi¬ 
tions  within  String  in  the  same  fashion 
as  we  would  if  working  with  a  C-string. 
If  the  position  given  is  beyond  the  last 
character  of  String ,  a  NULL  character 
is  returned. 

The  Implementation 

With  the  just  mentioned  definition  and 
a  copy  of  Listing  One  (string,  hpp),  a 
programmer  should  be  able  to  use  and 
expand  upon  String  objects  without 
ever  seeing  the  implementation  of  the 
String  class.  There  are,  however,  some 
interesting  facets  of  method  implemen¬ 
tation  that  can  be  seen  by  studying 
Listing  Two  (string. cpp).  It  is  particu¬ 
larly  important  to  see  the  way  in  which 
objects  are  returned  from  functions. 

If  you  examine  the  methods  that  re¬ 
turn  String,  you  will  see  what  looks 
like  a  violation  of  proper  programming 
practice.  For  example,  SubStrC ,)  copies 
the  substring  into  a  local  String  object  — 
TempStr.  Then,  it  returns  TempStr,  a 
seemingly  dangerous  act.  After  all,  isn’t 
the  destructor  for  TempStr  called  when 
the  method  is  exited,  meaning  that  the 
recipient  of  the  method’s  return  value 
will  get  garbage? 

Again,  C++  is  trickier  than  it  looks. 
When  an  object  is  returned  from  a  func¬ 
tion,  the  copy  constructor  is  called  first 
to  copy  the  return  value  into  its  desti¬ 
nation,  and  then  the  destructor  is  called. 
This  makes  it  much  easier  to  write  meth¬ 
ods  that  return  objects. 

Summing  Up 

As  I  mentioned  earlier,  it  is  possible  to 
improve  this  class.  The  most  obvious 
improvement  is  to  add  methods  for  the 
comparison  operators  (<,  >,  and  =  =). 

I  haven’t  needed  them,  but  perhaps 
your  application  will. 

The  String  class  does  not  contain 
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any  inline  methods.  I  tend  to  be  cau¬ 
tious  about  making  methods  inline.  Re¬ 
member  that  under  the  C++  definition, 
inline  methods  can  be  treated  as  regu¬ 
lar  method  functions  by  the  compiler. 
Such  as  the  register  keyword,  inline 
methods  can  be  ignored  by  the  com¬ 
piler.  No  C++  compiler  I  know  of  will 
actually  inline  a  method  that  contains 
complex  control  statements  like  loops 
and  switches;  these  methods  are  made 
into  function  methods,  regardless  of 
their  declaration  as  inline.  Not  all  C++ 
translators  can  inline  methods  contain¬ 
ing  t/statements,  either, 

Inline  functions  also  tend  to  be 
abused  by  programmers  who  are  learn- 

Again, 

C++  is  trickier 
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ing  C++.  While  an  inline  method  is 
certainly  faster  than  a  function  method, 
it  can  cause  severe  code-size  increases. 
You  need  to  analyze  which  methods 
are  being  used  the  most,  and  deter¬ 
mine  what  the  speed  versus  size  trade¬ 
offs  are.  In  the  String  class,  the  most 
obvious  candidates  for  inlining  are  the 
simple  methods  like  Length( ). 

This  class  has  served  me  well  in  a 
number  of  complex  applications.  Work 
with  and  modify  it;  if  you  come  up  with 
interesting  alternatives  and  changes,  I’d 
like  to  hear  about  your  experiences. 
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In  discrete  event  simulation,  events 
in  the  simulated  system  happen  at 
discrete  times,  and  these  are  the 
only  times  at  which  the  system 
changes  state.  For  example,  when 
simulating  a  queue  of  customers  wait¬ 
ing  for  service  at  a  bank,  the  events 
include  a  new  customer  arriving,  a  cus¬ 
tomer  reaching  the  head  of  the  line  and 
being  served  by  a  teller,  a  customer 
leaving,  and  so  on.  The  key  points  are 
the  times  at  which  these  events  happen; 
as  far  as  the  simulation  is  concerned, 
nothing  happens  between  the  events. 
Discrete  event  simulation  differs  from 
"continuous  time”  simulation,  which 
is  used  to  simulate  continuous  systems 
such  as  water  flowing  over  a  dam. 

Concurrent  programming  can  sim¬ 
plify  the  task  of  writing  a  discrete  event 
simulation  program;  the  resulting  pro¬ 
gram  is  easy  to  understand  and  modify. 
In  particular: 


El#  r  os 


Simulating  discrete  events  with  concurrent  processing 


N.H.  Gehani  and  W.D.  Roome 


•  The  simulation  program  is  easy  to 
write:  For  each  entity  type,  a  simple 
sequential  process  that  describes  the 


Narain  and  William  are  the  architects 
of  Concurrent  C  and  authors  of  The 
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steps  performed  by  the  entity  is  writ¬ 
ten.  These  processes  communicate 
when  the  entities  they  are  simulating 
need  to  communicate  or  synchronize. 
This  is  called  the  “process-interaction 
model”  of  simulation. 

•  It  is  easy  to  reuse  entity  processes 
from  previous  simulations  or  to  create 
a  library  of  processes  for  standard  enti¬ 
ties. 

•  Even  if  entity  processes  from  previ¬ 
ous  simulations  cannot  be  reused  as  is, 
they  can  be  used  as  templates  that  can 
be  customized  for  new  simulations. 

•  It  is  easy  to  capture  statistics  for  each 
entity;  Just  record  them  in  local  vari¬ 
ables  in  each  entity  process  (that  is,  a 
running  average).  If  there  are  several 
instances  of  the  same  entity,  each  pro¬ 
cess  automatically  gets  its  own  ver¬ 
sions  of  these  variables. 

•  The  processes  can  be  automatically 
distributed  over  the  processors  in  a 
multiprocessor  system.  This  can  speed 
up  a  computationally  intensive  simula¬ 
tion  program  (that  is,  one  in  which  the 
entity  processes  are  compute-bound  be¬ 
tween  process  interactions). 

We  will  illustrate  these  points  by  show¬ 
ing  how  to  write  a  Concurrent  C  pro¬ 
gram  that  models  a  multi-stage,  multi¬ 
server  queuing  network.  Each  queue 
and  each  server  is  modeled  by  a  Con¬ 
current  C  process.  This  is  a  natural  way 
to  simulate  a  queuing  network:  Each 
process  runs  independently,  as  do  the 
queue  and  servers  in  the  real  network, 
and  they  interact  when  necessary,  for 
example,  when  a  server  takes  a  job 
from  its  input  queue.  We’ll  present  sev¬ 
eral  general  processes  that  can  be  used 
in  other  simulation  programs;  these  in¬ 
clude  an  event  scheduler  process  and 
a  queue  manager  process. 

The  Process-Interaction  Model 

Consider  the  queuing  system  in  Figure 
1  where  the  simulation  uses  three  pro¬ 
cesses:  One  for  the  source,  one  for  the 
queue,  and  one  for  the  server.  The 
source  process  generates  items  (“jobs”). 
The  inter-arrival  time  —  the  time  be¬ 
tween  item  arrivals  —  is  a  random  vari¬ 
able.  The  body  of  the  source  process 
consists  of  a  simple  loop  that  calculates 
the  next  inter-arrival  time,  waits  for  that 
many  time  units,  generates  a  new  item, 
and  then  places  the  new  item  on  the 
queue  as  in  Example  1. 

Similarly,  the  server  process  repeat¬ 
edly  takes  the  next  item  from  the  queue, 
processes  it  for  the  appropriate  service 
time,  and  finally  discards  the  item.  The 
queue  accepts  items  from  the  source 
and  gives  them  to  the  server. 


General  Method 

The  first  step  in  the  process-interaction 
model  is  to  determine  the  sequential, 
independent  entities  in  the  system  be¬ 
ing  simulated.  The  entities  in  a  queu¬ 
ing  network  include  sources,  queues, 
and  servers.  Each  entity  performs  a  well- 
defined  series  of  operations.  Some  of 
these  operations  may  require  interac¬ 
tion  with  another  entity;  one  example 
is  a  server  taking  an  item  from  a  queue. 
Other  than  that,  each  entity  is  indepen¬ 
dent  of  the  other  entities. 

The  next  step  is  to  identify  the  types 
of  interactions  between  the  entities.  Each 
such  interaction  becomes  a  transaction 
call.  It  is  convenient  to  divide  entities 
into  two  categories:  Active  entities,  such 
as  servers,  and  passive  entities,  such 
as  queues.  In  general,  passive  entities 
wait  for  requests,  and  usually  represent 
“resources”  that  are  used  by  the  active 
entities.  The  process  that  implements 
a  passive  entity  has  one  transaction  for 
each  type  of  request.  For  example,  a 
queue  process  will  have  a  put  trans¬ 
action  to  put  an  item  into  the  queue, 
and  a  take  transaction  to  remove  the 
next  item  from  the  queue.  The  process 
for  an  active  entity,  such  as  the  server, 
is  not  called  by  the  other  processes, 
and  thus  does  not  have  transactions. 
This  is  not  an  absolute  rule.  For  exam¬ 
ple,  while  handling  a  request,  a  passive 
process  might  actively  request  service 
from  another  passive  process.  But  it  is 
often  a  useful  paradigm  for  structuring 
the  processes  in  a  simulation  program. 

For  each  distinct  type  of  entity,  we 
then  write  the  specification  and  body 
for  the  Concurrent  C  process  that  simu¬ 
lates  it.  If  the  simulation  needs  several 
entities  of  the  same  type,  we  can  create 
an  instance  of  the  corresponding  pro¬ 
cess  type  for  each  entity.  The  process 
for  simulating  an  active  entity  is  a  sim¬ 
ple  sequential  program  that  performs 


Figure  1:  A  queuing  system 


Example  1:  The  server  process 


the  entity’s  operations.  The  process  for 
simulating  a  passive  entity  consists  of 
a  loop  that  repeatedly  executes  a  select 
statement  with  alternatives  for  all  of  its 
transactions.  In  general,  each  process 
keeps  statistics,  such  as  the  mean  time 
in  system,  and  prints  them  out  at  the 
end  of  the  simulation. 

The  final  step  is  to  write  a  main 
process  that  creates  all  the  entity  pro¬ 
cesses  and  connects  these  processes 
appropriately. 

Scheduler  Process 

Delays  in  simulated  time  —  such  as  the 
service  time  delay  —  are  handled  by  a 
scheduler  process.  (Simulated  time  is 
different  from  actual  time,  so  we  can¬ 
not  use  the  Concurrent  C  delay  state¬ 
ment  to  simulate  service  or  arrival  de¬ 
lays.)  This  scheduler  process  maintains 
the  current  simulated  time  and  advances 
it  appropriately.  You  can  think  of  the 
scheduler  as  maintaining  a  clock  that 
gives  the  current  simulated  time.  For 
each  delay  request  from  a  process,  the 
scheduler  determines  the  simulated  time 
at  which  the  process  is  to  be  reacti¬ 
vated,  and  saves  this  request  in  an  acti¬ 
vation  request  list.  When  all  processes 
are  waiting  for  delays  to  expire,  the 
scheduler  searches  this  list  for  the  entry 
with  the  lowest  activation  time.  The 
scheduler  then  advances  the  simulated 
clock  to  this  time,  removes  this  entity 
from  the  list,  and  reactivates  the  se¬ 
lected  process.  If  several  processes  are 
waiting  to  be  reactivated  at  the  same 
simulated  time,  the  scheduler  awakens 
all  of  them  simultaneously.  Any  com¬ 
putation  done  by  a  process  takes  place 
in  zero  simulated  time. 

One  complication  is  that  a  process 
can  be  waiting  for  an  event  other  than 
an  explicit  delay  request.  For  example, 
suppose  that  a  server  process  tries  to 
take  an  item  from  an  empty  queue.  The 
server  process  waits  for  the  queue  pro¬ 
cess,  which  is  waiting  for  a  source  pro¬ 
cess  to  put  an  item  into  the  queue.  The 
source  process  is  waiting  for  a  delay 
to  expire,  at  which  point  it  will  place  a 
new  item  in  the  queue.  Thus,  the  sched¬ 
uler  advances  the  simulated  time  when 
every  process  is  either  waiting  for  a 
delay  request  to  expire  or  is  waiting  for 
some  event  that  will  be  generated  by  a 
process  that  is  waiting  for  a  delay  re¬ 
quest  to  expire. 

Before  showing  how  the  scheduler 
process  can  determine  when  this  has 
happened,  we  need  to  introduce  some 
formalism.  At  any  given  time,  each  en¬ 
tity  process  is  in  one  of  these  three 
states: 

waiting:  Waiting  for  an  explicit  delay 
request  from  the  scheduler 
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active:  Computing  in  zero  simulated 

time 

passive:  Waiting  for  something  other 
than  a  delay  request 

As  an  example,  consider  a  source  pro¬ 
cess  that  waits  for  a  random  inter¬ 
arrival  delay  and  then  places  a  job  on 
the  queue.  The  source  process  starts 
in  the  active  state.  It  enters  the  waiting 
state  when  it  delays  for  the  inter-arrival 
time;  it  becomes  active  again  when  the 
scheduler  reactivates  it.  If  the  Q  is  not 
full,  the  source  process  stays  active  while 
it  places  the  job  in  the  queue.  How¬ 
ever,  if  the  queue  is  full,  the  source 
process  enters  the  passive  state,  and 
remains  passive  until  some  server  pro¬ 
cess  creates  space  by  removing  a  job 
from  the  queue. 

Thus  the  scheduler  accepts  delay  re¬ 
quests  until  there  are  no  active  entity 
processes,  at  which  time  the  scheduler 
advances  the  simulated  clock  and  re¬ 
activates  the  appropriate  process(es). 
The  scheduler  knows  the  number  of 
processes  waiting  for  the  delay  requests, 
so  all  it  needs  to  know  is  the  number 
of  passive  processes.  To  give  the  sched¬ 
uler  this  information,  we  will  call  a 
scheduler  transaction  whenever  a  pro¬ 
cess  changes  state  from  active  to  pas¬ 
sive  or  vice  versa. 

A  Two-State  Queuing  Network 

We  will  develop  a  simulation  program 
for  the  queuing  network  in  Figure  2. 
In  this  network,  jobs  enter  queue  1 
from  a  Poisson  source  (exponential  inter¬ 
arrival  times).  The  arrows  indicate  the 
direction  in  which  jobs  flow.  The  first 
stage  has  two  servers  (servers  1.1  and 
1.2),  each  of  which  takes  the  next  avail¬ 
able  job  from  a  common  queue.  The 
second  stage  has  one  server;  it  takes 
jobs  from  the  second  queue,  and  dis¬ 
cards  them  when  done.  The  queues 
are  FIFO  (first-in-first-out),  and  can  hold 
at  most  100  jobs.  If  a  queue  is  full,  the 
server  or  source  putting  an  item  into 
this  queue  is  blocked  until  space  is 
available.  Similarly,  if  a  queue  is  empty, 
the  server  taking  an  item  from  the  queue 
is  blocked  until  an  item  is  available  (if 
more  items  are  expected)  or  an  end-of- 
file  is  indicated  to  the  server.  The  ser¬ 
vice  times  are  exponentially  distributed, 
and  are  determined  when  a  job  enters 
the  system.  Servers  1.1  and  1.2  run  at 
half  the  speed  of  server  2;  that  is,  if 
server  2  takes  x  time  units  to  process  a 
job,  server  1.1  takes  2x  units. 

Structure  of  the  Simulation  Program 

In  this  section,  we  present  the  inter¬ 
faces  to  the  processes  in  the  simulation 
program  for  the  queuing  network  de¬ 
scribed  in  the  previous  section;  the  next 
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section  describes  how  these  processes 
are  implemented.  This  simulation  pro¬ 
gram  uses  four  types  of  processes: 

sched:  Simulated-time  scheduler 

process 

queue:  Finite-capacity  FIFO  queue 

source:  Source  of  arriving  jobs 

server:  Single-input,  single-output 

server 

The  main  process  creates  these  pro¬ 
cesses  and  connects  them  appropriately. 


Concurrent 
programming  can 
simplify  the  task  of 
writing  a  discrete  event 
simulation  program 


The  simulation  program  terminates 
after  simulating  the  specified  number 
of  jobs.  The  source  process  terminates 
after  generating  these  jobs.  Before  ter¬ 
minating,  the  source  process  informs 
its  output  queue  that  no  more  jobs  will 
arrive.  When  the  queue  is  empty  (and 
no  more  jobs  are  expected),  the  queue 
process  informs  the  servers  that  no  more 
jobs  will  arrive.  Each  server  then  prints 
its  statistics,  tells  its  output  queue  that 
it  is  done,  and  terminates.  In  this  way 
the  queues  are  drained  automatically 
and  all  processes  eventually  terminate. 

Strictly  speaking,  this  causes  our  sta¬ 
tistics  to  be  distorted  by  the  “edge  ef¬ 
fects”  of  filling  up  the  queues  at  the 
beginning  of  the  simulation.  And  drain¬ 
ing  them  at  the  end.  However,  we  will 
simulate  enough  jobs  to  mitigate  this 
distortion. 

Scheduler  Process  Interface 

The  scheduler  process  manages  simu¬ 
lated  time.  The  time  units  are  arbitrary. 
We  will  refer  to  the  processes  that  call 
the  scheduler’s  transactions  as  the  “cli¬ 
ents”  of  the  scheduler.  The  specifica¬ 
tion  of  the  scheduler  process  is  in  List¬ 
ing  One,  page  71. 

A  delay  request  requires  calling  the 
transactions  reqDelay  and  wait.  The 
client  process  first  calls  reqDelay,  giv¬ 
ing  the  number  of  time  units  to  delay, 
and  then  calls  wait,  giving  the  value 
returned  by  reqDelay.  The  wait  trans¬ 
action  returns  the  simulated  time  as  the 
end  of  the  delay.  Thus,  if  s  is  the  sched¬ 
uler  process,  the  following  statement 


delays  the  calling  process  for  ten  time 
units,  and  saves  the  time  at  the  end  of 
the  delay  in  ts:  ts  =  s.wait(  s. reqDe¬ 
lay  (10)  ); 

The  scheduler  accepts  reqDelay  calls 
until  it  has  received  a  request  from 
every  active  client  process.  Then  the 
scheduler  accepts  the  wait  call  from 
the  process  with  the  smallest  delay  re¬ 
quest. 

For  this  to  work,  the  scheduler  must 
know  the  number  of  its  client  processes, 
and  must  know  how  many  of  them  are 
in  the  passive  state.  Each  client  process 
calls  transaction  addUser  when  it  starts, 
and  calls  transaction  dropUser  before 
it  terminates,  so  that  the  scheduler  can 
maintain  a  client  count.  Whenever  an 
active  client  process  becomes  passive, 
the  scheduler  is  informed  by  calling 
transaction  passive.  This  call  is  made 
by  the  server  process  that  forces  a  cli¬ 
ent  to  wait.  Whenever  a  passive  pro¬ 
cess  becomes  active,  the  process  that 
makes  it  active  calls  the  scheduler’s 
active  transaction.  Thus  the  scheduler 
can  determine  the  number  of  passive 
processes. 

Source  Process  Interface 

The  source  process  has  the  specifica¬ 
tions  shown  in  Listing  Two,  page  71. 
Arrivals  are  Poisson,  and  service  times 
are  exponentially  distributed.  The  pro¬ 
cess  parameters  define  the  output 
queue,  the  mean  values  for  the  distri¬ 
butions,  and  so  on. 

The  name  parameter  is  a  symbolic 
name,  such  as  “sourcel,”  which  the 
source  process  uses  to  identify  itself 
when  printing  statistics  (a  simulation 
program  could  have  several  different 
source  processes).  The  type  name_t  is 
a  structure  containing  a  character  string: 

typedef  struct  Ichar  str[20];l  namej; 

This  structure  is  passed  by  value  to  the 
source  process.  A  simpler  alternative 
would  be  to  declare  the  parameter  as 
a  character  pointer.  However,  if  we  do 
that,  our  simulation  program  will  work 
only  when  run  on  an  implementation 
that  provides  shared  memory.  Passing 
a  structure  by  value,  on  the  other  hand, 
will  work  on  any  Concurrent  implemen¬ 
tation. 

Server  Process  Interface 

The  server  process  has  the  specifica¬ 
tions  shown  in  Listing  Three,  page  71. 
If  the  output  queue  parameter  is 
c_nullpid,  then  the  server  discards  each 
job  after  processing  it.  The  speed  pa¬ 
rameter  is  the  relative  speed  of  this 
server;  this  server  takes  ^speed  time 
units  to  process  a  job  whose  service 
time  is  x. 
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Queue  Process  Interface 

Each  job  in  a  queue  is  represented  by 
a  structure  of  type  Item ,  as  shown  in 
Listing  Four,  page  71.  We  save  the  job 
arrival  time  in  this  structure  so  that  we 
can  calculate  statistics  for  the  time  spent 
by  jobs  in  the  system. 

The  queue  process  simulates  a  FIFO 
queue,  as  shown  in  Listing  Five  (page 
71).  A  queue  process  can  have  several 
clients.  Clients  are  either  consumers 
(“takers”)  or  producers  (“putters”).  A 
source  process  is  a  producer;  a  server 
process  is  a  consumer  for  its  input  queue 
and  a  producer  for  its  output  queue. 
Each  producer  process  calls  transac¬ 
tion  addProd  when  it  starts,  and  calls 
transaction  dropProd  before  it  termi¬ 
nates.  Similarly,  each  consumer  pro¬ 
cess  calls  transactions  addCons  and  drop- 
Cons.  This  allows  the  queue  process 
to  keep  track  of  the  number  of  pro¬ 
ducer  and  consumer  clients.  When  the 
queue  is  empty  and  the  last  producer 
has  terminated,  all  subsequent  take  re¬ 
quests  return  an  end-of-file  indication. 
The  queue  process  terminates  when  it 
has  no  more  producers  or  consumers. 

Transactions  putReq  and  putWait  put 
an  item  onto  the  queue,  and  transac¬ 
tions  takeReq  and  takeWait  take  the 
next  item  from  the  queue.  However, 
client  processes  do  not  call  these  trans¬ 
actions  directly.  Instead,  these  processes 
call  functions  qPut  and  qTake ,  which 
perform  the  put  and  take  operations. 
Both  functions  wait  until  the  operation 
can  be  performed.  If  an  operation  can¬ 
not  be  completed  immediately,  the 
queue  process  informs  the  scheduler 
process  of  the  client’s  change  of  state 
(active  to  passive  or  passive  to  active). 
Function  Take  returns  1  if  able  to  take 
(get)  an  item,  or  0  on  end-of-file.  qPut 
and  qTake  are  the  interface  functions 
for  the  queue  process;  they  hide  a  com¬ 
plicated  transaction  interface. 

Example  2  takes  jobs  from  the  queue 
qFrom  and  places  them  on  the  queue 
^Tband  continues  until  qFrom  is  empty 
and  all  its  producers  have  terminated. 
The  implementations  of  the  qPut  and 
qTake  functions,  and  the  body  of  the 
queue  process,  will  be  described  later. 

Statistical  Functions 

We  will  use  a  simple  statistical  package 
that  calculates  the  mean  and  standard 
deviation  of  a  set  of  values,  as  shown 
in  Listing  Six,  page  71.  The  statistics  are 
kept  in  a  structure  of  type  stats.  Each 
of  the  functions  declared  earlier  takes 
a  pointer  to  such  a  structure  as  its  first 
argument.  Function  stlnit  initializes  the 
structure.  Function  stVal  updates  the 
statistics  to  reflect  a  new  value.  Func¬ 
tions  stMean  and  stDev return  the  mean 
and  standard  deviation  of  these  values. 


The  random  number  generator  er¬ 
rand! m)  returns  an  exponentially  dis¬ 
tributed  integer  whose  mean  is  the  in¬ 
ter  value  m.  (Strictly  speaking,  errand 
cannot  be  exponential  because  it  re¬ 
turns  integer  values  instead  of  floating¬ 
point  values.  However,  we  will  use 
large  mean  values  so  that  the  round-off 
effect  will  be  insignificant.) 

Example  3  shows  the  code  fragment 
that  generates  1000  random  numbers 
and  prints  their  average. 

Process  Implementations 

The  main  process,  shown  in  Listing 
Seven,  page  71,  creates  the  processes 
that  simulate  the  entities  and  connects 
them  together.  Function  makeNamecre- 
ates  and  returns  a  structure  of  type 
name_t  that  contains  the  string  passed 
as  an  argument. 

The  structure  of  the  queuing  net¬ 
work  —  the  number  of  stages,  the  num¬ 
ber  of  servers  per  stage,  and  so  on  —  is 
determined  by  main  and  can  easily  be 
changed.  For  example,  we  can  add  a 
third  server  to  the  first  stage  just  by 
replicating  the  line  that  creates  server 
1.2,  but  with  a  different  symbolic  name. 

Notice  that  main  sleeps  for  a  few 
seconds  before  terminating.  This  delay 
allows  other  processes  to  call  the  trans¬ 
action  addUser  of  the  scheduler  and 
to  make  their  initial  delay  request  (if 
any).  The  scheduler  will  now  allow 
any  other  process  to  proceed  until  main 
calls  transaction  dropUser.  Delaying 
main  is  necessary  to  allow  other  pro¬ 
cesses  enough  time  to  register  with  the 
scheduler.  Otherwise,  the  scheduler  will 
terminate  immediately  after  main  calls 
transaction  dropUser. 

We  have  assumed  that  all  processes 
will  be  dispatched  and  will  perform 
their  initialization  within  two  seconds. 
To  avoid  this  assumption,  we  could 
modify  main  to  call  an  initialization 


Example  2:  Moving  jobs  between 
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transaction  belonging  to  each  of  the 
processes  that  it  creates;  this  initializa¬ 
tion  transaction  would  call  transaction 
addUser  of  the  scheduler. 

Source  and  Server  Processes 

Listing  Eight,  page  71,  shows  the  body 
of  the  source  process.  First,  the  source 
process  initializes  the  statistics  count¬ 
ers,  and  tells  the  scheduler  and  queue 
processes  that  they  have  one  more 
client.  Then  the  source  process  repeat¬ 
edly  calculates  an  inter-arrival  time, 
delays  for  this  amount,  generates  a 
service  time,  and  places  a  job  in  the 
output  queue.  Finally,  the  source  pro¬ 
cess  prints  its  statistics  and  tells  the 
scheduler  and  the  output  queue  that 
they  have  one  less  client.  This  pattern  — 
initialization,  main  processing,  and  ter¬ 
mination  —  is  common  in  our  pro¬ 
cesses. 

Listing  Nine,  page  71,  shows  the  body 
of  the  server  process.  It  starts  by  telling 
the  scheduler,  the  input  queue,  and  the 
output  queue  to  increment  their  client, 
consumer,  and  producer  counts,  re¬ 
spectively.  The  server  process  then  re¬ 
peatedly  takes  a  job  from  its  input 
queue,  delays  for  the  job’s  service  time, 
and  places  the  job  on  its  output  queue. 
Finally,  the  server  process  prints  statis¬ 
tics  on  the  time  that  job  spent  in  the 
system.  The  server  process  also  tells  its 
input  and  output  queues  and  the  sched¬ 
uler  to  decrement  their  client  counts. 

Queue  Process 

Listing  Ten,  page  71,  shows  the  source 
for  the  interface  functions  for  the  queue 
process.  A  put  or  take  request  that  can 
be  done  immediately  requires  one  trans¬ 
action  call;  otherwise  two  calls  are  re¬ 
quired.  As  mentioned  earlier,  functions 
qPut  and  qTake ,  which  are  called  by 
the  clients  of  a  queue  process,  imple¬ 
ment  the  necessary  protocol  for  inter¬ 
stats  mystats; 
int  i; 

stlnit (smystats)  ; 
for  (i  =  1;  i  <=  10000;  i++) 
stVal (Smystats,  erand(100)); 
printfC'Mean  is  %lf\n",  stMean 
(Smystats) ) ; 

Example  3:  Generating  random 
numbers 
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acting  with  the  queue  process.  To  put 
an  item,  qPtr  first  calls  putReq.  If  the 
queue  is  not  full,  putReq  puts  the  item 
and  returns  -1.  If  the  queue  is  full, 
putReq  returns  a  non-negative  “ticket" 
value.  In  this  case,  qPut calls  the  queue’s 
putWait  transaction,  giving  the  ticket 
returned  by  putReq.  When  space  be¬ 
comes  available  in  the  queue,  the  queue 
process  accepts  transaction  put  Wait  and 
puts  the  item  on  the  queue. 

Function  qTake  is  similar;  the  only 
difference  is  that  the  takeReq  transac¬ 
tion  returns  a  structure  that  contains 
either  the  item  taken  or  the  ticket  value. 

The  body  of  the  queue  process  uses 
several  auxiliary  functions  to  manipu¬ 
late  the  data  structures  that  maintain 
the  queue’s  state.  All  the  information 
necessary  to  define  a  queue  is  col¬ 
lected  in  a  structure  of  type  qlnfo.  The 
queue  process  passes  a  pointer  from 
this  structure  to  the  auxiliary  functions 
shown  in  Listing  Eleven,  page  72. 

Member  items  of  the  structure  type 
qlnfo  point  to  a  circular  buffer  qltem 
structure.  The  integer  head  is  the  index 
of  the  next  item  that  can  be  taken  from 
the  queue,  and  tail  is  the  index  of  the 
next  slot  into  which  an  item  can  be 
put.  We  keep  statistics  on  “time  in 
queue”  and  “number  in  queue.”  The 
latter  is  sampled  when  a  job  is  placed 
in  a  queue. 

Ticket  numbers  returned  by  putReq 
and  takeReq  are  assigned  circularly  from 
0  and  9999.  Put  and  take  tickets  are 
assigned  independently.  Structure  tlnfo 
contains  information  about  pending  tick¬ 
ets.  We  need  one  instance  of  this  struc¬ 
ture  for  pending  puts,  and  another  for 
pending  takes.  Listing  Twelve,  page  72, 
shows  the  body  of  the  queue  process. 

The  queue  process  starts  by  initializ¬ 
ing  the  qlnfo  structure,  and  then  waits 
for  the  first  producer's  addProc  request. 
The  queue  process  then  accepts  re¬ 
quests  as  long  as  it  has  any  clients. 
Before  terminating,  the  queue  process 
prints  the  statistics  that  it  has  recorded. 

We  will  now  analyze  handling  of  the 
“take”  requests  by  the  queue  process 
in  detail.  There  are  two  alternatives  for 
takeReq  with  mutually  exclusive  guards. 
The  first  of  these  alternatives  accepts 
requests  whenever  there  are  items  in 
the  queue  and  when  there  are  no  pend- 


Figure  3:  A  feedback  queuing  network 


ing  takeWa  it  requests  (that  is,  no  pend¬ 
ing  take  tickets).  This  alternative  calls 
takeltem,  which  removes  an  item  from 
the  buffer,  updates  the  statistics,  and 
sets  the  ticket  and  gotltem  fields  to  indi¬ 
cate  that  an  item  was  taken  immediately. 
Also,  if  another  client  is  blocked  on  a 
put  request,  takeltem  tells  the  sched¬ 
uler  that  the  process  is  now  active.  This 

Each  queue  and  each 
server  is  modeled  by  a 
Concurrent  C process. 
This  is  a  natural  way 
to  simulate  a 
queuing  network 


ensures  that  the  scheduler  will  not  honor 
another  delay  request  until  the  process 
that  is  blocked  on  the  put  request  is 
able  to  execute  its  pending  putWait 
transaction.  This  takeReq a\\.emaX\ve  re¬ 
turns  the  item  selected  by  takeltem  to 
the  client  process. 

The  second  takeReq  alternative  ac¬ 
cepts  requests  whenever  the  queue  is 
empty.  It  assigns  a  ticket,  updates  the 
ticket  data,  tells  the  scheduler  that  an 
active  client  has  just  become  passive, 
and  returns  the  ticket  to  the  client. 

There  are  two  alternatives  for  take- 
Wait.  When  there  are  items  in  the  queue, 
the  first  alternative  accepts  the  request 
with  the  oldest  pending  ticket.  This 
alternative  takes  an  item  from  the  buffer 
and  returns  it  to  the  client.  When  end-of- 
file  has  occurred  (when  there  are  no 
producers  and  the  queue  is  empty)  the 
second  take  Wait  alternative  accepts  any 
remaining  takeWait  calls.  This  alterna¬ 
tive  returns  an  end-of-file  indicator  to 
the  client. 

The  put  requests  are  handled  simi¬ 
larly.  Transactions  addCons,  dropCons, 
addProd,  and  dropProd just  update  the 
consumer  and  producer  counts.  Listing 


Thirteen,  page  72,  shows  the  auxiliary 
functions  called  from  the  body  of  the 
queue  process. 

Scheduler  Process 

The  scheduler  keeps  a  list  of  pending 
delay  requests,  ordered  by  the  time  at 
which  the  client  is  to  be  reactivated. 
List  entries  are  pairs  (f,  ri)  where  r  is  the 
simulated  time  and  n  is  the  number  of 
processes  to  be  awakened  at  that  time. 
Listing  Fourteen,  page  72,  is  an  outline 
of  the  body  of  the  scheduler  process 
sched. 

After  initialization,  the  scheduler  pro¬ 
cess  repeatedly  accepts  requests  until 
all  clients  become  passive.  For  each 
delay  request,  the  scheduler  calculates 
the  absolute  time  at  which  the  request¬ 
ing  process  should  be  reactivated,  and 
adds  an  appropriate  entry  to  the  list  of 
pending  delay  requests.  This  list  is  or¬ 
dered  by  increasing  reactivation  times. 
List  entries  are  allocated  from  an  array; 
the  reqDelay  transaction  uses  the  array 
index  as  a  ticket  value.  When  all  client 
processes  are  passive,  the  scheduler 
takes  the  next  request  from  the  list, 
advances  the  simulated  time,  and  ac¬ 
cepts  wait  requests  from  all  the  clients 
waiting  for  the  new  simulated  time. 

The  suchthat  clause  performs  a  lin¬ 
ear  search  through  the  pending  requests; 
this  will  be  inefficient  if  there  are  hun¬ 
dreds  or  thousands  of  pending  delay 
requests.  For  small  simulations,  how¬ 
ever,  the  simplicity  of  the  scheduler 
makes  up  for  the  inefficiency  that  may 
result  from  this  linear  search.  If  this 
search  proves  to  be  expensive  in  large 
simulations,  we  can  eliminate  the  such¬ 
that  clause  by  making  the  client  pro¬ 
cess  supply  a  transaction  pointer  with 
which  the  scheduler  will  call  the  client 
when  it  is  ready  to  accept  the  client’s 
delay  request. 

A  Feedback  Queuing  Network 

Consider  the  feedback  queuing  net¬ 
work  in  Figure  3.  This  network  differs 
from  the  previous  network  in  two  ways: 

•  Each  server  in  the  first  stage  has  its 
own  queue.  When  a  job  arrives,  the 
source  places  the  job  in  the  shorter 
of  the  two  queues. 

•  With  probability  p,  the  second  stage 
server  discards  a  completed  job;  with 
probability  1-p,  it  returns  the  job  to 
queue  2  for  further  processing. 

To  simulate  this  network,  we  can  reuse 
the  server,  queue,  and  scheduler  pro¬ 
cesses.  We  will  need  two  new  process 
types:  A  source  process  that  puts  the 
job  in  the  smaller  of  two  queues,  and 
another  server  process  that  discards  a 
job  with  some  probability. 
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The  new  source  process  will  be  simi¬ 
lar  to  the  original  source  process,  except 
that  it  has  two  output  queue  parame¬ 
ters,  outQl  and  outQ2.  After  generating 
a  job,  the  new  source  process  puts  the 
job  on  the  smaller  of  the  two  output 
queues,  which  it  can  do  with  the  code 
fragment  shown  in  Example  4. 

The  new  server  process  is  similar  to 
the  original  server  process,  except  that 
it  has  a  new  parameter probDone,  which 
is  the  probability  of  discarding  a  job 
after  processing  it.  Because  this  new 
server  is  a  feedback  server,  it  does  not 
tell  the  output  queue  that  it  is  a  con¬ 
sumer  process.  (If  it  did  this,  the  simu¬ 
lation  would  never  terminate.  That  is, 
the  server  will  not  terminate  until  its 
input  queue  indicates  end-of-file.  This 
will  not  happen  until  all  of  the  input 
queue's  producers  have  terminated.  If 
the  server  process  were  one  of  these 
producers,  it  would  never  terminate.) 

Extensions  and  Modifications 

We  will  now  discuss  some  ways  of 
extending  our  simulation  program  to 
model  other  queuing  programs. 

Other  Queue  Disciplines  —  Our 
queue  process  can  be  easily  modified 
to  use  a  last-in-first-out  (LIFO)  disci¬ 
pline,  or  a  more  complicated  queue 
discipline,  such  as  shortest-service-time- 
first.  This  would  require  simple  changes 
to  the  putltem  and  takeltem  functions, 
but  the  basic  structure  of  the  queue 
process  would  remain  unchanged. 

Servers  with  Multiple  Output 
Queues  —  Modeling  a  more  general 
queuing  network  in  which  servers  out¬ 
put  to  multiple  queues  is  straightfor¬ 
ward.  For  example,  the  server  could 
be  given  an  array  of  output  queue  pro¬ 
cess  identifiers,  and  the  server  could 
randomly  select  the  output  queue  for 


if  (outQl . itemCnt ()  <  outQ2 . 

itemCnt  ( ) ) 

qPut (outQl, 
else 

item) ; 

qPut (outQ2, 

item) ; 

Example  4:  Choosing  queues 


main  () 

{ 

create  all  processes 
while  (1)  { 

s . wait (s . reqDelay (10000) ) ; 
for  each  entity  process  p 
entity-stats  =  p. 
giveStats  ()  ; 

if  (statistics  have  been  stable 
for  long  enough) 

break; 

) 

print  final  statistics 
for  all  processes  p 
c_abort (p)  ; 

} 


Example  5:  An  example  o/main(  ) 


each  job.  Alternatively,  the  server  could 
send  each  job  to  all  of  its  output  queues. 

More  General  Networks  —  The 
structure  of  the  queuing  network  is 
determined  by  how  the  main  process 
creates  the  source,  server,  and  queue 
processes,  and  how  it  connects  them 
together.  This  is  easy  to  extend;  we 
could  even  write  a  main  process  that 
reads  a  network  description  at  run  time. 

Statistics  —  In  general,  we  want  to 
measure  the  steady-state  performance 
of  a  queuing  system.  Our  processes 
do  not.  Instead,  they  measure  the  en¬ 
tire  simulation  run,  including  the  in¬ 
itialization  phase  (starting  with  an  empty 
queue)  and  the  termination  phase  (drain¬ 
ing  the  queues  after  the  source  stops). 
We  compensate  for  this  by  simulating 
many  jobs,  so  that  the  initialization  and 
termination  phases  are  small  compared 
to  the  steady-state  period. 

A  better  technique  is  to  monitor  the 
statistics  during  the  simulation  and  ter¬ 
minate  the  simulation  when  the  statis¬ 
tics  have  been  stable  for  a  long  time. 
We  can  accomplish  this  by  adding  a 
giveStats  transaction  to  each  entity  pro¬ 
cess.  This  transaction  will  return  the 
current  statistics  of  the  process  to  which 
it  belongs.  After  starting  all  processes, 
main  would  repeat  this  cycle  until  it 
decided  that  the  simulation  had  reached 
a  steady  state.  Thus,  main  would  look 
something  like  Example  5.  Transaction 
giveStats  is  easy  to  add  to  the  queue 
process;  it  is  just  another  alternative  in 
the  central  select  statement.  For  the 
source  and  server  process,  the  central 
loop  would  be  modified  to  condition¬ 
ally  accept  a  giveStats  transaction  (that 
is,  accept  a  call  if  one  is  available,  but 
continue  if  no  call  is  pending). 

Availability 

All  source  code  is  available  on  a  single 
disk  and  online.  To  order  the  disk, 
send  $14.95  (Calif,  residents  add  sales 
tax)  to  Dr.  Dobb’s Journal ,  501  Galves¬ 
ton  Dr.,  Redwood  City,  CA  94063,  or 
call  800-356-2002  (from  inside  Calif.) 
or  800-533-4372  (from  outside  Calif.). 
Please  specify  the  issue  number  and 
format  (MS-DOS,  Macintosh,  Kaypro). 
Source  code  is  also  available  online 
through  the  DDJ  Forum  on  Compu¬ 
Serve  (type  GO  DDJ).  The  DDJ  Listing 
Service  (603-882-1599)  supports  300/ 
1200/2400  baud,  8-data  bits,  no  parity, 
1-stop  bit.  Press  SPACEBAR  when  the 
system  answers,  type:  listings  (lower¬ 
case)  at  the  log-in  prompt. 

DDJ 

(Listings  begin  on  page  71.) 

Vote  for  your  favorite  feature/article. 

Circle  Reader  Service  No.  3. 
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Making  the  move 


Al  Stevens 


s  (void)  ; 


n  () 

te  dt; 
workday 

e  * 


t->isXmas  () ; 


m 


■  V' 


77  workday:: is 
//  date::isXma 
//  workday:: is 


date : : isXmas ( ) ;  / /  date : : isXm< 


C++  is  an  object-oriented  super¬ 
set  of  C  that  Bjarne  Stroustrup 
developed  at  AT&T  Bell  Labo¬ 
ratories  beginning  in  1980  and 
continuing  with  successive  re¬ 
leases.  Although  C++  goes  back  almost 
ten  years,  its  recent  attention  in  the  PC 
community  is  largely  due  to  the  grow¬ 
ing  interest  in  object-oriented  program¬ 
ming  and  the  availability  of  new  C++ 
language  development  environments. 

In  this  article,  I  will  discuss  some 
C++  extensions  that  make  life  easier 
for  C  programmers  and  how  C++  brings 
the  object-oriented  programming  para¬ 
digm  to  C.  This  article  is  not  a  compre¬ 
hensive  treatment  of  the  subject;  I  nei¬ 
ther  describe  all  the  features  of  C++ 
nor  explain  every  nuance  of  every  fea¬ 
ture.  Such  coverage  would  fill  a  book, 
and  C++  books  and  articles  are  appear¬ 
ing  with  increased  regularity  as  the  lan¬ 
guage  gains  momentum. 

Dr.  Stroustrup  developed  the  C++ 
language  system  as  a  preprocessor  that 
translates  C++  code  into  C  code,  which 
is  then  compiled  by  a  traditional  C  com¬ 
piler.  Newer  C++  language  systems  use 
native  code  compilers  that  translate  di- 


Al  is  a  contributing  editor  and  colum¬ 
nist  for  DDJ  and  the  author  of  a  num¬ 
ber  of  books  on  C.  He  can  be  reached 
at  DDJ ,  501  Galveston  Drive,  Redwood 
City,  CA  94063- 
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rectly  from  the  C++  source  language 
to  the  native  language  of  the  target 
machine.  I  will  refer  to  all  C++  lan¬ 
guage  systems  as  “compilers,”  but  these 
references  apply  as  well  to  prepro¬ 
cessing  translators. 

C++,  an  Improved  C 

Forget,  for  the  moment,  object-oriented 
programming.  If  you  never  define  a 
class  or  declare  an  object  —  things  I'll 
discuss  shortly  —  you  can  still  benefit 
from  the  improvements  that  C++  of¬ 
fers.  Many  of  these  improvements  were 
important  enough  that  the  ANSI  X3J11 
committee  incorporated  them  into  the 
C  language-standard  specification,  and 
you  might  know  them  now  as  ANSI  C 
additions  rather  than  as  the  legacy  of 
C++.  Among  the  ANSI  adoptions  are 
the  function  prototype,  the  const  type 
qualifier,  and  the  void  type.  There  are 
other  C++  features  that  you  can  use  in 
your  traditional  function-oriented  C  pro¬ 
gramming,  ones  not  included  by  ANSI, 
but  definite  enhancements,  nonethe¬ 
less.  I’ll  discuss  some  of  these  advan¬ 
tages  before  exploring  the  object-ori¬ 
ented  facets  of  C++.  So,  for  now,  let’s 
look  at  C++  as  an  improved  C. 

Mandatory  Prototypes  —  One  of  the 

C++  contributions  to  ANSI  C  was  the 
new-style  function  definition  and  declara¬ 
tion  blocks.  ANSI  calls  the  definition 
block  a  “function  prototype.”  Both 
blocks  contain  the  parameters’  type  de¬ 
scriptions  in  the  parenthesized  parame¬ 
ter  list. 

ANSI  C  allows  for  both  the  old  and 
new-style  function  blocks  to  protect 
existing  code,  and  you  can  use  a  mix 
of  both  styles  in  an  ANSI  C  program. 
With  C++,  however,  the  old  style  is  not 
supported.  C++  requires  you  to  code 
with  the  new  style,  and  that  is  a  strong 
advantage,  because  the  new  style  en¬ 
forces  stronger  type  checking  of  pa¬ 
rameter  and  return  data  types. 

Comments  —  C++,  as  a  superset  of  C, 
recognizes  the  standard  C  comment 
style  that  delimits  comments  with  the 
/  *  and  */  tokens.  But  C++  has  another 
comment  format.  Wherever  the  //  to¬ 
ken  appears,  everything  to  the  end  of 
the  line  is  a  comment. 

Because  C++  recognizes  both  for¬ 
mats,  many  programmers  use  the  new 
format  for  comments  and  the  old  for¬ 
mat  to  temporarily  disable  blocks  of 
code.  Comments  do  not  nest  in  C,  so 
disabling  code  by  surrounding  it  with 
the  /  *  and  V  delimiters  does  not  work 
if  the  code  to  be  disabled  itself  con¬ 
tains  comments.  In  C++,  old-style  com¬ 
ments  can  include  the  new  style  com¬ 
ment  format,  so  the  /*...*/  format  is 


an  effective  way  to  “comment  out”  code. 
If  you  use  the  old  format  exclusively 
for  this  purpose,  finding  all  such  com- 
mented-out  code  is  a  simple  matter  of 
using  a  grep  utility  program  or  your 
editor  to  find  all  instances  of  the  /  * 
token. 

Default  Function  Arguments  — You  can 

declare  a  default  value  for  arguments 
in  a  C++  function  prototype  in  the  fol¬ 
lowing  way: 

void  funcfint  =  5,  double  =  1.23); 

The  expressions  declare  default  values 
for  the  arguments.  The  C++  compiler 
substitutes  the  default  values  if  you 
omit  the  arguments  when  you  call  the 
function.  You  can  call  the  function  by 
using  any  of  these  ways: 

func(12,  3.45);  //  overrides  both  defaults 
func(3);  //  effectively  func(3,  1.23); 

funcf  );  //  effectively  func(5,  1 .23); 

Variable  Declaration  Placement  —  In 

C,  you  must  declare  all  variables  at  the 
beginning  of  the  block  in  which  they 
have  scope.  You  may  not  intermix  vari¬ 
able  declaration  and  procedural  expres¬ 
sions.  C++  removes  that  restriction,  allow¬ 
ing  you  to  declare  a  variable  anywhere 
before  you  reference  it  and  making  ex¬ 
pressions  such  as  this  one  possible: 

forCint  ctr  =  0;  ctr  <  MAXCTR;  ctr++) 

//  ... 

This  feature  allows  you  to  code  the 
declaration  of  a  variable  closer  to  the 
code  that  uses  it. 

Stand-alone  Structure  Names  —  In  C, 

you  refer  to  structures  with  the  struct 
keyword  as  a  prefix  to  the  name.  In 
C++,  the  structure  is  closely  related  to 
the  class  (discussed  later),  and  its  name 
is  similar  to  a  keyword  for  as  long  as 
the  definition  is  in  scope.  You  can  code 
the  following: 

struct  linkedlist  I 

/*  —  whatever  —  */ 
linkedlist  *previous_node; 
linkedlist  *next_node;  ); 

Observe  that  the  two  pointers  are  de¬ 
clared  without  the  struct  keyword.  Later 
declarations  of  the  structure  may  use 
the  linkedlist  word  only,  as  shown  here: 

linkedlist  mylist; 

The  effect  here  is  as  if  you  had  used 
this  typedef  m  C: 

typedef  struct  linkedlist  linkedlist; 


The  typedef  would  not  have  worked 
for  the  pointers  in  the  structure  be¬ 
cause  the  fgrierfe/cleclaration  is  not  com¬ 
plete  when  the  pointer  declarations  oc¬ 
cur,  so  the  C++  notation  offers  a  dis¬ 
tinct  improvement. 

Inline  Functions  —  You  can  tell  the  C++ 
compiler  that  a  function  is  “inline.”  This 
causes  a  new  copy  of  it  to  be  compiled 
in  line  each  time  it  is  called.  The  inline 
nature  of  the  individual  copies  elimi¬ 
nates  the  function-calling  overhead  of 
a  traditional  function.  Obviously  you 
should  use  the  inline  function  qualifier 
only  when  the  function  itself  is  rela¬ 
tively  small. 

Global  Scope  Resolution  —  In  C,  if  a 

local  variable  and  a  global  variable  have 
the  same  name,  all  references  to  that 
name  from  within  the  block  where  the 
local  variable  is  declared  will  refer  to 
the  local  variable.  The  local  variable 
name  overrides  the  global  name.  C++ 
adds  the  global  scope  resolution 
operator  with  which  you  can  explicitly 
reference  a  global  variable  from  a  scope 
where  a  local  variable  has  the  same 
name.  Consider  the  code  in  Example  1. 

In  this  example,  the  output  would 
be  123456  because  the  first  printf  refers 
to  the  hidden  global  amount  variable 
by  virtue  of  the  global  scope  resolu¬ 
tion  operator. 

asm  ( string );  —  C++  offers,  as  a  stan¬ 
dard  way  to  incorporate  assembly  lan¬ 
guage  into  a  C++  program,  the  “asm” 
keyword.  Many  C  compilers  have  ways 
to  do  this,  but  there  is  no  standard. 
ANSI  sidestepped  the  issue  as  being 
implementation  dependent.  C++  faces 
it  head-on  and  provides  a  standard 
way  to  pass  the  string  of  your  choice 
to  the  assembler.  Assuming  all  C++  com¬ 
pilers  use  the  standard,  only  the  con¬ 
tents  of  the  string  are  implementation- 
dependent.  If  you  define  the  strings 
separately,  the  assembly  language  com¬ 
ponents  of  your  programs  are  more 
manageable. 

Of  course,  this  is  not  a  perfect  solu¬ 
tion.  Whenever  you  use  assembly  lan¬ 
guage,  you  must  be  ready  to  deal  with 
it  when  you  undertake  a  port.  Just  be¬ 
cause  assembly  language  was  appro¬ 
priate  in  your  original  program  does 
not  mean  you  will  be  able  to  use  it  in 
the  ported  version.  But  at  least  the  C++ 
approach  moves  the  layer  of  non-port¬ 
able  implementation  dependence  to  a 
more  distant  platform. 

The  Free  Store  —  C++  introduces  an 
improved  heap  management  facility 
called  the  “free  store.”  It  is  implemented 
with  two  operators  named  “new”  and 
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“delete.”  The  new  operator  is  analo¬ 
gous  to  malloc  in  that  it  allocates  mem¬ 
ory  and  assigns  its  address  to  a  pointer. 
Its  argument,  however,  is  more  descrip¬ 
tive  than  the  integer  value  that  you 
pass  to  malloc.  Its  purpose  is  to  allow 
you  to  allocate  memory  for  a  semi¬ 
permanent  variable,  one  that  remains 
in  scope  beyond  the  block  in  which  it 
is  declared.  Here  are  some  examples: 

char  *cp  =  new 
char[strlen(whatever)+ 1  ] ; 
linkedlist  *first_node  =  new 
linkedlist; 

Observe  that  the  array-like  expression 
in  the  first  example  contains  a  variable 
dimension.  The  second  example  assumes 
a  structure  (or  class)  named  “linked¬ 
list,”  such  as  the  one  used  earlier. 

When  you  are  ready  to  destroy  the 
variable,  you  use  the  delete  operator 
in  much  the  same  way  that  you  used 
the  free  function  in  traditional  C. 

delete  cp; 
delete  first_node; 

C++  allows  you  to  override  the  new 
and  delete  operators  by  coding  your 
own  new  and  delete  functions.  It  also 
provides  a  global  function  pointer  that 
the  system  calls  when  any  new  opera¬ 
tion  cannot  get  the  memory  it  needs. 
By  calling  the  set_new_handler  func¬ 
tion  with  the  address  of  your  heap 
exhaustion  error  function,  you  can  is¬ 
sue  new  operations  without  testing 
the  pointer  values  for  a  NULL  return 
every  time. 

References  —  C++  includes  a  derived 
data  type  called  a  “reference.”  It  is  a 
form  of  alias  and  will  seem  oddly  like 
a  pointer  to  the  C  programmer.  Here’s 
what  a  simple  reference  looks  like: 

int  sam; 

int&  george  =  sam; 

The  &  reference-to  operator  tells  the 
C++  compiler  that  george  is  an  alias  for 
sam.  Wherever  you  say  george  you 
could  have  said  sam.  If  you  only  use  it 
that  way,  you  might  just  as  well  use  a 
#define,  but  simple  substitution  is  not 
the  strength  of  a  reference. 

If  you  pass  a  variable  as  an  argument 
to  a  function  that  is  expecting  a  refer¬ 
ence,  the  compiler  actually  passes  the 
variable’s  address.  The  called  function 
acts  upon  the  caller’s  copy  of  the  vari¬ 
able  through  its  address  rather  than 
upon  a  local  copy.  This  feature  shows 
its  promise  when  used  with  structures. 
An  example: 

void  setheight(struct  cube&  box) 

( 

box.height  =  5; 


This  function  will  change  the  value  of 
the  structure  owned  by  the  calling  func¬ 
tion  rather  than  the  value  of  a  local 
copy.  This  procedure  eliminates  un¬ 
necessary  copying  of  data  values  back 
and  forth  between  functions  while  pre¬ 
serving  the  notation  of  a  local  variable, 
which  is  simpler  and  more  readable 
than  de-referenced  pointer  notation. 

A  function  can  return  a  reference, 
as  shown  in  this  code: 

int&  getwidth(  ) 

( 

/*...*/ 

return  newwidth; 


The  caller  of  the  getwidth  function  does 
not  need  to  know  that  the  called  func¬ 
tion  returns  a  reference.  You  can  code 
the  receiving  variable  as  a  reference 
itself  or  an  actual  variable.  Either  way 
works.  Some  C++  experts  believe  that 
you  should  never  return  a  reference. 
Others  disagree. 

Overloaded  Function  Names  —  In  C++, 
you  can  have  several  functions  with 
the  same  name  in  the  same  scope.  The 
compiler  distinguishes  the  functions 
based  on  their  argument  types.  This 
feature,  called  “overloading,”  lets  you 
use  the  same  name  to  represent  the 
same  generic  operation  on  different 
data  types. 

Here  is  an  example  of  an  overloaded 
function  name’s  prototypes: 


Example  1:  Global  variables 


Example  2:  Structures  with  functions 


void  display(int);  //  display  an  int 

void  display(char);  //  display  a  char 
void  display(long);  //  display  a  long 
void  displayCdouble);  //  display  a  double 

These  prototypes  represent  four  dis¬ 
tinct  functions  with  the  same  name. 
When  you  call  the  name,  the  argument 
you  supply  tells  the  compiler  which 
one  you  want. 

Support  for  overloading  is  one  rea¬ 
son  why  C++  needs  prototypes  for  ev¬ 
erything.  The  compiler  must  see  the 
argument  types  so  it  can  distinguish 
functions  that  have  the  same  name. 

Structures  with  Functions  —  C++  al¬ 
lows  you  to  code  functions  as  mem¬ 
bers  of  structures.  This  practice  binds 
a  function  call  to  an  instance  of  a  struc¬ 
ture.  Consider  the  code  in  Example  2. 

You  have  defined  a  structure  that 
has  three  integers  and  a  function.  You 
must  now  complete  the  structure’s  defi¬ 
nition  by  declaring  the  function: 

int  cube: :volume( void) 

I 

return  length  *  width  *  height; 


Observe  that  you  declare  the  function 
as  a  member  of  the  cube  structure  by 
attaching  the  cube::  prefix  to  the  func¬ 
tion  name.  Notice  also  that  the  func¬ 
tion  does  not  need  to  name  the  in¬ 
stance  of  the  structure  when  it  refers 
to  one  of  the  structure’s  members.  The 
compiler  knows  that  the  function  will 
be  called  on  behalf  of  an  instance  of 
the  structure  in  which  the  function  is  a 
member,  and  the  compiler  automati¬ 
cally  makes  the  association  for  you. 

Next  you  declare  a  cube  object  and 
get  some  values  into  the  cube’s  dimen¬ 
sions: 

struct  cube  box  =  (5,4,3); 

That  looks  like  and  is  traditional  C. 
You  have  declared  a  structure  of  type 
cube  and  named  it  box.  You  have  in¬ 
itialized  the  dimensions  of  the  struc¬ 
ture.  Finally,  you  call  the  cube’s  vol¬ 
ume  function  to  compute  the  volume 
of  the  cube. 

printfC “Volume:  %d”,  box. volume!  )); 

Observe  the  form  of  the  volume  func¬ 
tion  call.  The  function  name  is  prefixed 
with  the  identifier  of  the  declared  struc¬ 
ture  in  standard  C  structure  member 
addressing  format. 

This  little  exercise  is  a  sneak  preview 
of  the  C++  class,  a  more  complex  ver¬ 
sion  of  the  enhanced  structure  used 
here.  It  is  also  your  introduction  to 


34 


Dr.  Dobb's  C Sourcebook,  Winter  1989/90 

985 


object-oriented  programming  in  that  the 
structure  just  shown  is  an  abstract  data 
type  including  a  method,  and  the  struc¬ 
ture  declaration  named  box  is  an  object. 

So  far  we’ve  concentrated  on  the 
additive  features  of  C++  that  can  en¬ 
hance  C  language  programming.  But, 
in  doing  so,  we  brushed  against  some 
new  object-oriented  programming  ideas. 
Now  let’s  consider  what  those  and  other 
new  things  mean  when  viewed  from 
the  perch  of  the  object-oriented  pro¬ 
gramming  platform. 

Object-Oriented  C 

C++,  we  have  said,  adds  the  object- 
oriented  programming  paradigm  to  the 
C  language.  C++  has  “data  abstraction,” 
“encapsulation,”  “objects,”  “methods,” 
“inheritance,”  and  “polymorphism.” 
These  ingredients,  we  are  told,  are  what 
embody  an  object-oriented  program¬ 
ming  platform.  Every  paradigm  wants 
its  own  parlance,  and  you  will  find  that 
these  strange  new  terms  have  unex¬ 
pected  parallels  in  your  C  experience, 
parallels  that,  once  revealed,  make  the 
new  things  easier  to  understand.  Be¬ 
fore  getting  into  the  object-oriented  de¬ 
tails  of  C++,  though,  let’s  try  to  liken 
some  of  these  new  object-oriented  con¬ 
cepts  to  their  counterparts  in  traditional 
function-oriented  C. 

Data  Abstraction,  Encapsulation,  and 
Objects  —  “Data  abstraction”  is  the  abil¬ 
ity  to  describe  new  data  types  in  terms 
of  their  format  and  the  processes  that 
act  upon  them.  “Encapsulation”  is  the 
process  by  which  you  combine,  the 
component  data  and  function  parts  of 
an  abstract  data  type  into  one  encapsu¬ 
lated  definition.  An  abstract  data  type, 
called  a  “class”  in  C++,  is  thus  a  collec¬ 
tion  of  other  data  items  and  functions. 
The  data  items  describe  the  new  class’s 
format,  and  the  functions  describe  how 
it  behaves.  An  instance  of  an  abstract 
data  type  is  called  an  “object." 

C  has  its  own  built-in  data  types.  In 
C,  you  use  char ,  int,  float ,  and  double 
and  qualified  variations.  When  you  de¬ 
clare  one  of  these,  you  are  declaring 
an  instance  of  the  type  or  an  object. 
The  developers  of  your  C  compiler  en¬ 
capsulated  these  data  types  into  the 
compiler  by  describing  their  formats 
and  by  including  the  methods  that  act 
upon  them.  When  you  say: 

int  answer  =  10  +  variable_integer; 

you  have  declared  the  int  object  named 
answer  and  invoked  the  C  compiler’s 
int  method  that  sums  the  values  from 
two  integer  data  type  objects  and  places 
the  result  into  the  answer  object.  The 
int  is  not  an  abstract  data  type  because 
it  is  built  into  the  compiler,  but  it  is, 


nonetheless,  an  object. 

In  object-oriented  programming,  you 
add  to  the  language’s  vocabulary  of 
data  types  with  abstract  data  types  en¬ 
capsulated  by  you  and,  perhaps,  by 
developers  of  third-party  data  type  li¬ 
braries.  So,  in  addition  to  the  int  and 
the  float ,  you  can  have  the  string ,  the 
blivot,  the  Bach_two _part_invention , 
and  whatever  else  you  dream  up  as  a 
new  data  type. 

•  C  Parallel  to  Abstract  Data  Types  — 
The  closest  things  to  abstract  data  types 
in  traditional  C  are  the  typedef  and  the 
struct,  although  they  lack  some  of  the 
other  qualities  of  object-oriented  data 
types.  If  you  define  a  structure  in  C  and 
assign  a  typedef  name  to  it,  you  have 
encapsulated  an  abstract  data  type.  You 
complete  the  encapsulation  by  writing 
C  functions  that  act  upon  structures  of 
the  named  typedef.  The  stdio.h  defini¬ 
tion  of  the  FILE  typedef  is,  when  com¬ 
bined  with  the  fopen,  J 'close ,  fgets,  and 
so  on  functions,  a  loose  encapsulation 
of  the  abstract  FILE  data  type  that  man¬ 
ages  stream  input/output.  The  encap¬ 
sulation  is  not  secure,  however,  and 
that  is  where  object-oriented  program¬ 
ming  comes  in. 

Methods  —  We  call  the  functions  de¬ 
fined  for  an  abstract  data  type  its  “meth¬ 
ods.”  In  object-oriented  programming, 
you  make  things  happen  by  sending 
messages  to  objects.  In  the  encapsula¬ 
tion,  someone  defined  the  methods  that 
act  upon  the  messages  you  send  to  the 
object. 

•  C  Parallel  to  Methods  —  There  is  very 
little  difference  between  the  object- 
oriented  notion  of  sending  a  message 
to  an  object  and  the  traditional  C  no¬ 
tion  of  calling  functions.  The  important 
single  difference  is  that  in  object-ori¬ 
ented  programming,  the  message  and 
the  method  are  tightly  bound  by  en¬ 
capsulation  to  the  declared  object,  the 
instance  of  the  abstract  data  type.  The 
encapsulation  defines  the  binding, 
which  occurs  when  you  declare  the 
object. 

Inheritance  —  Having  defined  an  ab¬ 
stract  data  type,  you  can  define  others 
that  inherit  its  attributes.  This  feature 
is  called  “inheritance.”  One  advantage 
is  that  all  the  work  that  went  into  the 
definition  of  the  base  type  passes  down 
to  the  derived  type.  Another  is  that  it 
encourages  you  to  think  of  and  design 
your  data  system  in  a  structured  way. 

•  C  Parallels  to  Inheritance  —  In  C,  a 
structure  that  has  another  structure  as 
an  element  effectively  inherits  the  prop¬ 
erties  of  the  element  structure  and  adds 
its  own  unique  elements  to  it. 

The  C  array  is  a  derived  type.  You 


describe  a  structure  and  then  describe 
an  array  of  those  structures.  The  struc¬ 
ture  is  the  base  type.  The  array  is  the 
derived  type,  inheriting  the  characteris¬ 
tics  of  the  structure.  Derived  classes  in 
C++  are,  however,  more  powerful  than 
the  simple  addition  of  dimension  to  a 
base  type. 

Other  derived  types  in  C  are  point¬ 
ers,  which  are  derived  directly  from  the 
base  types  to  which  they  point;  con¬ 
stants,  which  are  derived  from  the  types 
assigned  to  them  by  the  compiler;  and 
structures,  which  are  early  examples  of 
derived  types  with  multiple  inheritance 
in  that  they  are  derived  from  the  vari¬ 
ous  types  of  their  multiple  elements. 

Function  Overriding  and  Polymor¬ 
phism  —  Function  overriding  is  the  abil¬ 
ity  for  a  type  or  method  in  a  derived 
type  to  override  a  similarly  defined  type 
or  method  in  its  base  type.  The  differ¬ 
ent  types  up  and  down  a  type  hierar¬ 
chy  can  define  member  types  and  meth¬ 
ods  according  to  their  individual  needs. 
The  programmer  who  is  using  an  ab¬ 
stract  data  type  does  not  need  to  know 
which  method  will  process  the  mes¬ 
sage  being  sent  or  in  which  abstract 
type  the  referenced  member  type  ap¬ 
pears. 

If  you  have  a  base  data  type  and  a 
derived  data  type,  you  send  messages 
to  an  object  of  the  derived  data  type  to 
get  it  to  do  what  you  want.  Because  the 
derived  type  has  inherited  the  attributes 
of  the  base,  you  can  send  messages 
that  are  defined  as  belonging  to  the 
base  data  type,  and  the  derived  type 
will  accept  them  and  use  the  methods 
of  the  base  to  act  upon  them. 

With  function  overriding,  you  can 
define  a  member  type  or  method  in  a 
derived  data  type  that  resembles  one 
in  its  base.  Send  a  message  via  that 
method  or  refer  to  that  member  type, 
and  the  one  defined  in  the  derived  type 
gets  used.  Not  all  of  the  base’s  derived 
types  will  duplicate  the  original.  If  you 
send  a  message  to  an  object  way  down 
the  hierarchical  ladder,  the  compiler 
will  select  the  method  from  the  first 
type  higher  in  the  hierarchy  where  the 
method  is  defined. 

If,  however,  you  address  the  derived 
type  through  the  base  type,  perhaps 
by  a  base-type  pointer  that  contains 
the  address  of  the  derived  type,  then 
the  base  function  gets  used,  and  overrid¬ 
ing  does  not  occur.  When  you  do  not 
want  this  to  happen,  when  you  want 
the  derived  overriding  function  to  be 
used  regardless  of  how  you  address 
the  type,  then  you  must  invoke  “poly¬ 
morphism.” 

Polymorphism  is  a  nuance  of  func¬ 
tion  overriding.  If  you  declare  the  base 
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function  as  a  “virtual”  function,  then  it 
will  always  be  overridden  by  functions 
with  the  same  name  and  characteristics 
in  the  derived  types. 

•  C  Parallel  to  Function  Overriding  — 
Traditional  C  uses  a  form  of  function 
overriding  in  its  arithmetic  operations. 
If  you  view  the  integers,  floating  point 
numbers,  and  pointers  as  a  hierarchy 
of  arithmetic  types,  the  various  ways 
that  you  add  to  them,  for  example,  can 
be  thought  of  as  similar  methods  in  a 
data  model,  methods  that  are  invoked 
on  the  basis  of  the  data  types  rather 
than  the  operators. 

There  seems  to  be  no  parallel  in  C 
to  the  object-oriented  concept  of  poly¬ 
morphism. 

These,  then,  are  the  fundamentals 
of  object-oriented  programming,  and 
we  have  considered  how  you  might 
associate  your  function-oriented  pro¬ 
gramming  practices  with  them.  Some 
of  our  analogies  stretch  the  point  to  its 
limit,  but  their  purpose  is  to  assure  you 
that  the  paradigm  called  “object-ori¬ 
ented  programming”  is  largely  a  differ¬ 
ent  way  of  looking  at  what  you  have 
been  doing  all  along. 

Now  let’s  look  at  some  of  the  details 
of  C++  and  see  how  those  principles 
are  applied. 

C++  Classes 

The  basic  unit  of  encapsulation  in  C++ 
is  the  class.  What  we  called  the  abstract 
data  type  before,  we  will  now  call  the 
“class”  because  they  are  the  same  thing. 
C++  uses  the  class  keyword  to  describe 
its  version  of  the  programmer-defined 
data  type.  When  you  encapsulate  an 
abstract  data  type,  you  define  a  class. 
When  you  declare  an  object,  you  de¬ 
clare  an  instance  of  a  class.  Example  3 
illustrates  what  a  definition  of  a  class 
looks  like. 

This  definition  describes  a  class 
named  date.  It  resembles  a  structure 
in  that  it  has  members  consisting  of 
data  variables  and  functions.  The  mem¬ 
bers  prior  to  the  public  keyword  are 
private  parts.  The  rest  are  public.  The 
difference  between  the  class  and  the 
struct  shown  earlier  is  that  all  the  mem¬ 
bers  of  the  struct  are  visible  to  all  parts 
of  your  program  while  only  the  public 
members  of  a  class  can  be  seen  by 
your  program’s  functions.  The  private 
parts  of  a  class  can  be  read  and  changed 
only  by  functions  that  are  themselves 
members  of  the  class.  (For  an  excep¬ 
tion,  see  the  discussion  on  friends.) 

Usually,  the  private  parts  are  vari¬ 
ables  and  the  public  parts  are  func¬ 
tions.  Nothing  says  that  this  must  be 
so,  but  it  seems  to  be  a  good  conven¬ 
tion  to  follow  and  works  for  most  class 
definitions. 


In  addition  to  the  public  keyword, 
you  can  declare  that  certain  members 
are  “private”  and  others  are  “protected.” 
Members  in  a  class  are  private  by  de¬ 
fault  as  are  our  day,  month ,  and  year 
members.  Members  in  a  structure  are 
public  by  default  unless  you  declare 
them  as  private  or  protected. 

The  access  control  of  a  member  indi¬ 
cates  what  kinds  of  functions  can  ac¬ 
cess  the  members.  A  private  member 
can  be  accessed  by  member  functions 
and  friends  only.  Public  members  can 
be  accessed  by  any  function  that  de¬ 
clares  an  object  of  the  class  or  has  the 
structure  in  scope.  Protected  members 
of  classes  are  private  except  that  mem¬ 
ber  functions  and  friends  of  derived 
classes  can  access  them.  We  will  dis¬ 
cuss  member  functions,  friends,  and 
derived  classes  soon. 

Our  date  class’s  encapsulation  is  in¬ 
complete  because  all  the  methods  are 
not  there  yet.  Remember,  methods  are 
functions. 

Classes  usually  have  at  least  two  mem¬ 
ber  functions  and  often  more.  The  usual 
two  are  the  “constructor”  member  func¬ 
tion  and  the  “destructor"  member  func¬ 
tion,  although  it  is  not  required  that 
you  define  them.  The  others  are  the 
methods. 

Constructors  and  Destructors  —  When 
you  declare  an  object  as  an  instance 
of  a  class,  you  do  it  in  much  the  same 
way  that  you  declare  any  other  data 
type.  Compare  this  integer  and  this  date: 

int  ctays_on_board;  date  datejiired; 
They  look  the  same,  and  to  the  pro¬ 


class  date  { 
int  day; 
int  month; 
int  year; 
public: 

date (void) 

(day  =  month  =  year  =  0;) 
date (int  da,  int  mo,  int  yr) ; 
date()  (  /*  null  destructor  */  ) 
void  display (void) ; 

); 


Example  3:  A  class  definition 


date : :date (int  da,  int  mo,  int  yr) 
{ 

day  =  da; 
month  =  mo; 
year  =  yr; 

) 


Example  4:  Constructor function 


grammer  using  them,  they  are.  But  when 
you  design  the  class,  you  usually  pro¬ 
vide  for  one  constructor  function  and 
one  destructor  function.  The  construc¬ 
tor  function  executes  when  you  de¬ 
clare  the  object,  and  the  destructor  func¬ 
tion  executes  when  the  object  goes  out 
of  scope.  If  you  omit  these  functions, 
then  no  special  processing  occurs  when 
an  object  enters  and  leaves  scope. 

A  constructor  function  has  the  same 
name  as  the  class  itself  and  has  no 
return  value.  In  the  date  example  above, 
we  have  defined  two  constructor  func¬ 
tions,  both  named  date.  They  are  dis¬ 
tinguished  by  their  different  argument 
types;  the  first  constructor  has  no  argu¬ 
ments,  and  the  second  constructor  has 
three  integer  arguments.  These  are  over¬ 
loaded  constructor  functions  because 
they  have  the  same  name  and  different 
parameters. 

Observe  next  that  the  first  construc¬ 
tor  definition  is  not  terminated  with  a 
semicolon  but  has  a  brace-surrounded 
block  of  code  following  it.  This  format 
is  the  member  function’s  version  of  an 
inline  function.  By  including  the  code 
with  the  definition  in  this  manner,  you 
build  an  inline  function,  in  this  case 
one  that  merely  initializes  the  three  date 
variable  members  to  zero.  This  con¬ 
structor  function  executes  when  you 
declare  a  date  object  with  no  initializ¬ 
ing  values  as  shown  here: 

date  date_hired; 

The  second  constructor  function  is  not 
an  inline  function  (although  it  could 
be),  so  you  must  provide  its  code  some¬ 
where.  The  function  might  look  like 
that  in  Example  4. 

Observe  that  the  function  declara¬ 
tion  is  prefixed  with  date::  to  associate 
it  with  the  date  class.  Observe  also  that 
the  function  has  free  access  to  the  pri¬ 
vate  members  of  the  class.  This  par¬ 
ticular  constructor  executes  when  you 
declare  a  date  object  with  three  integer 
initializer  values  as  shown  here: 

date  date_retired(25,  5,  88); 

The  destructor  function  has  the  same 
name  as  the  class  but  with  a  tilde  pre¬ 
fix.  In  the  date  example  class  used 
here,  the  destructor  function  does  noth¬ 
ing,  so  it  is  coded  as  a  null  inline  func¬ 
tion.  More  complex  classes  will  require 
things  to  be  done  when  the  object  goes 
out  of  scope.  Perhaps  some  free  store 
memory  needs  to  be  deleted,  for  exam¬ 
ple,  and  the  destructor  function  would 
take  care  of  that. 

Member  Functions  —  Besides  the  con¬ 
structor  and  destructor,  a  class  can  have 
other  member  functions.  These  are  the 
methods  of  the  class.  In  our  date  exam- 
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pie,  we  show  a  member  function  named 
“display.”  To  use  this  method,  we  must 
code  it  something  like  this-. 

void  date  ::display( void) 

I 

printf(“%d/%d/%d”,  month,  day,  year); 

) 

(Experienced  C++  programmers  might 
wonder  why  I  use  the  old-fashioned 
printf  when  the  C++  stream  facility  is 
available.  Because  I  haven’t  described 
the  stream  classes  yet,  their  use  would 
tend  to  confuse  those  who  are  not  fa¬ 
miliar  with  them  I'll  discuss  streams 
later.) 

The  program  that  declares  a  date 
object  can  then  use  a  member  function 
related  to  the  date  class  such  as  this: 

date_hired.display(  ); 

In  the  parlance  of  object-oriented  pro¬ 
gramming,  we  have  sent  a  message  to 
the  date_hired  object  to  tell  it  to  use  its 
display  method.  It  looks  a  lot  like  a 
traditional  function  call,  doesn’t  it? 

Friends  —  The  private  members  of  a 
class  are  visible  only  to  the  class’s  mem¬ 
ber  functions.  The  constructor,  destruc¬ 
tor,  and  display  member  functions  in 
the  date  class  can  read  and  write  the 
month,  day,  and  year  integers,  but  no 
outside  function  has  that  access.  From 
time  to  time  you  will  find  a  need  to 
provide  outside  access  to  the  innards 
of  one  of  your  classes.  A  named  func¬ 
tion  or  class  can  be  a  “friend”  of  the 
class  being  defined.  You  can  make  the 
assignment  of  friend  status  only  from 
within  the  definition  of  the  class  that 
grants  access  as  shown  in  Example  5. 

These  are  two  classes  named  date 
and  time  (with  the  details  omitted). 
We  need  the  extra  time  declaration  at 
the  top  because  the  friend  statement 
in  the  date  class  has  a  reference  to  it. 
The  two  classes  share  a  friend  function 
named  shownow ,  which  might  display 
the  current  date  and  time  like  this: 

void  shownow(date&  d,  time&  t) 

I 

printf(“\n%d/%d/%d”,  d.day,  d. month, 

d.year); 

printf(“\n%d:%d:°/6d”,  t.hr,  t.min,  t.sec); 

1 

Because  the  shownow  function  is  a 
friend  to  both  classes,  it  can  read  the 
private  members  of  both. 

A  class  can  have  another  class  as  its 
friend  with  this  statement: 

class  date  (//...  friend  class  time; ); 

Operator  Overloading 

Operator  overloading  is  one  of  the 
neater  tricks  you  can  do  with  C++.  It  is 
what  makes  the  language  so  extensi¬ 


ble.  You've  already  seen  how  you  can 
add  data  types  by  defining  classes.  Next, 
you  might  want  to  perform  arithmetic, 
relational,  and  other  operations  on  your 
classes  the  same  way  that  you  do  with 
int  and  float  variables  and  the  like. 
We  built  a  simple  date  class.  Consider 
Example  6. 

Both  these  forms  are  possible  with 
C++.  You  can  build  class  member  func¬ 
tions  that  the  compiler  associates  with 
C  operators.  This  feature  is  called  “op¬ 
erator  overloading.”  When  you  use  an 
operational  expression  such  as  the  ones 
just  shown,  your  operator  overloading 
member  functions  get  called.  Here’s 
an  example: 

class  date  ( 

// ... 

int  operator<(date&); 


Example  5:  Making  an  assignment  of 
friend  status 


Example  6:  A  simple  date  class 


Example  7:  A  member  function 


The  date  class  definition  says  that  a 
member  function  overloads  the  less- 
than  operator.  When  you  code  this  ex¬ 
pression: 

(retirement_date  <  today) 

the  function  that  associates  the  less- 
than  operator  to  a  date  class  with  an¬ 
other  date  class  as  the  argument  is  called. 
It  returns  a  true  or  false  integer.  The 
member  function  might  look  like  that 
in  Example  7. 

The  function  refers  to  the  class  on 
the  left  side  of  the  expression  by  nam¬ 
ing  its  private  parts  without  qualifica¬ 
tion  (day,  month,  year).  It  refers  to  the 
argument’s  private  parts  by  way  of  the 
reference  variable  ( dt.day ,  dt.month , 
dt.year). 

You  can  overload  any  C  operator  in 
this  manner.  You  cannot  create  your 
own  operators  such  as  “)(”  or  anything 
the  compiler  would  choke  on,  and  you 
may  not  use  overloaded  operators  in 
ways  that  the  compiler  cannot  parse, 
such  as  A  [  B.  You  could,  however,  use 
this  feature  to  create  some  really  con¬ 
fusing  code.  You  might,  for  example, 
use  the  +  operator  to  logically  subtract 
two  classes.  Try  to  steer  clear  of  such 
nonsense. 

Operator  overloading  is  a  powerful 
feature.  You  can  overload  the  [ )  array 
operator  to  create  your  own  array  pro¬ 
cessing.  You  can  overload  the  (  )  func¬ 
tion  call  operator  to  make  a  class  look 
like  a  function  call.  And,  of  course,  you 
can  have  several  different  functions  over¬ 
loading  the  same  operator  with  differ¬ 
ent  argument  types.  You  might  want 
separate  functions  for  adding  floats  and 
longs  to  your  class,  for  example. 

The  /Ms Pointer  —  Every  member  func¬ 
tion  has  a  built-in  pointer  named  this. 
It  points  to  the  object  being  processed 
by  the  member  function.  When  a  mem¬ 
ber  function  wants  to  make  a  copy  of 
the  object  or  return  it  after  perhaps 
modifying  it,  the  member  function  can 
reference  the  object  as  *this. 

To  illustrate  the  use  of  the  this  pointer, 
let’s  take  another  look  at  the  overloaded 
addition  operator.  Our  less-than  over¬ 
loaded  operator  returned  an  integer, 
but  an  arithmetic  expression  needs  to 
return  a  copy  of  the  class.  Consider  the 
example  we  saw  earlier: 

if  (date_married  +  365  =  =  today)  // 
Happy  Anniversary  .  .  . 

There  are  two  overloaded  operations 
implied  by  this  expression.  One  is  the 
equality  =  =  operator,  which  would  look 
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a  lot  like  the  less-than  operator  we 
already  built.  The  other  is  the  addition 
operator.  Here  they  are  in  the  class 
definition. 

class  date  ( 

II ... 

date&  operator+(int); 
int  operator=  =(date  &); 

) 

The  overloaded  +  operator  must  re¬ 
turn  a  class  that  has  the  result  of  the 
addition  as  its  value.  It  does  not  add 
the  integer  to  the  class  called  out  in  the 
expression.  It  performs  the  addition 
and  returns  the  result,  which  is  itself  a 
date  class.  Without  the  complex  date 
arithmetic  that  checks  for  month  over¬ 
flow,  leap  years,  and  all  that,  here  is 
what  the  overloaded  +  operator  func¬ 
tion  looks  like. 

date&  date::operator+(int  n) 

I 

date  dt; 
dt  =  ’this; 

//  add  n  to  dt. month, dt. day. dt. year 
//  ... 
return  dt; 

1 

You  will  see  that  we  copy  the  object 
being  added  to  into  a  temporary  date 
named  dt.  The  this  pointer  provides  a 


way  for  us  to  do  this. 

If  you  wanted  to  overload  the 
+  =  operator,  the  function  would  look 
like  this: 

date&  date::operator+=(int  n) 

I 

//  add  n  to  month, day, year 

II ... 

return  ’this; 


Class  Assignment 

Observe  in  the  overloaded  +  operator 
above  that  the  object  pointed  to  by  this 
is  assigned  to  the  object  named  dt.  C++ 
includes  a  built-in  assignment  operator 
for  every  class  you  define.  It  simply 
copies  all  the  members  from  one  ob¬ 
ject  to  the  other  much  the  way  that 
structure  assignment  works  in  C.  You 
can  overload  the  assignment  operator 
if  you  need  to.  You  would  do  that  if 
you  wanted  to  assign  something  other 
than  another  object  of  the  same  class. 
Consider  this,  for  example: 

^include  <time.h> 

II ... 

date_hired  =  time(NULL); 

stream,  h 

Throughout  the  examples  so  far,  we 


have  used  print/ to  display  data.  C++ 
includes  stream  input/output  classes 
already  defined  in  stream. h.  They  have 
several  advantages  over  the  traditional 
printf/scanf  pair.  To  write  something 
to  the  console  you  say: 

cout  «  “Hello,  Dolly”; 

The  stream. h  file  not  only  includes 
the  ostream  and  istream  classes,  it  in¬ 
cludes  external  declarations  of  the  stan¬ 
dard  objects,  cout  and  cin ,  which  are 
assigned  to  the  console.  The  example 
just  given  shows  how  the  ostream  class 
has  overloaded  the  «  operator.  This 
is  not  a  bitwise  shift  operation  in  this 
usage.  The  notation  is  meant  to  repre¬ 
sent  the  direction  of  data  flow.  The  « 
operator  is  overloaded  several  times 
to  allow  you  to  send  different  data 
types  to  the  console  without  worrying 
about  their  format.  Here  are  examples: 

cout  «  “Blossom"; 
cout  «  ’  \  n’; 
cout  «  123; 

The  overloaded  operator  functions  re¬ 
turn  references  to  the  object  being  pro¬ 
cessed,  so  you  can  write  the  above 


example  in  this  way: 

cout  «  ’’Blossom"  «  ’  \  n’  «  123; 

The  istream  class  works  the  other 
way  with  »  as  the  operator  to  signify 
data  flowing  from  the  object  to  the 
argument  variable  as  shown  here: 

void  main(  ) 

I 

char  mystring[80]; 

//.  .  . 

cin  »  mystring; 


You  can  declare  streams  and  associate 
them  with  file  buffers  as  well.  There 
are  several  standard  methods  that  sup¬ 
port  file  stream  input/output  included 
in  stream. h. 

Conversion  Functions  —  Conversion 
functions  allow  you  to  provide  for  the 
conversion  of  a  class  to  another  type, 
either  a  standard  C  data  type  or  another 
class  as  shown  here: 

class  date  1 

//.  . 

operator  long!  ); 


You  would  write  the  overloaded  func¬ 
tion  such  as  the  one  shown  in  Example 
8  and  can  call  the  function  one  of  sev¬ 
eral  ways  as  shown  in  Example  9. 

The  notation  you  choose  would  de¬ 


long  date :: operator  long () (void) 

( 

long  days_since_creation; 

//  compute  the  number  of  days... 

II  ... 

return  days_since_creation; 

) 


Example  8:  An  overloaded  function 


void  main () 

1 

date  today; 
long  eversince; 

II  ... 

eversince  =  (long) today; 
eversince  =  today; 
eversince  =  long (today); 

} 


Example  9:  One  way  of  calling  the 
function  listed  in  Example  8 


pend  on  how  you  are  using  the  con¬ 
version.  The  first  format  looks  like  a 
cast,  and  the  second  implies  that  a  nor¬ 
mal  type  conversion  is  going  on.  You 
might  use  the  last  format  if  you  want 
the  code  to  remind  you  that  you  are 
invoking  a  class  conversion  function. 

This  example  shows  how  you  con¬ 
vert  a  class  to  a  standard  C  or  C++  data 
type.  You  can  use  the  same  technique 
to  build  class-to-class  conversion  func¬ 
tions,  but  some  programmers  prefer  to 
use  specific  constructor  functions  to 
perform  conversions  of  classes  to  other 
classes.  When  the  target  class  comes 
into  scope,  the  constructor  conversion 
function  gets  the  data  values  from 
the  object  that  is  its  parameter.  For 
example: 

date  today(25,  12,  89); 

II ... 

Julian  julian_today( today);  //  a  class 
named  Julian 

Inheritance 

Inheritance  is  a  vital  ingredient  for  object- 
oriented  programming.  Many  C  pro¬ 
grammers  will  use  the  advanced  fea¬ 
tures  of  C++  classes  to  add  data  types 
and  never  concern  themselves  with  class 
hierarchies.  Others  will  explore  the 
murky  depths  of  inheritance  and  will 
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build  huge,  exotic  class  systems,  mak¬ 
ing  every  new  class  a  new  wrinkle  on 
an  old.  Somewhere  in  between  is  the 
probable  ideal. 

A  class  in  C++  can  be  defined  as  a 
derivative  of  another  class.  Given  the 
generic  date  class  we’ve  used  so  far, 

If  you  never  define  a 
class  or  declare  an 
object  you  can  still 
benefit  from  the 
improvements  that 
C++  offers 


we  might  need  a  more  specific  date, 
one  that  has  all  the  properties  of  other 
dates  but  that  has  a  few  unique  ones 
of  its  own.  Here  is  how  you  would 
code  a  derived  class: 

class  workday  :  date  I 

int  shift; 

public: 

workdayfint  da,  int  mo,  int  yr,  int  sh); 

//  ... 

1; 

We  have  defined  a  class  named  work¬ 
day  that  is  derived  from  the  class  named 
date.  The  workday  class  is  called  the 
“derived”  class,  and  the  date  class  is 
called  the  “base”  class.  The  derived 
workday  class  has  its  own  private  mem¬ 
ber,  the  shift  variable.  What  you  do  not 
see  is  that  the  class  also  has  variables 
named  day,  month,  and  year  because 
it  is  derived  from  the  date  class  which 
has  those  variables,  and  that  is  how 
inheritance  works.  The  workday  con¬ 
structor  function  has  a  shift  variable, 
one  more  variable  than  the  correspond¬ 
ing  date  constructor.  Here  is  the  con¬ 
structor  function: 

workday: :workday(int  da, int  mo, int 
yr,int  sh) 

:  date(  da,  mo,  yr  ) 

1 

shift  =  sh; 


The  expression  following  the  colon  af¬ 
ter  the  argument  list  shows  what  the 
workday  constructor  function  will  pass 
to  the  date  constructor  function.  The 
values  do  not  have  to  be  taken  from 
the  argument  list  as  we  have  done  here, 


they  can  be  any  valid  expressions  that 
match  the  argument  types  of  the  base 
class’s  constructor  function. 

Member  functions  in  a  derived  class 
can  read  and  write  the  public  members 
of  the  base  class  if  the  derived  class  has 
not  reused  the  member  name  as  shown 
in  Example  10. 

A  derived  class  can  reuse  a  member 
name  that  is  used  in  a  base.  This  is 
function  overriding.  If  the  derived  class 
has  reused  the  base  member’s  name, 
any  unqualified  references  to  that  name 
will  point  to  the  member  in  the  derived 
class.  But  if  the  member  wants  to  ac¬ 
cess  the  base  class's  member,  the  de¬ 
rived  member  function  qualifies  the 
name  such  as  this: 

x  =  date  ::  month; 

Non-member  functions  that  declare 
objects  of  the  derived  class  cannot  ac¬ 
cess  the  public  members  of  the  base 
class  unless  the  public  keyword  qualifies 
the  inheritance  as  shown  in  Example  11. 

A  derived  class  cannot  access  the 
private  parts  of  its  base  unless  it  is 
declared  by  the  base  as  a  friend.  If  you 
are  adding  a  new  class  to  a  class  hierar¬ 
chy  and  find  that  a  derived  class  needs 
to  get  at  a  private  member  of  a  base 
class  somewhere  up  the  line,  you  will 
need  to  rummage  around  in  the  class 
definitions  to  find  and  modify  the  base 
class.  You  must  either  declare  the  de¬ 
rived  class  (or  one  of  its  functions)  as 
a  friend  of  the  base  Or  move  the  de¬ 
sired  element  into  the  public  part  of  the 
base  class. 

Multiple  Inheritance 

The  object-oriented  world  traditionally 
describes  its  types  in  what  they  call  a 


class  workday  :  date  { 
public: 

II  ... 

int  isXmas (void) ; 

); 

int  workday :: isXmas (void) 

( 

return  month  ==  12  &&  day  ==.  25; 

) 


Example  10:  Member  functions 


class  workday  :  public  date  { 

II  ... 

}; 

void  main() 

{ 

workday  proj_dt; 

//  ... 

int  yr_comp  =  pro j_dt. year; 

} 


Example  11:  Non-member  functions 
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“class  hierarchy.”  This  is  often  a  misno¬ 
mer.  In  object-oriented  design,  a  base 
type  can  have  many  derived  types.  If 
you  were  to  stop  there,  you  would 
have  a  hierarchy;  in  a  true  hierarchy 
each  lower  element  is  subordinate  to 
only  one  superior.  Versions  of  C++  prior 
to  2.0,  which  is  the  latest,  adhered  to 
the  hierarchical  model  in  that  a  derived 
C++  class  could  have  only  one  base 
class.  In  Version  2.0,  as  in  many  other 
object-oriented  languages,  a  derived 
class  can  have  multiple  base  classes. 
This  model  is  called  “multiple  inheri¬ 
tance,”  and  it  is  not  a  hierarchy  —  it  is 
a  network.  Programmers  love  to  mix, 
confuse,  and  abuse  metaphors.  No 
doubt  the  “type  hierarchy”  metaphor 
is  destined  to  remain  with  us  even 
though  it  misuses  the  base  from  which 
it  derives. 

A  C++  class  can  inherit  the  attributes 
of  multiple  base  classes  as  shown  in 
Example  12. 

We  have  defined  a  derived  class 
named  datetime  that  inherits  the  attri¬ 
butes  of  two  base  classes  named  date 
and  time.  The  constructor  for  the 
datetime  class  would  look  like  this: 


class  date  { 

II  ... 

}; 

class  time  { 

II  ... 

); 

class  datetime  :  date,  time  { 

II  ... 

public: 

datetime (int  da,int  mo,int  yr, 


Example  12:  Inheriting  attributes  of 
multiple  base  classes 


class  date  { 

//  ... 
public: 

virtual  int  isXmas (void) ; 

}; 

class  workday  :  date  ( 
public: 

int  isXmas (void) ; 

}; 

void  main() 

{ 

date  dt; 
workday  wd; 
date  *dat  =  &dt; 

II  ... 

wd. isXmas ();  //  workday :: isXmas 

dt. isXmas ();  //  date:: isXmas 

dat->isXmas () ;  //  workday :: isXmas  (!) 

wd.date: : isXmas () ;  //  date:: isXmas 

} 


Example  13:  Examples  of  C++  virtual 
functions 


datetime  ::  datetime(int  da,  int  mo,  int 

yr, 

int  hr,  int  min,  int  sec) 

:  date  (da,  mo,  yr),  time  (hr,  min,  sec) 

I 

II ... 

I 

| 

There  are  many  things  to  consider  when  j 
you  build  a  network  of  multiple-inheri-  j 
tance  classes.  You  must  be  aware  of 
the  order  in  which  base  constructors 
are  called  and  you  must  guard  against 
ambiguities  when  you  refer  to  mem¬ 
bers  of  the  derived  and  base  classes. 
The  taller  the  family  tree,  the  harder  it 
is  to  keep  track  of  what  is  involved 
with  distant,  unseen  relatives,  ances¬ 
tors,  and  friends. 

Virtual  Functions 

C++  uses  the  virtual  function  qualifier 
to  declare  a  base-member  function  as 
one  that  is  always  overridden  by  a  de¬ 
rived  class  regardless  of  how  the  de¬ 
rived  class  is  addressed.  If  you  declare 
a  function  in  the  derived  class  with  the 
same  name  and  argument  types,  then 
any  reference  to  that  function  —  even 
through  a  reference  to  the  base  —  will 
invoke  the  derived  class’s  copy  of  the 
virtual  function.  Example  13  illustrates 
some  of  these  concepts. 

This  ability  to  redefine  methods  up 
and  down  the  class  network  is  what 
gives  your  C++  class  definitions  their 
polymorphic  characteristics. 

Future  Directions 

Some  of  the  features  I  discussed  in  this 
article  are  new  to  C++  2.0.  But  the 
language  has  not  finished  growing.  For 
example,  Dr.  Stroustrup  is  working  to 
add  parameterized  data  types  and  ex¬ 
ception  handling  as  intrinsic  parts  of 
the  language.  And  ANSI  is  about  to 
field  a  committee  whose  task  it  will  be 
to  write  a  standard  description  of  C++. 

With  Microsoft  and  Borland  moving 
in  the  object-oriented  language  direc¬ 
tion  and  with  rumors  that  both  will 
introduce  C++  compilers  in  the  ’90s, 
the  future  of  C++  seems  secure.  Given 
the  extensive  improvements  that  C++ 
makes  to  the  C  language,  we  can  safely 
predict  that  C++  will  eventually  replace 
C  as  the  language  of  choice. 
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Automatic 
Module  Control 

Revisited 

Adding  power  to  an  already  powerful  documenting  utility 


Ron  Winter 


This  article  is  a  follow  up  to  Stew¬ 
art  Nutter’s  article  “An  Aid  To 
Documenting  C,”  DDJ,  August 
1988.  In  that  article,  Stewart  pre¬ 
sented  a  printer  program  he 
called  cp  (for  C  printer),  which  allowed 
programmers  to  document  C  source- 
code  modules.  When  I  first  saw  the 
program,  I  realized  that  it  addressed 
my  needs  in  a  general  way,  but  as 
presented  the  program  was  just  not 
sufficient. 

After  entering  the  source  as  printed 
(and  adding  a  few  missing  ++s  and 
fixing  a  few  other  minor  typos)  I  got 
cp  to  run.  Two  things  struck  me  imme¬ 
diately:  Lowercase  Is  as  variables  are 
amazingly  similar  to  Is  in  small  type, 
and  the  program  crashed  when  I  gave 
my  target  program  as  input!  By  this 
time  my  curiosity  was  sufficiently 
aroused,  so  I  decided  I  had  better  un¬ 
derstand  the  program  before  changing 
it  too  much,  or  it  might  never  work. 

What  appeared  to  be  a  simple  task 
became  instead  a  small  research  pro¬ 
ject  into  the  C  language.  It  is  amazing 
how  much  C  code  you  can  write  with- 


Ron  is  a  faithful  Dr.  Dobb’s  subscriber, 
and  has  been  a  microcomputer  aficio¬ 
nado  for  many  years.  He  is  a  software 
engineer  at  SPEX  in  Edison,  N.J.  You 
can  contact  him  at  P.O.  Box  4143, 
Metuchen,  N.J.  08840. 
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out  really  understanding  why  C  is  the 
way  it  is.  The  process  of  correcting  the 
code  so  that  it  would  follow  the  rules 
of  a  C  compiler  and  linker  helped  me 
understand  the  role  of  functions,  and 
brought  me  a  deeper  understanding 
of  computer  languages  and  an  appre¬ 
ciation  for  what  they  do.  Nevertheless, 
you  usually  only  go  far  enough  to  get 
the  job  done.  In  the  case  of  cp,  I  real¬ 
ized  that  if  I  went  much  further,  the 
program  would  start  to  become  a  com¬ 
piler!  That’s  a  thought  I  try  not  to  con¬ 
sider  too  seriously. 

Rewriting  Without  Rewriting 

When  I  began  rewriting  Stewart’s  origi¬ 
nal  program,  all  of  my  prejudices  and 
preferences  in  style  came  to  bear  upon 
the  code  in  a  fit  of  global  search  and 
replacements.  My  own  C  style  is  “pas- 
calean”  in  indenting  and  braces,  with 
highly  descriptive  functions  and  vari¬ 
able  names,  especially  globals. 

Every  function  in  the  original  pro¬ 
gram  is  in  my  own  version  of  cp,  but  the 
names  have  been  changed  to  make  them 
a  little  clearer  (at  least  to  me).  Some 
new  functions  have  been  added.  Func¬ 
tion  declarations  are  included,  and  two 
new  files  were  added:  cpbuild.c  and 
cpinput.c.  cpbuild.c  contains  all  the 
code  needed  by  the  original  function 
xref( ).  The  second  file,  cpinput.c,  han¬ 
dles  the  prompting  and  parameter  pars¬ 
ing  that  the  program  does  at  start-up. 

My  cp  program  consists  of  the  fol¬ 
lowing  files:  CPHEADER.H,  the  header 
file  (Listing  One,  page  73);  CP.C,  the 
main  source  file  (Listing  Two,  page 
73);  CPINPUT.C,  the  command-line 
parser  (Listing  Three,  page  78);  CP 
BUILD. C,  the  front-end  section  of  the 
program  (Listing  Four,  page  79); 
CPFUNCTS.C,  the  back-end  section  (List¬ 
ing  Five,  page  83);  CP,  the  make  file 
(Listing  Six,  page  85);  and  CPLIST,  the 
input  file  to  execute  the  program  on 
itself  (Listing  Seven,  page  85). 

The  make  file  now  uses  the  /packcode 
directive  in  the  linker  command.  This 
allows  me  to  make  all  the  functions 
“near,”  even  in  different  files  in  large 
model  programs,  as  long  as  the  code 
size  is  less  than  a  segment.  The  effect 
is  to  have  the  speed  and  size  of  a  small 
model  program  with  respect  to  the  code. 
The  arguments  to  the  program  are  much 
the  same  as  they  were  in  the  original 
program.  Some  new  parameters  are:  n 
for  normal  (as  opposed  to  IBM)  char¬ 
acter  graphics,  /for  size  of  called  func¬ 
tion  array,  /  for  library  call  statistics,  q 
for  quiet  mode,  d  to  show  declarations 
and  definitions  on  the  console  as  they 
are  found,  h  to  show  more  help  than 
is  shown  when  cp  is  executed  with  no 
arguments,  and  jcto  show  some  techni¬ 


cal  information.  The  program  now  can 
take  uppercase  or  lowercase  parameters 
with  eitherthe"  -  ”  or  “  /  ”  switch  charac¬ 
ter. 

Figure  1  shows  a  sample  printout  of 
the  the  cp  program;  Figure  2  shows  a 
portion  of  a  typical  report  the  program 
produces. 

Repairing  the  Algorithms 

A  minor  deficiency  of  the  original  code 
is  that  it  incorrectly  assumes  that  a  func¬ 
tion  definition  ends  with  a  new  line.  A 
more  correct  algorithm  scans  forward 
from  possible  identifiers;  if  an  open 
parenthesis  is  found,  it  then  scans  for 
the  matching  close  parenthesis  and 
checks  the  next  non-white  character. 
As  in  “Find  That  Function!"  by  Marvin 
Hymowech  (also  in  August  1988),  the 
key  is  to  note  that  if  this  next  character 
is  a  comma  or  semicolon,  a  declaration 
or  prototype  has  been  found.  In  either 
ANSI  style  or  standard  C,  definitions 
have  either  an  open  brace  or  variable 
declaration(s)  following  the  close  pa¬ 
renthesis. 

I  had  to  overcome  two  major  defi¬ 
ciencies  in  the  original  code.  The  first 
was  the  lack  of  treatment  of  static  func¬ 
tions.  The  second  was  the  way  leading 
comments  were  stored.  In  the  original 
code,  the  strdup( )  was  not  checked 
for  failure  at  the  end  of  the  function 
xref( ),  so  it  crashed  on  my  large  pro¬ 
gram.  I  made  a  minor  change  to  the 
program  that  dressed  up  the  form  of 
the  tree-structured  output.  The  con¬ 
necting  lines  did  not  stop  when  there 
was  nothing  underneath  to  connect 
them  to.  Finally,  I  added  a  toggle  for 
IBM  character  graphics  to  draw  the  tree 


in  fine  style. 

I  discovered  that  you  must  really  un¬ 
derstand  what  constitutes  a  correct  C 
program  first  before  you  can  parse  it 
for  function  definitions  and  function 
calls.  The  scanner,  called  getnext( )  in 
the  original,  incorrectly  scanned  quoted 
(“)  strings  and  pound  sign  (#)  state¬ 
ments.  They  both  allow  the  line  con¬ 
tinuation  form  of  backslash  followed 
immediately  by  a  new  line.  Also,  com¬ 
ments  are  considered  white  space  in  a 
#statement  construction.  The  function 
is  now  called  get_to_next_ possible_  to¬ 
ken/  ),  and  it  handles  these  situations 
correctly. 
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static  stop 

Figure  2:  Sample  report  from  the  cp  program 
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I  corrected  the  treatment  of  static 
functions.  First,  you  have  to  recognize 
them,  and  then  mark  them  when  they 
are  entered  into  the  data  base.  It  is  also 
necessary  to  mark  them  in  the  called- 
function  list  with  their  file  name,  if  they 
are  called  at  any  time  in  the  file  under 
analysis.  In  C,  you  can  have  many  func¬ 
tions  with  the  same  name  in  a  program, 
as  long  as  only  one  of  them  is  not  static 
and  each  is  in  a  different  file.  This 
requires  a  change  to  the  way  the  de¬ 
fined  function  call  count  is  done  and 
the  way  the  output  tree  is  checked. 
Basically,  the  binary  search  of  the  sorted 


data  base  must  be  called  with  the  un¬ 
derstanding  that  there  might  be  more 
than  one  defined  function  with  the  same 
name.  If  the  called  function  is  in  a 
different  file  from  the  defined  function 
and  the  defined  function  is  static,  it 
should  not  match.  You  must  search 
adjacent  names  in  the  ASCII  sorted  list 
for  a  called  function  that  is  (first)  static 
in  the  defined  functions  file,  (second) 
not  static  and  in  any  file,  else  it  must 
be  a  library  function.  This  also  reflects 
upon  the  recursion  check.  All  of  these 
issues  are  addressed  in  the  new  ver¬ 
sion  of  the  program.  A  function  is  re¬ 


cursive  if  it  calls  a  function  with  the 
same  name  (perhaps  through  other  func¬ 
tions)  and  the  test  checks  that  the  file 
name  associated  with  the  called  func¬ 
tion  is  the  same  as  the  file  name  of  the 
calling  function.  This  avoids  the  trap 
of  function  x( )  say  in  filel ,  calling  func¬ 
tion  y()  in  file2,  and  y( )  calling  static 
function  x( )  in  file2.  The  original  code 
would  say  incorrectly  that  function  x( ) 
was  recursive. 

A  Few  Extras 

The  point  of  making  the  called  func¬ 
tion  array  programmable  is  to  allow 


C  Printer  for 

Kevin  E.  Poole 


I  modified  Ron  Winter’s  PC/MS-DOS 
C  Printer  Utility  (CP),  presented  in  the 
accompanying  article,  to  run  on  two 
additional  operating  systems:  VAX 
VMS  and  VAX  Unix.  The  modifica¬ 
tions  are  divided  into  four  sets  of 
steps:  The  first  set  involves  creating 
the  makefiles ,  the  second  set  involves 
modifying  the  C  source  code,  the  third 
involves  compiling  and  running  the 
new  CP,  and  the  fourth  set  provides 
two  optional  enhancements  to  CP. 
The  listings  in  my  version  were  devel¬ 
oped  using  DEC  VAX  VMS  5.1-1 
and  DEC  VAX  Unix  BSD  4.3. 

Creating  the  makefiles 

Step  1:  An  MMS  utility  description 

file  was  created  for  the  VMS  operating 

system,  as  shown  in  Listing  One  (page 

86). 

Step  2:  The  make  utility  makefile 
shown  in  Listing  Two  (page  86)  was 
created  for  the  Unix  operating  sys¬ 
tem. 

Step  3:  CP  uses  command-line  op¬ 
tions,  so  the  following  line  should  be 
added  to  the  VMS  login.com  file  to 
create  a  foreign  command  to  run  CP: 

CP  ==  "$DEVLCE:[YOUR_ 

ACCOUNT  .CPjCP.EXE" 


Kevin  is  a  software  design  engineer 
on  the  Boeing  automated  software 
engineering  (BASE) project.  The  BASE 
project  increases  quality  and  produc¬ 
tivity  in  the  development  of  embed¬ 
ded  computer  software .  The  capabili¬ 
ties  presented  in  the  article  are  part 
of  the  BASE  documentation  produc¬ 
tion  system.  Kevin  can  be  contacted 
at  14424  34th  Ave.  S.,  # 2 ,  Seattle, 
WA  98168. 


Step  4:  Because  the  C  Printer  execut¬ 
able  is  called  “cp,”  it  was  necessary  to 
change  it  to  something  else  so  that  it 
would  not  be  confused  with  the  Unix 
cp  command.  CP  (printed  in  bold  in 
my  Listing  Two)  was  changed  to  mycp. 
You  can  name  it  whatever  you  like. 

Modifying  the  C  Code 

Because  of  space  constraints,  the  en¬ 
tire  source  code  for  the  VMS  and  the 
Unix  version  of  the  cp  program  are 
not  included  with  this  article.  Instead, 
I’ve  provided  code  that  should  be 
inserted  into  Ron’s  program,  as  well 
as  code  that  should  replace  portions 
of  his  listings.  Ron’s  listings  will  be 
prefaced  by  the  letters  “RW”  (RW- 
Listing  One,  for  example)  so  as  not 
to  be  confused  with  the  listings  in  this 
article.  However,  the  complete  sys¬ 
tem  is  available  on  the  DDJ  listings 
disk,  the  DDJ  Forum  on  CompuServe, 
and  on  the  DDJ  Listing  Service. 

Step  1:  Define  one  constant  per  op¬ 
erating  system  using  C  preprocessor 
#define  commands.  These  constants 
are  used  in  conjunction  with  the  #if 
and  *e«rft/structures  to  surround  code 
that  is  to  be  conditionally  compiled. 
The  lines  in  Listing  Three  (page  86) 
should  be  inserted  into  RW-Listing 
One  between  lines  3  and  4. 

Step  2:  The  Microsoft  C  function  dec¬ 
larations  contain  the  reserved  word 
“near,”  which  is  not  supported  by 
VMS  or  Unix.  The  function  declara¬ 
tion  blocks  at  the  top  of  each  source 
file  ending  in  “.c”  must  be  duplicated. 
Surround  one  block  with  the  #if 
MSDOS  and  #endif  pair.  Surround 
the  other  block  with  the  #i/VMS  and 
#endif  pair.  From  the  VMS  block  re¬ 


move  all  instances  of  the  “near”  re¬ 
served  word.  The  lines  in  Listing  Four 
(page  86)  should  replace  lines  27 
through  52  in  RW-Listing  Two.  The 
other  source  files  must  also  be  modi¬ 
fied  in  this  way.  The  Unix  compiler 
produces  syntax  errors  on  function 
declarations,  so  they  were  omitted. 

The  Microsoft  C  function  defini¬ 
tions  also  contain  the  reserved  word 
“near.”  Function  definitions  contain¬ 
ing  the  “near”  reserved  word  must 
be  duplicated.  Remove  the  “near”  re¬ 
served  word  from  the  duplicated  defi¬ 
nitions  to  support  VMS  and  Unix.  Sur¬ 
round  the  original  and  duplicate  defi¬ 
nitions  with  the  #if  MSDOS ,  #elseif 
and  #endif  structure  as  in  Listing  Five 
(page  86),  which  replaces  line  56  in 
RW-Listing  Two.  All  function  defini¬ 
tions  in  source  files  ending  in  ,c  should 
be  changed  in  this  way. 

Step  3:  Each  compiler  supplies  a  dif¬ 
ferent  set  of  include  files.  Where  the 
include  file  names  are  the  same,  the 
contents  most  often  differ.  The  lines 
in  Listing  Six  (page  86)  replace  lines 
5  through  9  in  RW-Listing  One  and 
the  lines  in  Listing  Seven  (page  86) 
replace  line  25  in  RW-Listing  Two  to 
make  the  necessary  include-file  modi¬ 
fications. 

Step  4:  A  few  library  functions  in  the 
MS-DOS  version  were  not  found  in 
either  of  the  VAX  C  libraries.  The 
strdup( )  function  must  be  added  to 
the  code  for  VMS  and  Unix  to  dupli¬ 
cate  the  functionality  of  the  missing 
library  function.  The  function  in  List¬ 
ing  Eight  (page  86)  should  be  in¬ 
serted  between  lines  824  and  825  in 
RW-Listing  Two. 

The  CP  report  header  contains  the 
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you  to  shrink  its  storage  requirements 
and  thus  allow  the  program  to  run  in 
less  memory.  This  allows  the  program 
to  be  launched  with  impunity  from 
within  editors,  TSRs,  Windows,  DESQ- 
view,  and  so  on. 

As  stated  in  the  code  comments,  this 
program  will  not  see  the  relationship 
between  functions  when  they  are  called 
indirectly  via  pointers  to  functions.  Also, 
functions  in  the  body  of  a  #define  will 
be  missed.  Code  in  both  #if  and  #else 
will  also  be  scanned,  possibly  noting 
more  function  calls  and  perhaps  even 
getting  out  of  sync  with  respect  to  open¬ 


ing  and  closing  braces.  This  may  be 
annoying  but  as  long  as  you  are  aware 
of  it,  I  don’t  think  it’s  too  serious.  If 
needed,  you  could  pass  the  source 
through  the  preprocessor  first  before 
processing  it  with  cp. 

The  code  now  catches  all  of  the  in¬ 
itial  comments  in  a  file.  I  am  not  sure 
what  it  did  in  the  original  code.  The 
temporary  buffer  for  it  is  3K.  Compile 
it  bigger  if  you  wish.  The  look-ahead 
buffer  that  scans  between  matching  pa¬ 
rentheses  in  a  function  declaration  or 
definition  is  the  manifest  constant 
c_line_length ,  which  is  set  to  512.  If 


you  are  even  more  verbose  in  your 
style  than  I  am,  you  may  want  to  make 
this  larger  (a  co-worker  of  mine  is,  so 
his  is  2048!).  The  called  function  array 
size  is  the  number  of  unique  functions 
per  function  definition  for  all  function 
definitions  in  the  program,  so  the  num¬ 
ber  of  function  calls  can  exceed  this 
number.  These  arrays  are  mallocd  so 
that  if  they  need  to  exceed  a  full  seg¬ 
ment,  one  only  has  to  change  the  mal- 
loc( Js  to  halloc( Os,  the  associated 
free( Os  to  hfree( Os,  and  then  the  really 
tedious  part,  chasing  all  associated 
global  and  local  variables  (usually  point- 


VMS  and  Unix 


current  date  and  time  that  is  pro¬ 
vided  by  the  MS-DOS  _strdate( )  and 
_strtime(  )  functions.  Although  not  in 
the  same  format,  this  information  is 
provided  by  the  time( )  and  local- 
time( 0  functions  in  VMS  and  Unix.  A 
new  function  was  created  for  VMS 
and  Unix  using  the  appropriate  li¬ 
brary  calls.  The  MS-DOS  code  was 
moved  into  a  function  body  and  re¬ 
placed  by  a  call  to  the  new  function. 
The  function  call  in  Listing  Nine  (page 
86)  replaces  lines  233  through  256  of 
RW-Listing  Two  and  the  functions  in 
Listing  Ten  (page  86)  should  be  in¬ 
serted  between  lines  210  and  211  in 
RW-Listing  Two. 

Step  5:  The  MS-DOS  and  VMS 
toloweri  )  library  function  returns  the 
lowercase  equivalent  of  an  uppercase 
character  or  the  same  character  if  it  is 
already  lowercase.  In  Unix  the  func¬ 
tion  works  the  same  if  the  character 
is  uppercase,  but  it  makes  a  lower¬ 
case  character  even  lower,  returning 
some  character  that  is  not  a  valid  com¬ 
mand-line  option.  Replace  line  93  in 
RW-Listing  Three  with  the  code  in 
Listing  Eleven  (page  88),  which  uses 
the  islower( )  function  to  check  the 
case  of  a  character  and  passes  the 
character  to  the  tolower( )  function 
only  if  it  is  uppercase. 

Step  6:  CP  directs  output  to  the  CRT 
by  specifying  that  the  outfile  be  “CON." 
On  PC/MS-DOS,  CON  is  a  reserved 
system  device  and  is  therefore  auto¬ 
matically  assigned.  On  VMS  and  Unix 
the  code  in  Listing  Twelve  (page  88) 
must  replace  line  850  in  RW-Listing 
Two  to  facilitate  this  option. 

Step  7:  The  Unix  C  compiler  detected 
an  error  that  neither  the  Microsoft  nor 


the  VMS  compiler  found.  Replace  line 
868  in  RW-Listing  Two  with  the  line 
in  Listing  Thirteen  to  remove  the  use 
of  a  variable  called  “errno”  that  was 
used  but  never  declared  and  could 
cause  a  run-time  error. 

Step  8:  Memory  size  limitations  are 
not  a  concern  on  the  virtual  machines 
for  the  requirements  of  the  C  printer. 
Replace  lines  95,  117,  140,  163,  188 
in  RW-Listing  Two  with  the  line  in 
Listing  Fourteen  (page  88)  to  use  the 
MS-DOS  constant  to  inhibit  CP’s  byte 
limit  errors  on  VMS  and  Unix. 

Compiling  and  Running  CP 

Step  1:  After  completing  the  steps 
required  to  modify  the  C  source  code, 
the  code  can  be  compiled  on  all  of 
the  supported  operating  systems  us¬ 
ing  the  make  utilities  and  files. 

Step  2:  CP  does  not  interpret  C  pre¬ 
processor  directives,  so  compile  the 
code  with  the  C  preprocessor  and 
then  run  CP  on  the  preprocessed  code. 
Listings  Fifteen  (page  88)  and  Sixteen 
(page  88)  contain  the  commands 
needed  to  run  the  C  preprocessor  on 
the  CP  source  files  on  VMS  and  Unix, 
respectively. 

Step  3:  The  cp.cpi  file  shown  in  List¬ 
ing  Seventeen  (page  88)  must  be  used 
as  the  list  file  to  ran  CP  on  the  prepro¬ 
cessed  source  code.  If  run  on  VMS 
or  Unix,  the  - n  option  should  be 
used  to  suppress  IBM-type  graphics 
characters  in  the  output. 

Enhancing  CP 

The  following  enhancements  to  the 
C  Printer  were  developed  to  support 
the  construction  of  design  documents 
for  software  created  by  The  Boeing 
Company. 


Step  1:  Path  names  can  be  very  long 
in  hierarchical  directory  structures,  so 
it  is  necessary  to  modify  CP  in  order 
that  it  will  accept  these  long  names 
in  its  list  file.  Insert  the  line  in  Listing 
Eighteen  (page  88)  between  lines  18 
and  19  of  RW-Listing  One  and  change 
the  value  of  the  LENJFILE  constant 
to  the  maximum  size  needed. 

The  rest  of  the  changes  needed  are 
made  by  replacing  line  262  of  RW- 
Listing  Two  with  the  code  in  Listing 
Nineteen  (page  88)  and  line  270  of 
RW-Listing  Two  with  the  code  in  List¬ 
ing  Twenty  (page  88). 

Step  2:  When  using  long  file  names, 
the  boxes  that  are  displayed  by  CP 
get  overrun.  The  b  option  has  been 
added  to  CP  to  allow  the  size  of  the 
box  to  be  varied  at  run  time.  See 
Listings  Twenty-One  through  Twenty- 
Nine  (pages  88  -  89)  for  the  code  and 
instructions  needed  to  implement  this 
option.  The  bounds-checking  values 
(Listings  Twenty-Eight  and  Twenty- 
Nine)  and  the  default  value  (Listing 
Twenty-Five)  can  be  changed  to  suit 
your  needs.  Listing  Twenty-Seven  will 
correct  two  errors  with  the  help  screen 
that  were  most  likely  inadvertently 
left  out  of  the  original  program.  Due 
to  lack  of  space,  the  details  of  the 
code  will  not  be  discussed.  If  you 
have  any  questions  about  this  option 
or  about  any  aspect  of  the  C  Printer 
write  me  at  the  address  given  at  the 
beginning  of  this  article. 

DDJ 

(Listings  begin  on  page  86.) 

Vote  for  your  favorite  feature/article. 

Circle  Reader  Service  No.  9. 
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ers  to  these  arrays)  and  changing  all 
their  definitions  to  huge,  such  as 
some_type  *  sorne_type_pointer  to 
some_type  huge  * some_type _p>ointer.  A 
large  model  recompile  is  all  that  is  re¬ 
quired.  This  is  all  Microsoft  C  5.x  spe¬ 
cific  talk,  though  I  assume  similar  con¬ 
structs  exist  in  other  Cs  on  the  IBM 
PC/XT/AT  platform.  I  would  expect 
these  huge  arrays  are  not  needed  until 
one  must  analyze  a  really  large  C  pro¬ 
gram,  perhaps  something  on  the  order 
of  1-2-3  release  3! 

The  Loose  Ends 

The  parser  still  worries  me.  It  catches 
all  the  stuff  I  have  thrown  at  it,  but 
because  I  am  still  not  sure  how  it 
works  (!),  I  feel  that  it  may  still  have 
some  black  holes.  I  can’t  follow  its 
execution  by  looking  at  it;  I  just  go  on 
faith.  The  next  version  will  probably 
return  a  space  for  any  white  space  char¬ 
acter.  That  is,  put  the  white  space  test¬ 
ing  into  get_to_next_possible_token( ). 
This  should  clean  up  build_the_data_ 
base/ )  a  little. 

I  would  like  to  contemplate  the  data 
structures  a  little  and  perhaps  come 
up  with  something  a  little  less  ugly 
than  what  exists  now,  especially  the 
structure  elements  that  mark  statics. 
There  must  be  a  neater  way  of  doing 


this.  You  may  want  to  add  yet  another 
input  toggle  to  plot  unused  functions. 
This  is  useful  in  a  C  program  that  uses 
pointers  to  functions.  You  may  not  be 
able  to  see  who  calls  the  function,  but 
you  can  plot  it  anyway. 

For  those  of  you  with  really  big  pro¬ 
grams,  you  could  go  to  halloc(  )  for  the 
arrays.  After  qualifying  the  declarations 
of  pointers  with  the  huge  attribute,  a 
large  model  recompile  is  all  that  is  re¬ 
quired  to  allow  arrays  larger  than  the 
64K  limit  imposed  by  malloc( ). 

Two  more  items  complete  the  wish 
list.  The  first  is  hooking  in  the  page 
linker  to  the  library  calls  in  doprintC  ) 
so  that  a  cross  reference  to  library  calls 
may  be  generated.  The  last  is  to  sort  the 
defined  functions  on  entry  rather  than 
at  the  end.  This  would  free  up  run-time 
dynamic  memory  and  would  not  cre¬ 
ate  a  significant  time  penalty;  in  fact,  it 
might  actually  speed  things  up! 

Late  Additions 

At  the  request  of  a  co-worker  (yes,  the 
same  one!)  the  input  buffer  for  the  input 
file  name  list  was  extended  from  20  bytes 
to  128  bytes.  Apparently  his  sources  were 
really  scattered  about  his  directory  tree, 
and  so  some  of  his  pathnames  were  quite 
long,  hence  the  change  to  the  buffer  size. 
A  small  change  was  also  made  to  allow 


an  optional  string  following  each  input 
file  pathname.  This  string  is  atoi  )d,  and 
if  it  is  not  0,  it  is  added  to  the  tree 
structure  defining  box  and  added  as  a 
column  in  the  sorted  function  list.  Its 
intended  usage  is  the  overlay  number  of 
the  function.  Overlays  are  the  trick  that 
allows  you  to  write  code  and  .exe  files 
that  may  wildly  exceed  640K  or  whatever 
your  memory  space  is.  This  is  yet  another 
argument  to  the  program,  its  default  is 
off.  The  reason  for  this  is  to  study  the 
program  flow  of  the  tree  diagram  to  check 
for  one  overlay,  calling  another  in  order 
to  prevent  thrashing  in  a  loop,  speeding 
up  execution  by  combining  them  into 
one  overlay  and  so  on. 

I  imagine  other  uses  could  be  put 
into  this  extra  information,  the  interpreta¬ 
tion  is  up  to  the  user.  The  same  (!) 
co-worker  also  asked  that  the  unused 
function  list  be  sorted  by  filename.  Yes, 
he  had  a  lot  of  them!  Because  the  sort¬ 
ing  routine  was  already  in  place  for  the 
used  functions,  it  was  simple  enough 
to  clone  it  into  the  unused  list  display 
function. 

Last  Words 

I  trust  that  more  C  wizards  will  pop  up 
and  carry  this  ball  a  little  further.  I  only 
carried  it  as  far  as  I  needed  for  my  pur¬ 
poses.  The  C  program  that  cp  is  now 
maintaining  is  over  4.2  million  bytes,  over 
117,000  lines,  198  files,  uses  993  defined 
functions  called  4600  times,  with  192  li¬ 
brary  functions  called  3118  times!  As  you 
can  imagine,  this  program  does  a  won¬ 
derful  job  at  wearing  out  printers!  Thanks 
to  Stewart  for  the  great  idea  and  for 
doing  all  the  initial  dirty  work. 

Availability 

All  source  code  is  available  on  a  single 
disk  and  online.  To  order  the  disk, 
send  $14.95  (Calif,  residents  add  sales 
tax)  to  Dr.  Dobb's Journal ,  501  Galves¬ 
ton  Dr.,  Redwood  City,  CA  94063,  or 
call  800-356-2002  (from  inside  Calif.) 
or  800-533-4372  (from  outside  Calif.). 
Please  specify  the  issue  number  and 
format  (MS-DOS,  Macintosh,  Kaypro). 
Source  code  is  also  available  online 
through  the  DDJ  Forum  on  Compu¬ 
Serve  (type  GO  DDJ).  The  DDJ  Listing 
Service  (603-882-1599)  supports  300/ 
1200/2400  baud,  8-data  bits,  no  parity, 
1-stop  bit.  Press  SPACEBAR  when  the 
system  answers,  type:  listings  (lower¬ 
case)  at  the  log-in  prompt. 

DDJ 


(Listings  begin  on  page  73-) 

Vote  for  your  favorite  feature/article. 
Circle  Reader  Service  No.  5. 


46  Dr.  Dobb  s  C  Sourcebook,  Winter  1989/90 

996 


C  List  Manager 

Lisp-like  lists  in  C 


Robert  F.  Starr 


List  management  buys  you  a  con¬ 
venient  way  to  create  randomly 
accessible  linked  lists  with  low- 
storage  overhead.  The  ability  to 
store  objects  of  any  type  gener¬ 
alizes  the  problem  of  list  management 
so  that  each  new  problem  doesn’t  find 
you  writing  virtually  the  same  code  over 
again  (to  handle  a  problem  only  mod¬ 
erately  different  from  the  previous  one). 

A  list  is  defined  as  a  collection  of 
information  of  the  same  type,  access¬ 
ible  in  either  sequential  or  random  or¬ 
der.  The  type  of  information  on  the  list 
can  be  anything,  but  within  a  given  list, 
the  type  must  be  consistent  (for  exam¬ 
ple,  all  int,  float,  struct,  pointers,  and 
so  on). 

Generally,  lists  are  represented  as  vec¬ 
tors  of  pointers  to  data.  Most  popular  is 
probably  the  linked  list,  where  each 
element  of  the  list  contains  a  pointer 
to  the  next  element  (a  regular  linked 
list),  and  possibly  a  pointer  to  the  pre¬ 
vious  element  (a  doubly  linked  list). 

In  a  language  such  as  C,  which  pro¬ 
vides  for  dynamic  memory  allocation, 
programmers  generally  opt  for  the 
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linked  list  approach  over  pointer  lists 
or  arrays  of  fixed  size.  This  allows  the 
list  to  consume  a  minimum  of  memory 
to  start  with,  and  presents  no  artificial 
upper  limit  on  the  length  of  the  list. 

Traditionally,  every  new  problem  car¬ 
ries  with  it  the  burden  of  defining  new 
data  structures  and  building  the  linked 
list  management  code  from  scratch.  This 
process  is  time-consuming,  not  to  men¬ 
tion  error-prone.  The  basic  tasks  re¬ 
quired  to  implement  a  linked  list  are: 

1 .  Describe  data  structure  for  the  linked 
list. 

2.  Write  code  to  add  an  element  to  the 
list.  This  involves  building  a  new 
data  structure,  populating  it,  and  link¬ 
ing  it  onto  the  list. 

3.  Free  all  memory  consumed  in  the 
linked  list. 

Wouldn’t  it  be  nice  if  linked  lists 
could  somehow  be  generalized,  so  that 
a  canned  package  would  easily  handle 
current  and  future  needs?  That’s  what 
I’m  presenting  in  this  article  —  a  gen¬ 
eral  list  management  system  written  in 
C  that  can  hold  any  type  of  objects, 
even  other  lists.  The  coding  was  done 
under  DOS  3-3  in  Microsoft  C  5.1,  and 
the  program  has  been  compiled  and 
run  with  no  modifications  on  Unix  Sys¬ 
tem  V,  VMS  4.7,  and  a  Sun  4/280.  The 
source  code  for  the  program  is  pre¬ 
sented  in  Listing  One,  page  90,  while 
the  header  file  is  listed  in  Listing  Two, 
page  91. 

One  thing  many  programmers  have 
discovered  is  that  although  the  general 
memory  allocation  routines  offered  with 
C  ( malloc ,  calloc,  and  so  on)  are  very 
nice,  they  can  be  terribly  inefficient  for 
many  problems.  This  is  especially  true 
when  the  memory  allocation  is  per¬ 
formed  in  several  small  chunks  (as  is 
often  the  case  when  building  linked 
lists):  Each  call  to  malloc  takes  time  (to 
find  the  requested  amount  of  memory) 
and  actually  consumes  more  memory 
than  you  requested  (for  bookkeeping 
overhead).  For  large  projects,  this  can 
get  so  bad  that  overall  performance  of 
the  application  suffers  greatly. 

I  have  seen  several  programs  gain 
substantial  speed  by  adding  a  higher- 
level  memory  allocation  routine.  If  the 
programmer  finds  himself  constantly 
calling  malloc  to  get  chunks  of  mem¬ 
ory  of  the  same  size,  he  can  call  this 
higher-level  function  to  get  memory 
from  the  memory  allocator  in  larger 
chunks  than  needed.  The  higher-level 
allocator  then  doles  out  the  space  in 
smaller  chunks  as  it  is  requested. 

This  limits  the  fragmentation  of  mem¬ 
ory,  and  adds  to  the  efficiency  of  the 
code.  But,  as  with  linked  list  imple¬ 


mentations,  the  code  to  handle  this 
must  be  written  especially  for  each  new 
application. 

The  list  management  system  de¬ 
scribed  here  gives  you  this  kind  of 
higher-level  memory  allocator.  To  test 
the  efficiency  of  the  program,  I  took 
code  that  made  many  calls  to  malloc 
and  replaced  it  with  this  list  manage¬ 
ment  system.  The  performance  of  the 
package  increased  by  a  factor  of  eight. 
You  will  realize  better  performance  than 
this  in  some  cases,  worse  in  others. 

Adding  NULL  as  the 
final  argument  is  an 
easy  solution  to 
simple  problems 

The  code  generalizes  the  list  man¬ 
agement  problem  in  such  a  way  that 
problems  of  this  kind  are  easily  han¬ 
dled.  If  building  and  managing  lists  is 
very  easy  to  do,  you  will  find  yourself 
using  them  in  ways  you  never  dreamed 
possible.  You  will  not  resist  building  a 
list  as  an  elegant  solution  to  a  problem 
merely  to  avoid  the  coding  complexity, 
or  due  to  project  time  constraints. 

I  will  first  discuss  the  list  manage¬ 
ment  package  from  the  subroutine  level 
and  then  show  you  how  it  can  be  used. 
There  will  be  enough  short  examples 
to  serve  as  an  easy  go-by  for  virtually 
any  project  you  can  imagine.  The  ex¬ 
amples  will  demonstrate  how  to  make 
and  maintain  lists  of  numbers,  strings, 
structures,  lists,  and  functions. 

The  Program  Interface 

A  whole  suite  of  subroutines  makes 
up  this  list  management  package.  They 
are  described  in  fairly  general  terms 
here. 

As  much  as  I  tried  to  make  the  list 
management  system  problem  indepen¬ 
dent,  there  is  one  small  facet  that  must 
be  considered  each  time  based  upon 
the  problem  at  hand. 

As  mentioned  earlier,  calling  malloc 
to  get  several  small  chunks  of  memory 
can  be  very  wasteful.  Because  avoid¬ 
ing  memory  fragmentation  was  one  of 
the  design  goals  for  this  project,  two 
items  of  information  are  required  to  set 
up  a  list: 

1.  The  size  of  each  entry  to  be  placed 
on  the  list. 

2.  The  number  of  entries  to  grab  at  a 
time  with  each  internal  call  to  mal¬ 
loc. 


The  choice  of  the  number  of  entries 
is  generally  problem  dependent,  and 
it  is  the  toughest  choice  you  will  have 
to  make.  Note  that  the  number  of  en¬ 
tries  presents  no  upper  bound  on  the 
size  of  the  list.  It  is  merely  used  for  the 
efficient  allocation  of  memory. 

A  list  is  created  using  makelist.  The 
return  value  is  a  void  pointer,  which  is 
passed  on  to  other  routines  in  the  pack¬ 
age.  Consider  the  return  value  from 
makelist  like  a  FILE  pointer.  You  needn’t 
be  concerned  with  what  it  points  to. 

After  a  list  has  been  created,  data  is 
put  onto  the  list  using  appendlist.  List 
data  always  gets  added  to  the  end  of 
the  list  in  this  implementation,  ap¬ 
pendlist  requires  two  arguments:  The 
list  pointer  to  which  the  data  is  being 
appended,  and  a  pointer  to  the  data  to 
be  put  on  the  list.  Because  appendlist 
expects  a  pointer  to  the  data  to  be  put 
on  the  list,  and  because  it  knows  the 
size  of  the  data  item  (you  provided 
that  in  the  call  to  makelist ),  it  performs 
a  copy  of  the  pointed-to  data  into  the 
internal  data  space  it  has  reserved. 

It  is  important  to  remember  that  the 
pointed-to  data  is  copied.  If  you  are 
putting  integers  onto  the  list,  the  inte¬ 
gers  themselves  will  be  copied.  There 
is  no  reason  for  the  data  being  put  on 
the  list  to  be  static,  in  this  case.  If  you 
are  appending  pointers  to  strings,  or 
pointers  to  structures,  these  pointers 
must  point  to  malloce d  or  static  data 
space,  if  you  expect  to  be  able  to  re¬ 
cover  the  data  from  the  list.  At  the  very 
least,  the  data  must  remain  static  through¬ 
out  the  life  of  the  list. 

You  might  think  that  having  to  have 
malloce d  data  space  to  put  on  a  list  is 
wasteful,  as  I  claim  that  this  package 
makes  memory  allocation  more  effi¬ 
cient.  In  reality,  the  package  is  a  list 
management  tool  that  manages  mem¬ 
ory  for  lists  much  more  efficiently  than 
you  could  do  with  malloc.  A  clever 
user  could  use  the  same  tool  for  getting 
data  space  for  his  string  storage  (if  that 
is  what  the  list  must  contain). 

Getting  data  off  the  list  is  easy.  You 
have  two  choices:  fetch  list  allows  you 
to  get  data  items  off  the  list  in  random 
order  (as  though  the  list  were  an  array). 
fetchlist  provides  array-bound  check¬ 
ing,  and  NULL  is  returned  if  your  indi¬ 
ces  go  outside  the  limits  of  the  list 
being  accessed. 

walklist  allows  you  to  walk  down 
the  list,  from  beginning  to  end,  without 
regard  for  list  indices,  walklist  expects 
you  to  traverse  the  entire  list.  If  you 
happen  to  find  what  you  are  looking 
for  before  walklist  is  done,  you  can  use 
rewindlist  to  reset  internal  pointers  so 
that  walklist  will  start  at  the  beginning 
on  the  next  call. 
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On  the  first  call,  walklist  always  starts 
reading  at  the  beginning  of  the  list.  It 
will  return  subsequent  entries  in  the 
list  until  the  end  of  the  list  is  seen  or  a 
call  is  made  to  rewindlist.  Calling  fetch- 
list  does  not  interfere  with  walklist  calls. 
When  walklist  gets  to  the  end  of  the 
list,  NULL  is  returned. 

What  walklist  and  fetchlist  return  are 
void  pointers  to  the  internal  data  space 
containing  your  data.  To  actually  get 
at  the  data  can  be  a  little  tricky.  For  this 
reason,  I  have  provided  examples  of 
storing  and  retrieving  many  different 
kinds  of  things  on  lists.  The  easiest 
thing  to  remember  is  this:  What  you 
get  back  is  a  pointer  to  a  data  area 
where  your  data  resides.  You  must  first 
cast  this  pointer  to  be  what  you  expect 
and,  in  general,  dereference  the  result. 

If  you  stored  integers,  for  example, 


the  pointer  returned  would  be  a  pointer 
to  an  integer.  Cast  it  as  such,  then  dere¬ 
ference  to  get  the  integer  value.  This  is 
demonstrated  in  Example  1 . 

If  you  stored  a  pointer  to  a  string,  the 
returned  value  is  a  pointer  to  a  pointer 
to  a  string.  This  is  demonstrated  in  Ex¬ 
ample  2.  If  you  wish  to  store  data  struc¬ 
tures  on  a  list,  what  you  get  back  will 
be  a  pointer  to  the  saved  data  structure. 
All  you  need  to  do  is  cast  the  returned 
pointer  —  you  needn't  dereference  it. 
That  is  because  the  data  pointer  re¬ 
turned  holds  the  actual  data  structure. 
This  is  demonstrated  in  Example  3- 

To  free  a  list  (return  all  memory  used 
by  the  list  to  free  store),  call  freelist, 
freelist  makes  no  assumptions  about 
the  data  you  have  saved  on  the  list.  If 
what  you  have  saved  is  pointers  to 
malloce d  data  space,  when  the  list  goes 


away,  so  do  your  pointers  to  the  mal- 
loce d  space.  In  this  case,  merely  use 
walklist  to  traverse  the  list,  freeing  each 
malloce d  pointer  as  you  go. 

malloclist  is  a  function  that  performs 
a  traditional  malloc,  with  the  malloce d 
data  address  automatically  added  onto 
a  list.  By  utilizing  this  function,  you  can 
easily  free  up  all  memory  malloce d 
during  a  particular  function  by  calling 
gclist.  This  is  different  from  freelist  in 
that  ail  data  in  the  list  is  assumed  to  be 
malloce d,  and  it  is  freed  before  the  list 
itself  is  freed.  Example  4  shows  how 
to  use  malloclist. 

pushlist  and  poplist  allow  you  to  eas¬ 
ily  use  a  list  as  a  stack,  toplist  allows 
you  to  examine  the  topmost  stack  item 
(the  last  entry  pushed  onto  the  stack). 
NULL  is  returned  if  the  list  is  empty. 
Using  these  functions  is  demonstrated 
in  Example  5. 

As  an  experiment,  I  added  Lisp-like 
property  manipulation  to  the  stack.  (Lisp 
allows  you  to  associate  a  property  with 
any  data  value.  In  Lisp,  a  property  has 
a  textual  name  and  a  value,  which  can 
be  anything.) 

In  my  implementation,  a  property  is 
like  an  environment  variable  in  DOS 
or  Unix,  where  there  is  a  name  and  an 
associated  value  (both  of  which  are 
strings).  For  property  lists,  each  prop¬ 
erty  is  associated  with  a  single  data 
item,  and  different  data  items  may  have 
the  same  property  name  with  different 
values.  There  is  no  conflict. 

When  data  is  put  onto  a  list  (using 
appendlist,  for  example),  a  pointer  is 
returned.  This  pointer  is  a  pointer  to  the 
actual  storage  location  for  the  data.  This 
pointer  is  used  to  associate  a  property 
with  a  data  item  (for  either  saving  or 
retrieving  property  information).  Many 
properties  may  be  associated  with  a 
single  data  item.  The  property  value 
may  be  passed  as  NULL.  Effectively, 
this  just  hangs  a  string  name  onto  the 
specified  data  item. 

To  append  data  onto  the  list  and 
associate  property  information  with  it 
simultaneously,  use  the  function  pap- 
pendlist.  In  its  most  common  usage, 
this  function  allows  you  to  hang  names 
on  data  values  as  they  are  put  on  the  list, 
which  can  be  a  very  powerful  feature. 

To  find  a  property  on  a  list,  use 
findprop.  This  function  will  find  the 
first  occurrence  of  a  property  with  the 
specified  name,  and  return  a  pointer 
to  the  data  to  which  that  property  has 
been  associated. 

Property  list  handling  is  not  done  as 
efficiently  as  it  could  be,  but  it  will  do 
for  small  applications.  Basic  property 
list  usage  is  demonstrated  in  Example 
6.  Property  list  usage  using  pappendlist 
is  shown  in  Example  7. 


♦ifdef  Explanation 


Make  a  list  to  hold  integers,  and  put  100  integers  onto  the  list. 
Then,  play  back  the  list. 


#endif 

♦include  <stdio.h> 

♦include  "makelist.h" 

main()  { 

void  *list,*dp; 
int  ii; 

/*  make  a  list  to  hold  integers  */ 
list  =  makelist (sizeof (int) , 10) ; 

/*  put  100  integers  on  list  */ 
for  (ii=0  ;  ii  <  100  ;  ii++) 
appendlist (list, Sii) ; 

/*  use  fetchlist  to  read  back  list  */ 
for  (ii=0  ;  ii  <  100  ;  ii++)  ( 

void  *dp  »  fetchlist (list, ii) ; 

printf ("Entry  %2d  •  %d\n”, ii, * (int  *)dp); 

) 

freelist (list) ; 

) 


Example  1:  A  list  of  integers 


♦ifdef  Explanation 


Demonstrates  the  putting  of  strings  on  a  list  and  use  of  gclist. 


♦endif 

♦include  <stdio.h> 

♦include  "makelist.h" 

extern  char  ‘strdupO; 

main()  ( 

char  buffer[132] ; 
void  ‘list, *dp, *ptr; 
int  ii; 
int  cnt; 

/*  make  list  to  hold  strings  */ 
list  =  makelist (sizeof (char  *),10); 

/*  build  the  list  of  strings  */ 
for  (ii=0  ;  ii  <  30  ;  ii++)  ( 

sprintf (buffer, "text  string  %d”,ii); 
dp  =  strdup (buffer) ; 
appendlist (list, sdp) ; 

/*  use  walklist  to  view  each  string  saved  in  list  */ 
while  (dp  =  walklist (list) ) 

printf ("%s\n”, *( (char  *‘)dp)); 

/*  free  up  list,  as  well  as  all  malloced  data  */ 
gclist (list)  ; 

) _ 

Example  2:  A  list  of  strings 
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Creative  List  Usage 

After  reviewing  a  few  of  the  examples, 
you  should  realize  that  the  list  manage¬ 
ment  package  is  easy  to  use.  The  big¬ 
gest  stumbling  block  is  remembering 
always  to  pass  pointers  for  information 
to  be  put  onto  the  list,  and  to  be  careful 
in  casting  and  dereferencing  the  items 
returned  off  the  list.  Once  you  get  the 
hang  of  this,  usage  is  a  snap. 

The  simplest  use  for  lists  is  for  saving 
data  in  malloced  data  space  much  more 
efficiently  than  malloc  alone  can  do. 
Speed-ups  of  a  factor  of  eight  of  this 
package  over  malloc  are  fairly  typical. 

An  interesting  use  of  stacks  is  to  in¬ 
itialize  a  list  of  lists.  Build  a  list  to  hold 
your  data,  and  then  push  the  list  onto 
the  list  of  lists  to  save  context.  This  is 
useful  in  recursive  contexts,  where  a 
lot  of  dynamic  information  must  be 
saved  during  recursion.  An  example 
of  how  a  list  of  lists  can  be  built  and 
manipulated  is  shown  in  Example  8. 

One  utility  for  property  lists  is  build¬ 
ing  a  list  that  contains  a  variety  of  dif¬ 
ferent  pointers  (pointers  to  different 
things).  This  does  not  violate  our  defi¬ 
nition  of  a  list:  Even  though  the  point¬ 
ers  point  to  different  things,  the  list  is 
still  merely  a  list  of  pointers.  You  can 
use  the  property  tag  to  tell  what  type 
of  pointer  each  list  item  is  within  the 
function  that  must  interpret  the  list. 

Real-World  List  Usage 

As  far  as  I  am  concerned,  two  types  of 
functions  are  developed  during  any  pro¬ 
gramming  project.  They  are: 

1.  Throw-away  routines,  written  to 
make  your  code  cleaner  and  easier 
to  understand. 

2.  Routines  that  are  well  thought-out 
and  have  usefulness  beyond  the 
scope  of  the  current  project  (here,  I 
invoke  the  buzzword  “reusable”). 

Functions  of  the  second  type  will  make 
life  easier  for  you  down  the  road.  They 
will  provide  you  with  a  new  set  of  tools 
for  future  development,  and  they  have 
already  been  tested  and  debugged. 

The  real  world  can  often  be  quite 
different,  though.  Most  programmers 
have  been  at  the  following  design  cross¬ 
road.  You  have  a  project  that  you  need 
to  get  working  and  time  is  running  out. 
Meeting  project  deadlines  can  often  im¬ 
pair  your  ability  to  dedicate  the  time 
required  to  generalize  functions  to  the 
point  that  they  are  useful  outside  the 
scope  of  the  current  project. 

A  good  programmer  can  easily  tell 
what  functionality  lends  itself  to  being 
made  into  a  subroutine.  He  sees  and 
anticipates  the  need  for  the  special  cod¬ 
ing  before  he  actually  begins  writing  it. 


He  will  often  ponder  a  few  minutes, 
deciding  what  arguments  need  to  be 
provided  with  the  subroutine,  and  what 
the  subroutine  can  return  that  will  be 
most  useful. 


He  will  try  to  arrange  the  calling 
arguments  in  a  reasonably  logical  fash¬ 
ion,  so  that  it  will  be  easy  to  remember 
how  to  call  the  function  (without  hav¬ 
ing  to  scrape  around  for  the  documen- 


#ifdef  Explanation 


Saving  and  retrieving  structures  on  lists. 


#endif 

♦include  <stdio.h> 

♦include  "makelist .h" 
extern  char  *strdup(); 

/*  here  is  our  data  structure  */ 
struct  foo  { 

char  *name; 
int  ndx; 

}  foo; 

main()  { 

void  *list; 
void  *vp; 
struct  foo  *fp; 
int  ii,jj,kk; 
char  buffer [256]; 

/*  make  list  to  hold  struct  foo  */ 
list  =  makelist (sizeof (struct  foo), 10); 

/*  build  list  of  30  instances  of  struct  foo  */ 
for  (ii=0  ;  ii  <  30  ;  ii++)  { 

sprintf (buffer, "foo  element  %d",ii); 
foo. name  =  strdup (buffer) ; 
foo. ndx  =  ii; 
appendlist (list, &foo) ; 

} 

/*  play  back  list,  note  that  vp  is  merely  cast  */ 
while  (vp=walklist (list) )  { 

fp  =  (struct  foo  *)vp; 

print f ("%2d)  %s\n", fp->ndx, fp->name) ; 

} 

/*  free  up  each  string  malloced  during  list  creation  */ 
while  (vp=walklist (list) )  ( 

fp  =  (struct  foo  *)vp; 
free (fp->name) ; 

} 

/*  free  the  list  itself  */ 
freelist (list) ; 

} 


Example  3:  A  list  of  structures 


#ifdef  Explanation 


We  use  malloclist  to  get  memory  space,  rather  than  malloc.  This  will 
automatically  append  malloced  data  onto  a  list  (which  you  must  provide), 
so  that  a  single  call  to  gclist  will  free  not  only  the  list,  but  all 
malloced  space  as  well. 


♦endif 

♦include  <stdio.h> 

♦include  "makelist .h" 

main()  { 

void  *list, *dp, *ptr; 

print f ("Exercising  malloclist. . . \n") ; 
list  =  makelist (sizeof (void  *),10); 

ptr  =  "string  ♦!"; 

dp  =  malloclist (list, strlen (ptr) +1) ; 
strcpy (dp, ptr) ; 
ptr  =  "string  ^2"; 

dp  =  malloclist (list, strlen (ptr) +1) ; 
strcpy (dp, ptr) ; 
ptr  =  "string  ♦ 3 "; 

dp  =  malloclist (list, strlen (ptr) +1) ; 
strcpy (dp, ptr) ; 

/*  play  back  list  */ 
while  (dp  =  walklist (list) ) 

printf ("%s\n", * (char  **)dp); 
/*  free  up  the  list  */ 
gclist (list) ; 


Example  4:  Using  malloclist  (  ) 
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C  LIST  MANAGER 


#ifdef  Explanation 


Demonstrate  how  to  push  &  pop  data  off  of  a  list. 


#endif 

♦include  <stdio.h> 

♦include  "makelist. h" 

main()  { 

void  *list, *dp, *ptr; 
int  ii,jj,kk; 
int  cnt; 

/*  build  list  to  hold  integers  */ 
list  *  makelist (sizeof (int) ,5) ; 

/*  push  10  integers  onto  list  */ 
for  (ii=0  ;  ii  <  10  ;  ii++) 

pushlist (list, &ii) ; 

/*  walk  down  list  10  times,  popping  an  entry  each  time  */ 
for  (ii=0  ;  ii  <  10  ;  ii++)  { 

extern  void  *toplist(); 
while  (dp  =  walklist (list) ) 
printf ("%d\n", * (int  *)dp); 
dp  *  toplist (list) ; 

printf ("popping  off  %d\n",*(int  *)dp); 
poplist (list) ; 

} 

/*  list  is  now  empty  */ 

printf ("pushing  onto  list  again\n"); 

for  (ii*0  ;  ii  <  10  ;  ii++) 

pushlist  (list, &ii) ; 

/*  verify  entire  list  */ 
while  (dp  =  walklist (list) ) 

printf ("%d\n", * (int  *)dp); 

/*  pop  off  an  item  at  a  time  off  list  */ 
for  (ii=0  ;  ii  <  10  ;  ii++)  { 

extern  void  *toplist(); 
dp  =  toplist (list) ; 

printf ("popping  off  %d\n",*(int  *)dp); 
poplist (list) ; 

} 

/*  ensure  list  is  indeed  empty  */ 

printf ("walking  list  again...  should  be  empty\n"); 

while  (dp  =  walklist (list) ) 

printf ("%d\n", * (int  *)dp); 
freelist (list) ; 

) 


Example  5:  Pushing  and  popping  a  list 


#ifdef  Explanation 


Put  100  integers  on  a  list.  Every  5th  element  on  the  list,  add  a 
special  property  value. 


♦endif 

♦include  <stdio.h> 
♦include  "makelist. h" 


extern  char  *strdup(); 
main()  { 

void  *list, *dp, *ptr; 
int  jj; 
int  cnt ; 

void  *nl  =  makelist (sizeof (int) , 20) ; 


} 


for  ( jj=0  ;  jj  <  100  ;  jj++)  ( 

void  *dp  =  appendlist (nl, & j j) ; 

/*  every  5th  element,  put  something  on  property  list 
if  <!  <  j j%5) )  { 

char  buffer [80]; 
sprint f (buffer, "list [%d] ",  j j) ; 
putproplist (nl, dp, "MSG", strdup (buffer) ) ; 


} 


} 


for  ( j j=0  ;  jj  <  100  ;  jj++)  { 

void  *dp  =  fetchlist (nl, j j) ; 
char  *ptr; 

printf ("%d\n", * (int  *)dp); 
if  { !  ( j j%5) )  { 


void  *p  =  (jj)  ?  dp  :  (void  *)NULL; 
printf ("PROP:  %s\n",ptr  =  getproplist 
.  .  „  .  (nl,p, "MSG") ) ; 

free  (ptr) ; 


} 


) 

freelist (nl) ; 


*/ 


Example  6:  Property  list  usage 


tation).  He  tries  to  give  the  function  a 
name  that  conveys  the  functionality, 
so  that  the  subsequent  coding  which 
uses  the  subroutine  will  be  easy  to  use, 
maintain,  read,  and  understand. 

As  every  experienced  programmer 
knows,  one  of  the  best  things  that  can 
come  out  of  any  programming  project 
is  a  collection  of  useful  subroutines 
that  can  be  used  in  other  projects  down 
the  road.  But  have  you  provided  the 
generality  necessary  to  make  such  a 
routine  truly  useful  in  a  lot  of  different 
environments? 

In  some  applications,  it  is  often  clear 
that  what  you  have  written  will  suffice 
for  all  applications  one  could  envision. 
Standard  library  routines  like  strlen  and 
strcat  are  good  examples.  Routines  like 
sprint 'f  are  less  clear.  There  is  a  reason¬ 
ably  good  case  to  be  made  supporting 
the  idea  that  what  sprint/ should  return 
is  a  pointer  to  the  string  that  it  built, 
rather  than  the  number  of  characters 
written.  But  it  doesn't.  You  can  do  little 
about  standard  library  routines. 

But  what  about  the  examples  where 
the  task  is  not  so  clear-cut?  Given  the 
time  constraints  for  a  project,  you  may 
not  be  able  to  devote  the  time  neces¬ 
sary  to  envision  all  of  the  possibilities, 
and  code  an  appropriate  solution. 

Often,  it  will  occur  to  you  that  there 
are  features  you’d  like  to  add  to  your 
new  function,  but  time  constraints  and 
satisfying  the  project  goals  limit  your 
creativity.  You  know  what  has  to  be 
done  now,  and  realize  the  potential  of 
this  routine  in  future  applications. 

Often  the  need  arises  to  add  extensi¬ 
bility  to  a  function  in  a  simple,  straight¬ 
forward  manner,  with  no  impact  on 
existing  code.  This  is  a  tough  problem. 

A  good  example  is  a  menu  function, 
wherein  the  user  is  presented  a  list  of 
options  on  the  screen.  The  topmost 
entry  is  highlighted.  The  user  moves 
the  cursor  over  the  item  of  choice  with 
the  arrow  keys  on  his  keyboard.  When 
the  highlighted  bar  is  over  the  appro¬ 
priate  menu  item,  he  hits  Enter. 

Should  the  menu  routine  handle  lists 
that  are  longer  than  the  box  on  the 
screen?  That  requires  extra  code  and 
extra  time  to  write.  Would  you  like  to 
let  the  user  leap  to  a  menu  entry  by 
merely  hitting  the  first  character  of  the 
menu  item?  More  code.  Allow  the  user 
to  fill  in  responses  to  certain  menu  items? 
Allow  him  to  sort  the  menu  a  variety 
of  ways?  And  on  and  on.  More  code. 

How  can  you  generalize  the  implemen¬ 
tation  so  that  gobs  of  code  don’t  have 
to  be  replicated  to  handle  future  situ¬ 
ations,  while  at  the  same  time  meeting 
your  goal  for  getting  your  project  out 
the  door  on  time?  Assume  that  you 
realize  that  a  function  you  are  coding 
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will  be  expanded  or  enhanced  at  a 
later  date.  Merely  add  a  void  pointer 
as  the  last  argument  of  the  function 
call.  In  current  usage  (until  you  get  the 
appropriate  code  written),  merely  pass 
a  (void*)  NULL  as  the  final  argument. 
You  can  even  put  out  documentation, 
telling  people  that  the  final  argument 
is  required  but  is  reserved  for  future 
expansion.  You  needn’t  tell  them  any¬ 
thing  else  at  this  point. 

What  could  be  better  than  a  generic 
list  to  add  as  the  final  argument?  Your 
code  can  always  check  for  NULL  as  the 
last  argument  and  take  the  appropriate 
default  action.  If  the  pointer  is  non- 
NULL,  consider  it  a  list,  and  interpret 
is  as  such. 

This  allows  adding  virtually  endless 
expansion  opportunities  to  a  function 
without  having  to  change  a  single  line 
of  existing  code.  And  because  you  have 
used  this  list  management  package,  the 
user  isn’t  burdened  with  having  to  write 
any  complicated  code.  His  job  is  eas¬ 
ier,  maintenance  headaches  are  less¬ 
ened,  and  you  can  release  a  half-fin¬ 
ished  project  before  its  time! 

This  approach  is  vastly  different  from 
the  exec  functions  approach  of  merely 
passing  a  list  of  strings  as  arguments, 
representing  argv  to  a  function,  where 
the  last  argument  is  a  NULL  pointer. 
Adding  NULL  as  the  final  argument  is 
an  easy  solution  to  simple  problems. 
When  the  variety  of  information  re¬ 
quired  to  be  passed  to  the  function  is 
more  than  simple  strings,  the  problem 
becomes  much  more  difficult. 

In  the  menu  example  just  mentioned, 
you  might  want  to  add  arguments  at  a 
later  date  having  to  do  with  the  menu- 
placement  coordinates,  how  long  the 
menu  is  allowed  to  be,  the  maximum 
width  of  the  window,  the  functions  to 
call  when  various  keys  are  hit,  and  a 
slew  of  other  parameters  that  can 
change  how  the  menu  works. 

This  is  where  a  generic  list  would 
prove  useful  as  the  last  argument  of  the 
subroutine  calling  sequence.  A  sugges¬ 
tion  would  be  to  create  a  list  of  void 
pointers  (that  is,  pointers  to  anything). 
As  an  item  is  put  on  the  list,  give  it  a 
special  property  name  with  no  prop¬ 
erty  value.  This  tells  the  function  what 
the  item  is.  To  facilitate  this  operation, 
use  the  pappendlist  function. 

In  your  application  function  which 
must  deal  with  the  list,  you  can  easily 
search  the  list  for  a  data  item  with 
a  particular  property  name  by  calling 
findprop. 

Another  approach  to  adding  extensi¬ 
bility  to  a  function  can  be  gotten  by 
adding  another  suite  of  functions,  which 
I’ll  call  “preparatory  functions.”  Prepara¬ 
tory  functions  are  used  to  “set  things 


up”  in  preparation  for  a  call  to  the 
function  you  are  actually  interested  in. 
You  write  each  function  to  set  certain 
internal  static  variables  so  that  when 


your  actual  function  of  interest  is  called, 
the  function  performs  to  the  user’s  speci¬ 
fications.  This  is  not  a  new  trick,  al¬ 
though  naming  the  preparatory  func- 


#ifdef  Explanation 


Make  a  list  to  hold  integers,  and  put  100  integers  onto  the  list. 
Then,  play  back  the  list.  For  each  integer  put  on  the  list,  add 
a  property  value  which  uniquely  identifies  the  data  value. 


#endif 

♦include  <stdio.h> 

♦include  "makelist. h" 

extern  char  *strdup(); 

main ( )  { 

void  *list,*dp; 
char  *ptr, buffer [80}; 
int  ii; 

list  =  makelist (sizeof (int) , 10) ; 

/*  put  100  integers  on  list,  w/  prop  to  tell  their  index  in  ASCII  */ 
for  (ii=0  ;  ii  <  100  ;  ii++)  { 

sprintf (buffer, "index  %d",ii); 
pappendlist (list, &ii, "OP", strdup (buffer) ) ; 

) 

/*  get  each  integer  off  list,  and  show  its  property  */ 
for  (ii*0  ;  ii  <  100  ;  ii++)  { 

void  *dp  «  fetchlist (list,ii) ; 
ptr  =  getproplist (list, dp, "OP") ; 

printf ("Entry  %2d  =  %d,  prop  =  %s\n", ii, * (int  *)dp,ptr); 
free (ptr) ; 

} 

freelist (list) ; 


Example  7:  Property  list  usage  w/pappendlist 


♦ifdef  Explanation 


Build  and  populate  a  list  of  lists 


♦endif 

♦include  <stdio.h> 

♦include  "makelist. h" 

main()  { 

void  *listlist; 
int  ii,jj,kk; 

/*  create  a  list  of  lists  */ 
listlist  =  makelist (sizeof (void  *),10); 

/*  build  10  lists  to  hold  integers  */ 
for  (ii=0  ;  ii  <  10  ;  ii++)  ( 

void  *vp  =  makelist (sizeof (int) , 10) ; 
appendlist (listlist, &vp) ; 

} 

/*  populate  each  of  the  10  lists  */ 
for  (ii=0  ;  ii  <  10  ;  ii++)  { 

void  *list  =  *(void  **) fetchlist (listlist, ii) ; 
for  (jj=0  ?  jj  <  20  ;  jj++)  { 
kk  =  ii*100  +  jj; 
appendlist (list, &kk) ; 

} 

} 

/*  replay  each  of  the  10  lists  */ 
for  (ii=0  ;  ii  <  10  ;  ii++)  { 

void  *list  =  * (void  **) fetchlist (listlist, ii) ; 
for  ( j  j=0  ;  jj  <  20  ;  jj++) 

printf ("List  %d,  data  =  %d\n", ii, * (int  *) fetchlist 

(list, j j) ) ; 

} 

/*  free  all  lists  */ 

for  (ii=0  ;  ii  <  10  ,*  ii++)  { 

void  *list  =  Mvoid  **) fetchlist (listlist, ii); 
freelist (list) ; 

} 

freelist (listlist) ; 

}  - 


Example  8:  A  list  of  lists 
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tions  can  be  rather  ugly. 

If  preparatory  functions  are  your 
choice  for  expandability  of  a  given  func¬ 
tion,  they  can  easily  be  handled  by 
creating  a  list  of  functions.  In  Example 
9, 1  show  a  function  called  proc.  I  have 
created  an  auxiliary  function  called 
fproc.  The  application  calls  f_proc  to 
get  a  list  of  the  functions  that  are  appli- 


Example  9:  A  list  of  functions 


cable  to  proc.  f_proc  builds  a  list,  and 
puts  the  address  of  several  functions 
on  the  list.  It  then  returns  a  pointer  to 
this  list. 

Each  of  the  functions  (foo ,  goo,  and 
poo )  declared  static  inside  Example  9. 
This  is  not  a  requirement;  it  just  makes 
for  a  cleaner  interface. 

Note  that  each  of  the  three  functions 


expects  a  variable  length  argument  list, 
so  varargs  is  used  to  get  each  argu¬ 
ment.  This  is  required  because  the  user 
interface  to  these  functions  is  made 
available  indirectly  through  funclist. 
When  funclist  actually  calls  the  func¬ 
tion,  it  passes  a  pointer  to  the  stack 
location  of  the  argument  list.  If  you 
aren’t  familiar  with  the  varargs  inter¬ 
face,  the  three  provided  functions 
should  give  you  sufficient  examples  of 
its  proper  usage. 

In  the  main  routine  in  Example  9, 
you  will  see  an  example  of  how  the 
user  would  access  the  extended  func¬ 
tionality  of  the  proc  function.  As  seen 
in  f_proc,  the  functions  have  been  given 
a  property  tag  which  mnemonically  in¬ 
dicates  what  the  functions  are.  This 
makes  for  a  cleaner,  easier  to  under¬ 
stand  interface  for  the  user. 

There  is  one  caveat  in  providing  an 
enhanced  interface  like  this.  If  the  func¬ 
tion  proc  was  initially  designed  to  run 
without  arguments  (as  in  our  exam¬ 
ple),  be  sure  that  it  takes  the  default 
action  as  initially  documented.  If  call¬ 
ing  any  of  the  preparatory  functions 
will  permanently  modify  the  behavior 
of  proc,  be  sure  to  tell  the  user  about  it. 
But  by  keeping  the  behavior  predict¬ 
able  upon  default,  you  will  not  need 
to  recompile  or  relink  any  existing  code 
to  add  functionality  at  a  later  date. 

Summary 

General  list  management  is  a  useful 
addition  to  your  arsenal  of  program¬ 
ming  tools.  Once  you  become  adept 
at  using  the  tools  in  this  package,  you 
will  find  yourself  building  and  using 
lists  in  ways  you  never  thought  of.  The 
best  way  to  understand  the  package  is 
to  review  the  many  examples. 

Availability 

All  source  code  is  available  on  a  single 
disk  and  online.  To  order  the  disk, 
send  $14.95  (Calif,  residents  add  sales 
tax)  to  Dr.  Dobb's Journal,  501  Galves¬ 
ton  Dr.,  Redwood  City,  CA  94063,  or 
call  800-356-2002  (from  inside  Calif.) 
or  800-533-4372  (from  outside  Calif.). 
Please  specify  the  issue  number  and 
format  (MS-DOS,  Macintosh,  Kaypro). 
Source  code  is  also  available  online 
through  the  DDJ  Forum  on  Compu¬ 
Serve  (type  GO  DDJ).  The  DDJ  Listing 
Service  (603-882-1599)  supports  300/ 
1200/2400  baud,  8-data  bits,  no  parity, 
1-stop  bit.  Press  SPACEBAR  when  the 
system  answers,  type:  listings  (lower¬ 
case)  at  the  log-in  prompt. 

DDJ 

(Listings  begin  on  page  90.) 

Vote  tor  your  favorite  feature/article. 

Circle  Reader  Service  No.  6. 


#ifdef  Explanation 


Demonstrate  how  to  use  build  a  list  of  functions  and  call  them 
directly  off  of  the  list,  with  arguments. 


#endif 

♦include  <stdio.h> 

♦include  <varargs.h> 

♦include  "makelist. h" 

/*  This  function  expects  integer  arguments,  zero  terminated  */ 
static 
foo (argmark) 
va__list  argmark;  { 
int  i; 
while  (1)  { 

i  *  va_arg (argmark, int) ; 
if  (!i)  break; 
printf ("%d\n", i) ; 

) 

} 

/*  This  function  expects  string  arguments,  NULL  terminated  */ 
static 
goo (argmark) 
va_list  argmark;  { 
char  *ptr; 
while  (1)  { 

ptr  =  va_arg( argmark, char  *); 
if  (!ptr)  break; 
printf ("%s\n", ptr) ; 

} 

} 

/*  This  function  expects  a  string,  followed  by  an  integer  */ 
static 
poo (argmark) 
va_list  argmark;  { 
char  *ptr; 
int  i ; 

ptr  =  va_arg (argmark, char  *); 

i  *  va_arg (argmark, int) ; 

printf ("string  =  %s,  int  =  %d\n",ptr,i) ; 


/*  build  list  for  functions  internal  to  proc,  and  return  pointer  to  list  */ 
static  void  *flist  =  NULL; 
void  * 
f _proc ( )  { 

int  (*func)(); 

if  (! flist)  flist  =  makelist (sizeof (int  (*)()), 10); 

/*  put  functions  on  flist,  and  give  'em  names  */ 
func  =  foo;  pappendlist  (flist,  Stfunc,  "FOO", NULL) ; 
func  =  goo;  pappendlist (flist, &func, "GOO", NULL) ; 
func  =  poo;  pappendlist (flist, &func, "POO", NULL) ; 
return  flist; 

} 

/*  our  proc  function  */ 

void 

proc()  { 

printf ("In  function  proc\n"); 

> 

main()  ( 

void  *l_proc; 

/*  get  list  of  proc's  functions  */ 
ljproc  =  f  jproc ( ) ; 

/*  invoke  each  of  the  functions  with  arguments  */ 
funclist (l_proc, "FOO", 1, 2,  3,4, 0) ; 

funclist (l_proc, "GOO", "line  1",  "line  2",  "line  3",  NULL); 
funclist (ljproc, "POO", "some  text",  666); 

/*  finally,  call  proc  */ 
proc ( ) ; 

} 
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Debugging  C 
Programs 

Don’t  forget  assert( )  and  the  stack 


Bob  Edgar 


Testing  and  debugging  are  prob¬ 
ably  the  most  time-consuming 
and  neglected  aspects  of  the 
programmer’s  trade,  and  we  pro¬ 
grammers  need  all  the  help  we 
can  get  to  figure  out  what  our  pro¬ 
grams  are  really  doing,  as  opposed  to 
what  we  think  they  should  be  doing. 

The  well-known  assert( )  macro  can 
be  extended  in  a  number  of  ways  as  a 
useful  debugging  tool.  The  basic  idea 
is  to  have  a  statement  that  checks  for 
an  illegal  condition  in  the  program;  the 
statement  can  be  completely  “deacti¬ 
vated”  by  defining  the  NDEBUG  macro, 
presumably  in  the  compiler  command 
line.  A  simple  version  is  in  Example  1. 
Or,  if  a  function  do_str( )  takes  a  single 
string  argument,  which  must  never  be 
NULL,  you  might  use  the  assertion 
shown  in  Example  2.  (Notice  that  a 
semicolon  is  not  required :  The  assert 
macro  defines  a  complete  statement.) 
The  definition  in  Example  1  assumes 
that  the  C  macro  processor  will  substi¬ 
tute  cond  in  the  string  argument  to 
print/,  with  the  condition  given  as  an 
argument  to  assert •  different  implemen¬ 
tations  of  the  macro  processor  differ 
on  their  rules  for  argument  substitution 
inside  strings,  and  you  should  check 


Bob  is  an  experienced  C  programmer 
from  Britain  and  can  be  reached 
through  the  DDJ  office. 
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the  documentation  for  your  compiler. 
ANSI  C  has  defined  new  operators  (#, 
##')  for  strings  in  macros,  which  would 
be  the  preferred  solution.  The  first  im¬ 
provement  is  to  make  an  arbitrary 
printf/ )  call  if  a  given  condition  was 
(or  was  not)  satisfied.  The  problem  is 
that  the  macro  processor  does  not  al¬ 
low  macros  with  a  variable  number  of 
arguments.  The  solution  is  to  use  pa¬ 
rentheses,  so  that  the  entire  argument 
list  to  print/ is  a  single  argument  to  the 
macro,  as  shown  in  Example  3.  (In  this 
and  the  following  macro  definitions,  it 
is  assumed  that  the  macro  is  defined 
to  be  empty  when  NDEBUG  is  turned 
on.)  A  typical  use  of  this  technique  is 
shown  in  Example  4. 

In  a  major,  complicated  program  it 
is  often  an  advantage  when  analyzing 
problems  to  have  statements  that  print 
out  critical  variables  and  data  struc¬ 
tures  when  required,  but  are  normally 
suppressed  so  that  the  output  from  the 
program  is  not  cluttered  with  a  lot  of 
irrelevant  information.  You  can  extend 
the  idea  of  the  assert  macro  to  provide 
a  convenient  mechanism  for  making 
such  output. 

I  introduce  the  idea  of  a  “trace  level,” 
which  determines  how  much  debug¬ 
ging  output  is  produced.  Permissible 
values  might  range  from  0,  meaning 
that  no  debugging  output  is  printed, 
to  9,  the  maximum  amount  of  output. 
A  macro  that  unconditionally  prints 
when  the  trace  level  is  high  enough  is 
shown  in  Example  5. 

An  external  integer  tlevel  should  be 
visible  and  should  contain  the  trace 
level.  The  macro  in  Example  6  prints 
the  values  of  i  and  j  when  the  value  of 
tlevel  is  two  or  more.  A  convenient  way 
of  setting  tlevel  is  to  provide  a  com¬ 
mand  line  argument  to  the  executable 
program,  such  as  Ln  where  n  is  a  digit 
from  0  to  9. 

To  avoid  having  to  check  for  this 
command-line  argument  in  all  programs 
using  these  macros,  write  a  standard 
version  of  main( )  that  checks  for  the 
argument,  performs  any  other  initiali¬ 
zations  required  by  your  libraries,  and 
calls  the  user’s  main ,  which  has  (trans¬ 
parently  to  the  user)  been  renamed. 
Your  version  of  the  assert. h  header  file 
could  include  code  similar  to  that  shown 
in  Example  7. 

The  standard  version  of  main( ) 
would  be  in  a  library  file,  which  would 
then  only  be  included  at  link  time  if  the 
user’s  version  of  main(  )  had  been  com¬ 
piled  without  NDEBUG.  An  elegant  so¬ 
lution  would  remove  the  -L  command¬ 
line  option  from  the  argument  list  so 
that  the  user  program  need  not  check 
for  it.  An  example  of  this  can  be  seen 
in  Listing  One,  page  93. 


A  trace  level  alone  is  probably  too  tbits  bits,  which  must  be  set  for  the 

crude  for  controlling  debugging  out-  information  to  be  printed.  This  will  be 

put  from  a  large  program;  to  improve  a  bit-wise  OR  of  one  or  more  of  the  bits 

it,  you  could  identify  major  program  that  the  user  assigns  to  parts  of  the 

modules  and  data  structures  that  might  program,  as  shown  in  Example  9.  A 

be  traced,  and  provide,  in  addition  to  general  macro,  say  assertbl,  would  in- 

tlevel,  an  integer  considered  as  a  bit  elude  both  bits  and  level  arguments, 

vector,  tbits.  A  module  or  data  structure  The  -L  command  line  argument  could 

in  the  program  is  assigned  a  bit  in  tbits-,  be  extended  to  the  form  -Lnxxxx,  where 

if  the  bit  is  set,  output  related  to  that  n  is  the  trace  level  and  xxxx  is  four  hex 

module  or  data  is  printed.  Imagine,  for  digits  specifying  the  bits  to  set  in  tbits. 

example,  a  compiler.  You  might  define  Putting  all  these  ideas  together  pro- 
the  bits  as  shown  in  Example  8.  vides  an  easy-to-use  package  for  the 

You  can  now  define  assert- like  mac-  programmer  to  add  selective  debug- 
ros  with  a  new  argument  to  specify  the  ging  print  (or  other)  statements  into 


♦ifndef  NDEBUG 

♦define  assert (cond)  (if 

( ! (cond) )  \ 

printf ("ASSERT  cond, 

file  %s  line  %d\n",  \ 

FILE  ,  LINE  ); 

exit (1) ; ) 

♦else 

♦define  assert (cond)  {;) 

/*  Empty  block  */ 

♦endif 

Example  1:  Defining  the  NDEBUG  macro 


Example  2:  Using  an  assertion 


♦define  assertp(cond,  args)  (if  < ! ( cond) )  \ 
printf ("ASSERT  cond,  file  %s,  line  %d\n",  \ 

_ FILE _ ,  _ LINE _ );  \ 

printf  args;  exit(l);} 


Example  3:  Using  parentheses  so  that  the  entire  argument  list  to  printf  is  a 
single  argument 


Example  4:  A  typical  use  of  assert 


♦define  assertl (level,  args) 

(if  (tlevel  >=  (level))  \ 

printf ("file  %s,  line  %d\n" 

\ 

FILE  ,  LINE  );  \ 

printf  args;  exit(l);) 

Example  5:  A  macro  that  unconditionally  prints  when  the  trace  level  is  high 
enough 


Example  6:  A  typical  use  of  Example  5 


Example  7:  An  assert. h  header  file 


♦define  TBIT_LEXER  0x0001  •/*  Lexical  analysis  functions  */ 
♦define  TBIT_PARSER  0x0002  /*  Parser  */ 

♦define  TBIT_EXPTREE  0x0004  /*  Expression  tree  */ 

♦define  TBITJOODEGEN  0x0008  /*  Code  generator  */ 

♦define  TBIT_OPTIM  0x0010  /*  Optimizer  */ 


Example  8:  Typical  bit  definitions 
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code  without  any  cost  in  object  code  selected  debugging  statements  when  the  program,  and  to  find  easily  under¬ 
in  a  production  version.  Because  the  a  user  of  the  program  rings  and  com-  stood  ways  of  displaying  the  program 

overhead  of  keeping  the  debugging  plains  about  an  apparent  error.  state.  This  discipline  in  itself  tends  to 

statements  is  usually  low,  you  might  A  beneficial  side  effect  to  using  such  produce  tighter,  better  thought-out  code, 

consider  keeping  the  statements  in  a  a  method  to  facilitate  testing  and  de- 

“final”  version  of  a  program;  a  large  bugging  is  that  it  encourages  the  pro-  Don't  Forget  the  Slack 

program  is  rarely  completely  bug  free,  grammer  to  think  about  the  legal  and  Consider  the  following  problem.  You 

and  it’s  nice  to  be  able  to  turn  on  illegal  states  of  the  data  structures  in  have  a  big  program  that  makes  many 

calls  to  a  low-level  function  called 
do_str( ).  The  program  fails,  and  you 
suspect  that  do_str( )  is  called  with  a 
NULL  pointer,  so  what  do  you  do?  Try 
adding  a  statement  similar  to  that  in 
Example  10  to  trap  the  error. 

OK,  so  you  get  the  error  message, 
but  where  was  do_str( )  called?  Wouldn’t 
it  be  wonderful  to  have  a  standard  func¬ 
tion  in  your  library,  say  caller( ),  which 
would  give  you  the  name  (as  a  C  string) 
of  the  calling  function?  You  could  then 
write  the  code  shown  in  Example  1 1 . 

An  impossible  dream?  Not  so,  as  1 
will  show.  By  accessing  the  stack  you 
can  reconstruct  the  entire  calling  se¬ 
quence  from  main(  )  down  to  the  cur¬ 
rent  function,  and  you  don’t  need  a 
debugger  —  you  use  the  same  tech¬ 
niques  that  a  debugger  uses,  but  you 
turn  an  introspective  eye  on  the  pro¬ 
gram  as  it  is  running.  The  details  are 
dependent  on  the  operating  system  and 
compiler  that  you  are  using,  but  the 
Example  1 1:  Using  caller  I  ideas  can  be  applied  to  almost  all  im- 


Example  9:  Defining  assert  -like  macros 


Example  10:  Adding  a  statement  to  trap  an  error 


plementations  of  C  (and  to  many  other 
procedural  languages),  although  a  cou¬ 
ple  of  assembler  subroutines  might  be 
needed.  To  begin  with,  you  have  to 
understand  how  your  compiler  uses 
the  stack  to  make  function  calls. 

Looking  at  the  Stack 

The  program  showstack  (see  Listing 
Two,  page  93),  perhaps  with  some  sim¬ 
ple  modifications,  will  reveal  the  se¬ 
crets  of  the  stack  on  most  computers. 

The  program  makes  a  couple  of  func¬ 
tion  calls  with  easily  recognized  values 
for  arguments,  and  prints  out  the  con¬ 
tents  of  the  stack.  I  use  SCO  Xenix  on 
an  80386  computer  with  the  Microsoft 
C  compiler,  and  the  output  on  my  ma¬ 
chine  is  shown  in  Figure  1  (with  anno¬ 
tations). 

The  stack  contains  local  variables 
(“automatic”  variables  in  official  C  jar¬ 
gon,  although  no  one  seems  to  use  the 
term),  function  arguments,  and  data 
required  to  manage  the  call/return  se¬ 
quences.  Under  Xenix,  the  stack  grows 
toward  lower  addresses,  so  the  macro 
STACKLOWis  defined.  To  see  whether 
the  stack  grows  toward  higher  or  lower 
addresses  on  your  box,  print  out  &argv 
and  &lower,  if  &argv  <  &lower ,  then 
your  stack  grows  toward  higher  ad¬ 
dresses.  Each  call  to  a  function  has  its 


own  area  on  the  stack,  sometimes  called 
the  “frame”  for  that  function.  While 
that  function  is  being  executed,  a  regis¬ 
ter  is  typically  reserved  to  point  at  the 
frame  on  the  stack.  This  register  is  often 
referred  to  as  the  base  pointer  (BP), 
and  will  typically  contain  the  value  of 
the  stack  pointer  (SP)  when  the  func¬ 
tion  was  called.  To  call  a  function,  the 
computer  does  something  like  that  in 
Example  12. 

Your  computer  may  do  other  things  — 
push  some  registers  to  save  their  val- 


push  n'th  argument 


push  2nd  argument 
push  1st  argument 
push  current  instruction  pointer 
(ie.  return  address) 
jump  to  start  of  function 
copy  stack  pointer  (SP)  to  base 
pointer  (BP) 

push  BP 


Example  12:  Calling  a  function 


2nd  arg 
1st  arg 
Return  addr 
•>  Caller's  BP 


Example  13:  The  top  of  the  stack  after 
functions  have  been  called 


ues,  for  example  —  but  will  almost  cer¬ 
tainly  perform  these  operations,  possi¬ 
bly  in  a  different  order.  When  this  se¬ 
quence  is  completed,  the  top  of  the 
stack  will  look  like  that  in  Example  13- 
(The  stack  grows  down  the  page,  so 
the  “top”  of  the  stack  is  the  last  line  — 
confusing,  but  conventional.)  The  base 
pointer  is  now  used  as  a  base  to  locate 
function  arguments  and  local  variables. 
Notice  that  the  arguments  are  pushed 
in  reverse  order;  the  first  argument  is 
then  a  known  offset  from  BP,  allowing 
function  calls  with  variable  numbers 
of  arguments.  Other  schemes  are  occa¬ 
sionally  used,  such  as  pushing  the  num¬ 
ber  of  arguments  onto  the  stack.  Local 
variables  will  come  after  the  caller’s 
BP  on  the  stack. 

To  return  from  a  function,  the  caller's 
BP  is  restored  (in  pseudo  C:  BP  =  *BP), 
and  the  return  address  is  then  a  known 
offset  away. 

Frames  for  each  function  make  a 
linked  list  on  the  stack,  with  the  current 
BP  as  the  head  of  the  list.  It  is  easy  to 
follow  the  links:  g’s  BP — ►  fs  BP  — ► 
main’s  BP  in  the  output  from  show- 
stack,  as  indicated  by  the  arrows.  The 
frame  for  the  call  to  main( )  points 
back  to  the  C  startup  function,  which 
performs  chores  such  as  setting  argc 
and  argv  before  calling  main( ).  A  de- 
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bugger  uses  this  linked  list  of  function 
invocations  to  trace  the  call  sequence 
in  a  program,  and  you  can  exploit  it  to 
create  some  powerful  debugging  tools. 
The  function  shown  in  Listing  Three, 
page  93,  follows  the  list;  it  may  need 
adjustment  for  other  compilers. 

The  stack  frame  for  the  call  to  ctrace( ) 
itself  is  found  by  taking  the  address  of 
its  first  argument:  The  output  from  show- 
stack  shows  that  the  caller’s  BP  is  at 
an  offset  of  2  from  the  first  argument, 
at  address  ( &arg_l  -  2).  The  return 
address  is  at  an  offset  of  1  from  the  BP. 
The  output  in  Example  14  was  pro¬ 
duced  by  modifying  showstack  so  that 
g( )  does  nothing  except  call  ctrace( ). 

The  values  of  &main ,  &f  and  &g  show 
the  address  ranges  of  the  code  for  these 
functions  in  memory  (see  Table  1). 

By  knowing  these  address  ranges,  it 
is  possible  to  work  out  where  a  given 
return  address  points.  You  need  an 
array  of  function  address  and  function 
name  to  make  the  conversion  of  an 
address  in  the  code  area  of  a  program 
to  the  name  of  the  function.  Listing 
Four,  page  93,  shows  how  this  is  done. 

The  function  atoname( )  finds  the 
function  closest  to,  but  starting  before, 
the  address  given  as  its  argument.  If  the 
printf/)  statement  in  ctrace( )  is 
changed  to  that  shown  in  Example  15, 
the  output  will  appear  as  the  example 
then  shows.  The  C  startup  function  is 
erroneously  identified  as  g( ),  because 
g( )  is  the  closest  function  that  ato- 
name( )  knows. 

Function  arguments  are  also  accessi¬ 
ble  at  a  known  offset  from  the  BP.  With 
my  compiler  there  is  no  way  of  deter¬ 
mining  the  number  of  arguments  made 
in  a  call,  so  I  assumed  that  there  are 
two  arguments  of  type  int,  and  changed 
ctrace( )  again,  as  shown  in  Example 
16.  If  the  symbol  table  used  by  ato- 
name( )  was  extended  with  the  num¬ 
ber  and  types  of  the  arguments  to  each 
function,  the  output  could  be  further 
improved. 

Most  software  development  environ¬ 
ments  provide  a  symbol  table  of  the 
type  required  by  atoname/ ),  which 
can  be  read  at  run  time.  This  might  be 
the  “memory  map”  provided  by  a  linker 
or  binder,  or,  as  in  the  Unix  or  Xenix 
environment,  a  table  included  in  the 
executable  run-time  file  itself.  This  ta¬ 
ble  may  provide  little  more  than  the 
address  of  each  function  entry  point, 
or  may  include  considerable  details  such 
as  the  source  file  name,  addresses  of 
statements  identified  by  source  file  line 
number,  numbers  and  types  of  func¬ 
tion  parameters,  and  other  information 
that  could  be  exploited  by  tracing  func¬ 
tions  such  as  those  described  here. 


Smain=00000094  Sf=000000db 

&g=000000f 9 

BP=0187ed20 

RET.  ADDR=0000010a 

BP=0187ed38 

RET.  ADDR=OOOOOOf 1 

BP=0187ed50 

RET.  ADDR-000000d3 

BP=0187ed6c 

RET.  ADDR=0000057d 

Example  14:  Modifying  showstack  so 
that  g(  )  calls  only  ctracef  )  results  in 
this  output 


printf  ("BP=%081x  FUNCTXON=%s\n", 

bp. 

atoname ( * (bp  +  1 ) ) ) ; 

then  the  output 

looks  like  this: 

Smain=00000094  Sf=000000db 

Sg=000000f 9 

BP=0187ed28 

FUNCTION=g 

BP=0187ed40 

FUNCTIONS 

BP=0187ed58 

FUNCTION=main 

BP=Q187ed74 

FUNCTION=g 

Example  15:  The  function  atonameC  ) 
finds  the  function  closest  to,  but 
starting  before,  the  address  given  as 
its  argument 


Example  16:  Changing  ctrace(  )  again 


Table  1:  Values  of& main,  &f,  and  8c g 


Availability 

All  source  code  is  available  on  a  single 
disk  and  online.  To  order  the  disk, 
send  $14,95  (Calif,  residents  add  sales 
tax)  to  Dr.  Dobb ’s  Journal,  501  Galves¬ 
ton  Dr.,  Redwood  City,  CA  94063,  or 
call  800-356-2002  (from  inside  Calif.) 
or  800-533-4372  (from  outside  Calif.). 
Please  specify  the  issue  number  and 
format  (MS-DOS,  Macintosh,  Kaypro). 
Source  code  is  also  available  online 
through  the  DDJ  Forum  on  Compu¬ 
Serve  (type  GO  DDJ).  The  DDJ  Listing 
Service  (603-882-1599)  supports  300/ 
1200/2400  baud,  8-data  bits,  no  parity, 
1-stop  bit.  Press  SPACEBAR  when  the 
system  answers,  type:  listings  (lower¬ 
case)  at  the  log-in  prompt. 

DDJ 

(Listings  begin  on  page  93.) 

Vote  for  your  favorite  feature/article. 

Circle  Reader  Service  No.  7. 


printf  ("%s  (%x,  %x)\n",  atoname  (*  (bp  +  1)),  *  (newbp  +  2),  Mnewbp  +  3)); 

After  this  change,  the  output  of  the  test  program  became: 

Smain=00000094  Sf=000000db  Sg=000000f9 

g (55556666,  187eda8) 
f(lill2222,  33334444) 
maind,  187eda8) 
g  (1,  187ee20) 


&argc=0187ed78 

&argv=0187ed7c 

&main=00000094 

&f=000000f0  &g=00000 1 0e 

0187ed7c 

0187eda4 

argv,  2nd  arg  of  main( ) 

0187ed78 

00000001 

argc,  1  st  arg  of  main( ) 

0187ed74 

0000058d  | 

Return  addr  C  startup  function 

0187ed70 

0187ed98  - ' 

- ►  BP  of  C  startup  function 

0187ed6c 

00000000 

0187ed68 

0187edac 

0187ed64 

0187eda4 

0187ed60 

33334444 

2nd  arg  of  f( ) 

0187ed5c 

11112222 

1st  arg  of  f( ) 

0187ed58 

000000e8 

Return  address  in  main( ) 

0187ed54 

0187ed70  - 

— ►  BP  of  main( ) 

0187ed50 

00000000 

0187ed4c 

0187edac 

0187ed48 

0187eda4 

0187ed44 

55556666 

1st  arg  of  g( ) 

0187ed40 

00000106 

Return  address  in  f( ) 

0187ed3c 

- ►  0187ed54  - 

BPofff) 

0187ed38 

77778888 

local 

BP - 

Figure  1:  Output  of  (he  showstack  program 


Function 

Addresses 

main{ ) 

0x94  to  Oxda 

f() 

0xdbto0xxf8 

90 

0xf9  to  ??? 
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C  Customized 
Memory  Allocators 

When  malloc( )  et  al  won’t  do 


Paul  Anderson 


C  programs  often  need  to  allo¬ 
cate  storage  at  run  time.  The  C 
library  routines  malloc( ),  cal- 
loc( ),  realloc( ),  and  free(  )  use 
pointers  to  heap  memory  for 
run-time  storage.  Although  these  rou¬ 
tines  are  easy  to  use,  there’s  no  error 
checking  if  you  call  them  incorrectly. 
Subtle  bugs  can  make  you  lose  valu¬ 
able  development  time. 

In  this  article,  I’ll  show  you  how  to 
customize  the  memory  allocator  rou¬ 
tines  to  help  you  during  the  develop¬ 
ment  cycle.  Along  the  way  I’ll  intro¬ 
duce  several  techniques  that  help  pin¬ 
point  memory  allocator  errors  as  they 
occur.  The  approach  is  to  provide  front 
ends  to  the  standard  allocators  for  de¬ 
bugging.  After  the  system  is  running 
and  becomes  stable,  you  can  then  re¬ 
place  the  customized  allocators  with 
the  standard  ones.  You  may,  however, 
want  to  continue  to  use  the  custom 
allocators  in  your  system,  depending 
upon  the  overhead  imposed  on  your 
system.  This  article  should  at  least  give 
you  some  ideas  on  how  to  better  C’s 
run-time  management  routines  for  your 
own  applications. 


Paul  is  a  consultant  and  coauthor  of 
Advanced  C  Tips  and  Techniques,  pub¬ 
lished  by  Howard  W.  Sams,  from  which 
this  article  was  adapted.  Paul  can  be 
reached  at  1212  Eolus  Ave.,  Leucadia, 
CA  92024. 
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Negative  Subscripts 

The  basic  rule  for  arrays  that  the  com¬ 
piler  uses  for  a  pointer  offset  is: 

&a[n]  =  a  +  n  =  (char  *)a  +  n  * 

sizeof(object) 

Substituting  0  for  n,  you  have 

&a[0]  =  a  =  (char  *)a 

This  explains  why  C  array  subscripts 
start  at  zero.  The  compiler  always  uses 
the  base  address  for  the  start  of  the 
array.  What  happens  when  n  is  nega¬ 
tive?  The  formula  for  a  negative  pointer 
offset  is  only  slightly  different: 

&a[-n]  =  a  -  n  =  (char  *)a  -  n  * 

sizeof(object) 

The  pointer  offset  is  below  the  base 
address  of  the  array.  Negative  subscripts 
are  legal  in  C  because  the  index  is 
converted  to  a  pointer  offset. 

Example  1  is  a  program  that  demon¬ 
strates  out-of-bounds  array  references 
in  C.  The  program  uses  a  negative  sub¬ 
script  and  also  references  an  array  ele¬ 
ment  beyond  its  last  member.  On  the 
Xenix  system  I  use,  this  program  pro¬ 
duces  a  core  dump,  but  I’ve  seen  it  run 
fine  under  DOS  and  other  Unix  sys¬ 
tems.  Note  that  this  program  would 
not  compile  if  rewritten  in  Pascal  or 
Algol.  These  languages  include  compile¬ 
time  checks  that  complain  if  an  array 
subscript  is  out-of-bounds.  In  C,  how¬ 
ever,  array  references  simply  convert 
to  pointer  offsets.  This  allows  programs 
with  negative  subscripts  to  compile  and 
sometimes  to  run. 

Negative  subscripts  can  be  put  to 
work  in  a  useful  way.  Here,  I’ll  use 
them  in  a  custom  version  of  the  C  li¬ 
brary  routine  callocC ).  The  routine, 
called  xcalloc( ),  provides  heap  mem¬ 
ory  for  data  storage  at  run  time,  and 
provides  features  that  calloc( )  does 
not.  For  example,  xcallocC )  checks  for 
errors  instead  of  leaving  this  job  to  the 
calling  routine.  This  makes  it  easier  to 
use,  and  it  helps  centralize  error  mes¬ 
sages.  xcalloc( )  also  stores  an  integer 
that  indicates  the  number  of  elements 
you  request  in  heap  storage  along  with 
the  data. 

Programs  call  xcallocC )  with  the  same 
protocols  as  callocC ).  xcallocC  ),  how¬ 
ever,  allocates  memory  for  an  integer 
value  in  addition  to  space  for  the  data. 
The  routine  stores  the  number  of  ele¬ 
ments  allocated  from  the  heap  and  re¬ 
turns  a  pointer  to  the  space  allocated 
for  the  data.  Programs  use  a  negative 
offset  from  the  heap  pointer  to  access 
the  number  of  elements. 

Suppose,  for  example,  you  call  xcal¬ 
locC  )  to  allocate  heap  storage  for  ten 


integers  and  assign  the  heap  address  ers  p  and  q  are  valid  because  xcallocC ) 
to  p( a  pointer  to  an  integer).  checks  for  heap  errors.  The  program 

calls  routines  to  assign  integers  to  the 
int  *p;  heap  and  display  their  values.  The  first 

....  call  to  fillC )  stores  ten  integer  numbers 

p  =  (int  *)  xcalloc(10,  sizeof(int));  on  the  heap,  and  the  second  call  stores 
....  fifteen  integers.  displayC )  prints  the  data 

from  the  heap  area  pointed  to  by  its 
xcallocC  )s  first  argument  is  the  num-  argument.  Neither  of  these  routines  re- 

ber  of  elements  and  the  second  argu-  quires  the  number  of  elements  as  a 

ment  is  the  size  of  each  element,  function  parameter — this  is  available 

sizeofC int)  is  used  for  portability.  Fig-  from  the  heap  pointer, 

ure  1  shows  a  modified  heap  configu-  Example  3  shows  the  code  for  xcal- 
ration  for  a  machine  with  16-bit  inte-  locC ).  The  variable  blksize  contains  the 

gers  and  addresses,  p  points  to  ten  amount  of  memory  you  request  from 

integers  (with  initial  values  of  zero)  on  the  heap.  The  function  calls  mallocC ) 

the  heap.  The  number  of  elements  (ten)  from  the  standard  C  library  to  allocate 

is  stored  at  address  8612,  in  front  of  the  blksize  bytes  plus  one  integer  (sizeof- 

data./t,  however,  points  to  address  8614,  C int)  bytes)  from  the  heap.  Note  that 

assuming  that  integers  are  2  bytes.  Pro-  xcallocC )  displays  an  error  message 

grams  use  a  negative  offset  from  p  to  and  terminates  the  program  if  heap 

access  the  number  of  elements  (ten).  space  is  not  available.  The  statement 
Example  2  is  a  program  called  neg.c 
that  demonstrates  xcallocC ).  neg.c  calls  *(int  *)pheap  =  nitems; 

xcallocC )  twice  for  heap  storage.  The  /*  store  no.  of  items  in  heap  */ 

first  call  allocates  storage  for  ten  inte¬ 
gers  and  the  second  for  fifteen  inte-  stores  the  number  of  elements  in  the 

gers.  You  can  assume  the  heap  point-  heap  by  casting  the  heap  pointer  to  an 


/*  twzone.c  -  array 

out  of  bounds  */ 

main  () 

int  buf [10] ; 

buf [-4 ]  =  1; 

/*  negative  subscript  */ 

buf [10]  =  2; 

/*  one  step  beyond  */ 

printf ("%d  ld\n' 

1 

,  *  (buf  -  4) ,  *  (buf  +  10) ) ; 

Example  1:  Out-of-bounds  references 


/*  neg.c  -  negative  subscripts  with  xcalloc  */ 

♦include  <stdio.h> 

main  () 
i 

char  *xcalloc(); 
int  *p,  *q; 

p  =  (int  *)  xcalloc (10,  sizeof  (int) ) ; 
q  =  (int  *)  xcalloc(15,  sizeof (int) ) ; 

fill(p);  /*  fill  with  10  numbers  */ 

display  (p);  /*  print  10  numbers  */ 

fill(q);  /*  fill  with  15  numbers  */ 

display (q);  /*  print  15  numbers  */ 

1 

$  neg 

123456789  10 
1  2  3  4  5  6  7  8  9  10  11  12  13  14  15 


Example  2:  Program  that  demonstrates  xcalloc(  ) 


Figure  1:  Modified  heap  storage  for  ten  integers 
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integer  pointer  before  the  size  is  stored. 
memsetC )  zeros  the  heap  area  to  make 
xcalloc( )  compatible  with  calloc( ).  The 
statement 

return  pheap  +  sizeof(int); 

/*  pointer  to  data  V 

returns  the  heap  pointer  to  the  calling 
routine,  which  is  offset  by  the  integer 
containing  the  number  of  elements. 
sizeofC )  makes  xcallocC )  portable. 

Now  for  the  rest  of  the  routines.  Ex¬ 
ample  4  shows  fill( )  and  displayC ), 
which  use  negative  subscripts.  Both 
routines  access  the  heap  to  determine 
the  number  of  elements  before  they 
loop  through  the  data.  The  statement 
pf-1]  uses  a  negative  subscript.  From 
the  basic  rule  for  C  arrays,  it's  as  if  you 
typed  *(p  -  1).  This  evaluates  to  an 
integer,  which  is  the  number  of  ele¬ 
ments  at  the  heap  address. 

neg.c  demonstrates  only  integer  point¬ 
ers.  Programs  may  use  xcalloc( )  to 
allocate  heap  pointers  to  any  C  data 
type.  Suppose,  for  example,  you  want 
to  allocate  space  for  20  structures  of 
type  something.  You  may  call  xcal- 
loc( )  as  follows: 

struct  something  *ps; 

ps  =  (struct  something  *)  xcalloc(20, 
sizeof(struct  something)); 

This  shows  that  xcalloc( )  is  indepen¬ 
dent  of  the  allocated  pointer’s  data  type. 
The  routine  still  stores  the  number  of 
elements  as  an  integer,  however,  which 
means  you  have  to  cast  the  pointer 
appropriately  to  access  it.  I’ll  elaborate. 

Suppose  sfillC  )  and  sdisplay(  )  store 
data  into  heap  structures  and  display 
data,  respectively.  A  call  to  sfill( ),  for 
example,  looks  like 

sfill(ps);  /*  fill  20  structures  V 

Inside  sfill( ),  you  access  the  number 
of  elements  with  the  following  state¬ 
ments: 

sfill(p) 

/*  fill  structures  from  heap  V 

struct  something  *p; 

1 

int  nitems  =  ((int  *)p)[-l]; 

/*  number  of  items  from  heap  */ 


You  must  cast  p  before  you  apply  the 
negative  subscript.  The  parentheses  are 
necessary  in  order  to  make  the  state¬ 
ment  compile.  Without  them,  the  com¬ 
piler  tries  to  cast  an  array  reference. 
The  same  changes  would  apply  to  sdis- 
playC  ). 


Customized  Memory  Allocators 

Many  of  the  standard  C  library  routines 
have  no  error  checking.  When  you  use 
these  routines  and  errors  occur,  you 
may  want  to  report  error  information 
that  the  standard  routines  can’t  (or 
won’t)  provide.  One  way  to  get  this 
extra  level  of  error  checking  is  to  write 
front  ends  to  the  standard  library  rou¬ 
tines.  These  custom  routines  check  for 
errors  and  handle  system  specifics,  then 
call  the  standard  routines  if  they  don’t 
discover  problems. 

The  dynamic  storage  allocators  from 
the  standard  C  library  are  good  candi¬ 
dates  for  custom  front  ends.  I’ve  found 
that  software  systems  that  make  heavy 
use  of  dynamic  storage  allocation  are 
harder  to  debug.  Calls  to  mallocC  ),  cal- 
loc(  ),  and  reallocC  ),  for  example,  pro¬ 
vide  some  information  about  errors,  but 
you  rarely  get  enough  to  find  the  cause 
of  the  problem.  What’s  worse,  free( ) 
may  destroy  the  integrity  of  the  heap 
if  its  argument  is  not  a  heap  address 
from  a  previous  call  to  the  allocator. 

With  a  little  effort  and  some  over¬ 
head,  you  can  improve  this  situation. 
In  this  section,  I’ll  present  front  ends 
for  malloc( ),  realloc(  ),  and  free(  ).  A 
front  end  for  callocC  )  follows  from  the 
same  approach. 


Front  Ends 

Programs  include  a  file  called  xalloc.h 
for  using  the  front  end  routines.  The 
statement  Hnclude  "xalloc.h  ’’provides 
the  interface.  I’ll  examine  this  file  shortly. 

I’ll  start  with  xmalloc( ),  a  front  end 
for  mallocC  )■  The  use  of  xmallocC ) 
allocates  storage  dynamically  in  the 
same  way  as  mallocC )■  Suppose,  for 
example,  a  file  called  pgm.c  contains 
the  following  statements. 

^include  “xalloc.h” 

char  *pheap; 

pheap  =  xmalloc(lOO); 

/*  100  bytes  V 

xmallocC  )  allocates  100  bytes  of  mem¬ 
ory  from  the  heap.  If  all  is  well,  it’s  as 
if  you  called  mallocC  ).  If  there  is  an 
error,  however,  the  program  terminates 
and  displays  the  following  message  on 
standard  error: 

file  pgm.c  -  line  56:  malloc  error  for 
100  bytes 

The  error  message  displays  the  file  name 
and  the  line  number  where  mallocC ) 
fails.  This  helps  you  locate  the  exact 


♦include  <stdio.h> 

♦include  <malloc.h> 

♦include  <memory.h> 

char  ‘xcalloc (nitems,  size) 
unsigned  nitems,  size; 

/*  custom  callocO  */ 

char  *pheap; 
unsigned  blksize; 

blksize  =  nitems  *  size; 

/*  size  of  chunk  */ 

if  ((pheap  =  malloc (blksize  +  sizeof (int) ) ) 
fprintf (stderr,  "Can't  malloc  on  heap\n" 
exit  (1) ; 

==  NULL)  ( 

; 

Mint  *) pheap  =  nitems; 

/*  store  no.  of  items  in  heap  */ 

memset (pheap  +  sizeof (int), 

0,  blksize) ; 

/*  zero  the  area  */ 

return  pheap  +  sizeof (int); 

) 

/*  pointer  to  data  */ 

Example  3:  xcalloc(  )  routine 


fill (p) 
int  *p; 

/*  fill  heap  with  integers  */ 

int  i; 

int  nints  =  p [ — 1 ] ; 

/*  number  of  items  from  heap  */ 

for  (i  =  0;  i  <  nints; 
p[i]  =  i  +  1; 

) 

i++) 

display (p) 
int  *p; 

/*  display  integers  from  heap  */ 

int  i; 

int  nints  =  p [ — 1 ] ; 

/*  number  of  items  from  heap  */ 

for  (i  =  0;  i  <  nints; 

printf ("%3d",  p [ i ] 
putchar (' \n' ) ; 

} 

i++) 

; 

Example  4:  fill(  )  and  display!  )  routines 
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spot  in  your  source  file  where  the  prob¬ 
lem  occurred. 

The  front  ends  xrealloc(  land  xfree( ) 
work  in  a  similar  way.  Programs  use 
these  front  ends  with  the  same  parame¬ 
ters  as  their  C  library  counterparts.  Note 
that  none  of  the  front  ends  require  you 
to  test  the  return  value  from  an  alloca¬ 
tor  call. 

Example  5  shows  what’s  inside  the 
include  file  xalloc.h.  The  header  file 
reveals  that  the  front  ends  are  actually 
macros  that  call  separate  functions.  The 
use  of  the  special  names  _FILE_  and 
_LINE_  makes  the  C  preprocessor  sub¬ 
stitute  a  filename  and  line  number  each 
time  the  macro  is  called.  This  allows 
each  function  to  display  an  error  mes¬ 
sage  with  a  file  name  and  a  line  number 
when  a  C  library  allocator  routine  fails. 

Note  that  xmallocC )  (a  macro)  calls 
ymallocC )  (a  function).  Example  6 
shows  the  first  version  of  ymallocC ). 
It’s  not  very  fancy  yet,  but  there’s  more 
to  come.  At  this  point,  ymalloc( )  calls 
malloc  and  checks  the  return  pointer 
value.  If  there’s  an  error,  an  error  mes¬ 
sage  appears  on  standard  error  and  the 
program  terminates. 

Now  put  xmallocC  )to  use.  Suppose 
you  want  to  maintain  a  symbol  table 
of  different  data  types.  For  simplicity, 
limit  data  types  to  only  strings  and  dou¬ 
bles.  One  way  to  handle  different  data 
types  is  with  a  union  of  pointers  to  the 
data.  Example  7  contains  a  header  file 
called  defs.h  which  defines  a  node, 
called  “Symbol,”  for  a  symbol  table 
linked  list.  The  pointer pnext  links  each 
symbol  in  the  table  to  the  next  one. 
Suppose  you  declare 

Symbol  *p; 

/*  pointer  to  symbol  table  */ 

in  a  program.  If  p  points  to  a  symbol 
and  p->dtype  is  equal  to  STRING,  then 
p->val.pstring  is  a  pointer  to  a  string. 
Otherwise,  p->valpdouble  points  to  a 
double. 

Listing  One,  page  94,  is  a  program 
that  calls  xmalloc( )  and  creates  stor¬ 
age  for  a  string  symbol,  a  double  sym¬ 
bol,  and  a  large  number  of  integers. 
For  the  symbols,  the  first  call  to  xmal¬ 
locC  )  allocates  storage  for  a  symbol, 
and  the  second  call  reserves  storage  for 
the  data.  I’ll  omit  the  details  of  linking 
the  two  symbols  together.  The  last  call 
to  xmallocf )  doesn’t  have  anything  to 
do  with  the  symbol  table,  but  it  shows 
what  happens  if  you  try  to  allocate 
heap  storage  for  too  many  objects. 

The  header  file  defs.h  contains  the 
definition  of  Symbol.  The  first  xmal- 
loc(  )  allocates  storage  for  a  string  sym¬ 
bol  and  assigns  a  heap  address  to 
pointer  pi.  The  second  xmalloc(  )  allo¬ 


cates  storage  for  the  string  member 
pointed  to  by  pi.  The  program  sets 
pi's  data  type  to  STRING  and  copies 
the  constant  string  “test  string”  pointed 
to  by  ps  to  the  heap. 

The  third  xmallocC )  allocates  stor¬ 
age  on  the  heap  for  a  double  symbol, 
and  the  fourth  xmalloc(  )  creates  stor¬ 
age  for  a  double.  The  program  assigns 
a  double  precision  constant  (6.7e  -  13) 
to  p2 ,  whose  data  type  is  DOUBLE. 
The  last  xmallocC )  attempts  to  allocate 
30,000  integers  on  the  heap.  The  pro¬ 
gram  fails  on  the  Xenix  machine  I  use 
because  there’s  not  enough  room.  The 
error  message  indicates  which  xmal- 
loc(  )  fails. 

Before  I  move  on  to  the  front  ends 
for  reallocC )  and  free( ),  let’s  include 
another  level  of  error  checking.  This 
time  I’ll  have  the  calls  to  xmalloc( )  and 
reallocC )  save  heap  pointers,  so  that 
xfree( )  can  check  them  before  it  calls 
free(  ).  With  this  arrangement,  the  front 
ends  flag  an  error  if  a  program  tries  to 
free  an  invalid  heap  pointer. 

This  requires  a  data  structure  to  hold 
heap  pointers.  For  simplicity,  I  use  an 
array  that  holds  a  maximum  of  256 


pointers.  Listing  Two,  page  94,  con¬ 
tains  the  C  source  code  for  this  ar¬ 
rangement.  Note  that  I  modified  ymal- 
loc  to  install  the  heap  pointer  in  the 
array  of  pointers  called  dbuf.  All  that’s 
different  from  the  first  version  is  a  call 
to  installC )  to  save  the  heap  pointers. 

The  install( )  routine  searches  the 
dbuf  array  for  an  empty  spot  (NULL). 
If  none  is  found,  the  program  exits 
with  an  error  message  that  says  the 
debug  buffer  is  full.  Otherwise,  the  heap 
pointer  is  stored  in  a  vacant  slot.  For 
simplicity,  I  make  a  linear  search 
through  the  dbuf  array  and  terminate 
the  program  if  it’s  full,  but  other  ap¬ 
proaches  are  possible  (see  the  bibliog¬ 
raphy  at  the  end  of  this  article). 

Recall  that  the  macro  xrealloc( )  calls 
the  function  yreallocC X  which  is  a  front 
end  to  realloc( ).  yreallocC )  verifies  that 
the  pointer  that’s  passed  to  it  has  been 
previously  allocated  on  the  heap,  how¬ 
ever.  It  checks  the  debug  buffer  for  the 
pointer,  and  if  it’s  there,  calls  the  stan¬ 
dard  reallocC )  to  replace  it  with  a  new 
pointer. 

Now  let’s  look  closer  at  the  yreal¬ 
locC  )  routine.  First,  yreallocC )  checks 


/*  xalloc.h  -  header  file  for  customized  memory  allocators  */ 

♦define  xmalloc(N) 

ymalloc (  FILE  ,  LINE  ,  N) 

♦define  xcalloc(N,  S) 

ycalloc (  FILE  ,  LINE  ,  N,  S) 

♦define  xrealloc(P,  N) 

yrealloc (  FILE  ,  LINE  ,  P,  N) 

♦define  xfree(P) 

yf ree  (  FILE  ,  LINE  ,  P) 

char  *ymalloc(),  *ycalloc(),  *yrealloc(); 

void  y free  () ; 

Example  5:  xalloc.h  header  file 


/*  ymallocl.c  -  front  end  for  mallocO 


♦include  <stdio.h> 

♦include  <malloc.h> 

char  *ymalloc (f ile,  lineno,  nbytes) 
char  *file; 
int  lineno; 
unsigned  int  nbytes; 

{ 

char  *pheap; 

pheap  =  malloc (nbytes) ; 
if  (pheap  ==  (char  *)  NULL)  { 

fprintf (stderr, "f ile  %s  -  line  %d:  malloc  error  for  %u  bytes\n", 
file,  lineno,  nbytes); 

exit  (1)  ; 

} 

return  pheap; 

) 


Example  6:  First  version  of  ymalloc.c 


/*  defs.h  -  symbol  table  definitions  */ 

♦define  STRING  1 
♦define  DOUBLE  2 

typedef  struct  Symbol  { 
int  dtype; 
union  { 

char  *pstring; 
double  *pdouble; 

)  val; 

struct  Symbol  *pnext; 

}  Symbol; 


Example  7:  Symbol  table  example 


Dr.  Dobb’s  C Sourcebook,  Winter  1989/90 


65 

1011 


MEMORY  ALLOCATORS 


/*  xalloc.h  -  header  file  for  standard  memory  allocators 

(No  error 

*/ 

checking) 

#define  xmalloc(N) 

malloc (N) 

tdefine  xcalloc(N,  S) 

calloc (N,  S) 

fdefine  xrealloc(P,  N) 

realloc  (P,  N) 

tdefine  xfree(P) 

free  (P) 

char  *malloc(),  *calloc(),  *realloc(); 

void  freed; 

_ 1 

Example  8:  Header  file  for  standard  allocators 


oldp  to  make  sure  that  it’s  not  NULL 
and  in  the  buffer.  Otherwise,  the  pro¬ 
gram  displays  an  error  message  along 
with  the  illegal  address,  and  exits.  If  all 
is  well,  yrealloc( )  calls  realloc/ )  and 
verifies  that  the  new  heap  pointer  is 
not  NULL.  Before  yreallocf )  returns 
the  heap  pointer,  the  function  installs 
the  pointer  in  the  same  debug  buffer 
slot  as  the  old  pointer. 

The  last  front  end  is  xfree( ),  which 
calls  yfreeC )  and  verifies  that  a  pointer 
has  heap  storage  associated  with  it. 
This  is  the  important  level  of  error  check¬ 
ing  that’s  missing  from  the  free( )  li¬ 
brary  routine. 

The  yfree( )  routine  displays  an  error 
message  and  exits  if  the  heap  pointer 
is  not  stored  in  dbuf  or  if  it  is  NULL. 
The  error  message  displays  the  bad 
address.  If  the  pointer  contains  a  valid 
heap  address,  the  routine  makes  the 
pointer’s  location  in  the  dbuf  array  avail¬ 
able  (NULL),  before  it  calls  free( ).  This 
arrangement  guarantees  that  you  never 
free  storage  on  the  heap  that  hasn’t 
been  previously  allocated. 

I  tested  these  new  routines  by  modi¬ 
fying  the  symbol  table  example.  Listing 
Three,  page  94,  is  a  program  called 
"sym2.c,”  which  reallocates  the  heap 
to  hold  a  longer  string  for  the  string 
symbol  and  calls  xfree( )  to  free  heap 
storage.  The  first  part  of  the  program 
is  the  same  as  the  previous  version. 
However,  sym2.c  calls  xreallocf )  with 
the  old  pointer,  pl->val.pstring,  to  al¬ 
locate  enough  storage  to  accommo¬ 
date  a  longer  string,  ps2.  The  program 
copies  the  longer  string  to  symbol  pi 
on  the  heap  and  displays  the  new  string. 

Note  that  sym2.c  calls  xfree( )  twice. 
The  first  call  works  fine  because  the 
pointer  contains  a  valid  heap  address. 
The  second  call,  however,  displays  an 
error  message  because  ps2  is  not  a 
heap  pointer. 

Performance  Issues 

How  about  performance?  Although  the 
front  ends  provide  error  checking,  be 
aware  that  these  routines  introduce  ad¬ 
ditional  overhead  and  may  cause  prob¬ 
lems  with  time-critical  software,  for  sev¬ 
eral  reasons.  First  of  all,  you’re  passing 
more  parameters  to  the  front  end  rou¬ 


tines  than  the  C  library  modules  re¬ 
quire.  Secondly,  it  takes  time  to  save 
heap  pointers  and  search  for  them.  What 
you  have,  therefore,  is  a  trade-off  be¬ 
tween  error  checking  and  performance. 

In  the  early  stages  of  development, 
the  front  ends  can  help  considerably 
during  debugging.  After  the  software 
becomes  stable,  you  can  always  re¬ 
move  the  front  ends  and  return  to  the 
standard  allocators.  One  way  to  do  this 
is  by  modifying  xalloc.h,  as  shown  in 
Example  8.  This  makes  your  code  exe¬ 
cute  the  C  library  calls  instead  of  their 
front  end  counterparts.  Bear  in  mind, 
however,  that  this  approach  does  not 
check  return  values. 
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SIRING  CLASSES 


Listing  One  (Text  begins  on  page  18.) 


Txt  =  Temp; 
} 


// 

// 

// 

// 

// 

// 

// 

// 

// 

// 

// 


Header: 
Version: 
Language : 
Environ: 
Compilers : 
Purpose: 
Written  by: 


String  (Dynamic  Strings) 

1.01  13-Sep-1989 

C++  2.0 

Any 

Zortech  C++ 

Provides  a  general  dynamic  string  class. 

Scott  Robert  Ladd 

705  West  Virginia 

Gunnison  CO  81230 

MCI  ID:  srl 

FidoNet:  1:104/45.2 


#if  ! defined (STRING_HPP) 
#def ine  STRING_HPP 


//  constructor 
String: :String{) 

( 

Len  =  0 ; 

Siz  =  Alloclncr; 

Txt  =  new  char [Siz); 

Txt [0]  =  ' \x00' ; 

) 

String: : String (String  &  Str) 
( 

Len  =  Str. Len; 

Siz  =  Str. Siz; 

Txt  =  new  char [Siz); 
memcpy (Txt, Str .Txt, Len) ; 


([include  "stddef.h" 

class  String 

{ 

private: 

//  instance  variables 

unsigned  int  Siz;  //  allocated  size 

unsigned  int  Len;  //  current  length 

char  *  Txt;  //  pointer  to  text 

//  class  constant 

static  unsigned  int  Alloclncr; 

//  private  method  used  to  shrink  a  string  to  its  minimum  allocation 
void  Shrink (); 
public: 

enum  StrCompVal  (SC_LESS,  SC_EQUAL,  SC_GREATER); 
enum  StrCompMode  ( SF_SENSITIVE,  SF_IGNORE); 

//  constructor 
String () ; 

String (String  &  Str); 

String (char  *  Cstr) ; 

String (char  FillCh,  unsigned  int  Count); 

//  destructor 
“St ring ()  ; 

//  value  return  methods 
unsigned  int  LengthO; 
unsigned  int  Size(); 

//  Function  to  return  a  blank  string 
friend  String  EmptyO; 

//  copy  String  to  c-string  method 

void  Copy (char  *  Cstr,  unsigned  int  Max); 

//  create  a  c-string  from  String  method 
char  *  Dupe(); 

//  assignment  method 

void  operator  =  (String  &  Str) ; 

//  concatenation  methods 

friend  String  operator  +  (String  Strl,  String  Str2); 
void  operator  +=  (String  Str) ; 

//  comparison  method 

StrCompVal  Compare (String  Str,  StrCompMode  Case  =  SF_IGNORE) ; 

//  substring  search  methods 

int  Find(Strinq  Str,  unsigned  int  &  Pos,  StrCompMode  Case  = 

SF_ IGNORE) ; 

//  substring  deletion  method 

void  Delete (unsigned  int  Pos,  unsigned  int  Count); 

//  substring  insertion  methods 

void  Insert (unsigned  int  Pos,  char  Ch) ; 

void  Insert (unsigned  int  Pos,  String  Str); 

//  substring  retrieval  method 

String  SubStr (unsigned  int  Start,  unsigned  int  Count); 

//  character  retrieval  method 
char  operator  []  (unsigned  int  Pos); 

//  case-modification  methods 
String  ToUpperO; 

String  ToLowerO; 

}; 

♦endif 


Listing  Two 


End  Listing  One 


String: :String (char  *  Cstr) 

{ 

Len  =  strlen (Cstr) ; 

Siz  =  ((Len  +  Alloclncr  -  1)  /  Alloclncr)  *  Alloclncr; 
Txt  =  new  char [Siz); 
memcpy (Txt, Cstr, Len) ; 

) 

String: :String (char  FillCh,  unsigned  int  Count) 

[ 

unsigned  int  Pos; 

Siz  =  ((Count  +  Alloclncr  -  1)  /  Alloclncr)  *  Alloclncr; 
Len  =  Siz; 

Txt  =  new  char [Siz); 
memset (Txt, FillCh, Count) ; 

) 

//  destructor 
String: : “String () 

I 

delete  Txt; 

) 


//  value  return  methods 
unsigned  int  String: :Length() 

[ 

return  Len; 

) 

unsigned  int  String: :Size() 

( 

return  Siz; 

) 

//  Function  to  return  a  blank  string 
String  EmptyO 
< 

static  String  EmptyStr; 
return  EmptyStr; 

) 

//  copy  String  to  c-string  method 
void  String: :Copy (char  *  Cstr,  unsigned  int  Max) 
{ 

unsigned  int  CopyLen; 
if  (Max  ==  0) 
return; 

if  (Len  >=  Max) 

CopyLen  =  Max  -  1; 

else 

CopyLen  =  Len; 
memcpy (Cstr, Txt, CopyLen) ; 

Cstr [CopyLen]  =  '\x00'; 

) 

//  create  a  c-string  from  String  method 
char  *  String: :Dupe () 

{ 

char  *  new_cstr; 
new_cstr  =  new  char [Len  +  1); 
memcpy ( new_cst  r , Txt , Len )  ; 
new_cstr [Len]  =  '\x00'; 
return  new_cstr; 

) 


// 

// 

// 

// 

// 

// 

// 

// 

// 

// 

// 


Module : 

Version: 

Language : 

Environ: 

Compilers: 

Purpose: 

Written  by: 


String  (Dynamic  Strings) 

1.01  13-Sep-1989 

C++  2.0 

Any 

Zortech  C++ 

Provides  a  general  dynamic  string  class. 

Scott  Robert  Ladd 

705  West  Virginia 

Gunnison  CO  81230 

MCI  ID:  srl 

FidoNet:  1:104/45.2 


♦include  "String. hpp" 

♦include  "string. h" 

♦include  "stddef.h" 

♦include  "ctype.h" 

//  class-global  constant  intialization 
unsigned  int  String: :AllocIncr  =  8; 

//  private  function  to  shrink  the  size  of  an  allocated  string 
void  String: :Shrink() 

1 

char  *  Temp; 

if  ((Siz  -  Len)  >  Alloclncr) 

Siz  =  ((Len  +  Alloclncr  -  1)  /  Alloclncr)  *  Alloclncr; 
Temp  =  new  char[Siz); 
memcpy (Temp, Txt , Len) ; 
delete  Txt; 


//  assignment  method 

void  String: : operator  =  (String  &  Str) 

f 

Len  =  St r. Len; 

Siz  =  Str. Siz; 

delete  Txt; 

Txt  =  new  char [Siz]; 
memcpy (Txt, Str. Txt, Len) ; 

) 


//  concatenation  methods 

String  operator  +  (String  Strl,  String  Str2) 

( 

unsigned  int  NewLen,  NewSiz,  CopyLen; 

String  TempStr; 
char  *  Temp; 

TempStr  =  Strl; 

CopyLen  =  St r 2. Len; 

NewLen  =  TempStr. Len  +  Str2.Len; 

NewSiz  =  TempStr. Siz  +  Str2.Siz; 

Temp  =  new  char [NewSiz] ; 

memcpy ( Temp , TempSt  r . Txt ,  TempSt  r . Len ) ; 

delete  TempStr. Txt; 

TempStr. Txt  =  Temp; 

memcpy (&TempStr .Txt [TempStr . Len] , St r2 .Txt , CopyLen) ; 
TempStr. Len  =  NewLen; 

TempStr. Siz  =  NewSiz; 

TempStr. Shrink () ; 
return  TempStr; 

} 
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void  String: : operator  +=  (String  Str) 

if  (Pos  <  Len) 

( 

for  (unsigned  int  Col  =  Len  +  1;  Col  >  Pos;  — Col) 

unsigned  int  NewLen,  NewSiz,  CopyLen; 

Txt [Col]  =  Txt [Col-1]; 

char  *  Temp; 

Txt [Pos]  =  Ch; 

CopyLen  =  Str.Len; 

++Len; 

NewLen  =  Len  +  CopyLen; 

) 

NewSiz  =  Siz  +  Str.Siz; 

void  String: : Insert (unsigned  int  Pos,  String  Str) 

Temp  =  new  char [NewSiz] ; 

( 

memcpy (Temp, Txt, Len) ; 

unsigned  int  SLen  =  Str.Len; 

delete  Txt; 

SLen  =  Str.Len; 

Txt  =  Temp; 

if  (SLen  >  0) 

memcpy (4 Txt [Len] , Str. Txt, CopyLen) ; 

for  (unsigned  int  1=0;  I  <  SLen;  ++I) 

Len  =  NewLen; 

( 

Siz  =  NewSiz; 

Insert (Pos, Str .Txt [ I ] ) ; 

Shrink () ; 

> 

++Pos; 

} 

//  comparison  method 

) 

StrCompVal  String: rCompare (String  Str,  StrCompMode  Case) 

//  substring  retrieval  method 

( 

String  String: :SubStr (unsigned  int  Start,  unsigned  int  Count) 

char  *  Tempi,  *  Temp2; 

{ 

Tempi  =  new  char [Len  +  1); 

String  TempStr; 

Copy (Tempi, Len+1) ; 

char  *  Temp; 

Temp2  =  new  char [Str. Len  +  1); 

if  ((Start  <  Len)  44  (Count  >  0)) 

Str .Copy (Temp2, Str. Len+1) ; 

for  (unsigned  int  Pos  =  0;  Pos  <  Count;  ++Pos) 

if  (Case  ==  SF  IGNORE) 

( 

{ 

if  (TempStr. Len  ==  TempStr. Siz) 

strupr (Tempi) ; 

( 

strupr (Temp2) ; 

TempStr. Siz  +=  Alloclncr; 

) 

Temp  =  new  char [TempStr. Siz] ; 

switch  (strcmp (Tempi, Temp2) ) 

memcpy (Temp, TempStr. Txt, Len) ; 

{ 

delete  TempStr. Txt; 

case  -1:  return  SC  LESS; 

TempStr. Txt  =  Temp; 

case  0:  return  SC  EQUAL; 

} 

case  1:  return  SC  GREATER; 

TempStr .Txt [Pos]  =  Txt [Start  +  Pos]; 

) 

++TempStr .Len; 

delete  Tempi; 

) 

delete  Temp2; 

} 

return  TempStr; 

} 

//  substring  search  methods 

//  character  retrieval  method 

int  String: :Find(String  Str,  unsigned  int  &  Pos,  StrCompMode  Case) 

char  String: :operator  []  (unsigned  int  Pos) 

char  *  TempStrl,  *  TempStr2; 

if  (Pos  >=  Len) 

unsigned  int  LastPos,  SearchLen,  TempPos; 

return  '\x00'; 

int  Found; 

return  Txt [Pos]; 

TempStrl  =  new  char (Len  +  1]; 
memcpy (TempStrl, Txt, Len) ; 

1 

TempStrl [Len]  =  '\x00'; 

//  case-modification  methods 

TempStr2  =  new  char [Str. Len  +  1]; 

String  String: :ToUpper () 

memcpy (TempStr2, Str .Txt, Str . Len) ; 

( 

TempStr2 [Str.Len]  =  '\x00'; 

String  TempStr  =  ‘this; 

if  (Case  ==  SF  IGNORE) 

for  (unsigned  int  Pos  =  0;  Pos  <  Len;  ++Pos) 

( 

TempStr .Txt [Pos]  =  toupper (TempStr .Txt [Pos] ) ; 

strupr (TempStrl) ; 

return  TempStr; 

) 

strupr (TempStr2) ; 

) 

String  String: :ToLower () 

Pos  -  0; 

( 

TempPos  =  0; 

String  TempStr  =  ‘this; 

Found  =  0; 

for  (unsigned  int  Pos  =  0;  Pos  <  Len;  ++Pos) 

SearchLen  =  Str.Len; 

TempStr .Txt [Pos]  =  tolower (TempStr. Txt [Pos] ) ; 

LastPos  =  Len  -  SearchLen; 

return  TempStr; 

) 

while  ((TempPos  <=  LastPos)  44  IFound) 

{ 

if  (0  ==  strncmp (4 TempStrl [TempPos] ,TempStr2, SearchLen) ) 

End  Listing  Two 

( 

Pos  =  TempPos; 

Listing  Three 

Found  -  1; 

♦include  "String. hpp" 

) 

♦include  "stdio.h" 

else 

++TempPos; 

♦include  "stream. hpp" 

} 

int  main () ; 

delete  TempStrl; 
delete  TempStr2; 

void  print_string (String  S); 

return  Found; 

String  si; 

} 

String  s2("This  is  the  second  string!"); 

//  substring  deletion  method 

int  main() 

( 

void  String: :Delete (unsigned  int  Pos,  unsigned  int  Count) 

( 

unsigned  int  CopyPos; 

String  Is; 

String  ls2 ("Another  local  string"); 

if  (Pos  >  Len) 

unsigned  int  pos,  i; 

return; 

CopyPos  =  Pos  +  Count; 

char  ch; 

if  (CopyPos  >=  Len) 

si  =  s2; 

Txt [Pos]  =  0; 

Is  =  "This  is  the  local  string."; 

else 

print  string(sl) ; 

while  (CopyPos  <=  Len) 

print  string(s2); 

( 

print  string(ls) ; 

Txt [ Pos ]  =  Txt [ CopyPos ] ; 

print  string(ls2); 

++Pos; 

++CopyPos; 

cout  «  "\n"; 

} 

si  =  s2  +  Is; 

Len  -=  Count; 

Shrink  () ; 

print  string (si); 

} 

//  substring  insertion  methods 

si  =  "String  one  has  a  value."; 
print_string (si) ; 

void  String: : Insert (unsigned  int  Pos,  char  Ch) 

si  =  Sl  +  "****"; 

{ 

char  *  Temp; 

print_string{sl) ; 

if  (Pos  >  Len) 

s2  +=  "*****"; 

return; 

print  string(s2) ; 

if  (Len  ==  Siz) 

print_string(ls) ; 

Siz  +=  Alloclncr; 

s2  +=  Is; 

Temp  =  new  char [Siz]; 
memcpy (Temp, Txt, Len) ; 

print_string (s2) ; 

delete  Txt; 

Txt  =  Temp; 

cout  «  "\n"; 

} 

lf  ls2  ■ Flnd  1  "surf  uigunk" ,  pos)  i  (continued  on  page  70) 
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Listing  Three  (Listing  continued, 

text  begins  on  page  18.) 

printf ("first  search  =  %d\n",pos); 
if  (s2.Find("*****",pos) ) 

printf ("second  search  =  %d\n",pcs); 
if  (s2.Find(ls,pos) ) 

printf ("third  search  =  %d\n",pos); 
if  (s2 .Find (si, pos) ) 

printf ("fourth  search  =  %d\n",pos); 
ls2  = 

si . Insert  (10,'*'); 
si . Insert (15, ls2) ; 
print_string (si) ; 

si . Insert (si. Length (),'%'); 
si . Insert (si . Length (),'%'); 
si . Insert (si . Length () ,'%'); 
si . Insert (si .Length {) ,'%'); 
print_string  (si) ; 

for  (i  =  0;  0  !=  (ch  =  si ( i ] ) ;  ++i) 
putchar (ch) ; 
putchar (' \n' ) ; 

si. Insert (2, "<><><><><>") ; 
print_string  (si) ; 

sl.Delete(2, 10) ; 
print_string(sl) ; 

s2  =  si .ToUpper  () ; 
print_string(s2) ; 

s2  =  si .ToLower  () ; 
print_string  (s2) ; 

si  =  Empty  (); 
print_string (si) ; 

si  =  s2 .SubStr (2, 10) ; 
pnnt_string (si) ; 

return  0; 

void  print_string (String  S) 

char  *  cs; 
cs  =  S. Duped  ; 

cout  «  cs  «  "  Len  =  "  «  S. Length()  « 
delete  cs; 

) 

'  Siz  =  "  «  S. Sized  «  "\n"; 

End  Listings 

EVENT  SIMULATION 


Listing  One  (Text  begins  on  page  24.) 


File:  sim-sched.h 

process  spec  schedO  { 

trans  long  now()  /*  return  simulated  time 
trans  long  reqDelay (long  del); 

/*  request  delay  */ 


trans  long  wait (long  x) ;  /* 
trans  void  addUser();  /* 
trans  void  dropUser();  /* 
trans  void  passive ()?  /* 
trans  void  active ();  /* 


Listing  Two 

File:  sim-source.h 

process  spec  source ( 
process  sched  s, 
process  queue  outQ, 
long  meanlat,  /* 

long  meanServt,  /* 

long  nGen,  /* 

name_t  name) ;  /* 


wait  for  delay  */ 
add  client  */ 
drop  client  *1 
client  is  passive  */ 
client  is  active  */ 


End  Listing  One 


/*  scheduler  */ 

/*  output  queue  */ 
mean  inter-arrival  time  */ 
mean  service  time  */ 
number  to  generate  */ 
symbolic  name  */ 


Listing  Three 


File:  sim-server.h 

process  spec  server  ( 
process  sched  s, 
process  queue  inQ, 
process  queue  outQ, 
double  speed, 
name  t  name) ; 


End  Listing  Two 


scheduler  */ 
input  queue  */ 
output  queue  */ 
speed  of  server  */ 
symbolic  name  */ 


End  Listing  Three 


Listing  Four 

File:  sim-qltem.h 

typedef  struct  { 

/*  Public:  */ 

long  servt;  /*  service  time  for  job  */ 
long  arrive;  /*  time  job  arrived  */ 

/*  Private  to  queue  process:  */ 
long  qEnter;  /*  time  entered  queue  */ 
int  ticket;  /*  ticket  from  takeReq  */ 
int  gotltem;  /*  !=0  if  item  was  taken  */ 
)  qltem; 


Listing  Five 


File:  sim-queue.h 


process  spec  queue ( 
process  sched  s, 
int  maxSize, 
name_t  name) 

{ 

trans  int  itemCnt(); 
trans  void  addProd(); 
trans  void  dropProdO 
trans  void  addConsO; 
trans  void  dropConsf) 


/*  scheduler  */ 

/*  max  queue  size  */ 

/*  symbolic  name  */ 

/*  return  queue  size  */ 
/*  add  producer  */ 

/*  drop  producer  */ 

/*  add  consumer  */ 

/*  drop  consumer  */ 


/*  start  and  finish  put  request:*/ 
trans  int  putReq (qltem) ; 
trans  void  putWait(int,  qltem); 


/*  start  and  finish  take  request:*/ 
trans  qltem  takeReqO; 
trans  qltem  takeWait (int) ; 


End  Listing  Four 


Listing  Six 

File:  sim-stats.h 


typedef  struct  f 

long  nv;  /*  number  of  values  */ 

long  maxv;  /*  max  value  */ 

double  sumv;  /*  sum  of  values  */ 

double  sumsq;  /*  sum  of  squares  */ 

)  stats; 


void  stlnitO;  /* 
void  stValO;  /* 
double  stMeanO;  /* 
double  stSdevO;  /* 
long  erand();  /* 


initialize  structure  */ 
add  new  value  */ 
return  mean  value  */ 
return  standard  deviation  */ 
exponential  random  number  */ 


Listing  Seven 


File:  sim-main. cc 


name_t  makeName (name)  char  *name; 
{  name_t  ret; 

strcpy(ret.str,  name) ; 
return  ret; 


main  () 

{  process  sched  s; 

process  queue  ql,  q2; 
long  nGen=100000;  /*  number  of  jobs  */ 

long  servt=500;  /*  mean  service  time  */ 

long  iat=1000;  /*  mean  inter-arrival  */ 

/*  Create  virtual  time  scheduler.  */ 
s  =  create  schedO;  s.addUserO; 


/*  Create  queues  and  servers.  */ 

ql  =  create  queue (s,  100,  makeName ("Ql”) ) ; 
q2  =  create  queue (s,  100,  makeName ( "Q2”) ) ; 
create  source (s,  ql,  iat,  servt,  nGen, 
makeName ("Src") ) ; 
create  server (s,  ql,  q2,  0.5, 

makename ("Servl . 1") ) ; 
create  server  (s,  ql,  q2,  0.5, 

makename ("Servl .2") ) ; 
create  server (s,  q2,  c_nullpid,  1.0, 
makename ("Serv2") ) ; 

/*  Wait  for  all  processes  to  start.  */ 
delay  2.0;  s .dropUser () ; 

} 

Listing  Eight 

File:  si-source. cc 


process  body  source (s,  outQ,  meanlat, 

meanServt,  nGen,  name) 
{  stats  iat,  servt; 
qltem  item; 
long  i,  t; 

/*  Initialization  phase  */ 
s.addUser  {) ; 
outQ.addProdO ; 

stlnit  (&iat) ;  stlnit (&servt) ; 


End  Listing  Five 


End  Listing  Six 


End  Listing  Seven 
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/*  Main  processing  phase:  generate  jobs.  */ 
for  (i=l;  i  <=  nGen;  i++)  { 
t  =  erand(raeanlat) ; 
stVal (&iat,  t); 

item. arrive  =  s.wait (s.reqDelay(t) ) ; 
item.servt  =  erand (meanServt) ; 
stVal (iservt,  item.servt); 
qPut (outQ,  item) ; 

) 

/*  Termination  phase:  print  stats,  etc.  */ 
print  statistics; 

outQ.dropProd () ;  s.dropUser  () ;  End  Listing  Eight 


Listing  Nine 

File:  sim-server .cc 

process  body  server (s,  inQ,  outQ,  speed,  name) 

{  stats  sysTime;  /*  time-in-system  */ 
qltem  item; 
long  ts; 

s.addUserO;  stlnit  (&sysTime)  ; 
inQ.addCons () ; 
if  (outQ  !■  c_nullpid) 
outQ.addProdO  ; 

while  (qTake(inQ,  iitem) )  ( 

ts  =  s.wait (s.reqDelay (item. servt/speed) ) ; 
stVal (SsysTime,  ts  -  item. arrive) ; 
if  (outQ  !■  c_nullpid) 
qPut  (outQ,  item) ; 

} 


or  (q. nElem<q.max) : 

accept  putWait(qt,  item) 

suchthat  (qt  ==  q.pPut.acc) 

{  putltem(&q,  sitem); 
incTick (iq.pPut . acc) ;  ) 
or  (q.nElem>0  &&  q.pTake.acc==q.pTake.give) : 
accept  takeReqO 

(  treturn  takeltem (&q) ;  ) 
or  (q.nElem==0) : 
accept  takeReqO 

(  x. ticket  =  incTick (Sq.pTake .give) ; 
s.passive();  q.pTake.nPass++; 
treturn  x;  ) 
or  (q.nElem>0) : 

accept  takeWait(qt) 

suchthat  (qt  ==  q.pTake.acc) 

I  incTick  (Sq.pTake.acc) ; 
treturn  takeltem (Sq) ;  ) 
or  (q . nProd==0  &&  q.nElem==0) : 
accept  takeWait(qt) 

{  x.gotltem  =  0;  treturn  x;  } 

or  accept  itemCntO  (  treturn  q.nElem;  } 

or  accept  addConsO  (  q.nCons++;  ) 

or  accept  addProdO  (  q.nProd++;  ) 

or  accept  dropConsO  (  q.nCons — ;  ) 

or  accept  dropProdO  (  q.nProd — ;  ) 

) 

/♦On  EOF,  make  pending  takers  active.  */ 
if  (q.nProd==0  &&  q.nElem==0) 

for  (;  q.pTake.nPass  >  0;  q.pTake .nPass— ) 
s. active  () ; 

) 

print  statistics;  End  Listing  Twelve 


print  statistics; 
if  (outQ  !=  c_nullpid) 
outQ.dropProd () ; 
inQ.addCons () ;  s .dropUser () ; 


Listing  Ten 

File  sim-qPut.cc 

/*  Put  item  onto  queue;  wait  if  full.  */ 
void  qPut(q,  item) 

process  queue  q;  qltem  item; 

(  int  ticket  =  q.putReq(item) ; 
if  (ticket  >=  0) 

q.putWait (ticket,  item); 


/*  Set  *itemp  to  next  item;  wait  if  empty.  */ 
/*  Return  1  if  item  was  taken,  0  on  EOF  */ 
int  qTake(q,  itemp) 

process  queue  q;  qltem  *itemp; 

( 

♦itemp  =  q. takeReqO; 
if  (itemp->ticket  >=  0) 

♦itemp  =  q.takeWait (itemp->ticket) ; 
return  itemp->got!tem; 


Listing  Eleven 

File:  sim-qlnfo.h 

/*  *tInfo:  Describe  outstanding  tickets.  */ 
typedef  struct  ( 

int  acc;  /*  next  ticket  to  accept  */ 

int  give;  /*  next  ticket  to  give  out  */ 

int  nPass;  /*  pending  passive  clients  */ 
)  tlnfo; 


Listing  Thirteen 

File:  sim-qAux.cc 

End  Listing  Nine 

/*  Increment  ticket,  return  prev  value.  */ 
int  incTick (tp) 
int  *tp; 

(  int  t  =  *tp; 

♦tp  =  (t+1) % 1 0000 ; 
return  t; 


/*  Remove  and  eturn  the  next  item  in  the  queue.  */ 
qltem  takeltem(qp) 
qlnfo  *qp; 

( 

qltem  item; 

item  =  qp->items [qp->head) ; 
item. ticket  =  -1; 
item. got  Item  =  1; 

stVal (&qp->qTime,  qp->s.now()  -  item.qEnter) ; 
qp->nElem — ; 

qp->head  =  (qp->head+l)  4  qp->max; 
if  (qp-pPut  .r.Pass  >0) 

(  qp->s. active () ;  qp->pPut . nPass — ;  } 
return  item; 

End  Listing  Ten  I 

/*  Add  item  * itemp  to  queue.  */ 
void  putltem(qp,  itemp) 

qlnfo  *qp;  qltem  ‘itemp; 

I 

qp->items [qp->tail]  =  *itemp; 
qp->items [qp->tailj .qEnter  =  qp->s.now(); 
stVal (&qp->qSize,  qp->nElem) ; 
qp->nElem++; 

qp->tail  =  (qp->tail+l)  4  qp->max; 
if  (qp->pTake. nPass  >  0) 

l  qp-os. active o ;  qp->pTake. nPass— ;  )  End  Listing  Thirteen 


/*  qlnfo:  Describe  one  queue.  */ 
typedef  struct  { 


process 

sched  s; 

/* 

scheduler  process  ♦/ 

int 

max; 

/* 

max  queue  size  */ 

int 

nProd; 

/* 

number  of  producers  */ 

int 

nCons; 

/* 

number  of  consumers  */ 

name_t 

name  ; 

/♦ 

name  of  queue  */ 

stats 

qTime; 

/* 

time-in-queue  stats  */ 

stats 

qSize; 

/* 

for  queue  size  stats  *, 

int 

nElem; 

/* 

items  in  queue  ♦/ 

int 

head; 

/* 

index  head  of  queue  */ 

int 

tail; 

/* 

index  tail  of  queue  */ 

qltem 

♦items; 

/* 

alloc' d  array  of  items 

Describe  pending 

put, 

,  take  requests:  */ 

tlnfo  pPut,  pTake; 

)  qinfo;  End  Listing  Eleven 

Listing  Twelve 

File:  sim-queue.cc 

process  body  queue (s,  maxSize,  name) 
f  qlnfo  q;  qltem  x; 

initialize  qlnfo  structure; 
accept  addProdO  {  q.nProd++;  ) 

while  (q.nProd+q.nCons  >0)  { 
select  { 

(q.nElenKq.max  &&  q.pPut.acc==q.pPut .give) : 
accept  putReq(item) 

(  putltem(&q,  &item) ;  treturn  -1;  } 
or  (q.nElem==q.max) : 
accept  putReq(item) 

(  s.passiveO;  q.pPut.nPass++; 
treturn  incTick (Sq.pPut .give) ;  } 


Listing  Fourteen 

File:  sim-sched.cc 

process  body  sched() 

{  int  nUser,  nAct,  i; 

long  curTime  =  0;  /*  Current  simulated  time  */ 

ordered  list  of  pending  delay  requests; 

initialize  pending  delay  list  data  structures; 
accept  addUserO  (  nUser  =  nAct  =  1;  ) 
while  (nUser  >0)  { 
select  ( 

accept  addUserO  (  ++nUser;  ++nAct;  } 
or  accept  dropUser ()  (  — nUser;  — nAct;  ) 

or  accept  active ()  (  ++nAct;  ) 

or  accept  passive {)  (  — nAct;  ) 

or  accept  now()  (  treturn  curTime;  ) 

or  accept  reqDelay(x) 

(  add  request  for  curTime+x  to  pending  delay  list; 
nAct — ;  treturn  request -index;  ) 

) 

if  (nAct  ==  0  &&  pending  delay  list  is  not  empty)  ( 
curTime  =  time  of  request  at  head  of  list; 
nAct  =  number  of  processes  waiting  for  that  time; 
for  (i  =  1;  i  <=  nAct;  i++) 
accept  wait (x) 

suchthat  (x  ==  index-of-head-request) 

(  treturn  curTime;  ) 

discard  request  at  head  of  pending  delay  list; 

I 

) 


End  Listings 
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Listing  One  (Text  begins  on  page  42.) 


♦include  <malloc.h> 

♦include  <conio.h> 

♦include  <stdio.h> 

♦include  <string.h> 

♦include  <stdlib.h> 

♦define  Max_unget_buf fer 
♦define  Max_general_buffers 
♦define  MAX_f unctions 
/*  #define  Max  functions 


20000 

3000 

5000 

4000  */ 


♦define  Max_defined_functions  1400 
♦define  Max_files  1400 
♦define  Max_Recursion  50 

♦define  false  0 
♦define  true  1 
♦define  completed  2 

♦define  Escape  Oxlb 
♦define  Control  z  Oxla 


typedef  struct  the_Pages 

1 

int  on_this_page; 

struct  the_Pages  *next_page_ptr; 
I linked_pages_list; 


typedef  struct 

( 

char 

char 

int 

int 

}function_type; 

typedef  struct 

{ 

char 

char 

unsigned  int 
long 

} f ile_record_type; 
typedef  struct 


‘function  s_name ; 
*its_filename; 
is_referenced; 
static  function; 


*source_filename; 
*source_f ile_comment; 
line  count; 


/*  this  is  the  main  data  base 


file_record_type  *f ile_record_ptr; 
char  *defined_function; 

function_type  *ptr_to_function_table; 

int  number_of_function_calls; 

linked_pages_list  *ptr_to_page_list; 
int  number_of_references; 

int  overlay_number; 

)data_base_record_type; 


function_type  /*  6  */ 

“sorted_called_list_ptrs, 

*function_list, 

*  f  unct ion_l i s  t_pt  r ; 
int 

Max_functions, 
count_of_functions  =  0; 

flle_record_type  /*  14  */ 

*file_record_array, 

* f i le_record_a r ray_pt r ; 
int 

count_of_source_files  =  0; 

data_base_record_type  /*  20  */ 

*data_base_array, 

*data_base_array_ptr, 

“array_of_unused_ptrs_to_records, 

“array_of  _ptrs_to_records; 
int 

count_of_valid_records  =  0; 

char  *recursion_array [  Max_Recursion  ]; 
int  recursion_depth  =  0; 

char  nesting_display_buf fer [  Max_general_buffers  ]; 


char  target [  40  ]  =  "main"; 
FILE  ‘output  =  NULL; 


char  push_buffer[  Max_unget_buf fer  ]  =  {  0,  0,  0,  0  }; 
char  *push_buf fer_ptr; 


char  f ile_comment_buf fer [  Max_general_buffers  ]; 
int  first  comment; 


int  effective  width; 


page  =  1, 
line  =  0, 

def ined_page_width  =  80 
def ined_page_length  =  60 
def ined_left_margin  =  1, 
defined_right_margin  =  1, 
stats_only  =  false, 


g_lib_flag  =  false, 

g_comment_flag  =  false, 
g_dec_def_flag  =  false, 
ghelpflag  =  false, 

ibm_flag  =  true, 

g_quiet_flag  =  false, 

g_tech_flag  =  false, 

g_ov_flag  =  false, 

g_un_flag  =  false, 

target_flag  =  false; 

int  top_of_form_done; 
char  title []  = 

/*  mm/dd/yyO  hh:mm:ss0  */ 


:  -  (c)  1987,  1988  rev.  1.3" 


extern  function_type 

“sorted_called_list_ptrs, 

*function_list, 

*function_list_ptr; 
extern  file_record_type 
*file_record_array, 

*  f i le_record_a  r raypt r ; 
extern  data_base_record_type 

*data_base_array, 

*data_base_array_ptr, 

*  *  a  r ray_o  f _unu  sed_pt r  s_t o_reco  r ds , 
“array_of_ptrs_to_records; 

extern  char  *recursion_array [  ]; 
extern  int 

count_of_valid_records, 
Maxfunctions, 
count_of_functions, 
count_of_source_f iles; 
extern  int  page,  line,  recur sion_depth; 
extern  int  f irst_comment ; 
extern  char  nesting_display_buf fer [  ]; 
extern  char  top_bottom_line_of_box [  ); 
extern  FILE  ‘output; 
extern  char  push_buffer[  ]; 
extern  char  *push_buf fer_ptr; 
extern  char  file_comment_buf fer [  ]; 
extern  int  def ined_page_width; 
extern  int  def ined_page_length; 
extern  int  def ined_left_margin; 
extern  int  def ined_right_margin; 
extern  int  ef fective_width; 
extern  char  target!  ]? 
extern  int 
stats_only, 
g_lib_flag, 
g_comment_flag, 
g_dec_def_flag, 
g_help_f lag, 
ibm_f lag, 
g_quiet_flag, 
g_tech_f lag, 
g_ov_flag, 
g_un_flag, 
target_f lag; 

extern  int  top_of_form_done; 
extern  char  titled; 


Listing  Two 


End  Listing  One 


static  void  i 
static  void  i 
static  void  i 
static  void  i 
static  void  i 
static  void  i 
static  void  i 
static  void  i 
static  void  i 
static  void  i 
static  void  i 
static  void  i 
static  void  i 
static  void  i 
static  void  i 
int 


bump_line_count (  void  ); 
do_top_of_page (  void  ) ; 
deallocate_arrays {  void  ); 
allocate_arrays (  void  ); 
initialize_globals (  void  ); 
build_records_from_list (  FILE  *  ); 
sort_the_data_base_array (  void  ) ; 
count_all_defined_references (  void  ); 
show_function_relationships (  void  )  ; 
show_line_and_byte_counts (  void  ); 
show_sorted_function_list (  void  ) ; 
show_page_references (  void  ); 
show_unused_if_any (  ); 
show_library_functions (  void  ); 
show_files_leading_comments {  ); 
main(  int,  char  “  ); 


♦define  MAIN  1 
♦include  "cpheader.h" 

♦include  "time.h" 

extern  int  near  binary_search_sorted_data_base (  char  *  ); 

extern  void  near  build_box_parts (  int  ); 

extern  int  near  build_the_data_base (  char  *,  char  *  ); 

extern  void  near  check_for_new_page (  void  ) ; 

extern  int  near  doprint (  int  ) ; 

extern  void  near  nasty (  int  ); 

extern  void  near  process_arguments {  int,  int,  char  “,  int  ); 
extern  void  near  scan_for_static_or_global (  int  *,  int,  char 
extern  void  near  tab_to_left_margin (  FILE  *  ); 

static  void  near  allocate_arrays (  void  ); 

static  void  near  build_records_f rom_list {  FILE  *  ) ; 

static  void  near  bump_line_count (  void  ); 
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count_all_def inedreferences (  void  ); 
deallocatearrays (  void  ); 
do_top_of_page (  void  ) ; 
initialize_globals (  void  ); 
show_f iles_leading_comments (  void  ); 
show_function_relationships (  void  ); 
show_library_functions (  void  ); 
show_line_and_byte_counts (  void  ); 
show_page_references (  void  )  ; 
show_sorted_function_list  (  void  ); 
show_unused_if_any (  void  ); 
sort_the_data_base_array {  void  ); 
main(  int,  char  **  ); 


static  void  near  bump_line  count (  ) 

( 

top_of_form_done  =  false; 

++line; 

check_for_new_page() ; 
tab_to_left_margin (  output  ) ; 


static  void  near  do_top  of  page{  ) 

{ 

if (  !top  of_form_done  ) 

1 

top_of_form_done  =  true; 
line  =  9999; 
check_for_new_page () ; 
tab_to_left_raargin (  output  ); 


static  void  near  deallocate  arrays!  ) 

{ 

if  (  function_list  ) 

free!  function_list  ); 
if  (  file_record_array  ) 

free!  f ile_record_array  ); 
if {  data_base_array  ) 

free!  data_base_array  ); 
if(  sorted_called_list_ptrs  ) 

free!  sorted_called_li$t_ptrs  ); 
if(  array_of_ptrs_to_records  ) 

free!  array_of_ptrs_to_records  ); 


static  void  near  allocate  arrays!  ) 

{ 

unsigned  long  length; 

length  =  (unsigned  long) Max_f unctions  *  sizeof(  function  type  ); 
if !  length  >  65535  ) 

{ 

(void)printf (  "too  many  called  functions  {  go  to  huge  model  code 
exit!  1  ); 

} 

else 

if! 

! {  function_list  = 

(function_type  *)malloc(  (unsigned  int) length  ) 


(void)printf (  "No  room  for  function_list\n"  ); 
exit (  1  ) ; 


if{  !g_quiet_flag  &&  g_tech_flag  ) 

(void)printf (  "function  list  -  %lu  bytes  long\n",  length  ); 


length  =  (unsigned  long)Max_files  *  sizeof!  file_record  type  ); 
if!  length  >  65535  ) 

( 

(void)printf (  "too  many  files  (  go  to  huge  model  code  )\n"  ); 
exit!  1  ); 


!  (  file_record_array  = 

(file_record_type  *)malloc(  (unsigned  int) length  ) 


(void)printf (  "No  room  for  f ile_reccrd_array\n"  ); 
exit (  1  ) ; 

} 

else 

{ 

if!  !g_quiet_flag  &&  g_tech_flag  ) 

(void)printf  (  "file  record  array  =  %lu  bytes  long\n",  length  ); 


length  = 

(unsigned  long) Max_defined_f unctions  *  sizeof!  data_base_record_type) ; 
if!  length  >  65535  ) 

{ 

(void) printf (  "too  many  defined  functions  (  go  to  huge  model  code)\n"  ); 
exit (  1  ) ; 

( 

else 

if! 

! (  data_base_array  = 

(data_base_reccrd_type  *)malloc(  (unsigned  int) length  ) 


(void)printf (  "No  room  for  data_base_array\n"  ); 
exit  (  1  ) ; 

} 

else 

{ 

if(  !g_quiet_flag  &&  g_tech_flag  ) 

(void) printf (  "data  base  array  =  %lu  bytes  long\n”,  length  ); 


length  = 

(unsigned  long)Max_def ined_functions  *  sizeof!  data_base_record_type  *); 
if!  length  >  65535  ) 

( 

(void) printf ( 

"too  many  defined  functions  pointers!  go  to  huge  model  code  ) \n" 

)  ; 

exit  (  1  ) ; 

1 

else 
if  ( 

! {  array_of_ptrs_to_records  = 

(data_base_record_type  **)malloc(  (unsigned  int) length  ) 

) 

) 

{ 

(void) printf (  "No  room  for  *array_of_ptrs_to_records\n"  ); 
exit (  1  ) ; 


if(  !g_quiet_flag  &&  g_tech_flag  ) 

(void) printf (  "array  of  ptrs  to  data  base  =  %lu  bytes  long\n", 
length  ) ; 

} 

length  =  (unsigned  long) Max_functions  *  sizeof!  function_type  *  ); 
if!  length  >  65535  ) 

[ 

(void)printf ( 

"too  many  called  function  ptrs  (  go  to  huge  model  code  )\n" 

) ; 

exit  (  1  )  ; 

) 

else 

if! 

! (  sorted_called_list_ptrs  = 

(function_type  **)malloc(  (unsigned  int) length  ) 

) 

) 

( 

(void) printf (  "No  room  for  ptr  function_list\n"  ); 
exit  {  1  ) ; 

} 

else 

{ 

if!  !g_quiet_flag  &&  g_tech_flag  ) 

(void) printf (  "sorted  called  list  ptrs  =  %lu  bytes  long\n",  length); 
} 

I 

/*********.********♦*****.**.***.***♦**«********************************/ 

static  void  near  initialize_globals (  ) 

{ 

int  i; 
char  *cp; 

function_list_ptr  =  function_list; 
data_base_array_ptr  =  data_base_array; 
file_record_array_ptr  =  f ile_record_array; 

for!  i  =  0;  i  <  Max_Recursion;  ++i  ) 
recursion_array (  i  ]  =  NULL; 
build_box_parts (  ibm_flag  ); 

ef fective_width  =  /******  set  global  output  width  *********/ 

defined_page_width  -  def ined_left jnargin  -  def ined_right_margin; 
if!  ef fective_width  <  40  ) 

I 

(void) printf (  "\nThe  page  width  is  too  narrow!  needs  >  40  )."  ); 
exit (  1  )  ; 


cp  =  &title(  0  ];  I*  insert  date  and  nice  time  into  title  */ 
(void)_strdate (  cp  ); 
title [  81=''; 
cp  =  &title (  10  ) ; 

(void)_strtime (  cp  ); 


title[  15  ]  =  '  ' ;  /*  knock  off  seconds  */ 

title  [  16  ;  /*  put  am,  pm  here  */ 

title [  17  )  =  ' m' ; 
title!  18  1  =  '  '  ; 

i  =  atoi (  &title[  10  ]  );  /*  f/  military  to  civilian  time  */ 

title!  16  ]  =  (  i  <  12  )?  (char) 'a':  (char)'p'; 

if!  i  ==  0  ) 
i  =  12; 
if!  i  >=  13  ) 
i  -=  12; 

(void) sprintf (  &title[  10  ],  "%2d",  i  ); 
title!  12  ]  =  ' 

if  (  title [  10  ]  ==  '  0'  ) 
title!  10  1  =  '  '; 

) 

/*.*,*,.*********,**.*****..********.*******.*********************** 
static  void  near  build_records_f rom_list (  stream  ) 

FILE  ‘stream; 

! 

char  input_list_filename ( 129] ,  input_line [129] ,  overlay_n umber [129] ; 
int  1  ; 

while!  ! feof (  stream  )  ) 


Dr.  Dobb’s  C  Sourcebook,  Winter  1989/90 


266:  ( 

267!  input_list_filename [  0  ]  =  '\0'; 

268!  input_line[  0  ]  =  '  \0'; 

269!  overlay_number [  0  ]  =  '\0'; 

270 :  fgets(  input_line,  128,  stream  );  /*  ends  at  \n  or  eof  */ 

271 : 

2721  if  ( 

273!  (  1  =  strlen<  input_line  )  )  >  1  /*  ie  not  nul  string  */ 

274:  ) 

2751  ( 

276:  if{  input_line[  1  -  1  ]  ==  '\n'  ) 

277!  input_line[  1-1  ]  =  '\0'; 

2781 

279!  1  =  sscanf (  input_line,  "  %s  %s  ", 

280:  input_list_filename,  overlay_number 

281 :  )  ; 

282:  if (  !g_quiet_flag  S4  g_tech_flag  ) 

283:  { 

284!  (void) printf (  "pathname  =  %s  ",  input_list_filename  ); 

285!  if (  1  ) 

286:  (void) printf (  "overlay  #  =  %s  ",  overlay_number  ) ; 

287;  ) 

288!  (void) build_the_data_base (  input_list_filename,  overlay_number  ); 

289:  ) 

290 :  } 

2911  } 

292!  /*****************«*******************************»********************/ 

293! 

2941  static  void  near  sort_the_data_base_array (  ) 

295:  ( 

2961  int  i,  still_sorting_f lag; 

2971 

2981  for(  i  =  0,  data_base_array_ptr  =  data_base_array; 

2991  i  <  count_of_valid_records? 

300 1  ++i 

301 :  ) 

3021  array_of_ptrs_to_records(  i  ]  =  data_base_array_ptr++; 

303: 

3041  if(  !g_quiet_flag  ) 

3051  { 

306!  (void)printf (  "\n\nSorting  the  function  list...\n"  ); 

307:  (void)printf (  "  of  %d  functions'^",  count_of_valid_records  ); 

3081  } 

3091  still_sorting_flag  =  true; 

310 :  while (  still_sorting_f lag  ) 

311 

312 

313 

314 

315 

316 

317 

318 

319 

320 

321 

322 

323 

324 

325 

326 

327 

328 

329 

330 

331 

3321  static  void  near  count_all_defined_references () 

3331  1 

3341  register  int  count; 

3351  int  found; 

3361  register  function_type  *f_list_ptr; 

3371 

3381  f_list_ptr  =  function_list;  /*  the  full  list  */ 

3391 

3401  for(  count  =  0;  count  <  count  of  functions;  ++count  ) 

341 

342 

343 

344 

345 

346 

347 

348 

349 

350 

351 

352 

353 

3541  if(  !g_quiet_flag  &&  g_dec_def_flag  ) 

3551  (void) printf (  "\n"  ); 

3561  ) 

3571  /**********************************************************************/ 
3581 

359:  static  void  near  show_function_relationships (  ) 

360 :  ( 

361 :  int  found; 

3621  int  record_index; 

363: 

3641  found  =  binary_search_sorted_data_base (  target  );/*  w/o  knowing  fname  */ 
3651  /*  note  if  static,  will  find  random  one  if  more  than*/ 

3661  /*  one  with  same  name  */ 

3671  if(  found  >=  0  ) 

3681  ( 

3691  recursion_depth  =  0; 

370!  if (  ! g_quiet_flag  ) 

371 1  ( 

3721  (void) printf (  "Checking  for  usage... \n"  ); 

3731  ) 

374 1  count_all_defined_references  {) ; 

3751  nesting_display_buffer [  0  ]  =  '\0'; 

376!  if (  !g_quiet_f lag  ) 

3771  ( 

3781  (void) printf (  "Starting  the  printout ... \n"  ) ; 

3791  ) 


found  =  binary_search_sorted_data_base (  f_list_ptr->functions_name  )  ; 
if (  found  >=  0  ) 

scan_for_static_or_global (  sfound, 

f_list_ptr->static_f unction, 
f _1 i s  t_pt  r->functi ons_name , 
f_list_ptr->its_filename 

) ; 

if (  found  >=  0  ) 

array_of_ptrs_to_records (  found  ] ->number_of_references  += 
f_list_ptr->is_referenced; 

++f_list_ptr;  /*  for  all  defined  functions  */ 

) 


still_sorting_flag  =  false; 
if (  !g_quiet_f lag  ) 

( 

(void) print f (  ); 

) 

for(  i  =  0;  i  <  count_of_valid_records  -  1;  ++i  ) 

( 

if{  strcmpt  array_of_ptrs_to_records [  i  ] ->defined_function, 

array_of_ptrs_to_records [  i  +  1  ] ->def ined_function  )  >  0) 

{ 

still_sorting_flag  =  true; 

data_base_array_ptr  =  array_of_ptrs_to_records [  i  ]; 
array_of_ptrs_to_records [  i  ]  -  array_of_ptrs_to_records (  i  +  1]; 
array_of_ptrs_to_records [  i  +  1  ]  =  data_base_array_ptr; 


380 

381 

382 

383 

384 

385 

386 

387 

388 

389 

390 

391 

392 

393 

394 

395 

396 

397 

398 

399 

400 

401 

402 

403 

404 

405 

406 

407 

408 

409 

410 

411 

412 

413 

414 

415 

416 

417 

418 

419 

420 

421 

422 

423 


if (  !target_flag  )  /*  main  is  only  called  once  */ 

array  of_ptrs_to_records (  found  ]->number_of_references  =  1; 
line  =  0; 
if (  !stats_only  ) 

{ 

(void) doprint (  found  );  /*  of  target  function  */ 

f or (  record_index  =  0; 

record_index  <  count_of_valid_records; 

++record_index 

) 

{ 

(void) fprintf (  output,  "\n"  ); 

++line; 

if (  array_of_ptrs_to_records [  record_index  ] ->number_of_references> 
1 

) 

(void) doprint (  record_index  ); 

) 

) 

) 

else  /*  cant  find  target  */ 

( 

(void) printf (  "cant  find  %s,  exitting\n",  target  ); 
exit  (  1  )  ; 


static  void  near  show_line_and_byte_counts (  ) 

{ 

long  int  total_byte_count; 
long  int  total_line_count; 
int  i; 

file_record_array_ptr  *  file_record_array; 
do_top_of_page() ; 

(void) fprintf  (  output,  "File  statistics : \n"  ); 
bump_line_count () ; 
totaT_byte_count  =  01; 
total_line_count  =  01; 

for(  i  =  0;  i  <  count_of_source_f iles;  ++i  ) 

( 

(void) fprintf  (  output, 


424 

425 

426 

427 

428 

429 

430 

431 

432 

433 

434 

435 

436 

437 

438 

439 

440 

441 

442 

443 

444 

445 

446 

447 

448 

449 

450 

451 

452 

453 

454 

455 

456 

457 

458 

459 

460 

461 

462 

463 

464 

465 

466 

467 

468 

469 
470: 
471 
472: 
473: 
474: 
475: 
476: 
477: 
478: 
479: 
480 : 
481 : 
482: 
483: 
484: 
485: 
486; 
4871 
488: 
489: 
4901 
4911 


"%-40s  -  %8u  lines,  %121d  bytes\n", 
file_record_array_ptr->source_filename, 
f i le_record_a  r  ray_pt  r-> 1 ine_count , 
f ile_record_array_ptr->size 

) ; 

bump_line_count () ; 

total_byte_count  +=  f ile_record_array_ptr->size; 
total_line_count  +=  f ile_record_array_ptr->line_count; 
++file_record_array_ptr; 

) 

(void)fputc(  '\n',  output  ) ; 
bump_line_count () ; 

(void) fprintf {  output,  "Totals :\n"  ); 
bump_line_count {) ; 

/******  "%-40s  -  %8u  lines,  %121d  bytes\n",  *******/ 

(void) fprintf (  output,  "%4d  files%-30s  -  %81d  lines,  %121d  bytes\n", 

count_of_source_files,  ”  ",  total_line_count,  total_byte_count 
) ; 

bump_line_count () ; 

(void)fputc(  '\n',  output  ); 
bump_line_count () ; 

(void) fprintf (  output, 

"  %d  defined  functions  found. \n",  count_of_valid_records 

)  ; 

bump_line_count () ; 

(void) fprintf (  output,  "Averages : \n"  ); 
bump_line_count () ; 

(void) fprintf (  output, 

"%6d  lines/file,  %6d  functions/file,  %6d  lines/function\n", 
(int)  (  total_line_count  /  count_of_source_f iles  ), 

(int)  (  count_of_valid_records  /  count_of_source_f iles  ), 
(int)  (  total_line_count  /  count_of_valid_records  ) 


) ; 


static  void  near  show_sorted_function_list (  ) 

( 

int  i,  record_index; 
long  reference_total  =  0; 

do_top_of_page () ; 

(void) fprintf (  output,  "Function  index: \n"  ); 
bump_line_count () ; 

if{  g_ov_flag  ) 

(void) fprintf (  output,  "%-39s  %-28s  %s  %s\n", 

"function",  "in  file”,  "ov#",  "refs"  ); 

else 

(void) fprintf (  output,  ”%-39s  %-28s  %s\n", 

"function",  "in  file",  "refs"  ); 

bump_line_count () ; 

for  (  i  =  0;  i  <  ef fective_width;  ++i  ) 

(void)fputc(  output  ); 

(void) fprintf (  output,  "\n"  ); 
bump_line_count () ; 

for(  record_index  =  0; 

record_index  <  count_of_valid_records; 

++record_index 

) 

1 

data_base_array_ptr  =  array_of_ptrs_to_records [  record_index  J; 
if (  data_base_array_ptr->number_of_references  >  0  ) 
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Listing  Two  (Listing  continued,  text  begins  on  page  42.) 


492 

493 

494 

495 

496 

497 

498 

499 

500 

501 

502 

503 

504 

505 

506 

507 

508 

509 

510 

511 

512 

513 

514 

515 

516 

517 

518 

519 

520 

521 

522 

523 

524 

525 

526 

527 

528 

529 

530 

531 

532 

533 

534 

535 

536 

537 

538 

539 

540 

541 

542 

543 

544 

545 

546 

547 

548 

549 

550 

551 

552 

553 

554 

555 

556 

557 

558 

559 

560 

561 

562 

563 
564i 
5651 
566! 

567 

568 

569 

570 

571 

572 

573 

574 

575 

576 

577 

578 

579 

580 

581 

582 

583 

584 

585 

586 

587 

588 

589 

590 

591 

592 

593 

594 

595 

596 

597 

598 

599 

600 
601 
602 


{ 

if (  g_ov_flag  &&  data_base_array_ptr->overlay_number  ) 

(void) fprintf (  output,  "%-7s%-32s  %-28s  %3d  %d\n", 

(  data_base_array_ptr->static_definition  )? 
"static": 

data_base_array_ptr->defined_f unction, 

(  data_base_array_ptr->f ile_record_ptr  ) ->source_filename, 
data_base_array_ptr->overlay_number, 
data_base_array_ptr->number_o preferences 

)  ; 

else 

(void) fprintf (  output,  "%-7s%-32s  l-28s  %d\n", 

{  data_base_array_ptr->static_definition  ) ? 
"static": 

data_base_array_ptr->defined_f unction, 

(  data_base_array_ptr->file_record_ptr  ) ->source_filename, 
data_base_array_ptr->number_of_references 

)  ; 

reference_total  +=  (long) data_base_array_ptr->number_of_references; 
bump_line_count ( ) ; 


(void) fprintf (  output,  "%-7s$-32s  %-28s 


bump_line_count () ; 

(void) fprintf {  output,  "%-7s%-32s  %-28s  %ld\n", 

"  ",  "  ",  "total  ",  reference_total 

) ; 

bump_line_count () ; 


static  void  near  show_page_references (  ) 

( 

int  pmax;  /*  max  x  ref  columns  */ 

int  i,  pent; 
linked_pages_list  *p; 

if  (  !stats_only  &&  (  defined  page  length  >  0  )  ) 

{ 

pmax  =  (int)  (  ef fective_width  -  7  -  32  -  2  )  /  5; 
do_top_of_page () ; 

(void) fprintf (  output,  "Function  cross  reference : \n"  ); 
bump_line_count () ; 

for(  i  =  0;  i  <  count_of_valid  records;  ++i  ) 

I 

data_base_array_ptr  =  array_of_ptrs_to_records [  i  ]; 
if (  data_base_array_ptr->number  of  references  >  0  ) 

I 

(void) fprintf (  output,  "%-7sl-32s-  ”, 

(  data_base_array_ptr->static_definition  )? 
"static":  "", 

data_base_array_ptr->defined_function  ) ; 
p  =  data_base_array_ptr->ptr_to_page  list; 
if  (  p  ) 

{ 

pent  =  0; 

while  (  p->next_page_ptr  ) 


(void) fprintf (  output, 
p  =  p->next_page_ptr; 
++pcnt; 

if (  pent  >=  pmax  ) 


”%4d,",  p->on_this_page  ); 


) 


(void)fputc(  '\n',  output  ); 
bump_line_count () ; 

(void) fprintf (  output,  "%7s%32s 
pent  =  0; 

) 


(void) fprintf (  output,  "%4d\n",  p->on_this_page  ); 
\n"  )  ; 


else 

(void) fprintf (  output 
bump_line_count ()  ; 

I 


static  void  near  show_unused_if_any (  ) 

( 

int  i,  unused_count,  unused_index,  count,  still_sorting_f lag; 
data_base_record_type  **unused_list_ptr_ptr,  *unused_list_ptr; 

do_top_of_page ( )  ; 

(void) fprintf (  output,  "Un-used  function  list:\n"  ); 
bump_line_count () ; 

unused_count  =  0; 

for(  i  =  0;  i  <  count_of_valid_records;  ++i  ) 

( 

data_base_array_ptr  =  array_of_ptrs_to_records [  i  ]; 
if(  ! data_base_array_ptr->number_of_references  ) 

{ 

++unused_count ; 
if (  !g_un_flag  ) 

( 

(void) fprintf (  output, 

"%-7s%-32s-  %-33s\n", 

(  data_base_array_ptr->static_definition  )? 
"static":  "", 

data_base_array_ptr->defined_f unction, 

(  data_base_array_ptr->f ile_record_ptr  ) ->source_f ilename 
) ; 

bump_line_count {) ; 

) 


if (  g_un_flag  ) 


/*  show  sorted  */ 


if(  unused_count  ) 

{ 

if  ( 

! (  array_of_unused_ptrs_to_records  = 

(data_base_record_type  **)malloc(  (unsigned  int) unused_count) 

) 

(void) printf (  "No  room  for  *array_of_unused_ptrs_to_records\n") ; 
else 
( 

unused_index  =  0; 

for(  i  =  0;  i  <  count_of_valid_records;  ++i  ) 

data_base_array_ptr  =  array_of_ptrs_to_records [  i  ]; 
if (  !data_base_array_ptr->number_of_references  ) 

(  /*  first  just  collect  them  */ 

array_of_unused_ptrs_to_records[  unused_index++  ]  = 
da t  a_ba  se_a  r  r  a  y_pt  r ; 

}  /*  so  now  there  are  unused_index  of  them*/ 

unused_list_ptr_ptr  =  array_of_unused_ptrs_to_records; 
still_sorting_flag  =  true; 
if(  unused_count  >  1  ) 

( 

while (  still_sorting_flag  ) 

( 

still_sorting_f lag  =  false; 

if (  !g_quiet_flag  &&  g_tech_flag  ) 

(void) printf (  ”.%d  \r",  count  ); 

for(  count  =  0;  count  <  unused_count  -  1;  ++count  ) 

( 

if (  strcmp(  unused_list_ptr_ptr [  count  )-> 

file_record_ptr->source_f ilename, 
unused_list_ptr_ptr [  count  +  1  ] -> 
file_record_ptr->source_f ilename 
)  >  0 

) 

1 

still_sorting_flag  =  true; 

unused_list_ptr  =  unused_list_ptr_ptr (  count  ] ; 
unused_list_ptr_ptr [  count  )  = 

unused_list_ptr_ptr [  count  +  1  ]; 
unused_list_ptr_ptr [  count  +  1  ]  =  unused_list_ptr; 


for(  i  =  0;  i  <  unused_count;  ++i  ) 

I 

(void) fprintf  (  output, 

"%-7s%-32s-  %-33s\n", 

(  unused_list_ptr_ptr [  i  ] ->static_def inition) ; 
"static":  "", 

unused_list_ptr_ptr [  i  ] ->def ined_function, 

(  unused_list_ptr_ptr [  i  J->f ile_record_ptr  ) ->source_f ilename 
) ; 

bump_line_count ( ) ; 

) 


) 


) 


if (  !unused_count  ) 

( 

tab_to_left_margin (  output  ); 

(void) fprintf (  output,  "No  un-used  functions  in  the  list.\n"  ); 
bump_line_count () ; 

) 

else 

( 

(void) fprintf (  output,  "%-7s%-39s-  %d\n",  "totals",  unused_count) ; 
bump_line_count () ; 

) 

) 

/******.,.*.,.*********.******.****,**********************************/ 

static  void  near  show_library_functions (  ) 

< 

register  int  count; 

int  found,  total,  still_sorting_f lag,  x_count,  final_count,  final_call; 
function_type  * *f_list_ptr_ptr,  *f_list_ptr; 

if(  g_lib_flag  ) 

i 

if (  !g_quiet_flag  &&  g_tech_flag  ) 

(void) printf (  "collecting  library  functions ... \n"  ); 
do_top_of_page () ; 

(void) fprintf (  output,  "Library  functions : \n"  ); 
bump_line_count ( ) ; 

total  =  0; 

f_list_ptr  =  function_list; 

for(  count  =  0;  count  <  count_of_f unctions;  ++count  ) 

( 

i f (  ! f_list_ptr->static_function  ) 

< 

if  ( 

(  found  = 

binary_search_sorted_data_base (  f_list_ptr->functions_name) 
)  <  0 

) 

sorted_called_list_ptrs |  total++  ]  =  f_list_ptr; 


++f_list_ptr; 


/*  for  all  called  functions  */ 


if(  !g_quiet_flag  iS  g_tech_flag  ) 

(void)printf (  "gathering  identical  library  functions ... \n”  ); 
final_count  =  total;  /*  number  of  calls  to  be  collected  and  sorted*/ 
f_list_ptr_ptr  =  sorted_called_list_ptrs; 
f or (  count  =  0;  count  <  (  total  -  1  );  ++count  ) 
t 

for(  x  count  =  count  +  1;  x  count  <  total;  ++x  count  ) 
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718: 

1 

7i9: 

if (  (  f  list_ptr  ptr[  count  ]->functions  name[  0  ]  !=  '\0 

)  && 

720: 

!strcmp(  f  list_ptr  ptr[  count  )->functions  name, 

721 

f  list  ptr  ptr(  x  count  )->functions  name  ) 

7221 

) 

723: 

( 

724: 

f  list  ptr  ptr(  count  ]->is  referenced  += 

725! 

f  list  ptr_ptr[  x  count  ]~>is  referenced; 

726! 

f  list  ptr  ptr[  x  count  ]->functions  name[  0  ]  =  '\0'; 

727: 

— final  count; 

7281 

} 

729! 

> 

730 : 

) 

731 

7321 

if {  !g  quiet  flag  &&  g  tech  flag  ) 

7331 

< 

7341 

(void)printf {  "\nSorting  the  library  function  calls... \n"  ); 

7351 

) 

7361 

7371 

f  list  ptr  ptr  =  sorted  called  list  ptrs; 

738: 

still  sorting  flag  =  true; 

739: 

while (  still  sorting  flag  ) 

740 : 

1 

741 

still  sorting  flag  =  false; 

742: 

if(  !g  quiet  flag  &&  g  tech  flag  ) 

743: 

(void) print f (  ".%d  \r",  count  ); 

744  : 

for{  count  =  0;  count  <  total  -  1;  ++count  ) 

745: 

{ 

746: 

if (  strcmp(  f  list  ptr  ptr[  count  ]->functions  name, 

747: 

f  list  ptr  ptr [  count  +  1  ]->f unctions  name  ) 

>  0 

748: 

1 

749: 

still  sorting  flag  =  true; 

750 : 

f  list_ptr  =  f  list  ptr  ptr[  count  ]; 

751 : 

f  list  ptr  ptr (  count  ]  =  f  list  ptr  ptr(  count  +  1  ); 

752: 

f  list  ptr  ptr(  count  +  1  ]  =  f  list _ptr; 

753: 

} 

754: 

} 

755: 

) 

756: 

if (  !g  quiet  flag  &&  g  tech  flag  ) 

757: 

(void) print f (  "\n"  ); 

758: 

759: 

(void) fprintf (  output,  "%-32s  %-28s\n". 

760 : 

"library  function",  "calls"  ); 

761 

bump  line  count (); 

762: 

763: 

for (  count  =  0;  count  <  effective  width;  ++count  ) 

764: 

(void)fputc(  '  output  ); 

765; 

(void) fprintf (  output,  "\n"  ); 

766: 

bump  line  count (); 

767; 

768: 

final  call  =  0; 

769: 

f  list  ptr  ptr  =  sorted  called  list  ptrs; 

770 : 

for(  count  =  0;  count  <  total;  ++count  ) 

771 : 

if(  (  *f  list  ptr  ptr  )->functions  name[  0  )  !=  '\0'  ) 

772! 

773: 

{ 

774: 

(void) fprintf (  output,  "%-32s  %d\n", 

775: 

(  *f  list  ptr  ptr  )->functions  name, 

776! 

(  *f  list  ptr  ptr  )->is  referenced 

777: 

); 

778: 

final  call  +=  (  *f  list  ptr  ptr  )->is  referenced; 

779: 

bump  line  count  (); 

780 : 

) 

781 : 

++f  list  ptr  ptr; 

782: 

> 

783: 

(void) fprintf  (  output,  "Totals:\n"  ); 

784: 

bump  line  count  (); 

785 : 

(void) fprintf  (  output,  "%6d  %-25s  %d  calls. \n", 

786: 

final  count,  "library  functions,",  final  call 

787: 

); 

788: 

bump  line  count  (); 

789: 

1 

790 : 

} 

791 : 

****/ 

792: 

793: 

static  void  near  show  files  leading  comments (  ) 

794; 

( 

795: 

int  i; 

796: 

char  *cp; 

797: 

798: 

i f (  g  comment  flag  1 

799: 

{ 

800 : 

do  top  of  paged; 

801 : 

(void) fprintf (  output,  "File  comments :\n"  ); 

802: 

bump  line  count (); 

803: 

file  record  array  ptr  =  file  record  array; 

804; 

for(  i  =  0;  i  <  count  of  source  files;  ++i  ) 

805: 

( 

806: 

(void) fprintf (  output,  "%40s\n", 

807: 

file  record  array  ptr->source  filename 

808: 

); 

809; 

bump  line  count (); 

810 : 

cp  =  file  record  array  ptr->source  file  comment; 

811 : 

while  (  *cp  ) 

812: 

< 

8i3: 

(void) fprintf  (  output,  "%c",  *cp  ); 

814 : 

if (  *++cp  ==  ' \n'  ) 

sis: 

( 

816: 

bump  line  count (); 

817: 

1 

818: 

) 

819: 

++file  record  array  ptr; 

*/ 

820 : 

do  top  of  paged;  /*  one  page  per  comment  at  least 

821 : 

) 

822: 

) 

823: 

} 

824; 

*****/ 

825: 

826: 

int  main(  argc,  argv  ) 

827: 

char  **argv; 

828: 

int  argc; 

829: 

f 

830 : 

int  index,  in  error  =  false,  out  error  =  false; 

831 : 

FILE  ‘stream; 
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Listing  Two  (Listing  continued,  text  begins  on  page  42.) 


832 

833 

834 

835 

836 

837 

838 

839 

840 

841 

842 

843 

844 

845 

846 

847 

848 

849 

850 

851 

852 

853 

854 

855 

856 

857 

858 

859 

860 
861 
862 

863 

864 

865 

866 

867 

868 

869 

870 

871 

872 

873 

874 

875 

876 

877 

878 

879 

880 
881 
882 

883 

884 

885 

886 

887 

888 

889 

890 

891 

892 

893 

894 

895 

896 


nasty (  argc  ) ; 

(void) printf (  "\ncp  -  ver.  1.3,  (C) 1 987 ,  1988  Stewart  A.  Nutter\n"  ); 

(void) printf (  "  extended  and  corrected  by  Ron  WinterXn"  ); 

index  =1; 

if(  !(  stream  =  fopen(  argv[  index  ),  "rt"  )  )  ) 
in_error  =  true; 
else 

++ index; 
if( 

(  argc  >  index  )  4  4 
( 

(  argv[  index  ](  0  ]  !='/'  )  44  (  argv{  index  ](  0  )  ) 

) 


output  =  fopen (  argv[  2  ],  "w+"  );  /***** 

++ index; 

) 

else 

output  =  fopen (  "prn",  "w+"  );  /***** 

if (  ! output  ) 

out_error  =  true; 

Max_functions  *  MAX_f unctions; 
process_arguments (  index,  argc,  argv,  in_error  ! 
if(  in_error  ) 

{ 

(void) printf (  "\n  can't  open  input  list  %s\n" 
exit  (  1  ) ; 

) 

if (  out_error  ) 


«««« 


wt+  ««« 


out  error  ) ; 


argv[  1  )  ); 


(void) printf (  "\n  can't  open  output  file,  error  %s\n",  strer-ror (errno) ) ; 
exit {  1  ); 

) 

allocate_arrays (  ); 
initialize_globals (  ); 

(void) printf (  "\n"  ); 

build_records_from_list (  stream  ); 
sort_the_data_base_array (  ) ; 
if (  !g_quiet_flag  ) 

( 

(void) printf (  "\n"  ); 

) 

top_of_form_done  =  false; 
show_function_relationships  (  ); 
show_page_references (  ) ; 
show_line_and_byte_counts (  ); 
show_sorted_function_list (  ); 
show_unused_if_any (  ); 
show_library_f unctions (  ); 
show_files_leading_comments (  ) ; 
deallocate_arrays (  ); 

/******«******  done  *****************/ 

(void) fprintf (  output,  "%c",  0x0c  );  /*  ff  */ 

return  false;  /*  ok  */ 

) 


Listing  Three 


End  Listing  Two 


cpinput.c 

void  near  nasty (  int  ); 

void  near  process_arguments (  int,  int,  char 

#def ine  MAIN  0 
#include  "cpheader .h" 

void  near  nasty (  int  ); 

void  near  process_arguments (  int,  int,  char 


void  near  nasty (  argc  ) 
int  argc; 


if (  argc  <  2  ) 


(void) printf (  "\ncp  listfile  (  outfile  ]  [\n"  ); 
(void) printf ( 

/p:nn  /w:nn  /m:nn  /r:nn  /t:main  /f:nnnn\n" 

)  ; 

(void) printf ( 

/I  /n  /s  /q  /d  /c  /h  /x\n" 

) ; 

]\n\n"  ); 


=  prn\n"  )  ; 

=  %3d  [  0,  50  -255  ]\n 


(void) printf 
(void) printf ( 

"  outfile 
(void) printf ( 

"  p:  page  length 

) ; 

(void) printf ( 

"  w:  page  width 

) ; 

(void) printf ( 

"  m:  left  margin 

) ; 

(void) printf ( 

"  r:  right  margin 

) ; 

(void) printf ( 

"  t:  target  function  =  %s\n”,  target 

) ; 

(void) printf ( 


=  %3d 


=  %2d 


=  %2d 


de  f ined_page_lengt h 
[  80  -  255  ]\n",  def ined_page_width 
(0-30  ]\n",  def ined_left_margin 
[0-30  ]\n",  def ined_right_margin 


2  -  5461  ]\n",  MA> 


"  f:  #  of  function  calls  =  %4d 

)  ; 

(void) printf ( 

"  n:  normal  characters)  ie  not  ibm  character  graphics 
)  ; 

(void) printf { 

"  1  output  library  functionsXn" 

) ; 

(void) printf ( 

"  c  output  fileX's  1st  commentXn" 

)  ; 

(void) printf ( 

"  s  output  statistics  onlyXn" 

) ; 

(void) printf ( 

"  d  show  declarations  and  def initionsXn" 

); 

(void) printf ( 

"  o  show  overlay  informationXn" 

)  ; 

(void) printf ( 

"  u  show  unused  sorted  by  filenameXn" 

) ; 

(void) printf ( 

"  q  show  no  messagesXn" 

) ; 

(void) printf ( 

"  h  show  more  helpXn" 

) ; 

(void) printf ( 

"  x  show  tech  infoXn" 

); 

(void)printf (  "\n"  ); 
exit (  0  ) ; 

} 

) 

/******.*******************.************,*,****************** 
void  near  process_arguments  (  index,  argc,  argv,  an_error  ) 
int  index,  argc,  anerror; 
char  **argv; 

1 

char  c; 
int  i,  tmp; 

for(  i  =  index;  i  <  argc;  ++i  ) 

( 

if(  (  argv(  i  )(  0  )=='/'  )  (  argv[  i  ][  0  ]  ==  '-'  ) 

{ 

c  =  (char) tolower (  (int) argv [  i  )[  1  )  ); 
switch  (  c  ) 

( 

case  ' n' : 

ibm_flag  =  (  ibm_flag  )?  false:  true; 
break; 
case  ' 1' : 

g_lib_flag  =  (  g_lib_flag  )?  false:  true; 
break; 
case  ' c' : 

g_comment_f lag  =  (  g_comment_flag  )?  false:  true; 
break; 
case  'd' : 

g_dec_def_flag  =  (  g_dec_def_f lag  )?  false:  true; 
break; 
case  ' s' : 

stats_only  =  (  stats_only  )?  false:  true; 
break; 
case  ' q' : 

g_quiet_flag  =  (  g_quiet_flag  )?  false:  true; 
break; 
case  ' o' : 

g_ov_flag  =  true; 
break; 
case  ' u' : 

g_un_flag  =  true; 
break; 
case  ' h' : 

g_help_flag  =  true; 
break; 
case  ' x' : 

g_tech_flag  =  true; 
break; 
default : 

if(  (  strlen(  argv(  i  ]  )  >  3  )  44  (  argv[  i  )[  2  ] 

( 

tmp  =  atoi(  4argv[  i  ][  3  ]  ); 
switch (  c  ) 

{ 

case  'p' : 

if (  (  (  50  <  tmp  )  4&  (  tmp  <  256  )  )  ! !  ( 
defined_page_length  =  tmp; 
break; 
case  'm'  : 

if(  (  0  <=  tmp  )  44  (  tmp  <=  30  )  ) 
def ined_left_margin  =  tmp; 
break; 
case  ' r' : 

if  (  (  0  <=  tmp  )  44  (  tmp  <=  30  )  ) 
def ined_right_margin  =  tmp; 
break; 
case  '  t '  : 

(void) strcpy (  target,  4argv[  i  ](  3  ]  ); 
target_flag  =  true; 
break; 
case  'w' : 

if(  (  79  <  tmp  )  44  (  tmp  <  256  )  ) 
def ined_page_width  =  tmp; 
break; 
case  ' f ' : 

if  (  (  1  <  tmp  )  44  (  tmp  <  5462  )  ) 
Max_functions  =  tmp; 
break; 
default : 

(void) printf ( 


;_functions 

)\n" 


) 


tmp  ==  0) ) 
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158 

159 

160 
161 
162 

163 

164 

165 

166 

167 

168 

169 

170 

171 

172 

173 

174 

175 
176! 
177: 
178! 
1791 
180 : 
i8i : 
182: 
183: 
184! 
185! 
186! 
1871 
188: 
189: 

190 : 
191 : 

192! 

1931 

194i 

195: 

196: 

197: 

198: 

199: 

200 : 
201 : 
202: 
203: 
204; 
205: 
206: 
207: 
208: 
209: 

210 : 

2ii : 
212: 
213: 
214: 
215! 
216: 
217: 
218: 
219: 
220 : 
221 : 
222: 
223: 
224! 
225: 
226: 
227! 
228: 
229! 
230 : 
231 : 
232: 
233! 
2341 
235! 
2361 
237: 
238! 
239! 
240 : 

241 : 

242: 
243! 
244  : 
245; 
246; 
247! 
248: 
249i 
250 : 

251 : 

252: 
253: 
254: 
255: 
256: 
257: 
258: 
259! 
260 : 
261 : 
262: 
263: 
264! 
265: 
266! 
267: 
268: 
269! 
270 : 


"\nUnknown  argument  character:  %c,  ignored! \n”, 
argv [  i  ] [  1  ] 

)  ; 

break; 

)  /*  end  of  switch  on  character  after  /  or  -  */ 

}  /*  end  of  if  : something  */ 

else 

(void)printf (  "\nMissing  :  for  argument  %s,  ignored! \n", 
argv[  i  ]  ); 

break; 

}  /*  end  of  switch  on  character  after  /  or  -  */ 

}  /*  end  of  if  /  or  -  */ 

:  else 

!  (void)printf (  "\nUnknown  argument:  %s,  ignored!\n",  argv[  i  ]  ); 

!  }  /*  end  of  for  loop  on  arguments  */ 

!  if (  g_tech_flag  ) 

:  ( 

(void)printf (  "\n"  ); 

(void)printf (  "Notes:  1.  Max  recursive  function  displacement  of%d.\n", 
Max_Recursion 

); 

(void) printf ( 

11  2.  Max  #  of  unique  function  calls  per  defined  function\n\ 

for  all  defined  functions  is  %d.\n", 

Max_functions  ) ; 

(void)printf (  "  3.  Max  #  of  defined  functions  is  %d.\n", 

Max_defined_functions  ) ; 

(void) printf {  "\n"  ); 

(void) printf (  "sizeof () \'s:\n"  ); 

(void) printf ( 

"  function  table  =  %u,  contents  -  %u,  data  base  =  %u,\ 
database  =  %u,  lib  =  %u\n", 
sizeof (  function_type  ), 
sizeof (  file_record_type  ), 
sizeof (  data_base_record_type  ), 
sizeof (  array_of_ptrs_to_records  ), 
sizeof (  sorted_called_list_ptrs  ) 

) ; 

(void)printf (  "\n"  ); 

(void) printf ( 

"The  program  will  tend  to  show  certain  VcV  functions  as  unused. \n")  ; 
(void) printf ( 

"1.  defined  functions  assigned  to  declared  pointers  to  functionnames\n"  ); 
(void) printf ( 

"  &  executed  as  pointers  to  those  function  names  won't  be  seen.Xn"); 

(void)printf ( 

"2.  #if(s)  controlling  the  generation  of  code  especially  with\n"  ); 

(void) printf { 

"  braces (  (  )  )  in  the  conditional  code  section  will  especially\n") ; 
(void) printf ( 

"  screw  up  if  there  is  an  #else  code  part.  This  program  willwork\n"  ); 
(void) printf ( 

"  on  both  code  parts  of  the  conditional  and  most  probably  get  out-\n"  ) , 
(void) printf ( 

"  of  sync  with  braces.  You  might  preprocessor  pass  compile\n"  ); 

(void) printf { 

"  and  heave  it\'s  output  files  as  input  files  at  this  program. \n") ; 
(void) printf ( 

"3.  #define(s)  expand  to  functions  and  call  functions  will  also\n"  ); 
(void)printf ( 

"  be  neglected.  The  preprocessor  may  be  used  as  stated  above. \n"); 

(void)printf ( 

"\n"  ) ; 

******/ 

(void) printf  (  "\n"  ); 

1 

if (  g_help_flag  ) 

( 

(void) printf  (  "\n"  ); 

(void)printf ( 

"The  listfile  argument  is  an  ascii  text  file  containing  the  listof\n" 

)  ; 

(void) printf ( 

"filenames  to  process,  1  filename/line  (optional  overlay  number. )\n" 

); 

(void) printf ( 

"The  output  file  may  be  a  device  or  a  filename.  If  there  is  no\n" 

) ; 

(void) printf ( 

"output  filename,  \'prn\'  is  assumed.  Note  that  one  may  putV con\' \n" 

) ; 

(void) printf ( 

"here  and  view  the  output  of  the  program  before  printing  or  saving\n" 

)  ; 

(void) printf ( 

"to  a  filename. \n" 

) ; 

(void)printf  ( 

"Also  note  that  the  output  filename  and  the  input  filenames  in  the\n" 

)  ; 

(void) printf ( 

"listfile  may  be  full  pathnames  with  drives  and  or  paths. \n" 

)  ; 

(void) printf (  "/  arguments  accept  the  alternate  -  form.Xn"  ); 

(void) printf (  "For  example:  cp  x  y  -s,  cp  /h,  cp  x  -x  /d  -t: junk\n") ; 

(void) printf (  "arguments  may  be  in  upper  or  lower  case.Nn"  ); 

(void)printf (  "Note  that  the  target  function  is  case  sensitive\n"  ); 
(void)printf (  "since  it  is  a  \'c\'  function  name.Xn"  ); 

(void) printf (  "\n"  ); 

) 

if (  an  error  ) 


Listing  Four 


( 

if(  g_help_flag 
exit (  0  ) ; 
else 

(void) printf (  "Oops 

) 


g_tech_flag  ) 

)  ; 


End  Listing  Three 


int  ) ; 
int  )  ; 


cpbuild.c 

static  void  near  mark_as_static (  function_type  *,  char*, 
static  int  near  test_and_add (  function_type  *,  char  *, 
static  void  near  unget_chars(  char  ); 
static  char  near  get_chars(  FILE  *  ); 
static  char  near  get_to_next_possible_token {  FILE  *  ); 
static  int  near  is_legal_identifier_character (  char  ); 
int  near  build_the  data_base (  char  *,  char  *  ); 


♦define  MAIN  0 
♦include  "cpheader.h” 

int  near  build_the_data_base (  char  *,  char  *  ); 
static  char  near  get_chars(  FILE  *  ); 
static  char  near  get_to_next_possible_token (  FILE  *  ); 
static  int  near  is_legal_identifier_character (  char  ); 
static  void  near  mark_as_static (  function_type  *,  char*,  int  ); 
static  int  near  test_and_add (  function_type  *,  char  *,  int  ); 
static  void  near  unget_chars(  char  ); 


static  void  near  mark_as_static (  ptr_to_function_list, 

name_of_static_function,  count 

) 

char  *name_of_static_function; 
function_type  *ptr_to_function_list; 
int  count; 

( 

int  i; 

for (  i  -  0;  i  <  count;  ++i  ) 

{ 

if  ( 

! strcmp (  name_of_static_function,  ptr_to_function_list->functions_name) 
) 

ptr_to_function_list->static_function  -  true; 
++ptr_to_function_list; 


♦define  KEYS  7 

static  int  near  test_and_add (  ptr_to_function_list,  string,  count  ) 
function_type  *ptr_to_function_list; 
char  ‘string; 
int  count; 

! 

int  i,  is_a_new_function_name; 
static  char  "keywords!  KEYS  ]  = 

f  /*  must  catch  do  (void) printf ,  while (),  else  (void)...  etc.  ***/ 
"do",  "while",  "if",  "else",  "for",  "switch",  "return" 

}; 

for(  i  =  0;  (i<  KEYS  )  &&  (  strcmp (  string,  keywords!  i  ]  )  !=  0  );  ++i) 
if (  i  <  KEYS  ) 

is_a_new_function_name  =  false;  /* 
else  /* 

! 

for(  i  =  0;  i  <  count;  ++i  ) 

{ 

iff  ! strcmp (  string,  ptr_to_function_list->functions_name  )  ) 

{  7*  function  name  matches  */ 

if (  !ptr_to_function_list->static_function  ) 
break;  /*  and  isn't  static  */ 

else 

( 

if (  ! strcmp (  ptr_to_function_list->its_f ilename, 

file_record_array_ptr->source_f ilename 

) 


ie  a  reserved  word  match 
is  a  function  name  */ 


if  ( 

! 


) 

break; 


++ptr_to_function_list; 

) 

count  ) 


/*  only  statics  in  same  file  match  */ 


is  a  new  function  name  =  true; 


new  function  name  */ 

add  function  name  to  list  */ 


if ( (  function_list_ptr->functions_name  =  strdup(  string  ))  ==  NULL) 


(void) fprintf (  stderr, 
exit {  1  ) ; 


"Ran  out  of  memory. \n"  ); 


function_list_ptr->static_function  =  false; 
function_list_ptr->its_filename  = 

file_record_array_ptr->source_f ilename; 
function_list_ptr->is_referenced  =  1; 

++function_list_ptr;  /*  point  to  next  empty  cell  */ 

++count_of_functions;  /*  increase  current  size  */ 

if(  count_of_functions  >  Max_functions  ) 

( 

(void) fprintf (  stderr,  "Too  many  functions . \n"  ); 
exit (  1  )  ; 

} 


) 

else 

{ 

is_a_new_function_name  =  false; 
ptr_to_function_list->is_referenced++; 


/*  string  already  in  function  list  */ 


) 


) 


return  is_a_new_function_name; 

} 

/********************************* 
static  void  near  unget_chars (  c  ) 
char  c; 

( 
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listing  Four  ( Listing  continued,  text  begins  on  page  42.) 

113!  if  <  {  push_buf fer_ptr  -  push_buffer  )  <  Max_unget_buf fer  ) 

114!  *push_buf fer_ptr++  =  c; 

115!  else 
116!  { 

117!  (void) fprintf (  stderr,  "\nProgram  syntax  error : "  ); 

118!  (void) fprintf (  stderr,  "  Too  many  pushed  characters . \n"  ); 

119!  exit(  1  ); 

120!  | 

121!  ) 

1.22 !  /*******************************************,****************»********/ 
123!  static  char  near  get_chars(  stream  ) 

124!  FILE  *  stream; 

125!  { 

126!  register  char  c; 

127! 


128 

129 

130 

131 

132 

133 

134 

135 

136 

137 

138 
139: 

140 

141 

142 

143 

144 

145 

146 

147 

148 

149 

150 

151 

152 

153 

154 

155 

156 

157 

158 

159 

160 
161 
162 

163 

164 

165 

166 

167 

168 

169 

170 

171 

172 

173 

174 

175 

176 

177 

178 

179 

180 
181 
182 

183 

184 

185 

186 

187 

188 

189 

190 

191 

192 

193 

194 

195 

196 

197 

198 

199 

200 
201 
202 

203 

204 

205 

206 

207 

208 

209 

210 
211 
212 

213 

214 

215 

216 

217 

218 

219 

220 
221 
222 
223 


/*  count  the  unseen  <cr>  */ 


if (  push_buffer_ptr  !=  push_buffer  ) 
c  =  * — push_buffer_ptr; 
else 
( 

c  =  (char)fgetc(  stream  ); 
if (  c  ==  EOF  ) 
c  =  Control_z; 
if {  c  -=  0x0a  ) 

( 

f ile_record_array_ptr->line_count++; 
file_record_array_ptr->size++; 

} 

file_record_array_ptr->size++; 

> 

return  c; 

} 

/*******.*.******,*,************.***.*,*.**,***,,******,.*****.***..***/ 

static  char  near  get_to_next_possible_token (  stream  ) 

FILE  ‘stream; 

{ 

register  char 
c; 
char 

next_char_peek; 

int 

done; 

static  int  /*  the  only  apparent  reason  these  are  static  is  for  speed  */ 
quotes_flag  =  false, 

comment_flag  =  false, 

escape_sequence_flag  »  false, 
pound_sign_flag  =  false, 

ascii_quote_f lag  =  false; 

static  int 

fp  =  0;  /*****«<«  */ 

static  char  *cp; 

done  =  false; 
do  { 

c  =  get_chars(  stream  ); 
if {  c  !=  Control_z  ) 

I 

if(  comment_flag  ) 


process  /*  comment  sequence  of  characters 

if (  first_comment  «  true  ) 

{ 

if(  fp  <  (  Max_general_buf fer j  -  2  )  ) 

( 

if  ( 

(  c  !=  '\n'  )  && 

(  strlen(  cp  )  <  ef fective_width  ) 

) 

I 

file_comment_buffer [  fp++  )  =  c; 
file_comment_buf fer (  fp  1  =  '\0'; 

} 

else  /*  c  ==  \n  or  length  >=  width  */ 

{ 

file_comment_buf fer [  fp++  ]  =  '  \n' ; 
f ile_comment_buf fer [  fp  ]  =  '\0'; 
cp  =  (char  *) &f ile_comment_buf fer [  fp  ]; 
if  (  c  !=  ' \n'  ) 

I 

file_comment_buf fer [  fp++  ]  =  c; 
file_comment_buf fer [  fp  ]  =  '\0'; 


} 

else 


if(  c  == 


1st  comment  exceeds  buffer  */ 
end  of  if  first  comment  ==  true  */ 


next_char_peek  =  get_chars (  stream  ) ; 

if (  next_char_peek  =='/')  /*  close  comment  */ 

{ 

comment_flag  =  false; 

unget_chars (  '  '  );  /*  comments  are  white  space  in  'c 

if (  first_comment  ==  true  ) 

{ 

first_comment  =  completed; 
fp  =  0; 

cp  =  (char  *) &file_comment_buffer [  fp  ]; 

} 

) 

else  /*  next_char_peek  !=  '/'  ie  close  comment  */ 

unget_chars (  (char) next_char_peek  ); 

}  /*  end  of  if  c  ==  '*'  */ 


else 

{ 


/*  not  /*  */ 


224! 

process 

\sequence  character,  hoping  \"  V  \\  etc  inside  "  or  ' 

225! 

********** 

*****************/ 

226! 

if(  escape  sequence  flag  ) 

227! 

escape  sequence  flag  =  false; 

228! 

else  /*  not  /*,  not  \  */ 

229! 

{ 

230! 

/********* 

***************** 

231! 

process 

"  string  sequence  of  characters 

232! 

********** 

*****************/ 

233! 

if (  quotes  flag  ) 

234! 

{ 

235! 

if(  c  ==  '  W  )  /*  check  for  \'\n' 

*/ 

236! 

{ 

237! 

next  char  peek  =  get  chars (  stream  ); 

238! 

if{  next  char  peek  !=  '\n'  )  /*  so  not  \'\n'  */ 

239! 

{ 

240! 

escape_sequence_f lag  =  true; 

241! 

unget  chars (  (char) next  char  peek  ); 

242! 

) 

243! 

/******* 

else  /*  \'\n'  continuation  * 

244! 

) 

245! 

else  /*  not  \  */ 

246! 

if (  c  ==  ' ) 

247! 

quotes  flag  =  false; 

248! 

) 

249! 

else  /*  not  ",  not  /*,  not  \  */ 

250! 

( 

251! 

/********* 

***************** 

252! 

process 

'  ascii  character  sequence 

253! 

********** 

*****************/ 

254! 

if(  ascii  quote  flag  ) 

255! 

( 

256! 

if  (  c  ==  '  W  ) 

257! 

escape_sequence_f l3g  =  true; 

258! 

else 

259! 

iff  c  ==  '  \  ' '  ) 

260! 

ascii  quote  flag  =  false; 

261! 

1 

262! 

else  /*  not  ',  not  ",  not  /*,  not  \  */ 

263! 

( 

264! 

/********* 

265! 

process 

#  sequence  of  characters,  ie  #if,  #define,  etc. 

266! 

define 

causes  code  sequencing  problems  it  would  seem! 

267! 

********** 

*****************/ 

268! 

if(  pound  sign  flag  ) 

269! 

( 

270! 

if (  c  ==  ' /'  )  /*  comments  override  #defines 

etc* 

271! 

( 

272! 

next_char_peek  =  get_chars (  stream  ); 

273! 

if(  next_char_peek  ==  '*'  ) 

274! 

comment  flag  =  true; 

275! 

else 

276! 

unget  chars (  (char) next  char  peek  ); 

277! 

1 

278! 

else 

279! 

( 

280! 

if  (  c  ==  ' \n'  ) 

281! 

pound_sign_flag  =  false; 

282! 

else  /*  c  !=  \n  */ 

283! 

( 

284! 

if  (  c  ==  'W  )  /*  check  \'\n'  continuation* 

285! 

( 

286! 

next_char_peek  =  get_chars (  stream  ); 

287! 

iff  next_char_peek  !=  '\n'  )  /*  not  \ 

\n' 

288! 

unget  chars (  (char) next  char  peek 

; 

289! 

/* 

else  /*  \'\n'  means  continue  # 

290! 

) 

291! 

) 

292! 

) 

293! 

1 

294! 

else  /*  not  ',  not  #,  not  ",  not  /*,  not  \  */ 

295! 

296! 

297! 

process 

anything  else 

298! 

********** 

*****************/ 

299! 

done  =  false;  /*  assume  a  '  or  "  or  #  or  / 

*/ 

300! 

switch (  c  ) 

301! 

( 

302! 

case  : 

303! 

quotes_flag  =  true; 

304! 

break; 

305! 

case  '  \  "  : 

306! 

ascii  quote  flag  =  true; 

307! 

break; 

308! 

case  ' : 

309! 

pound  sign_flag  =  true; 

310! 

break; 

311! 

case  ' : 

312! 

next  char  peek  =  get_chars(  stream  ); 

313! 

if (  next  char  peek  ==  '*'  ) 

314! 

( 

315! 

comment  flag  =  true; 

316! 

iff  first  comment  ==  false  ) 

317! 

(  /*  the  1st  comment  of  the  file 

*/ 

318! 

first  comment  =  true; 

319! 

fp  =  0; 

320! 

cp  =  (char  *)&file  comment  buffer! 

fp) 

321! 

) 

322! 

) 

323! 

else 

324! 

I 

325! 

unget  chars (  (char) next  char  peek  ); 

326! 

done  =  true; 

327! 

) 

328! 

break; 

329! 

default:  /*  a  worthy  character  to  return*/ 

330! 

done  =  true; 

331! 

} 

332! 

)  /*  end  of  else  not  ascii  */ 

333! 

)  /*  end  of  else  not  #  */ 

334! 

)  /*  end  of  else  not  "  */ 

335! 

)  /*  end  of  else  not  /*  */ 

336! 

) 

/*  end  of  else  not  \  */ 

337! 

> 

/*  end  of  if  c  !=  Control  z  */ 

338! 

) 
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Listing  Four  (Listing  continued,  text  begins  on  page  42.) 

3391  while (  Idone  &s  (  c  !=  Control_z  )  ); 

340!  iff  c  ==  Control_z  ) 

341 :  { 

342!  ascii_quote_flag  =  false; 

343!  pound_sign_f lag  =  false; 

344!  quotes_flag  =  false; 

345!  escape_sequence_flag  =  false; 

346!  comment_flag  =  false; 

347!  fp  =  0; 

348!  } 

349!  return  c; 

350!  ) 

351!  /*********************************************************************/ 
352!  static  int  near  is_legal_identifier_character (  c  ) 

353!  char  c; 

354!  ( 

355!  iff 

356!  (  (  'A'  <=  c  )  &&  (  c  <=  'V  )  )  !  ! 

357!  (  (  'a'  <=  c  )  44  (  C  <=  'z'  )  )  ! ! 

358!  (  (  'O'  <=  c  )  S&  (  c  <=  '9'  )  )  ! ! 

359!  (  c  == 

360!  ) 

361!  return  true; 

362!  else 

363!  return  false; 

364!  ) 

365:  /**********************************.************.******.**.****.****.*/ 
366!  fdefine  C_line_length  2048  /*  was  512,  JH  has  BIG  definitions!!  */ 

367!  fdefine  C_identifier_length  80 
368! 

369!  int  near  build_the_data_base (  the_filename,  ov_string  ) 

370!  char  *  the_filename,  *  ov_string; 

371!  { 

372!  static  char  fake_comment [  ]  =  "no  room!"; 

373!  int  found_a_possible_function; 

374!  int  brace_count,  body_found; 

375!  int  open_parenthesis,  parenthesis_count; 

376!  int  at_end_of_source_file; 

377!  int  dummy_index,  total_called_count; 

378!  int  function_def inition_f lag,  static_flag; 

379!  int  analyze_buf fer_flag  =  false; 

380!  int  ov_num  =  0; 

381!  char  c; 

382!  char  *function_name_buf fer_ptr; 

383!  char  function_name_buf fer [  C_identifier_length  ]; 

384!  char  look_ahead_buffer (  C_line_length  +  1  ); 

385!  FILE  ‘stream; 

386!  data_base_record_type  *data_base_ptr,  *starting_data_base_ptr; 

387!  function_type  »starting_called_function_ptr; 

388! 

389!  iff  !g_quiet_flag  ) 

390!  { 

391!  (void) printf (  "Processing  file:  %-12s\n",  the_filename  ); 

392!  } 

393!  iff  !(  stream  =  fopenf  the_filename,  "r"  )  )  )  /““*  rt  «««««  */ 

394!  { 

395!  (void) printf (  "Cant  open  %s\n",  the_filename  ); 

396!  return  -1; 

397!  ) 

398!  ov_num  =  atoi (  ov_string  ); 

399!  push_buf fer_ptr  =  push_buffer;  /*  reset  input  character  stack  */ 

400!  /*  add  file  name  to  data  base  */ 


401 

402 

403 

404 

405 

406 

407 

408 

409 

410 
411! 
412! 
413 
414! 
415! 
416! 
417 
418! 
419! 
420! 
421! 
422! 
423! 
424! 
425! 
426! 
427! 
428! 
429! 
430! 
431! 
432! 
433! 
434! 
435! 
436! 
437! 
438! 
439! 
440! 
441! 
442! 
443! 
444! 
445! 
446! 
447! 
448! 
449! 
450! 
451! 
452! 
453! 
454! 
455! 
456! 
457! 
458! 
459! 
460! 
461! 
462! 
463! 
464! 
465! 
466! 


if ( ! {  file_record_array_ptr->source_f ilename  =  strdupf  the_filename  )  )) 

( 

(void)printf (  "Ran  out  of  memory. \n"  ); 
exit (  1  ) ; 

> 

starting_called_function_ptr  =  function_list_ptr; 

start ing_data_base_ptr  =  data_base_array_ptr;  /*  mark  start  of  list  */ 

look_ahead_buf fer [  0  ]  =  '\0'; 

first_comment  =  false; 
file_comment_buffer (  0  )  =  '\0'; 

file_record_array_ptr->line_count  =  0;  /*  clear  it's  variables  */ 

file_record_array_ptr->size  =  01; 

function_name_buf fer_ptr  =  function_name_buf fer; 
function_name_buffer [  0  ]  =  '\0'; 

static_flag  =  false; 
found_a_possible_f unction  =  false; 
open_parenthesis  =  false; 
body_found  =  false; 

brace_count  =  0; 
parenthesis_count  =  0; 

at_end_of_source_file  =  false; 
while (  !at_end_of_source_file  ) 
f 

c  =  get_to_next_possible_token (  stream  ); 
switch (  c  ) 

{ 

case  '  { ' : 

++brace_count ; 
break; 
case  ' } ' : 

— brace_count ; 
break; 

case  Control_z: 

at_end_of_source_file  =  true; 
analyze_buf fer_flag  =  true; 
break; 
case  '  ('  : 

iff  !open_parenthesis  ) 

++open_parenthesis; 
analyze_buf ferflag  =  true; 
break; 

case  '  ' :  /*  this  is  where  we  eat  white  space  */ 

case  ' \v' : 
case  ' \b' : 
case  ' \f '  : 
case  ' \t' : 
case  ' \r' : 
case  ' \n' : 
do  f 

c  =  get_to_next_possible_token (  stream  ); 

) 

while  ( 

(  c  ==  ' \f '  )  (  c  ==  '  '  )  ::  (  c  ==  '\v'  )  :: 

(  c  ==  ' \b'  )  ::  (  c  ==  '\t'  )  ::  (  c  ==  '\r'  )  :: 

(  c  ==  '\n'  ) 

)  ; 

unget_chars(  c  );  /*  put  next  non  white  character  back  */ 
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578 

1 

Listing  Four  (Listing  continued,  text  begins  on  page  42.) 

579 

580 

if!  g  dec  def  flag  ) 

{ 

581 

if(  static  flag  ) 

4671 

if  (  C  !=  '  ('  ) 

582 

(void)printf (  "  static"  ); 

4681 

analyze  buffer  flag  =  true; 

583 

else 

469! 

/*“  else  /*  c  ==  ' ('  and  next  pass  will  find  it  */ 

584 

(void) printf (  "  "  ); 

470 : 

break; 

585 

(void) printf (  "  declaration  "  ); 

471 : 

default : 

586 

(void) printf (  "%s(%s\n". 

472: 

if {  is  legal  identifier  character (  c  )  ) 

587 

function  name  buffer. 

473: 

{  /*  it's  a  good  identifier  character  */ 

588 

look  ahead  buffer  ) ; 

474: 

‘function  name  buffer_ptr++  =  c; 

589 

1 

475: 

‘function  name  buffer_ptr  =  '\0'; 

) 

590 

} 

476: 

591 

) 

477! 

else  /*  it  isn't,  so  toss  it  */ 

592 

break; 

4781 

( 

593 

default:  /*  any  other  non  white  character  means  */ 

479! 

if (  static  flag  &&  {  c  —  ';'  )  ) 

594 

function  definition  flag  =  completed; 

480 : 

static  flag  =  false; 

595 

if(  !g  quiet  flag  ) 

481 : 

/*  if (  c  !=■  '*'  )  */ 

596 

{ 

482! 

analyze  buffer  flag  =  true; 

597 

if!  g  dec  def  flag  ) 

483: 

} 

598 

( 

484,' 

break; 

599 

if!  static  flag  ) 

485: 

}  /*  end  of  preliminary  character  parse  */ 

600 

(void)printf (  "static  "  ); 

4861 

/***********»***** 

601 

else 

487: 

start  checking  characters  accumulated  in  function  name  buffer [] 

602 

(void) printf (  "  "  ); 

488i 

******************/ 

603 

(void) printf (  "define  "  ); 

489: 

if  (  analyze  buffer  flag  } 

604 

) 

490: 

{ 

605 

) 

491 : 

analyze  buffer  flag  =  false; 

606 

break; 

492: 

if  ( 

607 

)  /*  dummy  index  is  bumped  */ 

493! 

function  name  buffer!  0  ]  Si  /*  ie  not  null  string  */ 

608 

)  /*  end  of  for  loop  parsing  character  after  )  */ 

494: 

(  /*  S  not  number  */ 

609 

body  found  =  false; 

495: 

(  function  name  buffer!  0  ]  <  '0'  )  !! 

610 

if(  function  definition  flag  ==  false  ) 

496: 

(  function  name  buffer!  0  ]  >  '9'  ) 

611 

{ 

497: 

) 

612 

(void) printf (  "\nSyntax  error:  "  ); 

498: 

) 

613 

(void) printf (  "Function  description. \n"  ); 

499: 

found  a  possible  function  *  true; 

614 

look  ahead  buffer!  dummy  index  ]  -  '\0'; 

500 : 

else  /*  it  aint  an  identifier  */ 

615 

(void)printf (  "\n%s\n",  look  ahead  buffer  ); 

501 : 

{  /*  so  erase  buffer  */ 

616 

exit!  1  ); 

502: 

function  name  buffer  ptr  =  function  name  buffer; 

617 

) 

503: 

function  name  buffer!  0  ]  =  '\0'; 

618 

while!  dummy  index  ) 

504: 

if {  static  flag  Si  (  c  ==  ';'  )  ) 

619 

(  /*  put  all  characters  after  (  back  */ 

505! 

static  flag  =  false; 

620 

unget  chars!  look  ahead  buffer!  dummy  index  -  1  ]  ); 

506! 

open_parenthesis  =  false; 

621 

— dummy  index; 

507: 

} 

622 

1 

508: 

}  /*  end  of  analyze  buffer  flag  */ 

623 

if(  function  definition  flag  ==  completed  ) 

509; 

/**********»****** 

624 

( 

510 : 

if  function  name  buffer!]  has  legal  function  name,  scan  ahead 

625 

if!  !g  quiet  flag  ) 

511 : 

****************.*/ 

626 

{ 

512! 

if (  found  a_possible  function  ) 

627 

if(  g  dec  def  flag  ) 

513: 

! 

628 

(void)printf (  "%-40s\n",  function  name  buffer  ) ; 

514: 

found  a_possible  function  =  false; 

629 

} 

515: 

‘function  name  buffer_ptr  -  '\0';  /*  append  nul  char  to  end  */ 

630 

516: 

if(  ! static  flag  )  /*  don't  retest  if  true  */ 

631 

this  element  can  distinguish  static  functions 

517 : 

if(  !strcmp(  function  name  buffer,  "static"  )  ) 

632 

in  different  files  with  the  same  name 

518: 

static  flag  =  true; 

633 

*******************/ 

519: 

if(  open_parenthesis  ) 

634 

data  base  array  ptr->file  record  ptr  =  file  record  array  ptr; 

( 

635 

data  base  array  ptr->number  of  function  calls  =  0; 

521 : 

open_parenthesis  =  false; 

636 

data  base  array  ptr->ptr  to  function  table  =function  list  ptr; 

if(  ! brace  count  ) 

637 

data  base  array  ptr->static  definition  =  static  flag; 

523! 

{  7*  ie  outside  any  function  body  */ 

638 

data  base  array  ptr->overlay  number  =  ov  num; 

524  : 

parenthesis  count  =  1; 

639 

525: 

for(  dummy  index  =  0; 

640 

static  flag  =  false; 

526; 

(  dummy  index  <  C  line  length  )  ss  parenthesis  count; 

641 

527.' 

++dummy  index 

642 

if! 

) 

643 

! (  data  base  array_ptr->de fined  function  = 
strdup!  function  name  buffer  ) 

529: 

{  /*  scan  ahead  for  function!)  */ 

644 

530 : 

c  =  get  to  next_possible  token!  stream  ); 

645 

) 

531 : 

if(  c  ==  Control  z  ) 

646 

) 

532: 

break;  /*  dummy  index  not  bumped  */ 

647 

{ 

533: 

look  ahead  buffer!  dummy  index  ]  =  c; 

648 

(void)printf (  "\nRan  out  of  memory!  for  strdup!)  )."); 

534 : 

look  ahead  buffer!  dummy  index  +  1  ]  =  '\0'; 

649 

exit!  1  ) ; 

) 

535: 

switch!  c  ) 

650 

536: 

1 

651 

data  base  array  ptr->number  of  references  =  0; 

537! 

case  ' (' : 

652 

data_base  array_ptr->ptr_to_page_list  =  NULL; 

538: 

++parenthesis  count; 

653 

539: 

break; 

654 

data  base  ptr  =  data  base  array  ptr;  /*  save  current  pointer*/ 

540 : 

case  ' ) ' : 

655 

++data  base  array  ptr;  /*  next  entry  */ 

541 : 

— parenthesis  count; 

656 

++count  of  valid  records; 

542: 

break; 

657 

if!  count  of  valid  records  >  Max  defined  functions  ) 

543! 

)  /*  dummy  index  is  bumped  */ 

658 

{ 

544: 

)  /*  end  of  for  loop  scanning  for  (...)  */ 

659 

(void) printf (  "\nToo  many  new  functions\n"  ); 

545! 

if(  (  c  *=  Control  z  )  ::  (  ! parenthesis  count  )  ) 

660 

exit!  1  ) ; 

) 

546: 

— dummy  index; 

661 

547! 

function  definition  flag  =  false; 

662 

)  /*  end  of  function  definition  */ 

548: 

for!  ++dummy  index; 

663 

static  flag  =  false; 

549: 

(dummy  index  <  C  line  length) S& ! function  definition  flag; 

664 

} 

550 : 

++dummy  index 

665 

else  /*  brace  count  is  not  zero  */ 

551 : 

) 

666 

{  /*  so  inside  a  function  */ 

552! 

(  /*  what  happens  past  (..)  */ 

667 

data  base  ptr->number  of  function  calls  += 

553: 

554: 

c  =  get_to  next_possible_token (  stream  ); 
if!  c  **=  Control  z  ) 

668 

669 

test  and  add!  data  base_ptr->ptr  to  function  table, 
function  name  buffer, 

555: 

break;  /*  w/  function  definition  flag  ==  false  */ 

670 

data  base_ptr->number  of  function  calls 

556: 

look  ahead  buffer!  dummy  index  ]  =  c; 

671 

)? 

} 

557! 

look  ahead  buffer!  dummy  index  +  1  ]  =  '\0'; 

672 

558: 

switch!  c  ) 

673 

look  ahead  buffer!  0  )  =  '\0';  /*  reset  tail  buffer  */ 

559: 

{ 

674 

static  flag  =  false; 

560! 

case  '  ' :  /*  this  is  where  we  eat  white  space  */ 

675 

}  /*  end  of  parenthesis  */ 

561 : 

case  ' \v' : 

676 

function  name  buffer  ptr  =  function  name  buffer;  /*  reset  buffer*/ 

562: 

case  ' \b' : 

677 

‘function  name  buffer_ptr  =  '\0'; 

563 : 

case  ' \f '  : 

678 

}  /*  end  of  found  a_possible  function  */ 

564  , 

case  ' \t' : 

67  9 

)  /*  end  of  while  !at  end  of  source  file  */ 

565: 

case  ' \n' : 

680 

(void) fclose (  stream  ); 

566: 

case  ' \r' : 

681 

if (  !g  quiet  flag  ) 

567: 

break; 

682 

( 

568! 

case  ' {' : 

683 

(void)printf (  "\n"  ); 

569: 

++body  found; 

684 

1 

570 : 

break; 

685 

571 : 

case  ' ; 

686 

if! 

572: 

case  ' , ' : 

687 

! (  file  record  array  ptr->source  file  comment  = 

573: 

case  ' (' :  /*  at  (*)  ()  type  declaration  */ 

688 

strdup!  file  comment  buffer  ) 

574: 

if(  !body  found  ) 

689 

) 

575: 

{ 

690 

) 

576: 

function  definition  flag  =  true;  /‘declaration*/ 

691 

file  record  array  ptr->source  file  comment  =  fake  comment; 

577! 

if(  !g_quiet_flag  ) 

692 

82 
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693!  /““*  mark  called  functions  in  list  as  static  if  in  defined  list  ****/ 

83 

bottom  line  of  box(  i  ]  =  '\0'; 

694!  total  called  count  =  0; 

84 

) 

6951  data  base_ptr  =  starting  data  base_ptr; 

85 

/*********************************************************»************/ 

696!  while (  data  base  ptr  !=  data  base  array  ptr  ) 

86 

void  near  tab  to  left  margin (  output  ) 

697!  { 

87 

FILE  ‘output; 

! 

698!  total  called  count  +=  data  base  ptr->number  of  function  calls; 

88 

699!  ++data  base  ptr; 

89 

register  int  i; 

700!  } 

90 

701!  data  base  ptr  =  starting  data  base  ptr; 

91 

for(  i  =  0;  i  <  defined  left  margin;  ++i  ) 

702!  while {  data  base_ptr  <  data 

base  array  ptr  ) 

92 

(void)fputc!  '  ',  output  } ; 

703!  { 

93 

} 

704!  if(  data  base  ptr->static  definition  ) 

94 

705!  mark  as  static  (  starting  called  function_ptr, 

95 

static  void  near  stop!) 

706!  data 

Dase  ptr->defined  function, 

707!  total 

called  count 

97 

(void) printf (  "hello"  ) ; 

} 

708!  ); 

98 

709!  ++data  base  ptr; 

99 

710!  ) 

/*  next  file  name  entry  */ 

100 

static  void  near  setpage!  data  base  ptr  ) 

711!  ++file  record  array  ptr; 

101 

data  base  record  type  ‘data  base  ptr; 

712!  ++count  of  source  files; 

102 

713!  if(  count  of  source_files  > 

=  Max  files  ) 

103 

linked  pages  list  ‘page  list  ptr; 

714 !  { 

104 

7151  (void) printf (  "\nError: 

too  many  files  to  process. \n"  ); 

105 

page  list  ptr  =  data  base  ptr->ptr  to  page  list; 

716!  exit  (  1  ); 

106 

if (  page  list  ptr  ==  NULL  ) 

717!  ) 

107 

( 

7181  return  at  end  of  source  file; 

108 

if! 

719!  ) 

109 

! (  page  list  ptr  = 

110 

(linked  pages  list  *)malloc(  sizeof!  linked  pages  list  )  ) 

721! 

/*** 

End  Listing  Four 

112 

113 

) 

{ 

Listing  Five 

114 

115 

(void) fprintf (  stderr,  "Ran  out  of  memory  for  page  #  list.Xn"  ); 
exit!  1  ) ; 

1 

1 

/************************** 

******************************************** 

116 

2 

cpfuncts.c 

117 

3 

void  near  build  box  parts  (  int  ); 

118 

data  base  ptr->ptr  to  page  list  =  page  list  ptr; 

4 

void  near  tab  to  left  margin (  FILE  *  ); 

119 

) 

5 

static  void  near  stop(  void 

>; 

120 

else 

6 

static  void  near  setpage (  data  base  record  type  *  ); 

121 

( 

7 

static  int  near  recursion  check (  char  *,  int  ); 

122 

while!  page  list  ptr->next  page  ptr  ) 

8 

void  near  check  for  new  page (  void  ); 

123 

page_list_ptr  -  page_list_ptr->next_page_ptr; 

9 

static  void  near  draw  output  block (  char  *,  char  *,  char  *, 

124 

10 

char  *,  int,  int,  int,  int  ); 

125 

if! 

11 

int  near  doprint (  int  ) ; 

126 

! (  page  list_ptr->next  page  ptr  = 

12 

void  near  scan  for  static  or  global (  int  *,  int,  char  *,  char  *); 

127 

(linked  pages  list  *)malloc(  sizeof!  linked  pages  list  )  ) 

13 

int  near  binary  search  sorted  data  base (  char  *  ); 

128 

) 

14 

*************************** 

*******************************************/ 

129 

) 

15 

130 

( 

16 

♦define  MAIN  0 

131 

(void) fprintf (  stderr,  "Ran  out  of  memory  for  page  #  list.Xn"  ); 

17 

♦include  "cpheader.h" 

132 

exit!  1  ); 

18 

133 

} 

19 

static  char 

134 

20 

top  line  of  box[  47  ],  bottom  line  of  box[  47  ], 

135 

paqe  list  ptr  =  paqe  list  ptr->next  page  ptr; 

21 

wall,  ibm  line,  bottom  attach, 

136 

) 

22 

upper  left  corner,  lower 

left  corner, 

137 

page  list  ptr->next  page  ptr  =  NULL; 

23 

upper  right  corner,  lower  right  corner, 

138 

page  list  ptr->on  this  page  =  page  -  1; 

24 

left  attach,  right  attach; 

139 

) 

25 

140 

/*****,*,****.***.***.************.*.*.*.*********.*.*****************/ 

26 

static  char  ‘recursion  filename,  ‘test  filename; 

141 

static  int  near  recursion  check!  string,  static  call  ) 

27 

static  int  static  recursion 

142 

char  ‘string; 

28 

143 

int  static  call; 

29 

int  near  binary  search  sorted  data  base (  char  »  ); 

144 

t 

30 

void  near  build  box  parts (  int  ); 

145 

register  char  “recursion  array  ptr; 

31 

void  near  check  for  new  page (  void  ) ; 

146 

32 

int  near  doprint (  int  ) ; 

147 

recursion  array  ptr  =  recursion  array; 

33 

void  near  scan  for  static  or  global!  int  *,  int,  char  *,  char  *); 

148 

if(  static  recursion  ) 

34 

void  near  tab  to  left  margin!  FILE  *  ); 

149 

{  /*  defined  function  is  static  */ 

35 

150 

while  ( 

36 

static  void  near  draw  output  block!  char  *,  char  *,  char  *, 

151 

‘recursion  array  ptr  &&  /*  not  null  */ 

37 

char  *,  int,  int,  int,  int  ); 

152 

/*  and  different  function  names  */ 

38 

static  int  near  recursion  check!  char  *,  int  ); 

153 

(  strcmp!  ‘recursion  array  ptr,  string  )  ! ! 

39 

static  void  near  stop!  void 

>: 

154 

/*  or  same  function  names  and  */ 

40 

static  void  near  setpage!  data  base  record  type  *  ); 

155 

/*  in  different  files  */ 

41 

156 

strcmp!  test  filename,  recursion  filename  ) 

42 

/************************** 

******************************************/ 

157 

) 

43 

void  near  build  box  parts!  is  ibm  ) 

158 

) 

44 

int  is  ibm; 

159 

++recursion  array  ptr; 

45 

{ 

160 

1 

46 

int  i; 

161 

else 

47 

162 

(  /*  defined  function  is  not  static  */ 

48 

if (  is  ibm  ) 

163 

while ( 

49 

{ 

164 

‘recursion  array  ptr  &&  /*  not  null  &  */ 

50 

wall  =  '\xb3'; 

165 

/*  and  different  function  names  */ 

51 

ibm  line  =  '\xc4'; 

166 

(  strcmp!  ‘recursion  array  ptr,  string  )  !! 

52 

bottom  attach  =  ' \xc2'; 

167 

/*  or  same  function  names  and  */ 

53 

upper  left  corner  =  '\xda'; 

168 

static  call  /*  called  is  static  */ 

54 

lower  left  corner  =  '\xc0'; 

169 

) 

55 

upper  right  corner  =  '\xbf'; 

170 

> 

56 

lower  right  corner  =  '\xd9'; 

171 

++recursion  array  ptr; 

57 

left  attach  =  '\xb4'; 

172 

) 

58 

right  attach  =  '\xc3'; 

173 

return  (  ‘recursion  array  ptr  )?  true:  false; 

59 

) 

174 

) 

60 

else 

175 

/**.********.***********************.*.********************************/ 

61 

( 

176 

void  near  check  for  new  page!) 

62 

wall  =  '  !' 

177 

! 

63 

ibm  line  =  ' 

178 

int  i; 

64 

bottom  attach  =  '+' 

179 

65 

upper  left  corner  =  '+' 

180 

if (  defined  page  length  ==  0  &&  line  ==  9999  ) 

66 

lower  left  corner  =  '+' 

181 

{ 

67 

upper  right_corner  =  '+' 

182 

(void) fprintf (  output,  "\n\n\n\n"  ); 

68 

lower  right  corner  =  '+' 

183 

line  =  0; 

69 

left  attach  =  '+' 

184 

) 

70 

right  attach  =  '+' 

185 

else 

71 

} 

186 

! 

72 

187 

if (  defined  page  length  !=  0  ) 

73 

top  line  of  box[  0  ]  =  upper  left  corner; 

188 

{ 

74 

bottom  line  of  box[  0  ]  =  lower_left_corner; 

189 

if!  line  >  (  defined  page  length  -  5  )  ) 

75 

for(  i=l;  i  <=  37;  ++i  ) 

190 

( 

76 

{ 

191 

(void) fprintf (  output,  "\f"  ); 

77 

top  line  of  box[  l  ]  =  ibm  line; 

192 

line  =  0; 

78 

bottom  line  of  box[  i  ]  =  ibm  line; 

193 

) 

79 

} 

194 

if(  line  ==  0  ) 

{ 

80 

top  line  of  box[  i  ]  =  upper  right  corner; 

195 

81 

bottom  line  of  box[  i  ]  =  lower  right  corner;  1 

196 

top  of  form  done  =  true; 

82 

top  line_of  box[  ++i  ]  =  '\0'; 
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307 

recursion  array!  recursion  depth  ]  =  record_ptr->def ined  function; 

308 

if (  ! recursion  depth  ) 

Listing  Five  (Listing  continued,  text  begins  on  page  42.) 

310 

recursion  filename  =  record  ptr->file  record  ptr->source_filename; 

311 

/*  add  function  to  list  for  recursion  check  */ 

197 

tab  to  left  margin!  output  ); 

312 

static  recursion  =  record  ptr->static  definition; 

198 

(void) fprintf (  output,  "%s",  title  ); 

313 

) 

199 

for!  i  =  strlen!  title  );  i  <  (  effective  width  -  10  );  ++i  ) 

314 

check  for  new  page!); 

200 

(void)fputc!  '  output  ); 

315 

setpage!  array  of  ptrs  to  records!  starting  index  )  ); 

201 

(void) fprintf (  output,  "Page: %4d\n",  page  ) ; 

316 

202 

tab  to  left  margin!  output  ); 

317 

return  value  =  page  -  1;  /*  must  be  a  relic!  */ 

203 

for(  i  =  0;  i  <  effective  width;  ++i  ) 

318 

/*  start  w/  target  function  */ 

204 

(void)fputc!  '  output  ); 

319 

draw  output  block!  nesting  display  buffer. 

205 

(void) fprintf (  output,  "\n\n"  ); 

320 

record  ptr->defined  function, 

206 

line  =  3; 

321 

(  record  ptr->file  record  ptr  ) ->source  filename, 

207 

++page; 

322 

funct  string, 

208 

) 

323 

record  ptr->number  of  function  calls, 

209 

) 

324 

true, 

210 

1 

325 

kill  flag. 

211 

} 

326 

record  ptr->overlay  number 

212 

327 

); 

213 

static  void  near  draw  output  block!  lead  in  string, 

328 

214 

name  of  function, 

329 

++recursion  depth; 

215 

description, 

330 

/““  mystic  width  =  4  *““/ 

216 

name  of  file, 

331 

(void) strcat (  nesting  display  buffer,  "  !"  ) ; 

217 

either  count, 

332 

nesting  display  buffer!  strlen!  nesting  display  buffer  )  -  1  ]  =  wall; 

218 

tail  flag, 

333 

219 

kill  flag, 

334 

max  count  =  record  ptr->number  of  function  calls; 

220 

ov  num 

335 

for!  loop  counter  =  0,  f  list  ptr  -  record  ptr->ptr  to  function  table; 

221 

) 

336 

loop  counter  <  max  count; 

222 

char  ‘lead  in  string, 

337 

++loop  counter,  ++f  list  ptr 

223 

‘name  of  function, 

338 

) 

224 

‘description, 

339 

( 

225 

‘name  of  file; 

340 

kill  flag  =  (  loop  counter  =*  (  max  count  -  1  )  )?  true:  false; 

226 

int  either  count,  tail  flag,  kill  flag,  ov  num; 

341 

check  for  new  page!); 

227 

{ 

342 

/*  is  called  function  defined?  */ 

228 

unsigned  int  string  length; 

343 

found  =  binary  search  sorted  data  base!  f  list  ptr->functions  name  ); 

229 

static  char  alternate  lead  in [  140  ]; 

34  4 

if (  found  >=  0  ) 

230 

345 

1 

231 

/***““  igt  line  ***************************************************“/ 

346 

scan  for  static  or  global!  Sfound, 

232 

tab  to  left  margin (  output  ) ; 

347 

f  list  ptr->static  function, 

233 

(void) fprintf (  output,  "%s  %s\n",  lead  in  string,  top  line  of  box  ); 

348 

f  list  ptr->functions  name, 

234 

349 

f  list  ptr->its  filename 

235 

/“““*  2nd  line““““““““““ “““““““* “****“*“* ****** ‘/ 

350 

) ; 

236 

tab  to  left  margin!  output  ); 

351 

237 

string  length  -  strlen!  lead  in  string  ); 

352 

I 

238 

if!  string  length  )  /*******  j.e  not  main  or  defined  function  box  *“/ 

353 

if(  found  >=  0  )  /*  yes  */ 

239 

{ 

354 

< 

240 

(void) strncpy (  alternate  lead  in,  lead  in  string,  — string  length  ); 

355 

test  filename  =  f  list  ptr->its  filename; 

241 

alternate  lead  inf  string  length++  )  =  *\0';  /‘restorestring  length*/ 

356 

if!  recursion  check!  f  list  ptr->functions  name, 

242 

) 

357 

f  list  ptr->static  function  ) 

243 

if(  string  length  )  /*******  ie  not  main  or  defined  function  box  *“/ 

358 

) 

244 

f 

359 

( 

245 

if!  g  ov  flag  s&  ov  num  ) 

360 

/*  tab  to  left  margin!  output  ); 

246 

(void) fprintf (  output,  "%s%c%c%c%-32s  %3d  %c\n", 

361 

/*  (void) fprintf (  output,  "%s\n",  nesting  display  buffer  );  */ 

247 

alternate  lead  in, 

362 

setpage!  array  of  ptrs  to  records!  found  ]  ); 

248 

/“*  if!  kill  flag  )  /“““  last  line  to  this  box  **«»**»*»****/ 

363 

/*  ++line;  */ 

249 

/“*  else  /“““  nne  continues  downwards  *»*»*»****/ 

364 

top  of  form  done  =  false; 

250 

(  kill  flag  )?  lower  left  corner:  right  attach, 

365 

draw  output  block!  nesting  display  buffer, 

251 

ibm  line,  left  attach,  name  of  function,  ov  num,  wall  ); 

366 

f  list  ptr->functions  name, 

252 

else 

367 

" (recursive) ", 

253 

(void) fprintf (  output,  "%s%c%c%c%-32s  %c\n", 

368 

"  ", 

254 

alternate  lead  in. 

369 

0, 

255 

(  kill  flag  )?  lower  left  corner:  right  attach, 

370 

false, 

256 

ibm  line,  left  attach,  name  of  function,  wall  ); 

371 

kill  flag, 

257 

) 

372 

array  of  ptrs  to  records!  found  ]->overlay  numbei 

258 

else  /“““  main  or  defined  box  starting  »*♦*»******/ 

373 

); 

259 

( 

374 

) 

260 

if(  g  ov  flag  &&  ov  num  ) 

375 

else  /*  not  recursive  and  found  >=  0  */ 

261 

(void) fprintf (  output,  "%c%c%-32s  %3d  lc\n", 

376 

( 

262 

ibm  line,  left  attach,  name  of  function,  ov  num,  wall  ); 

377 

if!  array  of  ptrs  to  records!  found  ]->number  of  references  ==  1) 

263 

else 

378 

(  /*  got  a  new  function  */ 

264 

(void) fprintf (  output,  "%c%c%-32s  %c\n". 

379 

/*  tab  to  left  margin!  output  ); 

265 

ibm  line,  left  attach,  name  of  function,  wall  ); 

380 

/*  (void) fprintf (  output,  "%s\n",  nesting  display  buffer  ); 

266 

) 

381 

/*  ++line; 

267 

/“““*  3rd  line  *******«*********************************************/ 

382 

/*  top  of  form  done  =  false;  */ 

268 

tab  to  left  margin!  output  ); 

383 

doprint!  found  ) ;  /‘  used  only  once  */ 

269 

if(  string  length —  )  /“  kill  outside  vertical  line  on  last  box  “/ 

384 

) 

270 

lead  in  string!  string  length++  ]  =  (  kill  flag  )?  (char)'  wall; 

385 

else 

271 

(void) fprintf (  output,  "%s  %c%-20s  %8s%3d  %c\n", 

386 

(  /*  a  previously  defined  function  */ 

272 

lead  in  string,  wall,  description, 

387 

/*  tab  to  left  margin!  output  ); 

273 

name  of  file,  either  count,  wall  ); 

388 

/*  (void) fprintf (  output,  "%s\n",  nesting  display  buffer  );*/ 

274 

389 

setpage!  array  of  ptrs  to  records!  found  ]  ); 

275 

/“““*  4th  line  *****************************************************/ 

390 

/*  ++line; 

276 

tab  to  left  margin!  output  ); 

391 

/*  top  of  form  done  =  false;  */ 

277 

bottom  line  of  box[  2  ]  =  /““  if  defined  box  has  calls  **♦**»*/ 

392 

draw  output  block!  nesting  display  buffer, 

278 

(  tail  flag  &&  either  count  )?  bottom  attach:  ibm  line; 

393 

f  list  ptr->functions  name, 

279 

(void) fprintf (  output,  "%s  %s\n",  lead  in  string,  bottom  line_of_box  ); 

394 

" (defined) ", 

280 

395 

usage  string, 

281 

line  +=  4; 

396 

f  list  ptr->is  referenced, 

282 

top  of  form  done  =  false; 

397 

false, 

283 

} 

398 

kill  flag, 

284 

/♦a************************.**.***.**.****.****************************/ 

399 

array  of  ptrs  to  records!  found  ]->overlay  number 

285 

400 

)? 

286 

static  char  library  string!]  =  (  "(library)"  ); 

401 

] 

287 

static  char  usage  string!]  =  (  "Used="  }; 

402 

) 

288 

static  char  funct  string!]  =  1  "Functs="  }; 

403 

1 

289 

404 

else  /*  found  =  -1  ie  not  defined  means  */ 

290 

int  near  doprint (  index  ) 

405 

!  /*  a  library  function  */ 

291 

int  index; 

406 

/*  tab  to  left  margin!  output  ); 

292 

{ 

407 

/*  (void) fprintf  (  output,  "%s\n",  nesting  display  buffer  ); 

293 

int 

408 

/*  ++line; 

294 

loop  counter, 

409 

/*  top  of  form  done  =  false;  */ 

295 

max  count. 

410 

draw  output  block!  nesting  display  buffer, 

296 

starting  index, 

411 

f  list  ptr->functions  name, 

297 

found. 

412 

library  string, 

298 

return  value; 

413 

usage  string, 

299 

data  base  record  type  ‘record  ptr; 

414 

f  list  ptr->is  referenced, 

300 

function  type  *f  list  ptr; 

415 

false, 

301 

416 

kill  flag, 

302 

static  int  kill  flag  =  false; 

417 

0  /*  .lib  functions  are  in  the  kernel  */ 

303 

418 

); 

304 

starting  index  =  index; 

419 

) 

305 

record  ptr  =  array  of  ptrs  to  records!  starting  index  ]; 

420 

)  /*  end  of  loop  on  all  called  functions  */ 

306 

421 
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422 

/*  remove  function  f/  recursion  list  */ 

423 

recursion  array [  recursion  depth  )  =  NULL; 

424 

/****  mystic  width  =  4  *****/ 

425 

nesting  display  buffer [  strlen(  nesting  display  buffer  )  -  4  ]  =  ' \0'; 

426 

— recursion  depth; 

427 

return  return  value; 

428 

1 

429 

430 

/**************, ***,***************************************************/ 

431 

void  near  scan  for  static  or  global! 

432 

index  ptr,  is  static,  function  name,  file  name 

433 

) 

434 

int  *  index  ptr,  is  static; 

435 

char  *  function  name,  *file  name; 

436 

( 

437 

438 

int  index; 

439 

index  =  *index  ptr; 

440 

if(  index  ) 

441 

while!  index —  ) 

442 

if!  strcmp!  function  name, 

443 

array  of  ptrs  to  records!  index  ]->defined  function  ) 

444 

) 

445 

{ 

446 

++index;  /*  exit  at  last  matching  defined  function  */ 

447 

break; 

448 

1 

449 

do  ( 

450 

-if  ( 

451 

{  ! is  static  &&  ! array  of  ptrs  to  records!  index  ]->static  definition 

452 

)  : ' 

453 

(  is  static  S4 

454 

array  of  ptrs  to  records!  index  ]->static  definition  && 

455 

! strcmp!  array  of  ptrs  to  records!  index  ] -> 

456 

file  record  ptr->source  filename, 

457 

file  name 

458 

) 

459 

) 

460 

) 

461 

break; 

462 

) 

463 

while ( 

464 

{  ++index  <  count  of  functions  )  && 

465 

! strcmp!  function  name, 

466 

array  of  ptrs  to  records!  index  ]->defined  function 

467 

) 

468 

>; 

469 

if! 

470 

(  index  >=  count  of  functions  )  ! ! 

471 

strcmp!  function  name,  array  of  ptrs  to  records!  index  ]->defined  function 

472 

) 

473 

) 

474 

index  =  -1; 

475 

*  index  ptr  =  index; 

476 

1 

477 

478 

int  near  binary  search  sorted  data  base!  key  ) 

479 

char  *key; 

480 

{ 

481 

int  lo,  hi,  index; 

482 

int  doesnt  match; 

483 

484 

lo  =  0; 

485 

hi  =  count  of  valid  records  -  1; 

486 

487 

index  =  (  hi  -  lo  )  12; 

488 

while!  true  ) 

489 

f 

490 

doesnt  match  = 

491 

strcmp!  key,  array  of  ptrs  to  records!  index  ]->defined  function  ); 

492 

if!  Idoesnt  match  )  /*  a  match  found  at  index  */ 

493 

break; 

494 

if (  lo  >=  hi  )  /*  no  match  found  */ 

495 

1 

496 

index  =  -1; 

497 

break; 

498 

) 

499 

if (  doesnt  match  <  0  )  /*  key  <  choice  so  go  downwards  */ 

500 

hi  =  index  -  1; 

501 

else  /*  key  >  choice  so  go  upwards  */ 

502 

lo  =  index  +  1; 

503 

index  =  (  hi  +  lo  )  /  2;  /*  new  choice  */ 

504 

1 

505 

return  index; 

506 

} 

507 

/*****«***,******..***.*.,******.*,.***,****,****,**.**.****.**********/ 

End  Listing  Five 

Listing  Six 

cp.obj  :  cp.c  cpheader.h  cp 
cl  -AL  -c  cp.c 

cpinput.obj  :  cpinput. c  cpheader.h  cp 
cl  -AL  -c  cpinput. c 

cpfuncts.obj  :  cpfuncts.c  cpheader.h  cp 
cl  -AL  -c  cpfuncts.c 

cpbuild.obj:  cpbuild.c  cpheader.h  cp 
cl  -AL  cpbuild.c  -c 

cp.exe  :  cp.obj  cpinput.obj  cpfuncts.obj  cpbuild.obj  cp 

link  cp+  cpinput+  cpbuild+  cpfuncts/packcode/st : 16000, , cp; 

End  Listing  Six 

Listing  Seven 

cpheader.h 

cp.c 

cpbuild.c 

cpfuncts.c 

cpinput. c 

End  Listings 

C  PRINTER  FOR  VMS  AND  UNIX 


Listing  One  (Text  begins  on  page  44.) 


VAX/VMS  MMS  Description  File 


DEFINITIONS: 
H  =  cpheader.h 


cp  DEPENDS_ON  cp.obj  cpbuild.obj  cpfuncts.obj  cpinput.obj 

LINK/EXEC=cp  cp . ob j , cpbui Id . ob j , cpf uncts .  ob  j , cpinput . ob j 
PURGE  *.obj,  *.exe 

cp.obj  DEPENDS_ON  $(H)  cp.c 
cc  cp.c 

cpbuild.obj  DEPENDS_ON  $ (H)  cpbuild.c 
cc  cpbuild.c 

cpfuncts.obj  DEPENDSON  $(H)  cpfuncts.c 
cc  cpfuncts.c 

cpinput.obj  DEPENDS_ON  $(H)  cpinput. c 
cc  cpinput. c 

Listing  Two 

#  VAX/Unix  Makefile 

# 

#  DEFINITIONS: 

H  =  cpheader.h 

♦ 

#  CP 

♦ 

cp  :  cp.o  cpbuild.o  cpfuncts.o  cpinput. o 

cc  -o  cp  cp.o  cpbuild.o  cpfuncts.o  cpinput. o 

cp.o  :  $H  cp.c 

cc  -c  cp.c 

cpbuild.o  :  $H  cpbuild.c 
cc  -c  cpbuild.c 

cpfuncts.o  :  $H  cpfuncts.c 
cc  -c  cpfuncts.c 

cpinput. o  :  $H  cpinput. c 
cc  -c  cpinput. c 


Listing  Three 


/*  Set  the  appropriate  constant  */ 
/*  to  one  (1)  before  compiling.  */ 
/*  All  others  are  zero  (0)  */ 


♦define  MSDOS  0 
♦define  VMS  0 
♦define  UNIX  1 

Listing  Four 

♦if  VMS 

extern  int  binary_search_sorted_data_base {  char  *  ); 

extern  void  build_box_parts (  int  ); 

extern  int  build_the_data_base (  char  *  ); 

extern  void  check_for_new_page (  void  ); 

extern  int  doprint (  int  )  ; 

extern  void  nasty (  int  ); 

extern  void  process_arguments (  int,  int,  char  **,  int  ); 
extern  void  scan_for_static_or_global (  int  *,  int,  char 
extern  void  tab_to_left_margin (  FILE  *  ); 

static  void  allocate_arrays (  void  ); 

static  void  build_records_f rom_list (  FILE  *  ); 

static  void  bump_line_count (  void  ); 

static  void  count_all_defined_references (  void  ); 

static  void  deallocate_arrays (  void  ); 

static  void  do_top_of_page (  void  ); 

static  void  initialize_globals {  void  ); 

static  void  show_f iles_leading_comments (  void  ) ; 

static  void  show_function_relationships (  void  ); 

static  void  show_library_functions (  void  ); 

static  void  show_line_and_byte_counts (  void  ); 

static  void  show_page_references (  void  ); 

static  void  show_sorted_function_list (  void  ) ; 

static  void  show_unused_if_any (  void  ); 

static  void  sort_the_data_base_array (  void  ); 

static  char*  strdup(  char  *  ); 

static  void  timedate(  char  *  ); 

int  main(  int,  char  **  ); 

♦endif 


) ; 


♦if  MSDOS 

extern  int  near  binary_search_sorted_data_base (  char 
extern  void  near  build_box_parts (  int  ); 
extern  int  near  build_the_data_base (  char  *  )  ; 
extern  void  near  check_for_new_page (  void  ) ; 
extern  int  near  doprint (  int  ) ; 
extern  void  near  nasty (  int  ); 

extern  void  near  process_arguments (  int,  int,  char  **,  int  ); 

extern  void  near  scan_for_static_or_global (  int  *,  int,  char  *,  char  *  ); 

extern  void  near  tab_to_left_margin (  FILE  *  ); 

static  void  near  allocate_arrays (  void  ); 

static  void  near  build_records_from_list (  FILE  *  ); 

static  void  near  bump_line_count (  void  ); 

static  void  near  count_all_def ined_references (  void  ); 

static  void  near  deallocate_arrays (  void  ); 

static  void  near  do_top_of_page (  void  ); 

static  void  near  initialize_globals {  void  ) ; 
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static  void  near  show_f iles_leading_comments (  void  ) ; 
static  void  near  show_function_relationships (  void  ) ; 
static  void  near  show_library_functions (  void  ) ; 
static  void  near  show_line_and_byte_counts {  void  ); 
static  void  near  show_page_references (  void  ) ; 
static  void  near  show_sorted_function_list {  void  ); 
static  void  near  show_unused_if_any {  void  ); 
static  void  near  sortthedatabasearray (  void  ); 
static  char*  near  strdup(  char  *  ); 
static  void  near  timedate(  char  *  ); 

int  near  main(  int,  char  **  ); 

iendif 

Listing  Five 


char  *ret_time; 
{ 

char  *cp; 
int  i; 


cp  =  &ret_time[  0  ]; 
(void)_strdate (  cp  ); 
ret_time[  8  ]  =  ' 
cp  =  &ret_time[  10  ]; 
(void)_strtime (  cp  ); 


/*  insert  date  and  nice 


time  into  ret_time  */ 


ret_time[  15  )  =  '  '; 
ret_t ime [16]=''; 
ret_time[  17  ]  =  'm'; 
ret_timef  18  ]  =  '  '; 


/*  knock  off  seconds  */ 
/*  put  am,  pm  here  */ 


#if  MSDOS 

static  void  near  bump_line_count (  ) 
#else 

static  void  bump_line_count (  ) 
#endif 

Listing  Six 


i  =  atoi  (  &ret_time[  10  ]  );  /*  f/  military  to  civilian  time  */ 

ret_time[  16  ]  =  (  i  <  12  )?  (char) 'a':  (char)'p'; 

if  (  i  ==  0  ) 
i  =  12; 
if  (  i  >=  13  ) 
i  —  12; 


#if  MSDOS 

♦include  <malloc.h> 
♦include  <conio.h> 
♦include  <stdlib.h> 
♦endif 


(void) sprintf (  &ret_time[  10  ],  "%2d",  i  ); 
ret_time[  12  ]  = 

if(  ret_time[  10  ]  ==  '0'  ) 
ret_time[  10  ]  -  '  '; 


♦include  <ctype.h>  /*  this  is  for  the  'tolower'  function  */ 
♦include  <stdio.h> 

♦include  <string.h> 


♦endif 


**/ 


Listing  Seven 

♦if  MSDOS 
♦include  "time.h" 
♦else 

♦include  <time.h> 
♦endif 


Listing  Eight 

♦if  ! MSDOS 
char  *strdup (orig) 
char  *orig; 

{ 

char  *ptr; 

ptr  =  (char  *)  malloc(  (strlen (orig)  *  sizeof (char) )  +  1); 


Listing  Eleven 

if (islower ( (int) argv[i] [1] ) ) 
c  =  argv(i) [1] ; 
else 

c  =  (char) tolower (  (int)argv[  i  ][  1  ]  ); 


Listing  Twelve 

if(  strcmp(argv[2] , "con")  ==  0) 
output  =  stderr; 
else 

output  »  fopen(  argv[  2  ],  "w+"  );  /*******  wt+  «««« 


Listing  Thirteen 

(void) printf (  "\n  can't  open  output  file.Nn"); 


if (ptr  !=  NULL) 

{ 

strcpy (ptr,  orig)  ; 

) 

return (ptr)  ; 

) 

♦endif 


Listing  Nine 

timedate (title) ; 


Listing  Ten 

/**»*************************,*.************,*.*.***.********/ 

♦if  ! MSDOS 

static  void  timedate (ret_time) 
char  *ret_time; 

{ 

struct  tm  *time_structure; 
int  time_val,  i; 

static  char  *hour[2]  =  ("am","pm"}; 
char  temp [19]; 

time (Stime_val) ; 

time_structure  =  localtime (4time_val) ; 
i  =  0; 

if ( (time_structure->tm_hour  >=  12) && (time_structure->tm_hour<24) )  i=l; 

if (time_structure->tm_hour  >  12) 

time_structure->tm_hour  =  (time_structure->tm_hour) -12; 
sprintf (temp, "%d/%d/%d  %d:%02d  %s", 

time_structure->tm_mon, 

time_structure->tm_mday, 

time_structure->tm_year, 

time_structure->tra_hour, 

time_structure->tm_min, 

hour [i] ) ; 

i=0; 

while (temp[i] !='\0') 

{ 

ret_time[i]  =  temp[i]; 
i++; 

) 

) 

♦endif 
♦if  MSDOS 

static  void  near  timedate (ret_t ime) 


Listing  Fourteen 

if (  (length  >  65535)  &&  (MSDOS)  ) 

Listing  Fifteen 

$  CC/PREPROCESS_ONLY  CP.C 
$  CC/PREPROCESS_ONLY  CPBUILD.C 
$  CC/PREPROCESS_ONLY  CP INPUT. C 
$  CC/PREPROCESS_ONLY  CPFUNCTS.C 
$  CC/PREPROCESS_ONLY  CPHEADER. H 

Listing  Sixteen 

cc  -E  cp.c  >cp.i 
cc  -E  cpbuild.c  >cpbuild.i 
cc  -E  cpinput.c  >cpinput.i 
cc  -E  cpfuncts.c  >cpfuncts.i 
cc  -E  cpheader.h  >cpheader.i 

Listing  Seventeen 

cp.  i 

cpinput . i 
cpbuild. i 
cpfuncts .i 
cpheader.h 

Listing  Eighteen 

♦define  LEN_INFILE  256 

Listing  Nineteen 

char  input_list_f ilename [  LEN_INFILE  ],  input_line[  LEN_INFILE  ]; 
char  overlay_number [  LEN_INFILE  ]; 


Listing  Twenty 

fgets(  input_line,  LEN_INFILE-1,  stream  );  /*  ends  at  \n  or  eof  */ 

Listing  Twenty-One 

Replaces  line  20  of  Listing  Five 

* top_l ine_of _box ,  *bot  t  om_l i ne_o f _box , 
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Listing  Twenty-Two 

Replaces  lines  73  thru  75  of  Listing  Five 

if (  !(  top_line_of_box  =(char  *)malloc(  defined_box_width  *  sizeof(char)  )) 

) 

( 

{void) fprintf (  stderr,  "Ran  out  of  memory  for  top  line  of  box.\n"  ); 
exit  (  1  ) ; 

} 

if(  !(  bottom_line_of_box  =(char  *)malloc(  defined  box  width  *  sizeof (char)  )) 


(void) fprintf {  stderr,  "Ran  out  of  memory  for  bottom  line  of  box.\n”  ); 
exit {  1  ) ; 


top_line_of_box(  0  ]  =  upper_left_corner; 
bottom_line_of_box (  0  ]  =  lower_left_corner; 
for(  i  =  1;  i  <=  (defined_box_width  -  3);  ++i  ) 


Listing  Twenty-Three 

Replaces  lines  215  and  216  of  Listing  Five 


name_of_file, 

description, 


Listing  Twenty-Four 

Replaces  lines  228  thru  274  of  Listing  Five 

unsigned  int  string_length; 
int  x; 

static  char  alternate_lead_in [  140  ]; 
tab  to_left_margin(  output  ); 

(void) fprintf (  output,  "%s  %s\n",  lead_in_string,  top_line_of_box  ); 

/*******  2nd  line  ‘a****************************************************/ 
tab_to_left_margin(  output  ); 
string_length  =  strlen{  lead_in_string  ); 

if (  string_length  )  /*******  ie  not  main  or  defined  function  box  *“/ 

{ 

(void)strncpy{  alternate_lead_in,  lead_in_string,  — string_length  ); 
alternate_lead_in [  string_length++  ]  =  '\0';  /‘restore  string_length*/ 


if(  string_length  ) 


ie  not  main  or  defined  function  box 


if (  g_ov_flag  &&  ov_num  ) 

{ 

(void) fprintf (  output,  "%s%c%c%c%s  %3d", 
alternate_lead_in, 

/*“  if (  kill_flag  )  7““**  last  line  to  this  box 

/“*  else  /“““  iine  continues  downwards 

{  kill_flag  )?  lower_left_corner :  right_attach, 
ibm_line,  left_attach,  name_of_function,  ov_num) ; 
for (x=strlen (name_of_function) ;x  <  def ined_box_width-7;x++) 
putc('  '.output); 
putc (wall, output) ; 
putc (' \n' , output)  ; 

} 

else 

{ 

(void) fprintf  (  output,  "%s%c%c%c%s  ", 

alternate  lead_in, 

/“*  if  (  kill_flag  )  7******  last  line  to  this  box 

/*“  else  /“““  iine  continues  downwards 

(  kill_flag  )?  lower_left_corner :  right_attach, 
ibm_line,  left_attach,  name_of_f unction) ; 
for (x=strlen (name_of_function) ;x  <  defined_box_width-7;x++) 
putc('  ', output); 
putc (wall, output) ; 
putc(' \n' , output) ; 


se  /******  main  or  defined  box  starting  ***********/ 

I 

if{  g_ov_flag  44  ov_num  ) 

( 

(void) fprintf {  output,  "%c%c%s  %3d", 

ibm_line,  left_attach,  name_of_function,  ov_num) ; 
for (x=strlen (nameoffunction) ;x  <  def ined_box_width-7;x++) 
putc('  '.output); 
putc (wall, output) ; 
putc (' \n' , output) ; 

) 

else 

( 

(void) fprintf (  output,  "%c%c!s  ", 

ibm_line,  left_attach,  name_of_f unction) ; 
for (x=strlen (name_of_function) ;x  <  def ined_box_width-7;x++) 
putc('  '.output); 
putc (wall, output) ; 
putc (' \n' , output) ; 


tab_to_left_margin (  output  ); 

if  (  string_length —  )  /“  kill  outside  vertical  line  on  last  box  “/ 

lead_in_string [  string_length++  ]  =  (  kill_flag  )?  (char)'  ':  wall; 


(void) fprintf (  output,  "%s  %c%s  %8s%3d", 

lead_in_string,  wall,  name_of_file,  description, 

either_count); 

for (x=strlen (name_of_f ile) ;x  <  def ined_box_width-17; x++)  putc{'  '.output); 
putc (wall, output) ; 
putc (' \n' .output) ; 

Listing  Twenty-Five 

Insert  between  109  and  110  of  Listing  One 
defined_box_width  =  40, 

Listing  Twenty-Six 

Insert  between  160  and  161  of  Listing  One 
extern  int  def ined_box_width; 


Listing  Twenty-Seven 

Replaces  lines  20  through  25  of  Listing  Three 

/p:nn  /w:nn  /m:nn  /r:nn  /t:main  /frnnnn  /b:nn\n" 

) ; 

(void)printf ( 

/I  /n  /s  /q  /d  /o  /u  /c  /h  /x\n" 

) ; 

(void)printf (  "  ]\n"  ); 


Listing  Twenty-Eight 

Insert  between  45  and  46  of  Listing  Three 
(void) printf ( 

b:  width  of  func.  box  -  %2d  (  20  -  255  ]\n",  defined  box  width 

); 


Listing  Twenty- Nine 

Insert  between  155  and  156  of  Listing  Three 


case  'b' : 

iff  (  20  <  tmp  )  &&  (  tmp  <  255  )  ) 
defined_box_width  =  tmp; 

break:  End  Listings 
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C  LIST  MANAGER 


Listing  One  (Text  begins  on  page  48.) 

void  ‘dataptr, *val; 

/*  makelist-  list  management  package 

char  ‘propsym;  ( 

PROP  ‘newprop  =  (PROP  *) imalloc (sizeof (PROP) ) ; 

RF  Starr 

PROP  ‘topprop  =  list->prop; 

2639  Valley  Field  Dr. 

if  (Hist)  return  NULL; 

SugarLand,  TX  77479 

if  (! newprop)  return; 

*/ 

newprop->dataptr  =  dataptr; 

# include  <stdio.h> 

newprop->propsym  =  propsym; 
newprop->propval  =  val; 

♦include  <varargs.h> 

newprop->next  =  topprop; 

♦ifdef  MSDOS 

list->prop  =  newprop; 

♦include  <stdlib.h> 

) 

♦include  <malloc.h> 

♦else 

/*  Read  an  item  off  of  the  property  list  for  a  particular  data 

♦define  void  char 

item.  NULL  returned  if  there  is  none. 

extern  char  ‘malloc (); 

*/ 

♦endif 

void  * 

/♦♦define  DEBUG*/ 

getproplist (list , dataptr , propsym) 

LIST  ‘list; 

♦ifdef  DEBUG 

void  ‘dataptr, ‘propsym;  { 

PROP  *p; 

♦define  Debug (x)  x 

void  ‘propval  =  NULL; 

♦  else 

if  (llist)  return  NULL; 

♦define  Debug (x) 

p  =  list->prop; 

♦endif 

while  (p)  1 

typedef  struct  data  DATA; 

int  fsym  =  ! strcmp (p->propsym, propsym) ; 

if  ( ( ! dataptr  &&  fsym)  ! !  (p->dataptr  ==  dataptr  &&  fsym))  { 

typedef  struct  list  LIST; 

propval  =  p->propval; 

typedef  struct  prop  PROP; 

break; 

struct  data  { 

) 

p  =  p->next; 

void  ‘data;  /*  space  for  list->nentries  instances  of  data  */ 

I 

DATA  *next;  /*  next  list->nentries  collection  of  data  */ 

); 

return  propval; 

) 

struct  prop  { 

/*  Find  data  item  associated  with  a  property  name  */ 

void  ‘dataptr;  /‘to  what  data  item  this  property  associates  */ 

void  * 

void  ‘propval;  /*  property  value  to  associate  with  the  data  */ 

findprop (list, propsym) 

void  ‘propsym;  /*  optional  symbol  (usually  char  *)  to  associate  */ 

LIST  ‘list; 

PROP  ‘next; 

char  ‘propsym;  ( 

}; 

PROP  *p; 

struct  list  { 

if  (Hist)  return  NULL; 
p  =  list->prop; 

int  entrysize;  /*  size  of  each  data  entry  in  bytes  */ 

while  (p)  ( 

int  nentries;  /*  ♦  entries  to  grab  per  malloc  call  */ 

if  (! strcmp (p->propsym, propsym) )  return  p->dataptr; 

int  empty  slots;  /*  empty  slots  left  in  current  data  block  */ 

p  =  p->next; 

int  nitems;  /*  total  items  saved  in  this  list  */ 

} 

int  ecount;  /*  where  we  are  when  reading  back  list  */ 

return  NULL; 

int  f block; 

) 

DATA  ‘fdata; 

PROP  ‘prop;  /*  optional  property  list  for  this  list  */ 

/*  Append  data  to  the  specified  list  */ 

DATA  ‘data;  /*  linked  list  for  the  actual  data  of  this  list  */ 

static  void 

DATA  ‘hidata;  /*  highest  allocated  data  block  (for  efficiency)  */ 

whereis (list, ndx, walk, put) 

I; 

LIST  ‘list; 

/*  Internal  malloc  routine  */ 

int  ‘walk, ‘put;  { 

‘walk  =  ndx  /  list->nentries; 

/‘♦define  MEMCHK* / 

‘put  =  ndx  %  list->nentries; 

) 

♦ifdef  MEMCHK 

static  FILE  ‘memfp  =  NULL; 

♦endif 

/*  Remove  last  entry  on  the  specified  list...  adjust  struct  accordingly  */ 

static  void  * 

void  * 

imalloc (size) 

poplist (list) 

int  size;  ( 

LIST  ‘list;  ( 

void  *ptr  =  malloc(size) ; 

DATA  *org; 

♦ifdef  MEMCHK 

void  *dp  =  NULL; 

if  (!memfp)  memfp  =  fopen ("meminfo", "w") ; 

unsigned  char  ‘data; 

♦endif 

int  put; 

if  (!ptr)  ( 

if  (Hist)  return  NULL; 

fprintf (stderr, "malloc  error:  no  free  memory  left.Xn"); 

if  ( !  list->nitems)  return  dp; 

f flush (stderr) ; 

org  =  list->data; 

) 

list->empty  slots++; 

♦ifdef  MEMCHK 

list->nitems — ; 

fprintf (memfp, "%x  malloc\n", ptr) ; 

if  (list->empty  slots  ==  list->nentries)  ( 

f flush (memfp) ; 

while  (org->next)  org  =  org->next; 

♦endif 

put  =  list->nitems  %  list->nentries; 

return  ptr; 

data  =  (unsigned  char  *)org->data; 

} 

dp  =  (void  *) (data+(list->entrysize*put) ) ; 

static  void  * 

if  (org->next)  ifree (org->next) ,  org->next  =  NULL; 
list->hidata  =  org; 

) 

ifree (addr) 

void  ‘addr;  ( 

return  dp; 

free (addr) ; 

♦ifdef  MEMCHK 

fprintf (memfp, "%x  f ree\nM, addr) ; 

/*  calculate  data  pointer  for  the  ndx  entry  */ 

f flush (memfp) ; 

static  void  * 

♦endif 

calcdp (list, ndx) 

LIST  ‘list; 

/*  Build,  initialize,  and  return  an  empty  list  */ 

DATA  ‘pdata; 

void  * 

unsigned  char  *dp; 

makelist  (esize, nentries) 

int  size  =  (list)  ?  list->entrysize  :0; 

int  esize, nentries;  ( 

LIST  ‘list  =  imalloc (sizeof (LIST) +sizeof (DATA) +esize*nentries) ; 

void  *dp  =  imalloc (sizeof (DATA) +esize*nentries) ; 

if  (Hist  :  1  ndx  >=  max)  return  (void  *)NULL; 

if  (Hist  ..  ! dp)  return  NULL; 

whereis (list,  ndx, &walk, &put) ; 

list->data  =  (DATA  *)dp; 

list->data->data  =  (char  *)dp  +  sizeof (DATA) ; 

while  (walk — )  pdata  =  pdata->next; 

list->entrysize  =  esize; 

dp  =  (unsigned  char  * ) pdata->data; 

list->nentries  =  nentries; 

return  (char  *) (dp+ (size*put) ) ; 

I 

list->emptv  slots  =  nentries; 

list->nitems  =  0; 

list->ecount  =  0; 

/*  Return  pointer  to  data  which  is  last  on  the  list  */ 

list->fblock  =  0; 

list->fdata  =  NULL; 

toplist (list) 

list->prop  =  (PROP  *) NULL; 

LIST  ‘list;  ( 

list->hidata  =  list->data; 

void  *dp  =  NULL; 

list->data->next  =  NULL; 

void  ‘fetchlist {) ; 

return  (void  *)list; 

unsigned  char  ‘data; 

) 

int  put; 

/*  Put  items  on  property  list  for  this  data  item.  Propsym  is  the 

if  (Hist  1!  ! list->nitems)  return  NULL; 
return  calcdp (list, list->nitems-l) ; 

) 

property  symbol,  and  val  is  a  pointer  to  a  static  are  where  the 

data  for  this  property  resides. 

*/ 

/*  append  a  data  item  onto  specified  list  */ 

putproplist (list, dataptr, propsym, val) 

void  * 

LIST  ‘list; 
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appendlist (list, data) 

LIST  *list; 
void  ‘data;  { 

DATA  ‘pdata; 

void  * where; 

unsigned  char  *dp; 

int  walk, put, size; 

if  ('.list)  return  NULL; 

size  =  list->entrysize; 

whereis (list, list->nitems, &walk, &put) ; 

pdata  =  list->hidata; 

if  ( ! list->erapty_slots)  ( 

void  *mem  =  imalloc (sizeof (DATA) +size*list->nentries) ; 
if  (!mem)  return  NULL; 

list->hidata  =  pdata  =  pdata->next  =  (DATA  *)mem; 
pdata->data  =  (void  *)((char  *) mem+sizeof (DATA) ) ; 
pdata->next  =  NULL; 
list->empty_slots  =  list->nentries; 

) 

dp  =  (unsigned  char  *) pdata->data; 
where  =  (char  *) (dp+ (put‘size) ) ; 
memcpy (where, data, size) ; 
list->empty_slots — ; 
list->nitems++; 
return  where; 


/*  return  index  of  NEXT  list  entry  */ 
listindex (list) 

LIST  ‘list;  ( 

return  list->nitems; 

} 

/*  append  a  data  item  onto  specified  list  with  property  value  information  */ 
void  * 

pappendlist (list, data, propsym, val) 

LIST  ‘list; 
void  *data,*val; 
char  ‘propsym;  ( 

void  ‘dataptr  =  appendlist (list, data) ; 
if  (dataptr)  putproplist (list, dataptr, propsym, val) ; 
return  dataptr; 

) 

/*  Just  like  appendlist...  new  name  for  compatibility  with  poplist  */ 
void  * 

pushlist (list, data) 

LIST  ‘list; 
void  ‘data;  { 

if  (Hist)  return  NULL; 
return  appendlist (list, data) ; 

) 

/*  Fetch  a  specific  data  item  off  of  list...  ndx  is  0-based  */ 
void  * 

fetchlist (list, ndx) 

LIST  ‘list; 
int  ndx;  { 

DATA  ‘pdata; 

unsigned  char  *dp; 

int  size  =  list->entrysize; 

int  max  =  list->nitems; 

int  walk, put; 

if  (llist)  return  NULL; 

if  (ndx  >=  max)  return  (void  *)NULL; 

whereis (list, ndx, &walk, Sput) ; 

if  (walk  ==  list->fblock) 

list->fdata  =  pdata  =  (list->fdata)  ?  list->fdata  :  list->data; 

else  { 

pdata  =  list->data; 
list->fblock  =  walk; 
while  (walk — ) 

pdata  =  pdata->next; 


list->fdata  =  pdata; 

) 

dp  =  (unsigned  char  *) pdata->data; 

Debug (printf ("fetchlist:  getting  data  from  %x\n" , dp+ (size*put) ) )  ; 
return  (char  *)  (dp+ (size*put) ) ; 

} 

/*  reset  pointer  used  by  walklist  */ 
rewindlist (list) 

LIST  ‘list;  ( 

if  (list)  list->ecount  =  0; 

) 

/*  walk  down  the  list,  returning  each  data  item  'till  there  ain't  no  more  */ 
void  * 

walklist (list) 

LIST  ‘list;  ( 

DATA  ‘pdata; 

unsigned  char  *dp; 

int  size  =  list->entrysize; 

int  max  =  list->nitems; 

int  index  =  list->ecount; 

int  walk, put; 

if  (llist)  return  NULL; 

dp  =  (unsigned  char  *) fetchlist (list, index) ; 
if  (!dp) 

list->ecount  =  0; 

else 

list->ecount++; 

return  (list->ecount)  ?  (void  *)dp  :  (void  *)NULL; 


/*  malloc  size  bytes,  and  add  address  of  malloced  space  to  the  list 
void  * 

malloclist (list, size) 

LIST  ‘list; 
int  size;  ( 

void  *dp; 

if  (llist)  return  NULL; 
dp  =  imalloc (size) ; 
if  (dp)  appendlist (list, &dp) ; 
return  dp; 


/*  Free  up  all  malloced  data  associated  with  the  specified  list  */ 
freelist (list) 

LIST  ‘list;  { 

f 1 (list, 0) ; 

} 

/*  garbage  collect  list...  assume  all  data  in  list  is  malloced  ptrs  */ 
gclist (list) 

LIST  ‘list;  { 

fl (list, 1) ; 

) 

/*  Free  the  list  up.  If  freedp  !=  0,  free  each  data  pointer  as  well  */ 
static 

fl (list, freedp) 

LIST  ‘list;  { 

DATA  ‘pdata, *ppd; 

PROP  *p  =  list->prop; 
if  (llist)  return; 
pdata  =  list->data; 
if  (freedp)  { 

void  *dp; 

rewindlist (list) ; 

while  (dp=walklist (list) ) 

ifree(*(char  *  * ) dp ) ; 

) 

/*  free  all  malloced  data  */ 
while  (pdata)  { 

DATA  ‘next  =  pdata->next; 
ifree (pdata) ; 
pdata  =  next; 

) 

/*  free  all  malloced  property  info  */ 
while  (p)  { 

PROP  *n  =  p->next; 
ifree (p) ; 

P  =  n; 


given  a  list  of  functions,  invoke  the  function  with  the  specified 
property  tag  with  the  arguments  supplied. 


/‘funclist (list, prop, args)  (actual  calling  argument  list)*/ 
int 

funclist (va_alist) 
va_dcl  ( 

void  ‘list; 

void  ‘prop; 

void  *vp; 

int  (*func)(); 

va_list  argmark; 

va_start (argmark) ; 

list  =  va_arg (argmark, void  *); 

prop  =  va_arg (argmark, void  *); 

vp  =  findprop (list, prop) ; 

if  (Ivp)  return  0; 

func  =  Mint  (“){))vp; 

return  (*func) (argmark) ; 


End  Listing  One 


Listing  Two 


/*  Header  file  for  makelist  */ 

/*  Remove  this  if  you  don't  have  ANSI  C  compiler  */ 

♦define  ANSIC 

♦ifndef  ANSIC 
♦define  void  char 
♦endif 

/*  Usage:  e.g.  deref(int,x)  or  dereffchar  *,x)  */ 

♦define  deref (type, x)  * ( (type* ) (x) ) 

/*  Function  prototypes/declarations  */ 

/* - */ 

♦ifdef  ANSIC 

extern  void  ‘makelist (int  esize,int  nentries) ; 

extern  int  putproplist (void  ‘list, void  ‘dataptr, char  ‘propsym, void  *val); 

extern  void  ‘getproplist (void  ‘list, void  ‘dataptr, void  ‘propsym); 

extern  void  ‘toplist (void  ‘list); 

extern  void  ‘poplist (void  ‘list); 

extern  void  ‘appendlist (void  ‘list, void  ‘data) ; 

extern  void  ‘pappendlist (void  ‘list, void  ‘data, char  ‘propsym, char  *val); 

extern  void  ‘pushlist (void  ‘list, void  ‘data) ; 

extern  void  ‘fetchlist (void  ‘list, int  ndx) ; 

extern  void  ‘walklist (void  ‘list) ; 

extern  void  rewindlist (void  ‘list); 

extern  void  ‘malloclist (void  ‘list, int  size) ; 

extern  int  freelist (void  ‘list); 

extern  int  gclist (void  ‘list); 

extern  int  funclist (void  *,...); 

extern  int  listindex (void  ‘list); 

♦else 

extern  void  ‘makelist (); 
extern  int  putproplist () ; 
extern  void  ‘getproplist () ; 
extern  void  ‘toplist  (); 
extern  void  ‘poplist (); 
extern  void  ‘appendlist () ; 
extern  void  ‘pappendlist () ; 
extern  void  ‘pushlist (); 
extern  void  ‘fetchlist () ; 
extern  void  ‘walklist (); 
extern  void  rewindlist () ; 
extern  void  ‘malloclist () ; 
extern  int  freelist (); 
extern  int  gclist (); 
extern  int  funclist  (); 
extern  int  listindexO; 


End  listings 
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DEBUGGING  C  PROGRAMS 


Listing  One  (Text  begins  on  page  56.) 

short  tlevel  =  0; 

local  =  0x77778888; 

♦ifdef  STACKLOW  /*  Stack  grows  towards  LOWER  addresses  */ 

main (argc,  argv,  envp) 

for  (ip  =  stacktop;  ip  >=  &local;  ip — ) 

char  *argv[]; 

♦else  /*  Stack  grows  towards  HIGHER  addresses  */ 

char  **envp; 

for  (ip  =  stacktop;  ip  <=  Slocal;  ip++) 

( 

♦endif 

int  n; 

printf ("%081x\t%08x\n“,  ip,  *ip); 

for  (n  =  0;  n  <  argc;  n++) 

1 

if  (argv[n][0]  ==  &&  argv[n] [1]  ==  'L') 

End  Listing  Two 

int  i; 
char  digit; 

Listing  Three 

/*  Found  -L  argument  -  process  it  */ 

calltrace (arg_l)  /*  Trace  calling  sequence  */ 

digit  =  argv[n] [2] ; 

int  *bp,  *newbp; 

if  (digit  <  '0'  I!  digit  >  '9') 

( 

bp  =  (int  *)  (&arg  1  -  2); 

printf ("Bad  -L  option\n"); 
exit  (1) ; 

while  (bp  <  stacktop)  /*  "<"  because  STACKLOW  */ 

tlevel  =  digit  -  'O'; 

newbp  =  (int  *)  *bp;  /*  next  link  in  list  */ 

printf ("BP=%081x  RET.  ADDR=%081x\n",  bp,  * (bp  +  1)); 

/*  Delete  this  element  from  argv[J.  */ 

bp  =  newbp; 

/*  We  assume  that  argv[)  has  argc+1  */ 

/*  elements  (most  systems  set  argv(argc)  */ 

/*  to  zero) .  */ 

!  1  End  Listing  Three 

argc — ; 

for  (i  =  n;  i  <  argc;  i++) 

argv[i]  =  argv[i+l]; 

Listing  Four 

1 

struct  func 

mymain(argc,  argv,  envp); 

int  (*addr)(); 

char  *name; 

End  Listing  One 

}; 

int  main  () ,  f  () ,  g  () ; 

Listing  Two 

struct  func  funcsf]  =  /*  symbol  table  */ 

{ 

/*  showstack:  Show  layout  of  host  machine's  stack  */ 

main,  "main", 

♦define  STACKLOW  1 

f,  "f", 

int  *stacktop,  *ip; 
int  f ( ) ,  g ( ) ; 

g.  "g"/ 

); 

main (argc,  argv) 

int  nfuncs  =  sizeof (funcs) /sizeof  (funcs [0] ) ; 

char  “argv; 

I 

char  *atoname(a)  /*  convert  address  to  function  name  */ 

stacktop  -  (int  *)  iargv; 

printf ("&argc=%081x  &argv=%081x\n",  &argc,  Sargv) ; 

int  (*a)();  /*  address  */ 

( 

printf ("&main=%081x  &f=%081x  &g=%081x\n",  main,  f,  g) ; 

char  *s; 

f (0x11112222,  0x33334444); 

} 

int  (*maxa)(); 
int  n; 

f(arg_l,  arg_2) 

maxa  =  0; 

g (0x55556666); 

for  (n  =  0;  n  <  nfuncs;  n++) 

) 

if  (funcs [n] .addr  <  a  &&  funcs [n] . addr  >  maxa) 

s  =  funcs ( n ] . name,  maxa  =  funcs [ n ) .addr; 

g (arg_2) 

return  s; 

( 

int  local; 

End  Listings 
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MEMORY  ALLOCATORS 


Listing  One  (Text  begins  on  page  62.) 

/*  syml.c  -  symbol  table  data  types  */ 

#include  <stdio.h> 

♦include  "xalloc.h" 

♦include  "defs.h" 


Symbol  *plf  *p2; 

char  *ps  =  "test  string"; 

int  *p5; 

pi  =  (Symbol  *)  xmalloc (sizeof (struct  Symbol)); 
pl->dtype  =  STRING; 

pl->val.pstring  =  xmalloc (strlen (ps)  +  1); 
strcpy (pl->val. pstring,  ps) ; 

p2  =  (Symbol  *)  xmalloc (sizeof (struct  Symbol)); 
p2->dtype  =  DOUBLE; 

p2->val .pdouble  =  (double  *)  xmalloc (sizeof (double) ) ; 
*p2->val .pdouble  =  6.7e-13; 

printf ("%s\n",  pl->val.pstring) ; 
printf ("lg\n",  *p2->val .pdouble) ; 

p5  =  (int  *)  xmalloc (30000  *  sizeof (int) ) ; 


$  syml 
test  string 
6.7e-13 

file  syml.c  -  line  26: 


malloc  error  for  60000  bytes 


Listing  Two 

♦include  <stdio.h> 
♦include  <malloc.h> 


♦define  MAXBUF  256 
static  char  *dbuf (MAXBUF]; 


End  Listing  One 


size  of  debug  buffer  */ 
debug  buffer  */ 


/*  ymalloc2.c 
*/ 


front  end  for  malloc () 
Version  2 


char  *ymalloc (f ile,  lineno,  nbytes) 
char  *file; 
int  lineno; 
unsigned  int  nbytes; 

I 

char  ‘pheap; 
void  install (); 

pheap  =  malloc (nbytes) ; 
if  (pheap  ==  (char  *)  NULL)  ( 


fprintf (stderr, "file  Is  -  line  %d:  malloc  error  for  %u  bytes\n", 
file,  lineno,  nbytes); 

exit  (1) ; 


I 


install (pheap) ; 
return  pheap; 


/*  place  in  debug  buffer  */ 


/*  store  heap  pointer  in  debug  buffer  */ 


void  install (pheap) 
char  ‘pheap; 

{ 

register  char  **pbuf; 

for  (pbuf  =  dbuf;  pbuf  <  dbuf  +  MAXBUF;  pbuf++) 
if  (*pbuf  ==  (char  *)  NULL)  ( 

‘pbuf  =  pheap; 
return; 

} 

fprintf (stderr,  "No  room  left  in  debug  buffer\n"); 
exit (1)  ; 

) 

char  ‘yrealloc (file,  lineno,  oldp,  nbytes) 
char  ‘file,  ‘oldp; 
int  lineno; 
unsigned  int  nbytes; 

{ 

char  *newp; 
register  char  “pbuf; 
short  found  =  0; 

if  (oldp  !=  (char  *)  NULL) 

for  (pbuf  =  dbuf;  pbuf  <  dbuf  +  MAXBUF;  pbuf++) 

if  (*pbuf  ==  oldp)  (  /*  find  oldp's  slot  */ 

found  =  1; 
break; 

) 

if  (! found)  { 

fprintf (stderr, "file  Is  -  line  Id:  realloc  error  for  address  lx\n", 
file,  lineno,  oldp) ; 

exit (1) ; 

) 

newp  =  realloc (oldp,  nbytes); 
if  (newp  ==  (char  *)  NULL)  f 

fprintf (stderr, "file  Is  -  line  Id:  realloc  error  for  %u  bytes\n", 
file,  lineno,  nbytes); 

exit (1) ; 


*pbuf  =  newp; 
return  newp; 


/*  replace  in  debug  buffer's  old  slot  */ 


void  yfree(file,  lineno,  pheap) 
char  *file,  *pheap; 
int  lineno; 

{ 

register  char  **pbuf; 

if  (pheap  !=  (char  *)  NULL) 

for  (pbuf  =  dbuf;  pbuf  <  dbuf  +  MAXBUF;  pbuf++) 
if  (*pbuf  ==  pheap)  ( 

*pbuf  =  NULL; 
free (pheap) ; 
return; 

) 

fprintf (stderr, "file  Is  -  line  Id:  free  error  for  address  lx\n", 
file,  lineno,  pheap); 

exit (1) ; 


Listing  Three 

/*  sym2.c  -  more  symbol  table  data  types  */ 

♦include  <stdio.h> 

♦include  "xalloc.h" 

♦include  "defs.h" 

main  () 

( 

Symbol  *pl,  *p2; 

char  *ps  =  "test  string"; 

char  *ps2  =  "much  longer  test  string"; 

pi  =  (Symbol  *)  xmalloc (sizeof (struct  Symbol)); 
pl->dtype  =  STRING; 

pl->val .pstring  =  xmalloc (strlen (ps)  +  1); 
strcpy (pl->val .pstring,  ps); 

p2  =  (Symbol  *)  xmalloc (sizeof (struct  Symbol)); 
p2->dtype  =  DOUBLE; 

p2->val .pdouble  =  (double  *)  xmalloc (sizeof (double) ) ; 

*p2->val .pdouble  =  6.7e-13; 

printf ("ls\n",  pl->val .pstring) ; 
printf ("%g\n",  *p2->val .pdouble) ; 

pl->val. pstring  =  xrealloc (pl->val .pstring,  strlen (ps2)  +  1); 
strcpy (pl->val. pstring,  ps2); 
printf ("ls\n",  pl->val. pstring) ; 


End  Listing  Two 


xfree((char  *)  p2->val. pdouble) ; 
xfree (ps2) ; 


/*  free  a  bad  pointer  */ 


$  sym2 
test  string 
6. 7e-13 

much  longer  test  string 

file  sym2.c  -  line  31:  free  error  for  address  2634 


End  Listings 
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n  the  June  1986  issue  of  Dr.  Dobbs  Journal,  I  wrote  a  “Viewpoint”  entitled  “What’s 

Wrong  With  C.”  Have  things  changed  enough  to  make  me  alter  my  opinion?  While  the 

title  of  this  “Viewpoint”  probably  gives  away  my  position  today,  it  is  nonetheless  time 
to  reassess  the  state  of  C,  and  see  how  it  stacks  up  for  the  1990s. 

Just  to  recap:  My  two  principle  objections  to  C  in  the  mid-1980s  were:  a.  The  quality  of  C 
compilers  and  their  output;  and  b.  The  productivity  (including  the  maintenance  part  of 
the  software  life  cycle)  of  programmers  using  C.  Let’s  put  the  easy  one  to  bed  quickly  — 
the  quality  of  today’s  C  compilers  is  dramatically  better  than  it  was  a  few  years  ago. 

The  popularity  of  a  language  correlates  well  with  the  quality  of  its  compilers.  The 
compiler  vendors  can  afford  to  spend  more  of  those  expensive  man-hours  improving  a 
product  that  sells  well  —  and  they  are  compelled  by  competition  to  do  so.  This  is  why 
nasty  (but  popular)  languages,  such  as  Fortran  and  Cobol,  often  produce  the  tightest  code 
in  the  environments  where  they  run. 

The  size  and  quickness  of  the  object  code  is  (mostly)  a  consequence  of  the  implementation, 
not  the  language  itself.  The  real  point  is  that  C,  with  its  inherently  low-level  nature,  is 
much  harder  (but  not  impossible,  as  my  1986  article  implied)  to  optimize  to  the  same 
degree  as  “better"  languages.  I’m  still  willing  to  bet  that  Microsoft  has  many  more 
man-months’  effort  invested  in  its  C  compilers’  optimizing  technology  than,  for  example, 
JPI  has  in  the  optimization  portions  of  its  excellent  Modula-2,  which  produces  comparable 
code.  Perhaps  many  times  more.  But,  as  long  as  someone  has  gone  to  the  trouble  for  us, 
and  as  long  as  people  are  willing  to  amortize  the  extra  cost  by  buying  and  using  C  in 
droves,  then  who  cares?  C  compilers  nowadays  are  generally  “right  and  tight.”  They  are 
production  quality  tools  in  a  way  much  hyped  and  hoped  for  in  the  early  1980s,  but 
seldom  seen. 

Somewhat  of  a  corollary  to  C’s  inherently  low-level,  operator-rich,  “portable  assembler” 
character  was  an  ethos  I  thought  of  as  “small  is  beautiful.”  The  idea  was  that  obscure 
idioms  are  O.K.  because  “the  notational  convenience  is  considerable”  (to  quote  K&R); 
and  that  C  compilers  did  not  have  much  to  do  because  a  truly  good  programmer  could 
always  build  his  own  (ideally  designed  and  reusable)  libraries;  and  unerringly  find  the 
appropriate,  optimal  algorithm;  and  without  fail  put  a  finger  on  the  right  ten  percent  of  a 
program  to  convert  into  assembler;  or  do  something  else  beautiful  (while  expending 
practically  no  time)  to  compensate  for  the  elegant  simplicity  of  his  tools. 

Tens  of  thousands  of  people  are  now  using  C  full  time;  it  should  be  obvious  that  we  are 
not  all  legendary  coding  paragons  such  as  Jon  Bentley,  Dennis  Ritchie,  and  Brian  Kemighan. 
Let  “small  is  beautiful”  rest  in  peace.  Codified  ANSI  C  seems  much  less  the  small, 
informally  specified,  gratuitously  “elegant,”  personal  use  language  that  was  so  objectionable 
to  those  facing  large-scale,  serious  systems  implementation  projects.  ANSI  C  is  larger,  with 
a  more  “designed  by  committee"  feel.  ANSI  C  is  internally  more  complex,  for  the  purpose 
of  providing  real-world  production  services,  such  as  compile-time  parameter  checking, 
which  production  coding  shops  have  come  to  expect  and  depend  on. 

C  compilers  are  now  presented  as  environments  that  do  lots  of  things  for  the  “pilot.” 
State-of-the-art  debuggers  and  code  profilers  and  front  ends  with  hypertext  online 
documentation  are  conveniently  (or  instantly)  available,  as  are  function  libraries,  prepackaged 
to  do  nearly  any  part  of  an  application  the  programmer  doesn’t  wish  to  tackle.  The 
infrastructure,  which  has  grown  up  around  C,  has  contributed  enormously  to  the  productivity 
of  C  programmers.  For  my  money,  this  is  as  it  should  be  and  (almost)  all  to  the  good. 

In  most  programming  situations,  bottom-line  productivity  —  man-hours  to  a  result  with 
some  acceptable  functionality  —  is  the  most  important  factor  separating  the  quick  from 
the  dead.  C  programmers  are  probably  more  productive  than  ever  before;  I  believe  it  is 
safe  to  say,  even  without  citing  corroborating  studies.  It  may  be  ironic  that  the  plethora 
of  productivity  aids  surrounding  C  grew  up  because  raw  “early  C”  was  so  idiomatic  and 
difficult  that  help  had  a  market  value.  Or  it  may  be  that  the  utilities  and  subordinate  tools 
appeared  for  reasons  having  nothing  to  do  with  alleged  difficulties  in  C.  Again,  who  cares, 
as  long  as  we  got  the  boost  we  needed? 

A  tremendous  strength  of  C,  which  I  totally  overlooked,  is  evidenced  by  the  growth  of 
new  technologies  that  leverage  on  C’s  portability  and  low-level  robustness.  The  very 
terseness  and  richness  of  C’s  operator  set,  which  I  bemoaned  as  distracting  to  the  human 
programmer,  makes  C  a  good  target  language  to  be  emitted  from  translators  evincing  new 
concepts  and  powers.  C++  is  perhaps  the  most  famous  example  of  this.  The  first  C++ 
emitted  ordinary  C  as  its  output,  bringing  “object  oriented-ness”  to  C  in  the  same  way  that 
RATFOR  brought  “structured-ness”  to  Fortran. 

Even  for  those  purists  who  believe  that  tacking  on  “object  orientation”  to  an  existing 
language  is  the  wrong  approach,  C  has  made  its  contribution.  For  example,  Bertrand 
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Meyer’s  Eiffel  language  emits  C  as  its 
object  code.  Eiffel  is  a  promising,  prac¬ 
tical  (not  interpreted  or  Smalltalk-like), 
purely  object-oriented  programming  sys¬ 
tem.  Meyer’s  (recommended)  book,  The 
Design  of  Object  Oriented  Systems ,  uses 
Eiffel  as  its  “presentation  language." 

When  employed  as  an  intermediate 
language,  C’s  terse  and  impenetrable 
tendencies  may  be  a  decided  plus.  No 
less  an  authority  than  Knuth  advises 
that  if  the  emitted  code  is  deliberately 
unfriendly,  then  people  will  use  the 
front  end  for  modifications,  rather  than 
tweaking  the  intermediate  (C)  code  and 
causing  maintenance  headaches.  Knuth’s 
WEB  document  compiler  system  uses 
this  approach,  deliberately  emitting  “un¬ 
readable”  Pascal.  Arranging  for  your 
new  translator  to  emit  unreadable  C 
should  be  easy;  getting  human  beings 
(or  anything  else)  to  write  halfway  read¬ 
able  C  appears  to  be  the  real  trick. 

C  still  is  (in  my  mind)  the  consum¬ 
mate  virtuoso’s  ax  for  “programming 
in  the  small.”  For  large  teams  working 
on  large  problems,  even  ANSI  C’s  im¬ 
provements  are  not  enough.  I  am  in¬ 
trigued  by  how  much  of  the  interest  in 
C++  and  other  C  variants  (such  as  Ob¬ 
ject  C  and  Objective  C)  may  be  due  not 
to  the  attractions  of  object-oriented  tech¬ 
nology  itself  (which  truly  requires  a 
shift  in  world  view)  but  to  the  possibil¬ 
ity  that  “C  objects”  might  be  used  in  the 
context  of  traditional  design  (as  Modula- 
2  modules  and  Ada  packages).  That  is, 
to  render  “programming  in  the  large" 
more  practical  and  productive,  and  de¬ 
sign  software  modules  more  “plug  com¬ 
patible”  and  reusable.  The  perceived 
need  is  not  for  (yet  another)  funda¬ 
mental  paradigm  shift,  but  rather  for  a 
way  to  manage  implementation  of  large 
traditional  designs  in  a  language  that 
is  neither  obscure,  nor  unwieldy,  nor 
disdained  by  the  best  programmers. 
Many  people  appear  to  be  examining 
the  “right  technology”  (such  as  object 
oriented-ness)  for  the  “wrong  reason" 
(or  the  hope  of  data  abstraction  and 
reliable  modularity)  just  because  both 
the  reason  and  the  technology  are  con¬ 
nected  with  C. 

It  is  a  monument  to  C’s  mutability, 
resilience,  and  popularity  among  the 
best  and  brightest  that  C  seems  to  be 
carrying  the  freight  of  the  world’s  hope 
for  a  language  which  is  great  for  the 
individual,  nice  for  the  team,  and  eco¬ 
nomical  for  the  life  cycle  of  a  system. 

DDJ 
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Each  bound  volume  contains  a  full  year’s  worth  of  useful  code  and  fascinating  history  from  Dr. 
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Chronicles  the  advent  of  the  microcomputer  era  in  1 976.  Always 
pertinent  for  bit  crunching  and  byte  saving,  home-brew  computer 
projects,  and  the  technical  history  of  home  computing.  Topics 
include:  Tiny  BASIC,  the  first  words  on  CP/M,  speech  synthesis, 
floating  point  routines,  the  6502  disassembler  for  the  Apple,  and 
much  more.  364pp. 

Volume  2  — 1976 

The  small  computer  emerges  as  a  powerful  tool  for  the  modem 
age  in  these  issues  from  1977.  Topics  include:  Lawrence  Liver¬ 
more  Lab’s  BASIC,  Dr.  Starkweather’s  PILOT,  using  a  modem, 
string-handling  techniques,  ciphers,  Turtle  graphics,  and  micro 
utilities.  498pp. 

Volume  3  —1978 

Explores  the  foundation  of  the  mass-market  computer  industry  in 
1978.  Topics  include:  programming  in  BASIC,  PILOT,  and 
Pascal;  RAM  memory  testers;  Apple  utility  programs;  the  S-100 
bus  standard;  STRUBAL;  and  a  structured  BASIC  compiler. 
478pp. 


Heralds  the  widespread  acceptance  of  the  microcomputer  in 
America.  Innovative  ideas  and  articles  guide  the  reader  through 
the  age  of  discovery  in  1979.  Topics  include:  selecting  business 
software,  microcomputer  speech  and  music,  information  net¬ 
works,  and  interfacing  techniques.  467pp. 

Volume  5  —1980 

Focuses  on  the  technological  promise  of  the  modem  microcom¬ 
puter.  Topics  include:  the  revolutionary  impact  of  CP/M,  C  pro¬ 
gramming  and  the  UNIX  operating  systems,  a  survey  of  computer 
networks,  software  portability,  introduction  to  Forth,  and  com¬ 
piler  writing.  450pp. 

Volume  6  — 1981 

The  microcomputer  enters  the  mainstream-these  issues  assess  the 
revolutionary  impact  of  microcomputers  on  the  individual  and  on 
society  in  1981.  Topics  include:  computer  conferencing,  the 
power  of  Forth,  B-  and  1 6-bit  technology,  Rubik’s  cube  simula¬ 
tor,  and  an  adventure  game  development  system.  558pp. 

Volume  7  — 1982 


Examines  the  potential  of  powerful  16-bit  micros,  including  the 
birth  of  the  IBM  PC  in  1982.  Topics  include:  in-depth  coverage 
of  Forth,  68000, 8088  programming,  C  software  tools,  utilities  for 
CP/M — including  a  spelling  checker,  using  bulletin  boards,  and 
more.  568pp. 


More  Bound  Volumes 


Volume  8  — 1983  Volume  11  — 1986 


DDJ  turns  pro.  Some  of  the  most  powerful  professional  program¬ 
mer’s  tools  ever  published  in  a  magazine  are  in  this  1983  volume, 
including  Small-C,  the  RED  editor,  and  an  Ada  subset.  798pp. 

Volume  9  — 1984 

Shaping  things  to  come.  In  1984  DDJ  examined  new  program¬ 
ming  environments  Prolog,  expert  systems,  Modula-2,  and  Pas¬ 
cal.  Other  topics  include  GREP,  UNIX  internals,  and  two  encryp¬ 
tions  systems.  982pp. 
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ory,  an  SCSI  port,  and  a  hard  disk  to  the  Macintosh;  challenged 
the  UNIX  establishment  with  plans  for  a  free  UNIX.  Includes 
software  tools  in  C,  Modula-2,  Forth,  Pascal,  assembly  language, 
and  Prolog.  942pp. 


The  promise  of  power.  Desktop  computers  began  to  rival  minis 
and  mainframes  in  power.  DDJ  cevered  1 986’s  changes  with 
issues  on  the  68000,  parallel  processing,  artificial  intelligence, 
the  80386,  and  multitasking.  DDJ  also  supported  the  new  chips 
with  assemblers,  translators,  and  other  development  tools.  868pp. 
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Building  better  brains.  DDJ  broke  new  ground  in  1987  with  a 
neural  network  implementation,  monthly  coverage  of  artificial 
intelligence  and  object-oriented  programming  techniques,  and 
reviews  of  implementation  of  Prolog,  LISP,  and  Smalltalk. 
1015pp. 
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The  new  frontier.  Database  technology.  Hyperanimation,  and 
much  more!  DDJ  talks  about  how  to  create  a  new  language, 
writing  real  time  programs  under  UNIX,  and  developing  good 
software.  Other  topics  on  object-oriented  programming,  SQL 
development  tools,  and  much  more  to  C  are  all  included.  864pp. 
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Wrapping  up  the  1 980s,  DDJ  continues  its  tradition  of  providing  programmers  with  the  technical  information  they  want  and  need.  At  the 
forefront  of  1989  were  object-oriented  programming',  windowing  systems,  and  32-bit  programming.  DDJ  brought  its  readers  in-depth 
coverage  of  these  subjects,  and  also  kept  them  current  on  traditional  topics  such  as  advanced  programming  languages,  operating  systems, 
graphics  programming,  and  more.  In  1989  DDJ  also  published  two  special  issues — Dr.  Dobb's  Macintosh  Journal  and  Dr.  Dobb’s  C 
Sourcebook.  The  Macintosh  Journal  explored  Macintosh  programming  problems  and  languages,  while  the  C  Sourcebook  contained  useful 
C  utilities,  programming  techniques  for  C++  and  Concurrent  C,  and  thought-provoking  interviews  with  Dennis  Ritchie  and  Bjarne 
Stroustrup,  developers  of  C  and  C++.  Both  special  issues  are  included  in  this  volume.  Other  1989  topics  include: 

Neurel  Nets.  As  with  most  types  of  software  tools,  you  can  buy  a  ready-to-go  neural  network  development  system,  or  roll  your  own. 
In  January,  DDJ  takes  a  look  at  both  approaches. 

Real-time  Programming.  DDJ  proposes  the  Rhealstone  real-time  benchmark  standard,  a  long-needed  method  of  comparing  one 
real-time  system  implementation  to  another. 

Windowing  Systems.  DDJ  questions  whether  the  “pane”  of  window  development  is  worth  the  gain,  focusing  on  Presentation 

Manager,  MS  Windows,  X/Gem,  the  X  Window  system,  and  OSF  Motif. 

* 

Memory  Management.  As  applications  get  bigger  and  resources  tighter,  memory  management  becomes  more  and  more 
important.  DDJ  presents  two  different  “swap”  techniques  for  swapping  programs  from  memory  to  expanded  memory  or  to  disk,  and  back. 

Structured  Languages.  DDJ  puts  structured  languages  to  work  with  the  first  of  a  two-part  article  that  uses  Turbo  Pascal  to  create 
TSR  tools,  Modula-2  to  implement  the  Kermit  communications  protocol,  and  BASIC  to  examine  dynamic  pseudostructures. 

Operating  Systems.  Our  operating  systems  issue  includes  interprocess  communications  in  OS/2,  undocumented  DOS  features, 
data  acquisition  using  real-time  operating  systems,  and  Unix  system  security. 

Graphics  Programming.  There’s  more  than  meets  the  eye  to  graphics  programming.  We  discuss  line-of-best-fit,  give  you  the 
tools  for  your  own  icon  editor,  discuss  the  benefits  that  a  graphics  coprocessor  brings  to  a  multitasking  operating  system,  and  investigate 
image  mathematics. 

Mixod-Languago  C  Programming.  DDJ’ s  annual  C  issue  takes  a  look  at  mixed-language  programming,  focusing  on  C  and 
Smalltalk,  C  and  Fortran,  and  C  and  Postscript. 

Simulation  and  Modoling.  DDJ  looks  at  the  A*  algorithm  as  it  applies  to  autorouting  and  printed  circuit  board  layout,  simulated 
annealing,  and  forced-based  simulation  (in  C++). 

Data  Communications.  Efficient  and  reliable  data  communications  is  mandatory,  so  DDJ  discusses  how  to  link  PCs  to  minis,  how 
to  use  NetBIOS  for  high-speed  file  transfers,  and  what  LZW  data  compression  is  all  about. 

Parallel  Processing.  DDJ  examines  data-flow  multitasking  with  multiple  processors  and  creates  a  parallel  make  using  an  off-the- 
shelf  API. 

Object-Oriented  Programming  in  Action.  DDJ  looks  at  Object  Pascal,  Actor,  C++,  Eiffel,  QuickPascal,  and  Smalltalk, 
before  stopping  to  ask  “Are  The  Emperor’s  New  Clothes  Object-Oriented?” 

You’ll  also  find  well-known  contributors,  including  Michael  Swaine,  Mike  Floyd,  A1  Stevens,  Jeff  Duntemann,  Andrew  Shulman,  and 
Michael  Abrash;  the  Dr.  Dobb's  Journal  1988  index;  and  all  of  the  source  code  for  1989  (also  supplied  on  disk,  PC/MS-DOS  format). 
Neatly  packaged  and  completely  indexed,  this  volume  makes  an  impressive  addition  to  your  library. 
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